@gramio/composer 0.3.1 → 0.3.4

package/README.md

@@ -521,6 +521,63 @@ command<TThis extends ComposerLike<TThis>>(
 ): TThis
 ```
 
+#### `EventContextOf<T, E>` — extract context for a specific event (global + per-event derives)
+
+Like `ContextOf<T>`, but also includes per-event derives registered via `derive(event, handler)`.
+
+| | Includes |
+|---|---|
+| `ContextOf<TThis>` | `TOut` — global derives only |
+| `EventContextOf<TThis, "message">` | `TOut & TDerives["message"]` — global **and** per-event derives |
+
+**Why it matters:** when a custom method always routes to a specific event (e.g. `command` → `"message"`), its handler should see per-event derives too. With `ContextOf` alone, a `derive("message", ...)` plugin's types are invisible inside the handler even though the value is there at runtime.
+
+```ts
+import { createComposer, defineComposerMethods, eventTypes } from "@gramio/composer";
+import type { ComposerLike, EventContextOf, Middleware } from "@gramio/composer";
+
+const methods = defineComposerMethods({
+  command<TThis extends ComposerLike<TThis>>(
+    this: TThis,
+    name: string,
+    //                  ↓ EventContextOf instead of ContextOf
+    handler: Middleware<MessageCtx & EventContextOf<TThis, "message">>,
+  ): TThis {
+    return this.on("message", (ctx: any, next: Next) => {
+      if (ctx.text === `/${name}`) return handler(ctx, next);
+      return next();
+    });
+  },
+});
+
+const { Composer } = createComposer<BaseCtx, { message: MessageCtx }, typeof methods>({
+  discriminator: (ctx) => ctx.updateType,
+  methods,
+});
+
+// Per-event plugin that adds `t` only for message events:
+const i18nPlugin = new Composer({ name: "i18n" })
+  .derive("message", (ctx) => ({
+    t: i18n.buildT(ctx.from?.languageCode ?? "en"),
+  }))
+  .as("scoped");
+
+new Composer()
+  .extend(i18nPlugin)
+  .command("start", (ctx, next) => {
+    ctx.t("Hello");   // ✅ typed — EventContextOf sees TDerives["message"]
+    ctx.text;         // ✅ string | undefined — from MessageCtx
+    return next();
+  })
+  .on("message", (ctx, next) => {
+    ctx.t("Hi");      // ✅ also works here via ResolveEventCtx
+    return next();
+  });
+```
+
+> [!NOTE]
+> If the derive is registered globally (`.derive(() => ...)` without an event name), both `ContextOf` and `EventContextOf` will see it. Per-event derives (`derive("message", ...)`) are only visible through `EventContextOf` in custom method signatures, or directly inside `.on("message", ...)` handlers.
+
 #### `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.

package/dist/index.cjs

@@ -313,7 +313,10 @@ class Composer {
       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];
+        if (!preKeys.has(key)) {
+          const desc = Object.getOwnPropertyDescriptor(ctx, key);
+          if (desc?.configurable) delete ctx[key];
+        }
       }
       Object.assign(ctx, snapshot);
       return next();
@@ -355,7 +358,10 @@ class Composer {
         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];
+          if (!preKeys.has(key)) {
+            const desc = Object.getOwnPropertyDescriptor(ctx, key);
+            if (desc?.configurable) delete ctx[key];
+          }
         }
         Object.assign(ctx, snapshot);
         return next();
@@ -380,6 +386,31 @@ class Composer {
       return info;
     });
   }
