@mmstack/resource 19.7.1 → 19.7.2

package/fesm2022/mmstack-resource.mjs

@@ -2510,6 +2510,57 @@ 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`.
+ * @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),
+ *   },
+ * );
+ * ```
+ */
+// The request callback maps the mutation value into an HTTP request. `body` is a
+// free-form request field (Angular's `body?: unknown`), independent of `TMutation`
+// and optional — so bodyless POSTs and transforms (e.g. params → `FormData`) are fine.
 function mutationResource(request, options0 = {}) {
     // Two-layer option injection: per-call > provideMutationResourceOptions > provideResourceOptions.
     const globalOpts = injectResourceOptions(options0.injector);