@mmstack/resource 19.5.1 → 19.6.0

package/index.d.ts

@@ -1,4 +1,5 @@
 export * from './lib/manual-query';
 export * from './lib/mutation-resource';
+export * from './lib/options';
 export * from './lib/query-resource';
 export * from './lib/util/public_api';

package/lib/mutation-resource.d.ts

@@ -1,5 +1,5 @@
 import { type HttpResourceRequest } from '@angular/common/http';
-import { type Signal, type ValueEqualityFn } from '@angular/core';
+import { type Provider, type Signal, type ValueEqualityFn } from '@angular/core';
 import { type QueryResourceOptions, type QueryResourceRef } from './query-resource';
 /**
  * @internal
@@ -68,6 +68,11 @@ export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult
     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.
+ */
+export 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
@@ -151,5 +156,5 @@ export type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Om
  * );
  * ```
  */
-export 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>;
+export 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 {};

package/lib/options.d.ts

@@ -0,0 +1,38 @@
+import { InjectionToken, type Injector, type Provider, type ResourceRef } from '@angular/core';
+import { type RegisterOptions } from '@mmstack/primitives';
+import { type CircuitBreakerOptions, type RetryOptions } from './util';
+/**
+ * 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.
+ */
+export type TransitionRegistration = boolean | RegisterOptions;
+/** Options common to every resource kind (the base layer for the options-injection system). */
+export 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. */
+export declare function provideResourceOptions(valueOrFn: CommonResourceOptions | (() => CommonResourceOptions)): Provider;
+export declare function injectResourceOptions(injector?: Injector): CommonResourceOptions;
+/** Shared helper for the type-specific providers (query/mutation), so precedence is identical. */
+export 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`.
+ */
+export declare function applyResourceRegistration(ref: ResourceRef<unknown>, register: TransitionRegistration | undefined, injector?: Injector): void;

package/lib/query-resource.d.ts

@@ -1,6 +1,6 @@
-import { HttpHeaders, type HttpResourceOptions, type HttpResourceRef, type HttpResourceRequest } from '@angular/common/http';
-import { Signal, WritableSignal } from '@angular/core';
-import { CircuitBreakerOptions, type RetryOptions } from './util';
+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 CommonResourceOptions } from './options';
 /**
  * Options for configuring caching behavior of a `queryResource`.
  * - `true`: Enables caching with default settings.
@@ -61,7 +61,7 @@ type ResourceCacheOptions = true | {
  * };
  * ```
  */
-export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult, TRaw> & {
+export 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.
@@ -72,10 +72,6 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
      * refresh its data at the specified interval.
      */
     refresh?: number;
-    /**
-     * Options for retrying failed requests.
-     */
-    retry?: RetryOptions;
     /**
      * Called on every failed attempt, including each retry.
      *
@@ -87,20 +83,20 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
      * "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.
+ */
+export 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
@@ -119,6 +115,24 @@ export type QueryResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<
  * ```
  */
 export 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`.
+ */
+export 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.
+ */
+export type RequestContext = {
+    readonly paused: typeof PAUSED;
+};
+/** The request fn shape: build a request, or return `undefined` (disable) / `ctx.paused` (pause). */
+export 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`
@@ -187,7 +201,7 @@ export type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers'
  * user.value(); // always User — never undefined, even before the first fetch resolves
  * ```
  */
-export declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
+export declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequestFn, options: QueryResourceOptions<TResult, TRaw> & {
     defaultValue: NoInfer<TResult>;
 }): QueryResourceRef<TResult>;
 /**
@@ -220,5 +234,5 @@ export declare function queryResource<TResult, TRaw = TResult>(request: () => Ht
  * user.disabledReason(); // null while enabled; 'offline' / 'circuit-open' / 'no-request' otherwise
  * ```
  */
-export declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
+export declare function queryResource<TResult, TRaw = TResult>(request: ResourceRequestFn, options?: QueryResourceOptions<TResult, TRaw>): QueryResourceRef<TResult | undefined>;
 export {};

package/lib/util/refresh.d.ts

@@ -1,3 +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>;
+export declare function refresh<T>(resource: HttpResourceRef<T>, destroyRef: DestroyRef, refresh?: number, inactive?: () => boolean): HttpResourceRef<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "19.5.1",
+  "version": "19.6.0",
   "keywords": [
     "angular",
     "signals",
@@ -17,7 +17,7 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/resource",
   "dependencies": {
-    "@mmstack/primitives": "^19.3.0",
+    "@mmstack/primitives": "^19.4.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {