@yaebal/session 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,13 @@
+# @yaebal/session
+
+a pluggable session store. implement this to back sessions with a file, redis, etc.
+
+## install
+
+```sh
+pnpm add @yaebal/session
+```
+
+---
+
+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,30 @@
+import type { Context, Plugin } from "@yaebal/core";
+/** a pluggable session store. implement this to back sessions with a file, redis, etc. */
+export interface StorageAdapter<T> {
+    get(key: string): T | undefined | Promise<T | undefined>;
+    set(key: string, value: T): unknown | Promise<unknown>;
+    delete(key: string): unknown | Promise<unknown>;
+}
+/** defaults to in-memory store. lost on restart — swap for a persistent adapter in production. */
+export declare class MemoryStorage<T> implements StorageAdapter<T> {
+    #private;
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+}
+export interface SessionOptions<S> {
+    /** build a fresh session when none is stored. required so the type is honest. */
+    initial: () => S;
+    /** where to persist sessions. defaults to in-memory. */
+    storage?: StorageAdapter<S>;
+    /** session key for an update. defaults to per-chat (`ctx.chat.id`). */
+    getKey?: (ctx: Context) => string | undefined;
+}
+/**
+ * session plugin: loads `ctx.session` before handlers run and persists it after.
+ * per-chat by default (the grammY convention); override `getKey` for per-user.
+ */
+export declare function session<S>(options: SessionOptions<S>): Plugin<Context, {
+    session: S;
+}>;
+//# 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,0FAA0F;AAC1F,MAAM,WAAW,cAAc,CAAC,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED,kGAAkG;AAClG,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,cAAc,CAAC,CAAC,CAAC;;IAGzD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAIhC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGzB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAChC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,wDAAwD;IACxD,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAC5B,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,CA2BtF"}

package/lib/index.js

