Keep Your Functions Clean & Focused: Context Provision with Node.js AsyncLocalStorage

You have probably heard of the SOLID principles in programming. By applying them to your codebase, you can create a solid (🤡) architecture that is both easy to maintain and extend.

SOLID stands for:

• Single Responsibility
• Open/Closed
• Liskov Substitution
• Interface Segregation
• Dependency Inversion

In this post, I will demonstrate how to leverage Node.js’s built-in AsyncLocalStorage to implement the Open/Closed principle.

What is the Open/Closed Principle?

The open/closed principle states that software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.

But what does that mean?

In this post, I will focus on two examples to showcase how you can apply the open/closed principle using Node.js’s AsyncLocalStorage:

1. Database transactions
2. Logging

First, I’ll show you a violation of the open/closed principle, and then I will demonstrate how to adhere to it using Node.js’s built-in AsyncLocalStorage.

Violation of the Open/Closed Principle

Example 1: Database Transactions

Imagine you have a repository function that creates a user profile in the database.

1
import { db } from './db';
2

3
async function main() {
4
  await createUserProfile({ id: '1', name: 'John Doe' });
5
}
6

7
async function createUserProfile(profile) {
8
  await db.insert(userProfileTable).values(profile);
9
};

Alright, now suppose you want to create the user profile together with a user entity stored in a different table. You should do that in a single transaction because neither should exist without the other. This is what you might do:

1
import { db } from './db';
2

3
async function main() {
4
  await db.transaction(async (transaction) => {
5
    await Promise.all([
6
      createUserProfile({ id: '1', name: 'John Doe' }, transaction),
7
      createUser({ id: '1', name: 'John Doe' }, transaction),
8
    ]);
9
  });
10
}
11

12
// ❌ we have added the transaction argument to the function (= extended the function)
13
// ❌ this violates the open/closed principle
14
async function createUserProfile(profile, transaction) {
15
  await (transaction ?? db).insert(userProfileTable).values(profile);
16
};
17

18
async function createUser(user, transaction) {
19
  await (transaction ?? db).insert(userTable).values(user);
20
}

That works, but it is a violation of the open/closed principle ❌ You are modifying the createUserProfile function to accommodate the new requirement. Every time you decide to run a repository function within a transaction, you must modify the function to pass the transaction argument.

Example 2: Logging

Imagine you have a logger with an appendKeys method that appends keys to every subsequent log statement (just like the logger from Powertools for AWS Lambda). This is very useful to find all logs that are related.

Consider a scenario where you have a function that processes an order. You want to easily find all logs related to a specific order. To achieve that, you use logger.appendKeys to append the orderId to every log statement:

1
import { logger } from './logger';
2

3
async function main() {
4
  await processOrder(order);
5
}
6

7
async function processOrder(order) {
8
  logger.appendKeys({ orderId: order.id });
9
  // ...
10
  const total = calculateOrderTotal(order.lineItems);
11
  // ...
12
}
13

14
function calculateOrderTotal(lineItems) {
15
  // calculation...
16

17
  // this will also log the orderId since we have appended it to the logger instance
18
  logger.debug('calculated order total', { total: 100 });
19
}

Now, suppose you want to process multiple orders concurrently. You cannot simply call appendKeys on the global logger instance because the orderId key would be overwritten, as all processOrder executions share the same logger instance.

One way to deal with this, would be to create a separate logger instance for every processOrder call:

1
import { logger } from './logger';
2

3
async function main() {
4
  await Promise.all(orders.map(order => {
5
    const childLogger = logger.createChild();
6
    return processOrder(order, childLogger);
7
  }));
8
}
9

10
// ❌ we had to add the logger argument to the function
11
// ❌ this violates the open/closed principle
12
async function processOrder(order, logger) {
13
  logger.appendKeys({ orderId: order.id });
14
  // ...
15
}

Another solution is to not use logger.appendKeys altogether and instead pass the orderId to every log statement:

1
import { logger } from './logger';
2

3
async function main() {
4
  await Promise.all(orders.map(order => processOrder(order, childLogger)));
5
}
6

7
async function processOrder(order) {
8
  // ...
9
  const total = calculateOrderTotal(order);
10
  // ...
11
}
12

13
// ❌ we now pass the whole order because we need access to the orderId for logging
14
// ❌ this violates the open/closed principle
15
function calculateOrderTotal(order) {
16
  // calculation...
17

18
  // this will also log the orderId since we have appended it to the logger instance
19
  logger.debug('calculated order total', { total: 100, orderId: order.id });
20
}

