@mmstack/resource 21.4.5 → 21.5.0

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:
@@ -295,7 +311,7 @@ After a successful mutation, related query caches usually need refreshing. Inste
 
 ```typescript
 mutationResource((p: Post) => ({ url: '/api/posts', method: 'POST', body: p }), {
-  invalidates: ['/api/posts'], // every cached GET under /api/posts (any params, subpaths, varyHeaders variants)
+  invalidates: ['/api/posts'], // every cached entry under /api/posts (any method, params, subpaths, varyHeaders variants)
 });
 
 // or derived from the result:
@@ -304,7 +320,7 @@ mutationResource(request, {
 });
 ```
 
-Strings are URL prefixes matched against auto-generated `GET` keys. Plain prefix matching also catches sibling paths sharing the prefix (`/api/posts-archive`) — pass `'/api/posts/'` or an exact URL to narrow. Entries keyed by a custom `hash` follow that function's shape instead; invalidate those via `injectQueryCache().invalidateWhere`.
+Strings are URL prefixes matched against the request URL of every cached entry, regardless of HTTP method (so a POST-bodied search cached under the same URL is cleared too). Plain prefix matching also catches sibling paths sharing the prefix (`/api/posts-archive`) — pass `'/api/posts/'` or an exact URL to narrow. Keys a custom `hash` merely *prepends* a namespace to (e.g. a tenant/`sub`) are still matched; keys that abandon the auto shape entirely need an `invalidateMatcher: (urlPrefix) => (key) => boolean` (set per-mutation or globally via `provideMutationResourceOptions`), or manual `injectQueryCache().invalidateWhere`.
 
 ### Re-firing with an identical body (`triggerOnSameRequest`)
 
@@ -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.)
 
@@ -431,14 +476,14 @@ With `syncTabs: true`, cache invalidations and updates broadcast via `BroadcastC
 
 ```typescript
 const cache = injectQueryCache<MyResponse>();
-cache.invalidate('GET:/api/posts:json'); // drop one entry by exact key
-cache.invalidatePrefix('GET:/api/posts'); // drop every key under a URL prefix
+cache.invalidateUrlPrefix('/api/posts'); // drop every entry under a URL prefix, any method
 cache.invalidateWhere((key) => key.includes('userId=42')); // arbitrary predicates
+cache.invalidatePrefix('raw-key-prefix'); // match the raw key string from its start
 cache.clear(); // drop EVERYTHING — memory, persisted rows, other tabs
 cache.store(key, value, staleTime, ttl); // imperative write
 ```
 
-Auto-generated keys have the shape `${method}:${url}:${responseType}[:params][:body][:vary]` — prefix matching against `GET:${url}` is the common move. Call `clear()` on logout so no prior user's responses survive. For observability there's a read-only `cache.stats()` signal (`{ size, hits, misses }`) — handy for a debug panel; it deliberately exposes no mutation surface.
+Auto-generated keys have the shape `${method}${SEP}${url}${SEP}${responseType}[${SEP}params][${SEP}body][${SEP}vary]`, where `SEP` is a content-rare control-character delimiter (treat keys as opaque — don't hand-build them). `invalidateUrlPrefix(urlPrefix)` is the common move: it recovers the URL field structurally, so it matches **any** HTTP method and even keys a custom `cache.hash` prepends a namespace to. For a fully-custom key scheme it takes an optional `match` (`(urlPrefix) => (key) => boolean`). Call `clear()` on logout so no prior user's responses survive. For observability there's a read-only `cache.stats()` signal (`{ size, hits, misses }`) — handy for a debug panel; it deliberately exposes no mutation surface.
 
 Prefer the declarative [`invalidates`](#declarative-invalidation-invalidates) option on `mutationResource` for the common "mutation succeeded → refresh related queries" case.
 
@@ -624,7 +669,7 @@ Declarative — the common case:
 
 ```typescript
 mutationResource((p: Post) => ({ url: '/posts', method: 'POST', body: p }), {
-  invalidates: ['/posts'], // every cached GET under /posts, params + subpaths + vary variants
+  invalidates: ['/posts'], // every cached entry under /posts, any method + params + subpaths + vary variants
 });
 ```