@gramio/composer 0.2.0 → 0.3.0

package/README.md

@@ -119,13 +119,21 @@ app.guard(
 );
 ```
 
-**Without handlers** — gate the chain: if false, stop this composer's remaining middleware:
+**Without handlers (gate mode)** — if false, stop this composer's remaining middleware. When a type predicate is used, downstream context is narrowed:
 
 ```ts
 // Only admin can reach subsequent middleware
 app
   .guard((ctx) => ctx.role === "admin")
   .use(adminOnlyHandler);  // skipped if not admin
+
+// Type predicate narrows context for all downstream handlers
+app
+  .guard((ctx): ctx is Ctx & { text: string } => "text" in ctx)
+  .on("message", (ctx, next) => {
+    ctx.text; // string (narrowed by guard)
+    return next();
+  });
 ```
 
 When used inside an `extend()`-ed plugin, the guard stops the plugin's chain but the parent continues:
@@ -305,6 +313,74 @@ const app = new Composer()
   });
 ```
 
+#### `.on()` with filters
+
+**Filter-only (no event name)** — the 2-arg `on(filter, handler)` applies the filter to **all** events without discriminating by event type:
+
+```ts
+// Type-narrowing filter — handler sees narrowed context across all compatible events
+app.on(
+  (ctx): ctx is { text: string } => typeof (ctx as any).text === "string",
+  (ctx, next) => {
+    ctx.text; // string (narrowed)
+    return next();
+  },
+);
+
+// Boolean filter — no narrowing, handler gets base TOut
+app.on(
+  (ctx) => ctx.updateType === "message",
+  (ctx, next) => {
+    // no type narrowing, full context
+    return next();
+  },
+);
+```
+
+**Event + filter** — the 3-arg `on(event, filter, handler)` supports both type-narrowing predicates and boolean filters:
+
+```ts
+// Type-narrowing filter — handler sees narrowed context
+app.on(
+  "message",
+  (ctx): ctx is MessageCtx & { text: string } => ctx.text !== undefined,
+  (ctx, next) => {
+    ctx.text; // string (narrowed, not string | undefined)
+    return next();
+  },
+);
+
+// Boolean filter — no narrowing, handler sees full context
+app.on(
+  "message",
+  (ctx) => ctx.text !== undefined,
+  (ctx, next) => {
+    ctx.text; // string | undefined (not narrowed)
+    return next();
+  },
+);
+```
+
+The 2-arg `on()` also accepts an optional `Patch` generic for context extensions (useful in custom methods):
+
+```ts
+app.on<"message", { args: string }>("message", (ctx, next) => {
+  ctx.args; // string — type-safe without casting
+  return next();
+});
+```
+
+`.use()` supports the same `Patch` generic — handy when a custom method enriches context before delegating to a user-provided handler:
+
+```ts
+app.use<{ args: string }>((ctx, next) => {
+  ctx.args; // string — type-safe without casting
+  return next();
+});
+```
+
+`Patch` does not change `TOut` — it is a local escape hatch for one handler, not a permanent context extension. Use `derive()` when you want the addition to propagate to all downstream middleware.
+
 #### `types` + `eventTypes()` — phantom type inference
 
 TypeScript cannot partially infer type arguments, so when you need both `TEventMap` and `TMethods` inferred together, use the `types` phantom field with the `eventTypes()` helper instead of explicit type parameters:
