@gramio/composer 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,214 @@
+/** next() continuation function */
+type Next = () => Promise<unknown>;
+/** Middleware function: receives context and next */
+type Middleware<T> = (context: T, next: Next) => unknown;
+/** Composed middleware: next is optional (acts as terminal continuation) */
+type ComposedMiddleware<T> = (context: T, next?: Next) => Promise<unknown>;
+/** Error handler receives an object with error, context, and resolved kind */
+type ErrorHandler<T> = (params: {
+    error: unknown;
+    context: T;
+    kind?: string;
+}) => unknown;
+/** Function that computes additional context properties */
+type DeriveHandler<T, D> = (context: T) => D | Promise<D>;
+/** Lazy middleware factory — called per invocation */
+type LazyFactory<T> = (context: T) => Middleware<T> | Promise<Middleware<T>>;
+/** Single value or array */
+type MaybeArray<T> = T | T[];
+/** Scope level for middleware propagation */
+type Scope = "local" | "scoped" | "global";
+/** Which method created a middleware entry */
+type MiddlewareType = "use" | "derive" | "decorate" | "guard" | "branch" | "route" | "fork" | "tap" | "lazy" | "group" | "extend" | "on";
+/** Read-only projection of a middleware entry for inspect()/trace() */
+interface MiddlewareInfo {
+    index: number;
+    type: MiddlewareType;
+    name?: string;
+    scope: Scope;
+    plugin?: string;
+}
+/** Trace callback invoked on middleware enter; returns cleanup called on exit */
+type TraceHandler = (entry: MiddlewareInfo, context: any) => ((error?: unknown) => void) | void;
+/** Internal middleware entry with scope annotation and metadata */
+interface ScopedMiddleware<T> {
+    fn: Middleware<T>;
+    scope: Scope;
+    type: MiddlewareType;
+    name?: string;
+    plugin?: string;
+}
+/** Composer constructor options */
+interface ComposerOptions {
+    name?: string;
+    seed?: unknown;
+}
+
+/**
+ * Compose an array of middleware functions into a single middleware.
+ * Koa-style onion model: each middleware receives (context, next).
+ */
+declare function compose<T>(middlewares: Middleware<T>[]): ComposedMiddleware<T>;
+
+/** Route handler: single middleware, array, or Composer instance */
+type RouteHandler<T extends object> = Middleware<T> | Middleware<T>[] | Composer<any, any, any>;
+/** Route builder passed to the builder-callback overload of route() */
+interface RouteBuilder<T extends object, K extends string> {
+    /** Register a route. Returns a pre-typed Composer for chaining derive/use/guard etc. */
+    on(key: K, ...middleware: Middleware<T>[]): Composer<T, T, {}>;
+    /** Fallback when router returns undefined or key has no handler */
+    otherwise(...middleware: Middleware<T>[]): void;
+}
+declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed extends object = {}> {
+    "~": {
+        middlewares: ScopedMiddleware<any>[];
+        onErrors: ErrorHandler<any>[];
+        extended: Set<string>;
+        compiled: ComposedMiddleware<any> | null;
+        name: string | undefined;
+        seed: unknown;
+        errorsDefinitions: Record<string, {
+            new (...args: any): any;
+            prototype: Error;
+        }>;
+        tracer: TraceHandler | undefined;
+    };
+    constructor(options?: ComposerOptions);
+    invalidate(): void;
+    decorate<D extends object>(values: D): Composer<TIn, TOut & D, TExposed>;
+    decorate<D extends object>(values: D, options: {
+        as: "scoped" | "global";
+    }): Composer<TIn, TOut & D, TExposed & D>;
+    use(...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): Composer<TIn, TOut & D, TExposed>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
+        as: "scoped" | "global";
+    }): Composer<TIn, TOut & D, TExposed & D>;
+    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): Composer<TIn, TOut, TExposed>;
+    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): Composer<TIn, TOut, TExposed>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): Composer<TIn, TOut, TExposed>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): Composer<TIn, TOut, TExposed>;
+    fork(...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
+    tap(...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
+    lazy(factory: LazyFactory<TOut>): Composer<TIn, TOut, TExposed>;
+    onError(handler: ErrorHandler<TOut>): Composer<TIn, TOut, TExposed>;
+    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): Composer<TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed>;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        prototype: Error;
+    }): this;
+    as(scope: "scoped" | "global"): Composer<TIn, TOut, TOut>;
+    group(fn: (composer: Composer<TOut, TOut, {}>) => void): Composer<TIn, TOut, TExposed>;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): Composer<TIn, TOut & UExposed, TExposed>;
+    inspect(): MiddlewareInfo[];
+    trace(handler: TraceHandler): this;
+    compose(): ComposedMiddleware<TIn>;
+    run(context: TIn, next?: Next): Promise<void>;
+}
+
+/**
+ * Concurrent event queue with graceful shutdown support.
+ * Processes events in parallel (like an event loop), not sequentially.
+ */
+declare class EventQueue<T> {
+    private handler;
+    private queue;
+    private pendingUpdates;
+    private active;
+    private idleResolvers;
+    constructor(handler: (event: T) => Promise<unknown>);
+    add(event: T): void;
+    addBatch(events: T[]): void;
+    stop(timeout?: number): Promise<void>;
+    onIdle(): Promise<void>;
+    get pending(): number;
+    get queued(): number;
+    get isActive(): boolean;
+    private process;
+    private checkIdle;
+}
+
+/**
+ * Distributes over E to create a correlated union:
+ * each event branch gets its own TEventMap entry + per-event derives.
+ *
+ * Single event → simple intersection.
+ * Array of events → discriminated union where each branch has correct derives.
+ */
+type ResolveEventCtx<TOut extends object, TEventMap extends Record<string, any>, TDerives extends Record<string, object>, E extends string> = E extends any ? TOut & (E extends keyof TEventMap ? TEventMap[E] : {}) & (E extends keyof TDerives ? TDerives[E] : {}) : never;
+/** EventComposer interface — Composer + .on() + per-event derive tracking */
+interface EventComposer<TBase extends object, TEventMap extends Record<string, TBase>, TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}> {
+    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+    decorate<D extends object>(values: D, options: {
+        as: "scoped" | "global";
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
+    use(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
+        as: "scoped" | "global";
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
+    derive<E extends keyof TEventMap & string, D extends object>(event: MaybeArray<E>, handler: DeriveHandler<ResolveEventCtx<TOut, TEventMap, TDerives, E>, D>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives & {
+        [K in E]: D;
+    }>;
+    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>>>, fallback?: (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    fork(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    tap(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    lazy(factory: LazyFactory<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    onError(handler: ErrorHandler<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): EventComposer<TBase, TEventMap, TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed, TDerives>;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        prototype: Error;
+    }): this;
+    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives>;
+    group(fn: (composer: Composer<TOut, TOut, {}>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives>;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives>;
+    inspect(): MiddlewareInfo[];
+    trace(handler: TraceHandler): this;
+    compose(): ComposedMiddleware<TIn>;
+    run(context: TIn, next?: Next): Promise<void>;
+    "~": {
+        middlewares: ScopedMiddleware<any>[];
+        onErrors: ErrorHandler<any>[];
+        extended: Set<string>;
+        compiled: ComposedMiddleware<any> | null;
+        name: string | undefined;
+        seed: unknown;
+        errorsDefinitions: Record<string, {
+            new (...args: any): any;
+            prototype: Error;
+        }>;
+        tracer: TraceHandler | undefined;
+        Derives: TDerives;
+    };
+    invalidate(): void;
+}
+interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>> {
+    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+}
+/**
+ * Creates a configured Composer class with type-safe .on() event discrimination.
+ */
+declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}>(config: {
+    discriminator: (context: TBase) => string;
+}): {
+    Composer: EventComposerConstructor<TBase, TEventMap>;
+    compose: typeof compose;
+    EventQueue: typeof EventQueue;
+};
+
+/** No-op next function: () => Promise.resolve() */
+declare const noopNext: Next;
+/** Pass-through middleware: calls next() immediately */
+declare const skip: Middleware<any>;
+/** Terminal middleware: does NOT call next() */
+declare const stop: Middleware<any>;
+
+export { Composer, EventQueue, compose, createComposer, noopNext, skip, stop };
+export type { ComposedMiddleware, ComposerOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, LazyFactory, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler };

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+/** next() continuation function */
+type Next = () => Promise<unknown>;
+/** Middleware function: receives context and next */
+type Middleware<T> = (context: T, next: Next) => unknown;
+/** Composed middleware: next is optional (acts as terminal continuation) */
+type ComposedMiddleware<T> = (context: T, next?: Next) => Promise<unknown>;
+/** Error handler receives an object with error, context, and resolved kind */
+type ErrorHandler<T> = (params: {
+    error: unknown;
+    context: T;
+    kind?: string;
+}) => unknown;
+/** Function that computes additional context properties */
+type DeriveHandler<T, D> = (context: T) => D | Promise<D>;
+/** Lazy middleware factory — called per invocation */
+type LazyFactory<T> = (context: T) => Middleware<T> | Promise<Middleware<T>>;
+/** Single value or array */
+type MaybeArray<T> = T | T[];
+/** Scope level for middleware propagation */
+type Scope = "local" | "scoped" | "global";
+/** Which method created a middleware entry */
+type MiddlewareType = "use" | "derive" | "decorate" | "guard" | "branch" | "route" | "fork" | "tap" | "lazy" | "group" | "extend" | "on";
+/** Read-only projection of a middleware entry for inspect()/trace() */
+interface MiddlewareInfo {
+    index: number;
+    type: MiddlewareType;
+    name?: string;
+    scope: Scope;
+    plugin?: string;
+}
+/** Trace callback invoked on middleware enter; returns cleanup called on exit */
+type TraceHandler = (entry: MiddlewareInfo, context: any) => ((error?: unknown) => void) | void;
+/** Internal middleware entry with scope annotation and metadata */
+interface ScopedMiddleware<T> {
+    fn: Middleware<T>;
+    scope: Scope;
+    type: MiddlewareType;
+    name?: string;
+    plugin?: string;
+}
+/** Composer constructor options */
+interface ComposerOptions {
+    name?: string;
+    seed?: unknown;
+}
+
+/**
+ * Compose an array of middleware functions into a single middleware.
+ * Koa-style onion model: each middleware receives (context, next).
+ */
+declare function compose<T>(middlewares: Middleware<T>[]): ComposedMiddleware<T>;
+
+/** Route handler: single middleware, array, or Composer instance */
+type RouteHandler<T extends object> = Middleware<T> | Middleware<T>[] | Composer<any, any, any>;
+/** Route builder passed to the builder-callback overload of route() */
+interface RouteBuilder<T extends object, K extends string> {
+    /** Register a route. Returns a pre-typed Composer for chaining derive/use/guard etc. */
+    on(key: K, ...middleware: Middleware<T>[]): Composer<T, T, {}>;
+    /** Fallback when router returns undefined or key has no handler */
+    otherwise(...middleware: Middleware<T>[]): void;
+}
+declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed extends object = {}> {
+    "~": {
+        middlewares: ScopedMiddleware<any>[];
+        onErrors: ErrorHandler<any>[];
+        extended: Set<string>;
+        compiled: ComposedMiddleware<any> | null;
+        name: string | undefined;
+        seed: unknown;
+        errorsDefinitions: Record<string, {
+            new (...args: any): any;
+            prototype: Error;
+        }>;
+        tracer: TraceHandler | undefined;
+    };
+    constructor(options?: ComposerOptions);
+    invalidate(): void;
+    decorate<D extends object>(values: D): Composer<TIn, TOut & D, TExposed>;
+    decorate<D extends object>(values: D, options: {
+        as: "scoped" | "global";
+    }): Composer<TIn, TOut & D, TExposed & D>;
+    use(...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): Composer<TIn, TOut & D, TExposed>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
+        as: "scoped" | "global";
+    }): Composer<TIn, TOut & D, TExposed & D>;
+    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): Composer<TIn, TOut, TExposed>;
+    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): Composer<TIn, TOut, TExposed>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): Composer<TIn, TOut, TExposed>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): Composer<TIn, TOut, TExposed>;
+    fork(...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
+    tap(...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
+    lazy(factory: LazyFactory<TOut>): Composer<TIn, TOut, TExposed>;
+    onError(handler: ErrorHandler<TOut>): Composer<TIn, TOut, TExposed>;
+    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): Composer<TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed>;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        prototype: Error;
+    }): this;
+    as(scope: "scoped" | "global"): Composer<TIn, TOut, TOut>;
+    group(fn: (composer: Composer<TOut, TOut, {}>) => void): Composer<TIn, TOut, TExposed>;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): Composer<TIn, TOut & UExposed, TExposed>;
+    inspect(): MiddlewareInfo[];
+    trace(handler: TraceHandler): this;
+    compose(): ComposedMiddleware<TIn>;
+    run(context: TIn, next?: Next): Promise<void>;
+}
+
+/**
+ * Concurrent event queue with graceful shutdown support.
+ * Processes events in parallel (like an event loop), not sequentially.
+ */
+declare class EventQueue<T> {
+    private handler;
+    private queue;
+    private pendingUpdates;
+    private active;
+    private idleResolvers;
+    constructor(handler: (event: T) => Promise<unknown>);
+    add(event: T): void;
+    addBatch(events: T[]): void;
+    stop(timeout?: number): Promise<void>;
+    onIdle(): Promise<void>;
+    get pending(): number;
+    get queued(): number;
+    get isActive(): boolean;
+    private process;
+    private checkIdle;
+}
+
+/**
+ * Distributes over E to create a correlated union:
+ * each event branch gets its own TEventMap entry + per-event derives.
+ *
+ * Single event → simple intersection.
+ * Array of events → discriminated union where each branch has correct derives.
+ */
+type ResolveEventCtx<TOut extends object, TEventMap extends Record<string, any>, TDerives extends Record<string, object>, E extends string> = E extends any ? TOut & (E extends keyof TEventMap ? TEventMap[E] : {}) & (E extends keyof TDerives ? TDerives[E] : {}) : never;
+/** EventComposer interface — Composer + .on() + per-event derive tracking */
+interface EventComposer<TBase extends object, TEventMap extends Record<string, TBase>, TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}> {
+    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+    decorate<D extends object>(values: D, options: {
+        as: "scoped" | "global";
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
+    use(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
+        as: "scoped" | "global";
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
+    derive<E extends keyof TEventMap & string, D extends object>(event: MaybeArray<E>, handler: DeriveHandler<ResolveEventCtx<TOut, TEventMap, TDerives, E>, D>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives & {
+        [K in E]: D;
+    }>;
+    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>>>, fallback?: (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    fork(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    tap(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    lazy(factory: LazyFactory<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    onError(handler: ErrorHandler<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): EventComposer<TBase, TEventMap, TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed, TDerives>;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        prototype: Error;
+    }): this;
+    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives>;
+    group(fn: (composer: Composer<TOut, TOut, {}>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives>;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives>;
+    inspect(): MiddlewareInfo[];
+    trace(handler: TraceHandler): this;
+    compose(): ComposedMiddleware<TIn>;
+    run(context: TIn, next?: Next): Promise<void>;
+    "~": {
+        middlewares: ScopedMiddleware<any>[];
+        onErrors: ErrorHandler<any>[];
+        extended: Set<string>;
+        compiled: ComposedMiddleware<any> | null;
+        name: string | undefined;
+        seed: unknown;
+        errorsDefinitions: Record<string, {
+            new (...args: any): any;
+            prototype: Error;
+        }>;
+        tracer: TraceHandler | undefined;
+        Derives: TDerives;
+    };
+    invalidate(): void;
+}
+interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>> {
+    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+}
+/**
+ * Creates a configured Composer class with type-safe .on() event discrimination.
+ */
+declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}>(config: {
+    discriminator: (context: TBase) => string;
+}): {
+    Composer: EventComposerConstructor<TBase, TEventMap>;
+    compose: typeof compose;
+    EventQueue: typeof EventQueue;
+};
+
+/** No-op next function: () => Promise.resolve() */
+declare const noopNext: Next;
+/** Pass-through middleware: calls next() immediately */
+declare const skip: Middleware<any>;
+/** Terminal middleware: does NOT call next() */
+declare const stop: Middleware<any>;
+
+export { Composer, EventQueue, compose, createComposer, noopNext, skip, stop };
+export type { ComposedMiddleware, ComposerOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, LazyFactory, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler };