@gramio/composer 0.3.4 → 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;

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>;
@@ -332,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;
@@ -515,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>;
@@ -332,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;
@@ -515,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;

package/package.json

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