@vizamodo/edge-cache-core 0.3.35 → 0.3.38

package/dist/runtime/cache.d.ts

@@ -1,10 +1,36 @@
+/**
+ * Fetcher can return a plain value T, or a WrappedResult<T> to communicate
+ * a server-side expiry time back to the cache layer.
+ */
 export type WrappedResult<T> = {
     readonly __wrapped: true;
     readonly value: T;
+    /**
+     * ISO-8601 timestamp. When present, the cache derives its TTL from this
+     * value (minus EDGE_BUFFER_SEC) instead of using the caller-supplied ttlSec.
+     */
     readonly expiresAt: string | undefined;
 };
 export declare function wrapResult<T>(value: T, expiresAt?: string): WrappedResult<T>;
-export declare function getCachedOrFetch<T>(key: string, fetcher: () => Promise<T | WrappedResult<T>>, options: {
+export type GetCachedOrFetchOptions = {
+    /**
+     * Default TTL (seconds) used when the fetcher does not supply an expiresAt.
+     */
     ttlSec: number;
+    /**
+     * When true, bypass L1 and L2 and re-populate them with a fresh value.
+     *
+     * Two concurrent force-refresh calls for the same key will both hit the
+     * fetcher independently — this is intentional. If you need exactly-once
+     * semantics on force-refresh, that belongs inside DedupePromiseCache.
+     */
     forceRefresh?: boolean;
-}): Promise<T>;
+};
+/**
+ * Three-layer cache:
+ *
+ *  L1 — in-process DedupePromiseCache  (per-isolate, concurrent-safe)
+ *  L2 — edge / distributed cache       (getEdgeCache / setEdgeCache)
+ *  L3 — fetcher callback
+ */
+export declare function getCachedOrFetch<T>(key: string, fetcher: () => Promise<T | WrappedResult<T>>, options: GetCachedOrFetchOptions): Promise<T>;

package/dist/runtime/cache.js

@@ -9,60 +9,89 @@ function isWrapped(v) {
         v["__wrapped"] === true);
 }
 // ── Constants ──────────────────────────────────────────────────────────────
-const EDGE_BUFFER_SEC = 300; // 5-min safety buffer before expiry
+/** Subtracted from the server-reported expiry as a safety buffer. */
+const EDGE_BUFFER_SEC = 300; // 5 min
+/** Floor for the computed edge TTL to avoid near-zero useless writes. */
 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.
+// One shared instance per isolate. The map is keyed by string and stores
+// heterogeneous value types, so the outer type parameter is `unknown`.
+// Type-safety is restored at the call-site via the generic on getCachedOrFetch.
 const l1 = new DedupePromiseCache();
+// ── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Derive the edge TTL (seconds) from an optional ISO-8601 expiry string.
+ *
+ * Returns:
+ *  - A positive number (>= MIN_TTL_SEC) when the expiry is usefully in the future.
+ *  - 0 when the expiry is absent, invalid, already past, or within the buffer.
+ */
+function deriveEdgeTtlSec(expiresAt, fallbackSec) {
+    if (!expiresAt)
+        return fallbackSec;
+    const expiresMs = Date.parse(expiresAt);
+    if (!Number.isFinite(expiresMs)) {
+        console.warn("[cache] expiresAt is not a valid ISO-8601 date", { expiresAt });
+        return 0;
+    }
+    const remainingSec = Math.floor((expiresMs - Date.now()) / 1000);
+    if (remainingSec <= 0)
+        return 0; // already expired
+    return Math.max(remainingSec - EDGE_BUFFER_SEC, MIN_TTL_SEC);
+}
+/**
+ * Unwrap the fetcher result and compute the effective edge TTL in one pass.
+ */
+function resolveResult(raw, fallbackTtlSec) {
+    if (!isWrapped(raw)) {
+        return { value: raw, edgeTtlSec: fallbackTtlSec };
+    }
+    return {
+        value: raw.value,
+        edgeTtlSec: deriveEdgeTtlSec(raw.expiresAt, fallbackTtlSec),
+    };
+}
 // ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Three-layer cache:
