@monixlite/grammy-scenes 1.2.1 → 1.3.0

package/README.md

@@ -1,38 +1,33 @@
 # @monixlite/grammy-scenes
 
-A lightweight FSM (Finite State Machine) engine for Telegram bots built on grammY.
-The module implements step-based scenes with declarative step definitions, automatic transitions, session-based state management, and an extensible navigation system.
+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.
 
 ---
 
 ## Installation
 
-```bash
+```
 npm install @monixlite/grammy-scenes
 ```
 
-## Requirements
-
-• Node.js >= 16
-• grammY >= 1.19
-
 ---
 
-## Core Concept
+## 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.
 
-A scene is a sequence of steps united under a common title.
-Each step is described by an object containing:
+The active scene state is stored in `ctx.session.scene`.
 
-• scene and step identifiers
-• a set of callbacks reacting to Telegram events (enter, message, callbackQuery)
+Each step definition contains:
 
-The current scene state is stored in `ctx.session.scene`.
+* scene identifier (title + step)
+* callbacks for lifecycle and update handling
 
 ---
 
 ## Basic Usage
 
-```js
+```
 const { Bot, session } = require("grammy");
 const { Scenes } = require("@monixlite/grammy-scenes");
 
@@ -46,7 +41,7 @@ const bot = new Bot("..."); {
 };
 
 
-const scene = new Scenes([
+const scenes = new Scenes([
     [
         {
             scene: {
@@ -54,7 +49,7 @@ const scene = new Scenes([
                 step: "phone",
             },
 
-            callbacks: {
+            action: {
                 enter: async (ctx) => {
                     await ctx.reply("• Enter your phone number:");
                 },
@@ -71,26 +66,26 @@ const scene = new Scenes([
                 step: "confirm",
             },
 
-            callbacks: {
+            action: {
                 enter: async (ctx) => {
                     const { phone } = ctx.session;
 
 
-                    await ctx.reply(([
+                    await ctx.reply([
                         `• Your phone number: ${phone}`,
-                        `• Is this correct?`
-                    ]).join("\n"), {
+                        `• Is this correct?`,
+                    ].join("\n"), {
                         reply_markup: {
                             inline_keyboard: [
                                 [
                                     {
                                         text: "• Yes",
-                                        callback_data: "confirm:yes"
+                                        callback_data: "confirm:yes",
                                     },
-
+                                    
                                     {
                                         text: "• No",
-                                        callback_data: "confirm:no"
+                                        callback_data: "confirm:no",
                                     },
                                 ],
                             ],
@@ -98,7 +93,7 @@ const scene = new Scenes([
                     });
                 },
 
-                query: [
+                callbacks: [
                     {
                         match: /^confirm:yes$/,
                         handler: async (ctx) => {
@@ -106,12 +101,13 @@ const scene = new Scenes([
 
 
                             await ctx.answerCallbackQuery();
-                            await ctx.reply(`• Thank you! Your phone number ${phone} has been saved.`);
+                            await ctx.reply(`• Thank you! ${phone} saved.`);
 
 
                             return "stop";
                         },
                     },
+
                     {
                         match: /^confirm:no$/,
                         handler: async (ctx) => {
@@ -126,7 +122,7 @@ const scene = new Scenes([
         },
     ],
 ], {
-    ["callbacks:enter:buttons:cancel"]: {
+    ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
         enabled: true,
 
         component: {
@@ -144,19 +140,20 @@ bot.callbackQuery("scene:cancel", async (ctx) => {
     await ctx.editMessageReplyMarkup(null);
     await ctx.answerCallbackQuery();
 
-    await ctx.reply("• Scene cancelled!");
+
+    await ctx.reply("• Scene cancelled");
 });
 
 
 bot.command("start", async (ctx) => {
-    return await scene.enter(ctx, {
+    await scenes.enter(ctx, {
         title: "auth",
         step: "phone",
     });
 });
 
 
-bot.use(scene.middleware);
+bot.use(scenes.middleware);
 
 bot.start();
 ```
@@ -165,20 +162,18 @@ bot.start();
 
 ## Scene Definition
 
-Each scene step is described by the following structure:
-
-```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>,
         }>,
@@ -186,59 +181,35 @@ Each scene step is described by the following structure:
 }
 ```
 
-`SceneResult` is a value that determines the next transition (described below).
+`SceneResult` determines the next transition.
 
 ---
 
 ## Callbacks
 
-### callbacks.enter(ctx)
-
-Triggered when entering a scene step.
-Used to send messages, keyboards, or initialize data.
-
-Details:
-
-• Executed automatically on step entry
-• Can freely use `ctx.reply`
-• If the cancel button option is enabled, it is automatically appended to the inline keyboard
-
----
-
-### callbacks.update(ctx)
+### enter(ctx)
 
-Triggered on **any update** while the step is active.
+Executed on step entry.
 
-Details:
+* Used for messages and keyboards
+* Cancel button can be injected automatically
 
-• Executed before `message` and `query`
-• Receives the raw grammY context
-• Can be used for global step logic (timeouts, guards, media handling)
-• Return value controls navigation using standard SceneResult rules
-
----
+### update(ctx)
 
-### callbacks.message(ctx)
+Executed on any update while the step is active.
 
