@mmstack/resource 22.1.6 → 22.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "22.1.6",
+  "version": "22.2.1",
   "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.
@@ -242,6 +273,26 @@ type CacheOptions = {
      */
     version?: number;
 };
+/**
+ * Provides a deterministic, in-memory `QueryCache` for unit tests.
+ *
+ * Unlike {@link provideQueryCache} this never touches IndexedDB or BroadcastChannel
+ * and disables the cleanup sweep interval (`checkInterval: Infinity`), so it plays
+ * nicely with `vi.useFakeTimers()`. It's a real cache (not a stub), so you can
+ * assert cache hits via {@link injectQueryCache} / its `stats` signal.
+ *
+ * @example
+ * TestBed.configureTestingModule({
+ *   providers: [
+ *     provideMockQueryCache(),
+ *     provideHttpClient(withInterceptors([createCacheInterceptor()])),
+ *   ],
+ * });
+ */
+declare function provideMockQueryCache(opt?: {
+    ttl?: number;
+    staleTime?: number;
+}): Provider;
 /**
  * Provides the instance of the QueryCache for queryResource. This should probably be called
  * in your application's root configuration, but can also be overriden with component/module providers.
@@ -530,7 +581,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`
@@ -573,6 +626,29 @@ type RetryOptions = number | {
     backoff?: number;
 };
 
+/**
+ * Provides controllable {@link ResourceSensors} for unit tests, letting you drive a
+ * resource's offline / page-hidden behavior deterministically instead of relying on
+ * the real `navigator.onLine` / `document.visibilityState`.
+ *
+ * Pass your own writable signals to toggle state mid-test; omit them for a static
+ * online + visible environment.
+ *
+ * @example
+ * import { signal } from '@angular/core';
+ *
+ * const online = signal(true);
+ * TestBed.configureTestingModule({
+ *   providers: [provideMockResourceSensors({ networkStatus: online })],
+ * });
+ * // ...later in the test
+ * online.set(false); // the resource now sees the network as down
+ */
+declare function provideMockResourceSensors(opt?: {
+    networkStatus?: Signal<boolean>;
+    pageVisibility?: Signal<DocumentVisibilityState>;
+}): Provider;
+
 /**
  * Options for enabling and configuring caching for a resource.
  *
@@ -1144,14 +1220,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 +1238,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>;
 };
 /**
@@ -1273,5 +1357,5 @@ declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult,
     body: TMutation;
 }) | undefined | void, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
 
-export { Cache, MutationCancelledError, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
+export { Cache, MutationCancelledError, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMockQueryCache, provideMockResourceSensors, 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 };