@mmstack/resource 19.0.0

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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,3 @@
+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

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

package/lib/util/index.d.ts

@@ -0,0 +1,9 @@
+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

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

package/lib/util/public_api.d.ts

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

package/lib/util/refresh.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,6 @@
+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

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mmstack/resource",
+  "version": "19.0.0",
+  "keywords": [
+    "angular",
+    "signals",
+    "http",
+    "resource",
+    "cache",
+    "mutation",
+    "rxjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mihajm/mmstack.git"
+  },
+  "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/resource",
+  "license": "MIT",
+  "peerDependencies": {
+    "@angular/common": "~19.2.3",
+    "@angular/core": "~19.2.3",
+    "rxjs": "~7.8.2",
+    "uuid": "~11.1.0"
+  },
+  "dependencies": {
+    "@mmstack/primitives": "*",
+    "@mmstack/object": "*",
+    "tslib": "^2.3.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/mmstack-resource.mjs"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "sideEffects": false,
+  "module": "fesm2022/mmstack-resource.mjs",
+  "typings": "index.d.ts"
+}