+  /**
+   * Returns a Set of all event names registered via `.on()` and event-specific `.derive()`.
+   *
+   * Useful for introspecting which update types the middleware chain handles,
+   * e.g. to auto-derive `allowed_updates` for the Telegram Bot API.
+   *
+   * @example
+   * ```typescript
+   * composer.on("message", handler);
+   * composer.on(["callback_query", "inline_query"], handler);
+   * composer.registeredEvents(); // Set {"message", "callback_query", "inline_query"}
+   * ```
+   */
+  registeredEvents() {
+    const events = /* @__PURE__ */ new Set();
+    for (const mw of this["~"].middlewares) {
+      if ((mw.type === "on" || mw.type === "derive") && mw.name) {
+        for (const part of mw.name.split("|")) {
+          const eventPart = part.includes(":") ? part.split(":")[0] : part;
+          if (eventPart) events.add(eventPart);
+        }
+      }
+    }
+    return events;
+  }
   trace(handler) {
     this["~"].tracer = handler;
     this.invalidate();

package/dist/index.d.cts

@@ -191,6 +191,20 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
     group(fn: (composer: Composer<TOut, TOut, {}>) => void): Composer<TIn, TOut, 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[];
+    /**
+     * Returns a Set of all event names registered via `.on()` and event-specific `.derive()`.
+     *
+     * Useful for introspecting which update types the middleware chain handles,
+     * e.g. to auto-derive `allowed_updates` for the Telegram Bot API.
+     *
+     * @example
+     * ```typescript
+     * composer.on("message", handler);
+     * composer.on(["callback_query", "inline_query"], handler);
+     * composer.registeredEvents(); // Set {"message", "callback_query", "inline_query"}
+     * ```
+     */
+    registeredEvents(): Set<string>;
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
     run(context: TIn, next?: Next): Promise<void>;
@@ -301,6 +315,7 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
     /** 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[];
+    registeredEvents(): Set<string>;
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
     run(context: TIn, next?: Next): Promise<void>;
@@ -379,6 +394,40 @@ type ContextOf<T> = T extends {
         Out: infer O;
     };
 } ? O : never;
+/**
+ * Extracts the context type for a specific event from an EventComposer instance,
+ * combining global `TOut` (like `ContextOf`) **and** per-event `TDerives[E]`.
+ *
+ * Use this in custom event-specific methods (e.g. `command`, `hears`) instead of
+ * `ContextOf<T>` so that handlers registered via `derive(event, handler)` are
+ * visible in the handler's type:
+ *
+ * @example
+ * ```ts
+ * const methods = defineComposerMethods({
+ *   command<TThis extends ComposerLike<TThis>>(
+ *     this: TThis,
+ *     name: string,
+ *     handler: Middleware<MsgCtx & EventContextOf<TThis, "message">>,
+ *   ): TThis {
+ *     return this.on("message", (ctx, next) => {
+ *       if (ctx.text === `/${name}`) return handler(ctx, next);
+ *       return next();
+ *     });
+ *   },
+ * });
+ *
+ * new Composer()
+ *   .derive("message", () => ({ t: (s: string) => s }))
+ *   .command("start", (ctx) => ctx.t("Hi!")); // ✅ t is visible
+ * ```
+ */
+type EventContextOf<T, E extends string> = T extends {
+    "~": {
+        Out: infer O extends object;
+        Derives: infer D extends Record<string, object>;
+    };
+} ? O & (E extends keyof D ? D[E] : {}) : never;
 /**
  * Helper to define custom composer methods with full TypeScript inference.
  *
@@ -466,4 +515,4 @@ declare const skip: Middleware<any>;
 declare const stop: Middleware<any>;
 
 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 };
+export type { CompatibleEvents, ComposedMiddleware, ComposerLike, ComposerOptions, ContextCallback, ContextOf, DeriveFromOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, EventContextOf, HandlerOptions, LazyFactory, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler, WithCtx };

package/dist/index.d.ts

@@ -191,6 +191,20 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
     group(fn: (composer: Composer<TOut, TOut, {}>) => void): Composer<TIn, TOut, 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[];
+    /**
+     * Returns a Set of all event names registered via `.on()` and event-specific `.derive()`.
+     *
+     * Useful for introspecting which update types the middleware chain handles,
+     * e.g. to auto-derive `allowed_updates` for the Telegram Bot API.
+     *
+     * @example
+     * ```typescript
+     * composer.on("message", handler);
+     * composer.on(["callback_query", "inline_query"], handler);
+     * composer.registeredEvents(); // Set {"message", "callback_query", "inline_query"}
+     * ```
+     */
+    registeredEvents(): Set<string>;
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
     run(context: TIn, next?: Next): Promise<void>;
@@ -301,6 +315,7 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
     /** 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[];
+    registeredEvents(): Set<string>;
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
     run(context: TIn, next?: Next): Promise<void>;
@@ -379,6 +394,40 @@ type ContextOf<T> = T extends {
         Out: infer O;
     };
 } ? O : never;
+/**
+ * Extracts the context type for a specific event from an EventComposer instance,
+ * combining global `TOut` (like `ContextOf`) **and** per-event `TDerives[E]`.
+ *
+ * Use this in custom event-specific methods (e.g. `command`, `hears`) instead of
+ * `ContextOf<T>` so that handlers registered via `derive(event, handler)` are
+ * visible in the handler's type:
+ *
+ * @example
+ * ```ts
+ * const methods = defineComposerMethods({
+ *   command<TThis extends ComposerLike<TThis>>(
+ *     this: TThis,
+ *     name: string,
+ *     handler: Middleware<MsgCtx & EventContextOf<TThis, "message">>,
+ *   ): TThis {
+ *     return this.on("message", (ctx, next) => {
+ *       if (ctx.text === `/${name}`) return handler(ctx, next);
+ *       return next();
+ *     });
+ *   },
+ * });
+ *
+ * new Composer()
+ *   .derive("message", () => ({ t: (s: string) => s }))
+ *   .command("start", (ctx) => ctx.t("Hi!")); // ✅ t is visible
+ * ```
+ */
+type EventContextOf<T, E extends string> = T extends {
+    "~": {
+        Out: infer O extends object;
+        Derives: infer D extends Record<string, object>;
+    };
+} ? O & (E extends keyof D ? D[E] : {}) : never;
 /**
  * Helper to define custom composer methods with full TypeScript inference.
  *
@@ -466,4 +515,4 @@ declare const skip: Middleware<any>;
 declare const stop: Middleware<any>;
 
 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 };
+export type { CompatibleEvents, ComposedMiddleware, ComposerLike, ComposerOptions, ContextCallback, ContextOf, DeriveFromOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, EventContextOf, HandlerOptions, LazyFactory, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler, WithCtx };

package/dist/index.js

@@ -310,7 +310,10 @@ class Composer {
       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];
+        if (!preKeys.has(key)) {
+          const desc = Object.getOwnPropertyDescriptor(ctx, key);
+          if (desc?.configurable) delete ctx[key];
+        }
       }
       Object.assign(ctx, snapshot);
       return next();
@@ -352,7 +355,10 @@ class Composer {
         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];
+          if (!preKeys.has(key)) {
+            const desc = Object.getOwnPropertyDescriptor(ctx, key);
+            if (desc?.configurable) delete ctx[key];
+          }
         }
         Object.assign(ctx, snapshot);
         return next();
@@ -377,6 +383,31 @@ class Composer {
       return info;
     });
   }
+  /**
+   * Returns a Set of all event names registered via `.on()` and event-specific `.derive()`.
+   *
+   * Useful for introspecting which update types the middleware chain handles,
+   * e.g. to auto-derive `allowed_updates` for the Telegram Bot API.
+   *
+   * @example
+   * ```typescript
+   * composer.on("message", handler);
+   * composer.on(["callback_query", "inline_query"], handler);
+   * composer.registeredEvents(); // Set {"message", "callback_query", "inline_query"}
+   * ```
+   */
+  registeredEvents() {
+    const events = /* @__PURE__ */ new Set();
+    for (const mw of this["~"].middlewares) {
+      if ((mw.type === "on" || mw.type === "derive") && mw.name) {
+        for (const part of mw.name.split("|")) {
+          const eventPart = part.includes(":") ? part.split(":")[0] : part;
+          if (eventPart) events.add(eventPart);
+        }
+      }
+    }
+    return events;
+  }
   trace(handler) {
     this["~"].tracer = handler;
     this.invalidate();

package/package.json

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