@mmstack/resource 19.2.0 → 19.3.1

package/fesm2022/mmstack-resource.mjs

@@ -1,11 +1,109 @@
-import { computed, untracked, InjectionToken, inject, isDevMode, signal, effect, linkedSignal, ResourceStatus, DestroyRef } from '@angular/core';
+import * as i0 from '@angular/core';
+import { isDevMode, untracked, computed, InjectionToken, inject, signal, effect, Injector, linkedSignal, ResourceStatus, 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 { of, tap, map, finalize, shareReplay, interval, firstValueFrom, catchError, combineLatestWith, filter } from 'rxjs';
 import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
-import { of, tap, map, finalize, shareReplay, interval, firstValueFrom, combineLatestWith, filter } from 'rxjs';
-import { HttpContextToken, HttpContext, HttpResponse, HttpParams, httpResource, HttpClient } from '@angular/common/http';
-import { mutable, toWritable } from '@mmstack/primitives';
-import { v7 } from 'uuid';
-import { keys, hash, entries } from '@mmstack/object';
 
+function createNoopDB() {
+    return {
+        getAll: async () => [],
+        store: async () => {
+            // noop
+        },
+        remove: async () => {
+            // noop
+        },
+    };
+}
+function toCacheDB(db, storeName) {
+    const getAll = async () => {
+        const now = Date.now();
+        return new Promise((res, rej) => {
+            const transaction = db.transaction(storeName, 'readonly');
+            const store = transaction.objectStore(storeName);
+            const request = store.getAll();
+            request.onsuccess = () => res(request.result);
+            request.onerror = () => rej(request.error);
+        })
+            .then((entries) => entries.filter((e) => e.expiresAt > now))
+            .catch((err) => {
+            if (isDevMode())
+                console.error('Error getting all items from cache DB:', err);
+            return [];
+        });
+    };
+    const store = (value) => {
+        return new Promise((res, rej) => {
+            const transaction = db.transaction(storeName, 'readwrite');
+            const store = transaction.objectStore(storeName);
+            store.put(value);
+            transaction.oncomplete = () => res();
+            transaction.onerror = () => rej(transaction.error);
+        }).catch((err) => {
+            if (isDevMode())
+                console.error('Error storing item in cache DB:', err);
+        });
+    };
+    const remove = (key) => {
+        return new Promise((res, rej) => {
+            const transaction = db.transaction(storeName, 'readwrite');
+            const store = transaction.objectStore(storeName);
+            store.delete(key);
+            transaction.oncomplete = () => res();
+            transaction.onerror = () => rej(transaction.error);
+        }).catch((err) => {
+            if (isDevMode())
+                console.error('Error removing item from cache DB:', err);
+        });
+    };
+    return {
+        getAll,
+        store,
+        remove,
+    };
+}
+function createSingleStoreDB(name, getStoreName, version = 1) {
+    const storeName = getStoreName(version);
+    if (!globalThis.indexedDB)
+        return Promise.resolve(createNoopDB());
+    return new Promise((res, rej) => {
+        if (version < 1)
+            rej(new Error('Version must be 1 or greater'));
+        const req = indexedDB.open(name, version);
+        req.onupgradeneeded = (event) => {
+            const db = req.result;
+            const oldVersion = event.oldVersion;
+            db.createObjectStore(storeName, { keyPath: 'key' });
+            if (oldVersion > 0) {
+                db.deleteObjectStore(getStoreName(oldVersion));
+            }
+        };
+        req.onerror = () => {
+            rej(req.error);
+        };
+        req.onsuccess = () => res(req.result);
+    })
+        .then((db) => toCacheDB(db, storeName))
+        .catch((err) => {
+        if (isDevMode())
+            console.error('Error creating query DB:', err);
+        return createNoopDB();
+    });
+}
+
+function generateID() {
+    if (globalThis.crypto?.randomUUID) {
+        return globalThis.crypto.randomUUID();
+    }
+    return Math.random().toString(36).substring(2);
+}
+function isSyncMessage(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'type' in msg &&
+        msg.type === 'cache-sync-message');
+}
 const ONE_DAY = 1000 * 60 * 60 * 24;
 const ONE_HOUR = 1000 * 60 * 60;
 const DEFAULT_CLEANUP_OPT = {
@@ -21,8 +119,18 @@ const DEFAULT_CLEANUP_OPT = {
 class Cache {
     ttl;
     staleTime;
+    db;
     internal = mutable(new Map());
     cleanupOpt;
+    id = generateID();
+    /**
+     * Destroys the cache instance, cleaning up any resources used by the cache.
+     * This method is called automatically when the cache instance is garbage collected.
+     */
+    destroy;
+    broadcast = () => {
+        // noop
+    };
     /**
      * Creates a new `Cache` instance.
      *
@@ -31,14 +139,17 @@ class Cache {
      *                    stale but can still be used while revalidation occurs in the background. Defaults to 1 hour.
      * @param cleanupOpt - Options for configuring the cache cleanup strategy.  Defaults to LRU with a
      *                     `maxSize` of 200 and a `checkInterval` of one hour.
+     * @param syncTabs - If provided, the cache will use the options a BroadcastChannel to send updates between tabs.
+     *                   Defaults to `undefined`, meaning no synchronization across tabs.
      */
     constructor(ttl = ONE_DAY, staleTime = ONE_HOUR, cleanupOpt = {
         type: 'lru',
         maxSize: 1000,
         checkInterval: ONE_HOUR,
-    }) {
+    }, syncTabs, db = Promise.resolve(createNoopDB())) {
         this.ttl = ttl;
         this.staleTime = staleTime;
+        this.db = db;
         this.cleanupOpt = {
             ...DEFAULT_CLEANUP_OPT,
             ...cleanupOpt,
@@ -49,14 +160,82 @@ class Cache {
         const cleanupInterval = setInterval(() => {
             this.cleanup();
         }, cleanupOpt.checkInterval);
-        const destroyId = v7();
+        let destroySyncTabs = () => {
+            // noop
+        };
+        if (syncTabs) {
+            const channel = new BroadcastChannel(syncTabs.id);
+            this.broadcast = (msg) => {
+                if (msg.action === 'invalidate')
+                    return channel.postMessage({
+                        action: 'invalidate',
+                        entry: { key: msg.entry.key },
+                        cacheId: this.id,
+                        type: 'cache-sync-message',
+                    });
+                return channel.postMessage({
+                    ...msg,
+                    entry: {
+                        ...msg.entry,
+                        value: syncTabs.serialize(msg.entry.value),
+                    },
+                    cacheId: this.id,
+                    type: 'cache-sync-message',
+                });
+            };
+            channel.onmessage = (event) => {
+                const msg = event.data;
+                if (!isSyncMessage(msg))
+                    return;
+                if (msg.cacheId === this.id)
+                    return; // ignore messages from this cache
+                if (msg.action === 'store') {
+                    const value = syncTabs.deserialize(msg.entry.value);
+                    if (value === null)
+                        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') {
+                    this.invalidateInternal(msg.entry.key, true);
+                }
+            };
+            destroySyncTabs = () => {
+                channel.close();
+            };
+        }
+        let destroyed = false;
+        const destroy = () => {
+            if (destroyed)
+                return;
+            destroyed = true;
+            clearInterval(cleanupInterval);
+            destroySyncTabs();
+        };
+        this.db
+            .then(async (db) => {
+            if (destroyed)
+                return [];
+            return db.getAll();
+        })
+            .then((entries) => {
+            if (destroyed)
+                return;
+            // load entries into the cache
+            const current = untracked(this.internal);
+            entries.forEach((entry) => {
+                if (current.has(entry.key))
+                    return;
+                this.storeInternal(entry.key, entry.value, entry.stale - entry.updated, entry.expiresAt - entry.updated, true);
+            });
+        });
+        this.destroy = destroy;
         // cleanup if object is garbage collected, this is because the cache can be quite large from a memory standpoint & we dont want all that floating garbage
         const registry = new FinalizationRegistry((id) => {
-            if (id === destroyId) {
-                clearInterval(cleanupInterval);
+            if (id === this.id) {
+                destroy();
             }
         });
-        registry.register(this, destroyId);
+        registry.register(this, this.id);
     }
     /** @internal */
     getInternal(key) {
@@ -96,6 +275,17 @@ class Cache {
     get(key) {
         return this.getInternal(key);
     }
+    /**
+     * Retrieves a cache entry or an object with the key if not found.
+     *
+     * @param key - A function that returns the cache key. The key is a signal, allowing for dynamic keys. If the function returns null the value is also null.
+     * @returns  A signal that holds the cache entry or an object with the key if not found. The signal
+     *          updates whenever the cache entry changes (e.g., due to revalidation or expiration).
+     */
+    getEntryOrKey(key) {
+        const valueSig = this.getInternal(key);
+        return computed(() => valueSig() ?? key());
+    }
     /**
      * Stores a value in the cache.
      *
@@ -104,7 +294,10 @@ class Cache {
      * @param staleTime - (Optional) The stale time for this entry, in milliseconds. Overrides the default `staleTime`.
      * @param ttl - (Optional) The TTL for this entry, in milliseconds. Overrides the default `ttl`.
      */
-    store(key, value, staleTime = this.staleTime, ttl = this.ttl) {
+    store(key, value, staleTime = this.staleTime, ttl = this.ttl, persist = false) {
+        this.storeInternal(key, value, staleTime, ttl, false, persist);
+    }
+    storeInternal(key, value, staleTime = this.staleTime, ttl = this.ttl, fromSync = false, persist = false) {
         const entry = this.getUntracked(key);
         if (entry) {
             clearTimeout(entry.timeout); // stop invalidation
@@ -114,17 +307,30 @@ class Cache {
         if (ttl < staleTime)
             staleTime = ttl;
         const now = Date.now();
+        const next = {
+            value,
+            created: entry?.created ?? now,
+            updated: now,
+            useCount: prevCount + 1,
+            stale: now + staleTime,
+            expiresAt: now + ttl,
+            key,
+        };
         this.internal.mutate((map) => {
             map.set(key, {
-                value,
-                created: entry?.created ?? now,
-                useCount: prevCount + 1,
-                stale: now + staleTime,
-                expiresAt: now + ttl,
+                ...next,
                 timeout: setTimeout(() => this.invalidate(key), ttl),
             });
             return map;
         });
+        if (!fromSync) {
+            if (persist)
+                this.db.then((db) => db.store(next));
+            this.broadcast({
+                action: 'store',
+                entry: next,
+            });
+        }
     }
     /**
      * Invalidates (removes) a cache entry.
@@ -132,6 +338,9 @@ class Cache {
      * @param key - The key of the entry to invalidate.
      */
     invalidate(key) {
+        this.invalidateInternal(key);
+    }
+    invalidateInternal(key, fromSync = false) {
         const entry = this.getUntracked(key);
         if (!entry)
             return;
@@ -140,6 +349,10 @@ class Cache {
             map.delete(key);
             return map;
         });
+        if (!fromSync) {
+            this.db.then((db) => db.remove(key));
+            this.broadcast({ action: 'invalidate', entry: { key } });
+        }
     }
     /** @internal */
     cleanup() {
@@ -186,9 +399,80 @@ const CLIENT_CACHE_TOKEN = new InjectionToken('INTERNAL_CLIENT_CACHE');
  * };
  */
 function provideQueryCache(opt) {
+    const serialize = (value) => {
+        const headersRecord = {};
+        const headerKeys = value.headers.keys();
+        headerKeys.forEach((key) => {
+            const values = value.headers.getAll(key);
+            if (!values)
+                return;
+            headersRecord[key] = values;
+        });
+        return JSON.stringify({
+            body: value.body,
+            status: value.status,
+            statusText: value.statusText,
+            headers: headerKeys.length > 0 ? headersRecord : undefined,
+            url: value.url,
+        });
+    };
+    const deserialize = (value) => {
+        try {
+            const parsed = JSON.parse(value);
+            if (!parsed || typeof parsed !== 'object' || !('body' in parsed))
+                throw new Error('Invalid cache entry format');
+            const headers = parsed.headers
+                ? new HttpHeaders(parsed.headers)
+                : undefined;
+            return new HttpResponse({
+                body: parsed.body,
+                status: parsed.status,
+                statusText: parsed.statusText,
+                headers: headers,
+                url: parsed.url,
+            });
+        }
+        catch (err) {
+            if (isDevMode())
+                console.error('Failed to deserialize cache entry:', err);
+            return null;
+        }
+    };
+    const syncTabsOpt = opt?.syncTabs
+        ? {
+            id: 'mmstack-query-cache-sync',
+            serialize,
+            deserialize,
+        }
+        : undefined;
+    const db = opt?.persist === false
+        ? undefined
+        : createSingleStoreDB('mmstack-query-cache-db', (version) => `query-store_v${version}`, opt?.version).then((db) => {
+            return {
+                getAll: () => {
+                    return db.getAll().then((entries) => {
+                        return entries
+                            .map((entry) => {
+                            const value = deserialize(entry.value);
+                            if (value === null)
+                                return null;
+                            return {
+                                ...entry,
+                                value,
+                            };
+                        })
+                            .filter((e) => e !== null);
+                    });
+                },
+                store: (entry) => {
+                    return db.store({ ...entry, value: serialize(entry.value) });
+                },
+                remove: db.remove,
+            };
+        });
     return {
         provide: CLIENT_CACHE_TOKEN,
-        useValue: new Cache(opt?.ttl, opt?.staleTime, opt?.cleanup),
+        useValue: new Cache(opt?.ttl, opt?.staleTime, opt?.cleanup, syncTabsOpt, db),
     };
 }
 class NoopCache extends Cache {
@@ -322,30 +606,25 @@ function parseCacheControlHeader(req) {
         };
     return directives;
 }
-function resolveTimings(cacheControl, staleTime, ttl) {
-    const timings = {
-        staleTime,
-        ttl,
-    };
+function resolveTimings(cacheControl, optStaleTime, optTTL) {
+    let staleTime = optStaleTime;
+    let ttl = optTTL;
     if (cacheControl.immutable)
         return {
             staleTime: Infinity,
             ttl: Infinity,
         };
+    if (cacheControl.maxAge !== null)
+        ttl = cacheControl.maxAge * 1000;
+    if (cacheControl.staleWhileRevalidate !== null)
+        staleTime = cacheControl.staleWhileRevalidate * 1000;
     // if no-cache is set, we must always revalidate
     if (cacheControl.noCache || cacheControl.mustRevalidate)
-        timings.staleTime = 0;
-    if (cacheControl.staleWhileRevalidate !== null)
-        timings.staleTime = cacheControl.staleWhileRevalidate;
-    if (cacheControl.maxAge !== null)
-        timings.ttl = cacheControl.maxAge * 1000;
-    // if stale-while-revalidate is set, we must revalidate after that time at the latest, but we can still serve the stale data
-    if (cacheControl.staleWhileRevalidate !== null) {
-        const ms = cacheControl.staleWhileRevalidate * 1000;
-        if (timings.staleTime === undefined || timings.staleTime > ms)
-            timings.staleTime = ms;
+        staleTime = 0;
+    if (ttl !== undefined && staleTime !== undefined && ttl < staleTime) {
+        staleTime = ttl;
     }
-    return timings;
+    return { staleTime, ttl };
 }
 /**
  * Creates an `HttpInterceptorFn` that implements caching for HTTP requests. This interceptor
@@ -397,13 +676,31 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
         if (lastModified) {
             req = req.clone({ setHeaders: { 'If-Modified-Since': lastModified } });
         }
+        if (opt.bustBrowserCache) {
+            req = req.clone({
+                setParams: { _cb: Date.now().toString() },
+            });
+        }
         return next(req).pipe(tap((event) => {
             if (event instanceof HttpResponse && event.ok) {
                 const cacheControl = parseCacheControlHeader(event);
-                if (cacheControl.noStore)
+                if (cacheControl.noStore && !opt.ignoreCacheControl)
                     return;
-                const { staleTime, ttl } = resolveTimings(cacheControl, opt.staleTime, opt.ttl);
-                cache.store(key, event, staleTime, ttl);
+                const { staleTime, ttl } = opt.ignoreCacheControl
+                    ? opt
+                    : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
+                if (opt.ttl === 0)
+                    return; // no point
+                const parsedResponse = opt.parse
+                    ? new HttpResponse({
+                        body: opt.parse(event.body),
+                        headers: event.headers,
+                        status: event.status,
+                        statusText: event.statusText,
+                        url: event.url ?? undefined,
+                    })
+                    : event;
+                cache.store(key, parsedResponse, staleTime, ttl, opt.persist);
             }
         }), map((event) => {
             // handle 304 responses due to eTag/last-modified
@@ -415,39 +712,82 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
     };
 }
 
+function catchValueError(resource, fallback) {
+    return {
+        ...resource,
+        value: toWritable(computed(() => {
+            try {
+                return resource.value();
+            }
+            catch {
+                return fallback;
+            }
+        }), (value) => resource.value.set(value)),
+    };
+}
+
+/** @internal */
+const DEFAULT_OPTIONS = {
+    treshold: 5,
+    timeout: 30000,
+    shouldFail: () => true,
+    shouldFailForever: () => false,
+};
 /** @internal */
-function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000) {
+function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldFail = () => true, shouldFailForever = () => false) {
     const halfOpen = signal(false);
     const failureCount = signal(0);
     const status = computed(() => {
         if (failureCount() >= treshold)
-            return 'CLOSED';
-        return halfOpen() ? 'HALF_OPEN' : 'OPEN';
+            return 'OPEN';
+        return halfOpen() ? 'HALF_OPEN' : 'CLOSED';
     });
-    const isClosed = computed(() => status() === 'CLOSED');
+    const isClosed = computed(() => status() !== 'OPEN');
+    const isOpen = computed(() => status() !== 'CLOSED');
     const success = () => {
         failureCount.set(0);
         halfOpen.set(false);
     };
     const tryOnce = () => {
-        if (!untracked(isClosed))
+        if (!untracked(isOpen))
             return;
         halfOpen.set(true);
         failureCount.set(treshold - 1);
     };
+    let failForeverResetId = null;
     const effectRef = effect((cleanup) => {
-        if (!isClosed())
+        if (!isOpen())
             return;
         const timeout = setTimeout(tryOnce, resetTimeout);
-        return cleanup(() => clearTimeout(timeout));
+        failForeverResetId = timeout;
+        return cleanup(() => {
+            clearTimeout(timeout);
+            failForeverResetId = null;
+        });
     });
-    const fail = () => {
+    const failInternal = () => {
         failureCount.set(failureCount() + 1);
         halfOpen.set(false);
     };
+    const failForever = () => {
+        if (failForeverResetId)
+            clearTimeout(failForeverResetId);
+        effectRef.destroy();
+        failureCount.set(Infinity);
+        halfOpen.set(false);
+        return;
+    };
+    const fail = (err) => {
+        if (shouldFailForever(err))
+            return failForever();
+        if (shouldFail(err))
+            return failInternal();
+        // If the error does not trigger a failure, we do nothing.
+    };
     return {
         status,
         isClosed,
+        isOpen,
         fail,
         success,
         halfOpen: tryOnce,
@@ -457,8 +797,9 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000) {
 /** @internal */
 function createNeverBrokenCircuitBreaker() {
     return {
-        isClosed: computed(() => false),
-        status: signal('OPEN'),
+        isClosed: computed(() => true),
+        isOpen: computed(() => false),
+        status: signal('CLOSED'),
         fail: () => {
             // noop
         },
@@ -473,6 +814,21 @@ function createNeverBrokenCircuitBreaker() {
         },
     };
 }
+const CB_DEFAULT_OPTIONS = new InjectionToken('MMSTACK_CIRCUIT_BREAKER_DEFAULT_OPTIONS');
+function provideCircuitBreakerDefaultOptions(options) {
+    return {
+        provide: CB_DEFAULT_OPTIONS,
+        useValue: {
+            ...DEFAULT_OPTIONS,
+            ...options,
+        },
+    };
+}
+function injectCircuitBreakerOptions(injector = inject(Injector)) {
+    return injector.get(CB_DEFAULT_OPTIONS, DEFAULT_OPTIONS, {
+        optional: true,
+    });
+}
 /**
  * Creates a circuit breaker instance.
  *
@@ -496,12 +852,16 @@ function createNeverBrokenCircuitBreaker() {
  * const resource1 = queryResource(..., { circuitBreaker: sharedBreaker });
  * const resource2 = mutationResource(..., { circuitBreaker: sharedBreaker });
  */
-function createCircuitBreaker(opt) {
+function createCircuitBreaker(opt, injector) {
     if (opt === false)
         return createNeverBrokenCircuitBreaker();
     if (typeof opt === 'object' && 'isClosed' in opt)
         return opt;
-    return internalCeateCircuitBreaker(opt?.treshold, opt?.timeout);
+    const { treshold, timeout, shouldFail, shouldFailForever } = {
+        ...injectCircuitBreakerOptions(injector),
+        ...opt,
+    };
+    return internalCeateCircuitBreaker(treshold, timeout, shouldFail, shouldFailForever);
 }
 
 // Heavily inspired by: https://dev.to/kasual1/request-deduplication-in-angular-3pd8
@@ -571,6 +931,82 @@ function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OP
     };
 }
 
+/**
+ * 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;
@@ -591,16 +1027,62 @@ function equalTransferCache(a, b) {
     const aSet = new Set(a.includeHeaders ?? []);
     return b.includeHeaders.every((header) => aSet.has(header));
 }
+function equalParamArray(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    return a.every((value) => b.includes(value));
+}
+function headersToObject(headerClass) {
+    const headers = {};
+    headerClass.keys().forEach((key) => {
+        const value = headerClass.getAll(key);
+        if (value === null)
+            return;
+        if (value.length === 1) {
+            headers[key] = value[0];
+        }
+        else {
+            headers[key] = value;
+        }
+    });
+    return headers;
+}
+function paramToObject(paramsClass) {
+    const params = {};
+    paramsClass.keys().forEach((key) => {
+        const value = paramsClass.getAll(key);
+        if (value === null)
+            return;
+        if (value.length === 1) {
+            params[key] = value[0];
+        }
+        else {
+            params[key] = value;
+        }
+    });
+    return params;
+}
 function equalParams(a, b) {
     if (!a && !b)
         return true;
     if (!a || !b)
         return false;
-    const aKeys = keys(a);
-    const bKeys = keys(b);
+    const aObj = a instanceof HttpParams ? paramToObject(a) : a;
+    const bObj = b instanceof HttpParams ? paramToObject(b) : b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
     if (aKeys.length !== bKeys.length)
         return false;
-    return aKeys.every((key) => a[key] === b[key]);
+    return aKeys.every((key) => {
+        if (Array.isArray(aObj[key]) || Array.isArray(bObj[key])) {
+            return equalParamArray(Array.isArray(aObj[key]) ? aObj[key] : [aObj[key]], Array.isArray(bObj[key]) ? bObj[key] : [bObj[key]]);
+        }
+        return aObj[key] === bObj[key];
+    });
 }
 function equalBody(a, b) {
     if (!a && !b)
@@ -614,22 +1096,44 @@ function equalHeaders(a, b) {
         return true;
     if (!a || !b)
         return false;
-    const aKeys = keys(a);
-    const bKeys = keys(b);
+    const aObj = a instanceof HttpHeaders ? headersToObject(a) : a;
+    const bObj = b instanceof HttpHeaders ? headersToObject(b) : b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
     if (aKeys.length !== bKeys.length)
         return false;
-    return aKeys.every((key) => a[key] === b[key]);
+    return aKeys.every((key) => {
+        if (Array.isArray(aObj[key]) || Array.isArray(bObj[key])) {
+            return equalParamArray(Array.isArray(aObj[key]) ? aObj[key] : [aObj[key]], Array.isArray(bObj[key]) ? bObj[key] : [bObj[key]]);
+        }
+        return aObj[key] === bObj[key];
+    });
+}
+function toHttpContextEntries(ctx) {
+    if (!ctx)
+        return [];
+    if (ctx instanceof HttpContext) {
+        const tokens = Array.from(ctx.keys());
+        return tokens.map((key) => [key.toString(), ctx.get(key)]);
+    }
+    if (typeof ctx === 'object') {
+        return Object.entries(ctx);
+    }
+    return [];
 }
 function equalContext(a, b) {
     if (!a && !b)
         return true;
     if (!a || !b)
         return false;
-    const aKeys = keys(a);
-    const bKeys = keys(b);
-    if (aKeys.length !== bKeys.length)
+    const aEntries = toHttpContextEntries(a);
+    const bEntries = toHttpContextEntries(b);
+    if (aEntries.length !== bEntries.length)
         return false;
-    return aKeys.every((key) => a[key] === b[key]);
+    if (aEntries.length === 0)
+        return true;
+    const bMap = new Map(bEntries);
+    return aEntries.every(([key, value]) => value === bMap.get(key));
 }
 function createEqualRequest(equalResult) {
     const eqb = equalResult ?? equalBody;
@@ -672,38 +1176,33 @@ function hasSlowConnection() {
     return false;
 }
 
-function presist(value, usePrevious, equal) {
+function persist(src, equal) {
     // linkedSignal allows us to access previous source value
     const persisted = linkedSignal({
-        source: () => {
-            return {
-                value: value(),
-                usePrevious: usePrevious(),
-            };
-        },
-        computation: (source, prev) => {
-            if (source.usePrevious && prev)
+        source: () => src(),
+        computation: (next, prev) => {
+            if (next === undefined && prev !== undefined)
                 return prev.value;
-            return source.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 value) {
-        persisted.set = value.set;
-        persisted.update = value.update;
-        persisted.asReadonly = value.asReadonly;
+    if ('set' in src) {
+        persisted.set = src.set;
+        persisted.update = src.update;
+        persisted.asReadonly = src.asReadonly;
     }
     return persisted;
 }
-function persistResourceValues(resource, persist = false, equal) {
-    if (!persist)
+function persistResourceValues(resource, shouldPersist = false, equal) {
+    if (!shouldPersist)
         return resource;
     return {
         ...resource,
-        statusCode: presist(resource.statusCode, resource.isLoading),
-        headers: presist(resource.headers, resource.isLoading),
-        value: presist(resource.value, resource.isLoading, equal),
+        statusCode: persist(resource.statusCode),
+        headers: persist(resource.headers),
+        value: persist(resource.value, equal),
     };
 }
 
@@ -770,11 +1269,44 @@ function retryOnError(res, opt) {
     };
 }
 
+class ResourceSensors {
+    networkStatus = sensor('networkStatus');
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: ResourceSensors, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: ResourceSensors, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: ResourceSensors, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+function injectNetworkStatus() {
+    return inject(ResourceSensors).networkStatus;
+}
+
+function toResourceObject(res) {
+    return {
+        asReadonly: () => res.asReadonly(),
+        destroy: () => res.destroy(),
+        error: res.error,
+        headers: res.headers,
+        isLoading: res.isLoading,
+        progress: res.progress,
+        status: res.status,
+        statusCode: res.statusCode,
+        value: res.value,
+        reload: () => res.reload(),
+        hasValue: (() => res.hasValue()),
+        set: (v) => res.set(v),
+        update: (v) => res.update(v),
+    };
+}
+
 function normalizeParams(params) {
     if (params instanceof HttpParams)
         return params.toString();
     const paramMap = new Map();
-    for (const [key, value] of entries(params)) {
+    for (const [key, value] of Object.entries(params)) {
         if (Array.isArray(value)) {
             paramMap.set(key, value.map(encodeURIComponent).join(','));
         }
@@ -783,6 +1315,7 @@ function normalizeParams(params) {
         }
     }
     return Array.from(paramMap.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
         .map(([key, value]) => `${key}=${value}`)
         .join('&');
 }
@@ -799,13 +1332,26 @@ function queryResource(request, options) {
         : inject(DestroyRef);
     const cb = createCircuitBreaker(options?.circuitBreaker === true
         ? undefined
-        : (options?.circuitBreaker ?? false));
+        : (options?.circuitBreaker ?? false), options?.injector);
+    const networkAvailable = injectNetworkStatus();
+    const eq = options?.triggerOnSameRequest
+        ? undefined
+        : createEqualRequest(options?.equal);
     const stableRequest = computed(() => {
-        if (cb.isClosed())
+        if (!networkAvailable() || cb.isOpen())
+            return undefined;
+        const req = request();
+        if (!req)
             return undefined;
-        return request() ?? undefined;
+        if (typeof req === 'string')
+            return { method: 'GET', url: req };
+        return req;
     }, {
-        equal: createEqualRequest(options?.equal),
+        equal: (a, b) => {
+            if (eq)
+                return eq(a, b);
+            return a === b;
+        },
     });
     const hashFn = typeof options?.cache === 'object'
         ? (options.cache.hash ?? urlWithParams)
@@ -818,6 +1364,11 @@ function queryResource(request, options) {
             return null;
         return hashFn(r);
     });
+    const bustBrowserCache = typeof options?.cache === 'object' &&
+        options.cache.bustBrowserCache === true;
+    const ignoreCacheControl = typeof options?.cache === 'object' &&
+        options.cache.ignoreCacheControl === true;
+    const persist = typeof options?.cache === 'object' && options.cache.persist === true;
     const cachedRequest = options?.cache
         ? computed(() => {
             const r = stableRequest();
@@ -829,31 +1380,39 @@ function queryResource(request, options) {
                     staleTime,
                     ttl,
                     key: cacheKey() ?? hashFn(r),
+                    bustBrowserCache,
+                    ignoreCacheControl,
+                    persist,
                 }),
             };
         })
         : stableRequest;
-    let resource = httpResource(cachedRequest, {
+    let resource = toResourceObject(httpResource(cachedRequest, {
         ...options,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         parse: options?.parse, // Not my favorite thing to do, but here it is completely safe.
-    });
+    }));
+    resource = catchValueError(resource, options?.defaultValue);
     // get full HttpResonse from Cache
-    const cachedEvent = cache.get(cacheKey);
-    const parse = options?.parse ?? ((val) => val);
-    const actualCacheValue = computed(() => {
-        const ce = cachedEvent();
-        if (!ce || !(ce.value instanceof HttpResponse))
-            return;
-        return parse(ce.value.body);
-    });
-    // retains last cache value after it is invalidated for lifetime of resource
-    const cachedValue = linkedSignal({
-        source: () => actualCacheValue(),
-        computation: (source, prev) => {
-            if (!source && prev)
+    const cachedEvent = cache.getEntryOrKey(cacheKey);
+    const cacheEntry = linkedSignal({
+        source: () => cachedEvent(),
+        computation: (entry, prev) => {
+            if (!entry)
+                return null;
+            if (typeof entry === 'string' &&
+                prev &&
+                prev.value !== null &&
+                prev.value.key === entry) {
                 return prev.value;
-            return source;
+            }
+            if (typeof entry === 'string')
+                return { key: entry, value: null };
+            if (!(entry.value instanceof HttpResponse))
+                return { key: entry.key, value: null };
+            return {
+                value: entry.value.body,
+                key: entry.key,
+            };
         },
     });
     resource = refresh(resource, destroyRef, options?.refresh);
@@ -861,7 +1420,8 @@ function queryResource(request, options) {
     resource = persistResourceValues(resource, options?.keepPrevious, options?.equal);
     const value = options?.cache
         ? toWritable(computed(() => {
-            return cachedValue() ?? resource.value();
+            resource.value();
+            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
@@ -882,7 +1442,7 @@ function queryResource(request, options) {
     const cbEffectRef = effect(() => {
         const status = resource.status();
         if (status === ResourceStatus.Error)
-            cb.fail();
+            cb.fail(untracked(resource.error));
         else if (status === ResourceStatus.Resolved)
             cb.success();
     });
@@ -894,7 +1454,7 @@ function queryResource(request, options) {
                 body: value,
                 status: 200,
                 statusText: 'OK',
-            }));
+            }), staleTime, ttl, persist);
     };
     const update = (updater) => {
         set(updater(untracked(resource.value)));
@@ -907,7 +1467,9 @@ function queryResource(request, options) {
         value,
         set,
         update,
-        disabled: computed(() => cb.isClosed() || stableRequest() === undefined),
+        statusCode: linkedSignal(resource.statusCode),
+        headers: linkedSignal(resource.headers),
+        disabled: computed(() => cb.isOpen() || stableRequest() === undefined),
         reload: () => {
             cb.halfOpen(); // open the circuit for manual reload
             return resource.reload();
@@ -920,16 +1482,35 @@ function queryResource(request, options) {
         prefetch: async (partial) => {
             if (!options?.cache || hasSlowConnection())
                 return Promise.resolve();
-            const request = untracked(cachedRequest);
-            if (!request)
-                return Promise.resolve();
+            const request = untracked(stableRequest);
+            const partialReq = typeof partial === 'string' ? { method: 'GET', url: partial } : partial;
             const prefetchRequest = {
                 ...request,
-                ...partial,
+                ...partialReq,
             };
+            if (!prefetchRequest.url)
+                return Promise.resolve();
+            const key = hashFn({
+                ...prefetchRequest,
+                url: prefetchRequest.url ?? '',
+            });
+            const found = cache.getUntracked(key);
+            if (found && !found.isStale)
+                return Promise.resolve();
             try {
                 await firstValueFrom(client.request(prefetchRequest.method ?? 'GET', prefetchRequest.url, {
                     ...prefetchRequest,
+                    context: setCacheContext(prefetchRequest.context, {
+                        staleTime,
+                        ttl,
+                        key: hashFn({
+                            ...prefetchRequest,
+                            url: prefetchRequest.url ?? '',
+                        }),
+                        bustBrowserCache,
+                        ignoreCacheControl,
+                        persist,
+                    }),
                     headers: prefetchRequest.headers,
                     observe: 'response',
                 }));
@@ -944,6 +1525,46 @@ function queryResource(request, options) {
     };
 }
 
+function manualQueryResource(request, options) {
+    const trigger = signal({ epoch: 0 }, {
+        equal: (a, b) => a.epoch === b.epoch,
+    });
+    const injector = options?.injector ?? inject(Injector);
+    const req = computed(() => {
+        const state = trigger();
+        if (state.epoch === 0)
+            return;
+        if (state.override)
+            return state.override;
+        return untracked(request);
+    }, {
+        equal: () => false,
+    });
+    const resource = queryResource(req, options);
+    return {
+        ...resource,
+        trigger: (override, injectorOverride) => {
+            trigger.update((s) => ({
+                epoch: s.epoch + 1,
+                override,
+            }));
+            return new Promise((res, rej) => {
+                const watcher = nestedEffect(() => {
+                    const status = resource.status();
+                    if (status === ResourceStatus.Resolved) {
+                        watcher.destroy();
+                        res(untracked(resource.value));
+                    }
+                    else if (status === ResourceStatus.Error) {
+                        watcher.destroy();
+                        rej(untracked(resource.error));
+                    }
+                }, { injector: injectorOverride ?? injector });
+            });
+        },
+    };
+}
+
 /**
  * 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.
@@ -951,96 +1572,124 @@ function queryResource(request, options) {
  * 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.  Unlike `queryResource`, the `body` property
- *               of the request is provided when `mutate` is called, *not* here.  If the
- *               function returns `undefined`, the mutation is considered "disabled." All properties,
- *               except the body, can be set here.
+ * @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`.
+ * @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.
  */
 function mutationResource(request, options = {}) {
     const { onMutate, onError, onSuccess, onSettled, equal, ...rest } = options;
     const requestEqual = createEqualRequest(equal);
-    const baseRequest = computed(() => request() ?? undefined, {
-        equal: requestEqual,
-    });
-    const nextRequest = signal(null, {
+    const eq = equal ?? Object.is;
+    const next = signal(null, {
         equal: (a, b) => {
             if (!a && !b)
                 return true;
             if (!a || !b)
                 return false;
-            return requestEqual(a, b);
+            return eq(a, b);
         },
     });
+    const queue = signal([]);
+    let ctx = undefined;
+    const queueRef = effect(() => {
+        const nextInQueue = queue().at(0);
+        if (!nextInQueue || next() !== null)
+            return;
+        queue.update((q) => q.slice(1));
+        const [value, ictx] = nextInQueue;
+        ctx = onMutate?.(value, ictx);
+        next.set(value);
+    });
     const req = computed(() => {
-        const nr = nextRequest();
+        const nr = next();
         if (!nr)
             return;
-        const base = baseRequest();
-        const url = nr.url ?? base?.url;
-        if (!url)
+        return request(nr) ?? undefined;
+    }, {
+        equal: requestEqual,
+    });
+    const lastValue = linkedSignal({
+        source: next,
+        computation: (next, prev) => {
+            if (next === null && !!prev)
+                return prev.value;
+            return next;
+        },
+    });
+    const lastValueRequest = computed(() => {
+        const nr = lastValue();
+        if (!nr)
             return;
-        const method = nr.method ?? base?.method;
-        return {
-            ...base,
-            ...nr,
-            url,
-            method,
-        };
+        return request(nr) ?? undefined;
+    }, {
+        equal: requestEqual,
     });
+    const cb = createCircuitBreaker(options?.circuitBreaker === true
+        ? undefined
+        : (options?.circuitBreaker ?? false), options?.injector);
     const resource = queryResource(req, {
         ...rest,
+        circuitBreaker: cb,
         defaultValue: null, // doesnt matter since .value is not accessible
     });
-    let ctx = undefined;
     const destroyRef = options.injector
         ? options.injector.get(DestroyRef)
         : inject(DestroyRef);
     const error$ = toObservable(resource.error);
-    const value$ = toObservable(resource.value);
+    const value$ = toObservable(resource.value).pipe(catchError(() => of(null)));
     const statusSub = toObservable(resource.status)
         .pipe(combineLatestWith(error$, value$), map(([status, error, value]) => {
         if (status === ResourceStatus.Error && error) {
             return {
-                status: ResourceStatus.Error,
+                status: 'error',
                 error,
             };
         }
         if (status === ResourceStatus.Resolved && value !== null) {
             return {
-                status: ResourceStatus.Resolved,
+                status: 'resolved',
                 value,
             };
         }
         return null;
     }), filter((v) => v !== null), takeUntilDestroyed(destroyRef))
         .subscribe((result) => {
-        if (result.status === ResourceStatus.Error)
+        if (result.status === 'error')
             onError?.(result.error, ctx);
         else
             onSuccess?.(result.value, ctx);
         onSettled?.(ctx);
         ctx = undefined;
-        nextRequest.set(null);
+        next.set(null);
     });
+    const shouldQueue = options.queue ?? false;
     return {
         ...resource,
         destroy: () => {
             statusSub.unsubscribe();
             resource.destroy();
+            queueRef.destroy();
         },
         mutate: (value, ictx) => {
-            ctx = onMutate?.(value.body, ictx);
-            nextRequest.set(value);
+            if (shouldQueue) {
+                return queue.update((q) => [...q, [value, ictx]]);
+            }
+            else {
+                ctx = onMutate?.(value, ictx);
+                next.set(value);
+            }
         },
-        current: nextRequest,
+        current: next,
+        // redeclare disabled with last value so that it is not affected by the resource's internal disablement logic
+        disabled: computed(() => cb.isOpen() || lastValueRequest() === undefined),
     };
 }
 
@@ -1048,5 +1697,5 @@ function mutationResource(request, options = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, mutationResource, noDedupe, provideQueryCache, queryResource };
+export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
 //# sourceMappingURL=mmstack-resource.mjs.map