@monixlite/grammy-scenes 1.2.0 → 1.2.2

package/README.md

@@ -1,38 +1,39 @@
 # @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
+* 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 +47,7 @@ const bot = new Bot("..."); {
 };
 
 
-const scene = new Scenes([
+const scenes = new Scenes([
     [
         {
             scene: {
@@ -76,21 +77,20 @@ const scene = new Scenes([
                     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",
                                     },
                                 ],
                             ],
@@ -106,7 +106,7 @@ 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";
@@ -126,7 +126,7 @@ const scene = new Scenes([
         },
     ],
 ], {
-    ["callbacks:enter:buttons:cancel"]: {
+    "callbacks:enter:buttons:cancel": {
         enabled: true,
 
         component: {
@@ -144,19 +144,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,9 +166,7 @@ bot.start();
 
 ## Scene Definition
 
-Each scene step is described by the following structure:
-
-```js
+```
 {
     scene: {
         title: string,
@@ -186,59 +185,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.
+### enter(ctx)
 
-Details:
+Executed on step entry.
 
-• 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
+* Used for messages and keyboards
+* Cancel button can be injected automatically
 
----
+### update(ctx)
 
-### callbacks.update(ctx)
+Executed on any update while the step is active.
 
-Triggered on **any update** while the step is active.
+* Runs before `message` and `query`
+* Suitable for guards, timeouts, media
+* Return value controls navigation
 
-Details:
+### message(ctx)
 
-• 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
+Triggered on text messages during the step.
 
----
+### query[]
 
-### callbacks.message(ctx)
-
-Triggered when a text message is received while the step is active.
-
----
-
-### callbacks.query
-
-An array of `callbackQuery` handlers.
-
-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,122 +221,74 @@ 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
-
----
-
-### Cancel a Scene Manually
+* Writes to `ctx.session.scene`
+* Resolves step
+* Executes `enter`
+* Temporarily patches `ctx.reply` for cancel button injection
 
-A scene can be terminated manually:
+### Manual Termination
 
-```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.
-
-### Terminating a Scene
+Transitions are driven by callback return values.
 
-• `"stop"`, `"exit"`, `"!"`
-→ `ctx.session.scene = null`
+### Transitions
 
----
-
-### All Transitions
+* `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
 
-• `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
-
----
+### Termination
 
-### Relative Transitions
-
-• `undefined` / `"next"` / `">"` → next step
-• `"prev"` / `"<"` → previous step
-
----
-
-### Absolute Transitions
-
-• `"^step"` → step within the current scene
-• `"^scene:step"` → jump to another scene
-
----
+Scene termination sets:
 
-### 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()`.
-
 ### callbacks:enter:buttons:cancel
 
-Adds a cancel button to all messages sent inside `callbacks.enter`.
+Injects a cancel button into all `enter` replies.
 
-```js
+```
 {
     "callbacks:enter:buttons:cancel": {
         enabled: true,
-
         component: {
             text: "Cancel",
             callback_data: "scene:cancel",
@@ -370,29 +297,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
+## API
 
 ### new Scenes(scenes, options)
 
-Creates a scene manager instance.
-
-Parameters:
-
-• `scenes` — an array of grouped scene steps
-• `options` — configuration object
+Creates a scene manager.
 
 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.0",
+    "version": "1.2.2",
     "description": "Scene middleware for grammY with step-based navigation",
     "main": "src/index.js",
     "type": "commonjs",