@gramio/composer 0.2.0 → 0.3.1

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:
@@ -274,6 +282,32 @@ app.extend(limit100); // applied
 app.extend(limit200); // applied (different seed)
 ```
 
+> [!WARNING]
+> **Dedup removes middleware at registration time — not at runtime per-request.**
+>
+> If a shared plugin (e.g. `withUser`) is extended only inside sub-composers, its
+> `derive` runs inside each sub-composer's isolation group. When dedup removes the
+> derive from the second sub-composer, `ctx.user` set in the first group is **not
+> visible** in the second — TypeScript types are correct, runtime value is `undefined`.
+>
+> **Fix:** extend the shared composer at the level where its data must be available,
+> and let sub-composers extend it only for type safety (dedup prevents double execution).
+>
+> ```ts
+> // ✅ correct — withUser runs once on the real ctx, both routers see ctx.user
+> app
+>   .extend(withUser)    // derive on real ctx
+>   .extend(adminRouter) // withUser inside → deduped (skipped)
+>   .extend(chatRouter); // withUser inside → deduped (skipped)
+>
+> // ⚠️  risky — works only if routers are mutually exclusive (one handles per update)
+> app
+>   .extend(adminRouter) // withUser runs in isolation group
+>   .extend(chatRouter); // withUser deduped → chatHandlers can't see ctx.user
+> ```
+>
+> See [`docs/layered-composers.md`](./docs/layered-composers.md) for the full breakdown.
+
 ### `createComposer(config)` — Event System
 
 Factory that creates a Composer class with `.on()` event discrimination.
@@ -305,6 +339,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 +424,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 +447,92 @@ 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.
+
+**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 bot = new Composer();
-bot.hears(/hello/, handler);            // custom method
-bot.on("message", h).hears(/hi/, h2);  // chaining works — TMethods preserved
+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` (the fully accumulated context type after all `.derive()` and `.decorate()` calls) from a Composer or EventComposer instance type.
+
+**Naming a plugin's context type for reuse:**
+
+```ts
+import type { ContextOf } from "@gramio/composer";
+
+const withUser = new Composer()
+  .derive(async (ctx) => ({
+    user: await db.getUser(ctx.userId),
+  }));
+
+// Extract the enriched context — no manual conditional type needed
+export type WithUser = ContextOf<typeof withUser>;
+// WithUser = { userId: string } & { user: User }
+
+// Use it in standalone functions, other plugins, or type assertions:
+function requireAdmin(ctx: WithUser) {
+  if (!ctx.user.isAdmin) throw new Error("Forbidden");
+}
 ```
 
-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`).
+**In a custom method signature** — `ContextOf<TThis>` captures all derives accumulated at the call site:
+
+```ts
+command<TThis extends ComposerLike<TThis>>(
+  this: TThis,
+  handler: Middleware<ContextOf<TThis>>,
+): TThis
+```
+
+#### `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 +553,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 });
@@ -296,8 +308,14 @@ class Composer {
     fn(group);
     const chain = compose(group["~"].middlewares.map((m) => m.fn));
     const mw = async (ctx, next) => {
-      const scopedCtx = Object.create(ctx);
-      await chain(scopedCtx, noopNext);
+      const preKeys = new Set(Object.keys(ctx));
+      const snapshot = {};
+      for (const key of preKeys) snapshot[key] = ctx[key];
+      await chain(ctx, noopNext);
+      for (const key of Object.keys(ctx)) {
+        if (!preKeys.has(key)) delete ctx[key];
+      }
+      Object.assign(ctx, snapshot);
       return next();
     };
     nameMiddleware(mw, "group");
@@ -316,6 +334,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) => {
@@ -331,8 +350,14 @@ class Composer {
     if (localMws.length > 0) {
       const chain = compose(localMws.map((m) => m.fn));
       const isolated = async (ctx, next) => {
-        const scopedCtx = Object.create(ctx);
-        await chain(scopedCtx, noopNext);
+        const preKeys = new Set(Object.keys(ctx));
+        const snapshot = {};
+        for (const key of preKeys) snapshot[key] = ctx[key];
+        await chain(ctx, noopNext);
+        for (const key of Object.keys(ctx)) {
+          if (!preKeys.has(key)) delete ctx[key];
+        }
+        Object.assign(ctx, snapshot);
         return next();
       };
       nameMiddleware(isolated, "extend", pluginName);
@@ -475,19 +500,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 +577,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;