@mmstack/resource 20.8.1 → 20.8.3

package/fesm2022/mmstack-resource.mjs

@@ -1,8 +1,8 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, inject, runInInjectionContext, DestroyRef, isDevMode, untracked, computed, signal, effect, Injector, Injectable, linkedSignal } from '@angular/core';
-import { injectTransitionScope, mutable, toWritable, keepPrevious, sensor, nestedEffect } from '@mmstack/primitives';
+import { InjectionToken, inject, runInInjectionContext, DestroyRef, isDevMode, signal, computed, untracked, PLATFORM_ID, effect, Injector, Injectable, linkedSignal } from '@angular/core';
 import { HttpHeaders, HttpResponse, HttpParams, HttpContextToken, HttpContext, httpResource, HttpClient } from '@angular/common/http';
-import { of, tap, map, finalize, shareReplay, interval, firstValueFrom, catchError, combineLatestWith, filter } from 'rxjs';
+import { injectTransitionScope, mutable, toWritable, keepPrevious, sensor, injectPaused, nestedEffect } from '@mmstack/primitives';
+import { finalize, shareReplay, of, tap, map, interval, firstValueFrom, catchError, combineLatestWith, filter } from 'rxjs';
 import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
 
 const RESOURCE_OPTIONS = new InjectionToken('@mmstack/resource:resource-options', { factory: () => ({}) });
