@yaebal/conversation 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @yaebal/conversation
+
+write multi-step dialogs as straight async functions — a coroutine approach where `cv.wait()` resolves with the next update for that chat.
+
+## install
+
+```sh
+pnpm add @yaebal/conversation
+```
+
+## usage
+
+```ts
+import { conversation, createConversation } from "@yaebal/conversation";
+
+const greet = createConversation("greet", async (cv, ctx) => {
+  await ctx.send("what's your name?");
+  
+  const answer = await cv.wait();
+  await answer.send(`hi ${answer.text}! nice to meet you.`);
+});
+
+const bot = new Bot(token).install(conversation([greet]));
+
+bot.command("greet", (ctx) => ctx.conversation.enter("greet"));
+```
+
+while a conversation is active it owns the chat's updates — they don't reach other handlers. state is in-memory (lost on restart), similar to `@yaebal/scenes`.
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,48 @@
+import type { Context, Plugin } from "@yaebal/core";
+/**
+ * @yaebal/conversation — write multi-step dialogs as a straight line:
+ *
+ *   const greet = createConversation("greet", async (cv, ctx) => {
+ *     await ctx.send("what's your name?");
+ *
+ *     const answer = await cv.wait();
+ *     await answer.send(`hi ${answer.text}`);
+ *   });
+ *   bot.install(conversation([greet]));
+ *   bot.command("greet", (ctx) => ctx.conversation.enter("greet"));
+ *
+ * it's a COROUTINE, not a replay engine (grammY-style): the builder runs once,
+ * detached, and `cv.wait()` resolves with the next update for that chat. while a
+ * conversation is active it OWNS the chat's updates (they don't reach other
+ * handlers). state is in-memory, lost on restart — like `prompt`/`scenes`.
+ */
+export interface Conversation {
+    /** resolve with the next update's context for this chat. */
+    wait(): Promise<Context>;
+    /** the most recent context (the entering update, then each waited one). */
+    readonly ctx: Context;
+}
+export type ConversationBuilder = (cv: Conversation, ctx: Context) => void | Promise<void>;
+export interface ConversationDef {
+    name: string;
+    builder: ConversationBuilder;
+}
+export declare function createConversation(name: string, builder: ConversationBuilder): ConversationDef;
+export interface ConversationControl {
+    /** start a registered conversation for this chat. */
+    enter(name: string): void;
+    /** whether a conversation is currently running for this chat. */
+    active(): boolean;
+    /** abandon the active conversation (its coroutine is left parked). */
+    leave(): void;
+}
+export interface ConversationOptions {
+    /** conversation key for an update. default: per-chat (`ctx.chat.id`). */
+    getKey?: (ctx: Context) => string | undefined;
+    /** called if a conversation builder throws. */
+    onError?: (error: unknown, ctx: Context) => void;
+}
+export declare function conversation(defs: ConversationDef[], options?: ConversationOptions): Plugin<Context, {
+    conversation: ConversationControl;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,mBAAmB,CAAC;CAC7B;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAE9F;AAED,MAAM,WAAW,mBAAmB;IACnC,qDAAqD;IACrD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iEAAiE;IACjE,MAAM,IAAI,OAAO,CAAC;IAClB,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IACnC,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9C,+CAA+C;IAC/C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAQD,wBAAgB,YAAY,CAC3B,IAAI,EAAE,eAAe,EAAE,EACvB,OAAO,GAAE,mBAAwB,GAC/B,MAAM,CAAC,OAAO,EAAE;IAAE,YAAY,EAAE,mBAAmB,CAAA;CAAE,CAAC,CA+ExD"}

package/lib/index.js

@@ -0,0 +1,74 @@
+export function createConversation(name, builder) {
+    return { name, builder };
+}
+export function conversation(defs, options = {}) {
+    const registry = new Map(defs.map((d) => [d.name, d]));
+    const sessions = new Map();
+    const getKey = options.getKey ?? ((ctx) => ctx.chat?.id?.toString());
+    const start = (key, def, enterCtx) => {
+        const live = { queue: [], current: enterCtx };
+        sessions.set(key, live);
+        const cv = {
+            wait: () => new Promise((resolve) => {
+                const queued = live.queue.shift();
+                if (queued) {
+                    live.current = queued;
+                    resolve(queued);
+                }
+                else {
+                    live.waiter = resolve;
+                }
+            }),
+            get ctx() {
+                return live.current;
+            },
+        };
+        Promise.resolve(def.builder(cv, enterCtx))
+            .catch((error) => options.onError?.(error, live.current))
+            .finally(() => {
+            if (sessions.get(key) === live)
+                sessions.delete(key);
+        });
+    };
+    const plugin = (composer) => composer
+        .derive((ctx) => {
+        const key = getKey(ctx);
+        const control = {
+            enter: (name) => {
+                if (key === undefined)
+                    return;
+                const def = registry.get(name);
+                if (!def)
+                    throw new Error(`conversation "${name}" is not registered`);
+                start(key, def, ctx);
+            },
+            active: () => key !== undefined && sessions.has(key),
+            leave: () => {
+                if (key !== undefined)
+                    sessions.delete(key);
+            },
+        };
+        return { conversation: control };
+    })
+        .use(async (ctx, next) => {
+        const key = getKey(ctx);
+        if (key !== undefined) {
+            const live = sessions.get(key);
+            if (live) {
+                if (live.waiter) {
+                    const resolve = live.waiter;
+                    live.waiter = undefined;
+                    live.current = ctx;
+                    resolve(ctx);
+                }
+                else {
+                    live.queue.push(ctx);
+                }
+                return; // owned by the active conversation
+            }
+        }
+        await next();
+    });
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { conversation, createConversation } from "./index.js";
+const noop = async () => { };
+const flush = () => new Promise((r) => setTimeout(r, 0));
+const entry = (c) => c.toMiddleware();
+function fakeApi() {
+    const sent = [];
+    const api = {
+        sendMessage(p) {
+            sent.push(String(p.text));
+            return Promise.resolve({ message_id: 1 });
+        },
+    };
+    return { api, sent };
+}
+const msgCtx = (api, text, chatId) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: chatId, type: "private" },
+            from: { id: chatId, is_bot: false, first_name: "u" },
+            text,
+        },
+    },
+    updateType: "message",
+});
+test("conversation walks through steps and consumes the chat's updates", async () => {
+    const { api, sent } = fakeApi();
+    let fellThrough = 0;
+    const greet = createConversation("greet", async (cv, ctx) => {
+        await ctx.send("name?");
+        const a = await cv.wait();
+        await a.send("age?");
+        const b = await cv.wait();
+        await b.send(`${a.text} is ${b.text}`);
+    });
+    const mw = entry(new Composer()
+        .install(conversation([greet]))
+        .command("greet", (ctx) => ctx.conversation.enter("greet"))
+        .on("message:text", () => {
+        fellThrough++;
+    }));
+    await mw(msgCtx(api, "/greet", 1), noop);
+    await flush();
+    await mw(msgCtx(api, "Bob", 1), noop);
+    await flush();
+    await mw(msgCtx(api, "30", 1), noop);
+    await flush();
+    assert.deepEqual(sent, ["name?", "age?", "Bob is 30"]);
+    assert.equal(fellThrough, 0); // every step was consumed by the conversation
+});
+test("a different chat is not captured by another chat's conversation", async () => {
+    const { api } = fakeApi();
+    let seen = "";
+    const wait1 = createConversation("wait", async (cv) => {
+        await cv.wait();
+    });
+    const mw = entry(new Composer()
+        .install(conversation([wait1]))
+        .command("go", (ctx) => ctx.conversation.enter("wait"))
+        .on("message:text", (ctx) => {
+        seen = ctx.text;
+    }));
+    await mw(msgCtx(api, "/go", 1), noop); // chat 1 enters a conversation
+    await flush();
+    await mw(msgCtx(api, "hello", 2), noop); // chat 2 is independent
+    assert.equal(seen, "hello");
+});
+test("active() reflects conversation state, leave() ends it", async () => {
+    const { api } = fakeApi();
+    const states = [];
+    const wait1 = createConversation("wait", async (cv) => {
+        await cv.wait();
+        await cv.wait(); // would need a third update, but we leave() before then
+    });
+    const mw = entry(new Composer()
+        .install(conversation([wait1]))
+        .command("go", (ctx) => ctx.conversation.enter("wait"))
+        .on("message:text", (ctx) => {
+        states.push(ctx.conversation.active());
+    }));
+    await mw(msgCtx(api, "/go", 1), noop);
+    await flush();
+    // chat 1 now has an active conversation: the next text is consumed (no fall-through)
+    await mw(msgCtx(api, "x", 1), noop);
+    await flush();
+    const probe = msgCtx(api, "probe", 3);
+    await mw(probe, noop);
+    assert.equal(states.includes(true), false); // chat 3 never had one
+    assert.equal(probe.conversation.active(), false);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/conversation",
+  "version": "0.0.1",
+  "description": "yaebal conversation — await-style multi-step dialogs (coroutine, no replay).",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "conversation",
+    "dialog"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/conversation"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { type ConversationControl, conversation, createConversation } from "./index.js";
+
+const noop = async () => {};
+const flush = () => new Promise<void>((r) => setTimeout(r, 0));
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+function fakeApi() {
+	const sent: string[] = [];
+	const api = {
+		sendMessage(p: Record<string, unknown>) {
+			sent.push(String(p.text));
+			return Promise.resolve({ message_id: 1 });
+		},
+	} as never;
+	return { api, sent };
+}
+
+const msgCtx = (api: never, text: string, chatId: number) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: chatId, type: "private" },
+				from: { id: chatId, is_bot: false, first_name: "u" },
+				text,
+			},
+		} as never,
+		updateType: "message",
+	});
+
+type Ctx = Context & { conversation: ConversationControl };
+
+test("conversation walks through steps and consumes the chat's updates", async () => {
+	const { api, sent } = fakeApi();
+	let fellThrough = 0;
+
+	const greet = createConversation("greet", async (cv, ctx) => {
+		await ctx.send("name?");
+		const a = await cv.wait();
+		await a.send("age?");
+		const b = await cv.wait();
+		await b.send(`${a.text} is ${b.text}`);
+	});
+
+	const mw = entry(
+		new Composer<Context>()
+			.install(conversation([greet]))
+			.command("greet", (ctx) => (ctx as Ctx).conversation.enter("greet"))
+			.on("message:text", () => {
+				fellThrough++;
+			}),
+	);
+
+	await mw(msgCtx(api, "/greet", 1), noop);
+	await flush();
+	await mw(msgCtx(api, "Bob", 1), noop);
+	await flush();
+	await mw(msgCtx(api, "30", 1), noop);
+	await flush();
+
+	assert.deepEqual(sent, ["name?", "age?", "Bob is 30"]);
+	assert.equal(fellThrough, 0); // every step was consumed by the conversation
+});
+
+test("a different chat is not captured by another chat's conversation", async () => {
+	const { api } = fakeApi();
+	let seen = "";
+
+	const wait1 = createConversation("wait", async (cv) => {
+		await cv.wait();
+	});
+
+	const mw = entry(
+		new Composer<Context>()
+			.install(conversation([wait1]))
+			.command("go", (ctx) => (ctx as Ctx).conversation.enter("wait"))
+			.on("message:text", (ctx) => {
+				seen = ctx.text;
+			}),
+	);
+
+	await mw(msgCtx(api, "/go", 1), noop); // chat 1 enters a conversation
+	await flush();
+	await mw(msgCtx(api, "hello", 2), noop); // chat 2 is independent
+	assert.equal(seen, "hello");
+});
+
+test("active() reflects conversation state, leave() ends it", async () => {
+	const { api } = fakeApi();
+	const states: boolean[] = [];
+
+	const wait1 = createConversation("wait", async (cv) => {
+		await cv.wait();
+		await cv.wait(); // would need a third update, but we leave() before then
+	});
+
+	const mw = entry(
+		new Composer<Context>()
+			.install(conversation([wait1]))
+			.command("go", (ctx) => (ctx as Ctx).conversation.enter("wait"))
+			.on("message:text", (ctx) => {
+				states.push((ctx as Ctx).conversation.active());
+			}),
+	);
+
+	await mw(msgCtx(api, "/go", 1), noop);
+	await flush();
+	// chat 1 now has an active conversation: the next text is consumed (no fall-through)
+	await mw(msgCtx(api, "x", 1), noop);
+	await flush();
+
+	const probe = msgCtx(api, "probe", 3);
+	await mw(probe, noop);
+	assert.equal(states.includes(true), false); // chat 3 never had one
+	assert.equal((probe as Ctx).conversation.active(), false);
+});

