@declaro/core 2.0.0-y.0 → 2.1.0

package/src/shims/async-local-storage.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it } from 'vitest'
+import { AsyncLocalStorage } from './async-local-storage'
+
+describe('AsyncLocalStorage shim', () => {
+    describe('run()', () => {
+        it('returns the fn result synchronously', () => {
+            const als = new AsyncLocalStorage<number>()
+            const result = als.run(1, () => 42)
+            expect(result).toBe(42)
+        })
+
+        it('returns a Promise when fn is async', async () => {
+            const als = new AsyncLocalStorage<string>()
+            const result = await als.run('ctx', async () => 'hello')
+            expect(result).toBe('hello')
+        })
+
+        it('forwards extra args to fn', () => {
+            const als = new AsyncLocalStorage<string>()
+            const result = als.run('ctx', (a: number, b: number) => a + b, 3, 4)
+            expect(result).toBe(7)
+        })
+
+        it('getStore() returns the active store inside run()', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.run('hello', () => {
+                expect(als.getStore()).toBe('hello')
+            })
+        })
+
+        it('getStore() returns undefined outside of run()', () => {
+            const als = new AsyncLocalStorage<string>()
+            expect(als.getStore()).toBeUndefined()
+        })
+
+        it('store is not visible after run() completes', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.run('hello', () => {})
+            expect(als.getStore()).toBeUndefined()
+        })
+
+        it('nested run() calls use the innermost store', () => {
+            const als = new AsyncLocalStorage<string>()
+
+            als.run('outer', () => {
+                expect(als.getStore()).toBe('outer')
+
+                als.run('inner', () => {
+                    expect(als.getStore()).toBe('inner')
+                })
+
+                expect(als.getStore()).toBe('outer')
+            })
+        })
+
+        it('restores prior store after nested run() completes', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.run('outer', () => {
+                als.run('inner', () => {})
+                expect(als.getStore()).toBe('outer')
+            })
+            expect(als.getStore()).toBeUndefined()
+        })
+
+        it('full lifecycle: undefined → outer → inner → outer → undefined', () => {
+            const als = new AsyncLocalStorage<string>()
+            const snapshots: (string | undefined)[] = []
+
+            snapshots.push(als.getStore())
+            als.run('outer', () => {
+                snapshots.push(als.getStore())
+                als.run('inner', () => {
+                    snapshots.push(als.getStore())
+                })
+                snapshots.push(als.getStore())
+            })
+            snapshots.push(als.getStore())
+
+            expect(snapshots).toEqual([undefined, 'outer', 'inner', 'outer', undefined])
+        })
+
+        it('restores store even when fn throws', () => {
+            const als = new AsyncLocalStorage<string>()
+            expect(() =>
+                als.run('ctx', () => {
+                    throw new Error('boom')
+                }),
+            ).toThrow('boom')
+            expect(als.getStore()).toBeUndefined()
+        })
+
+        it('multiple ALS instances are isolated from each other', () => {
+            const als1 = new AsyncLocalStorage<string>()
+            const als2 = new AsyncLocalStorage<number>()
+
+            als1.run('hello', () => {
+                als2.run(42, () => {
+                    expect(als1.getStore()).toBe('hello')
+                    expect(als2.getStore()).toBe(42)
+                })
+                expect(als1.getStore()).toBe('hello')
+                expect(als2.getStore()).toBeUndefined()
+            })
+        })
+    })
+
+    describe('async usage', () => {
+        it('store is accessible at the start of an async fn (before any await)', async () => {
+            const als = new AsyncLocalStorage<string>()
+            let captured: string | undefined
+
+            await als.run('ctx', async () => {
+                // No await yet — still in the synchronous call stack of run()
+                captured = als.getStore()
+            })
+
+            expect(captured).toBe('ctx')
+        })
+
+        it('resolves the returned Promise correctly', async () => {
+            const als = new AsyncLocalStorage<string>()
+            const result = await als.run('ctx', async () => 'resolved')
+            expect(result).toBe('resolved')
+        })
+
+        it('propagates rejections correctly', async () => {
+            const als = new AsyncLocalStorage<string>()
+            await expect(
+                als.run('ctx', async () => {
+                    throw new Error('async boom')
+                }),
+            ).rejects.toThrow('async boom')
+        })
+
+        it('restores store after an async fn resolves', async () => {
+            const als = new AsyncLocalStorage<string>()
+            await als.run('ctx', async () => {})
+            expect(als.getStore()).toBeUndefined()
+        })
+
+        // The shim uses synchronous save/restore. The finally block in run()
+        // fires as soon as the async fn returns its Promise — before any
+        // awaited microtasks resume. Context is therefore not visible after an
+        // await boundary. Native AsyncLocalStorage (Node/Bun) does not have
+        // this limitation.
+        it('does NOT propagate store across await boundaries (synchronous shim limitation)', async () => {
+            const als = new AsyncLocalStorage<string>()
+            let captured: string | undefined = 'sentinel'
+
+            await als.run('ctx', async () => {
+                await Promise.resolve()
+                captured = als.getStore()
+            })
+
+            expect(captured).toBeUndefined()
+        })
+
+        it('does NOT isolate concurrent async tasks (synchronous shim limitation)', async () => {
+            const als = new AsyncLocalStorage<string>()
+            const results: (string | undefined)[] = []
+
+            await Promise.all([
+                als.run('task-a', async () => {
+                    await new Promise<void>((r) => setTimeout(r, 10))
+                    results.push(als.getStore())
+                }),
+                als.run('task-b', async () => {
+                    await new Promise<void>((r) => setTimeout(r, 5))
+                    results.push(als.getStore())
+                }),
+            ])
+
+            expect(results).toEqual([undefined, undefined])
+        })
+    })
+
+    describe('exit()', () => {
+        it('clears the store for the duration of fn', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.run('ctx', () => {
+                als.exit(() => {
+                    expect(als.getStore()).toBeUndefined()
+                })
+            })
+        })
+
+        it('restores the store after exit() completes', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.run('ctx', () => {
+                als.exit(() => {})
+                expect(als.getStore()).toBe('ctx')
+            })
+        })
+
+        it('restores store even when fn throws', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.run('ctx', () => {
+                expect(() =>
+                    als.exit(() => {
+                        throw new Error('boom')
+                    }),
+                ).toThrow('boom')
+                expect(als.getStore()).toBe('ctx')
+            })
+        })
+    })
+
+    describe('enterWith()', () => {
+        it('sets the store imperatively', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.enterWith('hello')
+            expect(als.getStore()).toBe('hello')
+        })
+
+        it('can be overwritten by another enterWith()', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.enterWith('first')
+            als.enterWith('second')
+            expect(als.getStore()).toBe('second')
+        })
+    })
+
+    describe('disable()', () => {
+        it('clears the store', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.enterWith('hello')
+            als.disable()
+            expect(als.getStore()).toBeUndefined()
+        })
+
+        it('has no effect when store is already empty', () => {
+            const als = new AsyncLocalStorage<string>()
+            als.disable()
+            expect(als.getStore()).toBeUndefined()
+        })
+    })
+
+    describe('AsyncLocalStorage.bind()', () => {
+        it('returns the function unchanged', () => {
+            const fn = () => 42
+            expect(AsyncLocalStorage.bind(fn)).toBe(fn)
+        })
+    })
+
+    describe('AsyncLocalStorage.snapshot()', () => {
+        it('returns a function that calls fn with provided args', () => {
+            const run = AsyncLocalStorage.snapshot()
+            const result = run((a: number, b: number) => a + b, 3, 4)
+            expect(result).toBe(7)
+        })
+
+        it('each call to snapshot() returns an independent executor', () => {
+            const run1 = AsyncLocalStorage.snapshot()
+            const run2 = AsyncLocalStorage.snapshot()
+            expect(run1).not.toBe(run2)
+        })
+    })
+})

