@yaebal/callback-data 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,19 @@
+# @yaebal/callback-data
+
+typed `callback_data`. define a prefix + a field→codec schema, then `pack`/`unpack`
+with full type inference. values are URL-encoded so the `:` separator is safe inside
+them. telegram caps callback_data at 64 bytes — keeping it short is the caller's job.
+
+codecs are not validated: `number` must be finite (garbage decodes to `NaN`), and
+`boolean` parses by exact `"true"` (anything else → `false`). safe for round-tripping
+data you packed yourself, which is all callback_data ever is.
+
+## install
+
+```sh
+pnpm add @yaebal/callback-data
+```
+
+---
+
+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,26 @@
+/**
+ * Typed `callback_data`. Define a prefix + a field→codec schema, then `pack`/`unpack`
+ * with full type inference. Values are URL-encoded so the `:` separator is safe inside
+ * them. Telegram caps callback_data at 64 bytes — keeping it short is the caller's job.
+ *
+ * Codecs are not validated: `Number` must be finite (garbage decodes to `NaN`), and
+ * `Boolean` parses by exact `"true"` (anything else → `false`). Safe for round-tripping
+ * data you packed yourself, which is all callback_data ever is.
+ */
+type Codec = NumberConstructor | StringConstructor | BooleanConstructor;
+type Infer<S extends Record<string, Codec>> = {
+    [K in keyof S]: S[K] extends NumberConstructor ? number : S[K] extends BooleanConstructor ? boolean : string;
+};
+export interface CallbackData<S extends Record<string, Codec>> {
+    /** Serialize a payload into a callback_data string. */
+    pack(data: Infer<S>): string;
+    /** Parse a callback_data string, or `undefined` if the prefix/arity doesn't match. */
+    unpack(raw: string): Infer<S> | undefined;
+    /** True if `raw` belongs to this callback_data namespace. */
+    filter(raw: string | undefined): boolean;
+    /** RegExp anchored to the prefix — pass to `bot.callbackQuery(cd.pattern, …)`. */
+    readonly pattern: RegExp;
+}
+export declare function callbackData<S extends Record<string, Codec>>(prefix: string, schema: S): CallbackData<S>;
+export {};
+//# 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;;;;;;;;GAQG;AAEH,KAAK,KAAK,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAExE,KAAK,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI;KAC5C,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,iBAAiB,GAC3C,MAAM,GACN,CAAC,CAAC,CAAC,CAAC,SAAS,kBAAkB,GAC9B,OAAO,GACP,MAAM;CACV,CAAC;AAEF,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAC5D,uDAAuD;IACvD,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC7B,sFAAsF;IACtF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC1C,6DAA6D;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACzC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC3D,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,GACP,YAAY,CAAC,CAAC,CAAC,CAuCjB"}

package/lib/index.js

