@mmstack/resource 19.6.4 → 19.6.6

package/README.md

@@ -279,6 +279,22 @@ mutationResource(
 
 The `TCTX` returned from `onMutate` flows into `onError` / `onSuccess` / `onSettled`. The optional `initialCtx` second arg to `.mutate(value, initialCtx)` flows into `onMutate` as its second argument.
 
+### Awaiting a mutation (`mutateAsync`)
+
+`.mutate()` is fire-and-forget. When you need to `await` the outcome — a form submit handler, an async validator — use `.mutateAsync()`, which returns a `Promise` that resolves with the result or rejects with the error. The lifecycle hooks still run exactly as with `.mutate()`.
+
+```typescript
+try {
+  const saved = await createPost.mutateAsync(post);
+  router.navigate(['/posts', saved.id]);
+} catch (e) {
+  if (e instanceof MutationCancelledError) return; // never ran — see below
+  toast.error('Failed to save');
+}
+```
+
+If the mutation never completes — superseded by a newer one (latest-wins), dropped from the queue (`clearQueue()` / a `key` change), abandoned on `destroy()`, or its `request()` returned `undefined` — the promise rejects with a `MutationCancelledError` whose `.type` (`MutationCancellationReason`) tells you which. Awaiters that don't expect cancellation should rethrow it. (Plain `.mutate()` has no promise, so it never produces an unhandled rejection.)
+
 ### Queuing
 
 By default, calling `.mutate()` while another mutation is in flight starts immediately — concurrent mutations run in parallel. With `queue: true`, mutations are serialized:
@@ -316,13 +332,42 @@ mutationResource(request, { triggerOnSameRequest: true });
 
 A mutation also honours the `register` option — but it registers the **mutation ref itself** into the transition scope (its internal query is never registered), so a `<mm-suspense>`/transition reacts to the mutation's own `pending` state. See [transitions & Suspense](#transitions--suspense).
 
+### File uploads & progress (`multipart/form-data`)
+
+There's no special upload API — return a `FormData` body and `HttpClient` sets the `multipart/form-data` boundary for you. Opt into upload progress with `reportProgress: true` and read the `progress` signal (an `HttpProgressEvent`).
+
+```typescript
+const upload = mutationResource<UploadResult, UploadResult, FormData>((form) => ({
+  url: '/api/upload',
+  method: 'POST',
+  body: form,
+  reportProgress: true, // opt in to progress events
+}));
+
+// trigger it:
+const form = new FormData();
+form.append('file', file);
+upload.mutate(form);
+
+// derive a percentage in a computed / template:
+readonly pct = computed(() => {
+  const p = upload.progress();
+  return p?.total ? Math.round((p.loaded / p.total) * 100) : null;
+});
+```
+
+`FormData`, `File`, and `Blob` bodies are hashed structurally for dedup/cache keys (a `File` by name + type + size + lastModified), so distinct files never collide. To re-upload the **same** file while one is already in flight, pair it with `triggerOnSameRequest: true`.
+
 ### Return shape (`MutationResourceRef<T, TMutation>`)
 
-| Member                                        | Type                        | Notes                                                  |
-| --------------------------------------------- | --------------------------- | ------------------------------------------------------ |
-| `mutate`                                      | `(value, ctx?) => void`     | Trigger the mutation.                                  |
-| `current`                                     | `Signal<TMutation \| null>` | The value currently being mutated (or `null` if idle). |
-| `status` / `error` / `isLoading` / `disabled` | as in `QueryResourceRef`    | –                                                      |
+| Member                                        | Type                                       | Notes                                                  |
+| --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------ |
+| `mutate`                                      | `(value, ctx?) => void`                    | Trigger the mutation (fire-and-forget).               |
+| `mutateAsync`                                 | `(value, ctx?) => Promise<TResult>`        | Trigger and `await` the result; rejects with the error or a `MutationCancelledError`. |
+| `current`                                     | `Signal<TMutation \| null>`                | The value currently being mutated (or `null` if idle). |
+| `progress`                                    | `Signal<HttpProgressEvent \| undefined>`   | Upload/download progress when `reportProgress: true`.  |
+| `status` / `error` / `isLoading` / `disabled` | as in `QueryResourceRef`                   | –                                                      |
+| `headers` / `statusCode`                      | as in `QueryResourceRef`                   | Response metadata, when available.                     |
 
 (Mutations deliberately don't expose `value`, `hasValue`, `set`, `update`, or `prefetch` — those don't make sense for one-off writes.)
 

package/fesm2022/mmstack-resource.mjs

@@ -2359,6 +2359,23 @@ function manualQueryResource(request, options) {
 }
 
 const NULL_VALUE = Symbol('@mmstack/resource:null');
+/**
+ * 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.
+ */
+class MutationCancelledError extends Error {
+    type;
+    constructor(type, message) {
+        super(message);
+        this.type = type;
+        this.name = 'MutationCancelledError';
+    }
+}
 const MUTATION_RESOURCE_OPTIONS = new InjectionToken('@mmstack/resource:mutation-resource-options', { factory: () => ({}) });
 /**
  * Layer 2 (mutation): default options for every `mutationResource`, inheriting + overriding the
@@ -2372,55 +2389,6 @@ function injectMutationResourceOptions(injector) {
         ? injector.get(MUTATION_RESOURCE_OPTIONS)
         : inject(MUTATION_RESOURCE_OPTIONS);
 }
-/**
- * Creates a resource for performing mutations (e.g., POST, PUT, PATCH, DELETE requests).
- * Unlike `queryResource`, `mutationResource` is designed for one-off operations that change data.
- * It does *not* cache responses and does not provide a `value` signal.  Instead, it focuses on
- * managing the mutation lifecycle (pending, error, success) and provides callbacks for handling
- * these states.
- *
- * @param request A function that returns the base `HttpResourceRequest` to be made. This function is called reactively. The parameter is the mutation value provided by the `mutate` method.
- * @param options Configuration options for the mutation resource.  This includes callbacks
- *               for `onMutate`, `onError`, `onSuccess`, and `onSettled`.
- * @typeParam TResult - The type of the expected result from the mutation.
- * @typeParam TRaw - The raw response type from the HTTP request (defaults to TResult).
- * @typeParam TMutation - The type of the mutation value (the request body).
- * @typeParam TICTX - The type of the initial context value passed to `onMutate`.
- * @typeParam TCTX - The type of the context value returned by `onMutate`.
- * @typeParam TMethod - The HTTP method to be used for the mutation (defaults to `HttpResourceRequest['method']`).
- * @returns A `MutationResourceRef` instance, which provides methods for triggering the mutation
- *          and observing its status.
- *
- * @example
- * ```ts
- * // Basic PATCH mutation
- * const updateUser = mutationResource<User, User, Partial<User>>(
- *   (body) => ({ url: `/api/users/${userId()}`, method: 'PATCH', body }),
- *   {
- *     onSuccess: (saved) => toast.success(`Updated ${saved.name}`),
- *     onError: (err) => toast.error(err),
- *   },
- * );
- *
- * updateUser.mutate({ name: 'Alice' });
- * ```
- *
- * @example
- * ```ts
- * // Optimistic update with rollback via the `ctx` returned from `onMutate`
- * const updateUser = mutationResource<User, User, Partial<User>, { prev: User | null }>(
- *   (body) => ({ url: `/api/users/${userId()}`, method: 'PATCH', body }),
- *   {
- *     onMutate: (patch) => {
- *       const prev = current();
- *       current.update((u) => (u ? { ...u, ...patch } : u));
- *       return { prev };
- *     },
- *     onError: (_err, { prev }) => current.set(prev),
- *   },
- * );
- * ```
- */
 function mutationResource(request, options0 = {}) {
     // Two-layer option injection: per-call > provideMutationResourceOptions > provideResourceOptions.
     const globalOpts = injectResourceOptions(options0.injector);
@@ -2437,11 +2405,6 @@ function mutationResource(request, options0 = {}) {
     const { onMutate, onError, onSuccess, onSettled, equal, register, equalRequest, invalidates, ...rest } = options;
     const cache = invalidates ? injectQueryCache(options.injector) : undefined;
     const requestEqual = equalRequest ?? createEqualRequest(equal);
-    // A mutation is an imperative command, so `triggerOnSameRequest` means "fire on EVERY mutate(),
-    // even with an identical body". By default we dedup an identical value/request while one is in
-    // flight (double-click protection); when this is set, both the `next` and `req` dedup are bypassed
-    // so a repeat click isn't silently swallowed mid-flight. (Otherwise it'd be dropped until `next`
-    // resets to NULL on settle — the "every other click" symptom.)
     const triggerOnSame = options.triggerOnSameRequest ?? false;
     const eq = equal ?? Object.is;
     const next = signal(NULL_VALUE, {
@@ -2455,25 +2418,19 @@ function mutationResource(request, options0 = {}) {
             return eq(a, b);
         },
     });
-    const queue = signal([]);
-    let ctx = undefined;
-    const queueRef = effect(() => {
-        const nextInQueue = queue().at(0);
-        if (nextInQueue === undefined || next() !== NULL_VALUE)
-            return;
-        queue.update((q) => q.slice(1));
-        const [value, ictx] = nextInQueue;
-        try {
-            ctx = onMutate?.(value, ictx);
-            next.set(value);
-        }
-        catch (mutationErr) {
-            ctx = undefined;
-            next.set(NULL_VALUE);
-            if (isDevMode())
-                console.error('[@mmstack/resource]: error thrown in onMutate hook, mutation was not applied', mutationErr);
-        }
-    }, { injector: options.injector });
+    const queueEnabled = !!options.queue;
+    const queueKeyFn = typeof options.queue === 'object' ? options.queue.key : undefined;
+    const queue = linkedSignal({
+        source: () => queueKeyFn?.(),
+        computation: (_key, prev) => {
+            // On a queue key change the previous pending entries are dropped — reject any
+            // mutateAsync promises waiting on them so awaiters don't hang.
+            if (prev)
+                for (const [, , deferred] of untracked(prev.value))
+                    deferred?.reject(new MutationCancelledError('queue-key-changed', 'mutation dropped: queue key changed before it ran'));
+            return signal([]);
+        },
+    });
     const req = computed(() => {
         const nr = next();
         if (nr === NULL_VALUE)
@@ -2490,6 +2447,57 @@ function mutationResource(request, options0 = {}) {
             return requestEqual(a, b);
         },
     });
+    let ctx = undefined;
+    let currentDeferred;
+    const begin = (value, ictx, deferred) => {
+        let nextCtx;
+        try {
+            nextCtx = onMutate?.(value, ictx);
+        }
+        catch (mutationErr) {
+            // match legacy mutate(): the throw aborts the mutation and resets state
+            ctx = undefined;
+            next.set(NULL_VALUE);
+            deferred?.reject(mutationErr);
+            if (isDevMode())
+                console.error('[@mmstack/resource]: error thrown in onMutate hook, mutation was not applied', mutationErr);
+            return;
+        }
+        ctx = nextCtx;
+        currentDeferred = deferred;
+        next.set(value);
+        if (deferred && untracked(req) === undefined) {
+            ctx = undefined;
+            currentDeferred = undefined;
+            next.set(NULL_VALUE);
+            deferred.reject(new MutationCancelledError('no-request', 'mutation not sent: request() returned undefined'));
+        }
+    };
+    const supersedeInFlight = () => {
+        if (untracked(next) === NULL_VALUE)
+            return;
+        if (isDevMode())
+            console.warn('[@mmstack/resource]: mutate() called while another mutation was in flight — the previous mutation was superseded (latest-wins) and its onSettled was invoked. Use `queue: true` for sequential mutations.');
+        try {
+            onSettled?.(ctx);
+        }
+        catch (settleErr) {
+            if (isDevMode())
+                console.error('[@mmstack/resource]: error thrown in onSettled hook for a superseded mutation', settleErr);
+        }
+        currentDeferred?.reject(new MutationCancelledError('superseded', 'mutation superseded by a newer mutation (latest-wins)'));
+        currentDeferred = undefined;
+        ctx = undefined;
+    };
+    const queueRef = effect(() => {
+        const q = queue(); // subscribe to swaps (key change / clearQueue)
+        const nextInQueue = q().at(0); // subscribe to contents
+        if (nextInQueue === undefined || next() !== NULL_VALUE)
+            return;
+        q.update((arr) => arr.slice(1));
+        const [value, ictx, deferred] = nextInQueue;
+        begin(value, ictx, deferred);
+    }, { injector: options.injector });
     const lastValue = linkedSignal({
         source: next,
         computation: (next, prev) => {
@@ -2548,8 +2556,12 @@ function mutationResource(request, options0 = {}) {
         return NULL_VALUE;
     }), filter((v) => v !== NULL_VALUE), takeUntilDestroyed(destroyRef))
         .subscribe((result) => {
-        if (result.status === 'error')
+        const deferred = currentDeferred;
+        currentDeferred = undefined;
+        if (result.status === 'error') {
             onError?.(result.error, ctx);
+            deferred?.reject(result.error);
+        }
         else {
             onSuccess?.(result.value, ctx);
             if (cache && invalidates) {
@@ -2557,61 +2569,61 @@ function mutationResource(request, options0 = {}) {
                 const prefixes = typeof invalidates === 'function'
                     ? invalidates(result.value, (mutation === NULL_VALUE ? undefined : mutation))
                     : invalidates;
-                // auto-keys are `${method}:${url}:...` — a `GET:`-prefixed url prefix hits
-                // the url with any params/subpaths and every varyHeaders variant
                 for (const prefix of prefixes)
                     cache.invalidatePrefix(`GET:${prefix}`);
             }
+            deferred?.resolve(result.value);
         }
         onSettled?.(ctx);
         ctx = undefined;
         next.set(NULL_VALUE);
     });
-    const shouldQueue = options.queue ?? false;
     const ref = {
         ...resource,
         destroy: () => {
             // queue first — a late queue flush must not poke an already-destroyed resource
             queueRef.destroy();
             statusSub.unsubscribe();
+            // reject any outstanding mutateAsync promises so awaiters don't hang
+            const cancelled = new MutationCancelledError('destroyed', 'mutation abandoned: resource destroyed');
+            currentDeferred?.reject(cancelled);
+            currentDeferred = undefined;
+            for (const [, , deferred] of untracked(queue)())
+                deferred?.reject(cancelled);
             resource.destroy();
         },
         mutate: (value, ictx) => {
-            if (shouldQueue) {
-                return queue.update((q) => [...q, [value, ictx]]);
+            if (queueEnabled) {
+                queue().update((arr) => [...arr, [value, ictx, undefined]]);
+                return;
+            }
+            supersedeInFlight();
+            begin(value, ictx, undefined);
+        },
+        mutateAsync: (value, ictx) => {
+            const deferred = Promise.withResolvers();
+            if (queueEnabled) {
+                queue().update((arr) => [...arr, [value, ictx, deferred]]);
             }
             else {
-                // latest-wins: a mutation already in flight gets superseded (its request is
-                // aborted by the request change), so its onSuccess/onError will never fire —
-                // settle its context NOW so optimistic state can be rolled back/cleaned up
-                if (untracked(next) !== NULL_VALUE) {
-                    if (isDevMode())
-                        console.warn('[@mmstack/resource]: mutate() called while another mutation was in flight — the previous mutation was superseded (latest-wins) and its onSettled was invoked. Use `queue: true` for sequential mutations.');
-                    try {
-                        onSettled?.(ctx);
-                    }
-                    catch (settleErr) {
-                        if (isDevMode())
-                            console.error('[@mmstack/resource]: error thrown in onSettled hook for a superseded mutation', settleErr);
-                    }
-                    ctx = undefined;
-                }
-                try {
-                    ctx = onMutate?.(value, ictx);
-                    next.set(value);
-                }
-                catch (mutationErr) {
-                    ctx = undefined;
-                    next.set(NULL_VALUE);
-                    if (isDevMode())
-                        console.error('[@mmstack/resource]: error thrown in onMutate hook, mutation was not applied', mutationErr);
-                }
+                supersedeInFlight();
+                begin(value, ictx, deferred);
             }
+            return deferred.promise;
         },
         current: computed(() => {
             const nv = next();
             return nv === NULL_VALUE ? null : nv;
         }),
+        clearQueue: () => {
+            if (!queueEnabled)
+                return;
+            const dropped = untracked(queue)();
+            queue.set(signal([]));
+            // reject mutateAsync promises whose entries we just dropped
+            for (const [, , deferred] of dropped)
+                deferred?.reject(new MutationCancelledError('queue-cleared', 'mutation dropped: queue cleared before it ran'));
+        },
         // redeclare disabled with last value so that it is not affected by the resource's internal disablement logic
         disabled: computed(() => cb.isOpen() || lastValueRequest() === undefined),
     };
@@ -2623,5 +2635,5 @@ function mutationResource(request, options0 = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { Cache, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
+export { Cache, MutationCancelledError, PAUSED, applyResourceRegistration, createCacheInterceptor, createCircuitBreaker, createDedupeRequestsInterceptor, hashRequest, infiniteQueryResource, injectQueryCache, injectResourceOptions, manualQueryResource, mutationResource, noDedupe, provideCircuitBreakerDefaultOptions, provideMutationResourceOptions, provideQueryCache, provideQueryResourceOptions, provideResourceOptions, provideTypedResourceOptions, queryResource };
 //# sourceMappingURL=mmstack-resource.mjs.map