-Triggered when a text message is received while the step is active.
+* Runs before `message` and `callbacks`
+* Suitable for guards, timeouts, media
+* Return value controls navigation
 
----
+### message(ctx)
 
-### callbacks.query
+Triggered on text messages during the step.
 
-An array of `callbackQuery` handlers.
+### callbacks[]
 
-Each handler has the following shape:
-
-```js
-{
-    match: RegExp,
-    handler: async (ctx) => SceneResult
-}
-```
-
-When `match` matches `ctx.callbackQuery.data`, the corresponding handler is executed.
-Its return value is processed using the same transition logic as `callbacks.message`.
+CallbackQuery handlers matched by regexp.
+The handler return value follows standard transition rules.
 
 ---
 
@@ -246,120 +217,73 @@ Its return value is processed using the same transition logic as `callbacks.mess
 
 ### scenes.enter(ctx, scene)
 
-Forces entry into a scene and step.
-
-```js
-await scenes.enter(ctx, {
-    title: "auth",
-    step: "phone",
-});
-```
+Forces entering a scene step.
 
 Behavior:
 
-• Writes the scene into `ctx.session.scene`
-• Locates the step definition
-• Executes `callbacks.enter` if present
-• Temporarily overrides `ctx.reply` to append the cancel button
-
----
+* Writes to `ctx.session.scene`
+* Resolves step
+* Executes `enter`
+* Temporarily patches `ctx.reply` for cancel button injection
 
-### Cancel a Scene Manually
+### Manual Termination
 
-A scene can be terminated manually:
-
-```js
+```
 ctx.session.scene = null;
 ```
 
-After this, the middleware stops processing scene events.
-
 ---
 
 ## Middleware
 
-```js
+```
 bot.use(session(...));
 bot.use(scenes.middleware);
 ```
 
 The middleware:
 
-• Checks for an active scene in the session
-• Resolves the current step
-• Delegates updates to the appropriate callbacks
-• Executes step transitions
+* Resolves the active step
+* Dispatches updates to callbacks
+* Applies transitions
 
-The middleware **must** be registered after the session middleware.
+Must be registered after session middleware.
 
 ---
 
 ## Step Navigation
 
-Transitions are determined by the value returned from callbacks.
+Transitions are driven by callback return values.
 
-### Terminating a Scene
+### Transitions
 
-• `"stop"`, `"exit"`, `"!"`
-→ `ctx.session.scene = null`
+* `undefined`, `"next"`, `">"` → next step
+* `"prev"`, `"<"` → previous step
+* `"stop"`, `"exit"`, `"!"` → terminate scene
+* `"^step"` → jump within current scene
+* `"^scene:step"` → jump to another scene
+* `{ step }` → absolute step
+* `{ scene: { title, step } }` → absolute scene
 
----
-
-### All Transitions
+### Termination
 
-• `undefined` or `"next"` → move to the next step
-• `"stop" | "exit" | "!"` → terminate the scene
-• `"<" | "prev"` → move to the previous step
-• `">" | "next"` → move to the next step
-• `"^step"` → jump to a step within the current scene
-• `"^scene:step"` → jump to another scene
-• `{ step: "..." }` → jump to a specific step
-• `{ scene: { title, step } }` → jump to another scene
-
----
+Scene termination sets:
 
-### Relative Transitions
-
-• `undefined` / `"next"` / `">"` → next step
-• `"prev"` / `"<"` → previous step
-
----
-
-### Absolute Transitions
-
-• `"^step"` → step within the current scene
-• `"^scene:step"` → jump to another scene
-
----
-
-### Object-Based Transitions
-
-```js
-return { step: "confirm" };
 ```
-
-```js
-return {
-    scene: {
-        title: "auth",
-        step: "phone",
-    },
-};
+ctx.session.scene = null;
 ```
 
 ---
 
 ## Options
 
-Options are passed as the second argument to `new Scenes()`.
+### action:enter:extra:reply_markup:inline_keyboard:cancel
 
-### callbacks:enter:buttons:cancel
+Injects a cancel button into all `enter` replies.
 
-Adds a cancel button to all messages sent inside `callbacks.enter`.
-
-```js
+```
 {
-    "callbacks:enter:buttons:cancel": {
+    ["action:enter:extra:reply_markup:inline_keyboard:cancel"]: {
         enabled: true,
 
         component: {
@@ -370,29 +294,23 @@ Adds a cancel button to all messages sent inside `callbacks.enter`.
 }
 ```
 
-Behavior:
+Notes:
 
-• Works only inside `callbacks.enter`
-• The button is appended automatically
-• Scene cancellation logic must be implemented by the user
+* Only affects `enter`
+* Cancellation logic is user-defined
 
 ---
 
-## Scenes Class
-
-### new Scenes(scenes, options)
-
-Creates a scene manager instance.
+## API
 
-Parameters:
+### new Scenes(scenes, options, DEV?)
 
-• `scenes` — an array of grouped scene steps
-• `options` — configuration object
+Creates a scene manager backed by `ScenesMiddleware`.
 
 Exports:
 
-• `scenes.middleware` — grammY middleware
-• `scenes.enter(ctx, scene)` — method to enter a scene
+* `scenes.middleware`
+* `scenes.enter(ctx, scene)`
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@monixlite/grammy-scenes",
-    "version": "1.2.1",
+    "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);
     };
 };