@frontmcp/sdk 0.2.5 → 0.3.1

package/src/transport/transport.registry.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransportService = void 0;
+const tslib_1 = require("tslib");
+// server/transport/transport.registry.ts
+const crypto_1 = require("crypto");
+const transport_remote_1 = require("./transport.remote");
+const transport_local_1 = require("./transport.local");
+const handle_streamable_http_flow_1 = tslib_1.__importDefault(require("./flows/handle.streamable-http.flow"));
+const handle_sse_flow_1 = tslib_1.__importDefault(require("./flows/handle.sse.flow"));
+class TransportService {
+    ready;
+    byType = new Map();
+    distributed;
+    bus;
+    scope;
+    constructor(scope) {
+        this.scope = scope;
+        this.distributed = false; // get from scope metadata
+        this.bus = undefined; // get from scope metadata
+        if (this.distributed && !this.bus) {
+            throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');
+        }
+        this.ready = this.initialize();
+    }
+    async initialize() {
+        await this.scope.registryFlows(handle_streamable_http_flow_1.default, handle_sse_flow_1.default);
+    }
+    async destroy() {
+        /* empty */
+    }
+    async getTransporter(type, token, sessionId) {
+        const key = this.keyOf(type, token, sessionId);
+        const local = this.lookupLocal(key);
+        if (local)
+            return local;
+        if (this.distributed && this.bus) {
+            const location = await this.bus.lookup(key);
+            if (location) {
+                return new transport_remote_1.RemoteTransporter(key, this.bus);
+            }
+        }
+        return undefined;
+    }
+    async createTransporter(type, token, sessionId, res) {
+        const key = this.keyOf(type, token, sessionId);
+        const existing = this.lookupLocal(key);
+        if (existing)
+            return existing;
+        const transporter = new transport_local_1.LocalTransporter(this.scope, key, res, () => {
+            key.sessionId = sessionId;
+            this.evictLocal(key);
+            if (this.distributed && this.bus) {
+                this.bus.revoke(key).catch(() => void 0);
+            }
+        });
+        await transporter.ready();
+        this.insertLocal(key, transporter);
+        if (this.distributed && this.bus) {
+            await this.bus.advertise(key);
+        }
+        return transporter;
+    }
+    async destroyTransporter(type, token, sessionId, reason) {
+        const key = this.keyOf(type, token, sessionId);
+        const local = this.lookupLocal(key);
+        if (local) {
+            await local.destroy(reason);
+            return;
+        }
+        if (this.distributed && this.bus) {
+            const location = await this.bus.lookup(key);
+            if (location) {
+                await this.bus.destroyRemote(key, reason);
+                return;
+            }
+        }
+        throw new Error('Invalid session: cannot destroy non-existent transporter.');
+    }
+    /* --------------------------------- internals -------------------------------- */
+    sha256(value) {
+        return (0, crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+    }
+    keyOf(type, token, sessionId, sessionIdSse) {
+        return {
+            type,
+            token,
+            tokenHash: this.sha256(token),
+            sessionId,
+            sessionIdSse,
+        };
+    }
+    ensureTypeBucket(type) {
+        let bucket = this.byType.get(type);
+        if (!bucket) {
+            bucket = new Map();
+            this.byType.set(type, bucket);
+        }
+        return bucket;
+    }
+    ensureTokenBucket(typeBucket, tokenHash) {
+        let bucket = typeBucket.get(tokenHash);
+        if (!bucket) {
+            bucket = new Map();
+            typeBucket.set(tokenHash, bucket);
+        }
+        return bucket;
+    }
+    lookupLocal(key) {
+        const typeBucket = this.byType.get(key.type);
+        if (!typeBucket)
+            return undefined;
+        const tokenBucket = typeBucket.get(key.tokenHash);
+        if (!tokenBucket)
+            return undefined;
+        return tokenBucket.get(key.sessionId);
+    }
+    insertLocal(key, t) {
+        const typeBucket = this.ensureTypeBucket(key.type);
+        const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);
+        tokenBucket.set(key.sessionId, t);
+    }
+    evictLocal(key) {
+        const typeBucket = this.byType.get(key.type);
+        if (!typeBucket)
+            return;
+        const tokenBucket = typeBucket.get(key.tokenHash);
+        if (!tokenBucket)
+            return;
+        tokenBucket.delete(key.sessionId);
+        if (tokenBucket.size === 0)
+            typeBucket.delete(key.tokenHash);
+        if (typeBucket.size === 0)
+            this.byType.delete(key.type);
+    }
+}
+exports.TransportService = TransportService;
+//# sourceMappingURL=transport.registry.js.map

