@mmstack/resource 20.5.1 → 20.6.0

package/fesm2022/mmstack-resource.mjs

@@ -1,7 +1,7 @@
 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 { HttpHeaders, HttpResponse, HttpContextToken, HttpContext, HttpParams, httpResource, HttpClient } from '@angular/common/http';
+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';
 
@@ -193,6 +193,12 @@ class Cache {
                     const value = syncTabs.deserialize(msg.entry.value);
                     if (value === null)
                         return;
+                    // Last-write-wins by `updated` timestamp. If our local entry was
+                    // written more recently than the broadcast we just received, the
+                    // broadcast is stale (in-flight when we wrote locally) — drop it.
+                    const existing = untracked(this.internal).get(msg.entry.key);
+                    if (existing && existing.updated >= msg.entry.updated)
+                        return;
                     this.storeInternal(msg.entry.key, value, msg.entry.stale - msg.entry.updated, msg.entry.expiresAt - msg.entry.updated, true, false);
                 }
                 else if (msg.action === 'invalidate') {
@@ -340,6 +346,31 @@ class Cache {
     invalidate(key) {
         this.invalidateInternal(key);
     }
+    /**
+     * Invalidates every cache entry whose key starts with `prefix`. Common after a
+     * list-mutating operation (e.g. invalidate every paginated `GET /api/posts*`
+     * after a POST). Returns the number of entries removed.
+     *
+     * @example
+     * cache.invalidatePrefix('GET https://api.example.com/posts');
+     */
+    invalidatePrefix(prefix) {
+        return this.invalidateWhere((key) => key.startsWith(prefix));
+    }
+    /**
+     * Invalidates every cache entry whose key matches the predicate. Use for
+     * arbitrary bulk invalidation that doesn't fit prefix matching (e.g.
+     * "everything containing `userId=42`"). Returns the number of entries removed.
+     *
+     * @example
+     * cache.invalidateWhere((key) => key.includes('/me/'));
+     */
+    invalidateWhere(predicate) {
+        const keys = Array.from(untracked(this.internal).keys()).filter(predicate);
+        for (const key of keys)
+            this.invalidateInternal(key);
+        return keys.length;
+    }
     invalidateInternal(key, fromSync = false) {
         const entry = this.getUntracked(key);
         if (!entry)
@@ -519,6 +550,173 @@ function injectQueryCache(injector) {
     return cache;
 }
 
+/**
+ * Returns `true` for any object-like value whose own enumerable keys should
+ * be sorted for stable hashing. Excludes arrays (positional), `Date`
+ * (handled by `toJSON`), `Map`/`Set` (handled explicitly), and binary types
+ * (`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`/typed arrays — these
+ * should be branched on before reaching `hash()`, typically by `hashRequest`).
+ *
+ * Plain objects, class instances, and `Object.create(null)` all qualify.
+ */
+function isHashableObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    if (value instanceof Date)
+        return false;
+    if (value instanceof Map)
+        return false;
+    if (value instanceof Set)
+        return false;
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return false;
+    if (typeof FormData !== 'undefined' && value instanceof FormData)
+        return false;
+    if (typeof URLSearchParams !== 'undefined' &&
+        value instanceof URLSearchParams)
+        return false;
+    if (value instanceof ArrayBuffer)
+        return false;
+    if (ArrayBuffer.isView(value))
+        return false;
+    return true;
+}
+function sortKeys(val) {
+    return Object.keys(val)
+        .toSorted()
+        .reduce((result, key) => {
+        result[key] = val[key];
+        return result;
+    }, {});
+}
+/**
+ * Internal helper to generate a stable JSON string from an array.
+ * - Object-like values (plain, class instances, null-proto) get their own
+ *   enumerable keys sorted alphabetically.
+ * - `Map` → marker object with sorted entries (sorted by `JSON.stringify(key)`).
+ * - `Set` → marker object with sorted values (sorted by `JSON.stringify(value)`).
+ * - Arrays preserve order. `Date` serializes via `toJSON`.
+ *
+ * @internal
+ */
+function hashKey(queryKey) {
+    return JSON.stringify(queryKey, (_, val) => {
+        if (val instanceof Map) {
+            // Schwartzian: compute each entry's sort key (recursive hash of the
+            // Map key) once, then sort by the cheap string compare.
+            const entries = [...val.entries()]
+                .map((e) => [hash(e[0]), e])
+                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                .map(([, e]) => e);
+            return { __map__: entries };
+        }
+        if (val instanceof Set) {
+            const values = [...val]
+                .map((v) => [hash(v), v])
+                .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                .map(([, v]) => v);
+            return { __set__: values };
+        }
+        if (isHashableObject(val))
+            return sortKeys(val);
+        return val;
+    });
+}
+/**
+ * Generates a stable, unique string hash from one or more arguments.
+ * Useful for creating cache keys or identifiers where object key order shouldn't matter.
+ *
+ * How it works:
+ * - Object-like values (plain objects, class instances, `Object.create(null)`) have
+ *   their own enumerable keys sorted alphabetically before hashing. This ensures
+ *   `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash.
+ * - `Map` and `Set` are serialized via stable, sorted markers (`__map__` / `__set__`).
+ * - Arrays preserve positional order; `Date` uses its ISO string via `toJSON`.
+ *
+ * @param {...unknown} args Values to include in the hash.
+ * @returns A stable string hash representing the input arguments.
+ * @example
+ * hash('posts', 10);
+ * // => '["posts",10]'
+ *
+ * hash({ a: 1, b: 2 }) === hash({ b: 2, a: 1 }); // true
+ *
+ * hash(new Map([['a', 1]])) === hash(new Map([['a', 1]])); // true
+ *
+ * // Be mindful of values JSON.stringify cannot handle (functions, undefined, Symbols)
+ * // hash('a', undefined, function() {}) => '["a",null,null]'
+ */
+function hash(...args) {
+    return hashKey(args);
+}
+
+function normalizeParams(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('&');
+    })
+        .join('&');
+}
+function hashBody(body) {
+    // File extends Blob — must check File first
+    if (typeof File !== 'undefined' && body instanceof File) {
+        return `File:${body.name}:${body.type}:${body.size}:${body.lastModified}`;
+    }
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        return `Blob:${body.type}:${body.size}`;
+    }
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const entries = [];
+        body.forEach((value, key) => {
+            entries.push([key, hashBody(value)]);
+        });
+        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) {
+        const sp = new URLSearchParams(body);
+        sp.sort();
+        return `URLSearchParams:${sp.toString()}`;
+    }
+    if (body instanceof ArrayBuffer) {
+        return `ArrayBuffer:${body.byteLength}`;
+    }
+    if (ArrayBuffer.isView(body)) {
+        return `${body.constructor.name}:${body.byteLength}`;
+    }
+    return hash(body);
+}
+/**
+ * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
+ * `HttpRequest` and `HttpResourceRequest`).
+ *
+ * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}]`
+ * - `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`
+ *   and typed arrays explicitly; everything else flows through key-sorted
+ *   `JSON.stringify` via `hash()`.
+ */
+function hashRequest(req) {
+    const method = req.method ?? 'GET';
+    const responseType = req.responseType ?? 'json';
+    const base = `${method}:${req.url}:${responseType}`;
+    const params = req.params ? `:${normalizeParams(req.params)}` : '';
+    const body = req.body != null ? `:${hashBody(req.body)}` : '';
+    return base + params + body;
+}
+
 const CACHE_CONTEXT = new HttpContextToken(() => ({
     cache: false,
 }));
