@gramio/composer 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -19,7 +19,88 @@ type MaybeArray<T> = T | readonly 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";
+type MiddlewareType = "use" | "derive" | "decorate" | "guard" | "branch" | "route" | "fork" | "tap" | "lazy" | "group" | "extend" | "on" | "macro";
+/** Brand symbol for ContextCallback marker type */
+declare const ContextCallbackBrand: unique symbol;
+/**
+ * Marker type for context-aware callbacks in macro options.
+ * The framework replaces this with the actual handler context type at the call site.
+ *
+ * @example
+ * ```ts
+ * interface ThrottleOptions {
+ *   limit: number;
+ *   onLimit?: ContextCallback;  // ← framework substitutes the real ctx type
+ * }
+ * ```
+ */
+interface ContextCallback {
+    readonly [ContextCallbackBrand]: true;
+    (ctx: never): unknown;
+}
+/**
+ * Recursively replaces all `ContextCallback` occurrences in `T`
+ * with `(ctx: TCtx) => unknown`.
+ */
+type WithCtx<T, TCtx> = T extends ContextCallback ? (ctx: TCtx) => unknown : T extends (...args: any[]) => any ? T : T extends object ? {
+    [K in keyof T]: WithCtx<T[K], TCtx>;
+} : T;
+/** What a macro can return when activated */
+interface MacroHooks<TDerive extends object = {}> {
+    /** Middleware to run before the main handler */
+    preHandler?: Middleware<any> | Middleware<any>[];
+    /**
+     * Context enrichment — return type gets merged into the handler's context.
+     * Return `void` / `undefined` to stop the middleware chain (acts as a guard).
+     */
+    derive?: (ctx: any) => TDerive | void | Promise<TDerive | void>;
+}
+/**
+ * A macro definition: either a function accepting options, or a plain hooks object (boolean shorthand).
+ *
+ * @example
+ * ```ts
+ * // Parameterized macro
+ * const throttle: MacroDef<{ limit: number }, {}> = (opts) => ({
+ *   preHandler: createThrottleMiddleware(opts),
+ * });
+ *
+ * // Boolean shorthand
+ * const onlyAdmin: MacroDef<void, {}> = {
+ *   preHandler: checkAdminMiddleware,
+ * };
+ * ```
+ */
+type MacroDef<TOptions = void, TDerive extends object = {}> = ((opts: TOptions) => MacroHooks<TDerive>) | MacroHooks<TDerive>;
+/** Registry of named macro definitions */
+type MacroDefinitions = Record<string, MacroDef<any, any>>;
+/** Extract the options type a macro accepts (boolean for shorthand macros) */
+type MacroOptionType<M> = M extends (opts: infer O) => any ? O : boolean;
+/** Extract the derive (context enrichment) type from a macro */
+type MacroDeriveType<M> = M extends (opts: any) => {
+    derive: (...a: any) => infer R;
+} ? Exclude<Awaited<R>, void> : M extends {
+    derive: (...a: any) => infer R;
+} ? Exclude<Awaited<R>, void> : {};
+/**
+ * Builds the `options` parameter type for handler methods.
+ * Includes `preHandler` plus all registered macro option types
+ * with ContextCallback markers replaced by `TBaseCtx`.
+ */
+type HandlerOptions<TBaseCtx, Macros extends MacroDefinitions> = {
+    preHandler?: Middleware<TBaseCtx> | Middleware<TBaseCtx>[];
+} & {
+    [K in keyof Macros]?: WithCtx<MacroOptionType<Macros[K]>, TBaseCtx>;
+};
+/** Helper: converts a union to an intersection */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Collects all derive types from macros that are activated in `TOptions`.
+ * The result is intersected into the handler's context type.
+ */
+type DeriveFromOptions<Macros extends MacroDefinitions, TOptions> = UnionToIntersection<{
+    [K in keyof TOptions & keyof Macros]: MacroDeriveType<Macros[K]>;
+}[keyof TOptions & keyof Macros]>;
 /** Read-only projection of a middleware entry for inspect()/trace() */
 interface MiddlewareInfo {
     index: number;
@@ -51,7 +132,7 @@ interface ComposerOptions {
 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>;
+type RouteHandler<T extends object> = Middleware<T> | Middleware<T>[] | Composer<any, 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. */
@@ -59,7 +140,7 @@ interface RouteBuilder<T extends object, K extends string> {
     /** 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 = {}> {
+declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed extends object = {}, TMacros extends MacroDefinitions = {}> {
     "~": {
         middlewares: ScopedMiddleware<any>[];
         onErrors: ErrorHandler<any>[];
@@ -72,13 +153,22 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
             prototype: Error;
         }>;
         tracer: TraceHandler | undefined;
+        macros: Record<string, MacroDef<any, any>>;
+        /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
+        Out: TOut;
     };
     constructor(options?: ComposerOptions);
     invalidate(): void;
+    /** Register a single named macro */
+    macro<const Name extends string, TDef extends MacroDef<any, any>>(name: Name, definition: TDef): Composer<TIn, TOut, TExposed, TMacros & Record<Name, TDef>>;
+    /** Register multiple macros at once */
+    macro<const TDefs extends Record<string, MacroDef<any, any>>>(definitions: TDefs): Composer<TIn, TOut, TExposed, TMacros & TDefs>;
     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(handler: Middleware<TOut>): this;
+    use<Patch extends object>(handler: Middleware<TOut & Patch>): this;
     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: {
@@ -99,7 +189,7 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
     }): 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>;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object, UMacros extends MacroDefinitions = {}>(other: Composer<UIn, UOut, UExposed, UMacros>): Composer<TIn, TOut & UExposed, TExposed, TMacros & UMacros>;
     inspect(): MiddlewareInfo[];
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
@@ -136,10 +226,47 @@ declare class EventQueue<T> {
  * 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;
+/**
+ * Given an event map and a Narrowing type, yields the union of event names
+ * whose context type contains all keys from Narrowing.
+ */
+type CompatibleEvents<TEventMap extends Record<string, any>, Narrowing> = {
+    [E in keyof TEventMap & string]: keyof Narrowing & string extends keyof TEventMap[E] ? E : never;
+}[keyof TEventMap & string];
+/**
+ * Minimal structural type for constraining `this` in custom composer methods.
+ *
+ * Use as an F-bounded constraint on `TThis` so that `this.on(...)` is typed
+ * and returns `TThis` without requiring `as any`:
+ *
+ * @example
+ * ```ts
+ * command<TThis extends ComposerLike<TThis>>(
+ *   this: TThis,
+ *   name: string,
+ *   handler: Middleware<MsgCtx & ContextOf<TThis>>,
+ * ): TThis {
+ *   const inner: Middleware<MsgCtx & ContextOf<TThis>> = (ctx, next) => {
+ *     if (ctx.text === `/${name}`) return handler(ctx, next);
+ *     return next();
+ *   };
+ *   return this.on("message", inner); // typed — no cast needed
+ * }
+ * ```
+ */
+type ComposerLike<T = unknown> = {
+    on(event: any, handler: any): T;
+};
 /** EventComposer interface — Composer + .on() + per-event derive tracking + custom methods */
-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> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}> {
-    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): this;
+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> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}, TMacros extends MacroDefinitions = {}> {
+    on<Narrowing>(filter: (ctx: any) => ctx is Narrowing, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, CompatibleEvents<TEventMap, Narrowing>> & Narrowing>): this;
+    on(filter: (ctx: TOut) => boolean, handler: Middleware<TOut>): this;
+    on<E extends keyof TEventMap & string, Narrowing>(event: MaybeArray<E>, filter: (ctx: any) => ctx is Narrowing, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E> & Narrowing>): this;
+    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, filter: (ctx: ResolveEventCtx<TOut, TEventMap, TDerives, E>) => boolean, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): this;
+    on<E extends keyof TEventMap & string, Patch extends object = {}>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E> & Patch>): this;
+    use<Patch extends object>(handler: Middleware<TOut & Patch>): this;
     use(...middleware: Middleware<TOut>[]): this;