package/src/transport/transport.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.registry.js","sourceRoot":"","sources":["../../../src/transport/transport.registry.ts"],"names":[],"mappings":"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","sourcesContent":["// server/transport/transport.registry.ts\nimport {createHash} from 'crypto';\nimport {\n  TransportBus,\n  Transporter,\n  TransportKey,\n  TransportRegistryBucket,\n  TransportTokenBucket,\n  TransportType,\n  TransportTypeBucket,\n} from './transport.types';\nimport {RemoteTransporter} from './transport.remote';\nimport {LocalTransporter} from './transport.local';\nimport {ServerResponse} from '../common';\nimport {Scope} from '../scope';\nimport HandleStreamableHttpFlow from './flows/handle.streamable-http.flow';\nimport HandleSseFlow from './flows/handle.sse.flow';\n\nexport class TransportService {\n  readonly ready: Promise<void>;\n  private readonly byType: TransportRegistryBucket = new Map();\n  private readonly distributed: boolean;\n  private readonly bus?: TransportBus;\n  private readonly scope: Scope;\n\n  constructor(scope: Scope) {\n    this.scope = scope;\n    this.distributed = false; // get from scope metadata\n    this.bus = undefined; // get from scope metadata\n    if (this.distributed && !this.bus) {\n      throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');\n    }\n\n    this.ready = this.initialize();\n\n  }\n\n\n  private async initialize() {\n    await this.scope.registryFlows(\n      HandleStreamableHttpFlow,\n      HandleSseFlow,\n    );\n  }\n\n  async destroy() {\n    /* empty */\n  }\n\n  async getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) return local;\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        return new RemoteTransporter(key, this.bus);\n      }\n    }\n\n    return undefined;\n  }\n\n  async createTransporter(\n    type: TransportType,\n    token: string,\n    sessionId: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, sessionId);\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      key.sessionId = sessionId;\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  async destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) {\n      await local.destroy(reason);\n      return;\n    }\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        await this.bus.destroyRemote(key, reason);\n        return;\n      }\n    }\n\n    throw new Error('Invalid session: cannot destroy non-existent transporter.');\n  }\n\n  /* --------------------------------- internals -------------------------------- */\n\n  private sha256(value: string): string {\n    return createHash('sha256').update(value, 'utf8').digest('hex');\n  }\n\n  private keyOf(type: TransportType, token: string, sessionId: string, sessionIdSse?: string): TransportKey {\n    return {\n      type,\n      token,\n      tokenHash: this.sha256(token),\n      sessionId,\n      sessionIdSse,\n    };\n  }\n\n  private ensureTypeBucket(type: TransportType): TransportTypeBucket {\n    let bucket = this.byType.get(type);\n    if (!bucket) {\n      bucket = new Map<string, TransportTokenBucket>();\n      this.byType.set(type, bucket);\n    }\n    return bucket;\n  }\n\n  private ensureTokenBucket(typeBucket: TransportTypeBucket, tokenHash: string): TransportTokenBucket {\n    let bucket = typeBucket.get(tokenHash);\n    if (!bucket) {\n      bucket = new Map<string, Transporter>();\n      typeBucket.set(tokenHash, bucket);\n    }\n    return bucket;\n  }\n\n\n  private lookupLocal(key: TransportKey): Transporter | undefined {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return undefined;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return undefined;\n    return tokenBucket.get(key.sessionId);\n  }\n\n  private insertLocal(key: TransportKey, t: Transporter): void {\n    const typeBucket = this.ensureTypeBucket(key.type);\n    const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);\n    tokenBucket.set(key.sessionId, t);\n  }\n\n  private evictLocal(key: TransportKey): void {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return;\n    tokenBucket.delete(key.sessionId);\n    if (tokenBucket.size === 0) typeBucket.delete(key.tokenHash);\n    if (typeBucket.size === 0) this.byType.delete(key.type);\n  }\n}\n"]}

package/src/transport/transport.remote.d.ts

@@ -0,0 +1,15 @@
+import { TransportBus, Transporter, TransportKey, TransportType } from './transport.types';
+import { AuthenticatedServerRequest } from '../server/server.types';
+import { ServerResponse } from '../common';
+export declare class RemoteTransporter implements Transporter {
+    private readonly key;
+    private readonly bus;
+    readonly type: TransportType;
+    readonly tokenHash: string;
+    readonly sessionId: string;
+    constructor(key: TransportKey, bus: TransportBus);
+    ping(timeoutMs?: number): Promise<boolean>;
+    initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
+    handleRequest(_req: AuthenticatedServerRequest, _res: ServerResponse): Promise<void>;
+    destroy(_reason?: string): Promise<void>;
+}

package/src/transport/transport.remote.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteTransporter = void 0;
+class RemoteTransporter {
+    key;
+    bus;
+    type;
+    tokenHash;
+    sessionId;
+    constructor(key, bus) {
+        this.key = key;
+        this.bus = bus;
+        this.type = key.type;
+        this.tokenHash = key.tokenHash;
+        this.sessionId = key.sessionId;
+    }
+    ping(timeoutMs) {
+        throw new Error('Method not implemented.');
+    }
+    initialize(req, res) {
+        throw new Error('Method not implemented.');
+    }
+    async handleRequest(_req, _res) {
+        throw new Error('RemoteTransporter: handleRequest() not implemented.');
+    }
+    async destroy(_reason) {
+        throw new Error('RemoteTransporter: destroy() not implemented.');
+    }
+}
+exports.RemoteTransporter = RemoteTransporter;
+//# sourceMappingURL=transport.remote.js.map

