@declaro/core 2.0.0-beta.99 → 2.1.0

package/src/http/request-context.ts

@@ -1,7 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'http'
-import { Context, type ContextMiddleware, type DeclaroRequestScope, type DeclaroScope } from '../context/context'
-
-import type { RequestScope, AppScope } from '#scope'
+import { Context, type ContextMiddleware, type DeclaroScope } from '../context/context'
 
 /**
  * Get the request middleware for the current context.

package/src/index.ts

@@ -26,6 +26,7 @@ export * from './application/use-declaro'
 export * from './context/context'
 export * from './context/context-consumer'
 export * from './context/validators'
+export * from './context/async-context'
 export * from './dataflow'
 export * from './events'
 export * from './validation'
@@ -46,3 +47,4 @@ export * from './schema/schema-mixin'
 export * from './schema/test/mock-model'
 
 export * from './shared/utils/action-descriptor'
+export * from './shared/utils/schema-utils'

package/src/schema/json-schema.ts

@@ -1,3 +1,16 @@
 import { type JSONSchema7 } from 'json-schema'
 
-export interface JSONSchema extends JSONSchema7 {}
+export type JSONSchemaDefinition = JSONSchema | boolean
+
+export interface JSONMeta {
+    hidden?: boolean
+    private?: boolean
+}
+
+export interface JSONSchema extends JSONSchema7, JSONMeta {
+    properties?:
+        | {
+              [key: string]: JSONSchemaDefinition
+          }
+        | undefined
+}

package/src/schema/model-schema.test.ts

@@ -2,8 +2,9 @@ import { describe, expect, it } from 'vitest'
 import { z } from 'zod/v4'
 import { ModelSchema, type MergeMixins } from './model-schema'
 import { MockModel } from './test/mock-model'
-import type { InferModelOutput } from './model'
+import type { InferModelInput, InferModelOutput } from './model'
 import type { ShallowMerge, UniqueKeys } from '../typescript'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 describe('ModelSchema', () => {
     it('should create a ModelSchema instance', () => {
@@ -125,4 +126,157 @@ describe('ModelSchema', () => {
 
         expect(schema.getEntityMetadata().primaryKey).toBe('id')
     })
+
+    it('should be able to manually strip private and hidden keys from input', () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const payload: InferModelInput<typeof testModel> = {
+            id: '1',
+            name: 'Test',
+            secret: 'top-secret',
+            internalNote: 'for-internal-use-only',
+        }
+
+        const stripped = testModel.stripExcludedFields(payload)
+
+        expect(stripped).toEqual({
+            id: '1',
+            name: 'Test',
+            internalNote: 'for-internal-use-only',
+        })
+    })
+
+    it('should strip private fields from validation input', async () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const payload: InferModelInput<typeof testModel> = {
+            id: '1',
+            name: 'Test',
+            secret: 'top-secret',
+            internalNote: 'for-internal-use-only',
+        }
+
+        const validation = await testModel.validate(payload, { strict: false })
+
+        expect(validation.issues).toBeUndefined()
+
+        const output = (validation as StandardSchemaV1.SuccessResult<InferModelOutput<typeof testModel>>).value
+
+        expect(output.secret).toBeUndefined()
+    })
+
+    it('should not strip hidden fields from validation input', async () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const payload: InferModelInput<typeof testModel> = {
+            id: '1',
+            name: 'Test',
+            secret: 'top-secret',
+            internalNote: 'for-internal-use-only',
+        }
+
+        const validation = await testModel.validate(payload, { strict: false })
+
+        expect(validation.issues).toBeUndefined()
+
+        const output = (validation as StandardSchemaV1.SuccessResult<InferModelOutput<typeof testModel>>).value
+
+        expect(output.internalNote).toBe('for-internal-use-only')
+    })
+
+    it('should strip private fields from model schema by default', () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const jsonSchema = testModel.toJSONSchema()
+
+        expect(Object.keys(jsonSchema.properties!)).toEqual(['id', 'name', 'internalNote'])
+    })
+
+    it('should not strip hidden fields from model schema', () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const jsonSchema = testModel.toJSONSchema({ includePrivateFields: false })
+
+        expect(Object.keys(jsonSchema.properties!)).toEqual(['id', 'name', 'internalNote'])
+    })
+
+    it('should not strip private fields from model schema when specified', () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const jsonSchema = testModel.toJSONSchema({ includePrivateFields: true })
+
+        expect(Object.keys(jsonSchema.properties!)).toEqual(['id', 'name', 'secret', 'internalNote'])
+    })
+
+    it('should include hidden fields in model schema when specified', () => {
+        const testModel = new MockModel(
+            'TestModel',
+            z.object({
+                id: z.string(),
+                name: z.string(),
+                secret: z.string().optional().meta({ private: true }),
+                internalNote: z.string().optional().meta({ hidden: true }),
+            }),
+        )
+
+        const jsonSchema = testModel.toJSONSchema()
+
+        expect(Object.keys(jsonSchema.properties!)).toEqual(['id', 'name', 'internalNote'])
+
+        const internalNoteSchema = jsonSchema.properties?.['internalNote']
+
+        if (typeof internalNoteSchema === 'object') {
+            expect(internalNoteSchema.hidden).toBe(true)
+        } else {
+            throw new Error('internalNote schema is not an object')
+        }
+    })
 })

package/src/schema/model.ts

@@ -7,6 +7,16 @@ export interface ModelValidationOptions {
     strict?: boolean
 }
 
+export interface ModelSchemaOptions {
+    includePrivateFields?: boolean
+}
+
+export function getDefaultModelSchemaOptions(): ModelSchemaOptions {
+    return {
+        includePrivateFields: false,
+    }
+}
+
 export abstract class Model<TName extends Readonly<string>, TSchema extends StandardSchemaV1>
     implements StandardSchemaV1<StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>
 {
@@ -27,15 +37,36 @@ export abstract class Model<TName extends Readonly<string>, TSchema extends Stan
         this.schema = schema
     }
 
+    stripExcludedFields(value: StandardSchemaV1.InferInput<TSchema>): StandardSchemaV1.InferInput<TSchema> {
+        const meta = this.toJSONSchema({
+            includePrivateFields: true,
+        })
+
+        const excludedKeys = Object.keys(meta.properties ?? {}).filter((key) => {
+            const property = meta.properties?.[key]
+            return !!property && typeof property === 'object' && property.private === true
+        })
+
+        if (value && excludedKeys.length > 0) {
+            excludedKeys.forEach((key) => {
+                delete value[key]
+            })
+        }
+
+        return value
+    }
+
     async validate(
         value: StandardSchemaV1.InferInput<TSchema>,
         options?: ModelValidationOptions,
     ): Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>> {
+        const meta = this.toJSONSchema()
+
+        value = this.stripExcludedFields(value)
+
         const result = await this.schema['~standard'].validate(value)
 
         if (result.issues) {
-            const meta = this.toJSONSchema()
-
             const issues = result.issues.map((issue) => {
                 let schema: JSONSchema | undefined = meta
                 let field: string | undefined = undefined
@@ -82,7 +113,7 @@ export abstract class Model<TName extends Readonly<string>, TSchema extends Stan
         return getLabels(this.name)
     }
 
-    abstract toJSONSchema(): JSONSchema
+    abstract toJSONSchema(options?: ModelSchemaOptions): JSONSchema
 
     // Implementing StandardSchemaV1 interface
     get version(): number {

package/src/schema/test/mock-model.ts

@@ -1,15 +1,19 @@
 import { z } from 'zod/v4'
 import type { $ZodType } from 'zod/v4/core'
 import type { JSONSchema } from '../json-schema'
-import { Model } from '../model'
+import { Model, type ModelSchemaOptions } from '../model'
+import { stripPrivateFieldsFromSchema } from '../../shared/utils/schema-utils'
 
 export class MockModel<TName extends Readonly<string>, TSchema extends $ZodType<any>> extends Model<TName, TSchema> {
     constructor(name: TName, schema: TSchema) {
         super(name, schema)
     }
 
-    toJSONSchema(): JSONSchema {
+    toJSONSchema(options?: ModelSchemaOptions): JSONSchema {
         const jsonSchema = z.toJSONSchema(this.schema)
+        if (options?.includePrivateFields !== true) {
+            stripPrivateFieldsFromSchema(jsonSchema as JSONSchema)
+        }
         return jsonSchema as JSONSchema
     }
 }

package/src/shared/utils/schema-utils.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import type { JSONSchema } from '../../schema/json-schema'
+import { stripPrivateFieldsFromSchema } from './schema-utils'
+
+describe('Schema Utils', () => {
+    it('should strip private fields from schema', () => {
+        const schema: JSONSchema = {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                secret: { type: 'string', private: true },
+                internalNote: { type: 'string', hidden: true },
+            },
+        }
+
+        const stripped = stripPrivateFieldsFromSchema(schema)
+
+        // The return value should have the private field removed
+        expect(stripped.properties).toBeDefined()
+        expect(stripped.properties?.['id']).toBeDefined()
+        expect(stripped.properties?.['name']).toBeDefined()
+        expect(stripped.properties?.['secret']).toBeUndefined()
+        expect(stripped.properties?.['internalNote']).toBeDefined()
+
+        // The original schema should also have the private field removed
+        expect(schema.properties).toBeDefined()
+        expect(schema.properties?.['id']).toBeDefined()
+        expect(schema.properties?.['name']).toBeDefined()
+        expect(schema.properties?.['secret']).toBeUndefined()
+        expect(schema.properties?.['internalNote']).toBeDefined()
+    })
+})

package/src/shared/utils/schema-utils.ts

@@ -0,0 +1,17 @@
+import type { JSONSchema } from '../../schema/json-schema'
+
+export function stripPrivateFieldsFromSchema(schema: JSONSchema): JSONSchema {
+    if (typeof schema?.properties === 'object') {
+        for (const key of Object.keys(schema.properties)) {
+            const property = schema.properties[key]
+            if (typeof property === 'object') {
+                if (property.private === true) {
+                    delete schema.properties[key]
+                } else {
+                    stripPrivateFieldsFromSchema(property)
+                }
+            }
+        }
+    }
+    return schema
+}

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)
+    }
+}