Vue.js introduced an amazing pattern called Composition API that allows organizing complex logic by splitting it into reusable functions and grouping in logical order. unctx allows easily implementing composition API pattern in your javascript libraries without hassle.
Usage
In your awesome library:
npx nypm i unctx
import { createContext } from "unctx";const ctx = createContext();export const useAwesome = ctx.use;// ...ctx.call({ test: 1 }, () => { // This is similar to the vue setup function // Any function called here can use `useAwesome` to get { test: 1 }});
Note: When no context is presented ctx.use will throw an error. Use ctx.tryUse for tolerant usages (return nullable context).
Using Namespaces
To avoid issues with multiple version of the library, unctx provides a safe global namespace to access context by key (kept in globalThis). Important: Please use a verbose name for the key to avoid conflict with other js libraries. Using the npm package name is recommended. Using symbols has no effect since it still causes multiple context issues.
You can also create your internal namespace with createNamespace utility for more advanced use cases.
Async Context
Using context is only possible in non-async usages and only before the first await statement. This is to make sure context is not shared between concurrent calls.
A simple workaround is caching context into a local variable:
async function setup() { const ctx = useAwesome(); // We can directly access cached version of ctx await new Promise((resolve) => setTimeout(resolve, 1000)); console.log(ctx);}
This is not always an elegant and easy way by making a variable and passing it around. After all, this is the purpose of unctx to make sure context is magically available everywhere in composables!
Native Async Context
Unctx supports Node.js AsyncLocalStorage as a native way to preserve and track async contexts. To enable this mode, set the asyncContext: true option.
The AsyncLocalStorage implementation is auto-detected from globalThis.AsyncLocalStorage or the node:async_hooks built-in module. If neither is available (or you want to use a custom implementation), you can explicitly pass one with the AsyncLocalStorage option:
import { createContext } from "unctx";import { AsyncLocalStorage } from "node:async_hooks";const ctx = createContext({ asyncContext: true, AsyncLocalStorage,});
Async Transform
Since native async context is not supported in all platforms yet, unctx provides a build-time solution that transforms async syntax to automatically restore context after each async/await statement. This requires using a bundler such as Rollup, Vite, or Webpack.
First, install the plugin peer dependencies. You always need unplugin and
magic-string, plus an oxc parser — either oxc-parser directly, or rolldown
(which re-exports the oxc utilities), which is convenient if you already depend
on it:
npx nypm i -D unplugin magic-string oxc-parser# or, if you already use rolldown:npx nypm i -D unplugin magic-string rolldown
These are all optional peer dependencies, so they only get installed if you use
the async transform.
Import and register transform plugin:
import { unctxPlugin } from "unctx/plugin";// Rollup// TODO: Add to rollup configurationunctxPlugin.rollup();// Vite// TODO: Add to vite configurationunctxPlugin.vite();// Webpack// TODO: Add to webpack configurationunctxPlugin.webpack();
Use ctx.callAsync instead of ctx.call:
await ctx.callAsync("test", setup);
NOTE:callAsync is not transformed by default. You need to add it to the plugin's asyncFunctions: [] option to transform it.
Any async function that requires context, should be wrapped with withAsyncContext:
import { withAsyncContext } from "unctx";const setup = withAsyncContext(async () => { console.log(useAwesome()); // Returns context await new Promise((resolve) => setTimeout(resolve, 1000)); console.log(useAwesome()); // Still returns context with dark magic!});
Transform API
If you are not using a bundler (or are building your own integration), the transform used by the plugin is also available standalone from unctx/transform. It only needs magic-string and an oxc parser (oxc-parser or rolldown) — unplugin is not required.
createTransformer is async because the parser is imported lazily. It resolves to an object with:
transform(code, { force? }): Returns { code, magicString }, or undefined when nothing was transformed. Pass { force: true } to skip the shouldTransform pre-check and always parse.
shouldTransform(code): Cheap check whether code contains a transformable call and an await.
filter: { code: RegExp } used to skip files that cannot contain a transformable call.
The same regexp can be computed without loading the parser via getTransformFilter(options), which is useful for pre-filtering files:
Function names whose function arguments should be transformed. Add "callAsync" to transform ctx.callAsync usages.
helperModule
"unctx"
Module the async helper is imported from.
helperName
"executeAsync"
Name of the async helper exported by helperModule.
objectDefinitions
{}
Object properties to transform, keyed by the defining function. For example { defineMeta: ["middleware"] } transforms the middleware key passed to defineMeta.
Singleton Pattern
If you are sure it is safe to use a shared instance (not depending to request), you can also use ctx.set and ctx.unset for a singleton pattern.
Note: You cannot combine set with call. Always use unset before replacing the instance otherwise you will get Context conflict error.
A generic type exists on all utilities to be set for instance/context type for typescript support.
// Return type of useAwesome is Awesome | nullconst { use: useAwesome } = createContext<Awesome>();
Under the hood
The composition of functions is possible using temporary context injection. When calling ctx.call(instance, cb), instance argument will be stored in a temporary variable then cb is called. Any function inside cb, can then implicitly access the instance by using ctx.use (or useAwesome)