package/src/transport/transport.remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.remote.js","sourceRoot":"","sources":["../../../src/transport/transport.remote.ts"],"names":[],"mappings":";;;AAIA,MAAa,iBAAiB;IAKC;IAAoC;IAJxD,IAAI,CAAgB;IACpB,SAAS,CAAS;IAClB,SAAS,CAAS;IAE3B,YAA6B,GAAiB,EAAmB,GAAiB;QAArD,QAAG,GAAH,GAAG,CAAc;QAAmB,QAAG,GAAH,GAAG,CAAc;QAChF,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,SAAkB;QACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CAAC,GAA+B,EAAE,GAAmB;QAC7D,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAgC,EAAE,IAAoB;QACxE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAgB;QAC5B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;CACF;AAzBD,8CAyBC","sourcesContent":["import { TransportBus, Transporter, TransportKey, TransportType } from './transport.types';\nimport { AuthenticatedServerRequest } from '../server/server.types';\nimport { ServerResponse } from '../common';\n\nexport class RemoteTransporter implements Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  constructor(private readonly key: TransportKey, private readonly bus: TransportBus) {\n    this.type = key.type;\n    this.tokenHash = key.tokenHash;\n    this.sessionId = key.sessionId;\n  }\n  ping(timeoutMs?: number): Promise<boolean> {\n    throw new Error('Method not implemented.');\n  }\n\n  initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void> {\n    throw new Error('Method not implemented.');\n  }\n\n  async handleRequest(_req: AuthenticatedServerRequest, _res: ServerResponse): Promise<void> {\n    throw new Error('RemoteTransporter: handleRequest() not implemented.');\n  }\n\n  async destroy(_reason?: string): Promise<void> {\n    throw new Error('RemoteTransporter: destroy() not implemented.');\n  }\n}\n"]}

package/src/transport/transport.types.d.ts

@@ -0,0 +1,54 @@
+import { AuthenticatedServerRequest } from '../server/server.types';
+import { ElicitResult } from '@modelcontextprotocol/sdk/types.js';
+import { ZodObject } from 'zod';
+import { Infer } from '../utils/types.utils';
+import { ServerResponse } from '../common';
+export type TransportType = 'sse' | 'streamable-http' | 'http';
+export interface TransportKey {
+    type: TransportType;
+    token: string;
+    tokenHash: string;
+    sessionId: string;
+    sessionIdSse?: string;
+}
+export interface RemoteLocation {
+    nodeId: string;
+    channel: string;
+}
+export interface TransportBus {
+    nodeId(): string;
+    advertise(key: TransportKey): Promise<void>;
+    revoke(key: TransportKey): Promise<void>;
+    lookup(key: TransportKey): Promise<RemoteLocation | null>;
+    proxyRequest(key: TransportKey, payload: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+    }, io: {
+        onResponseStart(statusCode: number, headers: Record<string, string>): void;
+        onResponseChunk(chunk: Uint8Array | string): void;
+        onResponseEnd(finalChunk?: Uint8Array | string): void;
+        onError?(err: Error | string): void;
+    }): Promise<void>;
+    destroyRemote(key: TransportKey, reason?: string): Promise<void>;
+}
+export interface Transporter {
+    readonly type: TransportType;
+    readonly tokenHash: string;
+    readonly sessionId: string;
+    initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
+    handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
+    destroy(reason?: string): Promise<void>;
+    ping(timeoutMs?: number): Promise<boolean>;
+}
+export interface TransportRegistryOptions {
+    distributed?: boolean;
+    bus?: TransportBus;
+}
+export type TransportTokenBucket = Map<string, Transporter>;
+export type TransportTypeBucket = Map<string, TransportTokenBucket>;
+export type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>;
+export type TypedElicitResult<T extends ZodObject<any>> = {
+    action: ElicitResult['action'];
+    content: Infer<T>;
+};

package/src/transport/transport.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transport.types.js.map

package/src/transport/transport.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.types.js","sourceRoot":"","sources":["../../../src/transport/transport.types.ts"],"names":[],"mappings":"","sourcesContent":["import { AuthenticatedServerRequest } from '../server/server.types';\nimport { ElicitResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ZodObject } from 'zod';\nimport { Infer } from '../utils/types.utils';\nimport { ServerResponse } from '../common';\n\nexport type TransportType = 'sse' | 'streamable-http' | 'http';\n\nexport interface TransportKey {\n  type: TransportType;\n  token: string;\n  tokenHash: string;\n  sessionId: string;\n  sessionIdSse?: string;\n}\n\nexport interface RemoteLocation {\n  nodeId: string;\n  channel: string;\n}\n\nexport interface TransportBus {\n  nodeId(): string;\n\n  advertise(key: TransportKey): Promise<void>;\n\n  revoke(key: TransportKey): Promise<void>;\n\n  lookup(key: TransportKey): Promise<RemoteLocation | null>;\n\n  proxyRequest(\n    key: TransportKey,\n    payload: {\n      method?: string;\n      url?: string;\n      headers?: Record<string, string | string[] | undefined>;\n    },\n    io: {\n      onResponseStart(statusCode: number, headers: Record<string, string>): void;\n      onResponseChunk(chunk: Uint8Array | string): void;\n      onResponseEnd(finalChunk?: Uint8Array | string): void;\n      onError?(err: Error | string): void;\n    },\n  ): Promise<void>;\n\n  destroyRemote(key: TransportKey, reason?: string): Promise<void>;\n}\n\n/* --------------------------------- API ---------------------------------- */\n\nexport interface Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  destroy(reason?: string): Promise<void>;\n\n  ping(timeoutMs?: number): Promise<boolean>;\n}\n\nexport interface TransportRegistryOptions {\n  distributed?: boolean;\n  bus?: TransportBus;\n}\n\nexport type TransportTokenBucket = Map<string, Transporter>; // sessionHash -> Transporter\nexport type TransportTypeBucket = Map<string, TransportTokenBucket>; // tokenHash   -> TokenBucket\nexport type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>; // tokenHash   -> TokenBucket\n\nexport type TypedElicitResult<T extends ZodObject<any>> = { action: ElicitResult['action']; content: Infer<T> };\n"]}

