@mmstack/resource 19.6.1 → 19.6.3

package/index.d.ts

@@ -1,3 +1,4 @@
+export * from './lib/infinite-query';
 export * from './lib/manual-query';
 export * from './lib/mutation-resource';
 export * from './lib/options';

package/lib/infinite-query.d.ts

@@ -0,0 +1,81 @@
+import { type HttpResourceRequest } from '@angular/common/http';
+import { type Signal } from '@angular/core';
+import { type PAUSED, type QueryResourceOptions, type QueryResourceRef, type RequestContext } from './query-resource';
+/**
+ * Context passed to an infinite query's request fn: the {@link RequestContext}
+ * (so the fn can return `ctx.paused` to pause the resource, exactly like
+ * `queryResource`) plus the `pageParam` addressing the page to load.
+ */
+export type InfiniteRequestContext<TPageParam> = RequestContext & {
+    pageParam: TPageParam;
+};
+/**
+ * Options for {@link infiniteQueryResource}. Extends {@link QueryResourceOptions}
+ * (minus `defaultValue` — the aggregate value is always the `pages` array) with the
+ * pagination contract.
+ */
+export type InfiniteQueryResourceOptions<TPage, TRaw = TPage, TPageParam = unknown> = Omit<QueryResourceOptions<TPage, TRaw>, 'defaultValue'> & {
+    /** The page param the FIRST page is requested with (e.g. `0`, `1`, or a cursor seed). */
+    initialPageParam: TPageParam;
+    /**
+     * Derives the NEXT page's param from the freshly loaded page (and all pages so far).
+     * Return `null`/`undefined` to signal "no more pages" — `hasNextPage` flips false
+     * and `fetchNextPage()` becomes a no-op.
+     *
+     * @example
+     * // cursor-based
+     * getNextPageParam: (last) => last.nextCursor;
+     * // offset-based
+     * getNextPageParam: (last, all) => (last.items.length < PAGE_SIZE ? null : all.length);
+     */
+    getNextPageParam: (lastPage: NoInfer<TPage>, allPages: NoInfer<TPage>[]) => TPageParam | null | undefined;
+};
+/**
+ * A paginated query resource. `pages` accumulates every loaded page in order;
+ * `fetchNextPage()` loads the next one (no-op while one is in flight or when
+ * exhausted). Inherits the underlying query's `status`/`error`/`isLoading` and
+ * its features (cache, retry, circuit breaker, refresh).
+ */
+export type InfiniteQueryResourceRef<TPage> = {
+    /** Every page loaded so far, in load order. */
+    pages: Signal<TPage[]>;
+    /** `true` once the first page is in and `getNextPageParam` keeps producing params. */
+    hasNextPage: Signal<boolean>;
+    /** `true` while a page request beyond the first is in flight. */
+    isFetchingNextPage: Signal<boolean>;
+    /** The underlying query's loading state (first page + subsequent pages). */
+    isLoading: Signal<boolean>;
+    status: QueryResourceRef<TPage | undefined>['status'];
+    error: QueryResourceRef<TPage | undefined>['error'];
+    /** Loads the next page. No-op while loading or when `hasNextPage()` is false. */
+    fetchNextPage: () => void;
+    /** Reloads the CURRENT page param — the freshly loaded page replaces its slot. */
+    reload: () => boolean;
+    /** Drops all pages and refetches from `initialPageParam`. */
+    reset: () => void;
+    destroy: () => void;
+};
+/**
+ * Creates a paginated HTTP resource over {@link queryResource}: one page request at a
+ * time, accumulated into a `pages` signal — cursor- and offset-based pagination both
+ * fit through `getNextPageParam`. Each page request inherits the full queryResource
+ * feature set (caching per page, retries, circuit breaker, refresh triggers).
+ *
+ * @example
+ * ```ts
+ * const posts = infiniteQueryResource<PostPage, PostPage, number>(
+ *   ({ pageParam }) => ({ url: '/api/posts', params: { page: pageParam } }),
+ *   {
+ *     initialPageParam: 0,
+ *     getNextPageParam: (last, all) => (last.items.length < 20 ? null : all.length),
+ *     cache: true,
+ *   },
+ * );
+ *
+ * // template:
+ * // @for (page of posts.pages(); track $index) { ... }
+ * // <button (click)="posts.fetchNextPage()" [disabled]="!posts.hasNextPage()">More</button>
+ * const flat = computed(() => posts.pages().flatMap((p) => p.items));
+ * ```
+ */
+export declare function infiniteQueryResource<TPage, TRaw = TPage, TPageParam = unknown>(request: (ctx: InfiniteRequestContext<TPageParam>) => HttpResourceRequest | string | undefined | typeof PAUSED, options: InfiniteQueryResourceOptions<TPage, TRaw, TPageParam>): InfiniteQueryResourceRef<TPage>;

