@mmstack/resource 21.1.1 → 21.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "21.1.1",
+  "version": "21.2.0",
   "keywords": [
     "angular",
     "signals",
@@ -37,5 +37,6 @@
       "types": "./types/mmstack-resource.d.ts",
       "default": "./fesm2022/mmstack-resource.mjs"
     }
-  }
+  },
+  "type": "module"
 }

package/types/mmstack-resource.d.ts

@@ -1,4 +1,4 @@
-import { HttpResponse, HttpInterceptorFn, HttpContext, HttpResourceRef, HttpHeaders, HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
+import { HttpResponse, HttpInterceptorFn, HttpRequest, HttpContext, HttpResourceRef, HttpHeaders, HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
 import { Signal, Injector, Provider, WritableSignal, ValueEqualityFn } from '@angular/core';
 
 type StoredEntry<T> = Omit<CacheEntry<T>, 'timeout'>;
@@ -142,6 +142,24 @@ declare class Cache<T> {
      * @param key - The key of the entry to invalidate.
      */
     invalidate(key: string): void;
+    /**
+     * 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: string): number;
+    /**
+     * 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: (key: string) => boolean): number;
     private invalidateInternal;
     /** @internal */
     private cleanup;
@@ -295,6 +313,13 @@ type CircuitBreaker = {
      * to test if the underlying issue has been resolved after the circuit breaker has been open.
      */
     halfOpen: () => void;
+    /**
+     * Fully resets the breaker state — clears the failure count, drops the half-open
+     * flag, and lifts a permanent open caused by `shouldFailForever`. Use after the
+     * underlying condition has been resolved (e.g. user re-authenticated after a
+     * 401-triggered permanent open).
+     */
+    hardReset: () => void;
     /**
      * Destroys the circuit breaker & initiates related cleanup
      */
@@ -308,6 +333,10 @@ type CreateCircuitBreakerOptions = {
      * The number of failures that will cause the circuit breaker to open.
      * @default 5
      */
+    threshold?: number;
+    /**
+     * @deprecated Misspelled — use `threshold` instead. Kept for backwards compatibility; will be removed in a future major.
+     */
     treshold?: number;
     /**
      * The time in milliseconds after which the circuit breaker will reset and allow operations to proceed again.
@@ -321,6 +350,7 @@ type CreateCircuitBreakerOptions = {
     shouldFail?: (err?: Error) => boolean;
     /**
      * A function that determines whether an error should cause the circuit breaker to be open forever.
+     * `hardReset()` is required to lift this state.
      * @default Always returns false
      */
     shouldFailForever?: (err?: Error) => boolean;
@@ -330,16 +360,39 @@ type CreateCircuitBreakerOptions = {
  *  - `false`: Disables circuit breaker functionality (always open).
  *  - true: Creates a new circuit breaker with default options.
  *  - `CircuitBreaker`: Provides an existing `CircuitBreaker` instance to use.
- *  - `{ treshold?: number; timeout?: number; }`: Creates a new circuit breaker with the specified options.
+ *  - `{ threshold?: number; timeout?: number; }`: Creates a new circuit breaker with the specified options.
  */
 type CircuitBreakerOptions = false | CircuitBreaker | CreateCircuitBreakerOptions;
+/**
+ * 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),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 declare function provideCircuitBreakerDefaultOptions(options: CircuitBreakerOptions): Provider;
 /**
  * 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.
  *
@@ -384,6 +437,9 @@ declare function noDedupe(ctx?: HttpContext): HttpContext;
  *
  * @param allowed - An array of HTTP methods for which deduplication should be enabled.
  *                  Defaults to `['GET', 'DELETE', 'HEAD', 'OPTIONS']`.
+ * @param keyFn - Optional function to compute the dedupe key from a request.
+ *                Defaults to `hashRequest`, which includes method, URL,
+ *                response type, params, and body.
  *
  * @returns An `HttpInterceptorFn` that implements the request deduplication logic.
  *
@@ -407,7 +463,7 @@ declare function noDedupe(ctx?: HttpContext): HttpContext;
  *   ],
  * };
  */
-declare function createDedupeRequestsInterceptor(allowed?: string[]): HttpInterceptorFn;
+declare function createDedupeRequestsInterceptor(allowed?: string[], keyFn?: (req: HttpRequest<unknown>) => string): HttpInterceptorFn;
 
 type RetryOptions = number | {
     max?: number;
@@ -475,10 +531,16 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
      */
     retry?: RetryOptions;
     /**
-     * An optional error handler callback.  This function will be called whenever the
-     * underlying HTTP request fails. Useful for displaying toasts or other error messages.
+     * Called on every failed attempt, including each retry.
+     *
+     * @param err - The error from the underlying HTTP request.
+     * @param retryCount - The number of retries that already happened before
+     * this error (`0` on the original failure, `1` after the first retry, etc.).
+     * @param isFinal - `true` when no further retry will be scheduled — either
+     * because retries are exhausted or `retry` was unset/0. Branch on this for
+     * "user actually needs to know" side effects (toasts, error reporting).
      */
-    onError?: (err: unknown) => void;
+    onError?: (err: unknown, retryCount: number, isFinal: boolean) => void;
     /**
      * Options for configuring a circuit breaker for the resource.
      */
@@ -493,6 +555,12 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
      */
     triggerOnSameRequest?: boolean;
 };
+/**
+ * The reason a query resource is currently in the `disabled` state, or `null`
+ * if it is enabled. Useful for branching UI on cause (e.g. "offline" vs
+ * "circuit tripped" vs "nothing to fetch yet").
+ */
+type DisabledReason = 'offline' | 'circuit-open' | 'no-request';
 /**
  * Represents a resource created by `queryResource`. Extends `HttpResourceRef` with additional properties.
  */
@@ -506,9 +574,14 @@ type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers' | 'sta
      */
     readonly statusCode: WritableSignal<number | undefined>;
     /**
-     * A signal indicating whether the resource is currently disabled (due to circuit breaker or undefined request).
+     * A signal indicating whether the resource is currently disabled (due to circuit breaker, offline, or undefined request).
      */
     disabled: Signal<boolean>;
+    /**
+     * Why the resource is currently disabled, or `null` if it is enabled.
+     * Maps to one of: `'offline'`, `'circuit-open'`, `'no-request'`.
+     */
+    disabledReason: Signal<DisabledReason | null>;
     /**
      * Prefetches data for the resource, populating the cache if caching is enabled.  This can be
      * used to proactively load data before it's needed.  If a slow connection is detected, prefetching is skipped.
@@ -673,4 +746,4 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
 declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TMethod extends HttpResourceRequest['method'] = HttpResourceRequest['method']>(request: (params: TMutation) => Omit<NextRequest<TMethod, TMutation>, 'body'> | undefined | void, options?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
 
 export { Cache, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
-export type { ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef };
+export type { DisabledReason, ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef };