@vizamodo/edge-cache-core 0.3.26 → 0.3.28

package/dist/runtime/cache.d.ts

@@ -1,6 +1,31 @@
-type Options = {
-    ttlSec?: number;
+export type CacheOptions = {
+    ttlSec: number;
     forceRefresh?: boolean;
 };
-export declare function getCachedOrFetch<T>(key: string, fetcher: () => Promise<T>, options?: Options): Promise<T>;
-export {};
+/**
+ * Wrap a fetcher result to override the TTL via an absolute expiry timestamp.
+ * Use this when the upstream API tells you exactly when the data expires
+ * (e.g. OAuth token expiresAt, CDN Cache-Control, etc.).
+ *
+ * @example
+ * fetcher: async () => {
+ *   const token = await getToken();
+ *   return wrapResult(token.accessToken, token.expiresAt); // ISO string
+ * }
+ */
+export type WrappedResult<T> = {
+    readonly __wrapped: true;
+    readonly value: T;
+    readonly expiresAt?: string;
+};
+export declare function wrapResult<T>(value: T, expiresAt?: string): WrappedResult<T>;
+/**
+ * Two-level cache: L1 in-memory → L2 edge → L3 fetcher.
+ *
+ * - ttlSec:       edge cache TTL in seconds (REQUIRED). Pass 0 to skip edge write.
+ * - forceRefresh: skips L1 + L2, always calls the fetcher and writes back.
+ * - WrappedResult: return wrapResult(value, expiresAt) from fetcher to override TTL
+ *                  with an absolute expiry from the upstream source.
+ * - Edge and memory write failures are non-fatal and will not throw.
+ */
+export declare function getCachedOrFetch<T>(key: string, fetcher: () => Promise<T | WrappedResult<T>>, options: CacheOptions): Promise<T>;

package/dist/runtime/cache.js

@@ -1,22 +1,61 @@
 import { getEdgeCache, setEdgeCache } from "./edge-cache";
 const memory = new Map();
-export async function getCachedOrFetch(key, fetcher, options) {
-    // L1: memory (skip if forceRefresh)
-    if (!options?.forceRefresh && memory.has(key)) {
-        return memory.get(key);
+export function wrapResult(value, expiresAt) {
+    return { __wrapped: true, value, expiresAt };
+}
+// ─── Internals ─────────────────────────────────────────────────────────────
+const TTL_BUFFER_SEC = 300; // 5-minute safety buffer
+const TTL_MIN_SEC = 60; // never cache for less than 1 minute
+function isWrapped(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        result.__wrapped === true);
+}
+function ttlFromExpiresAt(expiresAt) {
+    const ms = new Date(expiresAt).getTime();
+    if (Number.isNaN(ms)) {
+        return TTL_MIN_SEC; // fallback safe
     }
-    // L2: edge cache (skip if forceRefresh)
-    if (!options?.forceRefresh) {
+    const ttl = Math.floor((ms - Date.now()) / 1000) - TTL_BUFFER_SEC;
+    return Math.max(ttl, TTL_MIN_SEC);
+}
+// ─── Main ──────────────────────────────────────────────────────────────────
+/**
+ * Two-level cache: L1 in-memory → L2 edge → L3 fetcher.
+ *
+ * - ttlSec:       edge cache TTL in seconds (REQUIRED). Pass 0 to skip edge write.
+ * - forceRefresh: skips L1 + L2, always calls the fetcher and writes back.
+ * - WrappedResult: return wrapResult(value, expiresAt) from fetcher to override TTL
+ *                  with an absolute expiry from the upstream source.
+ * - Edge and memory write failures are non-fatal and will not throw.
+ */
+export async function getCachedOrFetch(key, fetcher, options) {
+    const { forceRefresh = false, ttlSec } = options;
+    if (!forceRefresh) {
+        // L1: memory
+        if (memory.has(key)) {
+            return memory.get(key);
+        }
+        // L2: edge cache
         const edge = await getEdgeCache(key);
-        if (edge) {
+        if (edge !== null) {
             memory.set(key, edge);
             return edge;
         }
     }
-    // L3: fetch
-    const value = await fetcher();
-    // write back
+    // L3: fetch from source
+    const result = await fetcher();
+    const value = isWrapped(result) ? result.value : result;
+    const finalTtl = isWrapped(result) && result.expiresAt
+        ? ttlFromExpiresAt(result.expiresAt)
+        : ttlSec;
+    // Write back to both layers — edge write is best-effort
     memory.set(key, value);
-    await setEdgeCache(key, value, options?.ttlSec ?? 3000);
+    try {
+        await setEdgeCache(key, value, finalTtl);
+    }
+    catch {
+        // non-fatal
+    }
     return value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizamodo/edge-cache-core",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "Edge cache primitives for Cloudflare Workers (L1 memory + L2 edge cache)",
   "type": "module",
   "main": "dist/index.js",