@@ -0,0 +1,41 @@
+/** defaults to in-memory store. lost on restart — swap for a persistent adapter in production. */
+export class MemoryStorage {
+    #map = new Map();
+    get(key) {
+        return this.#map.get(key);
+    }
+    set(key, value) {
+        this.#map.set(key, value);
+    }
+    delete(key) {
+        this.#map.delete(key);
+    }
+}
+/**
+ * session plugin: loads `ctx.session` before handlers run and persists it after.
+ * per-chat by default (the grammY convention); override `getKey` for per-user.
+ */
+export function session(options) {
+    const { initial } = options;
+    const storage = options.storage ?? new MemoryStorage();
+    const getKey = options.getKey ?? ((ctx) => ctx.chat?.id?.toString());
+    return (composer) => composer
+        // post-next save. wraps the derive below; runs after handlers, then persists.
+        .use(async (ctx, next) => {
+        const key = getKey(ctx);
+        await next();
+        // no key for this update (e.g. a channel post): the session was a throwaway.
+        if (key === undefined)
+            return;
+        // ponytail: writes back unconditionally. add a dirty-check only if a remote
+        // storage adapter makes the extra write measurably expensive.
+        await storage.set(key, ctx.session);
+    })
+        // load (or initialise) the session before handlers run; the field flows typed.
+        .derive(async (ctx) => {
+        const key = getKey(ctx);
+        const value = key === undefined ? initial() : ((await storage.get(key)) ?? initial());
+        return { session: value };
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,kGAAkG;AAClG,MAAM,OAAO,aAAa;IACzB,IAAI,GAAG,IAAI,GAAG,EAAa,CAAC;IAE5B,GAAG,CAAC,GAAW;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,GAAW;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;CACD;AAWD;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAI,OAA0B;IACpD,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE5B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,aAAa,EAAK,CAAC;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE9E,OAAO,CAAC,QAAQ,EAAE,EAAE,CACnB,QAAQ;QACP,8EAA8E;SAC7E,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,MAAM,IAAI,EAAE,CAAC;QAEb,6EAA6E;QAC7E,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO;QAE9B,4EAA4E;QAC5E,8DAA8D;QAC9D,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,EAAG,GAAiC,CAAC,OAAO,CAAC,CAAC;IACpE,CAAC,CAAC;QACF,+EAA+E;SAC9E,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACrB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;QAEtF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC,CAAC,CAAC;AACN,CAAC"}

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,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { MemoryStorage, session } from "./index.js";
+const api = {};
+const noop = async () => { };
+// the entry ctx is a bare Context; the session middleware adds `session` itself.
+// mirror Bot.start()'s cast so the runnable type matches the runtime reality.
+const entry = (c) => c.toMiddleware();
+function mkCtx(chatId) {
+    return 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: "hi",
+            },
+        },
+        updateType: "message",
+    });
+}
+test("MemoryStorage round-trips values", () => {
+    const s = new MemoryStorage();
+    s.set("a", 1);
+    assert.equal(s.get("a"), 1);
+    s.delete("a");
+    assert.equal(s.get("a"), undefined);
+});
+test("session persists per chat across updates", async () => {
+    const storage = new MemoryStorage();
+    const c = new Composer()
+        .install(session({ initial: () => ({ count: 0 }), storage }))
+        .use((ctx, next) => {
+        ctx.session.count++;
+        return next();
+    });
+    const mw = entry(c);
+    await mw(mkCtx(42), noop);
+    await mw(mkCtx(42), noop);
+    await mw(mkCtx(99), noop);
+    assert.equal((await storage.get("42"))?.count, 2);
+    assert.equal((await storage.get("99"))?.count, 1);
+});
+test("session falls back to initial when nothing stored", async () => {
+    const storage = new MemoryStorage();
+    let seen = -1;
+    const c = new Composer()
+        .install(session({ initial: () => ({ count: 7 }), storage }))
+        .use((ctx, next) => {
+        seen = ctx.session.count;
+        return next();
+    });
+    await entry(c)(mkCtx(1), noop);
+    assert.equal(seen, 7);
+});
+test("a custom getKey switches the partition", async () => {
+    const storage = new MemoryStorage();
+    const c = new Composer()
+        .install(session({ initial: () => ({ n: 0 }), storage, getKey: () => "global" }))
+        .use((ctx, next) => {
+        ctx.session.n++;
+        return next();
+    });
+    const mw = entry(c);
+    await mw(mkCtx(1), noop);
+    await mw(mkCtx(2), noop);
+    assert.equal((await storage.get("global"))?.n, 2);
+});
+test("keyless update gets a working, non-persisted session", async () => {
+    const storage = new MemoryStorage();
+    let seen = -1;
+    const c = new Composer()
+        .install(session({ initial: () => ({ count: 3 }), storage }))
+        .use((ctx, next) => {
+        ctx.session.count++;
+        seen = ctx.session.count;
+        return next();
+    });
+    // an update with no chat (e.g. a poll) → no key
+    const keyless = new Context({
+        api,
+        update: { update_id: 1 },
+        updateType: "poll",
+    });
+    await entry(c)(keyless, noop);
+    assert.equal(seen, 4); // session was usable
+    assert.equal(await storage.get("0"), undefined); // nothing persisted
+});
+test("a throwing handler leaves storage untouched", async () => {
+    const storage = new MemoryStorage();
+    const c = new Composer()
+        .install(session({ initial: () => ({ count: 0 }), storage }))
+        .use((ctx) => {
+        ctx.session.count++;
+        throw new Error("boom");
+    });
+    await assert.rejects(async () => {
+        await entry(c)(mkCtx(5), noop);
+    }, /boom/);
+    assert.equal(await storage.get("5"), undefined);
+});
+//# 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":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAmB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,GAAG,GAAG,EAAW,CAAC;AACxB,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;AAE5B,iFAAiF;AACjF,8EAA8E;AAC9E,MAAM,KAAK,GAAG,CAAoB,CAAc,EAAE,EAAE,CACnD,CAAC,CAAC,YAAY,EAAoC,CAAC;AAEpD,SAAS,KAAK,CAAC,MAAc;IAC5B,OAAO,IAAI,OAAO,CAAC;QAClB,GAAG;QACH,MAAM,EAAE;YACP,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE;gBACR,UAAU,EAAE,CAAC;gBACb,IAAI,EAAE,CAAC;gBACP,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;gBACrC,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE;gBACpD,IAAI,EAAE,IAAI;aACV;SACQ;QACV,UAAU,EAAE,SAAS;KACrB,CAAC,CAAC;AACJ,CAAC;AAED,IAAI,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAC7C,MAAM,CAAC,GAAG,IAAI,aAAa,EAAU,CAAC;IAEtC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACd,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACd,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;IAC3D,MAAM,OAAO,GAAG,IAAI,aAAa,EAAqB,CAAC;IACvD,MAAM,CAAC,GAAG,IAAI,QAAQ,EAAW;SAC/B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;SAC5D,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QAClB,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;IAEJ,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpB,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAE1B,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;IACpE,MAAM,OAAO,GAAG,IAAI,aAAa,EAAqB,CAAC;IACvD,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IAEd,MAAM,CAAC,GAAG,IAAI,QAAQ,EAAW;SAC/B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;SAC5D,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QAClB,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC;QACzB,OAAO,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;IAEJ,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;IACzD,MAAM,OAAO,GAAG,IAAI,aAAa,EAAiB,CAAC;IACnD,MAAM,CAAC,GAAG,IAAI,QAAQ,EAAW;SAC/B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;SAChF,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QAClB,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAChB,OAAO,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;IAEJ,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpB,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAEzB,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;IACvE,MAAM,OAAO,GAAG,IAAI,aAAa,EAAqB,CAAC;IACvD,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IAEd,MAAM,CAAC,GAAG,IAAI,QAAQ,EAAW;SAC/B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;SAC5D,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QAClB,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC;QACzB,OAAO,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;IAEJ,gDAAgD;IAChD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC;QAC3B,GAAG;QACH,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,EAAW;QACjC,UAAU,EAAE,MAAM;KAClB,CAAC,CAAC;IAEH,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9B,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,qBAAqB;IAC5C,MAAM,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,oBAAoB;AACtE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;IAC9D,MAAM,OAAO,GAAG,IAAI,aAAa,EAAqB,CAAC;IACvD,MAAM,CAAC,GAAG,IAAI,QAAQ,EAAW;SAC/B,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;SAC5D,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACZ,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEJ,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE;QAC/B,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,EAAE,MAAM,CAAC,CAAC;IAEX,MAAM,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/session",
+  "version": "0.0.1",
+  "description": "yaebal session plugin — per-chat state with pluggable storage adapters.",
+  "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",
+    "session",
+    "storage"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/session"
+  },
+  "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,130 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { MemoryStorage, session } from "./index.js";
+
+const api = {} as never;
+const noop = async () => {};
+
+// the entry ctx is a bare Context; the session middleware adds `session` itself.
+// mirror Bot.start()'s cast so the runnable type matches the runtime reality.
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+function mkCtx(chatId: number): Context {
+	return 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: "hi",
+			},
+		} as never,
+		updateType: "message",
+	});
+}
+
+test("MemoryStorage round-trips values", () => {
+	const s = new MemoryStorage<number>();
+
+	s.set("a", 1);
+	assert.equal(s.get("a"), 1);
+
+	s.delete("a");
+	assert.equal(s.get("a"), undefined);
+});
+
+test("session persists per chat across updates", async () => {
+	const storage = new MemoryStorage<{ count: number }>();
+	const c = new Composer<Context>()
+		.install(session({ initial: () => ({ count: 0 }), storage }))
+		.use((ctx, next) => {
+			ctx.session.count++;
+			return next();
+		});
+
+	const mw = entry(c);
+
+	await mw(mkCtx(42), noop);
+	await mw(mkCtx(42), noop);
+	await mw(mkCtx(99), noop);
+
+	assert.equal((await storage.get("42"))?.count, 2);
+	assert.equal((await storage.get("99"))?.count, 1);
+});
+
+test("session falls back to initial when nothing stored", async () => {
+	const storage = new MemoryStorage<{ count: number }>();
+	let seen = -1;
+
+	const c = new Composer<Context>()
+		.install(session({ initial: () => ({ count: 7 }), storage }))
+		.use((ctx, next) => {
+			seen = ctx.session.count;
+			return next();
+		});
+
+	await entry(c)(mkCtx(1), noop);
+	assert.equal(seen, 7);
+});
+
+test("a custom getKey switches the partition", async () => {
+	const storage = new MemoryStorage<{ n: number }>();
+	const c = new Composer<Context>()
+		.install(session({ initial: () => ({ n: 0 }), storage, getKey: () => "global" }))
+		.use((ctx, next) => {
+			ctx.session.n++;
+			return next();
+		});
+
+	const mw = entry(c);
+
+	await mw(mkCtx(1), noop);
+	await mw(mkCtx(2), noop);
+
+	assert.equal((await storage.get("global"))?.n, 2);
+});
+
+test("keyless update gets a working, non-persisted session", async () => {
+	const storage = new MemoryStorage<{ count: number }>();
+	let seen = -1;
+
+	const c = new Composer<Context>()
+		.install(session({ initial: () => ({ count: 3 }), storage }))
+		.use((ctx, next) => {
+			ctx.session.count++;
+			seen = ctx.session.count;
+			return next();
+		});
+
+	// an update with no chat (e.g. a poll) → no key
+	const keyless = new Context({
+		api,
+		update: { update_id: 1 } as never,
+		updateType: "poll",
+	});
+
+	await entry(c)(keyless, noop);
+	assert.equal(seen, 4); // session was usable
+	assert.equal(await storage.get("0"), undefined); // nothing persisted
+});
+
+test("a throwing handler leaves storage untouched", async () => {
+	const storage = new MemoryStorage<{ count: number }>();
+	const c = new Composer<Context>()
+		.install(session({ initial: () => ({ count: 0 }), storage }))
+		.use((ctx) => {
+			ctx.session.count++;
+			throw new Error("boom");
+		});
+
+	await assert.rejects(async () => {
+		await entry(c)(mkCtx(5), noop);
+	}, /boom/);
+	
+	assert.equal(await storage.get("5"), undefined);
+});

