@monixlite/grammy-scenes 1.2.2 → 1.3.0

package/README.md

@@ -1,7 +1,6 @@
 # @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 step-based scenes with declarative definitions, session-backed state, deterministic transitions, and extensible navigation.
 
 ---
 
@@ -11,11 +10,6 @@ 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
@@ -55,7 +49,7 @@ const scenes = new Scenes([
                 step: "phone",
             },
 
-            callbacks: {
+            action: {
                 enter: async (ctx) => {
                     await ctx.reply("• Enter your phone number:");
                 },
@@ -72,7 +66,7 @@ const scenes = new Scenes([
                 step: "confirm",
             },
 
-            callbacks: {
+            action: {
                 enter: async (ctx) => {
                     const { phone } = ctx.session;
 
@@ -88,6 +82,7 @@ const scenes = new Scenes([
                                         text: "• Yes",
                                         callback_data: "confirm:yes",
                                     },
+                                    
                                     {
                                         text: "• No",
                                         callback_data: "confirm:no",
@@ -98,7 +93,7 @@ const scenes = new Scenes([
                     });
                 },
 
-                query: [
+                callbacks: [
                     {
                         match: /^confirm:yes$/,
                         handler: async (ctx) => {
@@ -112,6 +107,7 @@ const scenes = new Scenes([
                             return "stop";
                         },
                     },
+
                     {
                         match: /^confirm:no$/,
                         handler: async (ctx) => {
@@ -126,7 +122,7 @@ const scenes = new Scenes([
         },
     ],
 ], {
-    "callbacks:enter:buttons:cancel": {
+    ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
         enabled: true,
 
         component: {
@@ -173,11 +169,11 @@ bot.start();
         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>,
         }>,
@@ -202,7 +198,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 +206,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.
@@ -281,14 +277,15 @@ ctx.session.scene = null;
 
 ## Options
 
-### callbacks:enter:buttons:cancel
+### action:enter:extra:reply_markup:inline_keyboard:cancel
 
 Injects a cancel button into all `enter` replies.
 
 ```
 {
-    "callbacks:enter:buttons:cancel": {
+    ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
         enabled: true,
+
         component: {
             text: "Cancel",
             callback_data: "scene:cancel",
@@ -306,9 +303,9 @@ Notes:
 
 ## API
 
-### new Scenes(scenes, options)
+### new Scenes(scenes, options, DEV?)
 
-Creates a scene manager.
+Creates a scene manager backed by `ScenesMiddleware`.
 
 Exports:
 

package/package.json

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

package/src/index.js

@@ -1,59 +1,68 @@
 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:extra:reply_markup:inline_keyboard: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,15 +74,19 @@ class ScenesMiddleware {
 
 
         const current = this.scene(scene); {
-            if (!current?.callbacks?.enter) return;
+            if (!current?.action?.enter) return;
         };
 
 
-        const original = ctx.reply.bind(ctx); {
+        const original = ctx.reply.bind(ctx);
+
+        try {
             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,
+                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,
                     ]);
                 };
 
@@ -81,15 +94,17 @@ class ScenesMiddleware {
                 return original(text, {
                     ...extra,
                     reply_markup: {
+                        ...(extra?.reply_markup || {}),
                         inline_keyboard: keyboard,
                     },
                 });
             };
-        };
 
 
-        await current.callbacks.enter(ctx);
-        ctx.reply = original;
+            await current.action.enter(ctx);
+        } finally {
+            ctx.reply = original;
+        };
     };
 
     handle = async (ctx, scene, result) => {
@@ -103,7 +118,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 +141,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, {
@@ -167,32 +202,38 @@ 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) {
+            for (const q of current.action.callbacks) {
+                if (!q?.match?.test || !q?.handler) continue;
+
+
                 if (q.match.test(data)) {
                     const result = await q.handler(ctx);
 
@@ -208,14 +249,15 @@ class ScenesMiddleware {
 
 
 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.middleware = this.instance.middleware.bind(this.instance);
         this.enter = this.instance.enter.bind(this.instance);
     };
 };