@mmstack/resource 22.1.5 → 22.1.6

package/package.json

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

package/types/mmstack-resource.d.ts

@@ -1049,15 +1049,28 @@ 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.
@@ -1181,6 +1194,18 @@ 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.
@@ -1241,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, MutationQueueOptions, 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 };