@gramio/composer 0.3.0 → 0.3.3

package/README.md

@@ -282,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.
@@ -464,22 +490,94 @@ new Composer()
 
 #### `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.
+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";
 
-// From a plain Composer:
-type Ctx = ContextOf<Composer<{ a: number }, { a: number; b: string }>>;
-//   Ctx = { a: number; b: string }
+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");
+}
+```
 
-// In a custom method — TThis is inferred from the caller instance:
+**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
 ```
 
+#### `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

@@ -308,8 +308,17 @@ 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)) {
+          const desc = Object.getOwnPropertyDescriptor(ctx, key);
+          if (desc?.configurable) delete ctx[key];
+        }
+      }
+      Object.assign(ctx, snapshot);
       return next();
     };
     nameMiddleware(mw, "group");
@@ -344,8 +353,17 @@ 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)) {
+            const desc = Object.getOwnPropertyDescriptor(ctx, key);
+            if (desc?.configurable) delete ctx[key];
+          }
+        }
+        Object.assign(ctx, snapshot);
         return next();
       };
       nameMiddleware(isolated, "extend", pluginName);

package/dist/index.d.cts

@@ -379,6 +379,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 +500,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

@@ -379,6 +379,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 +500,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

@@ -305,8 +305,17 @@ 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)) {
+          const desc = Object.getOwnPropertyDescriptor(ctx, key);
+          if (desc?.configurable) delete ctx[key];
+        }
+      }
+      Object.assign(ctx, snapshot);
       return next();
     };
     nameMiddleware(mw, "group");
@@ -341,8 +350,17 @@ 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)) {
+            const desc = Object.getOwnPropertyDescriptor(ctx, key);
+            if (desc?.configurable) delete ctx[key];
+          }
+        }
+        Object.assign(ctx, snapshot);
         return next();
       };
       nameMiddleware(isolated, "extend", pluginName);

package/package.json

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