@mmstack/resource 19.6.5 → 19.7.0

package/lib/mutation-resource.d.ts

@@ -2,15 +2,28 @@ import { type HttpResourceRequest } from '@angular/common/http';
 import { type Provider, type Signal, type ValueEqualityFn } from '@angular/core';
 import { type QueryResourceOptions, type QueryResourceRef } from './query-resource';
 /**
- * @internal
- * Helper type for inferring the request body type based on the HTTP method.
+ * Why a {@link MutationResourceRef.mutateAsync} promise was cancelled — a closed
+ * set so consumers can branch on the cause without parsing the message:
+ * - `'superseded'`: a newer mutation replaced it (latest-wins).
+ * - `'queue-cleared'`: dropped from the queue by `clearQueue()`.
+ * - `'queue-key-changed'`: dropped from the queue by a reactive `key` change.
+ * - `'destroyed'`: the resource was destroyed while it was pending/in flight.
+ * - `'no-request'`: `request()` returned `undefined`, so nothing was sent.
  */
-type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMethod extends 'DELETE' | 'delete' ? Omit<HttpResourceRequest, 'body' | 'method'> & {
-    method: TMethod;
-} : Omit<HttpResourceRequest, 'body' | 'method'> & {
-    body: TMutation;
-    method: TMethod;
-};
+export type MutationCancellationReason = 'superseded' | 'queue-cleared' | 'queue-key-changed' | 'destroyed' | 'no-request';
+/**
+ * Rejection reason for a {@link MutationResourceRef.mutateAsync} promise whose
+ * mutation never completed. The {@link MutationCancelledError.type} discriminant
+ * carries the cause ({@link MutationCancellationReason}); the message is a
+ * human-readable elaboration of it.
+ *
+ * Only `mutateAsync` promises reject with this; plain `mutate()` calls have no
+ * promise and so produce no (potentially unhandled) rejection.
+ */
+export declare class MutationCancelledError extends Error {
+    readonly type: MutationCancellationReason;
+    constructor(type: MutationCancellationReason, message: string);
+}
 /**
  * Object form of the `queue` option. Enabling the queue serializes mutations
  * into a FIFO that runs one-at-a-time.
@@ -84,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
@@ -99,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>;
 };
 /**
@@ -134,6 +155,18 @@ export type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Om
      * @param ctx An optional initial context value that will be passed to the `onMutate` callback.
      */
     mutate: (value: TMutation, ctx?: TICTX) => void;
+    /**
+     * Executes the mutation and returns a `Promise`
+     *
+     * If the mutation never completes — superseded by a newer `mutate`/`mutateAsync`
+     * (latest-wins), dropped from the queue (`clearQueue` / queue `key` change),
+     * abandoned on `destroy()`, or its `request()` returned `undefined` — the
+     * promise rejects with a {@link MutationCancelledError}.
+     *
+     * @param value The mutation value (usually the request body).
+     * @param ctx An optional initial context value that will be passed to the `onMutate` callback.
+     */
+    mutateAsync: (value: TMutation, ctx?: TICTX) => Promise<TResult>;
     /**
      * A signal that holds the current mutation request, or `null` if no mutation is in progress.
      * This can be useful for tracking the state of the mutation or for displaying loading indicators.
@@ -194,5 +227,9 @@ export type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Om
  * );
  * ```
  */
-export declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TMethod extends HttpResourceRequest['method'] = HttpResourceRequest['method']>(request: (params: TMutation) => Omit<NextRequest<TMethod, TMutation>, 'body'> | undefined | void, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
-export {};
+export declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX>(request: (params: TMutation) => (Omit<HttpResourceRequest, 'body' | 'method'> & {
+    method: 'DELETE' | 'delete';
+}) | undefined | void, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
+export declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX>(request: (params: TMutation) => (Omit<HttpResourceRequest, 'body'> & {
+    body: TMutation;
+}) | undefined | void, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;

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.5",
+  "version": "19.7.0",
   "keywords": [
     "angular",
     "signals",