@gramio/composer 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -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,39 +226,80 @@ 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;
-/** 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>;
+/**
+ * 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> = {}, 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;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): this;
+    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>): this;
+    fork(...middleware: Middleware<TOut>[]): this;
+    tap(...middleware: Middleware<TOut>[]): this;
+    lazy(factory: LazyFactory<TOut>): this;
+    onError(handler: ErrorHandler<TOut>): this;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        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, TMacros> & TMethods;
     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>;
+    }): 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>;
+    }): 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;
-    }>;
-    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>;
+    }, 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,24 +316,148 @@ 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>> {
-    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>;
+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> = {}, 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
+ * so that `TEventMap` can be inferred from the `types` config field.
+ *
+ * @example
+ * ```ts
+ * const { Composer } = createComposer({
+ *   discriminator: (ctx: BaseCtx) => ctx.updateType,
+ *   types: eventTypes<EventMap>(),
+ *   methods: { hears(trigger) { return this.on("message", ...); } },
+ * });
+ * ```
+ */
+declare function eventTypes<TEventMap extends Record<string, any>>(): TEventMap;
 /**
  * Creates a configured Composer class with type-safe .on() event discrimination.
  */
-declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}>(config: {
+declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}>(config: {
     discriminator: (context: TBase) => string;
+    types?: TEventMap;
+    methods?: TMethods & ThisType<EventComposer<TBase, TEventMap, TBase, TBase, {}, {}, TMethods> & TMethods>;
 }): {
-    Composer: EventComposerConstructor<TBase, TEventMap>;
+    Composer: EventComposerConstructor<TBase, TEventMap, TMethods>;
     compose: typeof compose;
     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 */
@@ -210,5 +465,5 @@ 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 };
+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 };

package/dist/index.js

@@ -76,7 +76,10 @@ class Composer {
     name: void 0,
     seed: void 0,
     errorsDefinitions: {},
-    tracer: void 0
+    tracer: void 0,
+    macros: {},
+    /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
+    Out: void 0
   };
   constructor(options) {
     this["~"].name = options?.name;
@@ -85,6 +88,14 @@ class Composer {
   invalidate() {
     this["~"].compiled = null;
   }
+  macro(nameOrDefs, definition) {
+    if (typeof nameOrDefs === "string") {
+      this["~"].macros[nameOrDefs] = definition;
+    } else {
+      Object.assign(this["~"].macros, nameOrDefs);
+    }
+    return this;
+  }
   decorate(values, options) {
     const mw = (ctx, next) => {
       Object.assign(ctx, values);
@@ -96,6 +107,7 @@ class Composer {
     this.invalidate();
     return this;
   }
+  // biome-ignore lint/suspicious/noExplicitAny: overload implementation signature
   use(...middleware) {
     for (const fn of middleware) {
       this["~"].middlewares.push({ fn, scope: "local", type: "use", name: fn.name || void 0 });
@@ -313,6 +325,7 @@ class Composer {
       this["~"].extended.add(key);
     }
     Object.assign(this["~"].errorsDefinitions, other["~"].errorsDefinitions);
+    Object.assign(this["~"].macros, other["~"].macros);
     this["~"].onErrors.push(...other["~"].onErrors);
     const pluginName = other["~"].name;
     const isNew = (m) => {
@@ -472,16 +485,36 @@ class EventQueue {
   }
 }
 
+function defineComposerMethods(methods) {
+  return methods;
+}
+function eventTypes() {
+  return void 0;
+}
 function createComposer(config) {
   class EventComposerImpl extends Composer {
-    on(event, handler) {
-      const events = Array.isArray(event) ? event : [event];
+    on(eventOrFilter, filterOrHandler, handler) {
+      if (typeof eventOrFilter === "function") {
+        const filter2 = eventOrFilter;
+        const actualHandler2 = filterOrHandler;
+        const filterLabel = filter2.name || "filter";
+        const mw2 = (ctx, next) => {
+          if (filter2(ctx)) return actualHandler2(ctx, next);
+          return next();
+        };
+        nameMiddleware(mw2, "on", filterLabel);
+        this["~"].middlewares.push({ fn: mw2, scope: "local", type: "on", name: filterLabel });
+        this.invalidate();
+        return this;
+      }
+      const events = Array.isArray(eventOrFilter) ? eventOrFilter : [eventOrFilter];
       const eventLabel = events.join("|");
+      const actualHandler = handler ?? filterOrHandler;
+      const filter = handler ? filterOrHandler : void 0;
       const mw = (ctx, next) => {
-        if (events.includes(config.discriminator(ctx))) {
-          return handler(ctx, next);
-        }
-        return next();
+        if (!events.includes(config.discriminator(ctx))) return next();
+        if (filter && !filter(ctx)) return next();
+        return actualHandler(ctx, next);
       };
       nameMiddleware(mw, "on", eventLabel);
       this["~"].middlewares.push({ fn: mw, scope: "local", type: "on", name: eventLabel });
@@ -509,6 +542,19 @@ function createComposer(config) {
       return this;
     }
   }
+  if (config.methods) {
+    for (const [name, fn] of Object.entries(config.methods)) {
+      if (name in EventComposerImpl.prototype) {
+        throw new Error(`Custom method "${name}" conflicts with built-in method`);
+      }
+      Object.defineProperty(EventComposerImpl.prototype, name, {
+        value: fn,
+        writable: true,
+        configurable: true,
+        enumerable: false
+      });
+    }
+  }
   return {
     Composer: EventComposerImpl,
     compose,
@@ -516,4 +562,44 @@ function createComposer(config) {
   };
 }
 
-export { Composer, EventQueue, compose, createComposer, noopNext, skip, stop };
+function buildFromOptions(macros, options, handler) {
+  if (!options) return handler;
+  const chain = [];
+  const preHandler = options.preHandler;
+  if (preHandler) {
+    if (Array.isArray(preHandler)) {
+      chain.push(...preHandler);
+    } else {
+      chain.push(preHandler);
+    }
+  }
+  for (const key of Object.keys(options)) {
+    if (key === "preHandler") continue;
+    const value = options[key];
+    if (value === false || value == null) continue;
+    const def = macros[key];
+    if (!def) continue;
+    const hooks = typeof def === "function" ? def(value === true ? void 0 : value) : def;
+    if (hooks.preHandler) {
+      if (Array.isArray(hooks.preHandler)) {
+        chain.push(...hooks.preHandler);
+      } else {
+        chain.push(hooks.preHandler);
+      }
+    }
+    if (hooks.derive) {
+      const deriveFn = hooks.derive;
+      chain.push(async (ctx, next) => {
+        const derived = await deriveFn(ctx);
+        if (derived == null) return;
+        Object.assign(ctx, derived);
+        return next();
+      });
+    }
+  }
+  chain.push(handler);
+  if (chain.length === 1) return chain[0];
+  return compose(chain);
+}
+
+export { Composer, EventQueue, buildFromOptions, compose, createComposer, defineComposerMethods, eventTypes, noopNext, skip, stop };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gramio/composer",
-	"version": "0.1.1",
+	"version": "0.3.0",
 	"description": "General-purpose, type-safe middleware composition library for TypeScript",
 	"main": "dist/index.cjs",
 	"module": "dist/index.js",