+    guard<Narrowing>(predicate: (context: any) => context is Narrowing): EventComposer<TBase, TEventMap, TIn, TOut & Narrowing, TExposed, TDerives, TMethods, TMacros> & TMethods;
     guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): this;
     branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): this;
     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>): this;
@@ -154,21 +281,25 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
         prototype: Error;
     }): this;
     group(fn: (composer: Composer<TOut, TOut, {}>) => void): this;
-    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods> & TMethods;
+    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods, TMacros> & TMethods;
     decorate<D extends object>(values: D, options: {
         as: "scoped" | "global";
-    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods> & TMethods;
-    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods> & TMethods;
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods, TMacros> & TMethods;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods, TMacros> & TMethods;
     derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
         as: "scoped" | "global";
-    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods> & TMethods;
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods, TMacros> & TMethods;
     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;
-    }, TMethods> & TMethods;
-    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, TMethods> & TMethods;
-    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives, TMethods> & TMethods;
-    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives, any>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives, TMethods> & TMethods;
-    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives, TMethods> & TMethods;
+    }, TMethods, TMacros> & TMethods;
+    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, TMethods, TMacros> & TMethods;
+    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives, TMethods, TMacros> & TMethods;
+    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>, UMacros extends MacroDefinitions = {}>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives, any, UMacros>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives, TMethods, TMacros & UMacros> & TMethods;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object, UMacros extends MacroDefinitions = {}>(other: Composer<UIn, UOut, UExposed, UMacros>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives, TMethods, TMacros & UMacros> & TMethods;
+    /** Register a single named macro */
+    macro<const Name extends string, TDef extends MacroDef<any, any>>(name: Name, definition: TDef): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives, TMethods, TMacros & Record<Name, TDef>> & TMethods;
+    /** Register multiple macros at once */
+    macro<const TDefs extends Record<string, MacroDef<any, any>>>(definitions: TDefs): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives, TMethods, TMacros & TDefs> & TMethods;
     inspect(): MiddlewareInfo[];
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
@@ -185,13 +316,108 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
             prototype: Error;
         }>;
         tracer: TraceHandler | undefined;
