@declaro/core 2.0.0-beta.99 → 2.1.0

package/dist/ts/shims/async-local-storage.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Browser polyfill for Node's AsyncLocalStorage.
+ *
+ * ## How it works
+ *
+ * Each AsyncLocalStorage instance has a unique Symbol as its "column" ID.
+ * The currently active state is a single `Map<symbol, unknown>` called a
+ * _frame_, where each column holds the value for one ALS instance.
+ *
+ * `run()` creates a new frame (a shallow copy of the parent frame with this
+ * instance's value set), makes it active for the duration of `fn`, then
+ * restores the previous frame in a `finally` block.
+ *
+ * Multiple ALS instances are fully isolated from each other within the same
+ * frame: `als1.run()` only writes to its own column and does not affect any
+ * other instance's column.
+ *
+ * ## Browser limitation
+ *
+ * Because browsers have no native async-context hook, the frame is propagated
+ * only within the synchronous call stack of `fn`. Any code that runs after an
+ * `await` boundary cannot see the frame that was active when the `await` was
+ * encountered. For true async propagation in the browser, use Zone.js or the
+ * forthcoming `AsyncContext` TC39 API.
+ */
+export declare class AsyncLocalStorage<T = any> {
+    #private;
+    getStore(): T | undefined;
+    run<R>(store: T, fn: (...args: any[]) => R, ...args: any[]): R;
+    exit<R>(fn: (...args: any[]) => R, ...args: any[]): R;
+    enterWith(store: T): void;
+    disable(): void;
+    static bind<F extends (...args: any[]) => any>(fn: F): F;
+    static snapshot(): <R>(fn: (...args: any[]) => R, ...args: any[]) => R;
+}
+//# sourceMappingURL=async-local-storage.d.ts.map

package/dist/ts/shims/async-local-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-local-storage.d.ts","sourceRoot":"","sources":["../../../src/shims/async-local-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,qBAAa,iBAAiB,CAAC,CAAC,GAAG,GAAG;;IAIlC,QAAQ,IAAI,CAAC,GAAG,SAAS;IAIzB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC;IAW9D,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC;IAWrD,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAMzB,OAAO,IAAI,IAAI;IAMf,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC;IAIxD,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;CAGzE"}

package/dist/ts/shims/async-local-storage.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=async-local-storage.test.d.ts.map

package/dist/ts/shims/async-local-storage.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-local-storage.test.d.ts","sourceRoot":"","sources":["../../../src/shims/async-local-storage.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@declaro/core",
-    "version": "2.0.0-beta.99",
+    "version": "2.1.0",
     "description": "Declarative Business Module Definition",
     "main": "dist/node/index.js",
     "module": "dist/node/index.js",
@@ -49,24 +49,32 @@
         "url": "https://github.com/emmertio/declaro/issues"
     },
     "homepage": "https://github.com/emmertio/declaro/tree/main#readme",
-    "gitHead": "0277b5d86fbbb5b1c1f77e367005bb11551471e7",
+    "gitHead": "d474a72810905706fdf1011441af4deb6c6f2620",
     "files": [
         "dist/**/*",
         "src/**/*"
     ],
     "exports": {
-        "bun": "./src/index.ts",
-        "types": "./dist/ts/index.d.ts",
-        "import": "./dist/node/index.js",
+        "import": {
+            "bun": "./dist/bun/index.js",
+            "browser": "./dist/browser/index.js",
+            "types": "./dist/ts/index.d.ts",
+            "default": "./dist/node/index.js"
+        },
         "require": "./dist/node/index.cjs",
-        "browser": "./dist/browser/index.js"
+        "types": "./dist/ts/index.d.ts",
+        "default": "./dist/node/index.js"
     },
     "imports": {
         "#scope": {
-            "types": "./dist/ts/scope/index.d.ts",
-            "import": "./dist/node/scope/index.js",
+            "import": {
+                "bun": "./dist/bun/scope/index.js",
+                "browser": "./dist/browser/scope/index.js",
+                "types": "./dist/ts/scope/index.d.ts",
+                "default": "./dist/node/scope/index.js"
+            },
             "require": "./dist/node/scope/index.cjs",
-            "browser": "./dist/browser/scope/index.js"
+            "types": "./dist/ts/scope/index.d.ts"
         }
     }
 }