@@ -62,6 +62,8 @@ function toCacheDB(db, storeName) {
             const request = store.getAll();
             request.onsuccess = () => res(request.result);
             request.onerror = () => rej(request.error);
+            // some browsers abort (rather than error) e.g. on quota issues — without this the promise would stay pending forever
+            transaction.onabort = () => rej(transaction.error);
         })
             .then((entries) => entries.filter((e) => e.expiresAt > now))
             .catch((err) => {
@@ -77,6 +79,8 @@ function toCacheDB(db, storeName) {
             store.put(value);
             transaction.oncomplete = () => res();
             transaction.onerror = () => rej(transaction.error);
+            // QuotaExceededError surfaces as an abort in some browsers
+            transaction.onabort = () => rej(transaction.error);
         }).catch((err) => {
             if (isDevMode())
                 console.error('Error storing item in cache DB:', err);
@@ -89,6 +93,7 @@ function toCacheDB(db, storeName) {
             store.delete(key);
             transaction.oncomplete = () => res();
             transaction.onerror = () => rej(transaction.error);
+            transaction.onabort = () => rej(transaction.error);
         }).catch((err) => {
             if (isDevMode())
                 console.error('Error removing item from cache DB:', err);
@@ -105,8 +110,10 @@ function createSingleStoreDB(name, getStoreName, version = 1) {
     if (!globalThis.indexedDB)
         return Promise.resolve(createNoopDB());
     return new Promise((res, rej) => {
-        if (version < 1)
+        if (version < 1) {
             rej(new Error('Version must be 1 or greater'));
+            return; // rej does not stop execution — without this, indexedDB.open(name, 0) still runs
+        }
         const req = indexedDB.open(name, version);
         req.onupgradeneeded = (event) => {
             const db = req.result;
@@ -141,6 +148,13 @@ function isSyncMessage(msg) {
         'type' in msg &&
         msg.type === 'cache-sync-message');
 }
+/**
+ * setTimeout coerces its delay through a signed 32-bit conversion: `Infinity` becomes 0
+ * (immediate!) and anything above 2^31-1 ms (~24.8 days) wraps negative. Entries beyond
+ * this bound get NO timer and rely on lazy expiry (`expiresAt <= now` checks) plus the
+ * periodic sweep instead.
+ */
+const MAX_TIMER_DELAY = 2 ** 31 - 1;
 const ONE_DAY = 1000 * 60 * 60 * 24;
 const ONE_HOUR = 1000 * 60 * 60;
 const DEFAULT_CLEANUP_OPT = {
@@ -160,9 +174,27 @@ class Cache {
     internal = mutable(new Map());
     cleanupOpt;
     id = generateID();
+    /** True once async hydration from the persistence layer has completed (or was empty). */
+    hydrated = false;
+    /** Keys invalidated while hydration was still in flight — must not be resurrected by it. */
+    hydrationTombstones = new Set();
+    hitCount = signal(0, ...(ngDevMode ? [{ debugName: "hitCount" }] : []));
+    missCount = signal(0, ...(ngDevMode ? [{ debugName: "missCount" }] : []));
     /**
-     * Destroys the cache instance, cleaning up any resources used by the cache.
-     * This method is called automatically when the cache instance is garbage collected.
+     * Read-only cache statistics for debugging/observability — entry count plus
+     * request-level hit/miss counters (counted on direct lookups, e.g. the cache
+     * interceptor's, not on every reactive signal read). Render it in a debug
+     * panel; it intentionally exposes no way to mutate the cache.
+     */
+    stats = computed(() => ({
+        size: this.internal().size,
+        hits: this.hitCount(),
+        misses: this.missCount(),
+    }), ...(ngDevMode ? [{ debugName: "stats" }] : []));
+    /**
+     * Destroys the cache instance, clearing the cleanup interval and closing the
+     * cross-tab channel. Called automatically when the providing injector is destroyed
+     * (wired up by `provideQueryCache`); call it manually for caches you construct yourself.
      */
     destroy;
     broadcast = () => {
@@ -179,11 +211,7 @@ class Cache {
      * @param syncTabs - If provided, the cache will use the options a BroadcastChannel to send updates between tabs.
      *                   Defaults to `undefined`, meaning no synchronization across tabs.
      */
-    constructor(ttl = ONE_DAY, staleTime = ONE_HOUR, cleanupOpt = {
-        type: 'lru',
-        maxSize: 1000,
-        checkInterval: ONE_HOUR,
-    }, syncTabs, db = Promise.resolve(createNoopDB())) {
+    constructor(ttl = ONE_DAY, staleTime = ONE_HOUR, cleanupOpt = DEFAULT_CLEANUP_OPT, syncTabs, db = Promise.resolve(createNoopDB())) {
         this.ttl = ttl;
         this.staleTime = staleTime;
         this.db = db;
@@ -193,10 +221,12 @@ class Cache {
         };
         if (this.cleanupOpt.maxSize <= 0)
             throw new Error('maxSize must be greater than 0');
-        // cleanup cache based on provided options regularly
-        const cleanupInterval = setInterval(() => {
-            this.cleanup();
-        }, cleanupOpt.checkInterval);
+        // a non-finite checkInterval disables the sweeper entirely (used by the shared NoopCache)
+        const cleanupInterval = Number.isFinite(this.cleanupOpt.checkInterval)
+            ? setInterval(() => {
+                this.cleanup();
+            }, this.cleanupOpt.checkInterval)
+            : undefined;
         let destroySyncTabs = () => {
             // noop
         };
@@ -230,13 +260,11 @@ class Cache {
                     const value = syncTabs.deserialize(msg.entry.value);
                     if (value === null)
                         return;
-                    // Last-write-wins by `updated` timestamp. If our local entry was
-                    // written more recently than the broadcast we just received, the
-                    // broadcast is stale (in-flight when we wrote locally) — drop it.
+                    // Last-write-wins by `updated` timestamp.
                     const existing = untracked(this.internal).get(msg.entry.key);
                     if (existing && existing.updated >= msg.entry.updated)
                         return;
-                    this.storeInternal(msg.entry.key, value, msg.entry.stale - msg.entry.updated, msg.entry.expiresAt - msg.entry.updated, true, false);
+                    this.restoreInternal({ ...msg.entry, value });
                 }
                 else if (msg.action === 'invalidate') {
                     this.invalidateInternal(msg.entry.key, true);
@@ -251,7 +279,8 @@ class Cache {
             if (destroyed)
                 return;
             destroyed = true;
-            clearInterval(cleanupInterval);
+            if (cleanupInterval !== undefined)
+                clearInterval(cleanupInterval);
             destroySyncTabs();
         };
         this.db
@@ -263,22 +292,19 @@ class Cache {
             .then((entries) => {
             if (destroyed)
                 return;
-            // load entries into the cache
             const current = untracked(this.internal);
             entries.forEach((entry) => {
                 if (current.has(entry.key))
                     return;
-                this.storeInternal(entry.key, entry.value, entry.stale - entry.updated, entry.expiresAt - entry.updated, true);
+                // a key invalidated while hydration was in flight must stay dead
+                if (this.hydrationTombstones.has(entry.key))
+                    return;
+                this.restoreInternal(entry);
             });
+            this.hydrated = true;
+            this.hydrationTombstones.clear();
         });
         this.destroy = destroy;
-        // cleanup if object is garbage collected, this is because the cache can be quite large from a memory standpoint & we dont want all that floating garbage
-        const registry = new FinalizationRegistry((id) => {
-            if (id === this.id) {
-                destroy();
-            }
-        });
-        registry.register(this, this.id);
     }
     /** @internal */
     getInternal(key) {
@@ -291,22 +317,45 @@ class Cache {
             const now = Date.now();
             if (!found || found.expiresAt <= now)
                 return null;
-            found.useCount++;
             return {
                 ...found,
                 isStale: found.stale <= now,
             };
+        }, {
+            equal: (a, b) => a === b ||
+                (!!a &&
+                    !!b &&
+                    a.key === b.key &&
+                    a.value === b.value &&
+                    a.updated === b.updated &&
+                    a.isStale === b.isStale),
         });
     }
+    /** @internal Imperative access bookkeeping for LRU eviction. */
+    touch(entry) {
+        entry.lastAccessed = Date.now();
+        entry.useCount++;
+    }
     /**
-     * Retrieves a cache entry without affecting its usage count (for LRU).  This is primarily
-     * for internal use or debugging.
+     * Retrieves a cache entry directly (non-reactively), updating its access bookkeeping
+     * for LRU eviction.
      * @internal
      * @param key - The key of the entry to retrieve.
      * @returns The cache entry, or `null` if not found or expired.
      */
     getUntracked(key) {
-        return untracked(this.getInternal(() => key));
+        const found = untracked(this.internal).get(key);
+        const now = Date.now();
+        if (!found || found.expiresAt <= now) {
+            this.missCount.update((c) => c + 1);
+            return null;
+        }
+        this.touch(found);
+        this.hitCount.update((c) => c + 1);
+        return {
+            ...found,
+            isStale: found.stale <= now,
+        };
     }
     /**
      * Retrieves a cache entry as a signal.
@@ -332,38 +381,65 @@ class Cache {
     /**
      * Stores a value in the cache.
      *
+     * NOTE: cached values are shared by reference across all consumers (current and
+     * future cache hits, persistence, cross-tab sync) — do not mutate a value after
+     * storing it or after reading it from the cache.
+     *
      * @param key - The key under which to store the value.
      * @param value - The value to store.
      * @param staleTime - (Optional) The stale time for this entry, in milliseconds. Overrides the default `staleTime`.
      * @param ttl - (Optional) The TTL for this entry, in milliseconds. Overrides the default `ttl`.
+     * @param persist - (Optional) Whether to also write the entry to the persistence layer (IndexedDB). Defaults to `false`.
      */
     store(key, value, staleTime = this.staleTime, ttl = this.ttl, persist = false) {
         this.storeInternal(key, value, staleTime, ttl, false, persist);
     }
     storeInternal(key, value, staleTime = this.staleTime, ttl = this.ttl, fromSync = false, persist = false) {
-        const entry = this.getUntracked(key);
-        if (entry) {
-            clearTimeout(entry.timeout); // stop invalidation
-        }
-        const prevCount = entry?.useCount ?? 0;
+        const entry = untracked(this.internal).get(key);
         // ttl cannot be less than staleTime
         if (ttl < staleTime)
             staleTime = ttl;
         const now = Date.now();
-        const next = {
+        this.setEntry({
             value,
             created: entry?.created ?? now,
             updated: now,
-            useCount: prevCount + 1,
+            useCount: (entry?.useCount ?? 0) + 1,
+            lastAccessed: now,
             stale: now + staleTime,
             expiresAt: now + ttl,
             key,
-        };
+        }, fromSync, persist);
+    }
+    /**
+     * @internal
+     * Inserts an entry that already carries ABSOLUTE timestamps — hydration from the
+     * persistence layer and cross-tab sync messages. Never re-anchors freshness to
+     * `Date.now()`, never persists, never broadcasts.
+     */
+    restoreInternal(entry) {
+        this.setEntry({
+            ...entry,
+            // rows persisted by older versions may lack the field
+            lastAccessed: entry.lastAccessed ?? entry.updated,
+        }, true, false);
+    }
+    /** @internal Shared writer: arms the expiry timer only within the safe delay range. */
+    setEntry(next, fromSync, persist) {
+        const existing = untracked(this.internal).get(next.key);
+        if (existing)
+            clearTimeout(existing.timeout); // stop the previous invalidation
+        const remaining = next.expiresAt - Date.now();
+        // already expired (clock skew on a synced/restored entry) — don't insert
+        if (remaining <= 0)
+            return;
+        // Infinity (immutable) or > 2^31-1 would coerce to an IMMEDIATE timeout — such
+        // entries get no timer and rely on lazy expiry + the periodic sweep instead
+        const timeout = Number.isFinite(remaining) && remaining <= MAX_TIMER_DELAY
+            ? setTimeout(() => this.invalidate(next.key), remaining)
+            : undefined;
         this.internal.mutate((map) => {
-            map.set(key, {
-                ...next,
-                timeout: setTimeout(() => this.invalidate(key), ttl),
-            });
+            map.set(next.key, { ...next, timeout });
             return map;
         });
         if (!fromSync) {
@@ -409,32 +485,55 @@ class Cache {
         return keys.length;
     }
     invalidateInternal(key, fromSync = false) {
-        const entry = this.getUntracked(key);
-        if (!entry)
-            return;
-        clearTimeout(entry.timeout);
-        this.internal.mutate((map) => {
-            map.delete(key);
-            return map;
-        });
+        // a key invalidated before async hydration completes must not be resurrected by it
+        if (!this.hydrated)
+            this.hydrationTombstones.add(key);
+        const entry = untracked(this.internal).get(key);
+        if (entry) {
+            clearTimeout(entry.timeout);
+            this.internal.mutate((map) => {
+                map.delete(key);
+                return map;
+            });
+        }
         if (!fromSync) {
             this.db.then((db) => db.remove(key));
             this.broadcast({ action: 'invalidate', entry: { key } });
         }
     }
-    /** @internal */
+    /**
+     * Removes EVERY entry — memory, persisted rows, and (via broadcast) other tabs.
+     * Call on logout/auth changes so no prior user's responses survive.
+     */
+    clear() {
+        for (const key of Array.from(untracked(this.internal).keys())) {
+            this.invalidateInternal(key);
+        }
+    }
+    /** @internal Drops expired entries, then enforces `maxSize` by the configured strategy. */
     cleanup() {
+        const now = Date.now();
+        // expired entries first — their timers may never have fired (throttled background
+        // tabs, or timer-less long-TTL entries)
+        const expired = Array.from(untracked(this.internal).entries()).filter(([, e]) => e.expiresAt <= now);
+        if (expired.length) {
+            expired.forEach(([, e]) => clearTimeout(e.timeout));
+            this.internal.mutate((map) => {
+                expired.forEach(([key]) => map.delete(key));
+                return map;
+            });
+        }
         if (untracked(this.internal).size <= this.cleanupOpt.maxSize)
             return;
         const sorted = Array.from(untracked(this.internal).entries()).toSorted((a, b) => {
             if (this.cleanupOpt.type === 'lru') {
-                return a[1].useCount - b[1].useCount; // least used first
+                return a[1].lastAccessed - b[1].lastAccessed; // least recently accessed first
             }
             else {
                 return a[1].created - b[1].created; // oldest first
             }
         });
-        const keepCount = Math.floor(this.cleanupOpt.maxSize / 2);
+        const keepCount = Math.max(1, Math.floor(this.cleanupOpt.maxSize / 2));
         const removed = sorted.slice(0, sorted.length - keepCount);
         const keep = sorted.slice(removed.length, sorted.length);
         removed.forEach(([, e]) => {
@@ -479,7 +578,8 @@ function provideQueryCache(opt) {
         return JSON.stringify({
             body: value.body,
             status: value.status,
-            statusText: value.statusText,
+            // statusText intentionally omitted: deprecated in Angular, meaningless under
+            // HTTP/2+ (HttpResponse defaults it to 'OK' on reconstruction)
             headers: headerKeys.length > 0 ? headersRecord : undefined,
             url: value.url,
         });
@@ -495,7 +595,6 @@ function provideQueryCache(opt) {
             return new HttpResponse({
                 body: parsed.body,
                 status: parsed.status,
-                statusText: parsed.statusText,
                 headers: headers,
                 url: parsed.url,
             });
@@ -506,48 +605,72 @@ function provideQueryCache(opt) {
             return null;
         }
     };
-    const syncTabsOpt = opt?.syncTabs
-        ? {
-            id: 'mmstack-query-cache-sync',
-            serialize,
-            deserialize,
-        }
-        : undefined;
-    const db = opt?.persist === false
-        ? undefined
-        : createSingleStoreDB('mmstack-query-cache-db', (version) => `query-store_v${version}`, opt?.version).then((db) => {
-            return {
-                getAll: () => {
-                    return db.getAll().then((entries) => {
-                        return entries
-                            .map((entry) => {
-                            const value = deserialize(entry.value);
-                            if (value === null)
-                                return null;
-                            return {
-                                ...entry,
-                                value,
-                            };
-                        })
-                            .filter((e) => e !== null);
-                    });
-                },
-                store: (entry) => {
-                    return db.store({ ...entry, value: serialize(entry.value) });
-                },
-                remove: db.remove,
-            };
-        });
+    // version-suffixed so two deploys with incompatible schemas in adjacent tabs don't
+    // push entries into each other's caches (the `version` option only fences IndexedDB)
+    const syncChannelId = `mmstack-query-cache-sync_v${opt?.version ?? 1}`;
     return {
         provide: CLIENT_CACHE_TOKEN,
-        useValue: new Cache(opt?.ttl, opt?.staleTime, opt?.cleanup, syncTabsOpt, db),
+        useFactory: () => {
+            const onServer = inject(PLATFORM_ID) === 'server';
+            // no IndexedDB / BroadcastChannel on the server — each request gets an
+            // isolated, request-lived, memory-only cache
+            const syncTabsOpt = !onServer && opt?.syncTabs
+                ? {
+                    id: syncChannelId,
+                    serialize,
+                    deserialize,
+                }
+                : undefined;
+            const db = onServer || opt?.persist === false
+                ? undefined
+                : createSingleStoreDB('mmstack-query-cache-db', (version) => `query-store_v${version}`, opt?.version).then((db) => {
+                    return {
+                        getAll: () => {
+                            return db.getAll().then((entries) => {
+                                return entries
+                                    .map((entry) => {
+                                    const value = deserialize(entry.value);
+                                    if (value === null)
+                                        return null;
+                                    return {
+                                        ...entry,
+                                        value,
+                                    };
+                                })
+                                    .filter((e) => e !== null);
+                            });
+                        },
+                        store: (entry) => {
+                            return db.store({ ...entry, value: serialize(entry.value) });
+                        },
+                        remove: db.remove,
+                    };
+                });
+            const cache = new Cache(opt?.ttl, opt?.staleTime, opt?.cleanup, syncTabsOpt, db);
+            // release the sweep interval / channel with the providing injector
+            inject(DestroyRef, { optional: true })?.onDestroy(() => cache.destroy());
+            return cache;
+        },
     };
 }
 class NoopCache extends Cache {
+    constructor() {
+        // Infinity checkInterval → no sweep interval is ever armed, so the shared
+        // instance below never pins a timer
+        super(undefined, undefined, {
+            type: 'lru',
+            maxSize: 200,
+            checkInterval: Infinity,
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     store(_, __, ___ = super.staleTime, ____ = super.ttl) {
         // noop
     }
 }
+// one shared instance — minting a NoopCache per injectQueryCache() miss would leak
+// an instance (and previously an interval) on every prod call without a provider
+let NOOP_CACHE;
 /**
  * Injects the `QueryCache` instance that is used within queryResource.
  * Allows for direct modification of cached data, but is mostly meant for internal use.
@@ -582,10 +705,21 @@ function injectQueryCache(injector) {
         if (isDevMode())
             throw new Error('Cache not provided, please add provideQueryCache() to providers array');
         else
-            return new NoopCache();
+            return (NOOP_CACHE ??= new NoopCache());
     }
     return cache;
 }
+/**
+ * Injects the cache statistics, including the current size of the cache and the number of hits and misses.
+ *
+ * @param injector - (Optional) The injector to use.  If not provided, the current
+ *                   injection context is used.
+ * @returns A signal containing the cache statistics.
+ */
+function injectCacheStats(injector) {
+    const cache = injectQueryCache(injector);
+    return cache.stats;
+}
 
 /**
  * Returns `true` for any object-like value whose own enumerable keys should
@@ -689,14 +823,121 @@ function hash(...args) {
     return hashKey(args);
 }
 
+/**
+ * @internal
+ * One-way ~64-bit digest from two independent FNV-1a passes. Used for header VALUES in
+ * cache keys: keys are persisted (IndexedDB) and broadcast cross-tab, so raw values
+ * (auth tokens!) must never appear in them. A single 32-bit digest's 2^-32 collision
+ * chance is too thin at a security boundary — two colliding tokens would serve one
+ * user's cached data under another user's key; 64 bits puts collisions out of reach.
+ * High-entropy secrets are not recoverable from the digest.
+ */
+function digestHeaderValue(value) {
+    let h1 = 0x811c9dc5; // FNV-1a offset basis
+    let h2 = 0xcbf29ce4; // independent second pass
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 0x01000193); // FNV prime
+        h2 = Math.imul(h2 ^ c, 0x01000197); // distinct odd multiplier
+    }
+    return ((h1 >>> 0).toString(16).padStart(8, '0') +
+        (h2 >>> 0).toString(16).padStart(8, '0'));
+}
+function readHeader(headers, name) {
+    if (!headers)
+        return null;
+    if (headers instanceof HttpHeaders) {
+        const all = headers.getAll(name);
+        return all && all.length ? all.join(',') : null;
+    }
+    // record form — header names are case-insensitive
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() !== lower)
+            continue;
+        const value = headers[key];
+        if (value == null)
+            return null;
+        return Array.isArray(value) ? value.join(',') : String(value);
+    }
+    return null;
+}
+/**
+ * Content-negotiation headers whose values are low-entropy and non-identifying —
+ * embedded (URI-encoded) raw, keeping keys human-readable and skipping the digest.
+ * Anything NOT on this list (Authorization, api keys, tenant/x-* headers — we can't
+ * know what they carry) is one-way digested instead.
+ */
+const SAFE_RAW_HEADERS = new Set([
+    'accept',
+    'accept-language',
+    'content-language',
+    'content-type',
+]);
+const UNSAFE_HEADER_MESSAGES = new Map([
+    [
+        'cookie',
+        "[@mmstack/resource]: varyHeaders includes 'cookie'. Browser-attached cookies never appear on the request object (so this usually partitions nothing), and manually-set cookie values often rotate per-request (shredding the hit rate). The header IS still honored (digested) — but prefer varying on 'Authorization' or a tenant header.",
+    ],
+    [
+        'set-cookie',
+        "[@mmstack/resource]: varyHeaders includes 'set-cookie'. Browser-attached cookies never appear on the request object (so this usually partitions nothing), and manually-set cookie values often rotate per-request (shredding the hit rate). The header IS still honored (digested) — but prefer varying on 'Authorization' or a tenant header.",
+    ],
+    [
+        'authorization',
+        "[@mmstack/resource]: varyHeaders includes 'Authorization'. If your token rotates frequently (e.g., short-lived JWTs), this will cause 100% cache churn on refresh. Consider adding a namespace prefix with the users sub, not using it as a cache-key or using a custom 'cache.hash' function with a stable session/user ID instead.",
+    ],
+    [
+        'x-request-id',
+        "[@mmstack/resource]: varyHeaders includes 'X-Request-ID'. This header is often set to a unique value per-request, which will cause 100% cache churn. Consider removing it from varyHeaders or using a custom 'cache.hash' function that ignores it.",
+    ],
+    [
+        'x-correlation-id',
+        "[@mmstack/resource]: varyHeaders includes 'X-Correlation-ID'. This header is often set to a unique value per-request, which will cause 100% cache churn. Consider removing it from varyHeaders or using a custom 'cache.hash' function that ignores it.",
+    ],
+    [
+        'if-none-match',
+        "[@mmstack/resource]: varyHeaders includes 'If-None-Match'. This header contains ETags that change whenever the server's resource version changes, which will cause cache misses on every update. Consider removing it from varyHeaders or using a custom 'cache.hash' function that ignores it.",
+    ],
+    [
+        'if-modified-since',
+        "[@mmstack/resource]: varyHeaders includes 'If-Modified-Since'. This header contains timestamps that change whenever the server's resource version changes, which will cause cache misses on every update. Consider removing it from varyHeaders or using a custom 'cache.hash' function that ignores it.",
+    ],
+]);
+function normalizeVaryHeaders(headers, names) {
+    const isDev = isDevMode();
+    return names
+        .map((n) => n.toLowerCase())
+        .toSorted()
+        .map((name) => {
+        if (isDev) {
+            const warning = UNSAFE_HEADER_MESSAGES.get(name);
+            if (warning)
+                console.warn(warning);
+        }
+        const value = readHeader(headers, name);
+        if (value === null)
+            return `${name}=`;
+        // known-safe values raw (readable, cheap); everything else digested, NEVER raw —
+        // keys are persisted to IndexedDB and broadcast across tabs
+        return SAFE_RAW_HEADERS.has(name)
+            ? `${name}=${encodeURIComponent(value)}`
+            : `${name}=${digestHeaderValue(value)}`;
+    })
+        .join('&');
+}
 function normalizeParams(params) {
-    const p = params instanceof HttpParams ? params : new HttpParams({ fromObject: params });
+    const p = params instanceof HttpParams
+        ? params
+        : new HttpParams({ fromObject: params });
     return p
         .keys()
         .toSorted()
         .map((key) => {
         const encodedKey = encodeURIComponent(key);
-        return (p.getAll(key) ?? []).map((v) => `${encodedKey}=${encodeURIComponent(v)}`).join('&');
+        return (p.getAll(key) ?? [])
+            .map((v) => `${encodedKey}=${encodeURIComponent(v)}`)
+            .join('&');
     })
         .join('&');
 }
@@ -716,7 +957,8 @@ function hashBody(body) {
         entries.sort(([ak, av], [bk, bv]) => ak.localeCompare(bk) || av.localeCompare(bv));
         return `FormData:${entries.map(([k, v]) => `${k}=${v}`).join('&')}`;
     }
-    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+    if (typeof URLSearchParams !== 'undefined' &&
+        body instanceof URLSearchParams) {
         const sp = new URLSearchParams(body);
         sp.sort();
         return `URLSearchParams:${sp.toString()}`;
@@ -733,20 +975,48 @@ function hashBody(body) {
  * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
  * `HttpRequest` and `HttpResourceRequest`).
  *
- * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}]`
+ * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}][:${vary}]`
  * - `method` defaults to `'GET'`, `responseType` to `'json'` (Angular defaults).
  * - Query params are sorted alphabetically and URL-encoded for stability.
  * - Body hashing handles `File`/`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`
  *   and typed arrays explicitly; everything else flows through key-sorted
  *   `JSON.stringify` via `hash()`.
+ * - `varyHeaders` (opt-in) mixes the named request headers into the key so responses
+ *   that differ per header (e.g. `Authorization` → per-user, `Accept-Language`) get
+ *   separate entries. Known-safe content-negotiation headers (`Accept`,
+ *   `Accept-Language`, `Content-Language`, `Content-Type`) embed their value raw for
+ *   readable keys; all other header VALUES are one-way digested, never embedded raw —
+ *   keys are persisted to IndexedDB and broadcast across tabs.
  */
-function hashRequest(req) {
+function hashRequest(req, varyHeaders) {
     const method = req.method ?? 'GET';
     const responseType = req.responseType ?? 'json';
     const base = `${method}:${req.url}:${responseType}`;
     const params = req.params ? `:${normalizeParams(req.params)}` : '';
     const body = req.body != null ? `:${hashBody(req.body)}` : '';
-    return base + params + body;
+    const vary = varyHeaders?.length
+        ? `:vary(${normalizeVaryHeaders(req.headers, varyHeaders)})`
+        : '';
+    return base + params + body + vary;
+}
+
+/**
+ * @internal
+ * Single-flight sharing: if a pending observable is already registered under `key`,
+ * return it; otherwise create one, share it (replaying the latest event to late
+ * subscribers), and deregister it on teardown/settle.
+ *
+ * Used by both the dedupe interceptor (keyed by full request hash, app-wide) and the
+ * cache interceptor (keyed by the CACHE key, guarding the miss/stale-revalidation path)
+ * — same mechanism, different keying/scope, so it lives here exactly once.
+ */
+function sharePending(pending, key, create) {
+    const existing = pending.get(key);
+    if (existing)
+        return existing;
+    const shared = create().pipe(finalize(() => pending.delete(key)), shareReplay({ bufferSize: 1, refCount: true }));
+    pending.set(key, shared);
+    return shared;
 }
 
 const CACHE_CONTEXT = new HttpContextToken(() => ({
@@ -766,6 +1036,7 @@ function parseCacheControlHeader(req) {
         noCache: false,
         mustRevalidate: false,
         immutable: false,
+        isPrivate: false,
         maxAge: null,
         staleWhileRevalidate: null,
     };
@@ -789,6 +1060,9 @@ function parseCacheControlHeader(req) {
             case 'immutable':
                 directives.immutable = true;
                 break;
+            case 'private':
+                directives.isPrivate = true;
+                break;
             case 'max-age': {
                 if (!value)
                     break;
@@ -797,7 +1071,7 @@ function parseCacheControlHeader(req) {
                     directives.maxAge = parsedValue;
                 break;
             }
-            case 's-max-age': {
+            case 's-maxage': {
                 if (!value)
                     break;
                 const parsedValue = parseInt(value, 10);
@@ -815,7 +1089,7 @@ function parseCacheControlHeader(req) {
             }
         }
     }
-    // s-max-age takes precedence over max-age
+    // s-maxage takes precedence over max-age
     if (sMaxAge !== null)
         directives.maxAge = sMaxAge;
     // if no store nothing else is relevant
@@ -825,6 +1099,7 @@ function parseCacheControlHeader(req) {
             noCache: false,
             mustRevalidate: false,
             immutable: false,
+            isPrivate: directives.isPrivate,
             maxAge: null,
             staleWhileRevalidate: null,
         };
@@ -844,14 +1119,32 @@ function resolveTimings(cacheControl, optStaleTime, optTTL) {
             staleTime: Infinity,
             ttl: Infinity,
         };
-    if (cacheControl.maxAge !== null)
-        ttl = cacheControl.maxAge * 1000;
-    if (cacheControl.staleWhileRevalidate !== null)
-        staleTime = cacheControl.staleWhileRevalidate * 1000;
-    // if no-cache is set, we must always revalidate
+    if (cacheControl.maxAge !== null) {
+        staleTime = cacheControl.maxAge * 1000;
+        if (cacheControl.staleWhileRevalidate !== null) {
+            ttl = staleTime + cacheControl.staleWhileRevalidate * 1000;
+        }
+        else if (ttl !== undefined) {
+            // a configured total lifetime must never undercut the server's fresh window
+            ttl = Math.max(ttl, staleTime);
+        }
+        // no swr + no configured ttl → leave undefined so the cache's default ttl applies
+        // (the entry stays resident past max-age for ETag revalidation)
+    }
+    else if (cacheControl.staleWhileRevalidate !== null) {
+        // swr without max-age: stale immediately, revalidatable for the window
+        staleTime = 0;
+        ttl = cacheControl.staleWhileRevalidate * 1000;
+    }
+    // if no-cache is set, we must always revalidate (the entry stays usable for conditional requests until ttl)
     if (cacheControl.noCache || cacheControl.mustRevalidate)
         staleTime = 0;
-    if (ttl !== undefined && staleTime !== undefined && ttl < staleTime) {
+    // option-only path (no server freshness): a misconfigured ttl < staleTime clamps the
+    // fresh window down, mirroring the cache's own internal clamp
+    if (cacheControl.maxAge === null &&
+        ttl !== undefined &&
+        staleTime !== undefined &&
+        ttl < staleTime) {
         staleTime = ttl;
     }
     return { staleTime, ttl };
@@ -865,6 +1158,10 @@ function resolveTimings(cacheControl, optStaleTime, optTTL) {
  * is made to the server, and the response is cached according to the configured TTL and staleness.
  * The interceptor also respects `Cache-Control` headers from the server.
  *
+ * Cache-enabled requests are single-flighted per cache key: N concurrent consumers of
+ * the same missing/stale entry share ONE network request. Non-cached requests are not
+ * touched — pair with `createDedupeRequestsInterceptor` to coalesce those as well.
+ *
  * @param allowedMethods - An array of HTTP methods for which caching should be enabled.
  *                        Defaults to `['GET', 'HEAD', 'OPTIONS']`.
  *
@@ -885,7 +1182,10 @@ function resolveTimings(cacheControl, optStaleTime, optTTL) {
  */
 function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
     const CACHE_METHODS = new Set(allowedMethods);
+    const inFlight = new Map();
     return (req, next) => {
+        if (inject(PLATFORM_ID) === 'server')
+            return next(req);
         const cache = injectQueryCache();
         if (!CACHE_METHODS.has(req.method))
             return next(req);
@@ -898,60 +1198,78 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
         if (entry && !entry.isStale)
             return of(entry.value);
         // resource itself handles case of showing stale data...the request must process as this will "refresh said data"
-        const eTag = entry?.value.headers.get('ETag');
-        const lastModified = entry?.value.headers.get('Last-Modified');
-        if (eTag) {
-            req = req.clone({ setHeaders: { 'If-None-Match': eTag } });
-        }
-        if (lastModified) {
-            req = req.clone({ setHeaders: { 'If-Modified-Since': lastModified } });
-        }
-        if (opt.bustBrowserCache) {
-            req = req.clone({
-                setParams: { _cb: Date.now().toString() },
-            });
-        }
-        return next(req).pipe(tap((event) => {
-            if (!(event instanceof HttpResponse))
-                return;
-            if (event.ok) {
-                const cacheControl = parseCacheControlHeader(event);
-                if (cacheControl.noStore && !opt.ignoreCacheControl)
-                    return;
-                const { staleTime, ttl } = opt.ignoreCacheControl
-                    ? opt
-                    : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
-                if (opt.ttl === 0)
-                    return; // no point
-                const parsedResponse = opt.parse
-                    ? new HttpResponse({
-                        body: opt.parse(event.body),
-                        headers: event.headers,
-                        status: event.status,
-                        statusText: event.statusText,
-                        url: event.url ?? undefined,
-                    })
-                    : event;
-                cache.store(key, parsedResponse, staleTime, ttl, opt.persist);
-                return;
+        return sharePending(inFlight, key, () => {
+            const eTag = entry?.value.headers.get('ETag');
+            const lastModified = entry?.value.headers.get('Last-Modified');
+            if (eTag) {
+                req = req.clone({ setHeaders: { 'If-None-Match': eTag } });
+            }
+            if (lastModified) {
+                req = req.clone({ setHeaders: { 'If-Modified-Since': lastModified } });
             }
-            // 304 → server confirmed our cached entry is still valid. Re-stamp the
-            // existing entry so subsequent reads within the new freshness window
-            // don't trigger another revalidation round-trip.
-            if (event.status === 304 && entry) {
-                const cacheControl = parseCacheControlHeader(event);
-                const { staleTime, ttl } = opt.ignoreCacheControl
-                    ? opt
-                    : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
-                cache.store(key, entry.value, staleTime, ttl, opt.persist);
+            if (opt.bustBrowserCache) {
+                req = req.clone({
+                    setParams: { _cb: Date.now().toString() },
+                });
             }
-        }), map((event) => {
-            // handle 304 responses due to eTag/last-modified
-            if (event instanceof HttpResponse && event.status === 304 && entry) {
-                return entry.value;
+            // non-JSON bodies (blob/arraybuffer) cannot survive the JSON persistence layer
+            const persistable = req.responseType === 'json';
+            if (opt.persist && !persistable && isDevMode()) {
+                console.warn(`[@mmstack/resource]: persist was requested for a '${req.responseType}' response — such bodies don't survive JSON serialization, persisting skipped.`);
             }
-            return event;
-        }));
+            return next(req).pipe(tap((event) => {
+                if (!(event instanceof HttpResponse))
+                    return;
+                if (event.ok) {
+                    const cacheControl = parseCacheControlHeader(event);
+                    if (cacheControl.noStore && !opt.ignoreCacheControl)
+                        return;
+                    const { staleTime, ttl } = opt.ignoreCacheControl
+                        ? opt
+                        : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
+                    if (ttl === 0)
+                        return; // no point
+                    // `Cache-Control: private` → fine to keep in memory, never on disk
+                    const persist = (opt.persist ?? false) &&
+                        persistable &&
+                        (opt.ignoreCacheControl || !cacheControl.isPrivate);
+                    const parsedResponse = opt.parse
+                        ? // statusText omitted — deprecated in Angular (HttpResponse defaults it)
+                            new HttpResponse({
+                                body: opt.parse(event.body),
+                                headers: event.headers,
+                                status: event.status,
+                                url: event.url ?? undefined,
+                            })
+                        : event;
+                    cache.store(key, parsedResponse, staleTime, ttl, persist);
+                    return;
+                }
+                // 304 → server confirmed our cached entry is still valid. Re-stamp the
+                // existing entry so subsequent reads within the new freshness window
+                // don't trigger another revalidation round-trip.
+                if (event.status === 304 && entry) {
+                    // ...unless the key was invalidated while this conditional request was in
+                    // flight (e.g. by a mutation) — re-storing would resurrect deleted data
+                    if (!cache.getUntracked(key))
+                        return;
+                    const cacheControl = parseCacheControlHeader(event);
+                    const { staleTime, ttl } = opt.ignoreCacheControl
+                        ? opt
+                        : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
+                    const persist = (opt.persist ?? false) &&
+                        persistable &&
+                        (opt.ignoreCacheControl || !cacheControl.isPrivate);
+                    cache.store(key, entry.value, staleTime, ttl, persist);
+                }
+            }), map((event) => {
+                // handle 304 responses due to eTag/last-modified
+                if (event instanceof HttpResponse && event.status === 304 && entry) {
+                    return entry.value;
+                }
+                return event;
+            }));
+        });
     };
 }
 
@@ -1173,6 +1491,12 @@ function noDedupe(ctx = new HttpContext()) {
  * only the first request will be sent to the server. Subsequent requests will
  * receive the response from the first request.
  *
+ * Relationship to `createCacheInterceptor`: the cache interceptor has built-in
+ * single-flight for CACHE-ENABLED requests (keyed by the cache key). This interceptor
+ * covers everything the cache doesn't see — non-cached resources, plain HttpClient
+ * calls, DELETEs — keyed by the request hash. Installing both is the recommended
+ * setup; where they overlap, this one degrades to a no-op passthrough.
+ *
  * @param allowed - An array of HTTP methods for which deduplication should be enabled.
  *                  Defaults to `['GET', 'DELETE', 'HEAD', 'OPTIONS']`.
  * @param keyFn - Optional function to compute the dedupe key from a request.
@@ -1207,13 +1531,7 @@ function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OP
     return (req, next) => {
         if (!DEDUPE_METHODS.has(req.method) || req.context.get(NO_DEDUPE))
             return next(req);
-        const key = keyFn(req);
-        const found = inFlight.get(key);
-        if (found)
-            return found;
-        const request = next(req).pipe(finalize(() => inFlight.delete(key)), shareReplay({ bufferSize: 1, refCount: true }));
-        inFlight.set(key, request);
-        return request;
+        return sharePending(inFlight, keyFn(req), () => next(req));
     };
 }
 
@@ -1386,6 +1704,57 @@ function hasSlowConnection() {
     return false;
 }
 
+/**
+ * Deep merges multiple circuit breaker options.
+ * The latter options override the former.
+ */
+function mergeCircuitBreakerOptions(global, query, local) {
+    if (!global && !query && !local)
+        return undefined;
+    return {
+        ...(global === true ? {} : global),
+        ...(query === true ? {} : query),
+        ...(local === true ? {} : local),
+    };
+}
+/**
+ * Deep merges multiple retry options.
+ * The latter options override the former.
+ */
+function mergeRetryOptions(global, query, local) {
+    if (global === undefined && query === undefined && local === undefined)
+        return undefined;
+    return {
+        ...(typeof global === 'number' ? { max: global } : global),
+        ...(typeof query === 'number' ? { max: query } : query),
+        ...(typeof local === 'number' ? { max: local } : local),
+    };
+}
+/**
+ * Deep merges multiple cache options.
+ * The latter options override the former.
+ */
+function mergeCacheOptions(query, local) {
+    if (query === undefined && local === undefined)
+        return undefined;
+    return {
+        ...(query === true ? {} : query),
+        ...(local === true ? {} : local),
+    };
+}
+/**
+ * Deep merges multiple refresh options.
+ * The latter options override the former.
+ */
+function mergeRefreshOptions(query, local) {
+    if (query === undefined && local === undefined)
+        return undefined;
+    return {
+        ...(typeof query === 'number' ? { interval: query } : query),
+        ...(typeof local === 'number' ? { interval: local } : local),
+    };
+}
+
 function persistResourceValues(resource, shouldPersist = false, equal) {
     if (!shouldPersist)
         return resource;
@@ -1397,24 +1766,61 @@ function persistResourceValues(resource, shouldPersist = false, equal) {
     };
 }
 
-// refresh resource every n miliseconds or don't refresh if undefined provided. 0 also excluded, due to it not being a valid usecase.
-function refresh(resource, destroyRef, refresh, inactive) {
-    if (!refresh)
+// refresh resource every n milliseconds and/or on visibility/reconnect transitions.
+function refresh(resource, destroyRef, opt, inactive, triggers) {
+    const normalized = typeof opt === 'number' ? { interval: opt } : (opt ?? {});
+    const { interval: ms, onFocus = false, onReconnect = false, } = normalized;
+    const hasInterval = !!ms; // 0 excluded — not a valid polling cadence
+    const hasTriggerEffects = !!triggers && (onFocus || onReconnect);
+    if (!hasInterval && !hasTriggerEffects)
         return resource; // no refresh requested
     const tick = () => {
         if (inactive?.())
-            return; // disabled / paused → skip the poll
+            return; // disabled / paused → skip
         resource.reload();
     };
+    const effectRefs = [];
+    if (triggers && onFocus) {
+        const vis = triggers.visibility;
+        let prev = untracked(vis);
+        effectRefs.push(effect(() => {
+            const next = vis();
+            const was = prev;
+            prev = next;
+            // only the hidden → visible TRANSITION refreshes — not the initial run
+            if (was !== 'visible' && next === 'visible')
+                untracked(tick);
+        }, { injector: triggers.injector }));
+    }
+    if (triggers && onReconnect) {
+        const online = triggers.online;
+        let prev = untracked(online);
+        effectRefs.push(effect(() => {
+            const next = online();
+            const was = prev;
+            prev = next;
+            if (!was && next)
+                untracked(tick);
+        }, { injector: triggers.injector }));
+    }
+    if (!hasInterval) {
+        return {
+            ...resource,
+            destroy: () => {
+                effectRefs.forEach((ref) => ref.destroy());
+                resource.destroy();
+            },
+        };
+    }
     // we can use RxJs here as reloading the resource will always be a side effect & as such does not impact the reactive graph in any way.
-    let sub = interval(refresh)
+    let sub = interval(ms)
         .pipe(takeUntilDestroyed(destroyRef))
         .subscribe(tick);
     const reload = () => {
         sub.unsubscribe(); // do not conflict with manual reload
         const hasReloaded = resource.reload();
         // resubscribe after manual reload
-        sub = interval(refresh)
+        sub = interval(ms)
             .pipe(takeUntilDestroyed(destroyRef))
             .subscribe(tick);
         return hasReloaded;
@@ -1424,6 +1830,7 @@ function refresh(resource, destroyRef, refresh, inactive) {
         reload,
         destroy: () => {
             sub.unsubscribe();
+            effectRefs.forEach((ref) => ref.destroy());
             resource.destroy();
         },
     };
@@ -1470,6 +1877,7 @@ function retryOnError(res, opt, onError) {
 
 class ResourceSensors {
     networkStatus = sensor('networkStatus');
+    pageVisibility = sensor('pageVisibility');
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: ResourceSensors, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: ResourceSensors, providedIn: 'root' });
 }
@@ -1482,6 +1890,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
 function injectNetworkStatus() {
     return inject(ResourceSensors).networkStatus;
 }
+function injectPageVisibility() {
+    return inject(ResourceSensors).pageVisibility;
+}
 
 function toResourceObject(res) {
     return {
@@ -1525,10 +1936,16 @@ function injectQueryResourceOptions(injector) {
 const PAUSED = Symbol('@mmstack/resource:paused');
 function queryResource(request, options0) {
     // Two-layer option injection: per-call > provideQueryResourceOptions > provideResourceOptions.
+    const globalOpts = injectResourceOptions(options0?.injector);
+    const queryOpts = injectQueryResourceOptions(options0?.injector);
     const options = {
-        ...injectResourceOptions(options0?.injector),
-        ...injectQueryResourceOptions(options0?.injector),
+        ...globalOpts,
+        ...queryOpts,
         ...options0,
+        cache: mergeCacheOptions(queryOpts.cache, options0?.cache),
+        circuitBreaker: mergeCircuitBreakerOptions(globalOpts.circuitBreaker, queryOpts.circuitBreaker, options0?.circuitBreaker),
+        retry: mergeRetryOptions(globalOpts.retry, queryOpts.retry, options0?.retry),
+        refresh: mergeRefreshOptions(queryOpts.refresh, options0?.refresh),
     };
     const cache = injectQueryCache(options?.injector);
     const destroyRef = options?.injector
@@ -1541,9 +1958,19 @@ function queryResource(request, options0) {
     const eq = options?.triggerOnSameRequest
         ? undefined
         : (options?.equalRequest ?? createEqualRequest());
+    // Opt-in auto-pausing: `true` reads the ambient Activity boundary (no-op outside
+    // one), a predicate is used directly. Composes with the manual `ctx.paused` path.
+    const pauseOpt = options?.pause ?? false;
+    const externallyPaused = pauseOpt === false
+        ? () => false
+        : typeof pauseOpt === 'function'
+            ? pauseOpt
+            : options?.injector
+                ? runInInjectionContext(options.injector, injectPaused)
+                : injectPaused();
     const requestCtx = { paused: PAUSED };
     const rawResult = computed(() => request(requestCtx), ...(ngDevMode ? [{ debugName: "rawResult" }] : []));
-    const paused = computed(() => rawResult() === PAUSED, ...(ngDevMode ? [{ debugName: "paused" }] : []));
+    const paused = computed(() => rawResult() === PAUSED || externallyPaused(), ...(ngDevMode ? [{ debugName: "paused" }] : []));
     const rawRequest = computed(() => {
         const r = rawResult();
         return r === PAUSED ? undefined : (r ?? undefined);
@@ -1553,9 +1980,12 @@ function queryResource(request, options0) {
             return 'offline';
         if (cb.isOpen())
             return 'circuit-open';
-        // PAUSED makes rawRequest undefined, so it reports 'no-request' here (and skips polling),
-        // while stableRequest below HOLDS the last request so the value is kept (no refetch on resume).
-        if (!rawRequest())
+        // Both pause sources report 'no-request' here — ctx.paused makes rawRequest
+        // undefined, while the external `pause` option still yields a real request, so it
+        // must be checked explicitly. Either way this also stops polling/refresh triggers
+        // (their inactive() guard reads disabledReason), while stableRequest below HOLDS
+        // the last request so the value is kept (no refetch on resume).
+        if (paused() || !rawRequest())
             return 'no-request';
         return null;
     }, ...(ngDevMode ? [{ debugName: "disabledReason" }] : []));
@@ -1609,8 +2039,10 @@ function queryResource(request, options0) {
                 return a === b;
             },
         }]));
+    const varyHeaders = typeof options?.cache === 'object' ? options.cache.varyHeaders : undefined;
     const hashFn = typeof options?.cache === 'object'
-        ? (options.cache.hash ?? hashRequest)
+        ? (options.cache.hash ??
+            ((r) => hashRequest(r, varyHeaders)))
         : hashRequest;
     const staleTime = typeof options?.cache === 'object' ? options.cache.staleTime : 0;
     const ttl = typeof options?.cache === 'object' ? options.cache.ttl : undefined;
@@ -1689,22 +2121,30 @@ function queryResource(request, options0) {
                 };
             },
         }]));
-    // A disabled (offline / circuit-open / no-request) or PAUSED resource must not poll.
-    resource = refresh(resource, destroyRef, options?.refresh, () => disabledReason() !== null);
+    // A disabled (offline / circuit-open / no-request) or PAUSED resource must not poll
+    // or react to focus/reconnect.
+    resource = refresh(resource, destroyRef, options?.refresh, () => disabledReason() !== null, {
+        injector: options?.injector ?? inject(Injector),
+        visibility: injectPageVisibility(),
+        online: networkAvailable,
+    });
     resource = retryOnError(resource, options?.retry, options?.onError);
     resource = persistResourceValues(resource, options?.keepPrevious, options?.equal);
     const set = (value) => {
         resource.value.set(value);
         const k = untracked(cacheKey);
         if (options?.cache && k)
-            cache.store(k, new HttpResponse({
+            cache.store(k, 
+            // statusText omitted — deprecated in Angular (HttpResponse defaults it)
+            new HttpResponse({
                 body: value,
                 status: 200,
-                statusText: 'OK',
             }), staleTime, ttl, persist);
     };
     const update = (updater) => {
-        set(updater(untracked(resource.value)));
+        // baseline on the COMPOSED value (cache-preferring): the cache entry can be newer
+        // than resource.value (cross-tab sync, another instance's set)
+        set(updater(untracked(value)));
     };
     const value = options?.cache
         ? toWritable(computed(() => cacheEntry()?.value ?? resource.value()), set, update)
@@ -1792,6 +2232,101 @@ function queryResource(request, options0) {
     return ref;
 }
 
+/**
+ * Creates a paginated HTTP resource over {@link queryResource}: one page request at a
+ * time, accumulated into a `pages` signal — cursor- and offset-based pagination both
+ * fit through `getNextPageParam`. Each page request inherits the full queryResource
+ * feature set (caching per page, retries, circuit breaker, refresh triggers).
+ *
+ * @example
+ * ```ts
+ * const posts = infiniteQueryResource<PostPage, PostPage, number>(
+ *   ({ pageParam }) => ({ url: '/api/posts', params: { page: pageParam } }),
+ *   {
+ *     initialPageParam: 0,
+ *     getNextPageParam: (last, all) => (last.items.length < 20 ? null : all.length),
+ *     cache: true,
+ *   },
+ * );
+ *
+ * // template:
+ * // @for (page of posts.pages(); track $index) { ... }
+ * // <button (click)="posts.fetchNextPage()" [disabled]="!posts.hasNextPage()">More</button>
+ * const flat = computed(() => posts.pages().flatMap((p) => p.items));
+ * ```
+ */
+function infiniteQueryResource(request, options) {
+    const { initialPageParam, getNextPageParam, ...rest } = options;
+    const injector = options.injector ?? inject(Injector);
+    const pageParam = signal(initialPageParam, ...(ngDevMode ? [{ debugName: "pageParam" }] : []));
+    // pages keyed by the param that produced them, so a reload of an already-loaded
+    // page REPLACES its slot instead of appending a duplicate
+    const loaded = signal([], ...(ngDevMode ? [{ debugName: "loaded" }] : []));
+    const resource = queryResource(
+    // forward queryResource's own context so the fn can return ctx.paused —
+    // pausing holds the loaded pages and stops page fetches until unpaused
+    (qctx) => request({ ...qctx, pageParam: pageParam() }), { ...rest, injector });
+    const appendRef = effect(() => {
+        if (resource.status() !== 'resolved')
+            return;
+        const page = resource.value();
+        if (page === undefined)
+            return;
+        untracked(() => {
+            const param = pageParam();
+            loaded.update((list) => {
+                const idx = list.findIndex((e) => Object.is(e.param, param));
+                if (idx >= 0) {
+                    const copy = [...list];
+                    copy[idx] = { param, page };
+                    return copy;
+                }
+                return [...list, { param, page }];
+            });
+        });
+    }, ...(ngDevMode ? [{ debugName: "appendRef", injector }] : [{ injector }]));
+    const pages = computed(() => loaded().map((e) => e.page), ...(ngDevMode ? [{ debugName: "pages" }] : []));
+    const nextPageParam = computed(() => {
+        const all = pages();
+        if (all.length === 0)
+            return null;
+        return getNextPageParam(all[all.length - 1], all) ?? null;
+    }, ...(ngDevMode ? [{ debugName: "nextPageParam" }] : []));
+    const hasNextPage = computed(() => nextPageParam() !== null, ...(ngDevMode ? [{ debugName: "hasNextPage" }] : []));
+    const fetchNextPage = () => {
+        if (untracked(resource.isLoading))
+            return; // one page at a time
+        const next = untracked(nextPageParam);
+        if (next === null)
+            return;
+        pageParam.set(next);
+    };
+    const reset = () => {
+        loaded.set([]);
+        if (Object.is(untracked(pageParam), initialPageParam)) {
+            resource.reload(); // param unchanged — force the refetch
+        }
+        else {
+            pageParam.set(initialPageParam);
+        }
+    };
+    return {
+        pages,
+        hasNextPage,
+        isFetchingNextPage: computed(() => resource.isLoading() && loaded().length > 0),
+        isLoading: resource.isLoading,
+        status: resource.status,
+        error: resource.error,
+        fetchNextPage,
+        reload: () => resource.reload(),
+        reset,
+        destroy: () => {
+            appendRef.destroy();
+            resource.destroy();
+        },
+    };
+}
+
 function manualQueryResource(request, options) {
     const trigger = signal({ epoch: 0 }, ...(ngDevMode ? [{ debugName: "trigger", equal: (a, b) => a.epoch === b.epoch }] : [{
             equal: (a, b) => a.epoch === b.epoch,
@@ -1808,6 +2343,12 @@ function manualQueryResource(request, options) {
             equal: () => false,
         }]));
     const resource = queryResource(req, options);
+    // Shared across trigger() calls: a per-call watcher could observe the PREVIOUS
+    // request's `resolved` status before this trigger's load flips the resource to
+    // loading (effect ordering within a flush is unspecified) and resolve with stale
+    // data; concurrent triggers would also cross-resolve each other's promises.
+    let pending = [];
+    let watcher = null;
     return {
         ...resource,
         trigger: (override, injectorOverride) => {
@@ -1816,15 +2357,41 @@ function manualQueryResource(request, options) {
                 override,
             }));
             return new Promise((res, rej) => {
-                const watcher = nestedEffect(() => {
+                if (untracked(req) === undefined) {
+                    // the request fn produced nothing — no load will ever start, so a watcher
+                    // would hang this promise forever
+                    rej(new Error('[@mmstack/resource]: trigger() produced no request (the request fn returned undefined)'));
+                    return;
+                }
+                pending.push({ res, rej });
+                // an active watcher (concurrent trigger) settles ALL pending promises with
+                // the final result of the latest request — TanStack-style latest-wins
+                if (watcher)
+                    return;
+                // only accept a settle AFTER the load for this trigger has been observed —
+                // the pre-trigger status may still be a stale `resolved`/`error`
+                let sawLoading = false;
+                watcher = nestedEffect(() => {
                     const status = resource.status();
-                    if (status === 'resolved') {
-                        watcher.destroy();
-                        res(untracked(resource.value));
+                    if (status === 'loading' || status === 'reloading') {
+                        sawLoading = true;
+                        return;
                     }
-                    else if (status === 'error') {
-                        watcher.destroy();
-                        rej(untracked(resource.error));
+                    if (!sawLoading)
+                        return;
+                    if (status === 'resolved' || status === 'error') {
+                        const settled = pending;
+                        pending = [];
+                        watcher?.destroy();
+                        watcher = null;
+                        if (status === 'resolved') {
+                            const value = untracked(resource.value);
+                            settled.forEach((p) => p.res(value));
+                        }
+                        else {
+                            const err = untracked(resource.error);
+                            settled.forEach((p) => p.rej(err));
+                        }
                     }
                 }, { injector: injectorOverride ?? injector });
             });
@@ -1897,14 +2464,19 @@ function injectMutationResourceOptions(injector) {
  */
 function mutationResource(request, options0 = {}) {
     // Two-layer option injection: per-call > provideMutationResourceOptions > provideResourceOptions.
+    const globalOpts = injectResourceOptions(options0.injector);
+    const mutOpts = injectMutationResourceOptions(options0.injector);
     const options = {
-        ...injectResourceOptions(options0.injector),
-        ...injectMutationResourceOptions(options0.injector),
+        ...globalOpts,
+        ...mutOpts,
         ...options0,
+        circuitBreaker: mergeCircuitBreakerOptions(globalOpts.circuitBreaker, mutOpts.circuitBreaker, options0?.circuitBreaker),
+        retry: mergeRetryOptions(globalOpts.retry, mutOpts.retry, options0?.retry),
     };
     // `register` is pulled out (and forced off on the inner query below) so the mutation ref is
     // the only thing registered into the transition scope, not its internal query resource.
-    const { onMutate, onError, onSuccess, onSettled, equal, register, equalRequest, ...rest } = options;
+    const { onMutate, onError, onSuccess, onSettled, equal, register, equalRequest, invalidates, ...rest } = options;
+    const cache = invalidates ? injectQueryCache(options.injector) : undefined;
     const requestEqual = equalRequest ?? createEqualRequest(equal);
     // A mutation is an imperative command, so `triggerOnSameRequest` means "fire on EVERY mutate(),
     // even with an identical body". By default we dedup an identical value/request while one is in
@@ -2042,8 +2614,19 @@ function mutationResource(request, options0 = {}) {
         .subscribe((result) => {
         if (result.status === 'error')
             onError?.(result.error, ctx);
-        else
+        else {
             onSuccess?.(result.value, ctx);
+            if (cache && invalidates) {
+                const mutation = untracked(lastValue);
+                const prefixes = typeof invalidates === 'function'
+                    ? invalidates(result.value, (mutation === NULL_VALUE ? undefined : mutation))
+                    : invalidates;
+                // auto-keys are `${method}:${url}:...` — a `GET:`-prefixed url prefix hits
+                // the url with any params/subpaths and every varyHeaders variant
+                for (const prefix of prefixes)
+                    cache.invalidatePrefix(`GET:${prefix}`);
+            }
+        }
         onSettled?.(ctx);
         ctx = undefined;
         next.set(NULL_VALUE);
@@ -2052,15 +2635,31 @@ function mutationResource(request, options0 = {}) {
     const ref = {
         ...resource,
         destroy: () => {
+            // queue first — a late queue flush must not poke an already-destroyed resource
+            queueRef.destroy();
             statusSub.unsubscribe();
             resource.destroy();
-            queueRef.destroy();
         },
         mutate: (value, ictx) => {
             if (shouldQueue) {
                 return queue.update((q) => [...q, [value, ictx]]);
             }
             else {
+                // latest-wins: a mutation already in flight gets superseded (its request is
+                // aborted by the request change), so its onSuccess/onError will never fire —
+                // settle its context NOW so optimistic state can be rolled back/cleaned up
+                if (untracked(next) !== NULL_VALUE) {
+                    if (isDevMode())
+                        console.warn('[@mmstack/resource]: mutate() called while another mutation was in flight — the previous mutation was superseded (latest-wins) and its onSettled was invoked. Use `queue: true` for sequential mutations.');
+                    try {
+                        onSettled?.(ctx);
+                    }
+                    catch (settleErr) {
+                        if (isDevMode())
+                            console.error('[@mmstack/resource]: error thrown in onSettled hook for a superseded mutation', settleErr);
+                    }
+                    ctx = undefined;
+                }
                 try {
                     ctx = onMutate?.(value, ictx);
                     next.set(value);
@@ -2088,5 +2687,5 @@ function mutationResource(request, options0 = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
+export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
 //# sourceMappingURL=mmstack-resource.mjs.map