@@ -0,0 +1,45 @@
+/**
+ * Typed `callback_data`. Define a prefix + a field→codec schema, then `pack`/`unpack`
+ * with full type inference. Values are URL-encoded so the `:` separator is safe inside
+ * them. Telegram caps callback_data at 64 bytes — keeping it short is the caller's job.
+ *
+ * Codecs are not validated: `Number` must be finite (garbage decodes to `NaN`), and
+ * `Boolean` parses by exact `"true"` (anything else → `false`). Safe for round-tripping
+ * data you packed yourself, which is all callback_data ever is.
+ */
+export function callbackData(prefix, schema) {
+    if (prefix.includes(":")) {
+        throw new Error(`callbackData: prefix "${prefix}" must not contain ":" (the field separator)`);
+    }
+    const keys = Object.keys(schema);
+    const pattern = new RegExp(`^${escapeRegExp(prefix)}(?::|$)`);
+    return {
+        pattern,
+        pack(data) {
+            const parts = keys.map((k) => encodeURIComponent(String(data[k])));
+            return [prefix, ...parts].join(":");
+        },
+        unpack(raw) {
+            const segs = raw.split(":");
+            if (segs[0] !== prefix)
+                return undefined;
+            const values = segs.slice(1);
+            if (values.length !== keys.length)
+                return undefined;
+            const out = {};
+            keys.forEach((k, i) => {
+                const dec = decodeURIComponent(values[i] ?? "");
+                const codec = schema[k];
+                out[k] = codec === Number ? Number(dec) : codec === Boolean ? dec === "true" : dec;
+            });
+            return out;
+        },
+        filter(raw) {
+            return raw !== undefined && pattern.test(raw);
+        },
+    };
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,MAAM,UAAU,YAAY,CAC3B,MAAc,EACd,MAAS;IAET,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,8CAA8C,CAAC,CAAC;IAChG,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAyB,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAE9D,OAAO;QACN,OAAO;QAEP,IAAI,CAAC,IAAI;YACR,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnE,OAAO,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,CAAC,GAAG;YACT,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;gBAAE,OAAO,SAAS,CAAC;YAEzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;gBAAE,OAAO,SAAS,CAAC;YAEpD,MAAM,GAAG,GAAG,EAA6B,CAAC;YAE1C,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBACrB,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBAChD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;gBAExB,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;YACpF,CAAC,CAAC,CAAC;YAEH,OAAO,GAAe,CAAC;QACxB,CAAC;QAED,MAAM,CAAC,GAAG;YACT,OAAO,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,CAAC;KACD,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACjD,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,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { callbackData } from "./index.js";
+const cd = callbackData("user", { id: Number, action: String, admin: Boolean });
+test("round-trips with typed coercion", () => {
+    const raw = cd.pack({ id: 5, action: "ban", admin: true });
+    assert.equal(raw, "user:5:ban:true");
+    assert.deepEqual(cd.unpack(raw), { id: 5, action: "ban", admin: true });
+});
+test("rejects a foreign prefix", () => {
+    assert.equal(cd.unpack("other:1:x:false"), undefined);
+});
+test("rejects wrong arity", () => {
+    assert.equal(cd.unpack("user:1"), undefined);
+});
+test("separator inside a value survives encoding", () => {
+    const raw = cd.pack({ id: 1, action: "a:b:c", admin: false });
+    assert.deepEqual(cd.unpack(raw), { id: 1, action: "a:b:c", admin: false });
+});
+test("pattern/filter matches its own namespace", () => {
+    assert.ok(cd.filter(cd.pack({ id: 1, action: "x", admin: false })));
+    assert.equal(cd.filter("nope:1"), false);
+    assert.equal(cd.filter(undefined), false);
+});
+test("rejects a prefix containing the separator", () => {
+    assert.throws(() => callbackData("a:b", { x: Number }), /must not contain ":"/);
+});
+test("prefix-only schema matches exactly", () => {
+    const ping = callbackData("ping", {});
+    assert.equal(ping.pack({}), "ping");
+    assert.deepEqual(ping.unpack("ping"), {});
+    assert.ok(ping.filter("ping"));
+    assert.equal(ping.unpack("pinger"), 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,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;AAEhF,IAAI,CAAC,iCAAiC,EAAE,GAAG,EAAE;IAC5C,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAE3D,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IACrC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACzE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACrC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,qBAAqB,EAAE,GAAG,EAAE;IAChC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;AAC9C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;IACvD,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0CAA0C,EAAE,GAAG,EAAE;IACrD,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;IACtD,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,sBAAsB,CAAC,CAAC;AACjF,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEtC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;AAChD,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@yaebal/callback-data",
+  "version": "0.0.1",
+  "description": "yaebal typed callback_data — pack/unpack button payloads with type-safe schemas.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "callback-data"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/callback-data"
+  },
+  "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,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { callbackData } from "./index.js";
+
+const cd = callbackData("user", { id: Number, action: String, admin: Boolean });
+
+test("round-trips with typed coercion", () => {
+	const raw = cd.pack({ id: 5, action: "ban", admin: true });
+
+	assert.equal(raw, "user:5:ban:true");
+	assert.deepEqual(cd.unpack(raw), { id: 5, action: "ban", admin: true });
+});
+
+test("rejects a foreign prefix", () => {
+	assert.equal(cd.unpack("other:1:x:false"), undefined);
+});
+
+test("rejects wrong arity", () => {
+	assert.equal(cd.unpack("user:1"), undefined);
+});
+
+test("separator inside a value survives encoding", () => {
+	const raw = cd.pack({ id: 1, action: "a:b:c", admin: false });
+	assert.deepEqual(cd.unpack(raw), { id: 1, action: "a:b:c", admin: false });
+});
+
+test("pattern/filter matches its own namespace", () => {
+	assert.ok(cd.filter(cd.pack({ id: 1, action: "x", admin: false })));
+	assert.equal(cd.filter("nope:1"), false);
+	assert.equal(cd.filter(undefined), false);
+});
+
+test("rejects a prefix containing the separator", () => {
+	assert.throws(() => callbackData("a:b", { x: Number }), /must not contain ":"/);
+});
+
+test("prefix-only schema matches exactly", () => {
+	const ping = callbackData("ping", {});
+	
+	assert.equal(ping.pack({}), "ping");
+	assert.deepEqual(ping.unpack("ping"), {});
+	assert.ok(ping.filter("ping"));
+	assert.equal(ping.unpack("pinger"), undefined);
+});

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Typed `callback_data`. Define a prefix + a field→codec schema, then `pack`/`unpack`
+ * with full type inference. Values are URL-encoded so the `:` separator is safe inside
+ * them. Telegram caps callback_data at 64 bytes — keeping it short is the caller's job.
+ *
+ * Codecs are not validated: `Number` must be finite (garbage decodes to `NaN`), and
+ * `Boolean` parses by exact `"true"` (anything else → `false`). Safe for round-tripping
+ * data you packed yourself, which is all callback_data ever is.
+ */
+
+type Codec = NumberConstructor | StringConstructor | BooleanConstructor;
+
+type Infer<S extends Record<string, Codec>> = {
+	[K in keyof S]: S[K] extends NumberConstructor
+		? number
+		: S[K] extends BooleanConstructor
+			? boolean
+			: string;
+};
+
+export interface CallbackData<S extends Record<string, Codec>> {
+	/** Serialize a payload into a callback_data string. */
+	pack(data: Infer<S>): string;
+	/** Parse a callback_data string, or `undefined` if the prefix/arity doesn't match. */
+	unpack(raw: string): Infer<S> | undefined;
+	/** True if `raw` belongs to this callback_data namespace. */
+	filter(raw: string | undefined): boolean;
+	/** RegExp anchored to the prefix — pass to `bot.callbackQuery(cd.pattern, …)`. */
+	readonly pattern: RegExp;
+}
+
+export function callbackData<S extends Record<string, Codec>>(
+	prefix: string,
+	schema: S,
+): CallbackData<S> {
+	if (prefix.includes(":")) {
+		throw new Error(`callbackData: prefix "${prefix}" must not contain ":" (the field separator)`);
+	}
+
+	const keys = Object.keys(schema) as (keyof S & string)[];
+	const pattern = new RegExp(`^${escapeRegExp(prefix)}(?::|$)`);
+
+	return {
+		pattern,
+
+		pack(data) {
+			const parts = keys.map((k) => encodeURIComponent(String(data[k])));
+			return [prefix, ...parts].join(":");
+		},
+
+		unpack(raw) {
+			const segs = raw.split(":");
+			if (segs[0] !== prefix) return undefined;
+			
+			const values = segs.slice(1);
+			if (values.length !== keys.length) return undefined;
+
+			const out = {} as Record<string, unknown>;
+
+			keys.forEach((k, i) => {
+				const dec = decodeURIComponent(values[i] ?? "");
+				const codec = schema[k];
+
+				out[k] = codec === Number ? Number(dec) : codec === Boolean ? dec === "true" : dec;
+			});
+
+			return out as Infer<S>;
+		},
+
+		filter(raw) {
+			return raw !== undefined && pattern.test(raw);
+		},
+	};
+}
+
+function escapeRegExp(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}