@mmstack/resource 19.3.1 → 19.3.2

package/lib/query-resource.d.ts

@@ -62,10 +62,16 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
      */
     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.
      */
@@ -80,6 +86,12 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
      */
     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").
+ */
+export type DisabledReason = 'offline' | 'circuit-open' | 'no-request';
 /**
  * Represents a resource created by `queryResource`. Extends `HttpResourceRef` with additional properties.
  */
@@ -93,9 +105,14 @@ export type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers'
      */
     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.

package/lib/util/cache/cache.d.ts

@@ -135,6 +135,24 @@ export 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;

package/lib/util/circuit-breaker.d.ts

@@ -37,6 +37,13 @@ export 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
      */
@@ -50,6 +57,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.
@@ -63,6 +74,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;
@@ -72,16 +84,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.
  */
 export 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),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 export 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.
  *

package/lib/util/retry-on-error.d.ts

@@ -3,4 +3,12 @@ export type RetryOptions = number | {
     max?: number;
     backoff?: number;
 };
-export declare function retryOnError<T>(res: HttpResourceRef<T>, opt?: RetryOptions): HttpResourceRef<T>;
+/**
+ * Callback fired by the retry wrapper for every failed attempt.
+ * `retryCount` is the number of retries that already happened before this
+ * error (`0` on the original failure, `1` after the first retry, etc.).
+ * `isFinal` is `true` when no further retry will be scheduled — either because
+ * retries are exhausted or `retry` was unset/0.
+ */
+export type RetryErrorCallback<TError = unknown> = (err: TError, retryCount: number, isFinal: boolean) => void;
+export declare function retryOnError<T>(res: HttpResourceRef<T>, opt?: RetryOptions, onError?: RetryErrorCallback): HttpResourceRef<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "19.3.1",
+  "version": "19.3.2",
   "keywords": [
     "angular",
     "signals",