package/lib/mutation-resource.d.ts

@@ -36,7 +36,7 @@ type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMe
  * };
  * ```
  */
-export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TError = unknown> = Omit<QueryResourceOptions<TResult, TRaw>, 'equal' | 'onError' | 'keepPrevious' | 'refresh' | 'cache'> & {
+export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TError = unknown> = Omit<QueryResourceOptions<TResult, TRaw>, 'equal' | 'onError' | 'keepPrevious' | 'refresh' | 'cache' | 'pause'> & {
     /**
      * A callback function that is called before the mutation request is made.
      * @param value The value being mutated (the `body` of the request).
@@ -66,6 +66,25 @@ export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult
      * @default false
      */
     queue?: boolean;
+    /**
+     * Cache entries to invalidate after a SUCCESSFUL mutation — the declarative
+     * alternative to calling `injectQueryCache().invalidatePrefix(...)` in `onSuccess`.
+     *
+     * Each string is a URL prefix matched against auto-generated `GET` cache keys
+     * (`GET:${url}:...`): `'/api/posts'` invalidates `/api/posts` with any query params,
+     * plus subpaths like `/api/posts/123` — and all `varyHeaders` variants of each.
+     * Note that plain prefix matching also catches sibling paths sharing the prefix
+     * (`/api/posts-archive`); pass `'/api/posts/'` or the exact URL to narrow.
+     *
+     * Entries keyed by a custom `hash` function follow that function's shape, not the
+     * auto-key shape — invalidate those manually via `injectQueryCache().invalidateWhere`.
+     *
+     * The function form receives the mutation result and the mutated value:
+     * ```ts
+     * invalidates: (saved) => [`/api/posts`, `/api/users/${saved.authorId}`]
+     * ```
+     */
+    invalidates?: string[] | ((value: NoInfer<TResult>, mutation: NoInfer<TMutation>) => string[]);
     equal?: ValueEqualityFn<TMutation>;
 };
 /**

package/lib/options.d.ts

@@ -1,5 +1,59 @@
 import { InjectionToken, type Injector, type Provider, type ResourceRef } from '@angular/core';
 import { type CircuitBreakerOptions, type RetryOptions } from './util';
+import { type HttpResourceRequest } from '@angular/common/http';
+/**
+ * Options for enabling and configuring caching for a resource.
+ *
+ * - `true`: Enables caching with default settings.
+ * - `{ ttl?: number; staleTime?: number; hash?: (req: HttpResourceRequest) => string; }`:  Configures caching with custom settings.
+ */
+export type ResourceCacheOptions = true | {
+    /**
+     * The time-to-live for the cached value in milliseconds.
+     * After this time, the value is removed from the cache entirely.
+     * Defaults to 5 minutes (`300_000`).
+     */
+    ttl?: number;
+    /**
+     * The time in milliseconds during which the cached value is considered "fresh".
+     * If a request is made within this time, the cached value is returned immediately without a background fetch.
+     * Defaults to 0 (always stale, triggering a background fetch).
+     */
+    staleTime?: number;
+    /**
+     * A custom function to generate the cache key from the HTTP request.
+     * By default, it hashes the URL, method, headers (specified by `varyHeaders`), and body.
+     */
+    hash?: (req: HttpResourceRequest) => string;
+    /**
+     * A list of header names to include in the default cache key generation.
+     * Ignored if a custom `hash` function is provided.
+     *
+     * Note: still call `cache.clear()` on logout — the previous user's entries are
+     * unreachable under the new key but linger until their TTL.
+     */
+    varyHeaders?: string[];
+    /**
+     * Whether to bust the browser cache by appending a unique query parameter to the request URL.
+     * This is useful for ensuring that the latest data is fetched from the server, bypassing any
+     * cached responses in the browser. The unique parameter is removed before calling the cache function, so it does not affect the cache key.
+     * @default false - By default, the resource will not bust the browser cache.
+     */
+    bustBrowserCache?: boolean;
+    /**
+     * Whether to ignore the `Cache-Control` headers from the server when caching responses.
+     * If set to `true`, the resource will not respect any cache directives from the server,
+     * allowing you to control caching behavior entirely through the resource options.
+     * @default false - By default the resource will respect `Cache-Control` headers.
+     */
+    ignoreCacheControl?: boolean;
+    /**
+     * If true, it saves the cached responses to an indexedDb table, making it available across
+     * tabs, sessions and reloads..only valid JSON responses can be persisted (so no Blobs, formData, ArrayBuffers etc.)
+     * @default false
+     */
+    persist?: boolean;
+};
 /**
  * Auto-registration into the nearest transition scope, as a resource OPTION:
  *  - `'suspend'` — register as *suspending*: the boundary holds its placeholder until this

package/lib/query-resource.d.ts

@@ -1,48 +1,9 @@
 import { type HttpHeaders, type HttpResourceOptions, type HttpResourceRef, type HttpResourceRequest } from '@angular/common/http';
 import { type Provider, type Signal, type WritableSignal } from '@angular/core';
-import { type CommonResourceOptions } from './options';
-/**
- * Options for configuring caching behavior of a `queryResource`.
- * - `true`: Enables caching with default settings.
- * - `{ ttl?: number; staleTime?: number; hash?: (req: HttpResourceRequest) => string; }`:  Configures caching with custom settings.
- */
-type ResourceCacheOptions = true | {
-    /**
-     * The Time To Live (TTL) for the cached data, in milliseconds. After this time, the cached data is
-     * considered expired and will be refetched.
-     */
-    ttl?: number;
-    /**
-     * The duration, in milliseconds, during which stale data can be served while a revalidation request
-     * is made in the background.
-     */
-    staleTime?: number;
-    /**
-     * A custom function to generate the cache key. Defaults to using the request URL with parameters.
-     * Provide a custom hash function if you need more control over how cache keys are generated,
-     * for instance, to ignore certain query parameters or to use request body for the cache key.
-     */
-    hash?: (req: HttpResourceRequest) => string;
-    /**
-     * Whether to bust the browser cache by appending a unique query parameter to the request URL.
-     * This is useful for ensuring that the latest data is fetched from the server, bypassing any
-     * cached responses in the browser. The unique parameter is removed before calling the cache function, so it does not affect the cache key.
-     * @default false - By default, the resource will not bust the browser cache.
-     */
-    bustBrowserCache?: boolean;
-    /**
-     * Whether to ignore the `Cache-Control` headers from the server when caching responses.
-     * If set to `true`, the resource will not respect any cache directives from the server,
-     * allowing you to control caching behavior entirely through the resource options.
-     * @default false - By default the resource will respect `Cache-Control` headers.
-     */
-    ignoreCacheControl?: boolean;
-    /**
-     * Whether to persist the cache entry in the local DB instance.
-     * @default false - By default, the cache entry is not persisted.
-     */
-    persist?: boolean;
-};
+import { type PauseOption } from '@mmstack/primitives';
+import { type CommonResourceOptions, type ResourceCacheOptions } from './options';
+import { type RefreshOptions } from './util';
+export { type RefreshOptions } from './util';
 /**
  * Options for configuring a `queryResource`. Extends Angular's
  * `HttpResourceOptions` with caching, retries, refresh intervals, circuit
@@ -68,10 +29,19 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
      */
     keepPrevious?: boolean;
     /**
-     * The refresh interval, in milliseconds. If provided, the resource will automatically
-     * refresh its data at the specified interval.
+     * Automatic refresh behavior. A number polls every n milliseconds; the object form
+     * composes polling with event-driven triggers:
+     *
+     * ```ts
+     * refresh: 30_000                                  // poll every 30s
+     * refresh: { onFocus: true, onReconnect: true }    // refetch on tab refocus / back-online
+     * refresh: { interval: 60_000, onFocus: true }     // both
+     * ```
+     *
+     * Triggers respect the resource's disabled/paused state (no refetch while
+     * offline, circuit-open, or paused).
      */
-    refresh?: number;
+    refresh?: RefreshOptions;
     /**
      * Called on every failed attempt, including each retry.
      *
@@ -87,6 +57,20 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
      * Options for enabling and configuring caching for the resource.
      */
     cache?: ResourceCacheOptions;
+    /**
+     * Opt-in automatic pausing (off by default — existing behavior unchanged):
+     * - `true` — pause whenever the surrounding Activity boundary (`MmActivity` /
+     *   `providePaused` from `@mmstack/primitives`) is paused. Outside a boundary this
+     *   is a no-op, so it's safe to set app-wide via `provideQueryResourceOptions`.
+     * - a `() => boolean` predicate (a `Signal<boolean>` qualifies) — pause while it
+     *   returns `true`.
+     *
+     * Pausing has the same semantics as returning `ctx.paused` from the request fn:
+     * the resource HOLDS its current value and last request (no refetch on resume if
+     * the request is unchanged) and stops background work (polling, focus/reconnect
+     * triggers). The two compose — either source can pause the resource.
+     */
+    pause?: PauseOption;
     /**
      * Comparison of request object
      */
@@ -113,6 +97,9 @@ export declare function provideQueryResourceOptions(valueOrFn: Partial<QueryReso
  *   }
  * });
  * ```
+ *
+ * Note: a PAUSED resource also reports `'no-request'` — it holds its previous value
+ * and request, but no request is currently active.
  */
 export type DisabledReason = 'offline' | 'circuit-open' | 'no-request';
 /**
@@ -171,7 +158,10 @@ export type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers'
     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.
+     * used to proactively load data before it's needed.
+     *
+     * Resolves immediately without fetching when caching is disabled or a slow
+     * connection is detected (prefetching would compete with user-initiated requests).
      *
      * @param req - Optional partial request parameters to use for the prefetch.  This allows you
      *              to prefetch data with different parameters than the main resource request.
@@ -235,4 +225,3 @@ export declare function queryResource<TResult, TRaw = TResult>(request: Resource
  * ```
  */
 export declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequestFn, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
-export {};

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

@@ -21,6 +21,10 @@ export declare function setCacheContext(ctx: HttpContext | undefined, opt: Omit<
  * 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.
  *
+ * Cache-enabled requests are single-flighted per cache key: N concurrent consumers of
+ * the same missing/stale entry share ONE network request. Non-cached requests are not
+ * touched — pair with `createDedupeRequestsInterceptor` to coalesce those as well.
+ *
  * @param allowedMethods - An array of HTTP methods for which caching should be enabled.
  *                        Defaults to `['GET', 'HEAD', 'OPTIONS']`.
  *

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

@@ -43,8 +43,11 @@ export type CacheEntry<T> = {
     updated: number;
     stale: number;
     useCount: number;
+    /** Timestamp of the last read/write — drives LRU eviction. */
+    lastAccessed: number;
     expiresAt: number;
-    timeout: ReturnType<typeof setTimeout>;
+    /** Absent for non-finite/over-int32 TTLs — those rely on lazy expiry instead. */
+    timeout?: ReturnType<typeof setTimeout>;
     key: string;
 };
 /**
@@ -65,9 +68,27 @@ export declare class Cache<T> {
     private readonly internal;
     private readonly cleanupOpt;
     private readonly id;
+    /** True once async hydration from the persistence layer has completed (or was empty). */
+    private hydrated;
+    /** Keys invalidated while hydration was still in flight — must not be resurrected by it. */
+    private readonly hydrationTombstones;
+    private readonly hitCount;
+    private readonly missCount;
     /**
-     * Destroys the cache instance, cleaning up any resources used by the cache.
-     * This method is called automatically when the cache instance is garbage collected.
+     * Read-only cache statistics for debugging/observability — entry count plus
+     * request-level hit/miss counters (counted on direct lookups, e.g. the cache
+     * interceptor's, not on every reactive signal read). Render it in a debug
+     * panel; it intentionally exposes no way to mutate the cache.
+     */
+    readonly stats: Signal<{
+        size: number;
+        hits: number;
+        misses: number;
+    }>;
+    /**
+     * Destroys the cache instance, clearing the cleanup interval and closing the
+     * cross-tab channel. Called automatically when the providing injector is destroyed
+     * (wired up by `provideQueryCache`); call it manually for caches you construct yourself.
      */
     readonly destroy: () => void;
     private readonly broadcast;
@@ -89,9 +110,11 @@ export declare class Cache<T> {
     }, db?: Promise<CacheDB<T>>);
     /** @internal */
     private getInternal;