@@ -662,7 +860,7 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
         const opt = getCacheContext(req.context);
         if (!opt.cache)
             return next(req);
-        const key = opt.key ?? req.urlWithParams;
+        const key = opt.key ?? hashRequest(req);
         const entry = cache.getUntracked(key); // null if expired or not found
         // If the entry is not stale, return it
         if (entry && !entry.isStale)
@@ -682,7 +880,9 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
             });
         }
         return next(req).pipe(tap((event) => {
-            if (event instanceof HttpResponse && event.ok) {
+            if (!(event instanceof HttpResponse))
+                return;
+            if (event.ok) {
                 const cacheControl = parseCacheControlHeader(event);
                 if (cacheControl.noStore && !opt.ignoreCacheControl)
                     return;
@@ -701,6 +901,17 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
                     })
                     : event;
                 cache.store(key, parsedResponse, staleTime, ttl, opt.persist);
+                return;
+            }
+            // 304 → server confirmed our cached entry is still valid. Re-stamp the
+            // existing entry so subsequent reads within the new freshness window
+            // don't trigger another revalidation round-trip.
+            if (event.status === 304 && entry) {
+                const cacheControl = parseCacheControlHeader(event);
+                const { staleTime, ttl } = opt.ignoreCacheControl
+                    ? opt
+                    : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
+                cache.store(key, entry.value, staleTime, ttl, opt.persist);
             }
         }), map((event) => {
             // handle 304 responses due to eTag/last-modified
@@ -728,17 +939,18 @@ function catchValueError(resource, fallback) {
 
 /** @internal */
 const DEFAULT_OPTIONS = {
-    treshold: 5,
+    threshold: 5,
     timeout: 30000,
     shouldFail: () => true,
     shouldFailForever: () => false,
 };
 /** @internal */
-function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldFail = () => true, shouldFailForever = () => false) {
+function internalCeateCircuitBreaker(threshold = 5, resetTimeout = 30000, shouldFail = () => true, shouldFailForever = () => false) {
     const halfOpen = signal(false, ...(ngDevMode ? [{ debugName: "halfOpen" }] : []));
     const failureCount = signal(0, ...(ngDevMode ? [{ debugName: "failureCount" }] : []));
+    const failedForever = signal(false, ...(ngDevMode ? [{ debugName: "failedForever" }] : []));
     const status = computed(() => {
-        if (failureCount() >= treshold)
+        if (failedForever() || failureCount() >= threshold)
             return 'OPEN';
         return halfOpen() ? 'HALF_OPEN' : 'CLOSED';
     }, ...(ngDevMode ? [{ debugName: "status" }] : []));
@@ -752,17 +964,17 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         if (!untracked(isOpen))
             return;
         halfOpen.set(true);
-        failureCount.set(treshold - 1);
+        failureCount.set(threshold - 1);
     };
-    let failForeverResetId = null;
+    // Auto-probe effect: schedules a half-open retry after `resetTimeout` whenever
+    // the breaker is open, *unless* we've been failed forever (in which case only
+    // hardReset() can recover).
     const effectRef = effect((cleanup) => {
-        if (!isOpen())
+        if (!isOpen() || failedForever())
             return;
         const timeout = setTimeout(tryOnce, resetTimeout);
-        failForeverResetId = timeout;
         return cleanup(() => {
             clearTimeout(timeout);
-            failForeverResetId = null;
         });
     }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
     const failInternal = () => {
@@ -770,12 +982,8 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         halfOpen.set(false);
     };
     const failForever = () => {
-        if (failForeverResetId)
-            clearTimeout(failForeverResetId);
-        effectRef.destroy();
-        failureCount.set(Infinity);
+        failedForever.set(true);
         halfOpen.set(false);
-        return;
     };
     const fail = (err) => {
         if (shouldFailForever(err))
@@ -784,6 +992,11 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
             return failInternal();
         // If the error does not trigger a failure, we do nothing.
     };
+    const hardReset = () => {
+        failedForever.set(false);
+        failureCount.set(0);
+        halfOpen.set(false);
+    };
     return {
         status,
         isClosed,
@@ -791,6 +1004,7 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         fail,
         success,
         halfOpen: tryOnce,
+        hardReset,
         destroy: () => effectRef.destroy(),
     };
 }
@@ -809,18 +1023,43 @@ function createNeverBrokenCircuitBreaker() {
         halfOpen: () => {
             // noop
         },
+        hardReset: () => {
+            // noop
+        },
         destroy: () => {
             // noop
         },
     };
 }
 const CB_DEFAULT_OPTIONS = new InjectionToken('MMSTACK_CIRCUIT_BREAKER_DEFAULT_OPTIONS');
+/**
+ * Provides application-wide default options for {@link createCircuitBreaker}.
+ * Any `createCircuitBreaker()` call without explicit options (or with only
+ * partial options) merges these defaults in, so you can centralize threshold /
+ * timeout / failure-classifier behavior in one place.
+ *
+ * Per-call options always win over the provided defaults.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideCircuitBreakerDefaultOptions({
+ *       threshold: 10,
+ *       timeout: 60_000,
+ *       shouldFailForever: (err) =>
+ *         err instanceof HttpErrorResponse && [401, 403].includes(err.status),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 function provideCircuitBreakerDefaultOptions(options) {
     return {
         provide: CB_DEFAULT_OPTIONS,
         useValue: {
             ...DEFAULT_OPTIONS,
-            ...options,
+            ...normalizeThreshold(options),
         },
     };
 }
@@ -829,12 +1068,23 @@ function injectCircuitBreakerOptions(injector = inject(Injector)) {
         optional: true,
     });
 }
+/** @internal — strips the deprecated `treshold` field and folds it into `threshold` */
+function normalizeThreshold(opt) {
+    if (!opt || typeof opt !== 'object' || 'isClosed' in opt)
+        return {};
+    const { treshold, threshold, ...rest } = opt;
+    return {
+        ...rest,
+        threshold: threshold ?? treshold,
+    };
+}
 /**
  * Creates a circuit breaker instance.
  *
  * @param options - Configuration options for the circuit breaker.  Can be:
- *   - `undefined`:  Creates a "no-op" circuit breaker that is always open (never trips).
- *   - `true`: Creates a circuit breaker with default settings (threshold: 5, timeout: 30000ms).
+ *   - `undefined`:  Uses defaults (threshold: 5, timeout: 30000ms) or provided defaults via {@link provideCircuitBreakerDefaultOptions}.
+ *   - `false`: Creates a "no-op" circuit breaker that is always closed (never trips).
+ *   - `true`: Creates a circuit breaker with default settings.
  *   - `CircuitBreaker`:  Reuses an existing `CircuitBreaker` instance.
  *   - `{ threshold?: number; timeout?: number; }`: Creates a circuit breaker with the specified threshold and timeout.
  *
@@ -857,11 +1107,11 @@ function createCircuitBreaker(opt, injector) {
         return createNeverBrokenCircuitBreaker();
     if (typeof opt === 'object' && 'isClosed' in opt)
         return opt;
-    const { treshold, timeout, shouldFail, shouldFailForever } = {
+    const { threshold, timeout, shouldFail, shouldFailForever } = {
         ...injectCircuitBreakerOptions(injector),
-        ...opt,
+        ...normalizeThreshold(opt),
     };
-    return internalCeateCircuitBreaker(treshold, timeout, shouldFail, shouldFailForever);
+    return internalCeateCircuitBreaker(threshold, timeout, shouldFail, shouldFailForever);
 }
 
 // Heavily inspired by: https://dev.to/kasual1/request-deduplication-in-angular-3pd8
@@ -893,6 +1143,9 @@ function noDedupe(ctx = new HttpContext()) {
  *
  * @param allowed - An array of HTTP methods for which deduplication should be enabled.
  *                  Defaults to `['GET', 'DELETE', 'HEAD', 'OPTIONS']`.
+ * @param keyFn - Optional function to compute the dedupe key from a request.
+ *                Defaults to `hashRequest`, which includes method, URL,
+ *                response type, params, and body.
  *
  * @returns An `HttpInterceptorFn` that implements the request deduplication logic.
  *
@@ -916,97 +1169,22 @@ function noDedupe(ctx = new HttpContext()) {
  *   ],
  * };
  */
-function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OPTIONS']) {
+function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OPTIONS'], keyFn = hashRequest) {
     const inFlight = new Map();
     const DEDUPE_METHODS = new Set(allowed);
     return (req, next) => {
         if (!DEDUPE_METHODS.has(req.method) || req.context.get(NO_DEDUPE))
             return next(req);
-        const found = inFlight.get(req.urlWithParams);
+        const key = keyFn(req);
+        const found = inFlight.get(key);
         if (found)
             return found;
-        const request = next(req).pipe(finalize(() => inFlight.delete(req.urlWithParams)), shareReplay());
-        inFlight.set(req.urlWithParams, request);
+        const request = next(req).pipe(finalize(() => inFlight.delete(key)), shareReplay({ bufferSize: 1, refCount: true }));
+        inFlight.set(key, request);
         return request;
     };
 }
 
-/**
- * Checks if `value` is a plain JavaScript object (e.g., `{}` or `new Object()`).
- * Distinguishes from arrays, null, and class instances. Acts as a type predicate,
- * narrowing `value` to `UnknownObject` if `true`.
- *
- * @param value The value to check.
- * @returns {value is UnknownObject} `true` if `value` is a plain object, otherwise `false`.
- * @example
- * isPlainObject({}) // => true
- * isPlainObject([]) // => false
- * isPlainObject(null) // => false
- * isPlainObject(new Date()) // => false
- */
-function isPlainObject(value) {
-    if (value === null || typeof value !== 'object')
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    if (proto === null)
-        return false; // remove Object.create(null);
-    return proto === Object.prototype;
-}
-/**
- * Internal helper to generate a stable JSON string from an array.
- * Sorts keys of plain objects within the array alphabetically before serialization
- * to ensure hash stability regardless of key order.
- *
- * @param queryKey The array of values to serialize.
- * @returns A stable JSON string representation.
- * @internal
- */
-function hashKey(queryKey) {
-    return JSON.stringify(queryKey, (_, val) => isPlainObject(val)
-        ? Object.keys(val)
-            .toSorted()
-            .reduce((result, key) => {
-            result[key] = val[key];
-            return result;
-        }, {})
-        : val);
-}
-/**
- * Generates a stable, unique string hash from one or more arguments.
- * Useful for creating cache keys or identifiers where object key order shouldn't matter.
- *
- * How it works:
- * - Plain objects within the arguments have their keys sorted alphabetically before hashing.
- * This ensures that `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash.
- * - Uses `JSON.stringify` internally with custom sorting for plain objects via `hashKey`.
- * - Non-plain objects (arrays, Dates, etc.) and primitives are serialized naturally.
- *
- * @param {...unknown} args Values to include in the hash.
- * @returns A stable string hash representing the input arguments.
- * @example
- * const userQuery = (id: number) => ['user', { id, timestamp: Date.now() }];
- *
- * const obj1 = { a: 1, b: 2 };
- * const obj2 = { b: 2, a: 1 }; // Same keys/values, different order
- *
- * hash('posts', 10);
- * // => '["posts",10]'
- *
- * hash('config', obj1);
- * // => '["config",{"a":1,"b":2}]'
- *
- * hash('config', obj2);
- * // => '["config",{"a":1,"b":2}]' (Same as above due to key sorting)
- *
- * hash(['todos', { status: 'done', owner: obj1 }]);
- * // => '[["todos",{"owner":{"a":1,"b":2},"status":"done"}]]'
- *
- * // Be mindful of values JSON.stringify cannot handle (functions, undefined, Symbols)
- * // hash('a', undefined, function() {}) => '["a",null,null]'
- */
-function hash(...args) {
-    return hashKey(args);
-}
 function equalTransferCache(a, b) {
     if (!a && !b)
         return true;
@@ -1240,13 +1418,16 @@ function refresh(resource, destroyRef, refresh) {
 }
 
 // Retry on error, if number is provided it will retry that many times with exponential backoff, otherwise it will use the options provided
-function retryOnError(res, opt) {
+function retryOnError(res, opt, onError) {
     const max = opt ? (typeof opt === 'number' ? opt : (opt.max ?? 0)) : 0;
     const backoff = typeof opt === 'object' ? (opt.backoff ?? 1000) : 1000;
     let retries = 0;
     let timeout;
-    const onError = () => {
-        if (retries >= max)
+    const handleError = () => {
+        const err = untracked(res.error);
+        const isFinal = retries >= max;
+        onError?.(err, retries, isFinal);
+        if (isFinal)
             return;
         retries++;
         if (timeout)
@@ -1261,7 +1442,7 @@ function retryOnError(res, opt) {
     const ref = effect(() => {
         switch (res.status()) {
             case 'error':
-                return onError();
+                return handleError();
             case 'resolved':
                 return onSuccess();
         }
@@ -1308,29 +1489,6 @@ function toResourceObject(res) {
     };
 }
 
-function normalizeParams(params) {
-    if (params instanceof HttpParams)
-        return params.toString();
-    const paramMap = new Map();
-    for (const [key, value] of Object.entries(params)) {
-        if (Array.isArray(value)) {
-            paramMap.set(key, value.map(encodeURIComponent).join(','));
-        }
-        else {
-            paramMap.set(key, encodeURIComponent(value.toString()));
-        }
-    }
-    return Array.from(paramMap.entries())
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([key, value]) => `${key}=${value}`)
-        .join('&');
-}
-function urlWithParams(req) {
-    if (!req.params)
-        return req.url;
-    return `${req.url}?${normalizeParams(req.params)}`;
-}
-
 function queryResource(request, options) {
     const cache = injectQueryCache(options?.injector);
     const destroyRef = options?.injector
@@ -1343,10 +1501,20 @@ function queryResource(request, options) {
     const eq = options?.triggerOnSameRequest
         ? undefined
         : createEqualRequest(options?.equal);
+    const rawRequest = computed(() => request() ?? undefined, ...(ngDevMode ? [{ debugName: "rawRequest" }] : []));
+    const disabledReason = computed(() => {
+        if (!networkAvailable())
+            return 'offline';
+        if (cb.isOpen())
+            return 'circuit-open';
+        if (!rawRequest())
+            return 'no-request';
+        return null;
+    }, ...(ngDevMode ? [{ debugName: "disabledReason" }] : []));
     const stableRequest = computed(() => {
-        if (!networkAvailable() || cb.isOpen())
+        if (disabledReason() !== null)
             return undefined;
-        const req = request();
+        const req = rawRequest();
         if (!req)
             return undefined;
         if (typeof req === 'string')
@@ -1364,8 +1532,8 @@ function queryResource(request, options) {
             },
         }]));
     const hashFn = typeof options?.cache === 'object'
-        ? (options.cache.hash ?? urlWithParams)
-        : urlWithParams;
+        ? (options.cache.hash ?? hashRequest)
+        : hashRequest;
     const staleTime = typeof options?.cache === 'object' ? options.cache.staleTime : 0;
     const ttl = typeof options?.cache === 'object' ? options.cache.ttl : undefined;
     const cacheKey = computed(() => {
@@ -1444,7 +1612,7 @@ function queryResource(request, options) {
             },
         }]));
     resource = refresh(resource, destroyRef, options?.refresh);
-    resource = retryOnError(resource, options?.retry);
+    resource = retryOnError(resource, options?.retry, options?.onError);
     resource = persistResourceValues(resource, options?.keepPrevious, options?.equal);
     const value = options?.cache
         ? toWritable(computed(() => {
@@ -1452,20 +1620,6 @@ function queryResource(request, options) {
             return cacheEntry()?.value ?? resource.value();
         }), resource.value.set, resource.value.update)
         : resource.value;
-    const onError = options?.onError; // Put in own variable to ensure value remains even if options are somehow mutated in-line
-    if (onError) {
-        const onErrorRef = effect(() => {
-            const err = resource.error();
-            if (err)
-                onError(err);
-        }, ...(ngDevMode ? [{ debugName: "onErrorRef" }] : []));
-        // cleanup on manual destroy, I'm comfortable setting these props in-line as we have yet to 'release' the object out of this lexical scope
-        const destroyRest = resource.destroy;
-        resource.destroy = () => {
-            onErrorRef.destroy();
-            destroyRest();
-        };
-    }
     // iterate circuit breaker state, is effect as a computed would cause a circular dependency (resource -> cb -> resource)
     const cbEffectRef = effect(() => {
         const status = resource.status();
@@ -1497,7 +1651,8 @@ function queryResource(request, options) {
         update,
         statusCode: linkedSignal(resource.statusCode),
         headers: linkedSignal(resource.headers),
-        disabled: computed(() => cb.isOpen() || stableRequest() === undefined),
+        disabled: computed(() => disabledReason() !== null),
+        disabledReason,
         reload: () => {
             cb.halfOpen(); // open the circuit for manual reload
             return resource.reload();