🍦 unctx
Composition-API in Vanilla js
What is unctx?
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:
yarn add unctx
npm install unctx
import { createContext } from "unctx";
const ctx = createContext();
export const useAwesome = ctx.use;
ctx.call({ test: 1 }, () => {
});
User code:
import { useAwesome } from "awesome-lib";
function setup() {
const ctx = useAwesome();
}
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.
import { useContext, getContext } from "unctx";
const useAwesome = useContext("awesome-lib");
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.
async function setup() {
console.log(useAwesome());
setTimeout(() => {
console.log(useAwesome());
}, 1);
await new Promise((resolve) => setTimeout(resolve, 1000));
console.log(useAwesome());
}
A simple workaround is caching context into a local variable:
async function setup() {
const ctx = useAwesome();
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, you need to set asyncContext: true
option and also provides an implementation for AsyncLocalStorage
(or provide globalThis.AsyncLocalStorage
polyfill).
See tc39 proposal for async context and cloudflare docs for relevant platform specific docs.
import { createContext } from "unctx";
import { AsyncLocalStorage } from "node:async_hooks";
const ctx = createContext({
asyncContext: true,
AsyncLocalStorage,
});
ctx.call("123", () => {
setTimeout(() => {
console.log(ctx.use());
}, 100);
});
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.
Import and register transform plugin:
import { unctxPlugin } from "unctx/plugin";
unctxPlugin.rollup();
unctxPlugin.vite();
unctxPlugin.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());
await new Promise((resolve) => setTimeout(resolve, 1000));
console.log(useAwesome());
});
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.
import { createContext } from "unctx";
const ctx = createContext();
ctx.set(new Awesome());
export const useAwesome = ctx.use;
Typed Context
A generic type exists on all utilities to be set for instance/context type for typescript support.
const { 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
)
Pitfalls
context can be only used before first await:
Please check Async Context section.
Context conflict
error:
In your library, you should only keep one call()
running at a time (unless calling with the same reference for the first argument)
For instance, this makes an error:
ctx.call({ test: 1 }, () => {
ctx.call({ test: 2 }, () => {
});
});
License
MIT. Made with 💖