+    /** @internal Imperative access bookkeeping for LRU eviction. */
+    private touch;
     /**
-     * Retrieves a cache entry without affecting its usage count (for LRU).  This is primarily
-     * for internal use or debugging.
+     * Retrieves a cache entry directly (non-reactively), updating its access bookkeeping
+     * for LRU eviction.
      * @internal
      * @param key - The key of the entry to retrieve.
      * @returns The cache entry, or `null` if not found or expired.
@@ -122,13 +145,27 @@ export declare class Cache<T> {
     /**
      * Stores a value in the cache.
      *
+     * NOTE: cached values are shared by reference across all consumers (current and
+     * future cache hits, persistence, cross-tab sync) — do not mutate a value after
+     * storing it or after reading it from 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`.
+     * @param persist - (Optional) Whether to also write the entry to the persistence layer (IndexedDB). Defaults to `false`.
      */
     store(key: string, value: T, staleTime?: number, ttl?: number, persist?: boolean): void;
     private storeInternal;
+    /**
+     * @internal
+     * Inserts an entry that already carries ABSOLUTE timestamps — hydration from the
+     * persistence layer and cross-tab sync messages. Never re-anchors freshness to
+     * `Date.now()`, never persists, never broadcasts.
+     */
+    private restoreInternal;
+    /** @internal Shared writer: arms the expiry timer only within the safe delay range. */
+    private setEntry;
     /**
      * Invalidates (removes) a cache entry.
      *
@@ -154,7 +191,12 @@ export declare class Cache<T> {
      */
     invalidateWhere(predicate: (key: string) => boolean): number;
     private invalidateInternal;
