@mmstack/resource 19.6.6 → 19.7.0

package/lib/mutation-resource.d.ts

@@ -97,14 +97,17 @@ export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult
      * Cache entries to invalidate after a SUCCESSFUL mutation — the declarative
      * alternative to calling `injectQueryCache().invalidatePrefix(...)` in `onSuccess`.
      *
-     * Each string is a URL prefix matched against auto-generated `GET` cache keys
-     * (`GET:${url}:...`): `'/api/posts'` invalidates `/api/posts` with any query params,
-     * plus subpaths like `/api/posts/123` — and all `varyHeaders` variants of each.
+     * Each string is a URL prefix matched against the request URL of every cached
+     * entry, regardless of HTTP method: `'/api/posts'` invalidates `/api/posts` with
+     * any query params, plus subpaths like `/api/posts/123` — and all `varyHeaders`
+     * variants of each — across GET/HEAD/OPTIONS/POST or whatever methods you cache.
      * Note that plain prefix matching also catches sibling paths sharing the prefix
      * (`/api/posts-archive`); pass `'/api/posts/'` or the exact URL to narrow.
      *
-     * Entries keyed by a custom `hash` function follow that function's shape, not the
-     * auto-key shape — invalidate those manually via `injectQueryCache().invalidateWhere`.
+     * Keys built by a custom `cache.hash` that merely *prepends* a namespace (e.g. a
+     * tenant/`sub` for per-user persistent caches) are still matched — the URL is
+     * recovered structurally. Keys that abandon the auto shape entirely need an
+     * a custom invalidateMatcher (or manual `injectQueryCache().invalidateWhere`).
      *
      * The function form receives the mutation result and the mutated value:
      * ```ts
@@ -112,6 +115,11 @@ export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult
      * ```
      */
     invalidates?: string[] | ((value: NoInfer<TResult>, mutation: NoInfer<TMutation>) => string[]);
+    /**
+     * override for how {@link MutationResourceOptions.invalidates} URL
+     * prefixes map onto cache keys — given a prefix, return a key predicate.
+     */
+    invalidateMatcher?: (urlPrefix: string) => (key: string) => boolean;
     equal?: ValueEqualityFn<TMutation>;
 };
 /**

package/lib/util/cache/cache.d.ts

@@ -1,6 +1,6 @@
 import { HttpResponse } from '@angular/common/http';
-import { Injector, type Provider, type Signal } from '@angular/core';
-import { CacheDB } from './persistence';
+import { type Injector, type Provider, type Signal } from '@angular/core';
+import { type CacheDB } from './persistence';
 /**
  * Options for configuring the Least Recently Used (LRU) cache cleanup strategy.
  * @internal
@@ -72,6 +72,8 @@ export declare class Cache<T> {
     private hydrated;
     /** Keys invalidated while hydration was still in flight — must not be resurrected by it. */
     private readonly hydrationTombstones;
+    /** Dev-only: ensures the "foreign keys, no matcher" hint in invalidateUrlPrefix fires at most once. */
+    private warnedForeignKeys;
     private readonly hitCount;
     private readonly missCount;
     /**
@@ -181,6 +183,35 @@ export declare class Cache<T> {
      * cache.invalidatePrefix('GET https://api.example.com/posts');
      */
     invalidatePrefix(prefix: string): number;
+    /**
+     * 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: string, match?: (urlPrefix: string) => (key: string) => boolean): number;
     /**
      * Invalidates every cache entry whose key matches the predicate. Use for
      * arbitrary bulk invalidation that doesn't fit prefix matching (e.g.

package/lib/util/cache/persistence.d.ts

@@ -1,4 +1,4 @@
-import { CacheEntry } from './cache';
+import { type CacheEntry } from './cache';
 type StoredEntry<T> = Omit<CacheEntry<T>, 'timeout'>;
 export type CacheDB<T> = {
     getAll: () => Promise<StoredEntry<T>[]>;

package/lib/util/hash-request.d.ts

@@ -7,11 +7,34 @@ type HashableRequest = {
     body?: unknown;
     headers?: HttpResourceRequest['headers'] | HttpRequest<unknown>['headers'];
 };
+/**
+ * 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.
+ */
+export declare const KEY_DELIMITER = "\u001F";
+/**
+ * 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.
+ */
+export declare function extractUrlFromKey(key: string): string | null;
 /**
  * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
  * `HttpRequest` and `HttpResourceRequest`).
  *
- * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}][:${vary}]`
+ * 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "19.6.6",
+  "version": "19.7.0",
   "keywords": [
     "angular",
     "signals",