+        macros: Record<string, MacroDef<any, any>>;
         Derives: TDerives;
+        /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
+        Out: TOut;
     };
     invalidate(): void;
 }
 interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>, TMethods extends Record<string, (...args: any[]) => any> = {}> {
-    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, TMethods> & TMethods;
+    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}, TMacros extends MacroDefinitions = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives, TMethods, TMacros> & TMethods;
 }
+/**
+ * Extracts the current accumulated context type (`TOut`) from an EventComposer
+ * or Composer instance type.
+ *
+ * Use with a `this: TThis` parameter in custom methods to get automatic
+ * derive type inference — the handler receives all types from previous `.derive()` calls
+ * without requiring explicit annotation at the call site.
+ *
+ * @example
+ * ```ts
+ * const { Composer } = createComposer({
+ *   methods: {
+ *     // Automatic: caller's derives are inferred into the handler
+ *     command<TThis>(
+ *       this: TThis,
+ *       name: string,
+ *       handler: Middleware<MessageCtx & ContextOf<TThis>>,
+ *     ) {
+ *       return (this as any).on("message", (ctx: any, next: any) => {
+ *         if (ctx.text === `/${name}`) return handler(ctx, next);
+ *         return next();
+ *       }) as TThis;
+ *     },
+ *
+ *     // Manual: caller declares which derives they need via Patch generic
+ *     hears<Patch extends object = {}>(
+ *       trigger: string,
+ *       handler: Middleware<MessageCtx & Patch>,
+ *     ) {
+ *       return this.on<"message", Patch>("message", (ctx, next) => {
+ *         if (ctx.text === trigger) return handler(ctx, next);
+ *         return next();
+ *       });
+ *     },
+ *   },
+ * });
+ *
+ * // With ContextOf — no type annotation needed at call site:
+ * new Composer()
+ *   .derive(() => ({ user: { id: 1 } }))
+ *   .command("start", (ctx) => ctx.user.id); // ✅ inferred automatically
+ *
+ * // With Patch — caller declares what they need:
+ * new Composer()
+ *   .derive(() => ({ user: { id: 1 } }))
+ *   .hears<{ user: { id: number } }>("hello", (ctx) => ctx.user.id); // ✅
+ * ```
+ */
+type ContextOf<T> = T extends {
+    "~": {
+        Out: infer O;
+    };
+} ? O : never;
+/**
+ * Helper to define custom composer methods with full TypeScript inference.
+ *
+ * TypeScript cannot infer generic method signatures when they're passed directly
+ * inside `createComposer({ methods: { ... } })` because `TMethods` is buried
+ * inside the nested return type `{ Composer: EventComposerConstructor<..., TMethods> }`.
+ *
+ * This helper has return type `TMethods` directly — which lets TypeScript preserve
+ * generic method signatures. Pass the result (via `typeof`) as the 3rd type argument
+ * to `createComposer`:
+ *
+ * @example
+ * ```ts
+ * const methods = defineComposerMethods({
+ *   // Pattern: `this: TThis` + `ContextOf<TThis>` — zero annotation at call site
+ *   command<TThis>(
+ *     this: TThis,
+ *     name: string,
+ *     handler: Middleware<MessageCtx & ContextOf<TThis>>,
+ *   ): TThis {
+ *     return (this as any).on("message", (ctx: any, next: any) => {
+ *       if (ctx.text === `/${name}`) return handler(ctx, next);
+ *       return next();
+ *     }) as TThis;
+ *   },
+ * });
+ *
+ * const { Composer } = createComposer<Base, EventMap, typeof methods>({
+ *   discriminator: (ctx) => ctx.updateType,
+ *   methods,
+ * });
+ *
+ * // No annotation needed — derives flow in automatically:
+ * new Composer()
+ *   .derive(() => ({ user: { id: 1 } }))
+ *   .command("start", (ctx) => ctx.user.id); // ✅
+ * ```
+ */
+declare function defineComposerMethods<TMethods extends Record<string, (...args: any[]) => any>>(methods: TMethods): TMethods;
 /**
  * Phantom type carrier for event map inference.
  * Returns `undefined` at runtime — exists purely for type-level inference
@@ -220,6 +446,18 @@ declare function createComposer<TBase extends object, TEventMap extends Record<s
     EventQueue: typeof EventQueue;
 };
 
+/**
+ * Composes a handler with macro hooks and preHandlers from an options object.
+ *
+ * Execution order:
+ * 1. `options.preHandler` array (explicit guards — user controls order)
+ * 2. Per-macro in options property order:
+ *    a. macro.preHandler (guard middleware)
+ *    b. macro.derive (context enrichment; void return = stop chain)
+ * 3. Main handler
+ */
+declare function buildFromOptions<TCtx>(macros: Record<string, MacroDef<any, any>>, options: Record<string, unknown> | undefined, handler: Middleware<TCtx>): Middleware<TCtx>;
+
 /** No-op next function: () => Promise.resolve() */
 declare const noopNext: Next;
 /** Pass-through middleware: calls next() immediately */
@@ -227,5 +465,5 @@ declare const skip: Middleware<any>;
 /** Terminal middleware: does NOT call next() */
 declare const stop: Middleware<any>;
 
-export { Composer, EventQueue, compose, createComposer, eventTypes, noopNext, skip, stop };
-export type { ComposedMiddleware, ComposerOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, LazyFactory, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler };
+export { Composer, EventQueue, buildFromOptions, compose, createComposer, defineComposerMethods, eventTypes, noopNext, skip, stop };
+export type { CompatibleEvents, ComposedMiddleware, ComposerLike, ComposerOptions, ContextCallback, ContextOf, DeriveFromOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, HandlerOptions, LazyFactory, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler, WithCtx };