@gramio/composer 0.3.0 → 0.3.1

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,16 +490,31 @@ 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>>,

package/dist/index.cjs

@@ -308,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");
@@ -344,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);

package/dist/index.js

@@ -305,8 +305,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");
@@ -341,8 +347,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);

package/package.json

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