@mmstack/resource 19.6.4 → 19.6.6

package/lib/mutation-resource.d.ts

@@ -2,14 +2,38 @@ import { type HttpResourceRequest } from '@angular/common/http';
 import { type Provider, type Signal, type ValueEqualityFn } from '@angular/core';
 import { type QueryResourceOptions, type QueryResourceRef } from './query-resource';
 /**
- * @internal
- * Helper type for inferring the request body type based on the HTTP method.
+ * Why a {@link MutationResourceRef.mutateAsync} promise was cancelled — a closed
+ * set so consumers can branch on the cause without parsing the message:
+ * - `'superseded'`: a newer mutation replaced it (latest-wins).
+ * - `'queue-cleared'`: dropped from the queue by `clearQueue()`.
+ * - `'queue-key-changed'`: dropped from the queue by a reactive `key` change.
+ * - `'destroyed'`: the resource was destroyed while it was pending/in flight.
+ * - `'no-request'`: `request()` returned `undefined`, so nothing was sent.
  */
-type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMethod extends 'DELETE' | 'delete' ? Omit<HttpResourceRequest, 'body' | 'method'> & {
-    method: TMethod;
-} : Omit<HttpResourceRequest, 'body' | 'method'> & {
-    body: TMutation;
-    method: TMethod;
+export type MutationCancellationReason = 'superseded' | 'queue-cleared' | 'queue-key-changed' | 'destroyed' | 'no-request';
+/**
+ * Rejection reason for a {@link MutationResourceRef.mutateAsync} promise whose
+ * mutation never completed. The {@link MutationCancelledError.type} discriminant
+ * carries the cause ({@link MutationCancellationReason}); the message is a
+ * human-readable elaboration of it.
+ *
+ * Only `mutateAsync` promises reject with this; plain `mutate()` calls have no
+ * promise and so produce no (potentially unhandled) rejection.
+ */
+export declare class MutationCancelledError extends Error {
+    readonly type: MutationCancellationReason;
+    constructor(type: MutationCancellationReason, message: string);
+}
+/**
+ * Object form of the `queue` option. Enabling the queue serializes mutations
+ * into a FIFO that runs one-at-a-time.
+ */
+export type MutationQueueOptions = {
+    /**
+     * Reactive queue key. When its returned value changes, the *pending* (not-yet-fired)
+     * queued mutations are dropped; an in-flight mutation is unaffected. e.g. `key: () => selectedId()`.
+     */
+    key?: () => string | number;
 };
 /**
  * Options for configuring a `mutationResource`. Inherits from
@@ -62,10 +86,13 @@ export type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult
      */
     onSettled?: (ctx: NoInfer<TCTX>) => void;
     /**
-     * Whether to queue the mutation requests and execute them in series. For example if network is unavailable or circuit breaker is open.
+     * Queue mutations and run them one-at-a-time in series, instead of latest-wins
+     * superseding (e.g. while offline or the circuit breaker is open). Pass
+     * {@link MutationQueueOptions} for a reactive `key` that resets the pending queue.
+     * The pending queue can also be cleared via `ref.clearQueue()`.
      * @default false
      */
-    queue?: boolean;
+    queue?: boolean | MutationQueueOptions;
     /**
      * Cache entries to invalidate after a SUCCESSFUL mutation — the declarative
      * alternative to calling `injectQueryCache().invalidatePrefix(...)` in `onSuccess`.
@@ -120,11 +147,28 @@ export type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Om
      * @param ctx An optional initial context value that will be passed to the `onMutate` callback.
      */
     mutate: (value: TMutation, ctx?: TICTX) => void;
+    /**
+     * Executes the mutation and returns a `Promise`
+     *
+     * If the mutation never completes — superseded by a newer `mutate`/`mutateAsync`
+     * (latest-wins), dropped from the queue (`clearQueue` / queue `key` change),
+     * abandoned on `destroy()`, or its `request()` returned `undefined` — the
+     * promise rejects with a {@link MutationCancelledError}.
+     *
+     * @param value The mutation value (usually the request body).
+     * @param ctx An optional initial context value that will be passed to the `onMutate` callback.
+     */
+    mutateAsync: (value: TMutation, ctx?: TICTX) => Promise<TResult>;
     /**
      * A signal that holds the current mutation request, or `null` if no mutation is in progress.
      * This can be useful for tracking the state of the mutation or for displaying loading indicators.
      */
     current: Signal<TMutation | null>;
+    /**
+     * Drops all *pending* queued mutations; an in-flight mutation is unaffected.
+     * Noops when `queue` is not enabled.
+     */
+    clearQueue: () => void;
 };
 /**
  * Creates a resource for performing mutations (e.g., POST, PUT, PATCH, DELETE requests).
@@ -175,5 +219,9 @@ 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, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
-export {};
+export declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX>(request: (params: TMutation) => (Omit<HttpResourceRequest, 'body' | 'method'> & {
+    method: 'DELETE' | 'delete';
+}) | undefined | void, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
+export declare function mutationResource<TResult, TRaw = TResult, TMutation = TResult, TCTX = void, TICTX = TCTX>(request: (params: TMutation) => (Omit<HttpResourceRequest, 'body'> & {
+    body: TMutation;
+}) | undefined | void, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/resource",
-  "version": "19.6.4",
+  "version": "19.6.6",
   "keywords": [
     "angular",
     "signals",