@mmstack/resource 19.0.0

package/fesm2022/mmstack-resource.mjs

@@ -0,0 +1,1049 @@
+import { computed, untracked, InjectionToken, inject, isDevMode, signal, effect, linkedSignal, ResourceStatus, DestroyRef } from '@angular/core';
+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';
+
+const ONE_DAY = 1000 * 60 * 60 * 24;
+const ONE_HOUR = 1000 * 60 * 60;
+const DEFAULT_CLEANUP_OPT = {
+    type: 'lru',
+    maxSize: 200,
+    checkInterval: ONE_HOUR,
+};
+/**
+ * A generic cache implementation that stores data with time-to-live (TTL) and stale-while-revalidate capabilities.
+ *
+ * @typeParam T - The type of data to be stored in the cache.
+ */
+class Cache {
+    ttl;
+    staleTime;
+    internal = mutable(new Map());
+    cleanupOpt;
+    /**
+     * Creates a new `Cache` instance.
+     *
+     * @param ttl - The default Time To Live (TTL) for cache entries, in milliseconds.  Defaults to one day.
+     * @param staleTime - The default duration, in milliseconds, during which a cache entry is considered
+     *                    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.
+     */
+    constructor(ttl = ONE_DAY, staleTime = ONE_HOUR, cleanupOpt = {
+        type: 'lru',
+        maxSize: 1000,
+        checkInterval: ONE_HOUR,
+    }) {
+        this.ttl = ttl;
+        this.staleTime = staleTime;
+        this.cleanupOpt = {
+            ...DEFAULT_CLEANUP_OPT,
+            ...cleanupOpt,
+        };
+        if (this.cleanupOpt.maxSize <= 0)
+            throw new Error('maxSize must be greater than 0');
+        // cleanup cache based on provided options regularly
+        const cleanupInterval = setInterval(() => {
+            this.cleanup();
+        }, cleanupOpt.checkInterval);
+        const destroyId = v7();
+        // 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);
+            }
+        });
+        registry.register(this, destroyId);
+    }
+    /** @internal */
+    getInternal(key) {
+        const keySignal = computed(() => key());
+        return computed(() => {
+            const key = keySignal();
+            if (!key)
+                return null;
+            const found = this.internal().get(key);
+            const now = Date.now();
+            if (!found || found.expiresAt <= now)
+                return null;
+            found.useCount++;
+            return {
+                ...found,
+                isStale: found.stale <= now,
+            };
+        });
+    }
+    /**
+     * Retrieves a cache entry without affecting its usage count (for LRU).  This is primarily
+     * for internal use or debugging.
+     * @internal
+     * @param key - The key of the entry to retrieve.
+     * @returns The cache entry, or `null` if not found or expired.
+     */
+    getUntracked(key) {
+        return untracked(this.getInternal(() => key));
+    }
+    /**
+     * Retrieves a cache entry as a signal.
+     *
+     * @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 `null` if not found or expired.  The signal
+     *          updates whenever the cache entry changes (e.g., due to revalidation or expiration).
+     */
+    get(key) {
+        return this.getInternal(key);
+    }
+    /**
+     * Stores a value in the cache.
+     *
+     * @param key - The key under which to store the value.
+     * @param value - The value to store.
+     * @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) {
+        const entry = this.getUntracked(key);
+        if (entry) {
+            clearTimeout(entry.timeout); // stop invalidation
+        }
+        const prevCount = entry?.useCount ?? 0;
+        // ttl cannot be less than staleTime
+        if (ttl < staleTime)
+            staleTime = ttl;
+        const now = Date.now();
+        this.internal.mutate((map) => {
+            map.set(key, {
+                value,
+                created: entry?.created ?? now,
+                useCount: prevCount + 1,
+                stale: now + staleTime,
+                expiresAt: now + ttl,
+                timeout: setTimeout(() => this.invalidate(key), ttl),
+            });
+            return map;
+        });
+    }
+    /**
+     * Invalidates (removes) a cache entry.
+     *
+     * @param key - The key of the entry to invalidate.
+     */
+    invalidate(key) {
+        const entry = this.getUntracked(key);
+        if (!entry)
+            return;
+        clearTimeout(entry.timeout);
+        this.internal.mutate((map) => {
+            map.delete(key);
+            return map;
+        });
+    }
+    /** @internal */
+    cleanup() {
+        if (untracked(this.internal).size <= this.cleanupOpt.maxSize)
+            return;
+        const sorted = Array.from(untracked(this.internal).entries()).toSorted((a, b) => {
+            if (this.cleanupOpt.type === 'lru') {
+                return a[1].useCount - b[1].useCount; // least used first
+            }
+            else {
+                return a[1].created - b[1].created; // oldest first
+            }
+        });
+        const keepCount = Math.floor(this.cleanupOpt.maxSize / 2);
+        const removed = sorted.slice(0, sorted.length - keepCount);
+        const keep = sorted.slice(removed.length, sorted.length);
+        removed.forEach(([, e]) => {
+            clearTimeout(e.timeout);
+        });
+        this.internal.set(new Map(keep));
+    }
+}
+const CLIENT_CACHE_TOKEN = new InjectionToken('INTERNAL_CLIENT_CACHE');
+/**
+ * Provides the instance of the QueryCache for queryResource. This should probably be called
+ * in your application's root configuration, but can also be overriden with component/module providers.
+ *
+ * @param options - Optional configuration options for the cache.
+ * @returns An Angular `Provider` for the cache.
+ *
+ * @example
+ * // In your app.config.ts or AppModule providers:
+ *
+ * import { provideQueryCache } from './your-cache';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideQueryCache({
+ *       ttl: 60000, // Default TTL of 60 seconds
+ *       staleTime: 30000, // Default staleTime of 30 seconds
+ *     }),
+ *     // ... other providers
+ *   ]
+ * };
+ */
+function provideQueryCache(opt) {
+    return {
+        provide: CLIENT_CACHE_TOKEN,
+        useValue: new Cache(opt?.ttl, opt?.staleTime, opt?.cleanup),
+    };
+}
+class NoopCache extends Cache {
+    store(_, __, ___ = super.staleTime, ____ = super.ttl) {
+        // noop
+    }
+}
+/**
+ * Injects the `QueryCache` instance that is used within queryResource.
+ * Allows for direct modification of cached data, but is mostly meant for internal use.
+ *
+ * @param injector - (Optional) The injector to use.  If not provided, the current
+ *                   injection context is used.
+ * @returns The `QueryCache` instance.
+ *
+ * @example
+ * // In your component or service:
+ *
+ * import { injectQueryCache } from './your-cache';
+ *
+ * constructor() {
+ *   const cache = injectQueryCache();
+ *
+ *   const myData = cache.get(() => 'my-data-key');
+ *   if (myData() !== null) {
+ *     // ... use cached data ...
+ *   }
+ * }
+ */
+function injectQueryCache(injector) {
+    const cache = injector
+        ? injector.get(CLIENT_CACHE_TOKEN, null, {
+            optional: true,
+        })
+        : inject(CLIENT_CACHE_TOKEN, {
+            optional: true,
+        });
+    if (!cache) {
+        if (isDevMode())
+            throw new Error('Cache not provided, please add provideQueryCache() to providers array');
+        else
+            return new NoopCache();
+    }
+    return cache;
+}
+
+const CACHE_CONTEXT = new HttpContextToken(() => ({
+    cache: false,
+}));
+function setCacheContext(ctx = new HttpContext(), opt) {
+    return ctx.set(CACHE_CONTEXT, { ...opt, cache: true });
+}
+function getCacheContext(ctx) {
+    return ctx.get(CACHE_CONTEXT);
+}
+function parseCacheControlHeader(req) {
+    const header = req.headers.get('Cache-Control');
+    let sMaxAge = null;
+    const directives = {
+        noStore: false,
+        noCache: false,
+        mustRevalidate: false,
+        immutable: false,
+        maxAge: null,
+        staleWhileRevalidate: null,
+    };
+    if (!header)
+        return directives;
+    const parts = header.split(',');
+    for (const part of parts) {
+        const [unparsedKey, value] = part.trim().split('=');
+        const key = unparsedKey.trim().toLowerCase();
+        switch (key) {
+            case 'no-store':
+                directives.noStore = true;
+                break;
+            case 'no-cache':
+                directives.noCache = true;
+                break;
+            case 'must-revalidate':
+            case 'proxy-revalidate':
+                directives.mustRevalidate = true;
+                break;
+            case 'immutable':
+                directives.immutable = true;
+                break;
+            case 'max-age': {
+                if (!value)
+                    break;
+                const parsedValue = parseInt(value, 10);
+                if (!isNaN(parsedValue))
+                    directives.maxAge = parsedValue;
+                break;
+            }
+            case 's-max-age': {
+                if (!value)
+                    break;
+                const parsedValue = parseInt(value, 10);
+                if (!isNaN(parsedValue))
+                    sMaxAge = parsedValue;
+                break;
+            }
+            case 'stale-while-revalidate': {
+                if (!value)
+                    break;
+                const parsedValue = parseInt(value, 10);
+                if (!isNaN(parsedValue))
+                    directives.staleWhileRevalidate = parsedValue;
+                break;
+            }
+        }
+    }
+    // s-max-age takes precedence over max-age
+    if (sMaxAge !== null)
+        directives.maxAge = sMaxAge;
+    // if no store nothing else is relevant
+    if (directives.noStore)
+        return {
+            noStore: true,
+            noCache: false,
+            mustRevalidate: false,
+            immutable: false,
+            maxAge: null,
+            staleWhileRevalidate: null,
+        };
+    // max age does not apply to immutable resources
+    if (directives.immutable)
+        return {
+            ...directives,
+            maxAge: null,
+        };
+    return directives;
+}
+function resolveTimings(cacheControl, staleTime, ttl) {
+    const timings = {
+        staleTime,
+        ttl,
+    };
+    if (cacheControl.immutable)
+        return {
+            staleTime: Infinity,
+            ttl: Infinity,
+        };
+    // 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;
+    }
+    return timings;
+}
+/**
+ * Creates an `HttpInterceptorFn` that implements caching for HTTP requests. This interceptor
+ * checks for a caching configuration in the request's `HttpContext` (internally set by the queryResource).
+ * If caching is enabled, it attempts to retrieve responses from the cache. If a cached response
+ * is found and is not stale, it's returned directly.  If the cached response is stale, it's returned,
+ * and a background revalidation request is made.  If no cached response is found, the request
+ * is made to the server, and the response is cached according to the configured TTL and staleness.
+ * The interceptor also respects `Cache-Control` headers from the server.
+ *
+ * @param allowedMethods - An array of HTTP methods for which caching should be enabled.
+ *                        Defaults to `['GET', 'HEAD', 'OPTIONS']`.
+ *
+ * @returns An `HttpInterceptorFn` that implements the caching logic.
+ *
+ * @example
+ * // In your app.config.ts or module providers:
+ *
+ * import { provideHttpClient, withInterceptors } from '@angular/common/http';
+ * import { createCacheInterceptor } from '@mmstack/resource';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(withInterceptors([createCacheInterceptor()])),
+ *     // ... other providers
+ *   ],
+ * };
+ */
+function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
+    const CACHE_METHODS = new Set(allowedMethods);
+    return (req, next) => {
+        const cache = injectQueryCache();
+        if (!CACHE_METHODS.has(req.method))
+            return next(req);
+        const opt = getCacheContext(req.context);
+        if (!opt.cache)
+            return next(req);
+        const key = opt.key ?? req.urlWithParams;
+        const entry = cache.getUntracked(key); // null if expired or not found
+        // If the entry is not stale, return it
+        if (entry && !entry.isStale)
+            return of(entry.value);
+        // resource itself handles case of showing stale data...the request must process as this will "refresh said data"
+        const eTag = entry?.value.headers.get('ETag');
+        const lastModified = entry?.value.headers.get('Last-Modified');
+        if (eTag) {
+            req = req.clone({ setHeaders: { 'If-None-Match': eTag } });
+        }
+        if (lastModified) {
+            req = req.clone({ setHeaders: { 'If-Modified-Since': lastModified } });
+        }
+        return next(req).pipe(tap((event) => {
+            if (event instanceof HttpResponse && event.ok) {
+                const cacheControl = parseCacheControlHeader(event);
+                if (cacheControl.noStore)
+                    return;
+                const { staleTime, ttl } = resolveTimings(cacheControl, opt.staleTime, opt.ttl);
+                cache.store(key, event, staleTime, ttl);
+            }
+        }), map((event) => {
+            // handle 304 responses due to eTag/last-modified
+            if (event instanceof HttpResponse && event.status === 304 && entry) {
+                return entry.value;
+            }
+            return event;
+        }));
+    };
+}
+
+/** @internal */
+function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000) {
+    const halfOpen = signal(false);
+    const failureCount = signal(0);
+    const status = computed(() => {
+        if (failureCount() >= treshold)
+            return 'CLOSED';
+        return halfOpen() ? 'HALF_OPEN' : 'OPEN';
+    });
+    const isClosed = computed(() => status() === 'CLOSED');
+    const success = () => {
+        failureCount.set(0);
+        halfOpen.set(false);
+    };
+    const tryOnce = () => {
+        if (!untracked(isClosed))
+            return;
+        halfOpen.set(true);
+        failureCount.set(treshold - 1);
+    };
+    const effectRef = effect((cleanup) => {
+        if (!isClosed())
+            return;
+        const timeout = setTimeout(tryOnce, resetTimeout);
+        return cleanup(() => clearTimeout(timeout));
+    });
+    const fail = () => {
+        failureCount.set(failureCount() + 1);
+        halfOpen.set(false);
+    };
+    return {
+        status,
+        isClosed,
+        fail,
+        success,
+        halfOpen: tryOnce,
+        destroy: () => effectRef.destroy(),
+    };
+}
+/** @internal */
+function createNeverBrokenCircuitBreaker() {
+    return {
+        isClosed: computed(() => false),
+        status: signal('OPEN'),
+        fail: () => {
+            // noop
+        },
+        success: () => {
+            // noop
+        },
+        halfOpen: () => {
+            // noop
+        },
+        destroy: () => {
+            // noop
+        },
+    };
+}
+/**
+ * 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).
+ *   - `CircuitBreaker`:  Reuses an existing `CircuitBreaker` instance.
+ *   - `{ threshold?: number; timeout?: number; }`: Creates a circuit breaker with the specified threshold and timeout.
+ *
+ * @returns A `CircuitBreaker` instance.
+ *
+ * @example
+ * // Create a circuit breaker with default settings:
+ * const breaker = createCircuitBreaker();
+ *
+ * // Create a circuit breaker with custom settings:
+ * const customBreaker = createCircuitBreaker({ threshold: 10, timeout: 60000 });
+ *
+ * // Share a single circuit breaker instance across multiple resources:
+ * const sharedBreaker = createCircuitBreaker();
+ * const resource1 = queryResource(..., { circuitBreaker: sharedBreaker });
+ * const resource2 = mutationResource(..., { circuitBreaker: sharedBreaker });
+ */
+function createCircuitBreaker(opt) {
+    if (opt === false)
+        return createNeverBrokenCircuitBreaker();
+    if (typeof opt === 'object' && 'isClosed' in opt)
+        return opt;
+    return internalCeateCircuitBreaker(opt?.treshold, opt?.timeout);
+}
+
+// Heavily inspired by: https://dev.to/kasual1/request-deduplication-in-angular-3pd8
+const NO_DEDUPE = new HttpContextToken(() => false);
+/**
+ * Disables request deduplication for a specific HTTP request.
+ *
+ * @param ctx - The `HttpContext` to modify. If not provided, a new `HttpContext` is created.
+ * @returns The modified `HttpContext` with the `NO_DEDUPE` token set to `true`.
+ *
+ * @example
+ * // Disable deduplication for a specific POST request:
+ * const context = noDedupe();
+ * this.http.post('/api/data', payload, { context }).subscribe(...);
+ *
+ * // Disable deduplication, modifying an existing context:
+ * let context = new HttpContext();
+ * context = noDedupe(context);
+ * this.http.post('/api/data', payload, { context }).subscribe(...);
+ */
+function noDedupe(ctx = new HttpContext()) {
+    return ctx.set(NO_DEDUPE, true);
+}
+/**
+ * Creates an `HttpInterceptorFn` that deduplicates identical HTTP requests.
+ * If multiple identical requests (same URL and parameters) are made concurrently,
+ * only the first request will be sent to the server. Subsequent requests will
+ * receive the response from the first request.
+ *
+ * @param allowed - An array of HTTP methods for which deduplication should be enabled.
+ *                  Defaults to `['GET', 'DELETE', 'HEAD', 'OPTIONS']`.
+ *
+ * @returns An `HttpInterceptorFn` that implements the request deduplication logic.
+ *
+ * @example
+ * // In your app.config.ts or module providers:
+ * import { provideHttpClient, withInterceptors } from '@angular/common/http';
+ * import { createDedupeRequestsInterceptor } from './your-dedupe-interceptor';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(withInterceptors([createDedupeRequestsInterceptor()])),
+ *     // ... other providers
+ *   ],
+ * };
+ *
+ * // You can also specify which methods should be deduped
+ *  export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(withInterceptors([createDedupeRequestsInterceptor(['GET'])])), // only dedupe GET calls
+ *     // ... other providers
+ *   ],
+ * };
+ */
+function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OPTIONS']) {
+    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);
+        if (found)
+            return found;
+        const request = next(req).pipe(finalize(() => inFlight.delete(req.urlWithParams)), shareReplay());
+        inFlight.set(req.urlWithParams, request);
+        return request;
+    };
+}
+
+function equalTransferCache(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === 'boolean' || typeof b === 'boolean')
+        return a === b;
+    if (!a.includeHeaders && !b.includeHeaders)
+        return true;
+    if (!a.includeHeaders || !b.includeHeaders)
+        return false;
+    if (a.includeHeaders.length !== b.includeHeaders.length)
+        return false;
+    if (a.includeHeaders.length === 0)
+        return true;
+    const aSet = new Set(a.includeHeaders ?? []);
+    return b.includeHeaders.every((header) => aSet.has(header));
+}
+function equalParams(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)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
+function equalBody(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return hash(a) === hash(b);
+}
+function equalHeaders(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)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
+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)
+        return false;
+    return aKeys.every((key) => a[key] === b[key]);
+}
+function createEqualRequest(equalResult) {
+    const eqb = equalResult ?? equalBody;
+    return (a, b) => {
+        if (!a && !b)
+            return true;
+        if (!a || !b)
+            return false;
+        if (a.url !== b.url)
+            return false;
+        if (a.method !== b.method)
+            return false;
+        if (!equalParams(a.params, b.params))
+            return false;
+        if (!equalHeaders(a.headers, b.headers))
+            return false;
+        if (!eqb(a.body, b.body))
+            return false;
+        if (!equalContext(a.context, b.context))
+            return false;
+        if (a.withCredentials !== b.withCredentials)
+            return false;
+        if (a.reportProgress !== b.reportProgress)
+            return false;
+        if (!equalTransferCache(a.transferCache, b.transferCache))
+            return false;
+        return true;
+    };
+}
+
+function hasSlowConnection() {
+    if (window &&
+        'navigator' in window &&
+        'connection' in window.navigator &&
+        typeof window.navigator.connection === 'object' &&
+        !!window.navigator.connection &&
+        'effectiveType' in window.navigator.connection &&
+        typeof window.navigator.connection.effectiveType === 'string')
+        return window.navigator.connection.effectiveType.endsWith('2g');
+    return false;
+}
+
+function presist(value, usePrevious, equal) {
+    // linkedSignal allows us to access previous source value
+    const persisted = linkedSignal({
+        source: () => ({
+            value: value(),
+            usePrevious: usePrevious(),
+        }),
+        computation: (source, prev) => {
+            if (source.usePrevious && prev)
+                return prev.value;
+            return source.value;
+        },
+        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;
+    }
+    return persisted;
+}
+function persistResourceValues(resource, hasCachedValue, persist = false, equal) {
+    if (!persist)
+        return resource;
+    return {
+        ...resource,
+        statusCode: presist(resource.statusCode, resource.isLoading),
+        headers: presist(resource.headers, resource.isLoading),
+        value: presist(resource.value, computed(() => resource.isLoading() || !hasCachedValue()), // should show cached value if available
+        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) {
+    if (!refresh)
+        return resource; // no refresh requested
+    // 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());
+    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());
+        return hasReloaded;
+    };
+    return {
+        ...resource,
+        reload,
+        destroy: () => {
+            sub.unsubscribe();
+            resource.destroy();
+        },
+    };
+}
+
+// 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) {
+    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)
+            return;
+        retries++;
+        if (timeout)
+            clearTimeout(timeout);
+        setTimeout(() => res.reload(), retries <= 0 ? 0 : backoff * Math.pow(2, retries - 1));
+    };
+    const onSuccess = () => {
+        if (timeout)
+            clearTimeout(timeout);
+        retries = 0;
+    };
+    const ref = effect(() => {
+        switch (res.status()) {
+            case ResourceStatus.Error:
+                return onError();
+            case ResourceStatus.Resolved:
+                return onSuccess();
+        }
+    });
+    return {
+        ...res,
+        destroy: () => {
+            ref.destroy(); // cleanup on manual destroy
+            res.destroy();
+        },
+    };
+}
+
+function normalizeParams(params) {
+    if (params instanceof HttpParams)
+        return params.toString();
+    const paramMap = new Map();
+    for (const [key, value] of 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())
+        .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
+        ? options.injector.get(DestroyRef)
+        : inject(DestroyRef);
+    const cb = createCircuitBreaker(options?.circuitBreaker === true
+        ? undefined
+        : (options?.circuitBreaker ?? false));
+    const stableRequest = computed(() => {
+        if (cb.isClosed())
+            return undefined;
+        return request();
+    }, {
+        equal: createEqualRequest(options?.equal),
+    });
+    const hashFn = typeof options?.cache === 'object'
+        ? (options.cache.hash ?? urlWithParams)
+        : urlWithParams;
+    const staleTime = typeof options?.cache === 'object' ? options.cache.staleTime : 0;
+    const ttl = typeof options?.cache === 'object' ? options.cache.ttl : undefined;
+    const cacheKey = computed(() => {
+        const r = stableRequest();
+        if (!r)
+            return null;
+        return hashFn(r);
+    });
+    const cachedRequest = options?.cache
+        ? computed(() => {
+            const r = stableRequest();
+            if (!r)
+                return r;
+            return {
+                ...r,
+                context: setCacheContext(r.context, {
+                    staleTime,
+                    ttl,
+                    key: cacheKey() ?? hashFn(r),
+                }),
+            };
+        })
+        : stableRequest;
+    let resource = 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.
+    });
+    // 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 instanceof HttpResponse))
+            return;
+        return parse(ce.body);
+    });
+    // retains last cache value after it is invalidated for lifetime of resource
+    const cachedValue = linkedSignal({
+        source: () => actualCacheValue(),
+        computation: (source, prev) => {
+            if (!source && prev)
+                return prev.value;
+            return source;
+        },
+    });
+    const value = options?.cache
+        ? toWritable(computed(() => {
+            return cachedValue() ?? resource.value();
+        }), resource.value.set, resource.value.update)
+        : resource.value;
+    resource = refresh(resource, destroyRef, options?.refresh);
+    resource = retryOnError(resource, options?.retry);
+    resource = persistResourceValues({ ...resource, value }, computed(() => !!cachedValue()), options?.keepPrevious, options?.equal);
+    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);
+        });
+        // 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();
+        if (status === ResourceStatus.Error)
+            cb.fail();
+        else if (status === ResourceStatus.Resolved)
+            cb.success();
+    });
+    const set = (value) => {
+        resource.set(value);
+        const k = untracked(cacheKey);
+        if (options?.cache && k)
+            cache.store(k, new HttpResponse({
+                body: value,
+                status: 200,
+                statusText: 'OK',
+            }));
+    };
+    const update = (updater) => {
+        set(updater(untracked(resource.value)));
+    };
+    const client = options?.injector
+        ? options.injector.get(HttpClient)
+        : inject(HttpClient);
+    return {
+        ...resource,
+        value,
+        set,
+        update,
+        disabled: computed(() => cb.isClosed() || stableRequest() === undefined),
+        reload: () => {
+            cb.halfOpen(); // open the circuit for manual reload
+            return resource.reload();
+        },
+        destroy: () => {
+            cbEffectRef.destroy();
+            cb.destroy();
+            resource.destroy();
+        },
+        prefetch: async (partial) => {
+            if (!options?.cache || hasSlowConnection())
+                return Promise.resolve();
+            const request = untracked(cachedRequest);
+            if (!request)
+                return Promise.resolve();
+            const prefetchRequest = {
+                ...request,
+                ...partial,
+            };
+            try {
+                await firstValueFrom(client.request(prefetchRequest.method ?? 'GET', prefetchRequest.url, {
+                    ...prefetchRequest,
+                    headers: prefetchRequest.headers,
+                    observe: 'response',
+                }));
+                return;
+            }
+            catch (err) {
+                if (isDevMode())
+                    console.error('Prefetch failed: ', err);
+                return;
+            }
+        },
+    };
+}
+
+/**
+ * Creates a resource for performing mutations (e.g., POST, PUT, PATCH, DELETE requests).
+ * Unlike `queryResource`, `mutationResource` is designed for one-off operations that change data.
+ * It does *not* cache responses and does not provide a `value` signal.  Instead, it focuses on
+ * managing the mutation lifecycle (pending, error, success) and provides callbacks for handling
+ * these states.
+ *
+ * @param request A function that returns the base `HttpResourceRequest` to be made.  This
+ *               function is called reactively.  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 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 TCTX - The type of the context value returned by `onMutate`.
+ * @returns A `MutationResourceRef` instance, which provides methods for triggering the mutation
+ *          and observing its status.
+ */
+function mutationResource(request, options = {}) {
+    const equal = createEqualRequest(options?.equal);
+    const baseRequest = computed(() => request(), {
+        equal,
+    });
+    const nextRequest = signal(null, {
+        equal: (a, b) => {
+            if (!a && !b)
+                return true;
+            if (!a || !b)
+                return false;
+            return equal(a, b);
+        },
+    });
+    const req = computed(() => {
+        const nr = nextRequest();
+        if (!nr)
+            return;
+        const base = baseRequest();
+        const url = base?.url ?? nr.url;
+        if (!url)
+            return;
+        return {
+            ...base,
+            ...nr,
+            url,
+        };
+    });
+    const { onMutate, onError, onSuccess, onSettled, ...rest } = options;
+    const resource = queryResource(req, {
+        ...rest,
+        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 statusSub = toObservable(resource.status)
+        .pipe(combineLatestWith(error$, value$), map(([status, error, value]) => {
+        if (status === ResourceStatus.Error && error) {
+            return {
+                status: ResourceStatus.Error,
+                error,
+            };
+        }
+        if (status === ResourceStatus.Resolved) {
+            return {
+                status: ResourceStatus.Resolved,
+                value,
+            };
+        }
+        return null;
+    }), filter((v) => v !== null), takeUntilDestroyed(destroyRef))
+        .subscribe((result) => {
+        if (result.status === ResourceStatus.Error)
+            onError?.(result.error, ctx);
+        else
+            onSuccess?.(result.value, ctx);
+        onSettled?.(ctx);
+        ctx = undefined;
+        nextRequest.set(null);
+    });
+    return {
+        ...resource,
+        destroy: () => {
+            statusSub.unsubscribe();
+            resource.destroy();
+        },
+        mutate: (value) => {
+            ctx = onMutate?.(value.body);
+            nextRequest.set(value);
+        },
+        current: nextRequest,
+    };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, mutationResource, noDedupe, provideQueryCache, queryResource };
+//# sourceMappingURL=mmstack-resource.mjs.map