@mmstack/resource 20.5.0 → 20.5.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') {
@@ -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)
@@ -682,7 +713,9 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
             });
         }
         return next(req).pipe(tap((event) => {
-            if (event instanceof HttpResponse && event.ok) {
+            if (!(event instanceof HttpResponse))
+                return;
+            if (event.ok) {
                 const cacheControl = parseCacheControlHeader(event);
                 if (cacheControl.noStore && !opt.ignoreCacheControl)
                     return;
@@ -701,6 +734,17 @@ function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']) {
                     })
                     : event;
                 cache.store(key, parsedResponse, staleTime, ttl, opt.persist);
+                return;
+            }
+            // 304 → server confirmed our cached entry is still valid. Re-stamp the
+            // existing entry so subsequent reads within the new freshness window
+            // don't trigger another revalidation round-trip.
+            if (event.status === 304 && entry) {
+                const cacheControl = parseCacheControlHeader(event);
+                const { staleTime, ttl } = opt.ignoreCacheControl
+                    ? opt
+                    : resolveTimings(cacheControl, opt.staleTime, opt.ttl);
+                cache.store(key, entry.value, staleTime, ttl, opt.persist);
             }
         }), map((event) => {
             // handle 304 responses due to eTag/last-modified
@@ -728,17 +772,18 @@ function catchValueError(resource, fallback) {
 
 /** @internal */
 const DEFAULT_OPTIONS = {
-    treshold: 5,
+    threshold: 5,
     timeout: 30000,
     shouldFail: () => true,
     shouldFailForever: () => false,
 };
 /** @internal */
-function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldFail = () => true, shouldFailForever = () => false) {
+function internalCeateCircuitBreaker(threshold = 5, resetTimeout = 30000, shouldFail = () => true, shouldFailForever = () => false) {
     const halfOpen = signal(false, ...(ngDevMode ? [{ debugName: "halfOpen" }] : []));
     const failureCount = signal(0, ...(ngDevMode ? [{ debugName: "failureCount" }] : []));
+    const failedForever = signal(false, ...(ngDevMode ? [{ debugName: "failedForever" }] : []));
     const status = computed(() => {
-        if (failureCount() >= treshold)
+        if (failedForever() || failureCount() >= threshold)
             return 'OPEN';
         return halfOpen() ? 'HALF_OPEN' : 'CLOSED';
     }, ...(ngDevMode ? [{ debugName: "status" }] : []));
@@ -752,17 +797,17 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         if (!untracked(isOpen))
             return;
         halfOpen.set(true);
-        failureCount.set(treshold - 1);
+        failureCount.set(threshold - 1);
     };
-    let failForeverResetId = null;
+    // Auto-probe effect: schedules a half-open retry after `resetTimeout` whenever
+    // the breaker is open, *unless* we've been failed forever (in which case only
+    // hardReset() can recover).
     const effectRef = effect((cleanup) => {
-        if (!isOpen())
+        if (!isOpen() || failedForever())
             return;
         const timeout = setTimeout(tryOnce, resetTimeout);
-        failForeverResetId = timeout;
         return cleanup(() => {
             clearTimeout(timeout);
-            failForeverResetId = null;
         });
     }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
     const failInternal = () => {
@@ -770,12 +815,8 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         halfOpen.set(false);
     };
     const failForever = () => {
-        if (failForeverResetId)
-            clearTimeout(failForeverResetId);
-        effectRef.destroy();
-        failureCount.set(Infinity);
+        failedForever.set(true);
         halfOpen.set(false);
-        return;
     };
     const fail = (err) => {
         if (shouldFailForever(err))
@@ -784,6 +825,11 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
             return failInternal();
         // If the error does not trigger a failure, we do nothing.
     };
+    const hardReset = () => {
+        failedForever.set(false);
+        failureCount.set(0);
+        halfOpen.set(false);
+    };
     return {
         status,
         isClosed,
@@ -791,6 +837,7 @@ function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000, shouldF
         fail,
         success,
         halfOpen: tryOnce,
+        hardReset,
         destroy: () => effectRef.destroy(),
     };
 }
@@ -809,18 +856,43 @@ function createNeverBrokenCircuitBreaker() {
         halfOpen: () => {
             // noop
         },
+        hardReset: () => {
+            // noop
+        },
         destroy: () => {
             // noop
         },
     };
 }
 const CB_DEFAULT_OPTIONS = new InjectionToken('MMSTACK_CIRCUIT_BREAKER_DEFAULT_OPTIONS');
+/**
+ * Provides application-wide default options for {@link createCircuitBreaker}.
+ * Any `createCircuitBreaker()` call without explicit options (or with only
+ * partial options) merges these defaults in, so you can centralize threshold /
+ * timeout / failure-classifier behavior in one place.
+ *
+ * Per-call options always win over the provided defaults.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideCircuitBreakerDefaultOptions({
+ *       threshold: 10,
+ *       timeout: 60_000,
+ *       shouldFailForever: (err) =>
+ *         err instanceof HttpErrorResponse && [401, 403].includes(err.status),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 function provideCircuitBreakerDefaultOptions(options) {
     return {
         provide: CB_DEFAULT_OPTIONS,
         useValue: {
             ...DEFAULT_OPTIONS,
-            ...options,
+            ...normalizeThreshold(options),
         },
     };
 }
@@ -829,12 +901,23 @@ function injectCircuitBreakerOptions(injector = inject(Injector)) {
         optional: true,
     });
 }
+/** @internal — strips the deprecated `treshold` field and folds it into `threshold` */
+function normalizeThreshold(opt) {
+    if (!opt || typeof opt !== 'object' || 'isClosed' in opt)
+        return {};
+    const { treshold, threshold, ...rest } = opt;
+    return {
+        ...rest,
+        threshold: threshold ?? treshold,
+    };
+}
 /**
  * Creates a circuit breaker instance.
  *
  * @param options - Configuration options for the circuit breaker.  Can be:
- *   - `undefined`:  Creates a "no-op" circuit breaker that is always open (never trips).
- *   - `true`: Creates a circuit breaker with default settings (threshold: 5, timeout: 30000ms).
+ *   - `undefined`:  Uses defaults (threshold: 5, timeout: 30000ms) or provided defaults via {@link provideCircuitBreakerDefaultOptions}.
+ *   - `false`: Creates a "no-op" circuit breaker that is always closed (never trips).
+ *   - `true`: Creates a circuit breaker with default settings.
  *   - `CircuitBreaker`:  Reuses an existing `CircuitBreaker` instance.
  *   - `{ threshold?: number; timeout?: number; }`: Creates a circuit breaker with the specified threshold and timeout.
  *
@@ -857,11 +940,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
@@ -1240,13 +1323,16 @@ function refresh(resource, destroyRef, refresh) {
 }
 
 // Retry on error, if number is provided it will retry that many times with exponential backoff, otherwise it will use the options provided
-function retryOnError(res, opt) {
+function retryOnError(res, opt, onError) {
     const max = opt ? (typeof opt === 'number' ? opt : (opt.max ?? 0)) : 0;
     const backoff = typeof opt === 'object' ? (opt.backoff ?? 1000) : 1000;
     let retries = 0;
     let timeout;
-    const onError = () => {
-        if (retries >= max)
+    const handleError = () => {
+        const err = untracked(res.error);
+        const isFinal = retries >= max;
+        onError?.(err, retries, isFinal);
+        if (isFinal)
             return;
         retries++;
         if (timeout)
@@ -1261,7 +1347,7 @@ function retryOnError(res, opt) {
     const ref = effect(() => {
         switch (res.status()) {
             case 'error':
-                return onError();
+                return handleError();
             case 'resolved':
                 return onSuccess();
         }
@@ -1343,10 +1429,20 @@ function queryResource(request, options) {
     const eq = options?.triggerOnSameRequest
         ? undefined
         : createEqualRequest(options?.equal);
+    const rawRequest = computed(() => request() ?? undefined, ...(ngDevMode ? [{ debugName: "rawRequest" }] : []));
+    const disabledReason = computed(() => {
+        if (!networkAvailable())
+            return 'offline';
+        if (cb.isOpen())
+            return 'circuit-open';
+        if (!rawRequest())
+            return 'no-request';
+        return null;
+    }, ...(ngDevMode ? [{ debugName: "disabledReason" }] : []));
     const stableRequest = computed(() => {
-        if (!networkAvailable() || cb.isOpen())
+        if (disabledReason() !== null)
             return undefined;
-        const req = request();
+        const req = rawRequest();
         if (!req)
             return undefined;
         if (typeof req === 'string')
@@ -1444,7 +1540,7 @@ function queryResource(request, options) {
             },
         }]));
     resource = refresh(resource, destroyRef, options?.refresh);
-    resource = retryOnError(resource, options?.retry);
+    resource = retryOnError(resource, options?.retry, options?.onError);
     resource = persistResourceValues(resource, options?.keepPrevious, options?.equal);
     const value = options?.cache
         ? toWritable(computed(() => {
@@ -1452,20 +1548,6 @@ function queryResource(request, options) {
             return cacheEntry()?.value ?? resource.value();
         }), resource.value.set, resource.value.update)
         : resource.value;
-    const onError = options?.onError; // Put in own variable to ensure value remains even if options are somehow mutated in-line
-    if (onError) {
-        const onErrorRef = effect(() => {
-            const err = resource.error();
-            if (err)
-                onError(err);
-        }, ...(ngDevMode ? [{ debugName: "onErrorRef" }] : []));
-        // cleanup on manual destroy, I'm comfortable setting these props in-line as we have yet to 'release' the object out of this lexical scope
-        const destroyRest = resource.destroy;
-        resource.destroy = () => {
-            onErrorRef.destroy();
-            destroyRest();
-        };
-    }
     // iterate circuit breaker state, is effect as a computed would cause a circular dependency (resource -> cb -> resource)
     const cbEffectRef = effect(() => {
         const status = resource.status();
@@ -1497,7 +1579,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();