@mmstack/resource 20.7.0 → 20.8.0

package/index.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.
@@ -513,9 +550,24 @@ type ResourceCacheOptions = true | {
     persist?: boolean;
 };
 /**
- * Options for configuring a `queryResource`.
+ * Options for configuring a `queryResource`. Extends Angular's
+ * `HttpResourceOptions` with caching, retries, refresh intervals, circuit
+ * breakers, and lifecycle callbacks. See the linked properties below for the
+ * full list.
+ *
+ * @example
+ * ```ts
+ * const options: QueryResourceOptions<User> = {
+ *   defaultValue: { id: 0, name: 'Anonymous' },
+ *   cache: { ttl: 60_000, staleTime: 10_000 },
+ *   refresh: 30_000,
+ *   retry: { max: 3 },
+ *   circuitBreaker: true,
+ *   onError: (err, retry, isFinal) => isFinal && toast.error(err),
+ * };
+ * ```
  */
-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.
@@ -526,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.
      *
@@ -541,28 +589,73 @@ 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
  * "circuit tripped" vs "nothing to fetch yet").
+ *
+ * @example
+ * ```ts
+ * effect(() => {
+ *   switch (user.disabledReason()) {
+ *     case 'offline':      return toast.warn('You are offline');
+ *     case 'circuit-open': return toast.warn('Service temporarily unavailable');
+ *     case 'no-request':   return; // expected — request signal returned undefined
+ *     case null:           return; // resource is enabled
+ *   }
+ * });
+ * ```
  */
 type DisabledReason = 'offline' | 'circuit-open' | 'no-request';
 /**
- * Represents a resource created by `queryResource`. Extends `HttpResourceRef` with additional properties.
+ * 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`
+ * (so optimistic updates can patch them), and `prefetch()` for proactive cache
+ * warm-up.
+ *
+ * @example
+ * ```ts
+ * const user = queryResource<User>(() => `/api/users/${userId()}`);
+ *
+ * effect(() => {
+ *   if (user.status() === 'resolved') console.log(user.value());
+ * });
+ *
+ * // Warm the cache before navigating
+ * onMouseEnter(() => user.prefetch());
+ * ```
  */
 type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers' | 'statusCode'> & {
     /**
@@ -601,8 +694,20 @@ type QueryResourceRef<TResult> = Omit<HttpResourceRef<TResult>, 'headers' | 'sta
  *               `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
  *                `onError`, `circuitBreaker`, and `cache`.  Additionally, when a `defaultValue` is provided, the resource's value will always be defined, even if the underlying HTTP request fails or is disabled.
  * @returns An `QueryResourceRef` instance, which extends the basic `HttpResourceRef` with additional features.
+ *
+ * @example
+ * ```ts
+ * const userId = signal(1);
+ *
+ * const user = queryResource<User>(
+ *   () => `/api/users/${userId()}`,
+ *   { defaultValue: { id: 0, name: 'Anonymous' } },
+ * );
+ *
+ * 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>;
 /**
@@ -616,12 +721,51 @@ declare function queryResource<TResult, TRaw = TResult>(request: () => HttpResou
  *                `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
  *                `onError`, `circuitBreaker`, and `cache`.
  * @returns An `QueryResourceRef` instance, which extends the basic `HttpResourceRef` with additional features.
+ *
+ * @example
+ * ```ts
+ * const userId = signal<number | undefined>(undefined);
+ *
+ * const user = queryResource<User>(
+ *   () => userId() ? `/api/users/${userId()}` : undefined,
+ *   {
+ *     cache: { ttl: 60_000, staleTime: 10_000 },
+ *     refresh: 30_000,
+ *     retry: { max: 3 },
+ *   },
+ * );
+ *
+ * user.value();          // User | undefined
+ * user.status();         // 'idle' | 'loading' | 'resolved' | 'error'
+ * 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.  This type extends the standard `QueryResourceRef`
- * with an additional `trigger` method that allows you to manually trigger the resource request.
+ * A reference to a manually triggered query resource. Extends
+ * {@link QueryResourceRef} with a `trigger()` method that runs the request
+ * imperatively and returns a `Promise<TResult>`. Useful when a request should
+ * only happen on user action (search submit, button click) rather than on
+ * every reactive change of the request inputs.
+ *
+ * @example
+ * ```ts
+ * const search = manualQueryResource<SearchResults>(() => ({
+ *   url: '/api/search',
+ *   params: { q: query() },
+ * }));
+ *
+ * async function onSubmit() {
+ *   try {
+ *     const results = await search.trigger();
+ *     showResults(results);
+ *   } catch (err) {
+ *     toast.error('Search failed');
+ *   }
+ * }
+ * ```
+ *
  * @see QueryResourceRef
  */
 type ManualQueryResourceRef<TResult> = QueryResourceRef<TResult> & {
@@ -637,6 +781,17 @@ type ManualQueryResourceRef<TResult> = QueryResourceRef<TResult> & {
  *               `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
  *                `onError`, `circuitBreaker`, and `cache`.  Additionally, when a `defaultValue` is provided, the resource's value will always be defined, even if the underlying HTTP request fails or is disabled.
  * @returns An `ManualQueryResourceRef` instance, which extends the basic `QueryResourceRef` with additional features.
+ *
+ * @example
+ * ```ts
+ * const search = manualQueryResource<SearchResults>(
+ *   () => ({ url: '/api/search', params: { q: query() } }),
+ *   { defaultValue: { hits: [], total: 0 } },
+ * );
+ *
+ * // search.value() is always SearchResults (never undefined) thanks to defaultValue.
+ * const results = await search.trigger();
+ * ```
  */
 declare function manualQueryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options: QueryResourceOptions<TResult, TRaw> & {
     defaultValue: NoInfer<TResult>;
@@ -652,6 +807,23 @@ declare function manualQueryResource<TResult, TRaw = TResult>(request: () => Htt
  *                `HttpResourceOptions` and add features like `keepPrevious`, `refresh`, `retry`,
  *                `onError`, `circuitBreaker`, and `cache`.
  * @returns An `ManualQueryResourceRef` instance, which extends the basic `QueryResourceRef` with additional features.
+ *
+ * @example
+ * ```ts
+ * const exportReport = manualQueryResource<Report>(() => ({
+ *   url: '/api/reports/export',
+ *   params: { range: range() },
+ * }));
+ *
+ * async function onExportClick() {
+ *   try {
+ *     const report = await exportReport.trigger();
+ *     download(report);
+ *   } catch (err) {
+ *     toast.error('Export failed');
+ *   }
+ * }
+ * ```
  */
 declare function manualQueryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): ManualQueryResourceRef<TResult | undefined>;
 
@@ -666,11 +838,29 @@ type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMe
     method: TMethod;
 };
 /**
- * Options for configuring a `mutationResource`.
+ * Options for configuring a `mutationResource`. Inherits from
+ * `QueryResourceOptions` (minus options that don't apply to mutations:
+ * `equal`, `keepPrevious`, `refresh`, `cache`) and adds lifecycle callbacks
+ * (`onMutate`, `onError`, `onSuccess`, `onSettled`) for managing optimistic
+ * updates, rollback, and side effects.
  *
  * @typeParam TResult - The type of the expected result from the mutation.
  * @typeParam TRaw - The raw response type from the HTTP request (defaults to TResult).
  * @typeParam TCTX - The type of the context value returned by `onMutate`.
+ *
+ * @example
+ * ```ts
+ * const options: MutationResourceOptions<User, User, Partial<User>, { previous: User | null }> = {
+ *   onMutate: (patch) => {
+ *     const previous = current();
+ *     current.update((u) => (u ? { ...u, ...patch } : u)); // optimistic
+ *     return { previous };
+ *   },
+ *   onError: (_err, { previous }) => current.set(previous), // rollback
+ *   onSuccess: (saved) => toast.success(`Updated ${saved.name}`),
+ *   queue: true, // serialize requests when offline / circuit open
+ * };
+ * ```
  */
 type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX, TError = unknown> = Omit<QueryResourceOptions<TResult, TRaw>, 'equal' | 'onError' | 'keepPrevious' | 'refresh' | 'cache'> & {
     /**
@@ -705,10 +895,29 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
     equal?: ValueEqualityFn<TMutation>;
 };
 /**
- * Represents a mutation resource created by `mutationResource`.  Extends `QueryResourceRef`
- * but removes methods that don't make sense for mutations (like `prefetch`, `value`, etc.).
+ * 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
+ * writes (`prefetch`, `value`, `hasValue`, `set`, `update`) and adds `mutate()`
+ * for triggering a mutation plus `current()` for tracking the in-flight value.
  *
  * @typeParam TResult - The type of the expected result from the mutation.
+ *
+ * @example
+ * ```ts
+ * const updateUser = mutationResource<User, User, Partial<User>>(...);
+ *
+ * effect(() => console.log('mutating:', updateUser.current()));
+ * effect(() => {
+ *   if (updateUser.status() === 'error') toast.error(updateUser.error());
+ * });
+ *
+ * updateUser.mutate({ name: 'Alice' });
+ * ```
  */
 type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<QueryResourceRef<TResult>, 'prefetch' | 'value' | 'hasValue' | 'set' | 'update'> & {
     /**
@@ -742,8 +951,38 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
  * @typeParam TMethod - The HTTP method to be used for the mutation (defaults to `HttpResourceRequest['method']`).
  * @returns A `MutationResourceRef` instance, which provides methods for triggering the mutation
  *          and observing its status.
+ *
+ * @example
+ * ```ts
+ * // Basic PATCH mutation
+ * const updateUser = mutationResource<User, User, Partial<User>>(
+ *   (body) => ({ url: `/api/users/${userId()}`, method: 'PATCH', body }),
+ *   {
+ *     onSuccess: (saved) => toast.success(`Updated ${saved.name}`),
+ *     onError: (err) => toast.error(err),
+ *   },
+ * );
+ *
+ * updateUser.mutate({ name: 'Alice' });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optimistic update with rollback via the `ctx` returned from `onMutate`
+ * const updateUser = mutationResource<User, User, Partial<User>, { prev: User | null }>(
+ *   (body) => ({ url: `/api/users/${userId()}`, method: 'PATCH', body }),
+ *   {
+ *     onMutate: (patch) => {
+ *       const prev = current();
+ *       current.update((u) => (u ? { ...u, ...patch } : u));
+ *       return { prev };
+ *     },
+ *     onError: (_err, { prev }) => current.set(prev),
+ *   },
+ * );
+ * ```
  */
-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 };

package/package.json

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