+ *
+ *  L1 — in-process DedupePromiseCache  (per-isolate, concurrent-safe)
+ *  L2 — edge / distributed cache       (getEdgeCache / setEdgeCache)
+ *  L3 — fetcher callback
+ */
 export async function getCachedOrFetch(key, fetcher, options) {
     const { ttlSec, forceRefresh = false } = options;
-    // 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) ─────────────────────────────
+    // DedupePromiseCache is typed as `unknown`; the single `as T` below is the
+    // only unsafe boundary in this module. It is safe because every write path
+    // inside the factory produces a value of type T.
+    const value = await l1.getOrCreate(key, async () => {
+        // ── L2: edge cache ──────────────────────────────────────────────────
         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).
+            const edgeValue = await getEdgeCache(key).catch((err) => {
+                console.error("[cache][edge-get-failed]", { key, err });
+                return null;
+            });
+            if (edgeValue != null) {
+                // Edge TTL is not externally observable. We use the caller-supplied
+                // ttlSec as an upper bound for L1. In the worst case L1 serves data
+                // slightly past the edge expiry — an accepted trade-off for skipping
+                // a second edge round-trip. To close this gap, store the expiry
+                // timestamp alongside the value in the edge cache and thread it back.
                 return { value: edgeValue, ttlMs: ttlSec * 1000 };
             }
         }
-        // ── L3: fetcher ───────────────────────────────────────────────────────
+        // ── 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;
-                }
-            }
-        }
-        else {
-            unwrapped = raw;
-        }
-        // Write to edge cache (must await to ensure commit before worker exits).
+        const { value: unwrapped, edgeTtlSec } = resolveResult(raw, ttlSec);
         if (edgeTtlSec > 0) {
-            try {
-                await setEdgeCache(key, unwrapped, edgeTtlSec);
-            }
-            catch {
-                // best-effort: do not break response on cache failure
-            }
+            await setEdgeCache(key, unwrapped, edgeTtlSec).catch((err) => {
+                console.error("[cache][edge-set-failed]", { key, err });
+            });
         }
-        // ttlMs for L1 = same window as edge TTL so both layers expire together.
-        const l1TtlMs = edgeTtlSec * 1000;
-        return { value: unwrapped, ttlMs: l1TtlMs };
+        // Mirror L1 TTL to edge TTL so both layers expire around the same time.
+        return { value: unwrapped, ttlMs: edgeTtlSec * 1000 };
     });
+    return value;
 }

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

@@ -6,4 +6,10 @@ export declare class DedupePromiseCache<T> {
     }>): Promise<T>;
     delete(key: string): void;
     clear(): void;
+    /**
+     * Remove all expired entries (in-flight sentinels are kept).
+     * Falls back to a full clear when the map is still over the limit after
+     * eviction — this is a last resort to avoid unbounded memory growth.
+     */
+    private evict;
 }

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

@@ -1,53 +1,84 @@
 // src/runtime/dedupe-promise-cache.ts
