@mmstack/resource 19.7.0 → 19.7.2

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';
@@ -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({
@@ -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

package/fesm2022/mmstack-resource.mjs

@@ -535,7 +535,7 @@ class Cache {
         };
         if (this.cleanupOpt.maxSize <= 0)
             throw new Error('maxSize must be greater than 0');
-        // a non-finite checkInterval disables the sweeper entirely (used by the shared NoopCache)
+        // a non-finite checkInterval disables the sweeper entirely (used by provideMockQueryCache)
         const cleanupInterval = Number.isFinite(this.cleanupOpt.checkInterval)
             ? setInterval(() => {
                 this.cleanup();
@@ -905,7 +905,48 @@ class Cache {
         this.internal.set(new Map(keep));
     }
 }
-const CLIENT_CACHE_TOKEN = new InjectionToken('INTERNAL_CLIENT_CACHE');
+const CLIENT_CACHE_TOKEN = new InjectionToken('INTERNAL_CLIENT_CACHE', {
+    // Memory-only default so a plain queryResource works with zero config. No
+    // IndexedDB / BroadcastChannel — keeps it SSR-safe and request-isolated under
+    // SSR (root injector is per-request). provideQueryCache() overrides this to
+    // layer on persistence / cross-tab sync / global TTL tuning.
+    providedIn: 'root',
+    factory: () => {
+        const cache = new Cache();
+        inject(DestroyRef, { optional: true })?.onDestroy(() => cache.destroy());
+        return cache;
+    },
+});
+/**
+ * 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()])),
+ *   ],
+ * });
+ */
+function provideMockQueryCache(opt) {
+    return {
+        provide: CLIENT_CACHE_TOKEN,
+        useFactory: () => {
+            const cache = new Cache(opt?.ttl, opt?.staleTime, {
+                type: 'lru',
+                maxSize: 200,
+                checkInterval: Infinity,
+            });
+            inject(DestroyRef, { optional: true })?.onDestroy(() => cache.destroy());
+            return cache;
+        },
+    };
+}
 /**
  * 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.
@@ -968,15 +1009,12 @@ function provideQueryCache(opt) {
             return null;
         }
     };
-    // version-suffixed so two deploys with incompatible schemas in adjacent tabs don't
-    // push entries into each other's caches (the `version` option only fences IndexedDB)
     const syncChannelId = `mmstack-query-cache-sync_v${opt?.version ?? 1}`;
     return {
         provide: CLIENT_CACHE_TOKEN,
         useFactory: () => {
             const onServer = inject(PLATFORM_ID) === 'server';
-            // no IndexedDB / BroadcastChannel on the server — each request gets an
-            // isolated, request-lived, memory-only cache
+            // no IndexedDB / BroadcastChannel on the server
             const syncTabsOpt = !onServer && opt?.syncTabs
                 ? {
                     id: syncChannelId,
@@ -1016,24 +1054,6 @@ function provideQueryCache(opt) {
         },
     };
 }
-class NoopCache extends Cache {
-    constructor() {
-        // Infinity checkInterval → no sweep interval is ever armed, so the shared
-        // instance below never pins a timer
-        super(undefined, undefined, {
-            type: 'lru',
-            maxSize: 200,
-            checkInterval: Infinity,
-        });
-    }
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    store(_, __, ___ = super.staleTime, ____ = super.ttl) {
-        // noop
-    }
-}
-// one shared instance — minting a NoopCache per injectQueryCache() miss would leak
-// an instance (and previously an interval) on every prod call without a provider
-let NOOP_CACHE;
 /**
  * Injects the `QueryCache` instance that is used within queryResource.
  * Allows for direct modification of cached data, but is mostly meant for internal use.
@@ -1058,18 +1078,8 @@ let NOOP_CACHE;
  */
 function injectQueryCache(injector) {
     const cache = injector
-        ? injector.get(CLIENT_CACHE_TOKEN, null, {
-            optional: true,
-        })
-        : inject(CLIENT_CACHE_TOKEN, {
-            optional: true,
-        });
-    if (!cache) {
-        if (isDevMode())
-            throw new Error('Cache not provided, please add provideQueryCache() to providers array');
-        else
-            return (NOOP_CACHE ??= new NoopCache());
-    }
+        ? injector.get(CLIENT_CACHE_TOKEN)
+        : inject(CLIENT_CACHE_TOKEN);
     return cache;
 }
 /**
@@ -1977,6 +1987,33 @@ function injectNetworkStatus() {
 function injectPageVisibility() {
     return inject(ResourceSensors).pageVisibility;
 }
+/**
+ * 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
+ */
+function provideMockResourceSensors(opt) {
+    return {
+        provide: ResourceSensors,
+        useValue: {
+            networkStatus: opt?.networkStatus ?? signal(true),
+            pageVisibility: opt?.pageVisibility ?? signal('visible'),
+        },
+    };
+}
 
 function toResourceObject(res) {
     return {
@@ -2473,6 +2510,57 @@ function injectMutationResourceOptions(injector) {
         ? injector.get(MUTATION_RESOURCE_OPTIONS)
         : inject(MUTATION_RESOURCE_OPTIONS);
 }
+/**
+ * Creates a resource for performing mutations (e.g., POST, PUT, PATCH, DELETE requests).
+ * Unlike `queryResource`, `mutationResource` is designed for one-off operations that change data.
+ * It does *not* cache responses and does not provide a `value` signal.  Instead, it focuses on
+ * managing the mutation lifecycle (pending, error, success) and provides callbacks for handling
+ * these states.
+ *
+ * @param request A function that returns the base `HttpResourceRequest` to be made. This function is called reactively. The parameter is the mutation value provided by the `mutate` method.
+ * @param options Configuration options for the mutation resource.  This includes callbacks
+ *               for `onMutate`, `onError`, `onSuccess`, and `onSettled`.
+ * @typeParam TResult - The type of the expected result from the mutation.
+ * @typeParam TRaw - The raw response type from the HTTP request (defaults to TResult).
+ * @typeParam TMutation - The type of the mutation value (the request body).
+ * @typeParam TICTX - The type of the initial context value passed to `onMutate`.
+ * @typeParam TCTX - The type of the context value returned by `onMutate`.
+ * @returns A `MutationResourceRef` instance, which provides methods for triggering the mutation
+ *          and observing its status.
+ *
+ * @example
+ * ```ts
+ * // Basic PATCH mutation
+ * const updateUser = mutationResource<User, User, Partial<User>>(
+ *   (body) => ({ url: `/api/users/${userId()}`, method: 'PATCH', body }),
+ *   {
+ *     onSuccess: (saved) => toast.success(`Updated ${saved.name}`),
+ *     onError: (err) => toast.error(err),
+ *   },
+ * );
+ *
+ * updateUser.mutate({ name: 'Alice' });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optimistic update with rollback via the `ctx` returned from `onMutate`
+ * const updateUser = mutationResource<User, User, Partial<User>, { prev: User | null }>(
+ *   (body) => ({ url: `/api/users/${userId()}`, method: 'PATCH', body }),
+ *   {
+ *     onMutate: (patch) => {
+ *       const prev = current();
+ *       current.update((u) => (u ? { ...u, ...patch } : u));
+ *       return { prev };
+ *     },
+ *     onError: (_err, { prev }) => current.set(prev),
+ *   },
+ * );
+ * ```
+ */
+// The request callback maps the mutation value into an HTTP request. `body` is a
+// free-form request field (Angular's `body?: unknown`), independent of `TMutation`
+// and optional — so bodyless POSTs and transforms (e.g. params → `FormData`) are fine.
 function mutationResource(request, options0 = {}) {
     // Two-layer option injection: per-call > provideMutationResourceOptions > provideResourceOptions.
     const globalOpts = injectResourceOptions(options0.injector);
@@ -2717,5 +2805,5 @@ function mutationResource(request, options0 = {}) {
  * Generated bundle index. Do not edit.
  */
 
-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 };
 //# sourceMappingURL=mmstack-resource.mjs.map