@yaebal/media-cache 0.0.1 → 0.0.3

package/README.md

@@ -1,11 +1,48 @@
 # @yaebal/media-cache
 
-where to keep `key → file_id`. defaults to in-memory (lost on restart).
+reuse a `file_id` instead of re-uploading the same file.
 
-## install
+## manual mode
 
-```sh
-pnpm add @yaebal/media-cache
+```ts
+import { mediaCache } from "@yaebal/media-cache"
+import { media } from "yaebal"
+
+const cache = mediaCache()
+
+bot.command("logo", async (ctx) => {
+    await cache.photo(ctx, "logo", media.path("./logo.png"))
+})
+```
+
+## transparent mode (hook into `ctx.send*`)
+
+```ts
+import { mediaCache } from "@yaebal/media-cache"
+import { media } from "yaebal"
+
+const cache = mediaCache()
+cache.hook(bot.api)
+
+// all sendPhoto/sendDocument/sendAudio/... auto-cache by path or URL
+bot.command("logo", async (ctx) => {
+    await ctx.sendPhoto(media.path("./logo.png")) // first time: upload
+    await ctx.sendPhoto(media.path("./logo.png")) // second time: cached file_id
+})
+```
+
+keyed by the source path or URL — if you send the same path twice, it reuses the `file_id` from the first response.
+
+## storage
+
+defaults to in-memory (`MemoryStorage`, lost on restart). pass a persistent storage:
+
+```ts
+import { mediaCache } from "@yaebal/media-cache"
+
+const cache = mediaCache({
+    storage: myRedisStorage, // any StorageAdapter<string>
+})
 ```
 
 ---

package/lib/index.d.ts

@@ -1,20 +1,32 @@
-import { type Context, type MediaSource, type Message } from "@yaebal/core";
+import { type Api, 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>;
+    hook(api: Api): void;
+    /**
+     * cached media sources — `.path()` and `.url()` return thenables that
+     * transparently resolve to a cached `file_id` string (if available) or
+     * the original source. works directly in `ctx.send*()` — no wrapper needed.
+     *
+     * @example
+     * const cache = mediaCache()
+     * bot.command("logo", async (ctx) => {
+     *   await ctx.sendPhoto(cache.media.path("./logo.png"))
+     * })
+     */
+    media: CachedMedia;
+}
+export interface CachedMedia {
+    path(p: string): MediaSource & {
+        then(resolve: (value: string | MediaSource) => unknown): unknown;
+    };
+    url(u: string): MediaSource & {
+        then(resolve: (value: string | MediaSource) => unknown): unknown;
+    };
 }
-/**
- * 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,GAAG,EACR,KAAK,OAAO,EAEZ,KAAK,WAAW,EAChB,KAAK,OAAO,EAEZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,iBAAiB;IACjC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IAC1B,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,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;IACpB,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IACrB;;;;;;;;;;OAUG;IACH,KAAK,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,CACH,CAAC,EAAE,MAAM,GACP,WAAW,GAAG;QAAE,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,KAAK,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;IACtF,GAAG,CACF,CAAC,EAAE,MAAM,GACP,WAAW,GAAG;QAAE,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,KAAK,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACtF;AA0CD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAwEtE"}

package/lib/index.js

@@ -1,19 +1,43 @@
-import { media } from "@yaebal/core";
+import { isMediaSource, 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;
+    const node = Array.isArray(value) ? value.at(-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).
- */
+const MEDIA_METHODS = {
+    sendPhoto: { param: "photo", field: "photo" },
+    sendDocument: { param: "document", field: "document" },
+    sendAudio: { param: "audio", field: "audio" },
+    sendVideo: { param: "video", field: "video" },
+    sendAnimation: { param: "animation", field: "animation" },
+    sendVoice: { param: "voice", field: "voice" },
+    sendVideoNote: { param: "video_note", field: "video_note" },
+    sendSticker: { param: "sticker", field: "sticker" },
+};
+function computeKey(source) {
+    if (source.kind === "path")
+        return `path:${source.path}`;
+    if (source.kind === "url")
+        return `url:${source.url}`;
+    return undefined;
+}
+function createCachedSource(source, storage_) {
+    const key = computeKey(source);
+    return {
+        ...source,
+        then(resolve) {
+            if (!key)
+                return resolve(source);
+            return Promise.resolve(storage_.get(key)).then((cached) => {
+                resolve(cached ? media.fileId(cached) : source);
+            });
+        },
+    };
+}
 export function mediaCache(options = {}) {
     const storage = options.storage ?? new MemoryStorage();
-    const send = async (ctx, key, source, field, sender, extra) => {
+    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) {
@@ -26,6 +50,45 @@ export function mediaCache(options = {}) {
     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),
+        media: {
+            path: (p) => createCachedSource(media.path(p), storage),
+            url: (u) => createCachedSource(media.url(u), storage),
+        },
+        hook(api) {
+            const cachedBefore = new Map();
+            api.before(async (method, params) => {
+                const config = MEDIA_METHODS[method];
+                if (!config || !params)
+                    return;
+                const src = params[config.param];
+                if (!isMediaSource(src))
+                    return;
+                const key = computeKey(src);
+                if (!key)
+                    return;
+                const fileId = await storage.get(key);
+                if (fileId) {
+                    params[config.param] = fileId;
+                    return params;
+                }
+                cachedBefore.set(params, key);
+                return params;
+            });
+            api.after(async (method, params, result) => {
+                if (!params)
+                    return;
+                const config = MEDIA_METHODS[method];
+                if (!config)
+                    return;
+                const key = cachedBefore.get(params);
+                if (!key)
+                    return;
+                cachedBefore.delete(params);
+                const id = extractFileId(result, config.field);
+                if (id)
+                    await storage.set(key, id);
+            });
+        },
     };
 }
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaebal/media-cache",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "yaebal media-cache — reuse a file_id instead of re-uploading the same file.",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,8 +16,8 @@
     "src"
   ],
   "dependencies": {
-    "@yaebal/core": "0.0.1",
-    "@yaebal/session": "0.0.1"
+    "@yaebal/core": "0.0.5",
+    "@yaebal/session": "0.0.2"
   },
   "devDependencies": {
     "@types/node": "latest"

package/src/index.test.ts

@@ -50,7 +50,7 @@ test("distinct keys cache independently", async () => {
 	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

@@ -1,46 +1,99 @@
-import { type Context, type MediaSource, type Message, media } from "@yaebal/core";
+import {
+	type Api,
+	type Context,
+	isMediaSource,
+	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>;
+	hook(api: Api): void;
+	/**
+	 * cached media sources — `.path()` and `.url()` return thenables that
+	 * transparently resolve to a cached `file_id` string (if available) or
+	 * the original source. works directly in `ctx.send*()` — no wrapper needed.
+	 *
+	 * @example
+	 * const cache = mediaCache()
+	 * bot.command("logo", async (ctx) => {
+	 *   await ctx.sendPhoto(cache.media.path("./logo.png"))
+	 * })
+	 */
+	media: CachedMedia;
+}
+
+export interface CachedMedia {
+	path(
+		p: string,
+	): MediaSource & { then(resolve: (value: string | MediaSource) => unknown): unknown };
+	url(
+		u: string,
+	): MediaSource & { then(resolve: (value: string | MediaSource) => unknown): unknown };
 }
 
 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;
-
+	const node = Array.isArray(value) ? value.at(-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).
- */
+const MEDIA_METHODS: Record<string, { param: string; field: string }> = {
+	sendPhoto: { param: "photo", field: "photo" },
+	sendDocument: { param: "document", field: "document" },
+	sendAudio: { param: "audio", field: "audio" },
+	sendVideo: { param: "video", field: "video" },
+	sendAnimation: { param: "animation", field: "animation" },
+	sendVoice: { param: "voice", field: "voice" },
+	sendVideoNote: { param: "video_note", field: "video_note" },
+	sendSticker: { param: "sticker", field: "sticker" },
+};
+
+function computeKey(source: MediaSource): string | undefined {
+	if (source.kind === "path") return `path:${source.path}`;
+	if (source.kind === "url") return `url:${source.url}`;
+	return undefined;
+}
+
+function createCachedSource(
+	source: MediaSource,
+	storage_: StorageAdapter<string>,
+): MediaSource & { then(resolve: (value: string | MediaSource) => unknown): unknown } {
+	const key = computeKey(source);
+
+	return {
+		...source,
+		then(resolve: (value: string | MediaSource) => unknown) {
+			if (!key) return resolve(source);
+			return Promise.resolve(storage_.get(key)).then((cached) => {
+				resolve(cached ? media.fileId(cached) : source);
+			});
+		},
+	};
+}
+
 export function mediaCache(options: MediaCacheOptions = {}): MediaCache {
 	const storage = options.storage ?? new MemoryStorage<string>();
 
 	const send = async (
-		ctx: Context,
+		_ctx: Context,
 		key: string,
 		source: MediaSource | string,
 		field: "photo" | "document",
@@ -52,7 +105,7 @@ export function mediaCache(options: MediaCacheOptions = {}): MediaCache {
 
 		if (!cached) {
 			const id = extractFileId(result, field);
-			
+
 			if (id) await storage.set(key, id);
 		}
 
@@ -64,5 +117,48 @@ export function mediaCache(options: MediaCacheOptions = {}): MediaCache {
 			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),
+		media: {
+			path: (p: string) => createCachedSource(media.path(p), storage),
+			url: (u: string) => createCachedSource(media.url(u), storage),
+		},
+		hook(api: Api) {
+			const cachedBefore = new Map<object, string>();
+
+			api.before(async (method, params) => {
+				const config = MEDIA_METHODS[method];
+				if (!config || !params) return;
+
+				const src = params[config.param];
+				if (!isMediaSource(src)) return;
+
+				const key = computeKey(src);
+				if (!key) return;
+
+				const fileId = await storage.get(key);
+				if (fileId) {
+					params[config.param] = fileId;
+					return params;
+				}
+
+				cachedBefore.set(params, key);
+
+				return params;
+			});
+
+			api.after(async (method, params, result) => {
+				if (!params) return;
+
+				const config = MEDIA_METHODS[method];
+				if (!config) return;
+
+				const key = cachedBefore.get(params);
+				if (!key) return;
+
+				cachedBefore.delete(params);
+
+				const id = extractFileId(result as Message, config.field);
+				if (id) await storage.set(key, id);
+			});
+		},
 	};
 }