@monixlite/grammy-scenes 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,8 @@
 # @monixlite/grammy-scenes
 
-A lightweight Finite State Machine (FSM) engine for Telegram bots built on grammY. The library provides step-based scenes with declarative definitions, session-backed state, deterministic transitions, and extensible navigation.
+A lightweight finite state machine (FSM) engine for Telegram bots built on grammY. The library provides declarative, step-based scenes with deterministic transitions, session-backed state, and minimal runtime overhead.
+
+The goal of the library is to stay simple and predictable: no hidden magic, no implicit state, and no tight coupling to bot logic. Everything is explicit and driven by return values.
 
 ---
 
@@ -14,20 +16,26 @@ npm install @monixlite/grammy-scenes
 
 ## Core Concepts
 
-A scene is a sequence of ordered steps grouped under a shared title. Each step is defined declaratively and reacts to Telegram updates via callbacks.
+### Scene
+
+A scene is a logical flow (for example: `auth`, `profile_edit`, `checkout`).
+
+### Step
 
-The active scene state is stored in `ctx.session.scene`.
+A step is a single state inside a scene. Steps are ordered in the same order they are declared.
 
-Each step definition contains:
+### FSM
 
-* scene identifier (title + step)
-* callbacks for lifecycle and update handling
+Internally, the library builds a finite state machine:
+
+* scene title → ordered step list
+* step → action handlers
 
 ---
 
 ## Basic Usage
 
-```
+```js
 const { Bot, session } = require("grammy");
 const { Scenes } = require("@monixlite/grammy-scenes");
 