-    /** @internal */
+    /**
+     * Removes EVERY entry — memory, persisted rows, and (via broadcast) other tabs.
+     * Call on logout/auth changes so no prior user's responses survive.
+     */
+    clear(): void;
+    /** @internal Drops expired entries, then enforces `maxSize` by the configured strategy. */
     private cleanup;
 }
 /**
@@ -238,4 +280,16 @@ export declare function provideQueryCache(opt?: CacheOptions): Provider;
  * }
  */
 export declare function injectQueryCache<TRaw = unknown>(injector?: Injector): Cache<HttpResponse<TRaw>>;
+/**
+ * Injects the cache statistics, including the current size of the cache and the number of hits and misses.
+ *
+ * @param injector - (Optional) The injector to use.  If not provided, the current
+ *                   injection context is used.
+ * @returns A signal containing the cache statistics.
+ */
+export declare function injectCacheStats(injector?: Injector): Signal<{
+    size: number;
+    hits: number;
+    misses: number;
+}>;
 export {};

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

@@ -1,2 +1,2 @@
-export { Cache, injectQueryCache, provideQueryCache } from './cache';
+export { Cache, injectCacheStats, injectQueryCache, provideQueryCache, } from './cache';
 export * from './cache-interceptor';

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

@@ -1,2 +1,2 @@
-export { Cache, injectQueryCache, provideQueryCache } from './cache';
+export { Cache, injectQueryCache, provideQueryCache, type CacheEntry, type CleanupType, } from './cache';
 export { createCacheInterceptor } from './cache-interceptor';

