@mmstack/resource 22.1.6 → 22.2.0

package/package.json

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

package/types/mmstack-resource.d.ts

@@ -80,6 +80,8 @@ 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;
     /**
@@ -189,6 +191,35 @@ 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.
@@ -530,7 +561,9 @@ type HashableRequest = {
  * 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`
@@ -1144,14 +1177,17 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
      * 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
@@ -1159,6 +1195,11 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
      * ```
      */
     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>;
 };
 /**