package/src/index.ts

@@ -0,0 +1,143 @@
+import type { Context, Plugin } from "@yaebal/core";
+
+/**
+ * @yaebal/conversation — write multi-step dialogs as a straight line:
+ *
+ *   const greet = createConversation("greet", async (cv, ctx) => {
+ *     await ctx.send("what's your name?");
+ * 
+ *     const answer = await cv.wait();
+ *     await answer.send(`hi ${answer.text}`);
+ *   });
+ *   bot.install(conversation([greet]));
+ *   bot.command("greet", (ctx) => ctx.conversation.enter("greet"));
+ *
+ * it's a COROUTINE, not a replay engine (grammY-style): the builder runs once,
+ * detached, and `cv.wait()` resolves with the next update for that chat. while a
+ * conversation is active it OWNS the chat's updates (they don't reach other
+ * handlers). state is in-memory, lost on restart — like `prompt`/`scenes`.
+ */
+
+export interface Conversation {
+	/** resolve with the next update's context for this chat. */
+	wait(): Promise<Context>;
+	/** the most recent context (the entering update, then each waited one). */
+	readonly ctx: Context;
+}
+
+export type ConversationBuilder = (cv: Conversation, ctx: Context) => void | Promise<void>;
+
+export interface ConversationDef {
+	name: string;
+	builder: ConversationBuilder;
+}
+
+export function createConversation(name: string, builder: ConversationBuilder): ConversationDef {
+	return { name, builder };
+}
+
+export interface ConversationControl {
+	/** start a registered conversation for this chat. */
+	enter(name: string): void;
+	/** whether a conversation is currently running for this chat. */
+	active(): boolean;
+	/** abandon the active conversation (its coroutine is left parked). */
+	leave(): void;
+}
+
+export interface ConversationOptions {
+	/** conversation key for an update. default: per-chat (`ctx.chat.id`). */
+	getKey?: (ctx: Context) => string | undefined;
+	/** called if a conversation builder throws. */
+	onError?: (error: unknown, ctx: Context) => void;
+}
+
+interface Live {
+	queue: Context[];
+	waiter?: (ctx: Context) => void;
+	current: Context;
+}
+
+export function conversation(
+	defs: ConversationDef[],
+	options: ConversationOptions = {},
+): Plugin<Context, { conversation: ConversationControl }> {
+	const registry = new Map(defs.map((d) => [d.name, d]));
+	const sessions = new Map<string, Live>();
+	const getKey = options.getKey ?? ((ctx: Context) => ctx.chat?.id?.toString());
+
+	const start = (key: string, def: ConversationDef, enterCtx: Context) => {
+		const live: Live = { queue: [], current: enterCtx };
+		sessions.set(key, live);
+
+		const cv: Conversation = {
+			wait: () =>
+				new Promise<Context>((resolve) => {
+					const queued = live.queue.shift();
+
+					if (queued) {
+						live.current = queued;
+						resolve(queued);
+					} else {
+						live.waiter = resolve;
+					}
+				}),
+			get ctx() {
+				return live.current;
+			},
+		};
+
+		Promise.resolve(def.builder(cv, enterCtx))
+			.catch((error) => options.onError?.(error, live.current))
+			.finally(() => {
+				if (sessions.get(key) === live) sessions.delete(key);
+			});
+	};
+
+	const plugin: Plugin<Context, { conversation: ConversationControl }> = (composer) =>
+		composer
+			.derive((ctx) => {
+				const key = getKey(ctx);
+				const control: ConversationControl = {
+					enter: (name) => {
+						if (key === undefined) return;
+
+						const def = registry.get(name);
+						if (!def) throw new Error(`conversation "${name}" is not registered`);
+
+						start(key, def, ctx);
+					},
+
+					active: () => key !== undefined && sessions.has(key),
+					leave: () => {
+						if (key !== undefined) sessions.delete(key);
+					},
+				};
+
+				return { conversation: control };
+			})
+			.use(async (ctx, next) => {
+				const key = getKey(ctx);
+				if (key !== undefined) {
+					const live = sessions.get(key);
+
+					if (live) {
+						if (live.waiter) {
+							const resolve = live.waiter;
+
+							live.waiter = undefined;
+							live.current = ctx;
+
+							resolve(ctx);
+						} else {
+							live.queue.push(ctx);
+						}
+
+						return; // owned by the active conversation
+					}
+				}
+				await next();
+			});
+	
+	return plugin;
+}