@mmstack/resource 22.1.4 → 22.1.6

package/package.json

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

package/types/mmstack-resource.d.ts

@@ -1049,14 +1049,38 @@ declare function manualQueryResource<TResult, TRaw = TResult>(request: () => Htt
 declare function manualQueryResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | string | undefined | void, options?: QueryResourceOptions<TResult, TRaw>): ManualQueryResourceRef<TResult | undefined>;
 
 /**
- * @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;
+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.
+ */
+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.
+ */
+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
@@ -1109,10 +1133,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`.
@@ -1167,11 +1194,28 @@ type MutationResourceRef<TResult, TMutation = TResult, TICTX = void> = Omit<Quer
      * @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).
@@ -1222,7 +1266,12 @@ 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>;
+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>;
+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>;
 
-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 { Cache, MutationCancelledError, 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, MutationCancellationReason, MutationQueueOptions, MutationResourceOptions, MutationResourceRef, QueryResourceOptions, QueryResourceRef, RefreshOptions, RequestContext, ResourceCacheOptions, ResourceRequestFn, TransitionRegistration };