@mmstack/resource 21.4.2 → 21.4.4

package/package.json

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

package/types/mmstack-resource.d.ts

@@ -1,4 +1,4 @@
-import { HttpResponse, HttpInterceptorFn, HttpRequest, HttpContext, HttpResourceOptions, HttpResourceRequest, HttpResourceRef, HttpHeaders } from '@angular/common/http';
+import { HttpResponse, HttpInterceptorFn, HttpRequest, HttpContext, HttpResourceRequest, HttpResourceOptions, HttpResourceRef, HttpHeaders } from '@angular/common/http';
 import { Signal, Injector, Provider, ResourceRef, InjectionToken, WritableSignal, ValueEqualityFn } from '@angular/core';
 import { PauseOption } from '@mmstack/primitives';
 
@@ -518,6 +518,33 @@ declare function noDedupe(ctx?: HttpContext): HttpContext;
  */
 declare function createDedupeRequestsInterceptor(allowed?: string[], keyFn?: (req: HttpRequest<unknown>) => string): HttpInterceptorFn;
 
+type HashableRequest = {
+    method?: string;
+    url: string;
+    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}][:${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.
+ */
+declare function hashRequest(req: HashableRequest, varyHeaders?: readonly string[]): string;
+
 /**
  * Refresh configuration for a query resource.
  * - a `number` is shorthand for `{ interval: number }` (poll every n milliseconds)
@@ -546,6 +573,59 @@ type RetryOptions = number | {
     backoff?: number;
 };
 
+/**
+ * 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.
+ */
+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
@@ -582,59 +662,6 @@ declare function provideTypedResourceOptions<T>(token: InjectionToken<T>, valueO
  */
 declare function applyResourceRegistration(ref: ResourceRef<unknown>, register: TransitionRegistration | undefined, injector?: Injector): void;
 
-/**
- * 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;
-    /**
-     * 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
  * `HttpResourceOptions` with caching, retries, refresh intervals, circuit
@@ -1197,5 +1224,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, 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 };
+export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, 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, ResourceCacheOptions, ResourceRequestFn, TransitionRegistration };