@mmstack/resource 21.4.6 → 21.5.0

package/fesm2022/mmstack-resource.mjs

@@ -1,10 +1,322 @@
-import { HttpHeaders, HttpResponse, HttpParams, HttpContextToken, HttpContext, httpResource, HttpClient } from '@angular/common/http';
+import { HttpHeaders, HttpParams, HttpResponse, HttpContextToken, HttpContext, httpResource, HttpClient } from '@angular/common/http';
 import * as i0 from '@angular/core';
 import { isDevMode, signal, computed, untracked, InjectionToken, inject, PLATFORM_ID, DestroyRef, effect, Injector, Injectable, runInInjectionContext, linkedSignal } from '@angular/core';
 import { mutable, toWritable, keepPrevious, sensor, injectTransitionScope, 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';
 
+/**
+ * Returns `true` for any object-like value whose own enumerable keys should
+ * be sorted for stable hashing. Excludes arrays (positional), `Date`
+ * (handled by `toJSON`), `Map`/`Set` (handled explicitly), and binary types
+ * (`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`/typed arrays — these
+ * should be branched on before reaching `hash()`, typically by `hashRequest`).
+ *
+ * Plain objects, class instances, and `Object.create(null)` all qualify.
+ */
+function isHashableObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    if (value instanceof Date)
+        return false;
+    if (value instanceof Map)
+        return false;
+    if (value instanceof Set)
+        return false;
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return false;
+    if (typeof FormData !== 'undefined' && value instanceof FormData)
+        return false;
+    if (typeof URLSearchParams !== 'undefined' &&
+        value instanceof URLSearchParams)
+        return false;
+    if (value instanceof ArrayBuffer)
+        return false;
+    if (ArrayBuffer.isView(value))
+        return false;
+    return true;
+}
+function sortKeys(val) {
+    return Object.keys(val)
+        .toSorted()
+        .reduce((result, key) => {
+        result[key] = val[key];
+        return result;
+    }, {});
+}
+/**
+ * Internal helper to generate a stable JSON string from an array.
+ * - Object-like values (plain, class instances, null-proto) get their own
+ *   enumerable keys sorted alphabetically.
+ * - `Map` → marker object with sorted entries (sorted by `JSON.stringify(key)`).
+ * - `Set` → marker object with sorted values (sorted by `JSON.stringify(value)`).
+ * - Arrays preserve order. `Date` serializes via `toJSON`.
+ *
+ * @internal
+ */
+function hashKey(queryKey) {
+    return JSON.stringify(queryKey, (_, val) => {
+        if (val instanceof Map) {
+            // Schwartzian: compute each entry's sort key (recursive hash of the
+            // Map key) once, then sort by the cheap string compare.
+            const entries = [...val.entries()]
+                .map((e) => [hash(e[0]), e])
+                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                .map(([, e]) => e);
+            return { __map__: entries };
+        }
+        if (val instanceof Set) {
+            const values = [...val]
+                .map((v) => [hash(v), v])
+                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                .map(([, v]) => v);
+            return { __set__: values };
+        }
+        if (isHashableObject(val))
+            return sortKeys(val);
+        return val;
+    });
+}
+/**
+ * Generates a stable, unique string hash from one or more arguments.
+ * Useful for creating cache keys or identifiers where object key order shouldn't matter.
+ *
+ * How it works:
+ * - Object-like values (plain objects, class instances, `Object.create(null)`) have
+ *   their own enumerable keys sorted alphabetically before hashing. This ensures
+ *   `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash.
+ * - `Map` and `Set` are serialized via stable, sorted markers (`__map__` / `__set__`).
+ * - Arrays preserve positional order; `Date` uses its ISO string via `toJSON`.
+ *
+ * @param {...unknown} args Values to include in the hash.
+ * @returns A stable string hash representing the input arguments.
+ * @example
+ * hash('posts', 10);
+ * // => '["posts",10]'
+ *
+ * hash({ a: 1, b: 2 }) === hash({ b: 2, a: 1 }); // true
+ *
+ * hash(new Map([['a', 1]])) === hash(new Map([['a', 1]])); // true
+ *
+ * // Be mindful of values JSON.stringify cannot handle (functions, undefined, Symbols)
+ * // hash('a', undefined, function() {}) => '["a",null,null]'
+ */
+function hash(...args) {
+    return hashKey(args);
+}
+
+/**
+ * Top-level field separator for auto-generated cache keys. ASCII Unit Separator
+ * (`\x1f`) is deliberately content-rare: it never occurs in HTTP method tokens,
+ * URLs, or `encodeURIComponent`/digest output (params, vary headers, body hash),
+ * so the structural layout stays unambiguous even when a custom `cache.hash`
+ * *prepends* a namespace with ordinary chars (e.g. `tenant:${hashRequest(req)}`).
+ * Survives `JSON.stringify` (IndexedDB persistence) and `structuredClone`
+ * (cross-tab broadcast) intact.
+ */
+const KEY_DELIMITER = '\x1f';
+/**
+ * Recovers the URL portion of an auto-generated cache key — the segment between
+ * the 1st and 2nd {@link KEY_DELIMITER} (the key shape is
+ * `method␟url␟responseType[␟…]`). Returns `null` when the key has no delimiter
+ * (e.g. produced by a custom `hash` that doesn't follow this shape).
+ *
+ * A namespace prepended with non-delimiter chars collapses into segment 0
+ * (`tenant:GET`), so the URL remains segment 1 — method-agnostic and
+ * namespacing-tolerant by construction.
+ */
+function extractUrlFromKey(key) {
+    const start = key.indexOf(KEY_DELIMITER);
+    if (start === -1)
+        return null;
+    const end = key.indexOf(KEY_DELIMITER, start + 1);
+    return end === -1
+        ? key.slice(start + 1)
+        : key.slice(start + 1, end);
+}
+/**
+ * @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 });
+    return p
+        .keys()
+        .toSorted()
+        .map((key) => {
+        const encodedKey = encodeURIComponent(key);
+        return (p.getAll(key) ?? [])
+            .map((v) => `${encodedKey}=${encodeURIComponent(v)}`)
+            .join('&');
+    })
+        .join('&');
+}
+function hashBody(body) {
+    // File extends Blob — must check File first
+    if (typeof File !== 'undefined' && body instanceof File) {
+        return `File:${body.name}:${body.type}:${body.size}:${body.lastModified}`;
+    }
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        return `Blob:${body.type}:${body.size}`;
+    }
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const entries = [];
+        body.forEach((value, key) => {
+            entries.push([key, hashBody(value)]);
+        });
+        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) {
+        const sp = new URLSearchParams(body);
+        sp.sort();
+        return `URLSearchParams:${sp.toString()}`;
+    }
+    if (body instanceof ArrayBuffer) {
+        return `ArrayBuffer:${body.byteLength}`;
+    }
+    if (ArrayBuffer.isView(body)) {
+        return `${body.constructor.name}:${body.byteLength}`;
+    }
+    return hash(body);
+}
+/**
+ * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
+ * `HttpRequest` and `HttpResourceRequest`).
+ *
+ * Key composition: `${method}␟${url}␟${responseType}[␟${params}][␟${body}][␟${vary}]`,
+ * where `␟` is {@link KEY_DELIMITER} (ASCII Unit Separator) — a content-rare top-level
+ * separator. Sub-fields inside `params`/`vary` keep their own `&`/`=` delimiters.
+ * - `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, varyHeaders) {
+    const method = req.method ?? 'GET';
+    const responseType = req.responseType ?? 'json';
+    const base = `${method}${KEY_DELIMITER}${req.url}${KEY_DELIMITER}${responseType}`;
+    const params = req.params
+        ? `${KEY_DELIMITER}${normalizeParams(req.params)}`
+        : '';
+    const body = req.body != null ? `${KEY_DELIMITER}${hashBody(req.body)}` : '';
+    const vary = varyHeaders?.length
+        ? `${KEY_DELIMITER}vary(${normalizeVaryHeaders(req.headers, varyHeaders)})`
+        : '';
+    return base + params + body + vary;
+}
+
 function createNoopDB() {
     return {
         getAll: async () => [],
@@ -141,6 +453,8 @@ class Cache {
     hydrated = false;
     /** Keys invalidated while hydration was still in flight — must not be resurrected by it. */
     hydrationTombstones = new Set();
