@mmstack/resource 19.2.0 → 20.0.1

package/lib/query-resource.d.ts

@@ -1,92 +0,0 @@
-import { type HttpResourceOptions, type HttpResourceRef, type HttpResourceRequest } from '@angular/common/http';
-import { Signal } from '@angular/core';
-import { CircuitBreakerOptions, type RetryOptions } 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;
-};
-/**
- * Options for configuring a `queryResource`.
- */
-export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult, TRaw> & {
-    /**
-     * Whether to keep the previous value of the resource while a refresh is in progress.
-     * Defaults to `false`. Also keeps status & headers while refreshing.
-     */
-    keepPrevious?: boolean;
-    /**
-     * The refresh interval, in milliseconds. If provided, the resource will automatically
-     * refresh its data at the specified interval.
-     */
-    refresh?: number;
-    /**
-     * Options for retrying failed requests.
-     */
-    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.
-     */
-    onError?: (err: unknown) => void;
-    /**
-     * Options for configuring a circuit breaker for the resource.
-     */
-    circuitBreaker?: CircuitBreakerOptions | true;
-    /**
-     * Options for enabling and configuring caching for the resource.
-     */
-    cache?: ResourceCacheOptions;
-};
-/**
- * Represents a resource created by `queryResource`. Extends `HttpResourceRef` with additional properties.
- */
-export type QueryResourceRef<TResult> = HttpResourceRef<TResult> & {
-    /**
-     * A signal indicating whether the resource is currently disabled (due to circuit breaker or undefined request).
-     */
-    disabled: Signal<boolean>;
-    /**
-     * 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.
-     *
-     * @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.
-     */
-    prefetch: (req?: Partial<HttpResourceRequest>) => Promise<void>;
-};
-export declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
-    defaultValue: NoInfer<TResult>;
-}): QueryResourceRef<TResult>;
-/**
- * Creates an extended HTTP resource with features like caching, retries, refresh intervals,
- * circuit breaker, and optimistic updates. Without additional options it is equivalent to simply calling `httpResource`.
- *
- * @param request A function that returns the `HttpResourceRequest` to be made.  This function
- *                is called reactively, so the request can change over time.  If the function
- *                returns `undefined`, the resource is considered "disabled" and no request will be made.
- * @param options Configuration options for the resource.  These options extend the basic
- *                `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
- *                `onError`, `circuitBreaker`, and `cache`.
- * @returns An `QueryResourceRef` instance, which extends the basic `HttpResourceRef` with additional features.
- */
-export declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
-export {};

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

