@maestro-js/context 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,360 @@
+# @maestro-js/context
+
+## Overview
+
+The `@maestro-js/context` package provides request-scoped key-value storage backed by Node.js `AsyncLocalStorage`. Each call to `run()` creates an isolated store with two buckets -- visible (safe for logging) and hidden (for sensitive data like tokens) -- ensuring data never leaks between concurrent requests.
+
+## Quick Setup
+
+```ts
+import { Context } from '@maestro-js/context'
+
+// Create and register a context provider
+const ctx = Context.Provider.create()
+Context.Provider.register('default', ctx)
+
+// Use the default facade directly
+Context.run(() => {
+  Context.add('userId', 123)
+  Context.get<number>('userId')  // 123
+  Context.all()                  // { userId: 123 }
+})
+```
+
+## API Reference
+
+### Lifecycle Methods
+
+#### `run<T>(callback: () => T): T`
+
+Initialize a fresh context store for the duration of `callback`. All `add`/`get`/`push` calls inside the callback (including across `await` boundaries) share the same isolated store. Returns the callback's return value.
+
+```ts
+const result = Context.run(() => {
+  Context.add('requestId', 'abc-123')
+  return Context.get('requestId')
+})
+// result === 'abc-123'
+```
+
+#### `runWith<T>(store: Context.Store | undefined, callback: () => T): T`
+
+Run `callback` within a previously captured store so context is available inside. If `store` is `undefined`, run the callback without any context (all reads return `undefined`).
+
+```ts
+Context.run(() => {
+  Context.add('userId', 42)
+  const store = Context.getStore()
+
+  // Later, in a different async boundary:
+  Context.runWith(store, () => {
+    Context.get('userId')  // 42
+  })
+})
+```
+
+#### `getStore(): Context.Store | undefined`
+
+Return a reference to the current `AsyncLocalStorage` store, or `undefined` if called outside a `run()`. The returned store is a live reference -- mutations via `runWith` affect the original.
+
+### Visible Context Methods
+
+#### `add(key: Context.Key, value: any): void`
+
+Store a key-value pair in the visible context, overriding any existing value.
+
+```ts
+Context.run(() => {
+  Context.add('tenantId', 'acme-corp')
+  Context.add('tenantId', 'other-corp')  // overrides
+  Context.get('tenantId')                // 'other-corp'
+})
+```
+
+#### `get<Value = unknown>(key: Context.Key): Value | undefined`
+
+Retrieve the value for a key from the visible context, or `undefined` if absent.
+
+```ts
+Context.run(() => {
+  Context.add('role', 'admin')
+  Context.get<string>('role')    // 'admin'
+  Context.get('nonexistent')     // undefined
+})
+```
+
+#### `has(key: Context.Key): boolean`
+
+Return `true` if the key exists in the visible context.
+
+#### `del(...key: Context.Key[]): void`
+
+Remove one or more keys from the visible context.
+
+```ts
+Context.run(() => {
+  Context.add('a', 1)
+  Context.add('b', 2)
+  Context.del('a', 'b')
+  Context.has('a')  // false
+})
+```
+
+#### `push(key: Context.Key, ...value: any[]): void`
+
+Append value(s) to an array in the visible context. Create the array if the key does not exist. Wrap an existing non-array value into an array before appending.
+
+```ts
+Context.run(() => {
+  Context.push('tags', 'admin')
+  Context.get('tags')              // ['admin']
+
+  Context.push('tags', 'user', 'verified')
+  Context.get('tags')              // ['admin', 'user', 'verified']
+
+  Context.add('scalar', 'x')
+  Context.push('scalar', 'y')
+  Context.get('scalar')            // ['x', 'y']
+})
+```
+
+#### `all(): { [key: Context.Key]: unknown }`
+
+Return all visible context entries as a plain object. Hidden entries are excluded.
+
+```ts
+Context.run(() => {
+  Context.add('userId', 123)
+  Context.addHidden('authToken', 'secret')
+  Context.all()  // { userId: 123 }
+})
+```
+
+#### `createItem<Value = unknown>(key: Context.Key)`
+
+Return a typed handle scoped to a single key in the visible context. The handle exposes `add(value)`, `get()`, `del()`, and `push(...)` methods.
+
+```ts
+Context.run(() => {
+  const userId = Context.createItem<number>('userId')
+  userId.add(42)
+  userId.get()  // 42
+  userId.del()
+  userId.get()  // undefined
+})
+```
+
+### Hidden Context Methods
+
+Hidden methods mirror visible methods but operate on a separate bucket excluded from `all()`. Use hidden context for sensitive data (tokens, credentials) that should not appear in logs.
+
+- `addHidden(key, value)` -- Store in hidden context.
+- `getHidden<Value>(key)` -- Retrieve from hidden context.
+- `hasHidden(key)` -- Check existence in hidden context.
+- `delHidden(...key)` -- Remove from hidden context.
+- `pushHidden(key, ...value)` -- Append to array in hidden context.
+- `allHidden()` -- Return all hidden entries as a plain object.
+- `createHiddenItem<Value>(key)` -- Typed handle for hidden context.
+
+```ts
+Context.run(() => {
+  Context.addHidden('authToken', 'Bearer xyz')
+  Context.getHidden('authToken')  // 'Bearer xyz'
+  Context.all()                   // {} -- hidden values excluded
+  Context.allHidden()             // { authToken: 'Bearer xyz' }
+})
+```
+
+### Provider Methods
+
+#### `Context.Provider.create(): Context.ContextService`
+
+Factory that instantiates a new context service with its own `AsyncLocalStorage`.
+
+#### `Context.Provider.register(name: Context.Provider.Key, service: Context.ContextService): void`
+
+Register an instance in the named registry.
+
+#### `Context.provider(key: Context.Provider.Key): Context.ContextService`
+
+Resolve a named instance. Resolution is deferred via Proxy, so `provider()` can be called before `register()`.
+
+## Common Patterns
+
+### Request-Scoped Data in HTTP Middleware
+
+Wrap each incoming request in `Context.run()` to isolate per-request data:
+
+```ts
+function contextMiddleware(req, res, next) {
+  Context.run(() => {
+    Context.add('requestId', req.headers['x-request-id'])
+    Context.add('method', req.method)
+    Context.add('path', req.path)
+    Context.addHidden('authToken', req.headers.authorization)
+    next()
+  })
+}
+```
+
+### Propagating Context Across Async Boundaries
+
+When context must survive into a callback that runs outside the original `run()` scope (e.g., stream event handlers), capture and restore the store:
+
+```ts
+Context.run(() => {
+  Context.add('queryId', 'q-001')
+  const store = Context.getStore()
+
+  stream.on('end', () => {
+    Context.runWith(store, () => {
+      // Context is available here
+      Context.get('queryId')  // 'q-001'
+    })
+  })
+})
+```
+
+This pattern is used by `@maestro-js/db` for query stream logging and by `@maestro-js/tracing` for span instrumentation.
+
+### Nested Runs Create Fresh Stores
+
+Each `run()` creates a completely fresh store. Nested calls do not inherit from the outer scope:
+
+```ts
+Context.run(() => {
+  Context.add('outer', 1)
+  Context.run(() => {
+    Context.get('outer')  // undefined -- fresh store
+    Context.add('inner', 2)
+  })
+  Context.get('inner')    // undefined -- inner store is gone
+  Context.get('outer')    // 1
+})
+```
+
+### Silent No-Ops Outside run()
+
+All context operations silently do nothing when called outside a `run()` scope. No errors are thrown:
+
+```ts
+Context.add('key', 'value')    // no-op
+Context.get('key')             // undefined
+Context.has('key')             // false
+Context.all()                  // {}
+```
+
+### Store Mutations via runWith Are Shared
+
+`getStore()` returns a reference, not a copy. Mutations inside `runWith` affect the original store:
+
+```ts
+Context.run(() => {
+  Context.add('count', 1)
+  const store = Context.getStore()
+
+  Context.runWith(store, () => {
+    Context.add('count', 2)
+  })
+
+  Context.get('count')  // 2 -- mutated by runWith
+})
+```
+
+### Multiple Isolated Providers
+
+Separate `create()` calls produce fully independent context instances:
+
+```ts
+const appContext = Context.Provider.create()
+const requestContext = Context.Provider.create()
+
+appContext.run(() => {
+  appContext.add('env', 'production')
+  requestContext.run(() => {
+    requestContext.add('env', 'staging')
+    appContext.get('env')       // 'production'
+    requestContext.get('env')   // 'staging'
+  })
+})
+```
+
+## Testing
+
+Context requires no mock driver -- `Provider.create()` returns a fully functional instance using in-process `AsyncLocalStorage`. Wrap test logic in `run()`:
+
+```ts
+import { Context } from '@maestro-js/context'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+test('adds and retrieves context values', () => {
+  const ctx = Context.Provider.create()
+  ctx.run(() => {
+    ctx.add('userId', 123)
+    expect(ctx.get('userId')).toBe(123)
+    expect(ctx.has('userId')).toBe(true)
+    expect(ctx.all()).toEqual({ userId: 123 })
+  })
+})
+
+test('hidden values excluded from all()', () => {
+  const ctx = Context.Provider.create()
+  ctx.run(() => {
+    ctx.add('visible', 'yes')
+    ctx.addHidden('secret', 'token')
+    expect(ctx.all()).toEqual({ visible: 'yes' })
+    expect(ctx.getHidden('secret')).toBe('token')
+  })
+})
+
+test('async propagation across await', async () => {
+  const ctx = Context.Provider.create()
+  await ctx.run(async () => {
+    ctx.add('before', true)
+    await new Promise((r) => setTimeout(r, 10))
+    expect(ctx.get('before')).toBe(true)
+  })
+})
+```
+
+Run tests with:
+
+```bash
+pnpm --filter @maestro-js/context test
+# or
+cd packages/context && npx beartest ./tests/context.test.ts
+```
+
+## Cross-Package Integration
+
+### Db (query stream logging)
+
+The `@maestro-js/db` package captures the context store before creating query streams and restores it in `end` and `error` event handlers via `Context.runWith()`, ensuring log messages emitted during stream callbacks include the original request context.
+
+### Tracing (span instrumentation)
+
+The `@maestro-js/tracing` package captures the context store when starting or wrapping spans and restores it in `onEnd` callbacks via `Context.runWith()`, so span completion logs include the request context.
+
+### Log (contextual logging)
+
+Log transports can call `Context.all()` to attach visible context entries to every log line within a request scope, providing automatic request-scoped structured logging without manually passing data.
+
+### Dependencies
+
+- **Depends on**: `@maestro-js/service-registry` (Provider pattern foundation)
+- **Used by**: `@maestro-js/db`, `@maestro-js/tracing`
+- **Works with**: `@maestro-js/log` (contextual logging)
+
+## Types
+
+```ts
+// Key type for context entries
+type Context.Key = string | number | symbol
+
+// The raw context snapshot containing visible and hidden Map buckets
+type Context.Store = {
+  hidden: Map<Context.Key, unknown>
+  visible: Map<Context.Key, unknown>
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Creates a new Context service instance with its own AsyncLocalStorage.
+ */
+declare function create(): Context.ContextService;
+declare function provider(key: Context.Provider.Key): Context.ContextService;
+type KeysWithFallback = keyof Context.Provider.Keys extends never ? {
+    default: unknown;
+} : Context.Provider.Keys & {
+    default: unknown;
+};
+/**
+ * Request-scoped key-value storage backed by AsyncLocalStorage.
+ * Call `Context.Provider.create()` and register it, or use the default instance.
+ */
+declare const Context: {
+    provider: typeof provider;
+    /** Initializes a fresh context store for the duration of `callback`. */
+    run<T>(callback: () => T): T;
+    /** Stores a key-value pair in the visible context, overriding any existing value. */
+    add(key: Context.Key, value: any): void;
+    /** Removes one or more keys from the visible context. */
+    del(...key: Context.Key[]): void;
+    /** Appends value(s) to an array in the visible context. Creates the array if the key doesn't exist. */
+    push(key: Context.Key, ...value: any[]): void;
+    /** Returns `true` if the key exists in the visible context. */
+    has(key: Context.Key): boolean;
+    /** Retrieves the value for `key` from the visible context, or `undefined` if absent. */
+    get<Value = unknown>(key: Context.Key): Value | undefined;
+    /** Returns all visible context entries as a plain object. */
+    all(): {
+        [key: Context.Key]: unknown;
+    };
+    /** Returns convenience methods scoped to a single key in the visible context. */
+    createItem<Value = unknown>(key: Context.Key): {
+        add(value: Value): void;
+        del(): void;
+        push: Value extends Array<any> ? (...value: Value) => void : never;
+        get(): Value | undefined;
+    };
+    /** Stores a key-value pair in the hidden context (excluded from {@link all}). */
+    addHidden(key: Context.Key, value: any): void;
+    /** Removes one or more keys from the hidden context. */
+    delHidden(...key: Context.Key[]): void;
+    /** Appends value(s) to an array in the hidden context. */
+    pushHidden(key: Context.Key, ...value: any[]): void;
+    /** Returns `true` if the key exists in the hidden context. */
+    hasHidden(key: Context.Key): boolean;
+    /** Retrieves the value for `key` from the hidden context, or `undefined` if absent. */
+    getHidden<Value = unknown>(key: Context.Key): Value | undefined;
+    /** Returns all hidden context entries as a plain object. */
+    allHidden(): {
+        [key: Context.Key]: unknown;
+    };
+    /** Returns convenience methods scoped to a single key in the hidden context. */
+    createHiddenItem<Value = unknown>(key: Context.Key): {
+        add(value: Value): void;
+        del(): void;
+        push: Value extends Array<any> ? (...value: Value) => void : never;
+        get(): Value | undefined;
+    };
+    /** Runs `callback` within the given store so context is available inside. */
+    runWith<T>(store: Context.Store | undefined, callback: () => T): T;
+    /** Returns a reference to the current AsyncLocalStorage store, or `undefined` outside a `run()`. */
+    getStore(): Context.Store | undefined;
+    Provider: {
+        create: typeof create;
+        register: (name: Context.Provider.Key, item: Context.ContextService) => void;
+    };
+};
+/**
+ * Request-scoped key-value storage backed by AsyncLocalStorage.
+ *
+ * Values are either "visible" (included when calling `all()`) or "hidden"
+ * (accessible only through the `*Hidden` methods, excluded from logging).
+ *
+ * @example
+ * ```ts
+ * Context.run(() => {
+ *   Context.add('userId', 123)
+ *   Context.push('tags', 'admin', 'user')
+ *
+ *   Context.get<number>('userId')   // 123
+ *   Context.all()                   // { userId: 123, tags: ['admin', 'user'] }
+ *
+ *   // Typed handle for a single key
+ *   const userId = Context.createItem<number>('userId')
+ *   userId.get() // 123
+ *
+ *   // Transfer context to another async boundary
+ *   const store = Context.getStore()
+ *   Context.runWith(store, () => { ... })
+ * })
+ * ```
+ */
+declare namespace Context {
+    type Key = string | number | symbol;
+    /** The raw context snapshot containing visible and hidden Map buckets */
+    type Store = {
+        hidden: Map<Key, unknown>;
+        visible: Map<Key, unknown>;
+    };
+    /**
+     * Request-scoped key-value storage backed by `AsyncLocalStorage`.
+     *
+     * Each request gets its own isolated context so data never leaks between
+     * requests. Values are split into two buckets:
+     *
+     * - **Visible** – included when calling {@link all} (safe for logging).
+     * - **Hidden** – accessible only through the `*Hidden` methods and excluded
+     *   from logging, intended for sensitive data like tokens or credentials.
+     *
+     * Start a new context with {@link run}, then use the remaining methods to
+     * read and write within that scope.
+     *
+     * @example
+     * ```ts
+     * Context.run(() => {
+     *   Context.add('userId', 123)
+     *   Context.get<number>('userId') // 123
+     *   Context.all()                 // { userId: 123 }
+     * })
+     * ```
+     */
+    interface ContextService {
+        /** Initializes a fresh context store for the duration of `callback`. */
+        run<T>(callback: () => T): T;
+        /** Stores a key-value pair in the visible context, overriding any existing value. */
+        add(key: Key, value: any): void;
+        /** Removes one or more keys from the visible context. */
+        del(...key: Key[]): void;
+        /** Appends value(s) to an array in the visible context. Creates the array if the key doesn't exist. */
+        push(key: Key, ...value: any[]): void;
+        /** Returns `true` if the key exists in the visible context. */
+        has(key: Key): boolean;
+        /** Retrieves the value for `key` from the visible context, or `undefined` if absent. */
+        get<Value = unknown>(key: Key): Value | undefined;
+        /** Returns all visible context entries as a plain object. */
+        all(): {
+            [key: Key]: unknown;
+        };
+        /** Returns convenience methods scoped to a single key in the visible context. */
+        createItem<Value = unknown>(key: Key): {
+            add(value: Value): void;
+            del(): void;
+            push: Value extends Array<any> ? (...value: Value) => void : never;
+            get(): Value | undefined;
+        };
+        /** Stores a key-value pair in the hidden context (excluded from {@link all}). */
+        addHidden(key: Key, value: any): void;
+        /** Removes one or more keys from the hidden context. */
+        delHidden(...key: Key[]): void;
+        /** Appends value(s) to an array in the hidden context. */
+        pushHidden(key: Key, ...value: any[]): void;
+        /** Returns `true` if the key exists in the hidden context. */
+        hasHidden(key: Key): boolean;
+        /** Retrieves the value for `key` from the hidden context, or `undefined` if absent. */
+        getHidden<Value = unknown>(key: Key): Value | undefined;
+        /** Returns all hidden context entries as a plain object. */
+        allHidden(): {
+            [key: Key]: unknown;
+        };
+        /** Returns convenience methods scoped to a single key in the hidden context. */
+        createHiddenItem<Value = unknown>(key: Key): {
+            add(value: Value): void;
+            del(): void;
+            push: Value extends Array<any> ? (...value: Value) => void : never;
+            get(): Value | undefined;
+        };
+        /** Runs `callback` within the given store so context is available inside. */
+        runWith<T>(store: Store | undefined, callback: () => T): T;
+        /** Returns a reference to the current AsyncLocalStorage store, or `undefined` outside a `run()`. */
+        getStore(): Store | undefined;
+    }
+    namespace Provider {
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+
+export { Context };

package/dist/index.js

@@ -0,0 +1,143 @@
+// src/index.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+function create() {
+  const asyncStore = new AsyncLocalStorage();
+  function makeContextFns(getContext) {
+    function add2(key, value) {
+      const store = getContext();
+      if (store) {
+        store.set(key, value);
+      }
+    }
+    function del2(...key) {
+      const store = getContext();
+      if (store) {
+        key.forEach((k) => store.delete(k));
+      }
+    }
+    function push2(key, ...value) {
+      const store = getContext();
+      if (store) {
+        const arr = store.get(key);
+        if (arr === void 0) {
+          store.set(key, [...value]);
+        } else if (Array.isArray(arr)) {
+          store.set(key, [...arr, ...value]);
+        } else {
+          store.set(key, [arr, ...value]);
+        }
+      }
+    }
+    function has2(key) {
+      const store = getContext();
+      return !!store?.has(key);
+    }
+    function get2(key) {
+      const store = getContext();
+      return store?.get(key);
+    }
+    function all2() {
+      const store = getContext();
+      const entries = store ? [...store.entries()] : [];
+      return Object.fromEntries(entries);
+    }
+    function createItem2(key) {
+      return {
+        add(value) {
+          add2(key, value);
+        },
+        del() {
+          del2(key);
+        },
+        push: ((...value) => {
+          push2(key, ...value);
+        }),
+        get() {
+          return get2(key);
+        }
+      };
+    }
+    return { add: add2, del: del2, push: push2, has: has2, get: get2, all: all2, createItem: createItem2 };
+  }
+  const { add, del, push, has, get, all, createItem } = makeContextFns(() => asyncStore.getStore()?.visible);
+  const {
+    add: addHidden,
+    del: delHidden,
+    push: pushHidden,
+    has: hasHidden,
+    get: getHidden,
+    all: allHidden,
+    createItem: createHiddenItem
+  } = makeContextFns(() => asyncStore.getStore()?.hidden);
+  function run(callback) {
+    return asyncStore.run({ visible: /* @__PURE__ */ new Map(), hidden: /* @__PURE__ */ new Map() }, callback);
+  }
+  function runWith(store, callback) {
+    if (store) {
+      return asyncStore.run(store, callback);
+    } else {
+      return callback();
+    }
+  }
+  function getStore() {
+    return asyncStore.getStore();
+  }
+  return {
+    run,
+    add,
+    del,
+    push,
+    has,
+    get,
+    all,
+    createItem,
+    addHidden,
+    delHidden,
+    pushHidden,
+    hasHidden,
+    getHidden,
+    allHidden,
+    createHiddenItem,
+    runWith,
+    getStore
+  };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    run: service.run,
+    add: service.add,
+    del: service.del,
+    push: service.push,
+    has: service.has,
+    get: service.get,
+    all: service.all,
+    createItem: service.createItem,
+    addHidden: service.addHidden,
+    delHidden: service.delHidden,
+    pushHidden: service.pushHidden,
+    hasHidden: service.hasHidden,
+    getHidden: service.getHidden,
+    allHidden: service.allHidden,
+    createHiddenItem: service.createHiddenItem,
+    runWith: service.runWith,
+    getStore: service.getStore
+  };
+}
+Provider.register("default", create());
+var Context = {
+  Provider,
+  ...provider("default"),
+  provider
+};
+export {
+  Context
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@maestro-js/context",
+  "description": "Guide for working with @maestro-js/context, a request-scoped key-value storage package backed by Node.js AsyncLocalStorage. Use when working with @maestro-js/context, adding per-request state, storing visible or hidden context values, propagating context across async boundaries, integrating context with logging or tracing, creating typed context item handles, or transferring context stores between execution scopes. Covers the Provider pattern, visible/hidden buckets, run/runWith lifecycle, createItem typed handles, getStore for context propagation, and testing patterns.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "npx beartest ./tests",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}