+const MAX_ENTRIES = 1_000;
 export class DedupePromiseCache {
     map = new Map();
     getOrCreate(key, factory) {
+        const now = Date.now();
         const existing = this.map.get(key);
-        // 1. In-flight → dedupe.
+        // 1. In-flight → dedupe on the sentinel promise.
         if (existing?.expiresAt === 0)
             return existing.promise;
-        // 2. Valid cache entry → reuse.
-        if (existing && existing.expiresAt > Date.now())
+        // 2. Valid (non-expired) entry → reuse.
+        if (existing && existing.expiresAt > now)
             return existing.promise;
-        // 3. Miss / expired → evict and run factory.
+        // 3. Stale entry → evict before running factory.
         if (existing)
             this.map.delete(key);
+        // Evict expired entries when the map is getting large.
+        // Runs before the new key is inserted so the size check is accurate.
+        if (this.map.size >= MAX_ENTRIES)
+            this.evict();
+        // Build the public promise separately from the resolution handles so we
+        // can suppress the unhandled-rejection warning on the sentinel itself
+        // while still propagating errors to callers who await the returned promise.
         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.
+        // Prevent "unhandled rejection" warnings for the case where rejection
+        // occurs before any external .catch / await is attached.
         promise.catch(() => { });
         // 🔥 Set sentinel BEFORE factory() so any concurrent getOrCreate()
-        // arriving during the async gap will dedupe on this promise.
+        // call during the async gap dedupes on this promise.
         this.map.set(key, { promise, expiresAt: 0 });
+        // Run factory asynchronously so the sentinel is visible to all callers
+        // synchronously queued after this point.
         Promise.resolve()
             .then(factory)
             .then(({ value, ttlMs }) => {
             resolveFn(value);
-            if (typeof ttlMs === "number" && ttlMs > 0) {
-                const resolved = Promise.resolve(value);
+            if (ttlMs != null && Number.isFinite(ttlMs) && ttlMs > 0) {
+                // Capture Date.now() AFTER factory resolves for an accurate expiry.
                 this.map.set(key, {
-                    promise: resolved,
+                    promise: Promise.resolve(value),
                     expiresAt: Date.now() + ttlMs,
                 });
             }
             else {
+                // ttlMs = 0 or undefined → do not cache the resolved value.
                 this.map.delete(key);
             }
         })
             .catch((err) => {
             rejectFn(err);
-            // Remove poisoned sentinel so the next caller retries.
+            // Remove the poisoned sentinel so the next caller retries the factory.
             this.map.delete(key);
         });
         return promise;
     }
-    delete(key) { this.map.delete(key); }
-    clear() { this.map.clear(); }
+    delete(key) {
+        this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+    }
+    // ── Private helpers ────────────────────────────────────────────────────
+    /**
+     * Remove all expired entries (in-flight sentinels are kept).
+     * Falls back to a full clear when the map is still over the limit after
+     * eviction — this is a last resort to avoid unbounded memory growth.
+     */
+    evict() {
+        const now = Date.now();
+        for (const [k, v] of this.map) {
+            if (v.expiresAt !== 0 && v.expiresAt <= now) {
+                this.map.delete(k);
+            }
+        }
+        if (this.map.size >= MAX_ENTRIES) {
+            this.map.clear();
+        }
+    }
 }

package/dist/runtime/edge-cache.d.ts

@@ -1,8 +1,14 @@
 /**
- * Generic edge cache GET helper
+ * Reads a value from the edge cache.
+ * Returns `null` on cache miss, parse failure, or any runtime error.
  */
 export declare function getEdgeCache<T>(key: string): Promise<T | null>;
 /**
- * Generic edge cache SET helper
+ * Writes a value to the edge cache with the given TTL.
+ * Platform-agnostic: no ExecutionContext required.
+ *
+ * @param key    - Cache key (arbitrary string).
+ * @param value  - Any JSON-serialisable value.
+ * @param ttlSec - Time-to-live in seconds. Values <= 0 are ignored.
  */
 export declare function setEdgeCache(key: string, value: unknown, ttlSec: number): Promise<void>;

package/dist/runtime/edge-cache.js

@@ -1,88 +1,88 @@
 const CACHE_KEY_PREFIX = "https://edge-cache.internal/";
+/**
+ * Encodes a cache key to a safe URL-compatible base64 string.
+ * Uses a loop instead of spread to avoid stack overflow on long keys.
+ */
 function normalizeKey(key) {
-    return btoa(unescape(encodeURIComponent(key)));
+    const bytes = new TextEncoder().encode(key);
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+/**
+ * Wraps primitive values so the stored JSON always has a stable object shape.
+ * Objects are stored as-is; primitives get wrapped with a sentinel flag.
+ */
+function wrap(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : { __primitive: true, value };
+}
+function unwrap(parsed) {
+    if (parsed !== null &&
+        typeof parsed === "object" &&
+        "__primitive" in parsed &&
+        parsed.__primitive === true) {
+        return parsed.value;
+    }
+    return parsed;
 }
 /**
- * Generic edge cache GET helper
+ * Reads a value from the edge cache.
+ * Returns `null` on cache miss, parse failure, or any runtime error.
  */
 export async function getEdgeCache(key) {
+    const cacheKey = CACHE_KEY_PREFIX + normalizeKey(key);
+    let res;
     try {
-        const cache = caches.default;
-        const req = new Request(CACHE_KEY_PREFIX + normalizeKey(key));
-        console.debug("[edge-cache] GET", { key, url: req.url });
-        const res = await cache.match(req);
-        console.debug("[edge-cache] MATCH RESULT", {
-            key,
-            hasResponse: !!res,
-            status: res?.status,
-            headers: res ? Object.fromEntries(res.headers.entries()) : null,
-        });
-        if (!res) {
-            console.debug("[edge-cache] MISS", { key });
-            return null;
-        }
-        console.debug("[edge-cache] HIT", {
-            key,
-            status: res.status,
-            headers: Object.fromEntries(res.headers.entries()),
-        });
-        try {
-            const data = await res.clone().text();
-            console.debug("[edge-cache] HIT RAW", {
-                key,
-                size: data.length,
-                preview: data.slice(0, 200), // avoid huge logs
-            });
-            let parsed;
-            try {
-                parsed = JSON.parse(data);
-            }
-            catch (err) {
-                console.error("[edge-cache] JSON PARSE FAILED", { key, err, dataPreview: data.slice(0, 200) });
-                return null;
-            }
-            console.debug("[edge-cache] PARSED OK", {
-                key,
-                type: typeof parsed,
-            });
-            return parsed;
-        }
-        catch {
-            // corrupted cache entry → ignore
-            return null;
-        }
+        res = await caches.default.match(new Request(cacheKey));
+    }
+    catch (err) {
+        console.error("[edge-cache] GET match failed", { key, err });
+        return null;
+    }
+    if (!res)
+        return null;
+    let raw;
+    try {
+        raw = await res.text();
+    }
+    catch (err) {
+        console.error("[edge-cache] GET read body failed", { key, err });
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return unwrap(parsed);
     }
     catch (err) {
-        console.error("[edge-cache] GET FAILED", { key, err });
+        console.error("[edge-cache] GET JSON parse failed", {
+            key,
+            err,
+            preview: raw.slice(0, 200),
+        });
         return null;
     }
 }
 /**
- * Generic edge cache SET helper
+ * Writes a value to the edge cache with the given TTL.
+ * Platform-agnostic: no ExecutionContext required.
+ *
+ * @param key    - Cache key (arbitrary string).
+ * @param value  - Any JSON-serialisable value.
+ * @param ttlSec - Time-to-live in seconds. Values <= 0 are ignored.
  */
 export async function setEdgeCache(key, value, ttlSec) {
     if (ttlSec <= 0)
         return;
-    const cache = caches.default;
-    const req = new Request(CACHE_KEY_PREFIX + normalizeKey(key));
-    console.debug("[edge-cache] SET", { key, url: req.url, ttlSec });
-    const body = JSON.stringify(value);
+    const cacheKey = CACHE_KEY_PREFIX + normalizeKey(key);
+    const body = JSON.stringify(wrap(value));
     const res = new Response(body, {
         headers: {
             "Content-Type": "application/json",
             "Cache-Control": `max-age=${ttlSec}`,
         },
     });
-    try {
-        console.debug("[edge-cache] SET BODY SIZE", { key, size: body.length });
-        const t0 = Date.now();
-        await cache.put(req, res);
-        // Force event loop flush to ensure write completes before worker exits
-        await new Promise((r) => setTimeout(r, 0));
-        const t1 = Date.now();
-        console.debug("[edge-cache] SET OK", { key, durationMs: t1 - t0 });
-    }
-    catch (err) {
-        console.error("[edge-cache] SET FAILED", { key, err });
-    }
+    await caches.default.put(new Request(cacheKey), res);
 }

package/package.json

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