This approach is not only tedious but also error-prone, since you must consistently use the same orderId key in every log statement to correlate logs associated with a specific order.

You can imagine that both of these approaches quickly become unmanageable—especially when processOrder calls many other functions in a deeply nested manner.

Applying the Open/Closed Principle with AsyncLocalStorage

Now that we know what a violation of the open/closed principle looks like, let’s explore how to apply the open/closed principle using Node.js’s built-in AsyncLocalStorage.

Context Sharing with AsyncLocalStorage

We want the createUserProfile and processOrder functions to work in different scenarios without needing to modify them. For instance, createUserProfile shouldn’t have to know whether it is running in a transaction or not, and processOrder should not change just because it is executed concurrently.

So how do we solve this?

We can leverage AsyncLocalStorage to create a context that is available to all functions executed within the same scope. This allows us to modify the behavior of functions without actually changing their implementations.

1
import { AsyncLocalStorage } from 'node:async_hooks';
2

3
export function createContext<T>() {
4
  const context = new AsyncLocalStorage<T>();
5
  return {
6
    use() {
7
      const result = context.getStore();
8
      if (!result) {
9
        throw new Error('No context available');
10
      }
11
      return result;
12
    },
13
    provide<R>(value: T, callback: () => R) {
14
      return context.run<R>(value, callback);
15
    },
16
  };
17
}

createContext creates a private storage context that is only accessible within the createContext function. It returns an object with a use method that returns the current context and a provide method that allows you to provide a context (value) that is available with the callback function.

Example usage:

1
const userContext = createContext<{ userId: string }>();
2

3
userContext.provide({ userId: '123' }, async () => {
4
  // this can be somewhere deeply nested in your codebase
5
  const { userId } = userContext.use();
6
});

How can we leverage the createContext function to solve our examples?

Example 1 Revisited: Database Transactions

Lets use the createContext function to create a context for the database transaction.

1
type TransactionOrDb = Transaction | typeof db;
2

3
const TransactionContext = createContext<{
4
  transaction: TransactionOrDb;
5
}>();
6

7
async function provideTransaction<T>(
8
  callback: (transaction: Transaction) => Promise<T>,
9
  transactionOptions?: TransactionOptions,
10
): Promise<T> {
11
  try {
12
    // if there already is a transaction context, we use that
13
    const { transaction } = TransactionContext.use();
14
    return callback(transaction);
15
  } catch {
16
    // otherwise we start a new transaction that we provide to the callback
17
    const result = await db.transaction(
18
      async (transaction) => {
19
        return TransactionContext.provide({ transaction }, () => callback(transaction));
20
      },
21
      transactionOptions,
22
    );
23
    return result as T;
24
  }
25
}
26

27
async function useTransactionOrDb<T>(callback: (transactionOrDb: TransactionOrDb) => Promise<T>) {
28
  try {
29
    // this throws outside of the context (see `createContext().use()`)
30
    const { transaction } = TransactionContext.use();
31
    return callback(transaction);
32
  } catch {
33
    // if not within a context, we use the db instance
34
    return callback(db);
35
  }
36
}

We have two functions that essentially wrap the use and provide methods of the createContext function:

• provideTransaction is used to provide a transaction to the callback function. It either uses an already existing transaction or starts a new one.
• useTransactionOrDb returns the transaction if it is within a transaction context or the db instance otherwise.

Now, instead of using the db instance directly in our app, we can just always use useTransactionOrDb.

Back to our example, we have the following code before deciding to use a transaction:

1
import { db } from './db';
2

3
async function main() {
4
  await createUserProfile({ id: '1', name: 'John Doe' });
5
}
6

7
async function createUserProfile(profile) {
8
  await useTransactionOrDb().insert(userProfileTable).values(profile);
9
};

Here, createUserProfile will just use the db instance directly since it is not within a transaction context.

Now, decide that we have to run createUserProfile in a transaction together with createUser. We can do that by providing a transaction to the createUserProfile function:

1
import { db } from './db';
2

3
async function main() {
4
  await provideTransaction(async () => {
5
    await Promise.all([
6
      createUserProfile({ id: '1', name: 'John Doe' }),
7
      createUser({ id: '1', name: 'John Doe' }),
8
    ]);
9
  });
10
}
11

12
// ✅ the arguments are unchanged – no modification needed
13
async function createUserProfile(profile) {
14
  await useTransactionOrDb().insert(userProfileTable).values(profile);
15
};
16