package/lib/util/dedupe-interceptor.d.ts

@@ -22,6 +22,12 @@ export declare function noDedupe(ctx?: HttpContext): HttpContext;
  * only the first request will be sent to the server. Subsequent requests will
  * receive the response from the first request.
  *
+ * Relationship to `createCacheInterceptor`: the cache interceptor has built-in
+ * single-flight for CACHE-ENABLED requests (keyed by the cache key). This interceptor
+ * covers everything the cache doesn't see — non-cached resources, plain HttpClient
+ * calls, DELETEs — keyed by the request hash. Installing both is the recommended
+ * setup; where they overlap, this one degrades to a no-op passthrough.
+ *
  * @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.

package/lib/util/hash-request.d.ts

@@ -5,17 +5,24 @@ type HashableRequest = {
     responseType?: string;
     params?: HttpResourceRequest['params'] | HttpRequest<unknown>['params'];
     body?: unknown;
+    headers?: HttpResourceRequest['headers'] | HttpRequest<unknown>['headers'];
 };
 /**
  * Builds a stable cache/dedupe key from an HTTP request shape (accepts both
  * `HttpRequest` and `HttpResourceRequest`).
  *
- * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}]`
+ * Key composition: `${method}:${url}:${responseType}[:${params}][:${body}][:${vary}]`
  * - `method` defaults to `'GET'`, `responseType` to `'json'` (Angular defaults).
  * - Query params are sorted alphabetically and URL-encoded for stability.
  * - Body hashing handles `File`/`Blob`/`FormData`/`URLSearchParams`/`ArrayBuffer`
  *   and typed arrays explicitly; everything else flows through key-sorted
  *   `JSON.stringify` via `hash()`.
+ * - `varyHeaders` (opt-in) mixes the named request headers into the key so responses
+ *   that differ per header (e.g. `Authorization` → per-user, `Accept-Language`) get
+ *   separate entries. Known-safe content-negotiation headers (`Accept`,
+ *   `Accept-Language`, `Content-Language`, `Content-Type`) embed their value raw for
+ *   readable keys; all other header VALUES are one-way digested, never embedded raw —
+ *   keys are persisted to IndexedDB and broadcast across tabs.
  */
-export declare function hashRequest(req: HashableRequest): string;
+export declare function hashRequest(req: HashableRequest, varyHeaders?: readonly string[]): string;
 export {};

package/lib/util/index.d.ts

@@ -5,6 +5,7 @@ export * from './dedupe-interceptor';
 export * from './equality';
 export * from './has-slow-connection';
 export * from './hash-request';
+export * from './merge-options';
 export * from './persist';
 export * from './refresh';
 export * from './retry-on-error';

package/lib/util/merge-options.d.ts

@@ -0,0 +1,24 @@
+import type { CircuitBreakerOptions } from './circuit-breaker';
+import type { RefreshOptions } from './refresh';
+import type { RetryOptions } from './retry-on-error';
+import type { ResourceCacheOptions } from '../options';
+/**
+ * Deep merges multiple circuit breaker options.
+ * The latter options override the former.
+ */
+export declare function mergeCircuitBreakerOptions(global?: CircuitBreakerOptions | true, query?: CircuitBreakerOptions | true, local?: CircuitBreakerOptions | true): CircuitBreakerOptions | true | undefined;
+/**
+ * Deep merges multiple retry options.
+ * The latter options override the former.
+ */
+export declare function mergeRetryOptions(global?: RetryOptions | number, query?: RetryOptions | number, local?: RetryOptions | number): RetryOptions | number | undefined;
+/**
+ * Deep merges multiple cache options.
+ * The latter options override the former.
+ */
+export declare function mergeCacheOptions(query?: ResourceCacheOptions, local?: ResourceCacheOptions): ResourceCacheOptions | undefined;
+/**
+ * Deep merges multiple refresh options.
+ * The latter options override the former.
+ */
+export declare function mergeRefreshOptions(query?: RefreshOptions | number, local?: RefreshOptions | number): RefreshOptions | number | undefined;