+    /** Dev-only: ensures the "foreign keys, no matcher" hint in invalidateUrlPrefix fires at most once. */
+    warnedForeignKeys = false;
     hitCount = signal(0, ...(ngDevMode ? [{ debugName: "hitCount" }] : /* istanbul ignore next */ []));
     missCount = signal(0, ...(ngDevMode ? [{ debugName: "missCount" }] : /* istanbul ignore next */ []));
     /**
@@ -433,6 +747,55 @@ class Cache {
     invalidatePrefix(prefix) {
         return this.invalidateWhere((key) => key.startsWith(prefix));
     }
+    /**
+     * Invalidates every cache entry whose *request URL* starts with `urlPrefix`,
+     * regardless of HTTP method. This is the engine behind `mutationResource`'s
+     * `invalidates` option: `'/api/posts'` clears `/api/posts` with any query
+     * params, subpaths like `/api/posts/123`, and all `varyHeaders` variants —
+     * across GET/HEAD/OPTIONS/POST or any other cached method. Returns the number
+     * of entries removed.
+     *
+     * Unlike {@link invalidatePrefix} (which matches the raw key from its start),
+     * this extracts the URL field from the auto-generated key shape, so it is not
+     * fooled by the leading method token nor by a namespace a custom `cache.hash`
+     * prepends (e.g. `tenant:…`). Plain prefix matching still catches siblings
+     * sharing the prefix (`/api/posts-archive`) — pass `'/api/posts/'` to narrow.
+     *
+     * Keys produced by a custom `hash` that don't follow the auto shape won't be
+     * matched by the default; pass `match` to describe how a URL prefix maps onto
+     * your key format. In dev mode, if a default-matcher call removes nothing and
+     * every cached key is foreign-shaped, this logs a one-time hint pointing at the
+     * `match` escape hatch (a likely sign of a custom `hash` with no matcher wired up).
+     *
+     * @param urlPrefix - URL prefix to match.
+     * @param match - Optional custom matcher: given the prefix, returns a key predicate.
+     *
+     * @example
+     * cache.invalidateUrlPrefix('/api/posts');
+     * // custom key scheme:
+     * cache.invalidateUrlPrefix('/api/posts', (p) => (k) => k.includes(`|url=${p}`));
+     */
+    invalidateUrlPrefix(urlPrefix, match) {
+        if (match)
+            return this.invalidateWhere(match(urlPrefix));
+        let sawAutoKey = false;
+        const removed = this.invalidateWhere((key) => {
+            const url = extractUrlFromKey(key);
+            if (url === null)
+                return false; // foreign-shaped key
+            sawAutoKey = true;
+            return url.startsWith(urlPrefix);
+        });
+        if (isDevMode() &&
+            !this.warnedForeignKeys &&
+            removed === 0 &&
+            !sawAutoKey &&
+            untracked(this.internal).size > 0) {
+            this.warnedForeignKeys = true;
+            console.warn(`[@mmstack/resource] invalidateUrlPrefix('${urlPrefix}') matched nothing, and no cached key follows the default key shape. If you use a custom 'cache.hash', pass an 'invalidateMatcher' (mutationResource) / 'match' (invalidateUrlPrefix) so invalidation can locate your keys.`);
+        }
+        return removed;
+    }
     /**
      * Invalidates every cache entry whose key matches the predicate. Use for
      * arbitrary bulk invalidation that doesn't fit prefix matching (e.g.
@@ -595,372 +958,93 @@ function provideQueryCache(opt) {
                                     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.
- *
- * @param injector - (Optional) The injector to use.  If not provided, the current
- *                   injection context is used.
- * @returns The `QueryCache` instance.
- *
- * @example
- * // In your component or service:
- *
- * import { injectQueryCache } from './your-cache';
- *
- * constructor() {
- *   const cache = injectQueryCache();
- *
- *   const myData = cache.get(() => 'my-data-key');
- *   if (myData() !== null) {
- *     // ... use cached data ...
- *   }
- * }
- */
-function injectQueryCache(injector) {
-    const cache = injector
-        ? injector.get(CLIENT_CACHE_TOKEN, null, {
-            optional: true,
-        })
-        : inject(CLIENT_CACHE_TOKEN, {
-            optional: true,
-        });
-    if (!cache) {
-        if (isDevMode())
-            throw new Error('Cache not provided, please add provideQueryCache() to providers array');
-        else
-            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
- * be sorted for stable hashing. Excludes arrays (positional), `Date`
- * (handled by `toJSON`), `Map`/`Set` (handled explicitly), and binary types
- * (`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`/typed arrays — these
- * should be branched on before reaching `hash()`, typically by `hashRequest`).
- *
- * Plain objects, class instances, and `Object.create(null)` all qualify.
- */
-function isHashableObject(value) {
-    if (value === null || typeof value !== 'object')
-        return false;
-    if (Array.isArray(value))
-        return false;
-    if (value instanceof Date)
-        return false;
-    if (value instanceof Map)
-        return false;
-    if (value instanceof Set)
-        return false;
-    if (typeof Blob !== 'undefined' && value instanceof Blob)
-        return false;
-    if (typeof FormData !== 'undefined' && value instanceof FormData)
-        return false;
-    if (typeof URLSearchParams !== 'undefined' &&
-        value instanceof URLSearchParams)
-        return false;
-    if (value instanceof ArrayBuffer)
-        return false;
-    if (ArrayBuffer.isView(value))
-        return false;
-    return true;
-}
-function sortKeys(val) {
-    return Object.keys(val)
-        .toSorted()
-        .reduce((result, key) => {
-        result[key] = val[key];
-        return result;
-    }, {});
-}
-/**
- * Internal helper to generate a stable JSON string from an array.
- * - Object-like values (plain, class instances, null-proto) get their own
- *   enumerable keys sorted alphabetically.
- * - `Map` → marker object with sorted entries (sorted by `JSON.stringify(key)`).
- * - `Set` → marker object with sorted values (sorted by `JSON.stringify(value)`).
- * - Arrays preserve order. `Date` serializes via `toJSON`.
- *
- * @internal
- */
-function hashKey(queryKey) {
-    return JSON.stringify(queryKey, (_, val) => {
-        if (val instanceof Map) {
-            // Schwartzian: compute each entry's sort key (recursive hash of the
-            // Map key) once, then sort by the cheap string compare.
-            const entries = [...val.entries()]
-                .map((e) => [hash(e[0]), e])
-                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
-                .map(([, e]) => e);
-            return { __map__: entries };
-        }
-        if (val instanceof Set) {
-            const values = [...val]
-                .map((v) => [hash(v), v])
-                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
-                .map(([, v]) => v);
-            return { __set__: values };
-        }
-        if (isHashableObject(val))
-            return sortKeys(val);
-        return val;
-    });
+                                    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;
 /**
- * Generates a stable, unique string hash from one or more arguments.
- * Useful for creating cache keys or identifiers where object key order shouldn't matter.
+ * Injects the `QueryCache` instance that is used within queryResource.
+ * Allows for direct modification of cached data, but is mostly meant for internal use.
  *
- * How it works:
- * - Object-like values (plain objects, class instances, `Object.create(null)`) have
- *   their own enumerable keys sorted alphabetically before hashing. This ensures
- *   `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash.
- * - `Map` and `Set` are serialized via stable, sorted markers (`__map__` / `__set__`).
- * - Arrays preserve positional order; `Date` uses its ISO string via `toJSON`.
+ * @param injector - (Optional) The injector to use.  If not provided, the current
+ *                   injection context is used.
+ * @returns The `QueryCache` instance.
  *
- * @param {...unknown} args Values to include in the hash.
- * @returns A stable string hash representing the input arguments.
  * @example
- * hash('posts', 10);
- * // => '["posts",10]'
+ * // In your component or service:
  *
- * hash({ a: 1, b: 2 }) === hash({ b: 2, a: 1 }); // true
+ * import { injectQueryCache } from './your-cache';
  *
- * hash(new Map([['a', 1]])) === hash(new Map([['a', 1]])); // true
+ * constructor() {
+ *   const cache = injectQueryCache();
  *
- * // Be mindful of values JSON.stringify cannot handle (functions, undefined, Symbols)
- * // hash('a', undefined, function() {}) => '["a",null,null]'
- */
-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 myData = cache.get(() => 'my-data-key');
+ *   if (myData() !== null) {
+ *     // ... use cached data ...
+ *   }
+ * }
  */
-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 });
-    return p
-        .keys()
-        .toSorted()
-        .map((key) => {
-        const encodedKey = encodeURIComponent(key);
-        return (p.getAll(key) ?? [])
-            .map((v) => `${encodedKey}=${encodeURIComponent(v)}`)
-            .join('&');
-    })
-        .join('&');
-}
-function hashBody(body) {
-    // File extends Blob — must check File first
-    if (typeof File !== 'undefined' && body instanceof File) {
-        return `File:${body.name}:${body.type}:${body.size}:${body.lastModified}`;
-    }
-    if (typeof Blob !== 'undefined' && body instanceof Blob) {
-        return `Blob:${body.type}:${body.size}`;
-    }
-    if (typeof FormData !== 'undefined' && body instanceof FormData) {
-        const entries = [];
-        body.forEach((value, key) => {
-            entries.push([key, hashBody(value)]);
+function injectQueryCache(injector) {
+    const cache = injector
+        ? injector.get(CLIENT_CACHE_TOKEN, null, {
+            optional: true,
+        })
+        : inject(CLIENT_CACHE_TOKEN, {
+            optional: true,
         });
-        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) {
-        const sp = new URLSearchParams(body);
-        sp.sort();
-        return `URLSearchParams:${sp.toString()}`;
-    }
-    if (body instanceof ArrayBuffer) {
-        return `ArrayBuffer:${body.byteLength}`;
-    }
-    if (ArrayBuffer.isView(body)) {
-        return `${body.constructor.name}:${body.byteLength}`;
+    if (!cache) {
+        if (isDevMode())
+            throw new Error('Cache not provided, please add provideQueryCache() to providers array');
+        else
+            return (NOOP_CACHE ??= new NoopCache());
     }
-    return hash(body);
+    return cache;
 }
 /**
- * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
- * `HttpRequest` and `HttpResourceRequest`).
+ * Injects the cache statistics, including the current size of the cache and the number of hits and misses.
  *
- * 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.
+ * @param injector - (Optional) The injector to use.  If not provided, the current
+ *                   injection context is used.
+ * @returns A signal containing the cache statistics.
  */
-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)}` : '';
-    const vary = varyHeaders?.length
-        ? `:vary(${normalizeVaryHeaders(req.headers, varyHeaders)})`
-        : '';
-    return base + params + body + vary;
+function injectCacheStats(injector) {
+    const cache = injectQueryCache(injector);
+    return cache.stats;
 }
 
 /**
@@ -2395,9 +2479,7 @@ function mutationResource(request, 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, invalidates, ...rest } = options;
+    const { onMutate, onError, onSuccess, onSettled, equal, register, equalRequest, invalidates, invalidateMatcher, ...rest } = options;
     const cache = invalidates ? injectQueryCache(options.injector) : undefined;
     const requestEqual = equalRequest ?? createEqualRequest(equal);
     const triggerOnSame = options.triggerOnSameRequest ?? false;
@@ -2555,7 +2637,7 @@ function mutationResource(request, options0 = {}) {
                     ? invalidates(result.value, (mutation === NULL_VALUE ? undefined : mutation))
                     : invalidates;
                 for (const prefix of prefixes)
-                    cache.invalidatePrefix(`GET:${prefix}`);
+                    cache.invalidateUrlPrefix(prefix, invalidateMatcher);
             }
             deferred?.resolve(result.value);
         }