unctx

By default, unctx context is only available in synchronous execution and only before the first await statement. This ensures that context is not accidentally shared between concurrent asynchronous calls.

If you attempt to use the context after an await or inside a setTimeout, it will return null (or throw if using use).

Workaround: Cache the context in a local variable at the start of your function:

async function setup() {
  const ctx = useAwesome(); // Cache the context immediately
  await new Promise((resolve) => setTimeout(resolve, 1000));
  console.log(ctx); // Still works because it's a local variable
}

async function setup() {
  console.log(useAwesome()); // Returns context
  setTimeout(() => {
    console.log(useAwesome());
  }, 1); // Returns null
  await new Promise((resolve) => setTimeout(resolve, 1000));
  console.log(useAwesome()); // Returns null
}

You can implement a pattern similar to Vue's Composition API by creating a context. This allows functions to access a shared instance without explicitly passing it through every function call.

1. Create a context using createContext().
2. Export a use function (e.g., ctx.use) for consumers to access the context.
3. Use ctx.call(instance, callback) to wrap the logic where the context should be available. Any function called within the callback can then use the exported use function to retrieve the instance.

Note: ctx.use throws an error if no context is present. Use ctx.tryUse if you want a tolerant version that returns null instead of throwing.

import { createContext } from "unctx";

const ctx = createContext();

export const useAwesome = ctx.use;

// ...
ctx.call({ test: 1 }, () => {
  // Any function called here can use `useAwesome` to get { test: 1 }
});

If you are building your own tool or not using a standard bundler, you can use the standalone transformer from unctx/transform. It requires magic-string and an oxc parser (oxc-parser or rolldown).

Transformer Options

Usage Example

import { createTransformer } from "unctx/transform";

const transformer = await createTransformer({
  // asyncFunctions: ["withAsyncContext"],
});

const result = transformer.transform(code);

if (result) {
  console.log(result.code); // Transformed code
  console.log(result.magicString.generateMap()); // Source map
}

import { createTransformer } from "unctx/transform";

const transformer = await createTransformer({
  // asyncFunctions: ["withAsyncContext"],
  // helperModule: "unctx",
  // helperName: "executeAsync",
  // objectDefinitions: {},
});

const result = transformer.transform(code);

if (result) {
  console.log(result.code); // Transformed code
  console.log(result.magicString.generateMap()); // Source map
}

If your environment doesn't support native async context (like most browsers), unctx provides a build-time transform that automatically restores context after await statements. This requires a bundler (Rollup, Vite, or Webpack) and specific peer dependencies.

1. Install Peer Dependencies

npx nypm i -D unplugin magic-string oxc-parser
# or if using rolldown:
# npx nypm i -D unplugin magic-string rolldown

2. Register the Plugin

Import unctxPlugin from unctx/plugin and register it in your bundler configuration (e.g., unctxPlugin.vite() for Vite).

3. Usage

Wrap async functions that require context with withAsyncContext from unctx:

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 thanks to the transform!
});

Note: If you use ctx.callAsync, you must add `

A Transformer object returned by createTransformer provides methods to inspect and transform code strings during the build process.

Methods

• transform(code: string, options?: { force?: boolean }): { code: string; magicString: MagicString } | undefined Transforms the provided code. If the code does not match the filter or does not contain transformable patterns, it returns undefined. If options.force is true, it bypasses the shouldTransform check.
• shouldTransform(code: string): boolean A predicate that returns true if the code contains both a target function call (from asyncFunctions or objectDefinitions) and an await expression.
• filter.code: RegExp The regex used for fast pre-filtering.

const transformer = await createTransformer();
const code = 'withAsyncContext(() => { await doSomething(); });';

const result = transformer.transform(code);
if (result) {
  console.log(result.code);
  // result.magicString is a MagicString instance for source map generation
}