@mmstack/resource 19.6.3 → 19.6.5

package/lib/mutation-resource.d.ts

@@ -11,6 +11,17 @@ type NextRequest<TMethod extends HttpResourceRequest['method'], TMutation> = TMe
     body: TMutation;
     method: TMethod;
 };
+/**
+ * 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
  * `QueryResourceOptions` (minus options that don't apply to mutations:
@@ -62,10 +73,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`.
@@ -125,6 +139,11 @@ export type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Om
      * 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).

package/package.json

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