package/src/types/drinen-hooks.types.d.ts

@@ -0,0 +1,20 @@
+import { Type } from '../common';
+export type AnyStage = string & {};
+export interface GenericHook<Ctx = unknown> {
+    providedBy: string;
+    priority?(): number;
+    filter?(ctx: Ctx): boolean | Promise<boolean>;
+    aroundExecute?: (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;
+    [stage: string]: any;
+}
+export interface CollectHooksFn<Ctx> {
+    (stage: AnyStage, options: {
+        resolve: <T>(cls: any) => T;
+        globalHooksByStage?: Partial<Record<AnyStage, Type[]>>;
+        localHooksByStage?: Partial<Record<AnyStage, Type[]>>;
+        ctx: Ctx;
+        owner?: {
+            name?: string;
+        };
+    }): Promise<GenericHook<Ctx>[]>;
+}

package/src/types/drinen-hooks.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=drinen-hooks.types.js.map

package/src/types/drinen-hooks.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drinen-hooks.types.js","sourceRoot":"","sources":["../../../src/types/drinen-hooks.types.ts"],"names":[],"mappings":"","sourcesContent":["import { Type } from '../common';\n\nexport type AnyStage = string & {};\n\n\nexport interface GenericHook<Ctx = unknown> {\n  providedBy: string;\n  priority?(): number;\n  filter?(ctx: Ctx): boolean | Promise<boolean>;\n  aroundExecute?: (ctx: Ctx, next: () => Promise<unknown>) => Promise<unknown>;\n  [stage: string]: any; // stage handler methods (will*/did*/on*)\n}\n\nexport interface CollectHooksFn<Ctx> {\n  (\n    stage: AnyStage,\n    options: {\n      resolve: <T>(cls: any) => T;\n      globalHooksByStage?: Partial<Record<AnyStage, Type[]>>;\n      localHooksByStage?: Partial<Record<AnyStage, Type[]>>;\n      ctx: Ctx;\n      owner?: { name?: string };\n    },\n  ): Promise<GenericHook<Ctx>[]>;\n}\n"]}

package/src/types/invoke.type.d.ts

@@ -0,0 +1,15 @@
+export declare class ControlRespond extends Error {
+    value: unknown;
+    constructor(value: unknown);
+}
+export declare class ControlAbort extends Error {
+    reason: string;
+    code?: string | undefined;
+    httpStatus?: number | undefined;
+    constructor(reason: string, code?: string | undefined, httpStatus?: number | undefined);
+}
+export declare class ControlRetryAfter extends Error {
+    ms: number;
+    reason?: string | undefined;
+    constructor(ms: number, reason?: string | undefined);
+}

package/src/types/invoke.type.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlRetryAfter = exports.ControlAbort = exports.ControlRespond = void 0;
+class ControlRespond extends Error {
+    value;
+    constructor(value) {
+        super('CONTROL_RESPOND');
+        this.value = value;
+    }
+}
+exports.ControlRespond = ControlRespond;
+class ControlAbort extends Error {
+    reason;
+    code;
+    httpStatus;
+    constructor(reason, code, httpStatus) {
+        super('CONTROL_ABORT');
+        this.reason = reason;
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+exports.ControlAbort = ControlAbort;
+class ControlRetryAfter extends Error {
+    ms;
+    reason;
+    constructor(ms, reason) {
+        super('CONTROL_RETRY_AFTER');
+        this.ms = ms;
+        this.reason = reason;
+    }
+}
+exports.ControlRetryAfter = ControlRetryAfter;
+//# sourceMappingURL=invoke.type.js.map

package/src/types/invoke.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.type.js","sourceRoot":"","sources":["../../../src/types/invoke.type.ts"],"names":[],"mappings":";;;AAAA,MAAa,cAAe,SAAQ,KAAK;IACpB;IAAnB,YAAmB,KAAc;QAC/B,KAAK,CAAC,iBAAiB,CAAC,CAAC;QADR,UAAK,GAAL,KAAK,CAAS;IAEjC,CAAC;CACF;AAJD,wCAIC;AACD,MAAa,YAAa,SAAQ,KAAK;IAE5B;IACA;IACA;IAHT,YACS,MAAc,EACd,IAAa,EACb,UAAmB;QAE1B,KAAK,CAAC,eAAe,CAAC,CAAC;QAJhB,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QACb,eAAU,GAAV,UAAU,CAAS;IAG5B,CAAC;CACF;AARD,oCAQC;AACD,MAAa,iBAAkB,SAAQ,KAAK;IACvB;IAAmB;IAAtC,YAAmB,EAAU,EAAS,MAAe;QACnD,KAAK,CAAC,qBAAqB,CAAC,CAAC;QADZ,OAAE,GAAF,EAAE,CAAQ;QAAS,WAAM,GAAN,MAAM,CAAS;IAErD,CAAC;CACF;AAJD,8CAIC","sourcesContent":["export class ControlRespond extends Error {\n  constructor(public value: unknown) {\n    super('CONTROL_RESPOND');\n  }\n}\nexport class ControlAbort extends Error {\n  constructor(\n    public reason: string,\n    public code?: string,\n    public httpStatus?: number\n  ) {\n    super('CONTROL_ABORT');\n  }\n}\nexport class ControlRetryAfter extends Error {\n  constructor(public ms: number, public reason?: string) {\n    super('CONTROL_RETRY_AFTER');\n  }\n}\n"]}

package/src/types/token.types.d.ts

@@ -0,0 +1 @@
+export type Ctor<T> = new (...args: any[]) => T;

package/src/types/token.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=token.types.js.map

package/src/types/token.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.types.js","sourceRoot":"","sources":["../../../src/types/token.types.ts"],"names":[],"mappings":"","sourcesContent":["import { Type } from '../common';\n\nexport type Ctor<T> = new (...args: any[]) => T;\n"]}

package/src/utils/metadata.utils.d.ts

@@ -0,0 +1,5 @@
+import 'reflect-metadata';
+import { Type } from '../common';
+export declare function getMetadata<T = any>(key: any, target: any, propertyKey?: string | symbol): T | undefined;
+export declare function setMetadata(key: any, value: any, target: any, propertyKey?: string | symbol): void;
+export declare function hasAsyncWith(klass: Type<any>): boolean;

package/src/utils/metadata.utils.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetadata = getMetadata;
+exports.setMetadata = setMetadata;
+exports.hasAsyncWith = hasAsyncWith;
+require("reflect-metadata");
+const common_1 = require("../common");
+function getMetadata(key, target, propertyKey) {
+    // Reflect.getMetadata is provided by reflect-metadata polyfill
+    return (propertyKey !== undefined)
+        ? Reflect.getMetadata(key, target, propertyKey)
+        : Reflect.getMetadata(key, target);
+}
+function setMetadata(key, value, target, propertyKey) {
+    if (propertyKey !== undefined) {
+        Reflect.defineMetadata(key, value, target, propertyKey);
+    }
+    else {
+        Reflect.defineMetadata(key, value, target);
+    }
+}
+function hasAsyncWith(klass) {
+    return (!!getMetadata(common_1.META_ASYNC_WITH, klass) &&
+        typeof klass.with === 'function');
+}
+//# sourceMappingURL=metadata.utils.js.map

package/src/utils/metadata.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.utils.js","sourceRoot":"","sources":["../../../src/utils/metadata.utils.ts"],"names":[],"mappings":";;AAGA,kCAKC;AAED,kCAMC;AAED,oCAKC;AAvBD,4BAA0B;AAC1B,sCAAkD;AAElD,SAAgB,WAAW,CAAU,GAAQ,EAAE,MAAW,EAAE,WAA6B;IACvF,+DAA+D;IAC/D,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC;QAChC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC;QAC/C,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,SAAgB,WAAW,CAAC,GAAQ,EAAE,KAAU,EAAE,MAAW,EAAE,WAA6B;IAC1F,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAe,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACnE,CAAC;SAAM,CAAC;QACL,OAAe,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,SAAiB,YAAY,CAAC,KAAgB;IAC5C,OAAO,CACL,CAAC,CAAC,WAAW,CAAC,wBAAe,EAAE,KAAK,CAAC;QACrC,OAAQ,KAAa,CAAC,IAAI,KAAK,UAAU,CAC1C,CAAC;AACJ,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { META_ASYNC_WITH, Type } from '../common';\n\nexport function getMetadata<T = any>(key: any, target: any, propertyKey?: string | symbol): T | undefined {\n  // Reflect.getMetadata is provided by reflect-metadata polyfill\n  return (propertyKey !== undefined)\n    ? Reflect.getMetadata(key, target, propertyKey)\n    : Reflect.getMetadata(key, target);\n}\n\nexport function setMetadata(key: any, value: any, target: any, propertyKey?: string | symbol): void {\n  if (propertyKey !== undefined) {\n    (Reflect as any).defineMetadata(key, value, target, propertyKey);\n  } else {\n    (Reflect as any).defineMetadata(key, value, target);\n  }\n}\n\nexport function  hasAsyncWith(klass: Type<any>): boolean {\n  return (\n    !!getMetadata(META_ASYNC_WITH, klass) &&\n    typeof (klass as any).with === 'function'\n  );\n}\n"]}

package/src/utils/server.utils.d.ts

@@ -0,0 +1,19 @@
+import { ServerRequest, ServerRequestHandler, ServerResponse } from '../common';
+type Runner<T> = (req: ServerRequest) => Promise<T> | T;
+type SuccessWriter<T> = (res: ServerResponse, result: T) => void | Promise<void>;
+type ErrorWriter = (res: ServerResponse, err: any) => void | Promise<void>;
+export declare function withResponseHandler<T>(runner: Runner<T>): {
+    /** Set the success writer; chainable. */
+    success(fn: SuccessWriter<T>): /*elided*/ any;
+    /**
+     * Set the error writer and finalize into a ServerHookHandler.
+     * Calling this returns the Express-like/host handler.
+     */
+    fail(fn: ErrorWriter): ServerRequestHandler;
+    /**
+     * If you prefer not to end with .fail(), you can call .build() after setting .success().
+     * It will use the default error writer unless overridden via .fail() earlier.
+     */
+    build(): ServerRequestHandler;
+};
+export {};

package/src/utils/server.utils.js

@@ -0,0 +1,59 @@
+"use strict";
+// utils/with-response-handler.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withResponseHandler = withResponseHandler;
+function withResponseHandler(runner) {
+    let onSuccess = (res, result) => {
+        throw new Error('No success writer set');
+    };
+    let onError = (res, err) => {
+        const status = typeof err?.status === 'number' ? err.status : 500;
+        const code = err?.code ?? 'server_error';
+        const message = typeof err?.message === 'string' ? err.message : 'internal error';
+        res.status(status);
+        res.setHeader('Content-Type', 'application/json');
+        res.json({ error: code, message });
+    };
+    const builder = {
+        /** Set the success writer; chainable. */
+        success(fn) {
+            onSuccess = fn;
+            return builder;
+        },
+        /**
+         * Set the error writer and finalize into a ServerHookHandler.
+         * Calling this returns the Express-like/host handler.
+         */
+        fail(fn) {
+            onError = fn;
+            const handler = async (req, res) => {
+                try {
+                    const result = await Promise.resolve(runner(req));
+                    await onSuccess(res, result);
+                }
+                catch (err) {
+                    await onError(res, err);
+                }
+            };
+            return handler;
+        },
+        /**
+         * If you prefer not to end with .fail(), you can call .build() after setting .success().
+         * It will use the default error writer unless overridden via .fail() earlier.
+         */
+        build() {
+            const handler = async (req, res) => {
+                try {
+                    const result = await Promise.resolve(runner(req));
+                    await onSuccess(res, result);
+                }
+                catch (err) {
+                    await onError(res, err);
+                }
+            };
+            return handler;
+        },
+    };
+    return builder;
+}
+//# sourceMappingURL=server.utils.js.map

package/src/utils/server.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.utils.js","sourceRoot":"","sources":["../../../src/utils/server.utils.ts"],"names":[],"mappings":";AAAA,iCAAiC;;AAQjC,kDAwDC;AAxDD,SAAgB,mBAAmB,CAAI,MAAiB;IACtD,IAAI,SAAS,GAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;QAChD,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,IAAI,OAAO,GAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,OAAO,GAAG,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;QAClE,MAAM,IAAI,GAAG,GAAG,EAAE,IAAI,IAAI,cAAc,CAAC;QACzC,MAAM,OAAO,GAAG,OAAO,GAAG,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAClF,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACnB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;QAClD,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG;QACd,yCAAyC;QACzC,OAAO,CAAC,EAAoB;YAC1B,SAAS,GAAG,EAAE,CAAC;YACf,OAAO,OAAO,CAAC;QACjB,CAAC;QAED;;;WAGG;QACH,IAAI,CAAC,EAAe;YAClB,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAyB,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;gBACvD,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;oBAClD,MAAM,SAAS,CAAC,GAAG,EAAE,MAAW,CAAC,CAAC;gBACpC,CAAC;gBAAC,OAAO,GAAQ,EAAE,CAAC;oBAClB,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QAED;;;WAGG;QACH,KAAK;YACH,MAAM,OAAO,GAAyB,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;gBACvD,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;oBAClD,MAAM,SAAS,CAAC,GAAG,EAAE,MAAW,CAAC,CAAC;gBACpC,CAAC;gBAAC,OAAO,GAAQ,EAAE,CAAC;oBAClB,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["// utils/with-response-handler.ts\n\nimport { ServerRequest, ServerRequestHandler, ServerResponse } from '../common';\n\ntype Runner<T> = (req: ServerRequest) => Promise<T> | T;\ntype SuccessWriter<T> = (res: ServerResponse, result: T) => void | Promise<void>;\ntype ErrorWriter = (res: ServerResponse, err: any) => void | Promise<void>;\n\nexport function withResponseHandler<T>(runner: Runner<T>) {\n  let onSuccess: SuccessWriter<T> = (res, result) => {\n    throw new Error('No success writer set');\n  };\n\n  let onError: ErrorWriter = (res, err) => {\n    const status = typeof err?.status === 'number' ? err.status : 500;\n    const code = err?.code ?? 'server_error';\n    const message = typeof err?.message === 'string' ? err.message : 'internal error';\n    res.status(status);\n    res.setHeader('Content-Type', 'application/json');\n    res.json({ error: code, message });\n  };\n\n  const builder = {\n    /** Set the success writer; chainable. */\n    success(fn: SuccessWriter<T>) {\n      onSuccess = fn;\n      return builder;\n    },\n\n    /**\n     * Set the error writer and finalize into a ServerHookHandler.\n     * Calling this returns the Express-like/host handler.\n     */\n    fail(fn: ErrorWriter): ServerRequestHandler {\n      onError = fn;\n      const handler: ServerRequestHandler = async (req, res) => {\n        try {\n          const result = await Promise.resolve(runner(req));\n          await onSuccess(res, result as T);\n        } catch (err: any) {\n          await onError(res, err);\n        }\n      };\n      return handler;\n    },\n\n    /**\n     * If you prefer not to end with .fail(), you can call .build() after setting .success().\n     * It will use the default error writer unless overridden via .fail() earlier.\n     */\n    build(): ServerRequestHandler {\n      const handler: ServerRequestHandler = async (req, res) => {\n        try {\n          const result = await Promise.resolve(runner(req));\n          await onSuccess(res, result as T);\n        } catch (err: any) {\n          await onError(res, err);\n        }\n      };\n      return handler;\n    },\n  };\n\n  return builder;\n}\n"]}

package/src/utils/string.utils.d.ts

@@ -0,0 +1 @@
+export declare function idFromString(name: string): string;

package/src/utils/string.utils.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.idFromString = idFromString;
+function idFromString(name) {
+    // Replace any invalid run with '-'
+    let cleaned = name.replace(/[^A-Za-z0-9_-]+/g, '-');
+    // Trim to max length and remove leading/trailing hyphens produced by cleaning
+    return cleaned.replace(/^-+|-+$/g, '').slice(0, 64);
+}
+//# sourceMappingURL=string.utils.js.map

package/src/utils/string.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.utils.js","sourceRoot":"","sources":["../../../src/utils/string.utils.ts"],"names":[],"mappings":";;AAAA,oCAKC;AALD,SAAgB,YAAY,CAAC,IAAY;IACvC,mCAAmC;IACnC,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACpD,8EAA8E;IAC9E,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC","sourcesContent":["export function idFromString(name: string): string {\n  // Replace any invalid run with '-'\n  let cleaned = name.replace(/[^A-Za-z0-9_-]+/g, '-');\n  // Trim to max length and remove leading/trailing hyphens produced by cleaning\n  return cleaned.replace(/^-+|-+$/g, '').slice(0, 64);\n}"]}

package/src/utils/token.utils.d.ts

@@ -0,0 +1,11 @@
+import { Token, Type } from '../common';
+export declare const tokenName: (t: Token) => string;
+export declare const isClass: (x: any) => x is Type;
+export declare const isPromise: (v: any) => v is Promise<any>;
+export declare function getAsyncWithTokens(klass: Type<any>): Type<any>[] | null;
+/** Read param types for static with(...) only; TDZ-friendly. */
+export declare function readWithParamTypes(klass: Type, forWhat: 'discovery' | 'invocation'): Type[];
+/** Discover deps for a CLASS token or a concrete Type (ctor/with). */
+export declare function depsOfClass(klass: Type, phase: 'discovery' | 'invocation'): Type[];
+/** Discover deps for a Function token  without the first N args. */
+export declare function depsOfFunc(fn: (...args: any[]) => any | Promise<any>, phase: 'discovery' | 'invocation'): Type[];

package/src/utils/token.utils.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPromise = exports.isClass = exports.tokenName = void 0;
+exports.getAsyncWithTokens = getAsyncWithTokens;
+exports.readWithParamTypes = readWithParamTypes;
+exports.depsOfClass = depsOfClass;
+exports.depsOfFunc = depsOfFunc;
+const common_1 = require("../common");
+const metadata_utils_1 = require("./metadata.utils");
+const tokenName = (t) => typeof t === 'function' && !!t.prototype
+    ? t.name
+    : t?.name ?? '[ref]';
+exports.tokenName = tokenName;
+const isClass = (x) => typeof x === 'function' && !!x.prototype;
+exports.isClass = isClass;
+const isPromise = (v) => !!v && typeof v.then === 'function';
+exports.isPromise = isPromise;
+function getAsyncWithTokens(klass) {
+    const resolver = (0, metadata_utils_1.getMetadata)(common_1.META_ASYNC_WITH_TOKENS, klass);
+    if (!resolver)
+        return null;
+    const arr = resolver() ?? [];
+    return arr.filter(exports.isClass);
+}
+/** Read param types for static with(...) only; TDZ-friendly. */
+function readWithParamTypes(klass, forWhat) {
+    const lazy = getAsyncWithTokens(klass);
+    if (lazy)
+        return lazy;
+    const meta = (0, metadata_utils_1.getMetadata)(common_1.DESIGN_PARAMTYPES, klass, 'with');
+    if (meta === undefined) {
+        const where = `${klass.name}.with(...)`;
+        const hint = 'Add @AsyncWith(() => [DepA, DepB]) to lazily declare deps, or decorate \'with\' so TypeScript emits design:paramtypes.';
+        throw new Error(`Cannot discover ${forWhat} deps for ${where}. ${hint}`);
+    }
+    const tdzIdx = meta.findIndex((t) => t === undefined);
+    if (tdzIdx !== -1) {
+        const where = `${klass.name}.with(...)`;
+        throw new Error(`Unresolved dependency at param #${tdzIdx} in ${where} (ESM circular import / TDZ).\n` +
+            `Fix: add @AsyncWith(() => [/* deps */]) on ${klass.name} to avoid TDZ, or refactor the import cycle.`);
+    }
+    return meta.filter(exports.isClass);
+}
+/** Discover deps for a CLASS token or a concrete Type (ctor/with). */
+function depsOfClass(klass, phase) {
+    if ((0, metadata_utils_1.hasAsyncWith)(klass))
+        return readWithParamTypes(klass, phase);
+    const ctorMeta = (0, metadata_utils_1.getMetadata)(common_1.DESIGN_PARAMTYPES, klass) ?? [];
+    const tdzIdx = ctorMeta.findIndex((t) => t === undefined);
+    if (tdzIdx !== -1) {
+        throw new Error(`Unresolved constructor dependency in ${klass.name} at param #${tdzIdx} (ESM circular import / TDZ).\n` +
+            `Fix: convert this provider to @AsyncWith(() => [/* deps */]) and use a static with(...), or break the import cycle.`);
+    }
+    return ctorMeta.filter(exports.isClass);
+}
+/** Discover deps for a Function token  without the first N args. */
+function depsOfFunc(fn, phase) {
+    const [_ignoreInput, ...fnMeta] = (0, metadata_utils_1.getMetadata)(common_1.DESIGN_PARAMTYPES, fn) ?? [];
+    const tdzIdx = fnMeta.findIndex((t) => t === undefined);
+    if (tdzIdx !== -1) {
+        throw new Error(`Unresolved function dependency in ${fn.name} at param #${tdzIdx} (ESM circular import / TDZ).\n`);
+    }
+    return fnMeta.filter(exports.isClass);
+}
+//# sourceMappingURL=token.utils.js.map

package/src/utils/token.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.utils.js","sourceRoot":"","sources":["../../../src/utils/token.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { DESIGN_PARAMTYPES, META_ASYNC_WITH_TOKENS, Token, Type } from '../common';\nimport { getMetadata, hasAsyncWith } from './metadata.utils';\n\nexport const tokenName = (t: Token): string =>\n  typeof t === 'function' && !!(t as any).prototype\n    ? (t as any).name\n    : (t as any)?.name ?? '[ref]';\n\nexport const isClass = (x: any): x is Type =>\n  typeof x === 'function' && !!x.prototype;\n\nexport const isPromise = (v: any): v is Promise<any> =>\n  !!v && typeof v.then === 'function';\n\nexport function getAsyncWithTokens(klass: Type<any>): Type<any>[] | null {\n  const resolver = getMetadata<null | (() => any[])>(\n    META_ASYNC_WITH_TOKENS,\n    klass,\n  ) as null | (() => any[]);\n  if (!resolver) return null;\n  const arr = resolver() ?? [];\n  return arr.filter(isClass) as Type<any>[];\n}\n\n/** Read param types for static with(...) only; TDZ-friendly. */\nexport function readWithParamTypes(klass: Type, forWhat: 'discovery' | 'invocation'): Type[] {\n  const lazy = getAsyncWithTokens(klass);\n  if (lazy) return lazy;\n\n  const meta = getMetadata<unknown[]>(DESIGN_PARAMTYPES, klass, 'with') as unknown[] | undefined;\n  if (meta === undefined) {\n    const where = `${klass.name}.with(...)`;\n    const hint =\n      'Add @AsyncWith(() => [DepA, DepB]) to lazily declare deps, or decorate \\'with\\' so TypeScript emits design:paramtypes.';\n    throw new Error(`Cannot discover ${forWhat} deps for ${where}. ${hint}`);\n  }\n\n  const tdzIdx = meta.findIndex((t) => t === undefined);\n  if (tdzIdx !== -1) {\n    const where = `${klass.name}.with(...)`;\n    throw new Error(\n      `Unresolved dependency at param #${tdzIdx} in ${where} (ESM circular import / TDZ).\\n` +\n      `Fix: add @AsyncWith(() => [/* deps */]) on ${klass.name} to avoid TDZ, or refactor the import cycle.`,\n    );\n  }\n\n  return (meta as any[]).filter(isClass) as Type[];\n}\n\n\n/** Discover deps for a CLASS token or a concrete Type (ctor/with). */\nexport function depsOfClass(klass: Type, phase: 'discovery' | 'invocation'): Type[] {\n  if (hasAsyncWith(klass)) return readWithParamTypes(klass, phase);\n  const ctorMeta: unknown[] = getMetadata<unknown[]>(DESIGN_PARAMTYPES, klass) ?? [];\n  const tdzIdx = ctorMeta.findIndex((t) => t === undefined);\n  if (tdzIdx !== -1) {\n    throw new Error(\n      `Unresolved constructor dependency in ${klass.name} at param #${tdzIdx} (ESM circular import / TDZ).\\n` +\n      `Fix: convert this provider to @AsyncWith(() => [/* deps */]) and use a static with(...), or break the import cycle.`,\n    );\n  }\n  return (ctorMeta as any[]).filter(isClass) as Type[];\n}\n\n\n/** Discover deps for a Function token  without the first N args. */\nexport function depsOfFunc(fn: (...args: any[])=>any | Promise<any>, phase: 'discovery' | 'invocation'): Type[] {\n  const [_ignoreInput, ...fnMeta]: unknown[] = getMetadata<unknown[]>(DESIGN_PARAMTYPES, fn) ?? [];\n  const tdzIdx = fnMeta.findIndex((t) => t === undefined);\n  if (tdzIdx !== -1) {\n    throw new Error(`Unresolved function dependency in ${fn.name} at param #${tdzIdx} (ESM circular import / TDZ).\\n`);\n  }\n  return (fnMeta as any[]).filter(isClass) as Type[];\n}\n"]}

package/src/utils/types.utils.d.ts

@@ -0,0 +1,7 @@
+import { z, ZodTypeAny } from 'zod';
+type Primitive = string | number | boolean | bigint | null | undefined;
+type Flatten<T> = T extends Primitive ? T : T extends Array<infer U> ? Array<Flatten<U>> : T extends Set<infer U> ? Set<Flatten<U>> : T extends Map<infer K, infer V> ? Map<Flatten<K>, Flatten<V>> : T extends object ? {
+    [K in keyof T]: Flatten<T[K]>;
+} : T;
+export type Infer<Schema extends ZodTypeAny> = Flatten<z.infer<Schema>>;
+export {};