@mmstack/resource 22.1.0 → 22.1.2

package/package.json

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

package/types/mmstack-resource.d.ts

@@ -1,6 +1,6 @@
-import { HttpResponse, HttpInterceptorFn, HttpRequest, HttpContext, HttpResourceRef, HttpHeaders, HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
+import { HttpResponse, HttpInterceptorFn, HttpRequest, HttpContext, HttpResourceOptions, HttpResourceRequest, HttpResourceRef, HttpHeaders } from '@angular/common/http';
 import { Signal, Injector, Provider, ResourceRef, InjectionToken, WritableSignal, ValueEqualityFn } from '@angular/core';
-import { RegisterOptions } from '@mmstack/primitives';
+import { PauseOption } from '@mmstack/primitives';
 
 type StoredEntry<T> = Omit<CacheEntry<T>, 'timeout'>;
 type CacheDB<T> = {
@@ -51,8 +51,11 @@ 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;
 };
 /**
@@ -73,9 +76,27 @@ 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;
@@ -97,9 +118,11 @@ 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.
@@ -130,13 +153,27 @@ 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.
      *
@@ -162,7 +199,12 @@ 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;
 }
 /**
@@ -256,6 +298,10 @@ declare function injectQueryCache<TRaw = unknown>(injector?: Injector): Cache<Ht
  * 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']`.
  *
@@ -436,6 +482,12 @@ 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.
@@ -466,6 +518,29 @@ declare function noDedupe(ctx?: HttpContext): HttpContext;
  */
 declare function createDedupeRequestsInterceptor(allowed?: string[], keyFn?: (req: HttpRequest<unknown>) => string): HttpInterceptorFn;
 
+/**
+ * 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
+ */
+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;
+};
+
 type RetryOptions = number | {
     max?: number;
     backoff?: number;
@@ -473,17 +548,17 @@ type RetryOptions = number | {
 
 /**
  * Auto-registration into the nearest transition scope, as a resource OPTION:
- *  - `true` — register for the pending indicator + hold-stale (does NOT block first paint);
- *  - `{ suspends: true }` — register as *suspending* (the boundary holds its placeholder until
- *    this resource has a value), i.e. full Suspense;
- *  - `{ suspends: false }` — same as `true`;
+ *  - `'suspend'` — register as *suspending*: the boundary holds its placeholder until this
+ *    resource has a value (full Suspense). The right choice for data the subtree can't render without;
+ *  - `'indicator'` — register for the pending indicator + hold-stale only (does NOT block first
+ *    paint). The right choice for in-region data: the boundary shows the held value with `aria-busy`;
  *  - `false` / omitted — don't register.
  *
  * Defaultable via `provideResourceOptions` / `provideQueryResourceOptions` and overridable
  * (including opting out with `false`) per call — so a dev can make "all queries participate in
  * transitions" the default and turn it off for the odd one.
  */
-type TransitionRegistration = boolean | RegisterOptions;
+type TransitionRegistration = false | 'indicator' | 'suspend';
 /** Options common to every resource kind (the base layer for the options-injection system). */
 type CommonResourceOptions = {
     /** Auto-registration into the nearest transition scope. */
@@ -548,6 +623,17 @@ type ResourceCacheOptions = true | {
      * @default false - By default, the cache entry is not persisted.
      */
     persist?: boolean;
+    /**
+     * Request headers whose values should partition the cache key — e.g.
+     * `['Authorization']` gives each user their own entries, `['Accept-Language']`
+     * separates per-language responses. Header values are one-way digested into the
+     * key (never embedded raw), so secrets don't end up in persisted/broadcast keys.
+     * Ignored when a custom `hash` function is provided (it owns the key entirely).
+     *
+     * 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[];
 };
 /**
  * Options for configuring a `queryResource`. Extends Angular's
@@ -574,10 +660,19 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
      */
     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.
      *
@@ -593,6 +688,20 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
      * 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
      */
@@ -619,6 +728,9 @@ declare function provideQueryResourceOptions(valueOrFn: Partial<QueryResourceOpt
  *   }
  * });
  * ```
+ *
+ * Note: a PAUSED resource also reports `'no-request'` — it holds its previous value
+ * and request, but no request is currently active.
  */
 type DisabledReason = 'offline' | 'circuit-open' | 'no-request';
 /**
@@ -677,7 +789,10 @@ type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers' | 'sta
     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.
@@ -742,6 +857,85 @@ declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequest
  */
 declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequestFn, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
 
+/**
+ * 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.
+ */
+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.
+ */
+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).
+ */
+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));
+ * ```
+ */
+declare function infiniteQueryResource<TPage, TRaw = TPage, TPageParam = unknown>(request: (ctx: InfiniteRequestContext<TPageParam>) => HttpResourceRequest | string | undefined | typeof PAUSED, options: InfiniteQueryResourceOptions<TPage, TRaw, TPageParam>): InfiniteQueryResourceRef<TPage>;
+
 /**
  * A reference to a manually triggered query resource. Extends
  * {@link QueryResourceRef} with a `trigger()` method that runs the request
@@ -862,7 +1056,7 @@ type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMe
  * };
  * ```
  */
-type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TError = unknown> = Omit<QueryResourceOptions<TResult, TRaw>, 'equal' | 'onError' | 'keepPrevious' | 'refresh' | 'cache'> & {
+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).
@@ -892,6 +1086,25 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
      * @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>;
 };
 /**
@@ -984,5 +1197,5 @@ 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, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
 
-export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
-export type { CommonResourceOptions, DisabledReason, ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RequestContext, ResourceRequestFn, TransitionRegistration };
+export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
+export type { CacheEntry, CleanupType, CommonResourceOptions, DisabledReason, InfiniteQueryResourceOptions, InfiniteQueryResourceRef, InfiniteRequestContext, ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RefreshOptions, RequestContext, ResourceRequestFn, TransitionRegistration };