@@ -1,177 +0,0 @@
-import type { HttpResponse } from '@angular/common/http';
-import { Injector, type Provider, type Signal } from '@angular/core';
-/**
- * Options for configuring the Least Recently Used (LRU) cache cleanup strategy.
- * @internal
- */
-type LRUCleanupType = {
-    type: 'lru';
-    /**
-     * How often to check for expired or excess entries, in milliseconds.
-     */
-    checkInterval: number;
-    /**
-     * The maximum number of entries to keep in the cache.  When the cache exceeds this size,
-     * the least recently used entries will be removed.
-     */
-    maxSize: number;
-};
-/**
- * Options for configuring the "oldest first" cache cleanup strategy.
- * @internal
- */
-type OldsetCleanupType = {
-    type: 'oldest';
-    /**
-     * How often to check for expired or excess entries, in milliseconds.
-     */
-    checkInterval: number;
-    /**
-     * The maximum number of entries to keep in the cache.  When the cache exceeds this size,
-     * the oldest entries will be removed.
-     */
-    maxSize: number;
-};
-/**
- * Represents an entry in the cache.
- * @internal
- */
-type CacheEntry<T> = {
-    value: T;
-    created: number;
-    stale: number;
-    useCount: number;
-    expiresAt: number;
-    timeout: ReturnType<typeof setTimeout>;
-};
-/**
- * Defines the types of cleanup strategies available for the cache.
- * - `lru`: Least Recently Used.  Removes the least recently accessed entries when the cache is full.
- * - `oldest`: Removes the oldest entries when the cache is full.
- */
-export type CleanupType = LRUCleanupType | OldsetCleanupType;
-/**
- * A generic cache implementation that stores data with time-to-live (TTL) and stale-while-revalidate capabilities.
- *
- * @typeParam T - The type of data to be stored in the cache.
- */
-export declare class Cache<T> {
-    protected readonly ttl: number;
-    protected readonly staleTime: number;
-    private readonly internal;
-    private readonly cleanupOpt;
-    /**
-     * Creates a new `Cache` instance.
-     *
-     * @param ttl - The default Time To Live (TTL) for cache entries, in milliseconds.  Defaults to one day.
-     * @param staleTime - The default duration, in milliseconds, during which a cache entry is considered
-     *                    stale but can still be used while revalidation occurs in the background. Defaults to 1 hour.
-     * @param cleanupOpt - Options for configuring the cache cleanup strategy.  Defaults to LRU with a
-     *                     `maxSize` of 200 and a `checkInterval` of one hour.
-     */
-    constructor(ttl?: number, staleTime?: number, cleanupOpt?: Partial<CleanupType>);
-    /** @internal */
-    private getInternal;
-    /**
-     * Retrieves a cache entry without affecting its usage count (for LRU).  This is primarily
-     * for internal use or debugging.
-     * @internal
-     * @param key - The key of the entry to retrieve.
-     * @returns The cache entry, or `null` if not found or expired.
-     */
-    getUntracked(key: string): (CacheEntry<T> & {
-        isStale: boolean;
-    }) | null;
-    /**
-     * Retrieves a cache entry as a signal.
-     *
-     * @param key - A function that returns the cache key. The key is a signal, allowing for dynamic keys. If the function returns null the value is also null.
-     * @returns A signal that holds the cache entry, or `null` if not found or expired.  The signal
-     *          updates whenever the cache entry changes (e.g., due to revalidation or expiration).
-     */
-    get(key: () => string | null): Signal<(CacheEntry<T> & {
-        isStale: boolean;
-    }) | null>;
-    /**
-     * Stores a value in 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`.
-     */
-    store(key: string, value: T, staleTime?: number, ttl?: number): void;
-    /**
-     * Invalidates (removes) a cache entry.
-     *
-     * @param key - The key of the entry to invalidate.
-     */
-    invalidate(key: string): void;
-    /** @internal */
-    private cleanup;
-}
-/**
- * Options for configuring the cache.
- */
-type CacheOptions = {
-    /**
-     * The default Time To Live (TTL) for cache entries, in milliseconds.
-     */
-    ttl?: number;
-    /**
-     * The default duration, in milliseconds, during which a cache entry is considered
-     * stale but can still be used while revalidation occurs in the background.
-     */
-    staleTime?: number;
-    /**
-     * Options for configuring the cache cleanup strategy.
-     */
-    cleanup?: Partial<CleanupType>;
-};
-/**
- * Provides the instance of the QueryCache for queryResource. This should probably be called
- * in your application's root configuration, but can also be overriden with component/module providers.
- *
- * @param options - Optional configuration options for the cache.
- * @returns An Angular `Provider` for the cache.
- *
- * @example
- * // In your app.config.ts or AppModule providers:
- *
- * import { provideQueryCache } from './your-cache';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideQueryCache({
- *       ttl: 60000, // Default TTL of 60 seconds
- *       staleTime: 30000, // Default staleTime of 30 seconds
- *     }),
- *     // ... other providers
- *   ]
- * };
- */
-export declare function provideQueryCache(opt?: CacheOptions): Provider;
-/**
- * Injects the `QueryCache` instance that is used within queryResource.
- * Allows for direct modification of cached data, but is mostly meant for internal use.
- *
- * @param injector - (Optional) The injector to use.  If not provided, the current
- *                   injection context is used.
- * @returns The `QueryCache` instance.
- *
- * @example
- * // In your component or service:
- *
- * import { injectQueryCache } from './your-cache';
- *
- * constructor() {
- *   const cache = injectQueryCache();
- *
- *   const myData = cache.get(() => 'my-data-key');
- *   if (myData() !== null) {
- *     // ... use cached data ...
- *   }
- * }
- */
-export declare function injectQueryCache(injector?: Injector): Cache<HttpResponse<unknown>>;
-export {};

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

@@ -1,39 +0,0 @@
-import { HttpContext, type HttpInterceptorFn } from '@angular/common/http';
-type CacheEntryOptions = {
-    key?: string;
-    ttl?: number;
-    staleTime?: number;
-    cache: boolean;
-};
-export declare function setCacheContext(ctx: HttpContext | undefined, opt: Omit<CacheEntryOptions, 'cache' | 'key'> & {
-    key: Required<CacheEntryOptions>['key'];
-}): HttpContext;
-/**
- * Creates an `HttpInterceptorFn` that implements caching for HTTP requests. This interceptor
- * checks for a caching configuration in the request's `HttpContext` (internally set by the queryResource).
- * If caching is enabled, it attempts to retrieve responses from the cache. If a cached response
- * is found and is not stale, it's returned directly.  If the cached response is stale, it's returned,
- * and a background revalidation request is made.  If no cached response is found, the request
- * 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.
- *
- * @param allowedMethods - An array of HTTP methods for which caching should be enabled.
- *                        Defaults to `['GET', 'HEAD', 'OPTIONS']`.
- *
- * @returns An `HttpInterceptorFn` that implements the caching logic.
- *
- * @example
- * // In your app.config.ts or module providers:
- *
- * import { provideHttpClient, withInterceptors } from '@angular/common/http';
- * import { createCacheInterceptor } from '@mmstack/resource';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideHttpClient(withInterceptors([createCacheInterceptor()])),
- *     // ... other providers
- *   ],
- * };
- */
-export declare function createCacheInterceptor(allowedMethods?: string[]): HttpInterceptorFn;
-export {};

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

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

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

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

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

@@ -1,74 +0,0 @@
-import { Signal } from '@angular/core';
-/**
- * Represents the possible states of a circuit breaker.
- * - `CLOSED`: The circuit breaker is closed, and operations are allowed to proceed.
- * - `OPEN`: The circuit breaker is open, and operations are blocked.
- * - `HALF_OPEN`: The circuit breaker is in a half-open state, allowing a limited number of operations to test if the underlying issue is resolved.
- */
-type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
-/**
- * Represents a circuit breaker, which monitors operations and prevents failures from cascading.
- */
-export type CircuitBreaker = {
-    /**
-     * A signal indicating whether the circuit breaker is currently closed (allowing operations).
-     */
-    isClosed: Signal<boolean>;
-    /**
-     * A signal representing the current state of the circuit breaker.
-     */
-    status: Signal<CircuitBreakerState>;
-    /**
-     * Signals a failure to the circuit breaker.  This may cause the circuit breaker to open.
-     */
-    fail: () => void;
-    /**
-     * Signals a success to the circuit breaker.  This may cause the circuit breaker to close.
-     */
-    success: () => void;
-    /**
-     * Attempts to transition the circuit breaker to the half-open state. This is typically used
-     * to test if the underlying issue has been resolved after the circuit breaker has been open.
-     */
-    halfOpen: () => void;
-    /**
-     * Destroys the circuit breaker & initiates related cleanup
-     */
-    destroy: () => void;
-};
-/**
- * Options for creating a circuit breaker.
- *  - `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.
- */
-export type CircuitBreakerOptions = false | CircuitBreaker | {
-    treshold?: number;
-    timeout?: number;
-};
-/**
- * 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).
- *   - `CircuitBreaker`:  Reuses an existing `CircuitBreaker` instance.
- *   - `{ threshold?: number; timeout?: number; }`: Creates a circuit breaker with the specified threshold and timeout.
- *
- * @returns A `CircuitBreaker` instance.
- *
- * @example
- * // Create a circuit breaker with default settings:
- * const breaker = createCircuitBreaker();
- *
- * // Create a circuit breaker with custom settings:
- * const customBreaker = createCircuitBreaker({ threshold: 10, timeout: 60000 });
- *
- * // Share a single circuit breaker instance across multiple resources:
- * const sharedBreaker = createCircuitBreaker();
- * const resource1 = queryResource(..., { circuitBreaker: sharedBreaker });
- * const resource2 = mutationResource(..., { circuitBreaker: sharedBreaker });
- */
-export declare function createCircuitBreaker(opt?: CircuitBreakerOptions): CircuitBreaker;
-export {};

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

