@gramio/composer 0.1.1 → 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,186 @@ 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:
+
+```ts
+import { createComposer, eventTypes } from "@gramio/composer";
+
+// eventTypes<T>() returns undefined at runtime — purely for inference
+const { Composer } = createComposer({
+  discriminator: (ctx: BaseCtx) => ctx.updateType,
+  types: eventTypes<{ message: MessageCtx; callback_query: CallbackCtx }>(),
+});
+// TBase inferred from discriminator, TEventMap inferred from types
+```
+
+#### `methods` — custom prototype methods
+
+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({
+  discriminator: (ctx: BaseCtx) => ctx.updateType,
+  types: eventTypes<{ message: MessageCtx }>(),
+  methods: {
+    hears(trigger: RegExp | string, handler: (ctx: MessageCtx) => unknown) {
+      return this.on("message", (ctx, next) => {
+        const text = ctx.text;
+        if (
+          (typeof trigger === "string" && text === trigger) ||
+          (trigger instanceof RegExp && text && trigger.test(text))
+        ) {
+          return handler(ctx);
+        }
+        return next();
+      });
+    },
+  },
+});
+```
+
+**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 { 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
+```
+
+#### `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`
 
 Concurrent event queue with graceful shutdown.
@@ -324,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,16 +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 });
@@ -512,6 +545,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,
@@ -519,10 +565,53 @@ 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;
 exports.stop = stop;