@yaebal/media-cache 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/media-cache
+
+where to keep `key → file_id`. defaults to in-memory (lost on restart).
+
+## install
+
+```sh
+pnpm add @yaebal/media-cache
+```
+
+---
+
+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,20 @@
+import { type Context, type MediaSource, type Message } from "@yaebal/core";
+import { type StorageAdapter } from "@yaebal/session";
+export interface MediaCacheOptions {
+    /** where to keep `key → file_id`. defaults to in-memory (lost on restart). */
+    storage?: StorageAdapter<string>;
+}
+export interface MediaCache {
+    /** send a photo, caching its `file_id` under `key` to skip future uploads. */
+    photo(ctx: Context, key: string, source: MediaSource | string, extra?: Record<string, unknown>): Promise<Message>;
+    /** send a document, caching its `file_id` under `key`. */
+    document(ctx: Context, key: string, source: MediaSource | string, extra?: Record<string, unknown>): Promise<Message>;
+}
+/**
+ * the first time you send a local file under a `key`, telegram returns a
+ * `file_id`; this caches it and reuses it on later sends — no re-upload.
+ * caller-supplied keys, so it's correct under concurrency (unlike a transparent
+ * hook that has to guess which upload produced which id).
+ */
+export declare function mediaCache(options?: MediaCacheOptions): MediaCache;
+//# 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,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,OAAO,EAAS,MAAM,cAAc,CAAC;AACnF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IAC1B,8EAA8E;IAC9E,KAAK,CACJ,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAAG,MAAM,EAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CACP,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAAG,MAAM,EAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;CACpB;AASD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CA6BtE"}

package/lib/index.js

@@ -0,0 +1,31 @@
+import { media } from "@yaebal/core";
+import { MemoryStorage } from "@yaebal/session";
+function extractFileId(result, field) {
+    const value = result[field];
+    const node = Array.isArray(value) ? value[value.length - 1] : value;
+    return node?.file_id;
+}
+/**
+ * the first time you send a local file under a `key`, telegram returns a
+ * `file_id`; this caches it and reuses it on later sends — no re-upload.
+ * caller-supplied keys, so it's correct under concurrency (unlike a transparent
+ * hook that has to guess which upload produced which id).
+ */
+export function mediaCache(options = {}) {
+    const storage = options.storage ?? new MemoryStorage();
+    const send = async (ctx, key, source, field, sender, extra) => {
+        const cached = await storage.get(key);
+        const result = await sender(cached ? media.fileId(cached) : source, extra);
+        if (!cached) {
+            const id = extractFileId(result, field);
+            if (id)
+                await storage.set(key, id);
+        }
+        return result;
+    };
+    return {
+        photo: (ctx, key, source, extra) => send(ctx, key, source, "photo", (s, e) => ctx.sendPhoto(s, e), extra),
+        document: (ctx, key, source, extra) => send(ctx, key, source, "document", (s, e) => ctx.sendDocument(s, e), extra),
+    };
+}
+//# 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,OAAO,EAAgD,KAAK,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,aAAa,EAAuB,MAAM,iBAAiB,CAAC;AAwBrE,SAAS,aAAa,CAAC,MAAe,EAAE,KAAa;IACpD,MAAM,KAAK,GAAI,MAA6C,CAAC,KAAK,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAEpE,OAAQ,IAAyC,EAAE,OAAO,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,UAA6B,EAAE;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,aAAa,EAAU,CAAC;IAE/D,MAAM,IAAI,GAAG,KAAK,EACjB,GAAY,EACZ,GAAW,EACX,MAA4B,EAC5B,KAA2B,EAC3B,MAAwF,EACxF,KAA+B,EACZ,EAAE;QACrB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAE3E,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,MAAM,EAAE,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAExC,IAAI,EAAE;gBAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpC,CAAC;QAED,OAAO,MAAM,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACN,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAClC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;QACtE,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CACrC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;KAC5E,CAAC;AACH,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,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { media } from "@yaebal/core";
+import { mediaCache } from "./index.js";
+test("first send uploads the source, later sends reuse the cached file_id", async () => {
+    const sent = [];
+    const ctx = {
+        sendPhoto: (src) => {
+            sent.push(src);
+            return Promise.resolve({ message_id: 1, photo: [{ file_id: "SMALL" }, { file_id: "BIG" }] });
+        },
+    };
+    const cache = mediaCache();
+    await cache.photo(ctx, "logo", media.path("./logo.png"));
+    await cache.photo(ctx, "logo", media.path("./logo.png"));
+    assert.equal(sent[0]?.kind, "path"); // first time → uploaded
+    assert.equal(sent[1]?.kind, "fileId"); // second time → cached
+    assert.equal(sent[1].fileId, "BIG"); // last/biggest size
+});
+test("document caches file_id from the document field", async () => {
+    const sent = [];
+    const ctx = {
+        sendDocument: (src) => {
+            sent.push(src);
+            return Promise.resolve({ message_id: 1, document: { file_id: "DOC" } });
+        },
+    };
+    const cache = mediaCache();
+    await cache.document(ctx, "report", media.path("./r.pdf"));
+    await cache.document(ctx, "report", media.path("./r.pdf"));
+    assert.equal(sent[1]?.kind, "fileId");
+    assert.equal(sent[1].fileId, "DOC");
+});
+test("distinct keys cache independently", async () => {
+    const sent = [];
+    const ctx = {
+        sendPhoto: (src) => {
+            sent.push(src);
+            return Promise.resolve({ message_id: 1, photo: [{ file_id: "X" }] });
+        },
+    };
+    const cache = mediaCache();
+    await cache.photo(ctx, "a", media.path("./a.png"));
+    await cache.photo(ctx, "b", media.path("./b.png")); // different key → uploads
+    assert.equal(sent[0]?.kind, "path");
+    assert.equal(sent[1]?.kind, "path");
+});
+//# 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,49 @@
+{
+  "name": "@yaebal/media-cache",
+  "version": "0.0.1",
+  "description": "yaebal media-cache — reuse a file_id instead of re-uploading the same file.",
+  "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",
+    "@yaebal/session": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "media-cache",
+    "file-id"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/media-cache"
+  },
+  "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,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { type Context, type MediaSource, media } from "@yaebal/core";
+import { mediaCache } from "./index.js";
+
+test("first send uploads the source, later sends reuse the cached file_id", async () => {
+	const sent: MediaSource[] = [];
+	const ctx = {
+		sendPhoto: (src: MediaSource) => {
+			sent.push(src);
+			return Promise.resolve({ message_id: 1, photo: [{ file_id: "SMALL" }, { file_id: "BIG" }] });
+		},
+	} as unknown as Context;
+
+	const cache = mediaCache();
+	await cache.photo(ctx, "logo", media.path("./logo.png"));
+	await cache.photo(ctx, "logo", media.path("./logo.png"));
+
+	assert.equal(sent[0]?.kind, "path"); // first time → uploaded
+	assert.equal(sent[1]?.kind, "fileId"); // second time → cached
+	assert.equal((sent[1] as { fileId: string }).fileId, "BIG"); // last/biggest size
+});
+
+test("document caches file_id from the document field", async () => {
+	const sent: MediaSource[] = [];
+	const ctx = {
+		sendDocument: (src: MediaSource) => {
+			sent.push(src);
+			return Promise.resolve({ message_id: 1, document: { file_id: "DOC" } });
+		},
+	} as unknown as Context;
+
+	const cache = mediaCache();
+	await cache.document(ctx, "report", media.path("./r.pdf"));
+	await cache.document(ctx, "report", media.path("./r.pdf"));
+
+	assert.equal(sent[1]?.kind, "fileId");
+	assert.equal((sent[1] as { fileId: string }).fileId, "DOC");
+});
+
+test("distinct keys cache independently", async () => {
+	const sent: MediaSource[] = [];
+	const ctx = {
+		sendPhoto: (src: MediaSource) => {
+			sent.push(src);
+			return Promise.resolve({ message_id: 1, photo: [{ file_id: "X" }] });
+		},
+	} as unknown as Context;
+
+	const cache = mediaCache();
+	await cache.photo(ctx, "a", media.path("./a.png"));
+	await cache.photo(ctx, "b", media.path("./b.png")); // different key → uploads
+	
+	assert.equal(sent[0]?.kind, "path");
+	assert.equal(sent[1]?.kind, "path");
+});

