@mmstack/resource 22.1.4 → 22.1.5

package/package.json

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

package/types/mmstack-resource.d.ts

@@ -1058,6 +1058,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.
+ */
+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:
@@ -1109,10 +1120,13 @@ type MutationResourceOptions<TResult, TRaw = TResult, TMutation = TResult, TCTX
      */
     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`.
@@ -1172,6 +1186,11 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
      * 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).
@@ -1225,4 +1244,4 @@ 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, options0?: MutationResourceOptions<TResult, TRaw, TMutation, TCTX, TICTX>): MutationResourceRef<TResult, TMutation, TICTX>;
 
 export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
-export type { CacheEntry, CleanupType, CommonResourceOptions, DisabledReason, InfiniteQueryResourceOptions, InfiniteQueryResourceRef, InfiniteRequestContext, ManualQueryResourceRef, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RefreshOptions, RequestContext, ResourceCacheOptions, ResourceRequestFn, TransitionRegistration };
+export type { CacheEntry, CleanupType, CommonResourceOptions, DisabledReason, InfiniteQueryResourceOptions, InfiniteQueryResourceRef, InfiniteRequestContext, ManualQueryResourceRef, MutationQueueOptions, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RefreshOptions, RequestContext, ResourceCacheOptions, ResourceRequestFn, TransitionRegistration };