@mmstack/resource 21.3.2 → 21.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "21.3.2",
+  "version": "21.4.0",
   "keywords": [
     "angular",
     "signals",
@@ -18,7 +18,7 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/resource",
   "dependencies": {
-    "@mmstack/primitives": "^21.0.17",
+    "@mmstack/primitives": "^21.1.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {

package/types/mmstack-resource.d.ts

@@ -1,5 +1,6 @@
 import { HttpResponse, HttpInterceptorFn, HttpRequest, HttpContext, HttpResourceRef, HttpHeaders, HttpResourceRequest, HttpResourceOptions } from '@angular/common/http';
-import { Signal, Injector, Provider, WritableSignal, ValueEqualityFn } from '@angular/core';
+import { Signal, Injector, Provider, ResourceRef, InjectionToken, WritableSignal, ValueEqualityFn } from '@angular/core';
+import { RegisterOptions } from '@mmstack/primitives';
 
 type StoredEntry<T> = Omit<CacheEntry<T>, 'timeout'>;
 type CacheDB<T> = {
@@ -470,6 +471,42 @@ type RetryOptions = number | {
     backoff?: 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`;
+ *  - `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;
+/** Options common to every resource kind (the base layer for the options-injection system). */
+type CommonResourceOptions = {
+    /** Auto-registration into the nearest transition scope. */
+    readonly register?: TransitionRegistration;
+    /** Retry failed requests. */
+    readonly retry?: RetryOptions;
+    /** Configure a circuit breaker for the resource. */
+    readonly circuitBreaker?: CircuitBreakerOptions | true;
+    /** Trigger a request even when the request parameters are unchanged. @default false */
+    readonly triggerOnSameRequest?: boolean;
+};
+/** Layer 1: defaults that apply to ALL resource kinds. Type-specific providers inherit + override these. */
+declare function provideResourceOptions(valueOrFn: CommonResourceOptions | (() => CommonResourceOptions)): Provider;
+declare function injectResourceOptions(injector?: Injector): CommonResourceOptions;
+/** Shared helper for the type-specific providers (query/mutation), so precedence is identical. */
+declare function provideTypedResourceOptions<T>(token: InjectionToken<T>, valueOrFn: T | (() => T)): Provider;
+/**
+ * Applies a resolved `register` option to a freshly-created resource — adds it to the nearest
+ * transition scope and removes it on destroy. Runs in the resource's injection context (or the
+ * provided `injector`), since registration needs `TRANSITION_SCOPE` + `DestroyRef`.
+ */
+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.
@@ -530,7 +567,7 @@ type ResourceCacheOptions = true | {
  * };
  * ```
  */
-type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult, TRaw> & {
+type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult, TRaw> & CommonResourceOptions & {
     /**
      * Whether to keep the previous value of the resource while a refresh is in progress.
      * Defaults to `false`. Also keeps status & headers while refreshing.
@@ -541,10 +578,6 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
      * refresh its data at the specified interval.
      */
     refresh?: number;
-    /**
-     * Options for retrying failed requests.
-     */
-    retry?: RetryOptions;
     /**
      * Called on every failed attempt, including each retry.
      *
@@ -556,20 +589,20 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
      * "user actually needs to know" side effects (toasts, error reporting).
      */
     onError?: (err: unknown, retryCount: number, isFinal: boolean) => void;
-    /**
-     * Options for configuring a circuit breaker for the resource.
-     */
-    circuitBreaker?: CircuitBreakerOptions | true;
     /**
      * Options for enabling and configuring caching for the resource.
      */
     cache?: ResourceCacheOptions;
     /**
-     * Trigger a request every time the request function is triggered, even if the request parameters are the same.
-     * @default false
+     * Comparison of request object
      */
-    triggerOnSameRequest?: boolean;
+    equalRequest?: (a: HttpResourceRequest, b: HttpResourceRequest) => boolean;
 };
+/**
+ * Layer 2 (query): default options for every `queryResource`, inheriting + overriding the
+ * common defaults from `provideResourceOptions`. Per-call options override these in turn.
+ */
+declare function provideQueryResourceOptions(valueOrFn: Partial<QueryResourceOptions<any, any>> | (() => Partial<QueryResourceOptions<any, any>>)): Provider;
 /**
  * The reason a query resource is currently in the `disabled` state, or `null`
  * if it is enabled. Useful for branching UI on cause (e.g. "offline" vs
@@ -588,6 +621,24 @@ type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult
  * ```
  */
 type DisabledReason = 'offline' | 'circuit-open' | 'no-request';
+/**
+ * Returned from a resource's request fn to PAUSE it: the resource holds its current value and last
+ * request (so it does not refetch on resume), and stops background work (no polling, no refetch
+ * while paused). Distinct from returning `undefined` (DISABLE), which drops the request — a
+ * disabled resource may refetch when re-enabled, a paused one resumes exactly where it left off.
+ *
+ * The request fn receives a {@link RequestContext} and can just return `ctx.paused`.
+ */
+declare const PAUSED: unique symbol;
+/**
+ * Context passed to a resource's request fn. An object (not positional args) so it can grow
+ * without changing the call signature. Today it carries {@link PAUSED} so the fn can return it.
+ */
+type RequestContext = {
+    readonly paused: typeof PAUSED;
+};
+/** The request fn shape: build a request, or return `undefined` (disable) / `ctx.paused` (pause). */
+type ResourceRequestFn = (ctx: RequestContext) => HttpResourceRequest | string | undefined | void | typeof PAUSED;
 /**
  * Represents a resource created by `queryResource`. Extends `HttpResourceRef`
  * with `disabled` / `disabledReason` signals, writable `headers` / `statusCode`
@@ -656,7 +707,7 @@ type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers' | 'sta
  * user.value(); // always User — never undefined, even before the first fetch resolves
  * ```
  */
-declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
+declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequestFn, options: QueryResourceOptions<TResult, TRaw> & {
     defaultValue: NoInfer<TResult>;
 }): QueryResourceRef<TResult>;
 /**
@@ -689,7 +740,7 @@ declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResou
  * user.disabledReason(); // null while enabled; 'offline' / 'circuit-open' / 'no-request' otherwise
  * ```
  */
-declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
+declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequestFn, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
 
 /**
  * A reference to a manually triggered query resource. Extends
@@ -843,6 +894,11 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
     queue?: boolean;
     equal?: ValueEqualityFn<TMutation>;
 };
+/**
+ * Layer 2 (mutation): default options for every `mutationResource`, inheriting + overriding the
+ * common defaults from `provideResourceOptions`. Per-call options override these in turn.
+ */
+declare function provideMutationResourceOptions(valueOrFn: Partial<MutationResourceOptions<any, any, any, any, any, any>> | (() => Partial<MutationResourceOptions<any, any, any, any, any, any>>)): Provider;
 /**
  * Represents a mutation resource created by `mutationResource`. Extends
  * `QueryResourceRef` but strips methods that don't make sense for one-off
@@ -926,7 +982,7 @@ 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, options?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
+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, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, injectQueryCache, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideQueryCache, queryResource };
-export type { DisabledReason, ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef };
+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 };