package/src/index.ts

@@ -0,0 +1,67 @@
+import type { Context, Plugin } from "@yaebal/core";
+
+/** a pluggable session store. implement this to back sessions with a file, redis, etc. */
+export interface StorageAdapter<T> {
+	get(key: string): T | undefined | Promise<T | undefined>;
+	set(key: string, value: T): unknown | Promise<unknown>;
+	delete(key: string): unknown | Promise<unknown>;
+}
+
+/** defaults to in-memory store. lost on restart — swap for a persistent adapter in production. */
+export class MemoryStorage<T> implements StorageAdapter<T> {
+	#map = new Map<string, T>();
+
+	get(key: string): T | undefined {
+		return this.#map.get(key);
+	}
+
+	set(key: string, value: T): void {
+		this.#map.set(key, value);
+	}
+
+	delete(key: string): void {
+		this.#map.delete(key);
+	}
+}
+
+export interface SessionOptions<S> {
+	/** build a fresh session when none is stored. required so the type is honest. */
+	initial: () => S;
+	/** where to persist sessions. defaults to in-memory. */
+	storage?: StorageAdapter<S>;
+	/** session key for an update. defaults to per-chat (`ctx.chat.id`). */
+	getKey?: (ctx: Context) => string | undefined;
+}
+
+/**
+ * session plugin: loads `ctx.session` before handlers run and persists it after.
+ * per-chat by default (the grammY convention); override `getKey` for per-user.
+ */
+export function session<S>(options: SessionOptions<S>): Plugin<Context, { session: S }> {
+	const { initial } = options;
+
+	const storage = options.storage ?? new MemoryStorage<S>();
+	const getKey = options.getKey ?? ((ctx: Context) => ctx.chat?.id?.toString());
+
+	return (composer) =>
+		composer
+			// post-next save. wraps the derive below; runs after handlers, then persists.
+			.use(async (ctx, next) => {
+				const key = getKey(ctx);
+				await next();
+
+				// no key for this update (e.g. a channel post): the session was a throwaway.
+				if (key === undefined) return;
+
+				// ponytail: writes back unconditionally. add a dirty-check only if a remote
+				// storage adapter makes the extra write measurably expensive.
+				await storage.set(key, (ctx as unknown as { session: S }).session);
+			})
+			// load (or initialise) the session before handlers run; the field flows typed.
+			.derive(async (ctx) => {
+				const key = getKey(ctx);
+				const value = key === undefined ? initial() : ((await storage.get(key)) ?? initial());
+				
+				return { session: value };
+			});
+}