@@ -322,7 +398,9 @@ const { Composer } = createComposer({
 
 #### `methods` — custom prototype methods
 
-Inject framework-specific DX sugar directly onto the Composer prototype via the `methods` config option. Method bodies receive `this` typed as the full `EventComposer`, giving access to `.on()`, `.use()`, `.derive()`, etc.
+Inject framework-specific DX sugar directly onto the Composer prototype. Custom methods are preserved through **all** method chains (`on`, `use`, `derive`, `extend`, etc.). A runtime conflict check throws if a method name collides with a built-in.
+
+**Simple methods** (no access to accumulated derives) work directly in `methods`:
 
 ```ts
 const { Composer } = createComposer({
@@ -343,13 +421,77 @@ const { Composer } = createComposer({
     },
   },
 });
+```
+
+**Methods that receive accumulated derives** require two steps. TypeScript cannot infer generic method signatures when `TMethods` is nested inside the return type of `createComposer`, so use `defineComposerMethods` first — its return type is directly `TMethods`, which preserves generic signatures. Then pass `typeof methods` as the 3rd type argument.
+
+Use `ComposerLike<TThis>` as an F-bounded constraint so that `this.on(...)` is fully typed and returns `TThis` — no casts needed.
 
-const bot = new Composer();
-bot.hears(/hello/, handler);            // custom method
-bot.on("message", h).hears(/hi/, h2);  // chaining works — TMethods preserved
+**Pattern: `this: TThis` + `ContextOf<TThis>` — zero annotation at the call site:**
+
+```ts
+import { createComposer, defineComposerMethods, eventTypes } from "@gramio/composer";
+import type { ComposerLike, ContextOf, Middleware } from "@gramio/composer";
+
+const methods = defineComposerMethods({
+  command<TThis extends ComposerLike<TThis>>(
+    this: TThis,
+    name: string,
+    handler: Middleware<MessageCtx & ContextOf<TThis>>,
+  ): TThis {
+    const inner: Middleware<MessageCtx & ContextOf<TThis>> = (ctx, next) => {
+      if (ctx.text === `/${name}`) return handler(ctx, next);
+      return next();
+    };
+    return this.on("message", inner);
+  },
+});
+
+const { Composer } = createComposer<BaseCtx, { message: MessageCtx }, typeof methods>({
+  discriminator: (ctx) => ctx.updateType,
+  methods,
+});
+
+// Derives flow into the handler automatically — no annotation needed:
+new Composer()
+  .derive(() => ({ user: { id: 1, name: "Alice" } }))
+  .command("start", (ctx, next) => {
+    ctx.user.id;   // ✅ typed — inferred from ContextOf<TThis>
+    ctx.text;      // ✅ string | undefined — from MessageCtx
+    return next();
+  });
+```
+
+#### `ContextOf<T>` — extract the current context type
+
+Extracts `TOut` from a Composer or EventComposer instance type. Used as `ContextOf<TThis>` in custom method signatures to automatically capture all accumulated derives at the call site.
+
+```ts
+import type { ContextOf } from "@gramio/composer";
+
+// From a plain Composer:
+type Ctx = ContextOf<Composer<{ a: number }, { a: number; b: string }>>;
+//   Ctx = { a: number; b: string }
+
+// In a custom method — TThis is inferred from the caller instance:
+command<TThis extends ComposerLike<TThis>>(
+  this: TThis,
+  handler: Middleware<ContextOf<TThis>>,
+): TThis
 ```
 
-Custom methods are preserved through **all** method chains (`on`, `use`, `derive`, `extend`, etc.). A runtime conflict check throws if a method name collides with a built-in (e.g. `on`, `use`, `derive`).
+#### `ComposerLike<T>` — minimal structural type for `this` constraints
+
+A minimal interface `{ on(event: any, handler: any): T }` used as an F-bounded constraint on `TThis`. Makes `this.on(...)` fully typed and return `TThis` without casts.
+
+```ts
+import type { ComposerLike } from "@gramio/composer";
+
+// Constraint in a custom method:
+command<TThis extends ComposerLike<TThis>>(this: TThis, ...): TThis {
+  return this.on("message", inner); // returns TThis — no `as TThis` needed
+}
+```
 
 ### `EventQueue`
 
@@ -370,6 +512,88 @@ queue.addBatch(events);
 await queue.stop(5000);
 ```
 
+### Macro System
+
+Declarative handler options inspired by [Elysia macros](https://elysiajs.com/patterns/macro.md). Register reusable behaviors (guards, rate-limits, auth) as macros, then activate them via an options object on handler methods.
+
+#### `macro(name, definition)` / `macro(definitions)`
+
+Register macros on a Composer or EventComposer instance.
+
+```ts
+import { Composer, type MacroDef, type ContextCallback } from "@gramio/composer";
+
+// Boolean shorthand macro — plain hooks object
+const onlyAdmin: MacroDef<void, {}> = {
+  preHandler: (ctx, next) => {
+    if (ctx.role !== "admin") return; // stops chain
+    return next();
+  },
+};
+
+// Parameterized macro — function receiving options
+interface ThrottleOptions {
+  limit: number;
+  window?: number;
+  onLimit?: ContextCallback; // ← replaced with actual ctx type at call site
+}
+
+const throttle: MacroDef<ThrottleOptions, {}> = (opts) => ({
+  preHandler: createThrottleMiddleware(opts),
+});
+
+// Macro with derive — enriches handler context
+interface AuthDerived { user: { id: number; name: string } }
+
+const auth: MacroDef<void, AuthDerived> = {
+  derive: async (ctx) => {
+    const user = await getUser(ctx.token);
+    if (!user) return; // void = stop chain (guard behavior)
+    return { user };
+  },
+};
+
+const app = new Composer()
+  .macro("onlyAdmin", onlyAdmin)
+  .macro({ throttle, auth }); // batch registration
+```
+
+#### `buildFromOptions(macros, options, handler)`
+
+Runtime helper that composes a handler with macro hooks. Used internally by frameworks to wire macros into handler methods.
+
+```ts
+import { buildFromOptions } from "@gramio/composer";
+
+// Execution order:
+// 1. options.preHandler[] (explicit guards — user controls order)
+// 2. Per-macro in options property order:
+//    a. macro.preHandler (guard middleware)
+//    b. macro.derive (context enrichment; void = stop chain)
+// 3. Main handler
+const composed = buildFromOptions(
+  app["~"].macros,
+  { auth: true, throttle: { limit: 5 } },
+  mainHandler,
+);
+```
+
+#### Macro Types
+
+```ts
+import type {
+  MacroDef,          // Macro definition (function or hooks object)
+  MacroHooks,        // { preHandler?, derive? }
+  MacroDefinitions,  // Record<string, MacroDef<any, any>>
+  ContextCallback,   // Marker type for context-aware callbacks
+  WithCtx,           // Recursively replaces ContextCallback with real ctx type
+  HandlerOptions,    // Builds the options parameter type for handler methods
+  DeriveFromOptions, // Collects derive types from activated macros
+  MacroOptionType,   // Extracts option type from MacroDef
+  MacroDeriveType,   // Extracts derive return type from MacroDef
+} from "@gramio/composer";
+```
+
 ### Utilities
 
 ```ts

package/dist/index.cjs

@@ -79,7 +79,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;
@@ -88,6 +91,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);
@@ -99,6 +110,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 });
@@ -316,6 +328,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) => {
@@ -475,19 +488,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 });
@@ -535,10 +565,52 @@ function createComposer(config) {
   };
 }
 
+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);
+}
+
 exports.Composer = Composer;
 exports.EventQueue = EventQueue;
+exports.buildFromOptions = buildFromOptions;
 exports.compose = compose;
 exports.createComposer = createComposer;
+exports.defineComposerMethods = defineComposerMethods;
 exports.eventTypes = eventTypes;
 exports.noopNext = noopNext;
 exports.skip = skip;

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 };

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,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 };

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,19 +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 });
@@ -532,4 +562,44 @@ function createComposer(config) {
   };
 }
 
-export { Composer, EventQueue, compose, createComposer, eventTypes, 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.2.0",
+	"version": "0.3.0",
 	"description": "General-purpose, type-safe middleware composition library for TypeScript",
 	"main": "dist/index.cjs",
 	"module": "dist/index.js",