@gramio/composer 0.3.3 → 0.4.0

package/dist/index.cjs

@@ -81,6 +81,7 @@ class Composer {
     errorsDefinitions: {},
     tracer: void 0,
     macros: {},
+    commandsMeta: /* @__PURE__ */ new Map(),
     /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
     Out: void 0
   };
@@ -280,6 +281,11 @@ class Composer {
       }
       Object.assign(this["~"].errorsDefinitions, temp["~"].errorsDefinitions);
       this["~"].onErrors.push(...temp["~"].onErrors);
+      if (temp["~"].commandsMeta) {
+        for (const [cmd, meta] of temp["~"].commandsMeta) {
+          this["~"].commandsMeta.set(cmd, meta);
+        }
+      }
       for (const key of temp["~"].extended) {
         this["~"].extended.add(key);
       }
@@ -339,6 +345,11 @@ class Composer {
     Object.assign(this["~"].errorsDefinitions, other["~"].errorsDefinitions);
     Object.assign(this["~"].macros, other["~"].macros);
     this["~"].onErrors.push(...other["~"].onErrors);
+    if (other["~"].commandsMeta) {
+      for (const [cmd, meta] of other["~"].commandsMeta) {
+        this["~"].commandsMeta.set(cmd, meta);
+      }
+    }
     const pluginName = other["~"].name;
     const isNew = (m) => {
       if (!m.plugin) return true;
@@ -386,6 +397,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

@@ -124,6 +124,22 @@ interface ComposerOptions {
     name?: string;
     seed?: unknown;
 }
+/** Shorthand strings for common BotCommandScope types */
+type ScopeShorthand = "default" | "all_private_chats" | "all_group_chats" | "all_chat_administrators";
+/**
+ * Metadata for a bot command, used by `syncCommands()` to push
+ * descriptions, localized names, and visibility scopes to the Telegram API.
+ */
+interface CommandMeta<TScope = any> {
+    /** Command description shown in the Telegram menu (1-256 chars) */
+    description: string;
+    /** Localized descriptions keyed by IETF language tag */
+    locales?: Record<string, string>;
+    /** Where this command is visible. Default: `["default"]` */
+    scopes?: (TScope | ScopeShorthand)[];
+    /** Exclude this command from `syncCommands()`. The handler still works. @default false */
+    hide?: boolean;
+}
 
 /**
  * Compose an array of middleware functions into a single middleware.
@@ -154,6 +170,7 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
         }>;
         tracer: TraceHandler | undefined;
         macros: Record<string, MacroDef<any, any>>;
+        commandsMeta: Map<string, CommandMeta<any>>;
         /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
         Out: TOut;
     };
@@ -174,7 +191,8 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
     derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
         as: "scoped" | "global";
     }): Composer<TIn, TOut & D, TExposed & D>;
-    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): Composer<TIn, TOut, TExposed>;
+    guard<S extends TOut>(predicate: (context: TOut) => context is S): Composer<TIn, S, TExposed>;
+    guard(predicate: (context: TOut) => boolean | Promise<boolean>, ...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
     branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): Composer<TIn, TOut, TExposed>;
     route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): Composer<TIn, TOut, TExposed>;
     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>): Composer<TIn, TOut, TExposed>;
@@ -191,6 +209,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 +333,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>;
@@ -317,6 +350,7 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
         }>;
         tracer: TraceHandler | undefined;
         macros: Record<string, MacroDef<any, any>>;
+        commandsMeta: Map<string, CommandMeta>;
         Derives: TDerives;
         /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
         Out: TOut;
@@ -500,4 +534,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, EventContextOf, HandlerOptions, LazyFactory, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler, WithCtx };
+export type { CommandMeta, 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, ScopeShorthand, TraceHandler, WithCtx };

package/dist/index.d.ts

@@ -124,6 +124,22 @@ interface ComposerOptions {
     name?: string;
     seed?: unknown;
 }
+/** Shorthand strings for common BotCommandScope types */
+type ScopeShorthand = "default" | "all_private_chats" | "all_group_chats" | "all_chat_administrators";
+/**
+ * Metadata for a bot command, used by `syncCommands()` to push
+ * descriptions, localized names, and visibility scopes to the Telegram API.
+ */
+interface CommandMeta<TScope = any> {
+    /** Command description shown in the Telegram menu (1-256 chars) */
+    description: string;
+    /** Localized descriptions keyed by IETF language tag */
+    locales?: Record<string, string>;
+    /** Where this command is visible. Default: `["default"]` */
+    scopes?: (TScope | ScopeShorthand)[];
+    /** Exclude this command from `syncCommands()`. The handler still works. @default false */
+    hide?: boolean;
+}
 
 /**
  * Compose an array of middleware functions into a single middleware.
@@ -154,6 +170,7 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
         }>;
         tracer: TraceHandler | undefined;
         macros: Record<string, MacroDef<any, any>>;
+        commandsMeta: Map<string, CommandMeta<any>>;
         /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
         Out: TOut;
     };
@@ -174,7 +191,8 @@ declare class Composer<TIn extends object = {}, TOut extends TIn = TIn, TExposed
     derive<D extends object>(handler: DeriveHandler<TOut, D>, options: {
         as: "scoped" | "global";
     }): Composer<TIn, TOut & D, TExposed & D>;
-    guard<S extends TOut>(predicate: ((context: TOut) => context is S) | ((context: TOut) => boolean | Promise<boolean>), ...middleware: Middleware<any>[]): Composer<TIn, TOut, TExposed>;
+    guard<S extends TOut>(predicate: (context: TOut) => context is S): Composer<TIn, S, TExposed>;
+    guard(predicate: (context: TOut) => boolean | Promise<boolean>, ...middleware: Middleware<TOut>[]): Composer<TIn, TOut, TExposed>;
     branch(predicate: ((context: TOut) => boolean | Promise<boolean>) | boolean, onTrue: Middleware<TOut>, onFalse?: Middleware<TOut>): Composer<TIn, TOut, TExposed>;
     route<K extends string>(router: (context: TOut) => K | undefined | Promise<K | undefined>, builder: (route: RouteBuilder<TOut, K>) => void): Composer<TIn, TOut, TExposed>;
     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>): Composer<TIn, TOut, TExposed>;
@@ -191,6 +209,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 +333,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>;
@@ -317,6 +350,7 @@ interface EventComposer<TBase extends object, TEventMap extends Record<string, T
         }>;
         tracer: TraceHandler | undefined;
         macros: Record<string, MacroDef<any, any>>;
+        commandsMeta: Map<string, CommandMeta>;
         Derives: TDerives;
         /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
         Out: TOut;
@@ -500,4 +534,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, EventContextOf, HandlerOptions, LazyFactory, MacroDef, MacroDefinitions, MacroDeriveType, MacroHooks, MacroOptionType, MaybeArray, Middleware, MiddlewareInfo, MiddlewareType, Next, RouteBuilder, RouteHandler, Scope, TraceHandler, WithCtx };
+export type { CommandMeta, 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, ScopeShorthand, TraceHandler, WithCtx };

package/dist/index.js

@@ -78,6 +78,7 @@ class Composer {
     errorsDefinitions: {},
     tracer: void 0,
     macros: {},
+    commandsMeta: /* @__PURE__ */ new Map(),
     /** Phantom type accessor — never set at runtime, used by `ContextOf<T>` */
     Out: void 0
   };
@@ -277,6 +278,11 @@ class Composer {
       }
       Object.assign(this["~"].errorsDefinitions, temp["~"].errorsDefinitions);
       this["~"].onErrors.push(...temp["~"].onErrors);
+      if (temp["~"].commandsMeta) {
+        for (const [cmd, meta] of temp["~"].commandsMeta) {
+          this["~"].commandsMeta.set(cmd, meta);
+        }
+      }
       for (const key of temp["~"].extended) {
         this["~"].extended.add(key);
       }
@@ -336,6 +342,11 @@ class Composer {
     Object.assign(this["~"].errorsDefinitions, other["~"].errorsDefinitions);
     Object.assign(this["~"].macros, other["~"].macros);
     this["~"].onErrors.push(...other["~"].onErrors);
+    if (other["~"].commandsMeta) {
+      for (const [cmd, meta] of other["~"].commandsMeta) {
+        this["~"].commandsMeta.set(cmd, meta);
+      }
+    }
     const pluginName = other["~"].name;
     const isNew = (m) => {
       if (!m.plugin) return true;
@@ -383,6 +394,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.3",
+	"version": "0.4.0",
 	"description": "General-purpose, type-safe middleware composition library for TypeScript",
 	"main": "dist/index.cjs",
 	"module": "dist/index.js",