@mmstack/resource 20.7.0 → 20.8.0

package/README.md

@@ -21,6 +21,9 @@ It's designed to be opt-in feature by feature: starting with `queryResource()` a
 - [`manualQueryResource`](#manualqueryresource)
 - [Caching](#caching)
 - [Circuit breakers](#circuit-breakers)
+- [Transitions & Suspense](#transitions--suspense)
+- [Pausing a resource](#pausing-a-resource)
+- [Default options (`provideResourceOptions`)](#default-options-provideresourceoptions)
 - [Composition (retry / refresh / keepPrevious)](#composition-retry--refresh--keepprevious)
 - [Recipes](#recipes)
 
@@ -177,12 +180,12 @@ queryResource(() => ({
 
 ```ts
 queryResource<TResult, TRaw = TResult>(
-  request: () => HttpResourceRequest | string | undefined,
+  request: (ctx: RequestContext) => HttpResourceRequest | string | undefined | typeof PAUSED,
   options?: QueryResourceOptions<TResult, TRaw>,
 ): QueryResourceRef<TResult>
 ```
 
-`request` is a reactive function. Whenever it returns a new value, a new request is made; returning `undefined` disables the resource until the function returns something again.
+`request` is a reactive function. Whenever it returns a new value, a new request is made; returning `undefined` **disables** the resource until the function returns something again. It receives a `RequestContext` whose `paused` token it can return to **pause** instead — see [pausing a resource](#pausing-a-resource).
 
 ### Options
 
@@ -196,7 +199,9 @@ queryResource<TResult, TRaw = TResult>(
 | `circuitBreaker`       | `true \| CircuitBreaker \| { threshold?, timeout?, … }` | off                | See [circuit breakers](#circuit-breakers).                                                                     |
 | `cache`                | `ResourceCacheOptions`                                 | off                | Enables caching for this resource. See [caching](#caching).                                                    |
 | `triggerOnSameRequest` | `boolean`                                              | `false`            | Re-run even if the request object equals the previous one. Use sparingly.                                      |
+| `register`             | `boolean \| { suspends?: boolean }`                    | `false`            | Auto-register into the nearest transition scope. See [transitions & Suspense](#transitions--suspense).         |
 | `equal`                | `ValueEqualityFn<TResult>`                             | `Object.is`        | Custom equality for the result value (forwarded to `httpResource`).                                            |
+| `equalRequest`         | `(a, b) => boolean`                                    | structural         | Custom equality for the **request** object (controls dedup / refetch). Defaults to a deep structural compare.   |
 | `injector`             | `Injector`                                             | `inject(Injector)` | Use this injector for cache/circuit-breaker resolution. Required if calling outside an injection context.      |
 | `parse`                | `(raw: TRaw) => TResult`                               | identity           | Transform the raw HTTP response. Does not affect cache keys.                                                   |
 
@@ -270,6 +275,16 @@ mutationResource(request, { queue: true });
 
 Queued mutations sit in a signal-backed queue and execute one at a time. The queue **persists across resource-disabled states** — if the circuit breaker opens or the network drops, queued mutations stay pending and run when the resource recovers. This is intentional for resilience (think "POST goes out when we're back online"), but it does mean a queued mutation can fire long after the user triggered it. Don't enable `queue` if that's surprising in your UX.
 
+### Re-firing with an identical body (`triggerOnSameRequest`)
+
+A mutation is an imperative command, so by default an identical `mutate(body)` while one is in flight is **deduplicated** (double-click protection). When a repeat with the same body _must_ fire — e.g. a "resend" button — set `triggerOnSameRequest: true`, and every `mutate()` fires regardless of whether the body changed.
+
+```typescript
+mutationResource(request, { triggerOnSameRequest: true });
+```
+
+A mutation also honours the `register` option — but it registers the **mutation ref itself** into the transition scope (its internal query is never registered), so a `<mm-suspense>`/transition reacts to the mutation's own `pending` state. See [transitions & Suspense](#transitions--suspense).
+
 ### Return shape (`MutationResourceRef<T, TMutation>`)
 
 | Member                                        | Type                        | Notes                                                  |
@@ -410,6 +425,81 @@ authService.refreshToken().subscribe(() => {
 
 `hardReset()` is also useful for testing — it gives you a "back to factory state" handle without reconstructing the breaker.
 
+## Transitions & Suspense
+
+Resources plug into `@mmstack/primitives`' [transition scope](https://www.npmjs.com/package/@mmstack/primitives#concurrency--transitions) — the machinery behind Suspense boundaries and route transitions. Set `register` and the resource adds itself to the nearest scope (and removes itself on destroy), so a `<mm-suspense>` boundary or a `<mm-transition-outlet>` can coordinate its loading state:
+
+The boundary provides the scope, so the resource has to register from **inside** it — i.e. the data-owning component sits within the `<mm-suspense>` tags (registration resolves the scope up the injector tree). A query declared on the same component that _renders_ the boundary is above it and won't be captured.
+
+```typescript
+import { Component, input } from '@angular/core';
+import { SuspenseBoundary } from '@mmstack/primitives';
+import { queryResource } from '@mmstack/resource';
+
+@Component({ selector: 'user-profile', template: `{{ user.value()?.name }}` })
+class UserProfile {
+  readonly id = input.required<string>();
+  // `register: { suspends: true }` registers into the nearest scope (the
+  // <mm-suspense> above) and blocks its first paint until a value lands.
+  readonly user = queryResource<User>(() => `/api/users/${this.id()}`, {
+    register: { suspends: true },
+  });
+}
+
+@Component({
+  selector: 'user-page',
+  imports: [SuspenseBoundary, UserProfile],
+  template: `
+    <mm-suspense>
+      <span placeholder>Loading…</span>
+      <user-profile [id]="id()" />
+    </mm-suspense>
+  `,
+})
+class UserPage {
+  readonly id = input.required<string>();
+}
+```
+
+- `register: true` (or `{ suspends: false }`) — register for the **pending indicator + hold-stale**; does _not_ block first paint. The right choice for in-region data: the boundary shows the held value with `aria-busy`, not a placeholder.
+- `register: { suspends: true }` — register as **suspending**: the boundary holds its placeholder until this resource has a value (full Suspense).
+- `false` / omitted — don't register.
+
+Combine with `keepPrevious: true` so reloads hold the last value instead of flashing empty — then a `<mm-suspense>` shows the placeholder only on the genuine first load, and `startTransition` (from `@mmstack/primitives`) can reveal a multi-resource update in one frame. For navigation, `@mmstack/router-core`'s `<mm-transition-outlet>` keeps the current route on screen until the incoming route's registered resources settle.
+
+## Pausing a resource
+
+The request fn can return `ctx.paused` (the `PAUSED` token) to **pause** the resource: it holds its current value and last request, stops polling, and does **not** refetch on resume unless the request changed. This is distinct from returning `undefined` (which _disables_ — a disabled resource may refetch when re-enabled; a paused one resumes exactly where it left off). It pairs with keep-alive (`MmActivity` / `injectPaused`) so a hidden tab's queries go quiet without losing their data:
+
+```typescript
+import { injectPaused } from '@mmstack/primitives';
+
+class Panel {
+  private readonly paused = injectPaused(); // true while the tab is hidden by *mmActivity
+
+  readonly data = queryResource<Data>((ctx) =>
+    this.paused() ? ctx.paused : `/api/data/${this.id()}`,
+  );
+}
+```
+
+## Default options (`provideResourceOptions`)
+
+Common options (`register`, `retry`, `circuitBreaker`, `triggerOnSameRequest`) can be defaulted app-wide, with a three-layer precedence — **per-call > type-specific provider > common provider**:
+
+```typescript
+providers: [
+  // Layer 1 — applies to every resource kind.
+  provideResourceOptions({ retry: { max: 2 }, register: true }),
+  // Layer 2 — queries only (inherits + overrides layer 1).
+  provideQueryResourceOptions({ circuitBreaker: true }),
+  // Layer 2 — mutations only.
+  provideMutationResourceOptions({ register: false }),
+];
+```
+
+Each accepts a value or a factory (`() => options`). A per-call option always wins — including opting out of a provider default with `register: false` — so you can make "all queries participate in transitions" the default and turn it off for the odd one.
+
 ## Composition (retry / refresh / keepPrevious)
 
 The wrappers stack in a fixed order inside `queryResource`:

package/fesm2022/mmstack-resource.mjs

@@ -1,10 +1,47 @@
 import * as i0 from '@angular/core';
-import { isDevMode, untracked, computed, InjectionToken, inject, signal, effect, Injector, linkedSignal, Injectable, DestroyRef } from '@angular/core';
-import { mutable, toWritable, sensor, nestedEffect } from '@mmstack/primitives';
+import { InjectionToken, inject, runInInjectionContext, DestroyRef, isDevMode, untracked, computed, signal, effect, Injector, Injectable, linkedSignal } from '@angular/core';
+import { injectTransitionScope, mutable, toWritable, keepPrevious, sensor, nestedEffect } from '@mmstack/primitives';
 import { HttpHeaders, HttpResponse, HttpParams, HttpContextToken, HttpContext, httpResource, HttpClient } from '@angular/common/http';
 import { of, tap, map, finalize, shareReplay, interval, firstValueFrom, catchError, combineLatestWith, filter } from 'rxjs';
 import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
 
+const RESOURCE_OPTIONS = new InjectionToken('@mmstack/resource:resource-options', { factory: () => ({}) });
+function asProvider(token, valueOrFn) {
+    return typeof valueOrFn === 'function'
+        ? { provide: token, useFactory: valueOrFn }
+        : { provide: token, useValue: valueOrFn };
+}
+/** Layer 1: defaults that apply to ALL resource kinds. Type-specific providers inherit + override these. */
+function provideResourceOptions(valueOrFn) {
+    return asProvider(RESOURCE_OPTIONS, valueOrFn);
+}
+function injectResourceOptions(injector) {
+    return injector ? injector.get(RESOURCE_OPTIONS) : inject(RESOURCE_OPTIONS);
+}
+/** Shared helper for the type-specific providers (query/mutation), so precedence is identical. */
+function provideTypedResourceOptions(token, valueOrFn) {
+    return asProvider(token, valueOrFn);
+}
+/**
+ * Applies a resolved `register` option to a freshly-created resource — adds it to the nearest
+ * transition scope and removes it on destroy. Runs in the resource's injection context (or the
+ * provided `injector`), since registration needs `TRANSITION_SCOPE` + `DestroyRef`.
+ */
+function applyResourceRegistration(ref, register, injector) {
+    if (!register)
+        return;
+    const opt = register === true ? { suspends: false } : register;
+    const run = injector
+        ? (fn) => runInInjectionContext(injector, fn)
+        : (fn) => fn();
+    run(() => {
+        const scope = injectTransitionScope();
+        const destroyRef = inject(DestroyRef);
+        scope.add(ref, opt);
+        destroyRef.onDestroy(() => scope.remove(ref));
+    });
+}
+
 function createNoopDB() {
     return {
         getAll: async () => [],
@@ -653,17 +690,13 @@ function hash(...args) {
 }
 
 function normalizeParams(params) {
-    const p = params instanceof HttpParams
-        ? params
-        : new HttpParams({ fromObject: params });
+    const p = params instanceof HttpParams ? params : new HttpParams({ fromObject: params });
     return p
         .keys()
         .toSorted()
         .map((key) => {
         const encodedKey = encodeURIComponent(key);
-        return (p.getAll(key) ?? [])
-            .map((v) => `${encodedKey}=${encodeURIComponent(v)}`)
-            .join('&');
+        return (p.getAll(key) ?? []).map((v) => `${encodedKey}=${encodeURIComponent(v)}`).join('&');
     })
         .join('&');
 }
@@ -683,8 +716,7 @@ function hashBody(body) {
         entries.sort(([ak, av], [bk, bv]) => ak.localeCompare(bk) || av.localeCompare(bv));
         return `FormData:${entries.map(([k, v]) => `${k}=${v}`).join('&')}`;
     }
-    if (typeof URLSearchParams !== 'undefined' &&
-        body instanceof URLSearchParams) {
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
         const sp = new URLSearchParams(body);
         sp.sort();
         return `URLSearchParams:${sp.toString()}`;
@@ -1354,57 +1386,37 @@ function hasSlowConnection() {
     return false;
 }
 
-function persist(src, equal) {
-    // linkedSignal allows us to access previous source value
-    const persisted = linkedSignal(...(ngDevMode ? [{ debugName: "persisted", source: () => src(),
-            computation: (next, prev) => {
-                if (next === undefined && prev !== undefined)
-                    return prev.value;
-                return next;
-            },
-            equal }] : [{
-            source: () => src(),
-            computation: (next, prev) => {
-                if (next === undefined && prev !== undefined)
-                    return prev.value;
-                return next;
-            },
-            equal,
-        }]));
-    // if original value was WritableSignal then override linkedSignal methods to original...angular uses linkedSignal under the hood in ResourceImpl, this applies to that.
-    if ('set' in src) {
-        persisted.set = src.set;
-        persisted.update = src.update;
-        persisted.asReadonly = src.asReadonly;
-    }
-    return persisted;
-}
 function persistResourceValues(resource, shouldPersist = false, equal) {
     if (!shouldPersist)
         return resource;
     return {
         ...resource,
-        statusCode: persist(resource.statusCode),
-        headers: persist(resource.headers),
-        value: persist(resource.value, equal),
+        statusCode: keepPrevious(resource.statusCode),
+        headers: keepPrevious(resource.headers),
+        value: keepPrevious(resource.value, { equal }),
     };
 }
 
-// refresh resource every n miliseconds or don't refresh if undefined provided. 0 also excluded, due to it not being a valid usecase
-function refresh(resource, destroyRef, refresh) {
+// refresh resource every n miliseconds or don't refresh if undefined provided. 0 also excluded, due to it not being a valid usecase.
+function refresh(resource, destroyRef, refresh, inactive) {
     if (!refresh)
         return resource; // no refresh requested
+    const tick = () => {
+        if (inactive?.())
+            return; // disabled / paused → skip the poll
+        resource.reload();
+    };
     // we can use RxJs here as reloading the resource will always be a side effect & as such does not impact the reactive graph in any way.
     let sub = interval(refresh)
         .pipe(takeUntilDestroyed(destroyRef))
-        .subscribe(() => resource.reload());
+        .subscribe(tick);
     const reload = () => {
         sub.unsubscribe(); // do not conflict with manual reload
         const hasReloaded = resource.reload();
         // resubscribe after manual reload
         sub = interval(refresh)
             .pipe(takeUntilDestroyed(destroyRef))
-            .subscribe(() => resource.reload());
+            .subscribe(tick);
         return hasReloaded;
     };
     return {
@@ -1489,7 +1501,35 @@ function toResourceObject(res) {
     };
 }
 
-function queryResource(request, options) {
+const QUERY_RESOURCE_OPTIONS = new InjectionToken('@mmstack/resource:query-resource-options', { factory: () => ({}) });
+/**
+ * Layer 2 (query): default options for every `queryResource`, inheriting + overriding the
+ * common defaults from `provideResourceOptions`. Per-call options override these in turn.
+ */
+function provideQueryResourceOptions(valueOrFn) {
+    return provideTypedResourceOptions(QUERY_RESOURCE_OPTIONS, valueOrFn);
+}
+function injectQueryResourceOptions(injector) {
+    return injector
+        ? injector.get(QUERY_RESOURCE_OPTIONS)
+        : inject(QUERY_RESOURCE_OPTIONS);
+}
+/**
+ * Returned from a resource's request fn to PAUSE it: the resource holds its current value and last
+ * request (so it does not refetch on resume), and stops background work (no polling, no refetch
+ * while paused). Distinct from returning `undefined` (DISABLE), which drops the request — a
+ * disabled resource may refetch when re-enabled, a paused one resumes exactly where it left off.
+ *
+ * The request fn receives a {@link RequestContext} and can just return `ctx.paused`.
+ */
+const PAUSED = Symbol('@mmstack/resource:paused');
+function queryResource(request, options0) {
+    // Two-layer option injection: per-call > provideQueryResourceOptions > provideResourceOptions.
+    const options = {
+        ...injectResourceOptions(options0?.injector),
+        ...injectQueryResourceOptions(options0?.injector),
+        ...options0,
+    };
     const cache = injectQueryCache(options?.injector);
     const destroyRef = options?.injector
         ? options.injector.get(DestroyRef)
@@ -1500,32 +1540,70 @@ function queryResource(request, options) {
     const networkAvailable = injectNetworkStatus();
     const eq = options?.triggerOnSameRequest
         ? undefined
-        : createEqualRequest(options?.equal);
-    const rawRequest = computed(() => request() ?? undefined, ...(ngDevMode ? [{ debugName: "rawRequest" }] : []));
+        : (options?.equalRequest ?? createEqualRequest());
+    const requestCtx = { paused: PAUSED };
+    const rawResult = computed(() => request(requestCtx), ...(ngDevMode ? [{ debugName: "rawResult" }] : []));
+    const paused = computed(() => rawResult() === PAUSED, ...(ngDevMode ? [{ debugName: "paused" }] : []));
+    const rawRequest = computed(() => {
+        const r = rawResult();
+        return r === PAUSED ? undefined : (r ?? undefined);
+    }, ...(ngDevMode ? [{ debugName: "rawRequest" }] : []));
     const disabledReason = computed(() => {
         if (!networkAvailable())
             return 'offline';
         if (cb.isOpen())
             return 'circuit-open';
+        // PAUSED makes rawRequest undefined, so it reports 'no-request' here (and skips polling),
+        // while stableRequest below HOLDS the last request so the value is kept (no refetch on resume).
         if (!rawRequest())
             return 'no-request';
         return null;
     }, ...(ngDevMode ? [{ debugName: "disabledReason" }] : []));
-    const stableRequest = computed(() => {
-        if (disabledReason() !== null)
-            return undefined;
-        const req = rawRequest();
-        if (!req)
-            return undefined;
-        if (typeof req === 'string')
-            return { method: 'GET', url: req };
-        return req;
-    }, ...(ngDevMode ? [{ debugName: "stableRequest", equal: (a, b) => {
+    // While PAUSED, hold the previous request so httpResource sees no change — it keeps its value and
+    // does NOT refetch. On resume the request is re-evaluated, so it refetches only if it changed.
+    const heldRequest = linkedSignal(...(ngDevMode ? [{ debugName: "heldRequest", source: () => {
+                if (paused())
+                    return { req: undefined, held: true };
+                if (disabledReason() !== null)
+                    return { req: undefined, held: false };
+                const req = rawRequest();
+                if (!req)
+                    return { req: undefined, held: false };
+                if (typeof req === 'string')
+                    return { req: { method: 'GET', url: req }, held: false };
+                return { req, held: false };
+            },
+            computation: (curr, prev) => curr.held && prev !== undefined ? prev.value : curr.req }] : [{
+            source: () => {
+                if (paused())
+                    return { req: undefined, held: true };
+                if (disabledReason() !== null)
+                    return { req: undefined, held: false };
+                const req = rawRequest();
+                if (!req)
+                    return { req: undefined, held: false };
+                if (typeof req === 'string')
+                    return { req: { method: 'GET', url: req }, held: false };
+                return { req, held: false };
+            },
+            computation: (curr, prev) => curr.held && prev !== undefined ? prev.value : curr.req,
+        }]));
+    // Dedup via the request-equality (the linkedSignal re-runs on every source tick; this computed
+    // is what actually gates httpResource — so an equal/held request never triggers a refetch).
+    const stableRequest = computed(() => heldRequest(), ...(ngDevMode ? [{ debugName: "stableRequest", equal: (a, b) => {
+                if (a === b)
+                    return true;
+                if (a === undefined || b === undefined)
+                    return false;
                 if (eq)
                     return eq(a, b);
                 return a === b;
             } }] : [{
             equal: (a, b) => {
+                if (a === b)
+                    return true;
+                if (a === undefined || b === undefined)
+                    return false;
                 if (eq)
                     return eq(a, b);
                 return a === b;
@@ -1611,7 +1689,8 @@ function queryResource(request, options) {
                 };
             },
         }]));
-    resource = refresh(resource, destroyRef, options?.refresh);
+    // A disabled (offline / circuit-open / no-request) or PAUSED resource must not poll.
+    resource = refresh(resource, destroyRef, options?.refresh, () => disabledReason() !== null);
     resource = retryOnError(resource, options?.retry, options?.onError);
     resource = persistResourceValues(resource, options?.keepPrevious, options?.equal);
     const set = (value) => {
@@ -1641,7 +1720,7 @@ function queryResource(request, options) {
     const client = options?.injector
         ? options.injector.get(HttpClient)
         : inject(HttpClient);
-    return {
+    const ref = {
         ...resource,
         value,
         set,
@@ -1708,6 +1787,9 @@ function queryResource(request, options) {
             }
         },
     };
+    // Auto-register into the nearest transition scope if the (merged) options ask for it.
+    applyResourceRegistration(ref, options.register, options?.injector);
+    return ref;
 }
 
 function manualQueryResource(request, options) {
@@ -1751,6 +1833,19 @@ function manualQueryResource(request, options) {
 }
 
 const NULL_VALUE = Symbol('@mmstack/resource:null');
+const MUTATION_RESOURCE_OPTIONS = new InjectionToken('@mmstack/resource:mutation-resource-options', { factory: () => ({}) });
+/**
+ * Layer 2 (mutation): default options for every `mutationResource`, inheriting + overriding the
+ * common defaults from `provideResourceOptions`. Per-call options override these in turn.
+ */
+function provideMutationResourceOptions(valueOrFn) {
+    return provideTypedResourceOptions(MUTATION_RESOURCE_OPTIONS, valueOrFn);
+}
+function injectMutationResourceOptions(injector) {
+    return 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.
@@ -1769,16 +1864,62 @@ const NULL_VALUE = Symbol('@mmstack/resource:null');
  * @typeParam TMethod - The HTTP method to be used for the mutation (defaults to `HttpResourceRequest['method']`).
  * @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),
+ *   },
+ * );
+ * ```
  */
-function mutationResource(request, options = {}) {
-    const { onMutate, onError, onSuccess, onSettled, equal, ...rest } = options;
-    const requestEqual = createEqualRequest(equal);
+function mutationResource(request, options0 = {}) {
+    // Two-layer option injection: per-call > provideMutationResourceOptions > provideResourceOptions.
+    const options = {
+        ...injectResourceOptions(options0.injector),
+        ...injectMutationResourceOptions(options0.injector),
+        ...options0,
+    };
+    // `register` is pulled out (and forced off on the inner query below) so the mutation ref is
+    // the only thing registered into the transition scope, not its internal query resource.
+    const { onMutate, onError, onSuccess, onSettled, equal, register, equalRequest, ...rest } = options;
+    const requestEqual = equalRequest ?? createEqualRequest(equal);
+    // A mutation is an imperative command, so `triggerOnSameRequest` means "fire on EVERY mutate(),
+    // even with an identical body". By default we dedup an identical value/request while one is in
+    // flight (double-click protection); when this is set, both the `next` and `req` dedup are bypassed
+    // so a repeat click isn't silently swallowed mid-flight. (Otherwise it'd be dropped until `next`
+    // resets to NULL on settle — the "every other click" symptom.)
+    const triggerOnSame = options.triggerOnSameRequest ?? false;
     const eq = equal ?? Object.is;
     const next = signal(NULL_VALUE, ...(ngDevMode ? [{ debugName: "next", equal: (a, b) => {
                 if (a === NULL_VALUE && b === NULL_VALUE)
                     return true;
                 if (a === NULL_VALUE || b === NULL_VALUE)
                     return false;
+                if (triggerOnSame)
+                    return false;
                 return eq(a, b);
             } }] : [{
             equal: (a, b) => {
@@ -1786,6 +1927,8 @@ function mutationResource(request, options = {}) {
                     return true;
                 if (a === NULL_VALUE || b === NULL_VALUE)
                     return false;
+                if (triggerOnSame)
+                    return false;
                 return eq(a, b);
             },
         }]));
@@ -1813,8 +1956,24 @@ function mutationResource(request, options = {}) {
         if (nr === NULL_VALUE)
             return;
         return request(nr) ?? undefined;
-    }, ...(ngDevMode ? [{ debugName: "req", equal: requestEqual }] : [{
-            equal: requestEqual,
+    }, ...(ngDevMode ? [{ debugName: "req", equal: (a, b) => {
+                if (a === undefined && b === undefined)
+                    return true;
+                if (a === undefined || b === undefined)
+                    return false;
+                if (triggerOnSame)
+                    return false;
+                return requestEqual(a, b);
+            } }] : [{
+            equal: (a, b) => {
+                if (a === undefined && b === undefined)
+                    return true;
+                if (a === undefined || b === undefined)
+                    return false;
+                if (triggerOnSame)
+                    return false;
+                return requestEqual(a, b);
+            },
         }]));
     const lastValue = linkedSignal(...(ngDevMode ? [{ debugName: "lastValue", source: next,
             computation: (next, prev) => {
@@ -1834,15 +1993,29 @@ function mutationResource(request, options = {}) {
         if (nr === NULL_VALUE)
             return;
         return request(nr) ?? undefined;
-    }, ...(ngDevMode ? [{ debugName: "lastValueRequest", equal: requestEqual }] : [{
-            equal: requestEqual,
+    }, ...(ngDevMode ? [{ debugName: "lastValueRequest", equal: (a, b) => {
+                if (a === b)
+                    return true;
+                if (a === undefined || b === undefined)
+                    return false;
+                return requestEqual(a, b);
+            } }] : [{
+            equal: (a, b) => {
+                if (a === b)
+                    return true;
+                if (a === undefined || b === undefined)
+                    return false;
+                return requestEqual(a, b);
+            },
         }]));
     const cb = createCircuitBreaker(options?.circuitBreaker === true
         ? undefined
         : (options?.circuitBreaker ?? false), options?.injector);
     const resource = queryResource(req, {
         ...rest,
+        register: false, // the mutation ref handles registration; never register the inner query
         circuitBreaker: cb,
+        equalRequest: requestEqual,
         defaultValue: NULL_VALUE, // doesnt matter since .value is not accessible
     });
     const destroyRef = options.injector
@@ -1876,7 +2049,7 @@ function mutationResource(request, options = {}) {
         next.set(NULL_VALUE);
     });
     const shouldQueue = options.queue ?? false;
-    return {
+    const ref = {
         ...resource,
         destroy: () => {
             statusSub.unsubscribe();
@@ -1907,11 +2080,13 @@ function mutationResource(request, options = {}) {
         // redeclare disabled with last value so that it is not affected by the resource's internal disablement logic
         disabled: computed(() => cb.isOpen() || lastValueRequest() === undefined),
     };
+    applyResourceRegistration(ref, register, options0.injector);
+    return ref;
 }
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
+export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
 //# sourceMappingURL=mmstack-resource.mjs.map