Scene-as-composer: builder step API, reusable modules, full Composer DSL on Scene

.github/workflows/publish.yml

@@ -13,6 +13,16 @@ on:
                 required: false
                 type: boolean
                 default: true
+            npm_tag:
+                description: "NPM dist-tag (latest | beta | next | …)"
+                required: false
+                type: string
+                default: "latest"
+            github_release_prerelease:
+                description: "Mark GitHub release as prerelease"
+                required: false
+                type: boolean
+                default: false
 
 permissions:
     contents: write
@@ -52,7 +62,7 @@ jobs:
 
             - name: Publish package to NPM
               if: ${{ github.event.inputs.publish_to_npm }}
-              run: bun publish --access public
+              run: bun publish --access public --tag ${{ github.event.inputs.npm_tag }}
               env:
                   NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
 
@@ -64,5 +74,5 @@ jobs:
                   name: v${{ steps.changelog.outputs.version }}
                   body: ${{ steps.changelog.outputs.changelog }}
                   draft: false
-                  prerelease: false
+                  prerelease: ${{ github.event.inputs.github_release_prerelease == 'true' }}
                   generateReleaseNotes: true

.gitignore

@@ -10,7 +10,7 @@ yarn-error.log*
 lerna-debug.log*
 .pnpm-debug.log*
 
-# Caches 
+# Caches
 
 .cache
 
@@ -176,3 +176,4 @@ dist
 
 test.ts
 tg-bot-api
+.research

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gramio/scenes",
-	"version": "0.6.0",
+	"version": "0.7.0-beta.1",
 	"description": "Scenes plugin for GramIO",
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.js",
@@ -24,7 +24,9 @@
 	"readme": "https://gramio.dev/plugins/official/scenes",
 	"scripts": {
 		"prepublishOnly": "bunx pkgroll",
-		"generate": "bun scripts/generate.ts"
+		"generate": "bun scripts/generate.ts",
+		"test": "bun test",
+		"test:types": "tsc --noEmit --project tsconfig.test.json"
 	},
 	"keywords": [
 		"gramio",
@@ -41,17 +43,18 @@
 		"@gramio/test": "^0.3.1",
 		"@standard-schema/spec": "^1.0.0",
 		"@types/bun": "^1.3.10",
-		"gramio": "^0.7.0",
+		"gramio": "^0.10.0",
 		"pkgroll": "^2.27.0",
 		"typescript": "^5.7.2",
 		"zod": "^3.25.4"
 	},
 	"peerDependencies": {
-		"gramio": ">=0.7.0"
+		"gramio": ">=0.9.0"
 	},
 	"files": ["dist"],
 	"license": "MIT",
 	"dependencies": {
+		"@gramio/composer": "^0.4.1",
 		"@gramio/storage": "^2.0.0"
 	}
 }

src/index.ts

@@ -132,9 +132,8 @@ export function scenes(scenes: AnyScene[], options?: ScenesOptions) {
 				scenes,
 			);
 
-			return scene.run(
-				// @ts-ignore
-				context,
+			return scene.dispatchActive(
+				context as any,
 				storage,
 				key,
 				sceneData,

src/scene-composer.ts

@@ -0,0 +1,38 @@
+import {
+	createComposer,
+	eventTypes,
+} from "@gramio/composer";
+import {
+	_composerMethods,
+	type Bot,
+	type Context,
+	type ContextsMapping,
+} from "gramio";
+
+type AnyBot = Bot<any, any, any>;
+type TelegramEventMap = {
+	[K in keyof ContextsMapping<AnyBot>]: InstanceType<ContextsMapping<AnyBot>[K]>;
+};
+
+/**
+ * Base class for `Scene`. Produced by `createComposer` with the gramio method
+ * table (`.command/.callbackQuery/.hears/.on/.use/.derive/.guard/.branch/.when/
+ * .extend/...`) so a `Scene` instance has the full bot-level DSL out of the
+ * box. Scene-specific methods (`.params/.state/.exitData/.onEnter/.onExit/
+ * .step/.ask`) are added by the `Scene` subclass.
+ *
+ * Generic slots are left at default (`{}` / no derive accumulation) — Scene
+ * tracks its own type chain via the `Derives` generic on the subclass, and
+ * `.extend()` merges plugin/composer types into that chain.
+ */
+export const { Composer: SceneComposerBase } = createComposer<
+	Context<AnyBot>,
+	TelegramEventMap,
+	typeof _composerMethods
+>({
+	discriminator: (ctx: Context<AnyBot>) => (ctx as any).updateType,
+	types: eventTypes<TelegramEventMap>(),
+	methods: _composerMethods,
+});
+
+export type SceneComposerBaseInstance = InstanceType<typeof SceneComposerBase>;

src/scene-internals.ts

@@ -0,0 +1,70 @@
+import type { Handler, Stringable } from "gramio";
+
+export type SceneLifecycleHandler = (ctx: any) => unknown | Promise<unknown>;
+
+/**
+ * Per-step record stored on a Scene's `~scene.steps` array.
+ *
+ * Each step is a sub-composer (StepComposer) plus lifecycle hooks
+ * registered via `c.enter()` / `c.exit()` / `c.fallback()` / `c.message()`.
+ *
+ * `composer` is typed as `unknown` here to avoid a circular import with
+ * `step-composer.ts`; consumers cast to the concrete StepComposer type at
+ * the use site.
+ */
+export interface SceneStepEntry {
+	id: string | number;
+	composer: unknown;
+	enter?: Handler<any>;
+	exit?: Handler<any>;
+	fallback?: Handler<any>;
+	/**
+	 * Sugar set by `c.message(text | factory)`. When present and the step's
+	 * `enter` hook is not, the runtime sends this on first entry.
+	 */
+	message?: Stringable | ((ctx: any) => Stringable | Promise<Stringable>);
+	/**
+	 * Event whitelist set by `c.events(["message"])` or step options.
+	 * `undefined` ⇒ default (`"message" | "callback_query"`).
+	 */
+	events?: readonly string[];
+}
+
+/**
+ * Scene-specific state that lives alongside the Composer's `~` slot.
+ * Stored at `scene["~scene"]` to avoid colliding with composer internals
+ * and to keep augmentation of `@gramio/composer` unnecessary.
+ */
+export interface SceneInternals<
+	Params = unknown,
+	State extends Record<string | number, any> = Record<string | number, any>,
+	ExitData = unknown,
+> {
+	steps: SceneStepEntry[];
+	stepsCount: number;
+	/** scene-level onEnter — single-arg, not middleware */
+	enter?: SceneLifecycleHandler;
+	/** scene-level onExit (lands in step 8) */
+	exit?: SceneLifecycleHandler;
+	isModule: boolean;
+	// Type-only carriers — never read at runtime, used so `params<T>()` /
+	// `state<T>()` / `exitData<T>()` carry the user's types through Scene's
+	// structural shape (so `Scene<{id}>` and `Scene<never>` are distinct
+	// types at the call-site level — needed for SceneEnterHandler arity).
+	params: Params;
+	state: State;
+	exitData: ExitData;
+}
+
+export function createSceneInternals(name: string | undefined): SceneInternals {
+	return {
+		steps: [],
+		stepsCount: 0,
+		enter: undefined,
+		exit: undefined,
+		isModule: name === undefined,
+		params: undefined,
+		state: {} as Record<string | number, any>,
+		exitData: undefined,
+	};
+}