js/context

constructor(name: string)

Create a context slot with a stable debug name.

The name is informational and does not affect lookup identity. Two contexts with the same name remain separate slots. The constructor does not install a value; get() returns undefined until a scope is entered.

import { Context } from 'fino:context';

const tenant = new Context<string>('tenant');
console.log(tenant.name);

get name()

Read the debug name supplied to the constructor.

The value is read-only and never falls back to a generated name. It is safe to use in logs, but it is not a unique key because callers may create multiple contexts with the same name.

import { Context } from 'fino:context';

const ctx = new Context('request');
console.log(ctx.name);

get(): T | undefined

Return the current value of this context slot, or undefined if no value has been set (or if runClear is active) in the current async scope.

The lookup is synchronous and allocation-free in the common case. A stored value of undefined is indistinguishable from an unset slot, so use a sentinel object if that distinction matters.

import { Context } from 'fino:context';

const locale = new Context<string>('locale');
console.log(locale.get());
locale.runWithValue('en-US', () => console.log(locale.get()));

runWithValue<R>(value: T, fn: () => R): R

Run fn with this context slot set to value. The previous value is restored when fn returns or throws, preserving proper scope nesting.

Works for both sync and async functions. When fn is async, all continuations within the returned promise will see value.

If fn throws, the previous frame is restored before the error propagates. The returned value has exactly the same shape as fn's return value; async callbacks therefore return their original Promise.

import { Context } from 'fino:context';

const trace = new Context<string>('trace');
const result = await trace.runWithValue('abc', async () => {
  await Promise.resolve();
  return trace.get();
});

withValue(value: T): ContextScope

Enter a disposable scope with this context slot set to value.

Use this with a using declaration when the scope is naturally represented by a block instead of a callback. Disposing the returned scope restores the complete context frame that was active before withValue() was called. Promise continuations scheduled while the scope is active inherit value.

import { Context } from 'fino:context';

const trace = new Context<string>('trace');
{
  using scope = trace.withValue('abc');
  await Promise.resolve();
  console.log(trace.get());
}

runClear<R>(fn: () => R): R

Run fn with this context slot explicitly cleared, making get() return undefined for the duration of fn even if an outer scope has a value. The previous value is restored afterwards.

Use this when calling code that must not inherit sensitive request state. As with runWithValue(), thrown errors propagate after restoration and async continuations created inside fn observe the cleared slot.

import { Context } from 'fino:context';

const auth = new Context<string>('auth');
auth.runWithValue('token', () => {
  auth.runClear(() => console.log(auth.get()));
});

withClear(): ContextScope

Enter a disposable scope with this context slot cleared.

Use this when a block must not inherit an outer value. Disposing the scope restores the complete context frame that was active before withClear() was called.

import { Context } from 'fino:context';

const auth = new Context<string>('auth');
auth.runWithValue('token', () => {
  using scope = auth.withClear();
  console.log(auth.get());
});

enterWith(value: T): void

Unconditionally set this slot to value in the current async execution scope without scheduling a restore. All future microtasks enqueued from this point - and their continuations - will inherit the value.

Use sparingly. Unlike runWithValue, there is no automatic cleanup: the caller is responsible for calling exit() when appropriate.

Analogous to Node.js AsyncLocalStorage.enterWith().

Prefer runWithValue() for bounded scopes. enterWith() is useful for event-loop integration points that need to set state before scheduling callbacks and then clear it explicitly.

import { Context } from 'fino:context';

const request = new Context<string>('request');
request.enterWith('req-42');
queueMicrotask(() => console.log(request.get()));
request.exit();

exit(): void

Clear this slot in the current async execution scope. Code running synchronously after this call will see undefined. Previously-enqueued microtasks keep their captured value unchanged.

exit() only clears this context's slot, not other Context instances. It does not throw when the slot is already empty.

import { Context } from 'fino:context';

const ctx = new Context('request');
ctx.enterWith('req-1');
ctx.exit();
console.log(ctx.get());

snapshot()

Capture the current frame as a Snapshot that can be re-entered later - useful when manually scheduling callbacks outside the normal async flow (e.g. passing callbacks to third-party queues or custom event emitters).

The snapshot captures all context slots, not just this instance. Re-enter it with Snapshot.runWithValue() around callbacks whose scheduler does not preserve promise continuation state.

import { Context } from 'fino:context';

const ctx = new Context<string>('request');
const saved = ctx.runWithValue('req-1', () => ctx.snapshot());
saved.runWithValue(() => console.log(ctx.get()));

constructor(handle: unknown)

Create a snapshot wrapper around an opaque runtime context frame.

Application code normally obtains snapshots through Context.snapshot() or snapshotAll(). The handle is intentionally opaque; passing an invalid value can restore an unusable frame.

import { snapshotAll } from 'fino:context';

const snap = snapshotAll();
snap.runWithValue(() => console.log('restored'));

runWithValue<R>(fn: () => R): R

Run fn inside the snapshotted frame. The previous frame is restored afterwards regardless of whether fn throws.

The return value is the exact return value from fn. If fn schedules promise continuations, those continuations inherit the snapshotted frame.

import { Context, snapshotAll } from 'fino:context';

const ctx = new Context<string>('trace');
const snap = ctx.runWithValue('abc', () => snapshotAll());
await snap.runWithValue(async () => ctx.get());