@mmstack/resource 22.1.5 → 22.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "22.1.5",
+  "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`
@@ -1049,15 +1082,28 @@ declare function manualQueryResource<TResult, TRaw = TResult>(request: () => Htt
 declare function manualQueryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): ManualQueryResourceRef<TResult | undefined>;
 
 /**
- * @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;
-};
+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.
+ */
+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.
@@ -1131,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
@@ -1146,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>;
 };
 /**
@@ -1181,6 +1235,18 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
      * @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.
@@ -1241,7 +1307,12 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
  * );
  * ```
  */
-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>;
+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>;
+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>;
 
-export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
-export type { CacheEntry, CleanupType, CommonResourceOptions, DisabledReason, InfiniteQueryResourceOptions, InfiniteQueryResourceRef, InfiniteRequestContext, ManualQueryResourceRef, MutationQueueOptions, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RefreshOptions, RequestContext, ResourceCacheOptions, ResourceRequestFn, TransitionRegistration };
+export { Cache, MutationCancelledError, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
+export type { CacheEntry, CleanupType, CommonResourceOptions, DisabledReason, InfiniteQueryResourceOptions, InfiniteQueryResourceRef, InfiniteRequestContext, ManualQueryResourceRef, MutationCancellationReason, MutationQueueOptions, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RefreshOptions, RequestContext, ResourceCacheOptions, ResourceRequestFn, TransitionRegistration };