@monixlite/grammy-scenes 1.2.2 → 1.4.0

package/README.md

@@ -1,7 +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.
 
 ---
 
@@ -11,29 +12,30 @@ The library provides step-based scenes with declarative definitions, session-bac
 npm install @monixlite/grammy-scenes
 ```
 
-## Requirements
-
-* Node.js >= 16
-* grammY >= 1.19
-
 ---
 
 ## 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`).
 
-The active scene state is stored in `ctx.session.scene`.
+### Step
 
-Each step definition contains:
+A step is a single state inside a scene. Steps are ordered in the same order they are declared.
 
-* scene identifier (title + step)
-* callbacks for lifecycle and update handling
+### FSM
+
+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");
 
@@ -55,7 +57,7 @@ const scenes = new Scenes([
                 step: "phone",
             },
 
-            callbacks: {
+            action: {
                 enter: async (ctx) => {
                     await ctx.reply("• Enter your phone number:");
                 },
@@ -72,7 +74,7 @@ const scenes = new Scenes([
                 step: "confirm",
             },
 
-            callbacks: {
+            action: {
                 enter: async (ctx) => {
                     const { phone } = ctx.session;
 
@@ -88,6 +90,7 @@ const scenes = new Scenes([
                                         text: "• Yes",
                                         callback_data: "confirm:yes",
                                     },
+                                    
                                     {
                                         text: "• No",
                                         callback_data: "confirm:no",
@@ -98,27 +101,28 @@ const scenes = new Scenes([
                     });
                 },
 
-                query: [
+                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";
-                        },
-                    },
-                    {
-                        match: /^confirm:no$/,
-                        handler: async (ctx) => {
-                            await ctx.answerCallbackQuery();
+                                    await ctx.reply(`• Thank you! Your phone number ${phone} has been saved.`);
 
 
-                            return "^phone";
+                                    return "stop";
+                                };
+
+                                default: {
+                                    return "^phone";
+                                };
+                            };
                         },
                     },
                 ],
@@ -126,7 +130,7 @@ const scenes = new Scenes([
         },
     ],
 ], {
-    "callbacks:enter:buttons:cancel": {
+    ["inline_keyboard:scene:cancel"]: {
         enabled: true,
 
         component: {
@@ -150,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",
     });
@@ -166,20 +170,24 @@ bot.start();
 
 ## Scene Definition
 
-```
+```js
 {
     scene: {
         title: string,
         step: string,
     },
 
-    callbacks: {
+    action: {
         enter?: (ctx) => Promise<void>,
+
         update?: (ctx) => Promise<SceneResult | void>,
         message?: (ctx) => Promise<SceneResult | void>,
-        query?: Array<{
+        callbacks?: Array<{
             match: RegExp,
-            handler: (ctx) => Promise<SceneResult | void>,
+            handler: (
+                ctx,
+                match: RegExpMatchArray,
+            ) => Promise<SceneResult | void>,
         }>,
     },
 }
@@ -202,7 +210,7 @@ Executed on step entry.
 
 Executed on any update while the step is active.
 
-* Runs before `message` and `query`
+* Runs before `message` and `callbacks`
 * Suitable for guards, timeouts, media
 * Return value controls navigation
 
@@ -210,7 +218,7 @@ Executed on any update while the step is active.
 
 Triggered on text messages during the step.
 
-### query[]
+### callbacks[]
 
 CallbackQuery handlers matched by regexp.
 The handler return value follows standard transition rules.
@@ -232,7 +240,7 @@ Behavior:
 
 ### Manual Termination
 
-```
+```js
 ctx.session.scene = null;
 ```
 
@@ -240,7 +248,7 @@ ctx.session.scene = null;
 
 ## Middleware
 
-```
+```js
 bot.use(session(...));
 bot.use(scenes.middleware);
 ```
@@ -273,7 +281,7 @@ Transitions are driven by callback return values.
 
 Scene termination sets:
 
-```
+```js
 ctx.session.scene = null;
 ```
 
@@ -281,14 +289,40 @@ ctx.session.scene = null;
 
 ## Options
 
-### callbacks:enter:buttons:cancel
+Options are passed to the `Scenes` constructor and stored internally.
 
-Injects a cancel button into all `enter` replies.
+```js
+const scenes = new Scenes(scenes, options, DEV);
+```
+
+### 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
 {
-    "callbacks:enter:buttons:cancel": {
+    ["inline_keyboard:scene:cancel"]: {
         enabled: true,
+
         component: {
             text: "Cancel",
             callback_data: "scene:cancel",
@@ -299,21 +333,56 @@ 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
 
 ---
 
 ## API
 
-### new Scenes(scenes, options)
+### new Scenes(scenes, options, DEV?)
 
-Creates a scene manager.
+Creates a scene manager backed by `ScenesMiddleware`.
 
 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.2.2",
+    "version": "1.4.0",
     "description": "Scene middleware for grammY with step-based navigation",
     "main": "src/index.js",
     "type": "commonjs",

package/src/index.js

@@ -1,59 +1,72 @@
 class ScenesMiddleware {
     constructor({
         scenes,
-        options = {},
+        options,
+        DEV,
     }) {
         this.scenes = scenes;
 
-        this.steps = {}; {
+
+        this.map = {}; {
             for (const group of scenes) {
                 for (const item of group) {
                     const { title, step } = item.scene;
 
 
-                    if (!this.steps[title]) {
-                        this.steps[title] = [];
+                    if (!this.map[title]) {
+                        this.map[title] = {
+                            order: [],
+                            steps: {},
+                        };
                     };
 
 
-                    this.steps[title].push(step);
+                    this.map[title].order.push(step);
+                    this.map[title].steps[step] = item;
                 };
             };
         };
 
 
         this.options = {
-            ["callbacks:enter:buttons:cancel"]: {
+            ["action:enter:redefinition:reply"]: {
+                enabled: true,
+            },
+
+            ["inline_keyboard:scene:cancel"]: {
                 enabled: true,
 
                 component: {
-                    text: "Отменить",
+                    text: "Cancel",
                     callback_data: "scene:cancel",
                 },
             },
 
             ...options,
         };
+
+
+        this.DEV = DEV;
     };
 
 
     scene = (scene) => {
-        return this.scenes.flat().find((x) => (x.scene.title == scene?.title && x.scene.step == scene?.step));
+        return (this.map?.[scene?.title]?.steps?.[scene?.step] ?? null);
     };
 
     step = (scene, dir) => {
-        const list = this.steps[scene?.title]; {
-            if (!list) return null;
+        const entry = this.map?.[scene?.title]; {
+            if (!entry) return null;
         };
 
 
-        const index = list.indexOf(scene?.step); {
+        const index = entry.order.indexOf(scene?.step); {
             if (index == -1) return null;
         };
 
 
-        if (dir == "next") return (list[(index + 1)] ?? null);
-        if (dir == "prev") return (list[(index - 1)] ?? null);
+        if (dir == "next") return (entry.order[(index + 1)] ?? null);
+        if (dir == "prev") return (entry.order[(index - 1)] ?? null);
 
 
         return null;
@@ -65,31 +78,42 @@ class ScenesMiddleware {
 
 
         const current = this.scene(scene); {
-            if (!current?.callbacks?.enter) return;
+            if (!current?.action?.enter) return;
         };
 
 
-        const original = ctx.reply.bind(ctx); {
-            ctx.reply = (text, extra = {}) => {
-                const keyboard = (extra.reply_markup?.inline_keyboard || []); {
-                    if (this.options?.["callbacks:enter:buttons:cancel"]?.enabled) keyboard.push([
-                        this.options?.["callbacks:enter:buttons:cancel"]?.component,
+        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 {
+            if (original?.reply) ctx.reply = (text, extra = {}) => {
+                const keyboard = [
+                    ...(extra.reply_markup?.inline_keyboard || []),
+                ]; {
+                    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 || {}),
                         inline_keyboard: keyboard,
                     },
                 });
             };
-        };
 
 
-        await current.callbacks.enter(ctx);
-        ctx.reply = original;
+            await current.action.enter(ctx);
+        } finally {
+            if (original?.reply) ctx.reply = original.reply;
+        };
     };
 
     handle = async (ctx, scene, result) => {
@@ -103,7 +127,17 @@ class ScenesMiddleware {
             const step = this.step({
                 title: scene.title,
                 step: scene.step,
-            }, "prev");
+            }, "prev"); {
+                if (!step) {
+                    if (this.DEV) {
+                        console.warn(`[grammy-scenes] No previous step found for scene "${scene.title}" (current step: "${scene.step}")`);
+                    };
+
+
+                    ctx.session.scene = null;
+                    return;
+                };
+            };
 
 
             return await this.enter(ctx, {
@@ -116,7 +150,17 @@ class ScenesMiddleware {
             const step = this.step({
                 title: scene.title,
                 step: scene.step,
-            }, "next");
+            }, "next"); {
+                if (!step) {
+                    if (this.DEV) {
+                        console.warn(`[grammy-scenes] No next step found for scene "${scene.title}" (current step: "${scene.step}")`);
+                    };
+
+
+                    ctx.session.scene = null;
+                    return;
+                };
+            };
 
 
             return await this.enter(ctx, {
@@ -139,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;
             };
@@ -167,56 +216,74 @@ class ScenesMiddleware {
 
 
         const current = this.scene(scene); {
-            if (!current?.callbacks) return next();
+            if (!current?.action) return next();
         };
 
 
-        if (ctx?.update && current.callbacks?.update) {
-            const result = await current.callbacks.update(ctx);
+        if (ctx?.update && current.action?.update) {
+            const result = await current.action.update(ctx);
 
             return await this.handle(ctx, scene, result);
         };
 
 
-        if (ctx?.message && current.callbacks?.message) {
+        if (ctx?.message && current.action?.message) {
             if (ctx?.message?.caption) ctx.message.text ??= ctx.message.caption;
 
 
-            const result = await current.callbacks.message(ctx);
+            const result = await current.action.message(ctx);
 
             return await this.handle(ctx, scene, result);
         };
 
 
-        if (ctx?.callbackQuery && current.callbacks?.query) {
+        if (ctx?.callbackQuery && current.action?.callbacks) {
+            if (!Array.isArray(current.action.callbacks)) return next();
+
+
             const data = ctx.callbackQuery.data;
 
 
-            for (const q of current.callbacks.query) {
-                if (q.match.test(data)) {
-                    const result = await q.handler(ctx);
+            for (const q of current.action.callbacks) {
+                if (!(q?.match instanceof RegExp) || !q?.handler) continue;
 
-                    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);
+    };
 };
 
 
 class Scenes {
-    constructor(scenes, options = {}) {
+    constructor(scenes = [], options = {}, DEV = false) {
         this.instance = new ScenesMiddleware({
             scenes: scenes,
             options: options,
+            DEV: DEV,
         });
 
 
-        this.middleware = this.instance.middleware;
         this.enter = this.instance.enter.bind(this.instance);
+        this.middleware = this.instance.middleware.bind(this.instance);
+
+
+        this.option = this.instance.option.bind(this.instance);
     };
 };