@@ -1,50 +0,0 @@
-import { HttpContext, HttpInterceptorFn } from '@angular/common/http';
-/**
- * Disables request deduplication for a specific HTTP request.
- *
- * @param ctx - The `HttpContext` to modify. If not provided, a new `HttpContext` is created.
- * @returns The modified `HttpContext` with the `NO_DEDUPE` token set to `true`.
- *
- * @example
- * // Disable deduplication for a specific POST request:
- * const context = noDedupe();
- * this.http.post('/api/data', payload, { context }).subscribe(...);
- *
- * // Disable deduplication, modifying an existing context:
- * let context = new HttpContext();
- * context = noDedupe(context);
- * this.http.post('/api/data', payload, { context }).subscribe(...);
- */
-export declare function noDedupe(ctx?: HttpContext): HttpContext;
-/**
- * Creates an `HttpInterceptorFn` that deduplicates identical HTTP requests.
- * If multiple identical requests (same URL and parameters) are made concurrently,
- * only the first request will be sent to the server. Subsequent requests will
- * receive the response from the first request.
- *
- * @param allowed - An array of HTTP methods for which deduplication should be enabled.
- *                  Defaults to `['GET', 'DELETE', 'HEAD', 'OPTIONS']`.
- *
- * @returns An `HttpInterceptorFn` that implements the request deduplication logic.
- *
- * @example
- * // In your app.config.ts or module providers:
- * import { provideHttpClient, withInterceptors } from '@angular/common/http';
- * import { createDedupeRequestsInterceptor } from './your-dedupe-interceptor';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideHttpClient(withInterceptors([createDedupeRequestsInterceptor()])),
- *     // ... other providers
- *   ],
- * };
- *
- * // You can also specify which methods should be deduped
- *  export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideHttpClient(withInterceptors([createDedupeRequestsInterceptor(['GET'])])), // only dedupe GET calls
- *     // ... other providers
- *   ],
- * };
- */
-export declare function createDedupeRequestsInterceptor(allowed?: string[]): HttpInterceptorFn;

package/lib/util/equality.d.ts

@@ -1,3 +0,0 @@
-import { HttpResourceRequest } from '@angular/common/http';
-import { type ValueEqualityFn } from '@angular/core';
-export declare function createEqualRequest<TResult>(equalResult?: ValueEqualityFn<TResult>): (a: Partial<HttpResourceRequest> | undefined, b: Partial<HttpResourceRequest> | undefined) => boolean;

package/lib/util/has-slow-connection.d.ts

@@ -1 +0,0 @@
-export declare function hasSlowConnection(): boolean;

package/lib/util/index.d.ts

@@ -1,9 +0,0 @@
-export * from './cache';
-export * from './circuit-breaker';
-export * from './dedupe.interceptor';
-export * from './equality';
-export * from './has-slow-connection';
-export * from './persist';
-export * from './refresh';
-export * from './retry-on-error';
-export * from './url-with-params';

package/lib/util/persist.d.ts

@@ -1,3 +0,0 @@
-import { type HttpResourceRef } from '@angular/common/http';
-import { type ValueEqualityFn } from '@angular/core';
-export declare function persistResourceValues<T>(resource: HttpResourceRef<T>, persist?: boolean, equal?: ValueEqualityFn<T>): HttpResourceRef<T>;

package/lib/util/public_api.d.ts

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

package/lib/util/refresh.d.ts

@@ -1,3 +0,0 @@
-import { HttpResourceRef } from '@angular/common/http';
-import { DestroyRef } from '@angular/core';
-export declare function refresh<T>(resource: HttpResourceRef<T>, destroyRef: DestroyRef, refresh?: number): HttpResourceRef<T>;

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

@@ -1,6 +0,0 @@
-import { type HttpResourceRef } from '@angular/common/http';
-export type RetryOptions = number | {
-    max?: number;
-    backoff?: number;
-};
-export declare function retryOnError<T>(res: HttpResourceRef<T>, opt?: RetryOptions): HttpResourceRef<T>;

package/lib/util/url-with-params.d.ts

@@ -1,2 +0,0 @@
-import { HttpResourceRequest } from '@angular/common/http';
-export declare function urlWithParams(req: HttpResourceRequest): string;