@@ -95,26 +103,26 @@ const scenes = new Scenes([
 
                 callbacks: [
                     {
-                        match: /^confirm:yes$/,
-                        handler: async (ctx) => {
-                            const { phone } = ctx.session;
+                        match: /^confirm:(yes|no)$/,
+                        handler: async (ctx, match) => {
+                            await ctx.answerCallbackQuery();
 
 
-                            await ctx.answerCallbackQuery();
-                            await ctx.reply(`• Thank you! ${phone} saved.`);
+                            switch (match[1]) {
+                                case "yes": {
+                                    const { phone } = ctx.session;
 
 
-                            return "stop";
-                        },
-                    },
+                                    await ctx.reply(`• Thank you! Your phone number ${phone} has been saved.`);
 
-                    {
-                        match: /^confirm:no$/,
-                        handler: async (ctx) => {
-                            await ctx.answerCallbackQuery();
 
+                                    return "stop";
+                                };
 
-                            return "^phone";
+                                default: {
+                                    return "^phone";
+                                };
+                            };
                         },
                     },
                 ],
@@ -122,7 +130,7 @@ const scenes = new Scenes([
         },
     ],
 ], {
-    ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
+    ["inline_keyboard:scene:cancel"]: {
         enabled: true,
 
         component: {
@@ -146,7 +154,7 @@ bot.callbackQuery("scene:cancel", async (ctx) => {
 
 
 bot.command("start", async (ctx) => {
-    await scenes.enter(ctx, {
+    return await scenes.enter(ctx, {
         title: "auth",
         step: "phone",
     });
@@ -162,7 +170,7 @@ bot.start();
 
 ## Scene Definition
 
-```
+```js
 {
     scene: {
         title: string,
@@ -171,11 +179,15 @@ bot.start();
 
     action: {
         enter?: (ctx) => Promise<void>,
+
         update?: (ctx) => Promise<SceneResult | void>,
         message?: (ctx) => Promise<SceneResult | void>,
         callbacks?: Array<{
             match: RegExp,
-            handler: (ctx) => Promise<SceneResult | void>,
+            handler: (
+                ctx,
+                match: RegExpMatchArray,
+            ) => Promise<SceneResult | void>,
         }>,
     },
 }
@@ -228,7 +240,7 @@ Behavior:
 
 ### Manual Termination
 
-```
+```js
 ctx.session.scene = null;
 ```
 
@@ -236,7 +248,7 @@ ctx.session.scene = null;
 
 ## Middleware
 
-```
+```js
 bot.use(session(...));
 bot.use(scenes.middleware);
 ```
@@ -269,7 +281,7 @@ Transitions are driven by callback return values.
 
 Scene termination sets:
 
-```
+```js
 ctx.session.scene = null;
 ```
 
@@ -277,13 +289,38 @@ ctx.session.scene = null;
 
 ## Options
 
-### action:enter:extra:reply_markup:inline_keyboard:cancel
+Options are passed to the `Scenes` constructor and stored internally.
+
+```js
+const scenes = new Scenes(scenes, options, DEV);
+```
 
-Injects a cancel button into all `enter` replies.
+### action:enter:redefinition:reply
 
+Controls whether `ctx.reply` is temporarily patched during `enter`.
+
+When enabled, all `ctx.reply` calls inside `enter`:
+
+* preserve existing inline keyboards
+* automatically append the cancel button (if enabled)
+
+```js
+{
+    ["action:enter:redefinition:reply"]: {
+        enabled: true,
+    },
+}
 ```
+
+Disable this option if you want full manual control over `ctx.reply` behavior inside `enter`.
+
+### inline_keyboard:scene:cancel
+
+Automatically injects a cancel button into **all `enter` replies**.
+
+```js
 {
-    ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
+    ["inline_keyboard:scene:cancel"]: {
         enabled: true,
 
         component: {
@@ -296,8 +333,33 @@ Injects a cancel button into all `enter` replies.
 
 Notes:
 
-* Only affects `enter`
-* Cancellation logic is user-defined
+* Only affects `enter(ctx)` replies
+* Does not implement cancellation logic
+* The handler for `scene:cancel` is user-defined
+
+---
+
+## Accessing Options at Runtime
+
+Options passed to `Scenes` are stored internally and can be accessed via `scenes.option(name)`.
+
+This is useful when you need to reuse option configuration (for example, the cancel button component) outside of the scene lifecycle.
+
+Example:
+
+```js
+const cancel = scenes.option("inline_keyboard:scene:cancel");
+
+if (cancel?.enabled) {
+    console.log(cancel.component);
+    // { text: 'Cancel', callback_data: 'scene:cancel' }
+};
+```
+
+Notes:
+
+* Returns `null` if the option is not defined
+* The returned object is not cloned; treat it as read-only
 
 ---
 
@@ -311,6 +373,16 @@ Exports:
 
 * `scenes.middleware`
 * `scenes.enter(ctx, scene)`
+* `scenes.option(name)`
+
+### DEV mode
+
+When `DEV` is set to `true`, the middleware prints warnings to the console if:
+
+* a transition points to a missing step
+* there is no next / previous step in a scene
+
+This mode is intended for development and debugging only.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@monixlite/grammy-scenes",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Scene middleware for grammY with step-based navigation",
     "main": "src/index.js",
     "type": "commonjs",

package/src/index.js

@@ -29,7 +29,11 @@ class ScenesMiddleware {
 
 
         this.options = {
-            ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
+            ["action:enter:redefinition:reply"]: {
+                enabled: true,
+            },
+
+            ["inline_keyboard:scene:cancel"]: {
                 enabled: true,
 
                 component: {
@@ -78,20 +82,25 @@ class ScenesMiddleware {
         };
 
 
-        const original = ctx.reply.bind(ctx);
+        if (!this.options?.["action:enter:redefinition:reply"]?.enabled) return await current.action.enter(ctx);
+
+
+        const original = {
+            reply: ((typeof (ctx.reply) == "function") ? ctx.reply.bind(ctx) : null),
+        };
 
         try {
-            ctx.reply = (text, extra = {}) => {
+            if (original?.reply) ctx.reply = (text, extra = {}) => {
                 const keyboard = [
                     ...(extra.reply_markup?.inline_keyboard || []),
                 ]; {
-                    if (this.options?.["action:enter:extra:reply_markup:inline_keyboard:cancel"]?.enabled) keyboard.push([
-                        this.options?.["action:enter:extra:reply_markup:inline_keyboard:cancel"]?.component,
+                    if (this.options?.["inline_keyboard:scene:cancel"]?.enabled) keyboard.push([
+                        this.options?.["inline_keyboard:scene:cancel"]?.component,
                     ]);
                 };
 
 
-                return original(text, {
+                return original.reply(text, {
                     ...extra,
                     reply_markup: {
                         ...(extra?.reply_markup || {}),
@@ -103,7 +112,7 @@ class ScenesMiddleware {
 
             await current.action.enter(ctx);
         } finally {
-            ctx.reply = original;
+            if (original?.reply) ctx.reply = original.reply;
         };
     };
 
@@ -174,6 +183,11 @@ class ScenesMiddleware {
 
         const transition = String(result).match(/^\^(.*)$/); {
             if (!transition || !transition?.[1]) {
+                if (this.DEV) {
+                    console.warn(`[grammy-scenes] Invalid transition result:`, result);
+                };
+
+
                 ctx.session.scene = null;
                 return;
             };
@@ -231,20 +245,28 @@ class ScenesMiddleware {
 
 
             for (const q of current.action.callbacks) {
-                if (!q?.match?.test || !q?.handler) continue;
-
+                if (!(q?.match instanceof RegExp) || !q?.handler) continue;
 
-                if (q.match.test(data)) {
-                    const result = await q.handler(ctx);
 
-                    return await this.handle(ctx, scene, result);
+                const match = data.match(q.match); {
+                    if (!match) continue;
                 };
+
+
+                const result = await q.handler(ctx, match);
+
+                return await this.handle(ctx, scene, result);
             };
         };
 
 
         return next();
     };
+
+
+    option = (option) => {
+        return (this.options?.[option] ?? null);
+    };
 };
 
 
@@ -257,8 +279,11 @@ class Scenes {
         });
 
 
-        this.middleware = this.instance.middleware.bind(this.instance);
         this.enter = this.instance.enter.bind(this.instance);
+        this.middleware = this.instance.middleware.bind(this.instance);
+
+
+        this.option = this.instance.option.bind(this.instance);
     };
 };