@mmstack/resource 19.6.2 → 19.6.4

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,62 +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 PauseOption } from '@mmstack/primitives';
-import { type CommonResourceOptions } from './options';
+import { type CommonResourceOptions, type ResourceCacheOptions } from './options';
 import { type RefreshOptions } from './util';
 export { type RefreshOptions } from './util';
-/**
- * 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

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/package.json

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