17
async function createUser(user) {
18
  await useTransactionOrDb().insert(userTable).values(user);
19
}

Now we are following the open/closed principle! We did not have to modify the createUserProfile function to accommodate the new requirement. Only the caller of the function has to know about the context.

Example 2 Revisited: Logging

Now, let’s see how we can apply the open/closed principle to the logging example.

Again, we are creating some helper functions that wrap the use and provide methods of the createContext function:

1
const LoggerContext = createContext<{
2
  logger: Logger;
3
}>();
4

5
export function createLoggerContext<T>(callback: (logger: Logger) => T): T {
6
  try {
7
    // if there is already a LoggerContext, use it
8
    const { logger } = LoggerContext.use();
9
    return callback(logger);
10
  } catch {
11
    // if there is no LoggerContext, create a new one with a new child logger
12
    let childLogger = logger.createChild();
13
    const result = LoggerContext.provide({ logger: childLogger }, () =>
14
      callback(childLogger),
15
    );
16
    return result as T;
17
  }
18
}
19

20
export function getLogger() {
21
  try {
22
    const { logger } = LoggerContext.use();
23
    return logger;
24
  } catch {
25
    return logger;
26
  }
27
}

This is essentially the same as in the previous example:

• createLoggerContext is used to create a child logger and provide it to the callback function.
• getLogger is used to return the logger. If there is no logger in the context, it will return the global logger.

Now we can use that to follow the open/closed principle in our second example. Instead of using the logger instance directly, just always use getLogger. This is how our initial code looks like:

1
import { getLogger } from './logger';
2

3
async function main() {
4
  await processOrder(order);
5
}
6

7
async function processOrder(order) {
8
  getLogger().appendKeys({ orderId: order.id });
9
  // ...
10
  const total = calculateOrderTotal(order.lineItems);
11
  // ...
12
}
13

14
function calculateOrderTotal(lineItems) {
15
  // calculation...
16

17
  // this will also log the orderId since we have appended it to the logger instance
18
  getLogger().debug('calculated order total', { total: 100 });
19
}

Okay, now we change it to run processOrder in parallel:

1
import { logger } from './logger';
2

3
async function main() {
4
  await Promise.all(orders.map(order => {
5
    return createLoggerContext(() => {
6
      return processOrder(order);
7
    });
8
  }));
9
}
10

11
// ✅ the arguments are unchanged – no modification needed
12
async function processOrder(order) {
13
  getLogger().appendKeys({ orderId: order.id });
14
  // ...
15
  const total = calculateOrderTotal(order.lineItems);
16
  // ...
17
}
18

19
function calculateOrderTotal(lineItems) {
20
  // calculation...
21

22
  // this will also log the orderId since we have appended it to the logger instance
23
  getLogger().debug('calculated order total', { total: 100 });
24
}

We now create a child logger for every processOrder call. processOrder can just call getLogger().appendKeys to append the orderId to the logger as it did before. Now the keys don’t overwrite each other because getLogger() returns different a child logger instances.

By using getLogger() everywhere in throughout your codebase instead of the global logger instance, we don’t have to modify any functions if they are run differently. We are following the open/closed principle!

Conclusion

In this post, we have seen how to apply the open/closed principle using Node.js’s built-in AsyncLocalStorage. We created a createContext function that allows us to establish a context for any type, which we then leveraged to solve our two examples.

Here are some key takeaways:

• Decoupled Context Management: By using AsyncLocalStorage, you can inject contextual data (like transaction handles or logging metadata) without modifying the core business logic.
• Adherence to the Open/Closed Principle: Functions remain closed for modification while still being open for extension, minimizing the need to alter function signatures as new requirements arise.
• Elimination of Manual Parameter Drag: AsyncLocalStorage prevents the tedious and error-prone process of manually threading context through multiple function calls.
• Improved Maintainability: By isolating context handling from your repository and logging logic, your codebase stays cleaner, more modular, and easier to maintain.
• Enhanced Debugging and Consistency: Automatically propagated context ensures that logs and database transactions are consistent, making debugging and analytics more straightforward.
• Versatile Application: This approach benefits various scenarios, including managing database transactions and setting up consistent logging across parallel asynchronous processes. These takeaways emphasize how leveraging Node.js AsyncLocalStorage can lead to more robust, maintainable, and scalable code while adhering to fundamental design principles.

Further Reading

• Node.js AsyncLocalStorage API
• AsyncLocalStorage Usage in the terminaldotshop codebase
• Open/Closed Principle
• SOLID Principles