@vizamodo/edge-cache-core 0.3.28 → 0.3.30

package/dist/runtime/cache.d.ts

@@ -1,31 +1,10 @@
-export type CacheOptions = {
-    ttlSec: number;
-    forceRefresh?: boolean;
-};
-/**
- * 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;
+    readonly expiresAt: string | undefined;
 };
 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>;
+export declare function getCachedOrFetch<T>(key: string, fetcher: () => Promise<T | WrappedResult<T>>, options: {
+    ttlSec: number;
+    forceRefresh?: boolean;
+}): Promise<T>;

package/dist/runtime/cache.js

@@ -1,61 +1,69 @@
 import { getEdgeCache, setEdgeCache } from "./edge-cache";
-const memory = new Map();
+import { DedupePromiseCache } from "./dedupe-promise-cache";
 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 isWrapped(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        v["__wrapped"] === true);
 }
-function ttlFromExpiresAt(expiresAt) {
-    const ms = new Date(expiresAt).getTime();
-    if (Number.isNaN(ms)) {
-        return TTL_MIN_SEC; // fallback safe
-    }
-    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.
- */
+// ── Constants ──────────────────────────────────────────────────────────────
+const EDGE_BUFFER_SEC = 300; // 5-min safety buffer before expiry
+const MIN_TTL_SEC = 60;
+// ── Module-level L1 cache ──────────────────────────────────────────────────
+// One shared instance per isolate; generic over `unknown` because different
+// callers store different value types under different keys.
+const l1 = new DedupePromiseCache();
+// ── Public API ─────────────────────────────────────────────────────────────
 export async function getCachedOrFetch(key, fetcher, options) {
-    const { forceRefresh = false, ttlSec } = options;
+    const { ttlSec, forceRefresh = false } = options;
+    // ── L1: memory (skip on forceRefresh) ───────────────────────────────────
     if (!forceRefresh) {
-        // L1: memory
-        if (memory.has(key)) {
-            return memory.get(key);
+        // DedupePromiseCache handles: in-flight dedupe + TTL expiry + sentinel cleanup.
+        // We wrap the inner fetch so L1 only misses once even under concurrency.
+        // The factory is only called when L1 truly misses.
+    }
+    // Use DedupePromiseCache as L1. On forceRefresh we bypass by deleting first.
+    if (forceRefresh)
+        l1.delete(key);
+    return l1.getOrCreate(key, async () => {
+        // ── L2: edge cache (skip on forceRefresh) ─────────────────────────────
+        if (!forceRefresh) {
+            const edgeValue = await getEdgeCache(key).catch(() => null);
+            if (edgeValue !== null && edgeValue !== undefined) {
+                // Populate L1 for next request; edge TTL is not observable,
+                // so use caller-supplied ttlSec as an upper bound (may slightly over-cache).
+                return { value: edgeValue, ttlMs: ttlSec * 1000 };
+            }
         }
-        // L2: edge cache
-        const edge = await getEdgeCache(key);
-        if (edge !== null) {
-            memory.set(key, edge);
-            return edge;
+        // ── L3: fetcher ───────────────────────────────────────────────────────
+        const raw = await fetcher();
+        let unwrapped;
+        let edgeTtlSec = ttlSec;
+        if (isWrapped(raw)) {
+            unwrapped = raw.value;
+            if (raw.expiresAt) {
+                const expiresMs = Date.parse(raw.expiresAt);
+                if (Number.isFinite(expiresMs) && expiresMs > Date.now()) {
+                    const remainingSec = Math.floor((expiresMs - Date.now()) / 1000);
+                    edgeTtlSec = Math.max(remainingSec - EDGE_BUFFER_SEC, MIN_TTL_SEC);
+                }
+                else {
+                    // expired or invalid → do not cache at edge
+                    edgeTtlSec = 0;
+                }
+            }
         }
-    }
-    // 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);
-    try {
-        await setEdgeCache(key, value, finalTtl);
-    }
-    catch {
-        // non-fatal
-    }
-    return value;
+        else {
+            unwrapped = raw;
+        }
+        // Write to edge cache (fire-and-forget — failure must not affect return value).
+        if (edgeTtlSec > 0) {
+            setEdgeCache(key, unwrapped, edgeTtlSec).catch(() => { });
+        }
+        // ttlMs for L1 = same window as edge TTL so both layers expire together.
+        const l1TtlMs = edgeTtlSec * 1000;
+        return { value: unwrapped, ttlMs: l1TtlMs };
+    });
 }

package/dist/runtime/dedupe-promise-cache.d.ts

@@ -0,0 +1,9 @@
+export declare class DedupePromiseCache<T> {
+    private readonly map;
+    getOrCreate(key: string, factory: () => Promise<{
+        value: T;
+        ttlMs?: number;
+    }>): Promise<T>;
+    delete(key: string): void;
+    clear(): void;
+}

package/dist/runtime/dedupe-promise-cache.js

@@ -0,0 +1,53 @@
+// src/runtime/dedupe-promise-cache.ts
+export class DedupePromiseCache {
+    map = new Map();
+    getOrCreate(key, factory) {
+        const existing = this.map.get(key);
+        // 1. In-flight → dedupe.
+        if (existing?.expiresAt === 0)
+            return existing.promise;
+        // 2. Valid cache entry → reuse.
+        if (existing && existing.expiresAt > Date.now())
+            return existing.promise;
+        // 3. Miss / expired → evict and run factory.
+        if (existing)
+            this.map.delete(key);
+        let resolveFn;
+        let rejectFn;
+        const promise = new Promise((resolve, reject) => {
+            resolveFn = resolve;
+            rejectFn = reject;
+        });
+        // Suppress unhandled rejection on the sentinel promise itself.
+        // Callers that attach after a failure will still receive the rejection
+        // via their own .catch / try-await — this only prevents the global warning
+        // for the case where no consumer is attached at the moment of rejection.
+        promise.catch(() => { });
+        // 🔥 Set sentinel BEFORE factory() so any concurrent getOrCreate()
+        // arriving during the async gap will dedupe on this promise.
+        this.map.set(key, { promise, expiresAt: 0 });
+        Promise.resolve()
+            .then(factory)
+            .then(({ value, ttlMs }) => {
+            resolveFn(value);
+            if (typeof ttlMs === "number" && ttlMs > 0) {
+                const resolved = Promise.resolve(value);
+                this.map.set(key, {
+                    promise: resolved,
+                    expiresAt: Date.now() + ttlMs,
+                });
+            }
+            else {
+                this.map.delete(key);
+            }
+        })
+            .catch((err) => {
+            rejectFn(err);
+            // Remove poisoned sentinel so the next caller retries.
+            this.map.delete(key);
+        });
+        return promise;
+    }
+    delete(key) { this.map.delete(key); }
+    clear() { this.map.clear(); }
+}

package/package.json

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