package/src/index.ts

@@ -0,0 +1,68 @@
+import { type Context, type MediaSource, type Message, media } from "@yaebal/core";
+import { MemoryStorage, type StorageAdapter } from "@yaebal/session";
+
+export interface MediaCacheOptions {
+	/** where to keep `key → file_id`. defaults to in-memory (lost on restart). */
+	storage?: StorageAdapter<string>;
+}
+
+export interface MediaCache {
+	/** send a photo, caching its `file_id` under `key` to skip future uploads. */
+	photo(
+		ctx: Context,
+		key: string,
+		source: MediaSource | string,
+		extra?: Record<string, unknown>,
+	): Promise<Message>;
+	/** send a document, caching its `file_id` under `key`. */
+	document(
+		ctx: Context,
+		key: string,
+		source: MediaSource | string,
+		extra?: Record<string, unknown>,
+	): Promise<Message>;
+}
+
+function extractFileId(result: Message, field: string): string | undefined {
+	const value = (result as unknown as Record<string, unknown>)[field];
+	const node = Array.isArray(value) ? value[value.length - 1] : value;
+
+	return (node as { file_id?: string } | undefined)?.file_id;
+}
+
+/**
+ * the first time you send a local file under a `key`, telegram returns a
+ * `file_id`; this caches it and reuses it on later sends — no re-upload.
+ * caller-supplied keys, so it's correct under concurrency (unlike a transparent
+ * hook that has to guess which upload produced which id).
+ */
+export function mediaCache(options: MediaCacheOptions = {}): MediaCache {
+	const storage = options.storage ?? new MemoryStorage<string>();
+
+	const send = async (
+		ctx: Context,
+		key: string,
+		source: MediaSource | string,
+		field: "photo" | "document",
+		sender: (src: MediaSource | string, extra?: Record<string, unknown>) => Promise<Message>,
+		extra?: Record<string, unknown>,
+	): Promise<Message> => {
+		const cached = await storage.get(key);
+		const result = await sender(cached ? media.fileId(cached) : source, extra);
+
+		if (!cached) {
+			const id = extractFileId(result, field);
+			
+			if (id) await storage.set(key, id);
+		}
+
+		return result;
+	};
+
+	return {
+		photo: (ctx, key, source, extra) =>
+			send(ctx, key, source, "photo", (s, e) => ctx.sendPhoto(s, e), extra),
+		document: (ctx, key, source, extra) =>
+			send(ctx, key, source, "document", (s, e) => ctx.sendDocument(s, e), extra),
+	};
+}