package/lib/util/public_api.d.ts

@@ -1,3 +1,4 @@
 export * from './cache/public_api';
 export { createCircuitBreaker, provideCircuitBreakerDefaultOptions, } from './circuit-breaker';
 export { createDedupeRequestsInterceptor, noDedupe, } from './dedupe-interceptor';
+export { hashRequest } from './hash-request';

package/lib/util/refresh.d.ts

@@ -1,3 +1,31 @@
-import { HttpResourceRef } from '@angular/common/http';
-import { DestroyRef } from '@angular/core';
-export declare function refresh<T>(resource: HttpResourceRef<T>, destroyRef: DestroyRef, refresh?: number, inactive?: () => boolean): HttpResourceRef<T>;
+import { type HttpResourceRef } from '@angular/common/http';
+import { type DestroyRef, type Injector, type Signal } from '@angular/core';
+/**
+ * Refresh configuration for a query resource.
+ * - a `number` is shorthand for `{ interval: number }` (poll every n milliseconds)
+ * - the object form composes polling with event-driven refresh triggers
+ */
+export type RefreshOptions = number | {
+    /**
+     * Poll interval in milliseconds. Omit (or 0) for no polling — useful when only
+     * the event-driven triggers below are wanted.
+     */
+    interval?: number;
+    /**
+     * Reload when the page becomes visible again (tab refocused, window restored).
+     * @default false
+     */
+    onFocus?: boolean;
+    /**
+     * Reload when the browser comes back online.
+     * @default false
+     */
+    onReconnect?: boolean;
+};
+/** @internal Reactive sources + injector for the event-driven refresh triggers. */
+export type RefreshTriggers = {
+    injector: Injector;
+    visibility: Signal<DocumentVisibilityState>;
+    online: Signal<boolean>;
+};
+export declare function refresh<T>(resource: HttpResourceRef<T>, destroyRef: DestroyRef, opt?: RefreshOptions, inactive?: () => boolean, triggers?: RefreshTriggers): HttpResourceRef<T>;

package/lib/util/sensors.d.ts

@@ -1,7 +1,9 @@
 import * as i0 from "@angular/core";
 export declare class ResourceSensors {
     readonly networkStatus: import("@mmstack/primitives").NetworkStatusSignal;
+    readonly pageVisibility: import("@angular/core").Signal<DocumentVisibilityState>;
     static ɵfac: i0.ɵɵFactoryDeclaration<ResourceSensors, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ResourceSensors>;
 }
 export declare function injectNetworkStatus(): import("@mmstack/primitives").NetworkStatusSignal;
+export declare function injectPageVisibility(): import("@angular/core").Signal<DocumentVisibilityState>;

package/lib/util/share-pending.d.ts

@@ -0,0 +1,12 @@
+import { type Observable } from 'rxjs';
+/**
+ * @internal
+ * Single-flight sharing: if a pending observable is already registered under `key`,
+ * return it; otherwise create one, share it (replaying the latest event to late
+ * subscribers), and deregister it on teardown/settle.
+ *
+ * Used by both the dedupe interceptor (keyed by full request hash, app-wide) and the
+ * cache interceptor (keyed by the CACHE key, guarding the miss/stale-revalidation path)
+ * — same mechanism, different keying/scope, so it lives here exactly once.
+ */
+export declare function sharePending<T>(pending: Map<string, Observable<T>>, key: string, create: () => Observable<T>): Observable<T>;

package/package.json

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