@mmstack/resource 21.1.1 → 21.1.2

package/fesm2022/mmstack-resource.mjs

@@ -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') {
@@ -239,7 +245,7 @@ class Cache {
     }
     /** @internal */
     getInternal(key) {
-        const keySignal = computed(() => key(), ...(ngDevMode ? [{ debugName: "keySignal" }] : []));
+        const keySignal = computed(() => key(), ...(ngDevMode ? [{ debugName: "keySignal" }] : /* istanbul ignore next */ []));
         return computed(() => {
             const key = keySignal();
             if (!key)
@@ -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)
@@ -683,7 +714,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;
@@ -702,6 +735,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
@@ -729,22 +773,23 @@ 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) {
-    const halfOpen = signal(false, ...(ngDevMode ? [{ debugName: "halfOpen" }] : []));
-    const failureCount = signal(0, ...(ngDevMode ? [{ debugName: "failureCount" }] : []));
+function internalCeateCircuitBreaker(threshold = 5, resetTimeout = 30000, shouldFail = () => true, shouldFailForever = () => false) {
+    const halfOpen = signal(false, ...(ngDevMode ? [{ debugName: "halfOpen" }] : /* istanbul ignore next */ []));
+    const failureCount = signal(0, ...(ngDevMode ? [{ debugName: "failureCount" }] : /* istanbul ignore next */ []));
+    const failedForever = signal(false, ...(ngDevMode ? [{ debugName: "failedForever" }] : /* istanbul ignore next */ []));
     const status = computed(() => {
-        if (failureCount() >= treshold)
+        if (failedForever() || failureCount() >= threshold)
             return 'OPEN';
         return halfOpen() ? 'HALF_OPEN' : 'CLOSED';
-    }, ...(ngDevMode ? [{ debugName: "status" }] : []));
-    const isClosed = computed(() => status() !== 'OPEN', ...(ngDevMode ? [{ debugName: "isClosed" }] : []));
-    const isOpen = computed(() => status() !== 'CLOSED', ...(ngDevMode ? [{ debugName: "isOpen" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+    const isClosed = computed(() => status() !== 'OPEN', ...(ngDevMode ? [{ debugName: "isClosed" }] : /* istanbul ignore next */ []));
+    const isOpen = computed(() => status() !== 'CLOSED', ...(ngDevMode ? [{ debugName: "isOpen" }] : /* istanbul ignore next */ []));
     const success = () => {
         failureCount.set(0);
         halfOpen.set(false);
@@ -753,30 +798,26 @@ 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" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "effectRef" }] : /* istanbul ignore next */ []));
     const failInternal = () => {
         failureCount.set(failureCount() + 1);
         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))
@@ -785,6 +826,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,
@@ -792,6 +838,7 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         fail,
         success,
         halfOpen: tryOnce,
+        hardReset,
         destroy: () => effectRef.destroy(),
     };
 }
@@ -810,18 +857,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),
         },
     };
 }
@@ -830,12 +902,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.
  *
@@ -858,11 +941,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
@@ -1179,7 +1262,7 @@ function hasSlowConnection() {
 
 function persist(src, equal) {
     // linkedSignal allows us to access previous source value
-    const persisted = linkedSignal({ ...(ngDevMode ? { debugName: "persisted" } : {}), source: () => src(),
+    const persisted = linkedSignal({ ...(ngDevMode ? { debugName: "persisted" } : /* istanbul ignore next */ {}), source: () => src(),
         computation: (next, prev) => {
             if (next === undefined && prev !== undefined)
                 return prev.value;
@@ -1233,13 +1316,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)
@@ -1254,11 +1340,11 @@ function retryOnError(res, opt) {
     const ref = effect(() => {
         switch (res.status()) {
             case 'error':
-                return onError();
+                return handleError();
             case 'resolved':
                 return onSuccess();
         }
-    }, ...(ngDevMode ? [{ debugName: "ref" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "ref" }] : /* istanbul ignore next */ []));
     return {
         ...res,
         destroy: () => {
@@ -1270,10 +1356,10 @@ function retryOnError(res, opt) {
 
 class ResourceSensors {
     networkStatus = sensor('networkStatus');
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: ResourceSensors, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: ResourceSensors, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: ResourceSensors, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: ResourceSensors, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: ResourceSensors, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: ResourceSensors, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -1337,16 +1423,26 @@ function queryResource(request, options) {
     const eq = options?.triggerOnSameRequest
         ? undefined
         : createEqualRequest(options?.equal);
+    const rawRequest = computed(() => request() ?? undefined, ...(ngDevMode ? [{ debugName: "rawRequest" }] : /* istanbul ignore next */ []));
+    const disabledReason = computed(() => {
+        if (!networkAvailable())
+            return 'offline';
+        if (cb.isOpen())
+            return 'circuit-open';
+        if (!rawRequest())
+            return 'no-request';
+        return null;
+    }, ...(ngDevMode ? [{ debugName: "disabledReason" }] : /* istanbul ignore next */ []));
     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')
             return { method: 'GET', url: req };
         return req;
-    }, { ...(ngDevMode ? { debugName: "stableRequest" } : {}), equal: (a, b) => {
+    }, { ...(ngDevMode ? { debugName: "stableRequest" } : /* istanbul ignore next */ {}), equal: (a, b) => {
             if (eq)
                 return eq(a, b);
             return a === b;
@@ -1361,7 +1457,7 @@ function queryResource(request, options) {
         if (!r)
             return null;
         return hashFn(r);
-    }, ...(ngDevMode ? [{ debugName: "cacheKey" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "cacheKey" }] : /* istanbul ignore next */ []));
     const bustBrowserCache = typeof options?.cache === 'object' &&
         options.cache.bustBrowserCache === true;
     const ignoreCacheControl = typeof options?.cache === 'object' &&
@@ -1392,7 +1488,7 @@ function queryResource(request, options) {
     resource = catchValueError(resource, options?.defaultValue);
     // get full HttpResonse from Cache
     const cachedEvent = cache.getEntryOrKey(cacheKey);
-    const cacheEntry = linkedSignal({ ...(ngDevMode ? { debugName: "cacheEntry" } : {}), source: () => cachedEvent(),
+    const cacheEntry = linkedSignal({ ...(ngDevMode ? { debugName: "cacheEntry" } : /* istanbul ignore next */ {}), source: () => cachedEvent(),
         computation: (entry, prev) => {
             if (!entry)
                 return null;
@@ -1412,7 +1508,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(() => {
@@ -1420,20 +1516,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();
@@ -1441,7 +1523,7 @@ function queryResource(request, options) {
             cb.fail(untracked(resource.error));
         else if (status === 'resolved')
             cb.success();
-    }, ...(ngDevMode ? [{ debugName: "cbEffectRef" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "cbEffectRef" }] : /* istanbul ignore next */ []));
     const set = (value) => {
         resource.value.set(value);
         const k = untracked(cacheKey);
@@ -1465,7 +1547,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();
@@ -1528,7 +1611,7 @@ function queryResource(request, options) {
 }
 
 function manualQueryResource(request, options) {
-    const trigger = signal({ epoch: 0 }, { ...(ngDevMode ? { debugName: "trigger" } : {}), equal: (a, b) => a.epoch === b.epoch });
+    const trigger = signal({ epoch: 0 }, { ...(ngDevMode ? { debugName: "trigger" } : /* istanbul ignore next */ {}), equal: (a, b) => a.epoch === b.epoch });
     const injector = options?.injector ?? inject(Injector);
     const req = computed(() => {
         const state = trigger();
@@ -1537,7 +1620,7 @@ function manualQueryResource(request, options) {
         if (state.override)
             return state.override;
         return untracked(request);
-    }, { ...(ngDevMode ? { debugName: "req" } : {}), equal: () => false });
+    }, { ...(ngDevMode ? { debugName: "req" } : /* istanbul ignore next */ {}), equal: () => false });
     const resource = queryResource(req, options);
     return {
         ...resource,
@@ -1586,14 +1669,14 @@ function mutationResource(request, options = {}) {
     const { onMutate, onError, onSuccess, onSettled, equal, ...rest } = options;
     const requestEqual = createEqualRequest(equal);
     const eq = equal ?? Object.is;
-    const next = signal(null, { ...(ngDevMode ? { debugName: "next" } : {}), equal: (a, b) => {
+    const next = signal(null, { ...(ngDevMode ? { debugName: "next" } : /* istanbul ignore next */ {}), equal: (a, b) => {
             if (!a && !b)
                 return true;
             if (!a || !b)
                 return false;
             return eq(a, b);
         } });
-    const queue = signal([], ...(ngDevMode ? [{ debugName: "queue" }] : []));
+    const queue = signal([], ...(ngDevMode ? [{ debugName: "queue" }] : /* istanbul ignore next */ []));
     let ctx = undefined;
     const queueRef = effect(() => {
         const nextInQueue = queue().at(0);
@@ -1603,14 +1686,14 @@ function mutationResource(request, options = {}) {
         const [value, ictx] = nextInQueue;
         ctx = onMutate?.(value, ictx);
         next.set(value);
-    }, ...(ngDevMode ? [{ debugName: "queueRef" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "queueRef" }] : /* istanbul ignore next */ []));
     const req = computed(() => {
         const nr = next();
         if (!nr)
             return;
         return request(nr) ?? undefined;
-    }, { ...(ngDevMode ? { debugName: "req" } : {}), equal: requestEqual });
-    const lastValue = linkedSignal({ ...(ngDevMode ? { debugName: "lastValue" } : {}), source: next,
+    }, { ...(ngDevMode ? { debugName: "req" } : /* istanbul ignore next */ {}), equal: requestEqual });
+    const lastValue = linkedSignal({ ...(ngDevMode ? { debugName: "lastValue" } : /* istanbul ignore next */ {}), source: next,
         computation: (next, prev) => {
             if (next === null && !!prev)
                 return prev.value;
@@ -1621,7 +1704,7 @@ function mutationResource(request, options = {}) {
         if (!nr)
             return;
         return request(nr) ?? undefined;
-    }, { ...(ngDevMode ? { debugName: "lastValueRequest" } : {}), equal: requestEqual });
+    }, { ...(ngDevMode ? { debugName: "lastValueRequest" } : /* istanbul ignore next */ {}), equal: requestEqual });
     const cb = createCircuitBreaker(options?.circuitBreaker === true
         ? undefined
         : (options?.circuitBreaker ?? false), options?.injector);