package/src/context/async-context.test.ts

@@ -0,0 +1,348 @@
+import { AsyncLocalStorage as NativeALS } from 'node:async_hooks'
+import { describe, expect, it } from 'vitest'
+import { AsyncLocalStorage as ShimALS } from '../shims/async-local-storage'
+import {
+    type AsyncContextStorage,
+    createContextAPI,
+    useContext,
+    withContext,
+} from './async-context'
+import { Context } from './context'
+
+// ---------------------------------------------------------------------------
+// Shared test suite — sync behavior that works for every storage implementation.
+// ---------------------------------------------------------------------------
+function sharedContextTests(storage: AsyncContextStorage<Context> | undefined) {
+    const { withContext, useContext } = createContextAPI<Context>(storage)
+
+    it('returns the fn result synchronously', () => {
+        const context = new Context()
+        const result = withContext(context, () => 42)
+        expect(result).toBe(42)
+    })
+
+    it('returns the fn result asynchronously', async () => {
+        const context = new Context()
+        const result = await withContext(context, async () => 'hello')
+        expect(result).toBe('hello')
+    })
+
+    it('useContext() returns the active context inside withContext', () => {
+        const context = new Context()
+        withContext(context, () => {
+            expect(useContext()).toBe(context)
+        })
+    })
+
+    it('useContext() returns null outside of withContext', () => {
+        expect(useContext()).toBeNull()
+    })
+
+    it('useContext({ strict: true }) throws outside of withContext', () => {
+        expect(() => useContext({ strict: true })).toThrow(
+            'useContext() was called outside of an active context'
+        )
+    })
+
+    it('useContext({ strict: true }) returns context inside withContext', () => {
+        const context = new Context()
+        withContext(context, () => {
+            expect(useContext({ strict: true })).toBe(context)
+        })
+    })
+
+    it('nested withContext calls use the innermost context', () => {
+        const outer = new Context()
+        const inner = new Context()
+
+        withContext(outer, () => {
+            expect(useContext()).toBe(outer)
+
+            withContext(inner, () => {
+                expect(useContext()).toBe(inner)
+            })
+
+            expect(useContext()).toBe(outer)
+        })
+    })
+
+    it('context is not visible after withContext completes', () => {
+        const context = new Context()
+        withContext(context, () => {})
+        expect(useContext()).toBeNull()
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Async propagation suite — only for storage types with true async support
+// (native AsyncLocalStorage). The synchronous browser shim cannot propagate
+// context across await boundaries.
+// ---------------------------------------------------------------------------
+function asyncPropagationTests(storage: AsyncContextStorage<Context> | undefined) {
+    const { withContext, useContext } = createContextAPI<Context>(storage)
+
+    it('useContext() returns the active context inside async withContext', async () => {
+        const context = new Context()
+        await withContext(context, async () => {
+            await Promise.resolve()
+            expect(useContext()).toBe(context)
+        })
+    })
+
+    it('context propagates across async boundaries', async () => {
+        const context = new Context()
+        const results: (Context | null)[] = []
+
+        await withContext(context, async () => {
+            results.push(useContext())
+            await new Promise((resolve) => setTimeout(resolve, 0))
+            results.push(useContext())
+        })
+
+        expect(results).toEqual([context, context])
+    })
+
+    describe('nested async contexts (request → event fork)', () => {
+        it('full lifecycle: null → outer → inner → outer → null', async () => {
+            const requestContext = new Context()
+            const eventContext = new Context()
+            const snapshots: (Context | null)[] = []
+
+            snapshots.push(useContext())
+
+            await withContext(requestContext, async () => {
+                snapshots.push(useContext())
+
+                await withContext(eventContext, async () => {
+                    snapshots.push(useContext())
+                })
+
+                snapshots.push(useContext())
+            })
+
+            snapshots.push(useContext())
+
+            expect(snapshots).toEqual([null, requestContext, eventContext, requestContext, null])
+        })
+
+        it('concurrent async tasks each see their own context independently', async () => {
+            const requestContext = new Context()
+            const eventContext = new Context()
+            const requestSnapshots: (Context | null)[] = []
+            const eventSnapshots: (Context | null)[] = []
+
+            await Promise.all([
+                withContext(requestContext, async () => {
+                    requestSnapshots.push(useContext())
+                    await new Promise((resolve) => setTimeout(resolve, 10))
+                    requestSnapshots.push(useContext())
+                }),
+                withContext(eventContext, async () => {
+                    eventSnapshots.push(useContext())
+                    await new Promise((resolve) => setTimeout(resolve, 5))
+                    eventSnapshots.push(useContext())
+                }),
+            ])
+
+            expect(requestSnapshots).toEqual([requestContext, requestContext])
+            expect(eventSnapshots).toEqual([eventContext, eventContext])
+        })
+
+        it('inner withContext with forked context does not bleed into outer after completion', async () => {
+            const requestContext = new Context()
+            const eventContext = new Context()
+
+            await withContext(requestContext, async () => {
+                const eventDone = withContext(eventContext, async () => {
+                    await Promise.resolve()
+                    expect(useContext()).toBe(eventContext)
+                })
+
+                expect(useContext()).toBe(requestContext)
+
+                await eventDone
+
+                expect(useContext()).toBe(requestContext)
+            })
+
+            expect(useContext()).toBeNull()
+        })
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Native AsyncLocalStorage — full async propagation
+// ---------------------------------------------------------------------------
+describe('withContext / useContext (native AsyncLocalStorage)', () => {
+    sharedContextTests(new NativeALS<Context>())
+    asyncPropagationTests(new NativeALS<Context>())
+
+    // These tests exercise Context.emit() which calls the module-level
+    // withContext (always native). They verify the framework integration and
+    // are only meaningful with true async propagation.
+    describe('typed scopes with event listeners', () => {
+        interface AppScope {
+            foo: string
+            bar: number
+        }
+
+        interface RequestScope extends AppScope {
+            baz: boolean
+        }
+
+        it("event listener receives the emitter's context, not the registration context", async () => {
+            const appContext = new Context<AppScope>()
+
+            let capturedViaALS: Context | null = null
+            let capturedViaArg: Context | null = null
+
+            appContext.on('testEvent', async (listenerContext) => {
+                capturedViaArg = listenerContext
+                capturedViaALS = useContext()
+            })
+
+            const requestContext = new Context<RequestScope>().extend(appContext)
+
+            await withContext(appContext, async () => {
+                await withContext(requestContext, async () => {
+                    await requestContext.emit('testEvent')
+                })
+            })
+
+            expect(capturedViaArg).toBe(requestContext)
+            expect(capturedViaALS).toBe(requestContext)
+        })
+
+        it('useContext() returns the correct typed context across nested scopes', async () => {
+            const appContext = new Context<AppScope>()
+            appContext.registerValue('foo', 'hello')
+            appContext.registerValue('bar', 42)
+
+            const snapshots: (Context | null)[] = []
+
+            appContext.on('testEvent', async () => {
+                snapshots.push(useContext())
+            })
+
+            const requestContext = new Context<RequestScope>().extend(appContext)
+            requestContext.registerValue('baz', true)
+
+            await withContext(appContext, async () => {
+                snapshots.push(useContext())
+
+                await withContext(requestContext, async () => {
+                    snapshots.push(useContext())
+                    await requestContext.emit('testEvent')
+                })
+
+                snapshots.push(useContext())
+            })
+
+            expect(snapshots).toEqual([appContext, requestContext, requestContext, appContext])
+        })
+
+        it('useContext<RequestScope>() narrows the type inside the request scope', async () => {
+            const appContext = new Context<AppScope>()
+
+            let resolvedBaz: boolean | undefined
+
+            appContext.on('testEvent', async () => {
+                const ctx = useContext<Context<RequestScope>>()
+                resolvedBaz = ctx?.resolve('baz')
+            })
+
+            const requestContext = new Context<RequestScope>().extend(appContext)
+            requestContext.registerValue('baz', true)
+
+            await withContext(requestContext, async () => {
+                await requestContext.emit('testEvent')
+            })
+
+            expect(resolvedBaz).toBe(true)
+        })
+
+        it('strict useContext() succeeds inside a listener because emit sets the context', async () => {
+            const appContext = new Context<AppScope>()
+            let capturedContext: Context | null = null
+
+            appContext.on('testEvent', async () => {
+                capturedContext = useContext({ strict: true })
+            })
+
+            await appContext.emit('testEvent')
+
+            expect(capturedContext).toBe(appContext)
+        })
+    })
+})
+
+// ---------------------------------------------------------------------------
+// Browser shim — synchronous propagation only.
+// Context is available within the synchronous call stack of withContext, but
+// is not propagated across await boundaries. This is expected and correct for
+// browser environments where native async hooks are unavailable.
+// ---------------------------------------------------------------------------
+describe('withContext / useContext (browser shim AsyncLocalStorage)', () => {
+    sharedContextTests(new ShimALS<Context>())
+
+    const { withContext, useContext } = createContextAPI<Context>(new ShimALS<Context>())
+
+    describe('async behavior (sync-only shim)', () => {
+        it('context is available at the start of an async fn before any await', async () => {
+            const context = new Context()
+            let captured: Context | null = null
+
+            await withContext(context, async () => {
+                captured = useContext()
+            })
+
+            expect(captured).toBe(context)
+        })
+
+        it('context is not available after an await boundary (expected shim behavior)', async () => {
+            const context = new Context()
+            let captured: Context | null | 'sentinel' = 'sentinel'
+
+            await withContext(context, async () => {
+                await Promise.resolve()
+                captured = useContext()
+            })
+
+            expect(captured).toBeNull()
+        })
+
+        it('full lifecycle: null → outer → inner → null → null (sync-only)', async () => {
+            const requestContext = new Context()
+            const eventContext = new Context()
+            const snapshots: (Context | null)[] = []
+
+            snapshots.push(useContext())
+
+            await withContext(requestContext, async () => {
+                snapshots.push(useContext())
+
+                await withContext(eventContext, async () => {
+                    snapshots.push(useContext())
+                })
+
+                snapshots.push(useContext())
+            })
+
+            snapshots.push(useContext())
+
+            // The shim restores context synchronously when run() exits.
+            // After awaiting the inner withContext, the outer context is gone.
+            expect(snapshots).toEqual([null, requestContext, eventContext, null, null])
+        })
+    })
+})
+
+// ---------------------------------------------------------------------------
+// Default storage — no storage argument; createContextAPI creates its own
+// AsyncLocalStorage internally. In browser builds this resolves to the shim.
+// In Node/Bun (where tests run) it resolves to native AsyncLocalStorage.
+// ---------------------------------------------------------------------------
+describe('withContext / useContext (default storage)', () => {
+    sharedContextTests(undefined)
+    asyncPropagationTests(undefined)
+})

package/src/context/async-context.ts

@@ -0,0 +1,129 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { Context } from './context'
+
+/**
+ * Minimal interface for the storage backing `withContext` / `useContext`.
+ * Satisfied by Node's native `AsyncLocalStorage` and by the browser shim.
+ */
+export interface AsyncContextStorage<C extends Context = Context> {
+    run<R>(store: C, fn: (...args: any[]) => R, ...args: any[]): R
+    getStore(): C | undefined
+}
+
+export interface UseContextOptions {
+    strict?: boolean
+}
+
+/**
+ * Create a `withContext` / `useContext` pair backed by the given storage.
+ *
+ * The generic type parameter `C` fixes the context type enforced by both
+ * functions, keeping the pair consistent. If no storage is provided, a new
+ * `AsyncLocalStorage<C>` is created automatically — in browser builds this
+ * resolves to the synchronous shim, so callers don't need to think about it.
+ *
+ * Pass a custom storage explicitly when you need an alternative
+ * implementation (e.g. a test spy or the browser shim in a test environment):
+ *
+ * @example Default (auto-polyfilled in browser builds)
+ * ```ts
+ * const { withContext, useContext } = createContextAPI<MyContext>()
+ * ```
+ *
+ * @example Custom storage (for testing or advanced use)
+ * ```ts
+ * import { AsyncLocalStorage } from '../shims/async-local-storage'
+ * const { withContext, useContext } = createContextAPI<MyContext>(new AsyncLocalStorage())
+ * ```
+ */
+export function createContextAPI<C extends Context = Context>(storage?: AsyncContextStorage<C>) {
+    const _storage: AsyncContextStorage<C> = storage ?? new AsyncLocalStorage<C>()
+
+    /**
+     * Run `fn` with `context` bound as the active async context. Inside `fn`
+     * (and any async work it triggers, including across `await` boundaries),
+     * calls to `useContext()` will return this context.
+     *
+     * Nesting is fully supported: an inner `withContext` creates a child scope
+     * that sees its own context; when it exits the parent scope is restored.
+     *
+     * Internally uses `AsyncLocalStorage` from `node:async_hooks`. In browser
+     * environments, a synchronous shim is substituted at build time — context
+     * propagates correctly across sequential async flows (event listeners,
+     * middleware chains) but not across concurrent async tasks running in
+     * parallel.
+     *
+     * @param context - The context to make active for the duration of `fn`.
+     * @param fn - Arbitrary sync or async callback to run inside the context.
+     * @returns Whatever `fn` returns.
+     *
+     * @example Basic usage
+     * ```ts
+     * await withContext(requestContext, async () => {
+     *     await eventEmitter.emitAsync(event) // listeners can call useContext()
+     * })
+     * ```
+     *
+     * @example Forking the context for an event
+     * ```ts
+     * await withContext(requestContext, async () => {
+     *     const eventContext = requestContext.extend()
+     *     await withContext(eventContext, () => emitter.emitAsync(event))
+     *     // useContext() here still returns requestContext
+     * })
+     * ```
+     *
+     * @example Creating a context-specific helper (recommended pattern)
+     * ```ts
+     * // For withContext, define a typed wrapper since TypeScript cannot partially
+     * // apply the return-type parameter via an instantiation expression:
+     * const withMyContext = <T>(context: MyContext, fn: () => T) =>
+     *     withContext<T>(context, fn)
+     * ```
+     */
+    function withContext<T = unknown>(context: C, fn: () => T): T {
+        return _storage.run(context, fn)
+    }
+
+    /**
+     * Return the `Context` currently active in async local storage, or `null`
+     * if called outside any `withContext` block.
+     *
+     * The optional generic parameter `U` narrows the return type to a subclass
+     * of `C` when you know the active context is more specific.
+     *
+     * Backed by `AsyncLocalStorage` on Node/Bun and a synchronous shim in
+     * browser builds. See `withContext` for details on browser limitations.
+     *
+     * @param options.strict - When `true`, throws instead of returning `null`.
+     *
+     * @example
+     * ```ts
+     * const context = useContext()               // C | null
+     * const context = useContext({ strict: true }) // C (throws if missing)
+     * ```
+     *
+     * @example Narrowing to a subtype
+     * ```ts
+     * const useMyContext = useContext<MyContext>
+     * ```
+     */
+    function useContext<U extends C = C>(options?: { strict?: false }): U | null
+    function useContext<U extends C = C>(options: { strict: true }): U
+    function useContext<U extends C = C>(options?: UseContextOptions): U | null {
+        const context = (_storage.getStore() ?? null) as U | null
+        if (!context && options?.strict) {
+            throw new Error(
+                'useContext() was called outside of an active context. Wrap your code with withContext().'
+            )
+        }
+        return context
+    }
+
+    return { withContext, useContext }
+}
+
+// Module-level pair backed by the default AsyncLocalStorage.
+// In browser builds the import of node:async_hooks is swapped for the
+// synchronous shim at build time, so this works without any extra config.
+export const { withContext, useContext } = createContextAPI<Context>()