@mmstack/resource 22.1.6 → 22.2.1

package/README.md

@@ -26,6 +26,7 @@ It's designed to be opt-in feature by feature: starting with `queryResource()` a
 - [Pausing a resource](#pausing-a-resource)
 - [Default options (`provideResourceOptions`)](#default-options-provideresourceoptions)
 - [Composition (retry / refresh / keepPrevious)](#composition-retry--refresh--keepprevious)
+- [Testing](#testing)
 - [Recipes](#recipes)
 
 ## Install
@@ -36,7 +37,9 @@ npm install @mmstack/resource
 
 ## Quick start
 
-Two-step setup: provide the cache + interceptors in your app config, then create resources in your services or components.
+A plain `queryResource()` works with nothing but `provideHttpClient()` — an in-memory cache is wired up by default. To turn caching on you add the interceptors (below) and opt resources into it per request. `provideQueryCache()` is **optional**: call it only when you want persistence (IndexedDB), cross-tab sync, or to tune the global TTL/stale defaults — it overrides the in-memory default.
+
+Recommended app config — interceptors plus `provideQueryCache()` for a tuned, persistent cache:
 
 ```typescript
 import { provideHttpClient, withInterceptors } from '@angular/common/http';
@@ -311,7 +314,7 @@ After a successful mutation, related query caches usually need refreshing. Inste
 
 ```typescript
 mutationResource((p: Post) => ({ url: '/api/posts', method: 'POST', body: p }), {
-  invalidates: ['/api/posts'], // every cached GET under /api/posts (any params, subpaths, varyHeaders variants)
+  invalidates: ['/api/posts'], // every cached entry under /api/posts (any method, params, subpaths, varyHeaders variants)
 });
 
 // or derived from the result:
@@ -320,7 +323,7 @@ mutationResource(request, {
 });
 ```
 
-Strings are URL prefixes matched against auto-generated `GET` keys. Plain prefix matching also catches sibling paths sharing the prefix (`/api/posts-archive`) — pass `'/api/posts/'` or an exact URL to narrow. Entries keyed by a custom `hash` follow that function's shape instead; invalidate those via `injectQueryCache().invalidateWhere`.
+Strings are URL prefixes matched against the request URL of every cached entry, regardless of HTTP method (so a POST-bodied search cached under the same URL is cleared too). Plain prefix matching also catches sibling paths sharing the prefix (`/api/posts-archive`) — pass `'/api/posts/'` or an exact URL to narrow. Keys a custom `hash` merely *prepends* a namespace to (e.g. a tenant/`sub`) are still matched; keys that abandon the auto shape entirely need an `invalidateMatcher: (urlPrefix) => (key) => boolean` (set per-mutation or globally via `provideMutationResourceOptions`), or manual `injectQueryCache().invalidateWhere`.
 
 ### Re-firing with an identical body (`triggerOnSameRequest`)
 
@@ -433,7 +436,7 @@ const rows = keyArray(items, (item) => buildRowVm(item), {
 
 ### `provideQueryCache(options?)`
 
-Registers the shared `Cache` in the root injector.
+Overrides the shared `Cache` in the root injector. It's optional — without it `queryResource` falls back to an in-memory cache (no persistence, no cross-tab sync). Call `provideQueryCache()` to add IndexedDB persistence, cross-tab sync, or to tune the global TTL/stale defaults.
 
 ```typescript
 provideQueryCache({
@@ -476,14 +479,14 @@ With `syncTabs: true`, cache invalidations and updates broadcast via `BroadcastC
 
 ```typescript
 const cache = injectQueryCache<MyResponse>();
-cache.invalidate('GET:/api/posts:json'); // drop one entry by exact key
-cache.invalidatePrefix('GET:/api/posts'); // drop every key under a URL prefix
+cache.invalidateUrlPrefix('/api/posts'); // drop every entry under a URL prefix, any method
 cache.invalidateWhere((key) => key.includes('userId=42')); // arbitrary predicates
+cache.invalidatePrefix('raw-key-prefix'); // match the raw key string from its start
 cache.clear(); // drop EVERYTHING — memory, persisted rows, other tabs
 cache.store(key, value, staleTime, ttl); // imperative write
 ```
 
-Auto-generated keys have the shape `${method}:${url}:${responseType}[:params][:body][:vary]` — prefix matching against `GET:${url}` is the common move. Call `clear()` on logout so no prior user's responses survive. For observability there's a read-only `cache.stats()` signal (`{ size, hits, misses }`) — handy for a debug panel; it deliberately exposes no mutation surface.
+Auto-generated keys have the shape `${method}${SEP}${url}${SEP}${responseType}[${SEP}params][${SEP}body][${SEP}vary]`, where `SEP` is a content-rare control-character delimiter (treat keys as opaque — don't hand-build them). `invalidateUrlPrefix(urlPrefix)` is the common move: it recovers the URL field structurally, so it matches **any** HTTP method and even keys a custom `cache.hash` prepends a namespace to. For a fully-custom key scheme it takes an optional `match` (`(urlPrefix) => (key) => boolean`). Call `clear()` on logout so no prior user's responses survive. For observability there's a read-only `cache.stats()` signal (`{ size, hits, misses }`) — handy for a debug panel; it deliberately exposes no mutation surface.
 
 Prefer the declarative [`invalidates`](#declarative-invalidation-invalidates) option on `mutationResource` for the common "mutation succeeded → refresh related queries" case.
 
@@ -657,6 +660,96 @@ Practical consequences:
 - **`keepPrevious` works alongside both.** While a retry or refresh is in flight, `value()` is the previous successful result, not `undefined`.
 - **Circuit breaker beats retry.** If the breaker opens during a retry sequence, the resource is disabled — no more retries until the breaker probes and closes.
 
+## Testing
+
+Testing code that uses `queryResource`/`mutationResource` comes down to two things: a deterministic cache and a way to feed mock HTTP responses.
+
+### `provideMockQueryCache(options?)`
+
+A real in-memory cache built for tests. Unlike `provideQueryCache()` it never touches IndexedDB or `BroadcastChannel`, and it disables the cleanup sweep interval — so it's safe under `vi.useFakeTimers()` / `jest.useFakeTimers()` and leaves no timers pinned between specs. It's a real cache (not a stub), so cache hits behave exactly as in production and you can assert against them.
+
+```typescript
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { TestBed } from '@angular/core/testing';
+import {
+  createCacheInterceptor,
+  createDedupeRequestsInterceptor,
+  provideMockQueryCache,
+} from '@mmstack/resource';
+
+beforeEach(() => {
+  TestBed.configureTestingModule({
+    providers: [
+      provideMockQueryCache(),
+      provideHttpClient(
+        withInterceptors([
+          createCacheInterceptor(),
+          createDedupeRequestsInterceptor(),
+          // your response-mocking interceptor (see below)
+        ]),
+      ),
+    ],
+  });
+});
+```
+
+> A plain `queryResource` no longer requires any cache provider at all (the in-memory default applies), so `provideMockQueryCache()` is only needed when you want the deterministic, timer-free cache for asserting caching behavior.
+
+### `provideMockResourceSensors(options?)`
+
+Resources auto-pause when the network drops or the page is hidden. To drive that behavior in a test — instead of relying on the real `navigator.onLine` / `document.visibilityState` — provide controllable sensors. Pass your own writable signals to toggle state mid-test; omit them for a static online + visible environment.
+
+```typescript
+import { signal } from '@angular/core';
+import { provideMockResourceSensors } from '@mmstack/resource';
+
+const online = signal(true);
+
+TestBed.configureTestingModule({
+  providers: [provideMockResourceSensors({ networkStatus: online })],
+});
+
+// ...later in the test
+online.set(false); // the resource sees the network drop and disables
+```
+
+### Mocking HTTP responses
+
+For most tests — a cold cache or a resource that doesn't cache — Angular's standard `provideHttpClientTesting()` + `HttpTestingController` works out of the box, because a cache miss flows through the interceptor chain to the testing backend like any other request.
+
+```typescript
+import {
+  provideHttpClient,
+  provideHttpClientTesting,
+} from '@angular/common/http/testing';
+import { HttpTestingController } from '@angular/common/http/testing';
+
+const ctrl = TestBed.inject(HttpTestingController);
+ctrl.expectOne('https://example.com/posts').flush([{ id: 1 }]);
+```
+
+When you specifically want to assert that a **cache hit short-circuits before the network**, `HttpTestingController` won't see the second request (that's the point). For those cases set the mock response on the request's `HttpContext` and read it from a tiny interceptor, which lets you count how many requests actually reached the network:
+
+```typescript
+import { HttpContextToken, type HttpInterceptorFn } from '@angular/common/http';
+import { HttpResponse } from '@angular/common/http';
+import { of } from 'rxjs';
+
+const MOCK = new HttpContextToken<() => unknown>(() => () => null);
+
+const mockInterceptor: HttpInterceptorFn = (req) =>
+  of(new HttpResponse({ body: req.context.get(MOCK)(), status: 200 }));
+```
+
+Pass `context` on the request and reuse the same cache key (same URL) to observe the hit:
+
+```typescript
+queryResource(
+  () => ({ url, context: new HttpContext().set(MOCK, () => ({ ok: true })) }),
+  { cache: { staleTime: 10_000 } },
+);
+```
+
 ## Recipes
 
 ### Optimistic update with rollback
@@ -669,7 +762,7 @@ Declarative — the common case:
 
 ```typescript
 mutationResource((p: Post) => ({ url: '/posts', method: 'POST', body: p }), {
-  invalidates: ['/posts'], // every cached GET under /posts, params + subpaths + vary variants
+  invalidates: ['/posts'], // every cached entry under /posts, any method + params + subpaths + vary variants
 });
 ```