package/src/shims/async-local-storage.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+
+// A frame maps ALS instance IDs → their stored values.
+// All concurrently active ALS instances share one frame object.
+type Frame = Map<symbol, unknown>
+
+let _activeFrame: Frame | undefined = undefined
+
+export class AsyncLocalStorage<T = any> {
+    // Unique identity for this ALS instance within a frame.
+    readonly #id: symbol = Symbol('AsyncLocalStorage')
+
+    getStore(): T | undefined {
+        return _activeFrame?.get(this.#id) as T | undefined
+    }
+
+    run<R>(store: T, fn: (...args: any[]) => R, ...args: any[]): R {
+        const prev = _activeFrame
+        _activeFrame = new Map(prev)
+        _activeFrame.set(this.#id, store)
+        try {
+            return fn(...args)
+        } finally {
+            _activeFrame = prev
+        }
+    }
+
+    exit<R>(fn: (...args: any[]) => R, ...args: any[]): R {
+        const prev = _activeFrame
+        _activeFrame = new Map(prev)
+        _activeFrame.delete(this.#id)
+        try {
+            return fn(...args)
+        } finally {
+            _activeFrame = prev
+        }
+    }
+
+    enterWith(store: T): void {
+        const frame = new Map(_activeFrame)
+        frame.set(this.#id, store)
+        _activeFrame = frame
+    }
+
+    disable(): void {
+        const frame = new Map(_activeFrame)
+        frame.delete(this.#id)
+        _activeFrame = frame
+    }
+
+    static bind<F extends (...args: any[]) => any>(fn: F): F {
+        return fn
+    }
+
+    static snapshot(): <R>(fn: (...args: any[]) => R, ...args: any[]) => R {
+        return (fn, ...args) => fn(...args)
+    }
+}

package/src/typescript/objects.ts

@@ -11,5 +11,36 @@ export type DeepPartial<T> = T extends object
  * Merge two object types without using an intersection type. Intersection types preserve the original types of the objects causing confusion, while this type will merge the types of the objects.
  */
 export type Merge<A, B> = {
-    [key in keyof A | keyof B]: key extends keyof B ? B[key] : key extends keyof A ? A[key] : never
+    [K in keyof A | keyof B]: K extends keyof B
+        ? B[K] extends object[] // Support for arrays
+            ? K extends keyof A
+                ? A[K] extends object[]
+                    ? Merge<A[K], B[K]> // If both are arrays, merge them
+                    : B[K] // If only B is an array, use B
+                : B[K]
+            : B[K] extends object
+            ? K extends keyof A
+                ? A[K] extends object
+                    ? Merge<A[K], B[K]>
+                    : B[K]
+                : B[K]
+            : B[K]
+        : K extends keyof A
+        ? A[K]
+        : never
 }
+
+/**
+ * Shallow merge two object types, replacing types of properties instead of merging them.
+ * Properties in B will completely replace properties in A.
+ */
+export type ShallowMerge<A extends object, B extends object> = {
+    [K in UniqueKeys<keyof A, keyof B>]: A[K]
+} & {
+    [K in keyof B]: B[K]
+}
+
+/**
+ * Extract keys from A that are not present in B
+ */
+export type UniqueKeys<A, B> = A extends B ? never : A

package/src/validation/validator.test.ts

@@ -1,5 +1,5 @@
 import { validate, validateAny } from './validator'
-import { describe, it, vi } from 'vitest'
+import { describe, it, vi, expect } from 'vitest'
 
 async function sleep(duration: number) {
     return new Promise((resolve, reject) => {
@@ -10,31 +10,25 @@ async function sleep(duration: number) {
 }
 
 describe('Validator', () => {
-    it('Should validate with valid property', async ({ expect }) => {
+    it('Should validate with valid property', async () => {
         const value = {
             message: 'Hello World',
         }
-        const valid = await validate(
-            value,
-            (val) => val.message === 'Hello World',
-        ).valid
+        const valid = await validate(value, (val) => val.message === 'Hello World').valid
 
         expect(valid).toBeTruthy()
     })
 
-    it('Should validate with invalid property', async ({ expect }) => {
+    it('Should validate with invalid property', async () => {
         const value = {
             message: 'Hello Mr. Anderson',
         }
-        const valid = await validate(
-            value,
-            (val) => val.message === 'Hello World',
-        ).valid
+        const valid = await validate(value, (val) => val.message === 'Hello World').valid
 
         expect(valid).toBeFalsy()
     })
 
-    it('Should validate with onValid callback', async ({ expect }) => {
+    it('Should validate with onValid callback', async () => {
         const valid = vi.fn((val) => {
             expect(val).toBe(42)
         })
@@ -54,7 +48,7 @@ describe('Validator', () => {
         expect(invalid.mock.calls.length).toBe(0)
     })
 
-    it('Should validate with onInvalid callback', async ({ expect }) => {
+    it('Should validate with onInvalid callback', async () => {
         const valid = vi.fn((val) => {
             expect(val).toBe(42)
         })
@@ -73,7 +67,7 @@ describe('Validator', () => {
         expect(invalid.mock.calls.length).toBe(1)
     })
 
-    it('Should validate multiple validators', async ({ expect }) => {
+    it('Should validate multiple validators', async () => {
         const value = {
             message: 'Hello Mr. Anderson',
         }
@@ -87,9 +81,7 @@ describe('Validator', () => {
         expect(valid).toBeTruthy()
     })
 
-    it('Should invalidate if one of multiple validators fails', async ({
-        expect,
-    }) => {
+    it('Should invalidate if one of multiple validators fails', async () => {
         const value = {
             message: 'Hello Mr. Anderson',
         }
@@ -103,7 +95,7 @@ describe('Validator', () => {
         expect(valid).toBeFalsy()
     })
 
-    it('Should be able to validate an any strategy', async ({ expect }) => {
+    it('Should be able to validate an any strategy', async () => {
         const value = {
             message: 'Hello Mr. Anderson',
         }
@@ -117,7 +109,7 @@ describe('Validator', () => {
         expect(valid).toBeTruthy()
     })
 
-    it('Should be able to invalidate an any strategy', async ({ expect }) => {
+    it('Should be able to invalidate an any strategy', async () => {
         const value = {
             message: 'Hello Mr. Anderson',
         }
@@ -131,7 +123,7 @@ describe('Validator', () => {
         expect(valid).toBeFalsy()
     })
 
-    it('Should validate an async validator', async ({ expect }) => {
+    it('Should validate an async validator', async () => {
         const value = {
             message: 'Hello World',
         }

package/dist/app/app-context.d.ts

@@ -1,8 +0,0 @@
-import { Context } from '../context/context';
-/**
- * Get the name of the app making the current request via header x-app. (returns "default" when no app was provided).
- *
- * @param context
- * @returns the name of the app in a string.
- */
-export declare function useApp(context: Context): string;

package/dist/app/app-lifecycle.d.ts

@@ -1,4 +0,0 @@
-import { Context, ContextListener } from '../context/context';
-export declare function onInit(context: Context, listener: ContextListener): void;
-export declare function onStart(context: Context, listener: ContextListener): void;
-export declare function onDestroy(context: Context, listener: ContextListener): void;

package/dist/app/app.d.ts

@@ -1,22 +0,0 @@
-import { Context, ContextMiddleware, ContextListener } from '../context/context';
-export type AppConfig = {
-    context?: Context;
-    init?: ContextMiddleware;
-    start?: ContextMiddleware;
-    destroy?: ContextMiddleware;
-};
-export declare class App {
-    readonly context: Context;
-    constructor(context: Context);
-    static Events: {
-        Init: string;
-        Start: string;
-        Destroy: string;
-    };
-    init(): Promise<void>;
-    onInit(listener: ContextListener): this;
-    start(): Promise<void>;
-    onStart(listener: ContextListener): void;
-    destroy(): Promise<void>;
-    onDestroy(listener: ContextListener): void;
-}

package/dist/auth/permission-validator.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/context/context.d.ts

@@ -1,161 +0,0 @@
-import { Class, PromiseOrValue, UnwrapPromise } from '../typescript';
-import { Validator } from '../validation';
-import { ContextConsumer } from './context-consumer';
-export type AppScope = {};
-export type RequestScope = {};
-export type AppContext = Context<AppScope>;
-export type RequestContext = Context<RequestScope>;
-export type ContextMiddleware = (context: Context) => any | Promise<any>;
-export type ContextState<TContext extends Context> = Record<PropertyKey, ContextAttribute<TContext, StateValue<any>>>;
-export type ContextResolver<T> = (context: Context) => StateValue<T>;
-export type StateValue<T> = T;
-export declare enum DependencyType {
-    VALUE = "VALUE",
-    FACTORY = "FACTORY",
-    CLASS = "CLASS"
-}
-export type FactoryFn<T, A extends any[]> = (...args: A) => T;
-export type ValueLoader<C extends Context, T> = (context: C) => T;
-export type FilterKeysByType<TScope, TValue> = {
-    [Key in keyof TScope]: TScope[Key] extends TValue ? Key : never;
-}[keyof TScope];
-export type FilterKeysByAsyncType<TScope, TValue> = {
-    [Key in keyof TScope]: TScope[Key] extends PromiseOrValue<TValue> ? Key : never;
-}[keyof TScope];
-export type FilterArgsByType<TScope, TArgs extends any[]> = {
-    [Key in keyof TArgs]: FilterKeysByType<TScope, TArgs[Key]>;
-};
-export type FilterAsyncArgsByType<TScope, TArgs extends any[]> = {
-    [Key in keyof TArgs]: FilterKeysByAsyncType<TScope, TArgs[Key]>;
-};
-export type ContextAttribute<TContext extends Context<any>, TValue> = {
-    key: PropertyKey;
-    value?: ValueLoader<TContext, TValue>;
-    type: DependencyType;
-    resolveOptions: ResolveOptions;
-    cachedValue?: TValue;
-    inject: PropertyKey[];
-};
-export type ScopeKey<S extends object> = keyof S;
-export type ContextListener = (context: Context) => any;
-export type ResolveOptions = {
-    strict?: boolean;
-    eager?: boolean;
-    singleton?: boolean;
-};
-export declare function defaultResolveOptions(): ResolveOptions;
-export type ContextOptions = {
-    defaultResolveOptions?: ResolveOptions;
-};
-export declare class Context<Scope extends object = any> {
-    private readonly state;
-    private readonly emitter;
-    readonly scope: Scope;
-    protected readonly defaultResolveOptions: ResolveOptions;
-    constructor(options?: ContextOptions);
-    /**
-     * Set a value in context, to be injected later.
-     *
-     * @param key
-     * @param payload
-     * @deprecated Use `provideValue` instead, or you can register the same dependency as a factory with `provideFactory` or class with `provideClass`.
-     */
-    provide<K extends ScopeKey<Scope>>(key: K, payload: Scope[K]): void;
-    /**
-     * Manually register a dependency. This should normally be used by utils or integrations that need to register dependencies in creative ways. For normal use cases, using `provideValue`, `provideFactory`, or `provideClass` is sufficient.
-     *
-     * @param key The key to register the dependency under
-     * @param dep The dependency record
-     */
-    register<K extends ScopeKey<Scope>>(key: K, dep: ContextAttribute<this, Scope[K]>): void;
-    /**
-     * Register a value in context scope.
-     *
-     * @param key The key to register the dependency under
-     * @param value The value to register
-     */
-    registerValue<K extends ScopeKey<Scope>>(key: K, value: Scope[K], defaultResolveOptions?: ResolveOptions): this;
-    /**
-     * Register a dependency as a factory in context scope.
-     *
-     * @param key The key to register the dependency under
-     * @param factory A factory function that will be called to generate the value when it is requested.
-     * @param inject An array of keys to use when injecting factory args.
-     * @returns A chainable instance of context
-     */
-    registerFactory<K extends ScopeKey<Scope>, A extends any[]>(key: K, factory: FactoryFn<Scope[K], A>, inject?: FilterArgsByType<Scope, A>, defaultResolveOptions?: ResolveOptions): this;
-    registerAsyncFactory<K extends FilterKeysByType<Scope, Promise<any>>, A extends any[]>(key: K, factory: FactoryFn<Scope[K], A>, inject?: FilterAsyncArgsByType<Scope, A>, defaultResolveOptions?: ResolveOptions): this;
-    registerClass<K extends FilterKeysByType<Scope, InstanceType<T>>, T extends Class<Scope[K]>>(key: K, Class: T, inject?: FilterArgsByType<Scope, ConstructorParameters<T>>, defaultResolveOptions?: ResolveOptions): this;
-    registerAsyncClass<K extends FilterKeysByType<Scope, InstanceType<any>>, T extends Class<UnwrapPromise<Scope[K]>>>(key: K, Class: T, inject?: FilterAsyncArgsByType<Scope, ConstructorParameters<T>>, defaultResolveOptions?: ResolveOptions): this;
-    getAllDependencies<K extends ScopeKey<Scope>>(key: K): ContextAttribute<this, any>[];
-    getAllDependents<K extends ScopeKey<Scope>>(key: K): ContextAttribute<this, any>[];
-    introspect<K extends ScopeKey<Scope>>(key: K): ContextState<this>[K];
-    protected _cacheIsValid<K extends ScopeKey<Scope>>(key: K): boolean;
-    protected _resolveValue<K extends ScopeKey<Scope>>(key: K, resolveOptions?: ResolveOptions): Scope[K];
-    /**
-     * Extract a value from context.
-     *
-     * @param key
-     * @returns
-     * @deprecated Use `resolve` instead
-     */
-    inject<T = any>(key: ScopeKey<Scope>): T | undefined;
-    resolve<K extends ScopeKey<Scope>>(key: K, resolveOptions?: ResolveOptions): Scope[K];
-    /**
-     * Ensure that only one copy of this instance exists in this context. Provides the instance if it doesn't exist yet, otherwise inject the cached instance.
-     *
-     * @param key
-     * @param instance
-     */
-    singleton<T = any>(key: ScopeKey<Scope>, instance: T): T;
-    /**
-     * Instantiate a ContextConsumer class
-     *
-     * @param Consumer
-     * @returns
-     */
-    hydrate<T extends ContextConsumer<this, any[]>, A extends any[]>(Consumer: new (context: this, ...args: A) => T, ...args: A): T;
-    /**
-     * Create a new context from other instance(s) of Context
-     *
-     * @param contexts
-     * @returns
-     */
-    extend(...contexts: Context[]): this;
-    /**
-     * Modify context with middleware
-     *
-     * @param middleware
-     * @returns
-     */
-    use(...middleware: ContextMiddleware[]): Promise<any>;
-    /**
-     * Validate context ensuring all validators are valid.
-     *
-     * @param validators
-     * @returns
-     */
-    validate(...validators: Validator<Context>[]): import('..').Validation<Context<any>>;
-    /**
-     * Validate context ensuring at least one validator is valid
-     * @param validators
-     * @returns
-     */
-    validateAny(...validators: Validator<Context>[]): import('..').Validation<any>;
-    /**
-     * Add a callback to listen for an event in this context.
-     *
-     * @param event
-     * @param listener
-     * @returns
-     */
-    on(event: string, listener: ContextListener): () => void;
-    /**
-     * Emit an event in this context
-     *
-     * @param event
-     * @param args
-     * @returns
-     */
-    emit(event: string): Promise<void>;
-}

package/dist/context/context.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/context/legacy-context.test.d.ts

@@ -1 +0,0 @@
-export {};