@gramio/composer 0.1.0 → 0.2.0

package/README.md

@@ -305,6 +305,52 @@ const app = new Composer()
   });
 ```
 
+#### `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 via the `methods` config option. Method bodies receive `this` typed as the full `EventComposer`, giving access to `.on()`, `.use()`, `.derive()`, etc.
+
+```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();
+      });
+    },
+  },
+});
+
+const bot = new Composer();
+bot.hears(/hello/, handler);            // custom method
+bot.on("message", h).hears(/hi/, h2);  // chaining works — TMethods preserved
+```
+
+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`).
+
 ### `EventQueue`
 
 Concurrent event queue with graceful shutdown.

package/dist/index.cjs

@@ -311,15 +311,23 @@ class Composer {
       if (this["~"].extended.has(key)) return this;
       this["~"].extended.add(key);
     }
+    const alreadyExtended = new Set(this["~"].extended);
     for (const key of other["~"].extended) {
       this["~"].extended.add(key);
     }
     Object.assign(this["~"].errorsDefinitions, other["~"].errorsDefinitions);
     this["~"].onErrors.push(...other["~"].onErrors);
     const pluginName = other["~"].name;
-    const localMws = other["~"].middlewares.filter((m) => m.scope === "local");
-    const scopedMws = other["~"].middlewares.filter((m) => m.scope === "scoped");
-    const globalMws = other["~"].middlewares.filter((m) => m.scope === "global");
+    const isNew = (m) => {
+      if (!m.plugin) return true;
+      for (const key of alreadyExtended) {
+        if (key.startsWith(m.plugin + ":")) return false;
+      }
+      return true;
+    };
+    const localMws = other["~"].middlewares.filter((m) => m.scope === "local" && isNew(m));
+    const scopedMws = other["~"].middlewares.filter((m) => m.scope === "scoped" && isNew(m));
+    const globalMws = other["~"].middlewares.filter((m) => m.scope === "global" && isNew(m));
     if (localMws.length > 0) {
       const chain = compose(localMws.map((m) => m.fn));
       const isolated = async (ctx, next) => {
@@ -467,6 +475,9 @@ class EventQueue {
   }
 }
 
+function eventTypes() {
+  return void 0;
+}
 function createComposer(config) {
   class EventComposerImpl extends Composer {
     on(event, handler) {
@@ -504,6 +515,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,
@@ -515,6 +539,7 @@ exports.Composer = Composer;
 exports.EventQueue = EventQueue;
 exports.compose = compose;
 exports.createComposer = createComposer;
+exports.eventTypes = eventTypes;
 exports.noopNext = noopNext;
 exports.skip = skip;
 exports.stop = stop;

package/dist/index.d.cts

@@ -15,7 +15,7 @@ type DeriveHandler<T, D> = (context: T) => D | Promise<D>;
 /** Lazy middleware factory — called per invocation */
 type LazyFactory<T> = (context: T) => Middleware<T> | Promise<Middleware<T>>;
 /** Single value or array */
-type MaybeArray<T> = T | T[];
+type MaybeArray<T> = T | readonly T[];
 /** Scope level for middleware propagation */
 type Scope = "local" | "scoped" | "global";
 /** Which method created a middleware entry */
@@ -136,39 +136,39 @@ declare class EventQueue<T> {
  * Array of events → discriminated union where each branch has correct derives.
  */
 type ResolveEventCtx<TOut extends object, TEventMap extends Record<string, any>, TDerives extends Record<string, object>, E extends string> = E extends any ? TOut & (E extends keyof TEventMap ? TEventMap[E] : {}) & (E extends keyof TDerives ? TDerives[E] : {}) : never;
-/** EventComposer interface — Composer + .on() + per-event derive tracking */
-interface EventComposer<TBase extends object, TEventMap extends Record<string, TBase>, TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}> {
-    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+/** EventComposer interface — Composer + .on() + per-event derive tracking + custom methods */
+interface EventComposer<TBase extends object, TEventMap extends Record<string, TBase>, TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}> {
+    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): this;
+    use(...middleware: Middleware<TOut>[]): this;
+    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): this;
+    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): this;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>>>, fallback?: (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>): this;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): this;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): this;
+    fork(...middleware: Middleware<TOut>[]): this;
+    tap(...middleware: Middleware<TOut>[]): this;
+    lazy(factory: LazyFactory<TOut>): this;
+    onError(handler: ErrorHandler<TOut>): this;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        prototype: Error;
+    }): this;
+    group(fn: (composer: Composer<TOut, TOut, {}>) => void): this;
+    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods> & TMethods;
     decorate<D extends object>(values: D, options: {
         as: "scoped" | "global";
-    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
-    use(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods> & TMethods;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods> & TMethods;
     derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
         as: "scoped" | "global";
-    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods> & TMethods;
     derive<E extends keyof TEventMap & string, D extends object>(event: MaybeArray<E>, handler: DeriveHandler<ResolveEventCtx<TOut, TEventMap, TDerives, E>, D>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives & {
         [K in E]: D;
-    }>;
-    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>>>, fallback?: (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    fork(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    tap(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    lazy(factory: LazyFactory<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    onError(handler: ErrorHandler<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): EventComposer<TBase, TEventMap, TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed, TDerives>;
-    error(kind: string, errorClass: {
-        new (...args: any): any;
-        prototype: Error;
-    }): this;
-    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives>;
-    group(fn: (composer: Composer<TOut, TOut, {}>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives>;
-    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives>;
+    }, TMethods> & TMethods;
+    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): EventComposer<TBase, TEventMap, TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed, TDerives, TMethods> & TMethods;
+    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives, TMethods> & TMethods;
+    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives, any>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives, TMethods> & TMethods;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives, TMethods> & TMethods;
     inspect(): MiddlewareInfo[];
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
@@ -189,16 +189,33 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
     };
     invalidate(): void;
 }
-interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>> {
-    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>, TMethods extends Record<string, (...args: any[]) => any> = {}> {
+    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives, TMethods> & TMethods;
 }
+/**
+ * Phantom type carrier for event map inference.
+ * Returns `undefined` at runtime — exists purely for type-level inference
+ * so that `TEventMap` can be inferred from the `types` config field.
+ *
+ * @example
+ * ```ts
+ * const { Composer } = createComposer({
+ *   discriminator: (ctx: BaseCtx) => ctx.updateType,
+ *   types: eventTypes<EventMap>(),
+ *   methods: { hears(trigger) { return this.on("message", ...); } },
+ * });
+ * ```
+ */
+declare function eventTypes<TEventMap extends Record<string, any>>(): TEventMap;
 /**
  * Creates a configured Composer class with type-safe .on() event discrimination.
  */
-declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}>(config: {
+declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}>(config: {
     discriminator: (context: TBase) => string;
+    types?: TEventMap;
+    methods?: TMethods & ThisType<EventComposer<TBase, TEventMap, TBase, TBase, {}, {}, TMethods> & TMethods>;
 }): {
-    Composer: EventComposerConstructor<TBase, TEventMap>;
+    Composer: EventComposerConstructor<TBase, TEventMap, TMethods>;
     compose: typeof compose;
     EventQueue: typeof EventQueue;
 };
@@ -210,5 +227,5 @@ declare const skip: Middleware<any>;
 /** Terminal middleware: does NOT call next() */
 declare const stop: Middleware<any>;
 
-export { Composer, EventQueue, compose, createComposer, noopNext, skip, stop };
+export { Composer, EventQueue, compose, createComposer, eventTypes, noopNext, skip, stop };
 export type { ComposedMiddleware, ComposerOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, LazyFactory, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler };

package/dist/index.d.ts

@@ -15,7 +15,7 @@ type DeriveHandler<T, D> = (context: T) => D | Promise<D>;
 /** Lazy middleware factory — called per invocation */
 type LazyFactory<T> = (context: T) => Middleware<T> | Promise<Middleware<T>>;
 /** Single value or array */
-type MaybeArray<T> = T | T[];
+type MaybeArray<T> = T | readonly T[];
 /** Scope level for middleware propagation */
 type Scope = "local" | "scoped" | "global";
 /** Which method created a middleware entry */
@@ -136,39 +136,39 @@ declare class EventQueue<T> {
  * Array of events → discriminated union where each branch has correct derives.
  */
 type ResolveEventCtx<TOut extends object, TEventMap extends Record<string, any>, TDerives extends Record<string, object>, E extends string> = E extends any ? TOut & (E extends keyof TEventMap ? TEventMap[E] : {}) & (E extends keyof TDerives ? TDerives[E] : {}) : never;
-/** EventComposer interface — Composer + .on() + per-event derive tracking */
-interface EventComposer<TBase extends object, TEventMap extends Record<string, TBase>, TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}> {
-    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+/** EventComposer interface — Composer + .on() + per-event derive tracking + custom methods */
+interface EventComposer<TBase extends object, TEventMap extends Record<string, TBase>, TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}> {
+    on<E extends keyof TEventMap & string>(event: MaybeArray<E>, handler: Middleware<ResolveEventCtx<TOut, TEventMap, TDerives, E>>): this;
+    use(...middleware: Middleware<TOut>[]): this;
+    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): this;
+    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): this;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>>>, fallback?: (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>): this;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): this;
+    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): this;
+    fork(...middleware: Middleware<TOut>[]): this;
+    tap(...middleware: Middleware<TOut>[]): this;
+    lazy(factory: LazyFactory<TOut>): this;
+    onError(handler: ErrorHandler<TOut>): this;
+    error(kind: string, errorClass: {
+        new (...args: any): any;
+        prototype: Error;
+    }): this;
+    group(fn: (composer: Composer<TOut, TOut, {}>) => void): this;
+    decorate<D extends object>(values: D): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods> & TMethods;
     decorate<D extends object>(values: D, options: {
         as: "scoped" | "global";
-    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
-    use(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives>;
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods> & TMethods;
+    derive<D extends object>(handler: DeriveHandler<TOut, D>): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed, TDerives, TMethods> & TMethods;
     derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
         as: "scoped" | "global";
-    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives>;
+    }): EventComposer<TBase, TEventMap, TIn, TOut & D, TExposed & D, TDerives, TMethods> & TMethods;
     derive<E extends keyof TEventMap & string, D extends object>(event: MaybeArray<E>, handler: DeriveHandler<ResolveEventCtx<TOut, TEventMap, TDerives, E>, D>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives & {
         [K in E]: D;
-    }>;
-    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>>>, fallback?: (composer: Composer<TOut, TOut, {}>) => Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, cases: Partial<Record<K, Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>>>, fallback?: Middleware<TOut> | Middleware<TOut>[] | Composer<any, any, any>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    fork(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    tap(...middleware: Middleware<TOut>[]): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    lazy(factory: LazyFactory<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    onError(handler: ErrorHandler<TOut>): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): EventComposer<TBase, TEventMap, TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed, TDerives>;
-    error(kind: string, errorClass: {
-        new (...args: any): any;
-        prototype: Error;
-    }): this;
-    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives>;
-    group(fn: (composer: Composer<TOut, TOut, {}>) => void): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
-    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives>;
-    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives>;
+    }, TMethods> & TMethods;
+    when<UOut extends TOut>(condition: boolean, fn: (composer: Composer<TOut, TOut, {}>) => Composer<TOut, UOut, any>): EventComposer<TBase, TEventMap, TIn, TOut & Partial<Omit<UOut, keyof TOut>>, TExposed, TDerives, TMethods> & TMethods;
+    as(scope: "scoped" | "global"): EventComposer<TBase, TEventMap, TIn, TOut, TOut, TDerives, TMethods> & TMethods;
+    extend<UIn extends TBase, UOut extends UIn, UExposed extends object, UDerives extends Record<string, object>>(other: EventComposer<TBase, TEventMap, UIn, UOut, UExposed, UDerives, any>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives & UDerives, TMethods> & TMethods;
+    extend<UIn extends object, UOut extends UIn, UExposed extends object>(other: Composer<UIn, UOut, UExposed>): EventComposer<TBase, TEventMap, TIn, TOut & UExposed, TExposed, TDerives, TMethods> & TMethods;
     inspect(): MiddlewareInfo[];
     trace(handler: TraceHandler): this;
     compose(): ComposedMiddleware<TIn>;
@@ -189,16 +189,33 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
     };
     invalidate(): void;
 }
-interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>> {
-    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives>;
+interface EventComposerConstructor<TBase extends object, TEventMap extends Record<string, TBase>, TMethods extends Record<string, (...args: any[]) => any> = {}> {
+    new <TIn extends TBase = TBase, TOut extends TIn = TIn, TExposed extends object = {}, TDerives extends Record<string, object> = {}>(options?: ComposerOptions): EventComposer<TBase, TEventMap, TIn, TOut, TExposed, TDerives, TMethods> & TMethods;
 }
+/**
+ * Phantom type carrier for event map inference.
+ * Returns `undefined` at runtime — exists purely for type-level inference
+ * so that `TEventMap` can be inferred from the `types` config field.
+ *
+ * @example
+ * ```ts
+ * const { Composer } = createComposer({
+ *   discriminator: (ctx: BaseCtx) => ctx.updateType,
+ *   types: eventTypes<EventMap>(),
+ *   methods: { hears(trigger) { return this.on("message", ...); } },
+ * });
+ * ```
+ */
+declare function eventTypes<TEventMap extends Record<string, any>>(): TEventMap;
 /**
  * Creates a configured Composer class with type-safe .on() event discrimination.
  */
-declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}>(config: {
+declare function createComposer<TBase extends object, TEventMap extends Record<string, TBase> = {}, TMethods extends Record<string, (...args: any[]) => any> = {}>(config: {
     discriminator: (context: TBase) => string;
+    types?: TEventMap;
+    methods?: TMethods & ThisType<EventComposer<TBase, TEventMap, TBase, TBase, {}, {}, TMethods> & TMethods>;
 }): {
-    Composer: EventComposerConstructor<TBase, TEventMap>;
+    Composer: EventComposerConstructor<TBase, TEventMap, TMethods>;
     compose: typeof compose;
     EventQueue: typeof EventQueue;
 };
@@ -210,5 +227,5 @@ declare const skip: Middleware<any>;
 /** Terminal middleware: does NOT call next() */
 declare const stop: Middleware<any>;
 
-export { Composer, EventQueue, compose, createComposer, noopNext, skip, stop };
+export { Composer, EventQueue, compose, createComposer, eventTypes, noopNext, skip, stop };
 export type { ComposedMiddleware, ComposerOptions, DeriveHandler, ErrorHandler, EventComposer, EventComposerConstructor, LazyFactory, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler };

package/dist/index.js

@@ -308,15 +308,23 @@ class Composer {
       if (this["~"].extended.has(key)) return this;
       this["~"].extended.add(key);
     }
+    const alreadyExtended = new Set(this["~"].extended);
     for (const key of other["~"].extended) {
       this["~"].extended.add(key);
     }
     Object.assign(this["~"].errorsDefinitions, other["~"].errorsDefinitions);
     this["~"].onErrors.push(...other["~"].onErrors);
     const pluginName = other["~"].name;
-    const localMws = other["~"].middlewares.filter((m) => m.scope === "local");
-    const scopedMws = other["~"].middlewares.filter((m) => m.scope === "scoped");
-    const globalMws = other["~"].middlewares.filter((m) => m.scope === "global");
+    const isNew = (m) => {
+      if (!m.plugin) return true;
+      for (const key of alreadyExtended) {
+        if (key.startsWith(m.plugin + ":")) return false;
+      }
+      return true;
+    };
+    const localMws = other["~"].middlewares.filter((m) => m.scope === "local" && isNew(m));
+    const scopedMws = other["~"].middlewares.filter((m) => m.scope === "scoped" && isNew(m));
+    const globalMws = other["~"].middlewares.filter((m) => m.scope === "global" && isNew(m));
     if (localMws.length > 0) {
       const chain = compose(localMws.map((m) => m.fn));
       const isolated = async (ctx, next) => {
@@ -464,6 +472,9 @@ class EventQueue {
   }
 }
 
+function eventTypes() {
+  return void 0;
+}
 function createComposer(config) {
   class EventComposerImpl extends Composer {
     on(event, handler) {
@@ -501,6 +512,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,
@@ -508,4 +532,4 @@ function createComposer(config) {
   };
 }
 
-export { Composer, EventQueue, compose, createComposer, noopNext, skip, stop };
+export { Composer, EventQueue, compose, createComposer, eventTypes, noopNext, skip, stop };

package/package.json

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