rastack 0.0.16 → 0.0.20

package/sync/hooks.ts

@@ -1,450 +1,450 @@
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useState,
-  useSyncExternalStore,
-} from "react";
-import { API } from "../hooks/query/api";
-import { useSyncEngine, useSyncEngineOptional } from "./provider";
-import { tempId, uuid4 } from "./transactions";
-import {
-  EngineStatus,
-  EntityDescriptor,
-  entityKey,
-  TransactionOp,
-} from "./types";
-
-export function useEngineStatus(): EngineStatus {
-  const engine = useSyncEngine();
-  return useSyncExternalStore(
-    (listener) => engine.subscribeStatus(listener),
-    () => engine.getStatus(),
-    () => engine.getStatus(),
-  );
-}
-
-export interface EntityListOptions<TRow> {
-  /** Local predicate applied to every row. */
-  filter?: (row: TRow) => boolean;
-  /** Local comparator. */
-  sort?: (a: TRow, b: TRow) => number;
-  /** Local search text, matched with searchFunction (or against searchFields). */
-  search?: string;
-  searchFields?: (keyof TRow)[];
-  searchFunction?: (search: string, row: TRow) => boolean;
-}
-
-export interface EntityListResult<TRow> {
-  data: TRow[] | undefined;
-  isLoading: boolean;
-  isReady: boolean;
-}
-
-/**
- * List read for a sync-mode entity — served from the local store: instant
- * after bootstrap, reactive to every delta and optimistic write thereafter.
- * Filtering, sorting and search all run locally.
- */
-export function useEntityList<TRow = any>(
-  entity: EntityDescriptor<TRow>,
-  options?: EntityListOptions<TRow>,
-): EntityListResult<TRow> {
-  const engine = useSyncEngine();
-  const key = entityKey(entity);
-
-  // Lazy entities partial-bootstrap the first time a component asks.
-  useEffect(() => {
-    void engine.ensureEntity(key).catch(() => {});
-  }, [engine, key]);
-
-  const rows = useSyncExternalStore(
-    (listener) => engine.store.subscribe(key, listener),
-    () => engine.store.getList(key),
-    () => engine.store.getList(key),
-  ) as TRow[];
-  const isReady = useSyncExternalStore(
-    (listener) => engine.store.subscribe(key, listener),
-    () => engine.store.isReady(key),
-    () => engine.store.isReady(key),
-  );
-
-  const { filter, sort, search, searchFields, searchFunction } = options || {};
-  const data = useMemo(() => {
-    let result = rows;
-    if (filter) {
-      result = result.filter(filter);
-    }
-    if (search) {
-      const lowered = search.toLowerCase();
-      const matches =
-        searchFunction ||
-        ((text: string, row: TRow) => {
-          const fields = searchFields || (Object.keys(row as any) as any[]);
-          return fields.some((field: any) =>
-            String((row as any)[field] ?? "")
-              .toLowerCase()
-              .includes(text.toLowerCase()),
-          );
-        });
-      result = result.filter((row) => matches(lowered, row));
-    }
-    if (sort) {
-      result = [...result].sort(sort);
-    }
-    return result;
-  }, [rows, filter, sort, search, searchFields, searchFunction]);
-
-  return {
-    data: isReady ? data : undefined,
-    isLoading: !isReady,
-    isReady,
-  };
-}
-
-export interface EntityRecordResult<TRow> {
-  data: TRow | undefined;
-  isLoading: boolean;
-  isReady: boolean;
-}
-
-/** Single-record read for a sync-mode entity, served from the local store. */
-export function useEntityRecord<TRow = any>(
-  entity: EntityDescriptor<TRow>,
-  id: string | number | undefined,
-): EntityRecordResult<TRow> {
-  const engine = useSyncEngine();
-  const key = entityKey(entity);
-
-  useEffect(() => {
-    void engine.ensureEntity(key).catch(() => {});
-  }, [engine, key]);
-
-  const resolvedId =
-    id === undefined ? undefined : engine.queue.resolveAlias(String(id));
-
-  const data = useSyncExternalStore(
-    (listener) => engine.store.subscribe(key, listener),
-    () =>
-      resolvedId === undefined
-        ? undefined
-        : (engine.store.get(key, resolvedId) as TRow | undefined),
-    () =>
-      resolvedId === undefined
-        ? undefined
-        : (engine.store.get(key, resolvedId) as TRow | undefined),
-  );
-  const isReady = useSyncExternalStore(
-    (listener) => engine.store.subscribe(key, listener),
-    () => engine.store.isReady(key),
-    () => engine.store.isReady(key),
-  );
-
-  return { data, isLoading: !isReady && data === undefined, isReady };
-}
-
-export interface MutationState<TResult> {
-  status: "idle" | "loading" | "success" | "error";
-  data: TResult | undefined;
-  error: unknown;
-}
-
-export interface EntityMutationResult<TVariables, TResult> {
-  /**
-   * Fire-and-forget: applies locally at once and syncs in the background.
-   * This is the default write mode.
-   */
-  mutate: (
-    variables: TVariables,
-    callbacks?: {
-      onSuccess?: (data: TResult) => void;
-      onError?: (error: unknown) => void;
-    },
-  ) => void;
-  /** Awaits the server acknowledgement (the local apply already happened). */
-  mutateAsync: (variables: TVariables) => Promise<TResult>;
-  isLoading: boolean;
-  isError: boolean;
-  isSuccess: boolean;
-  data: TResult | undefined;
-  error: unknown;
-  status: MutationState<TResult>["status"];
-  reset: () => void;
-}
-
-function useMutationState<TResult>() {
-  const [state, setState] = useState<MutationState<TResult>>({
-    status: "idle",
-    data: undefined,
-    error: undefined,
-  });
-  const reset = useCallback(
-    () => setState({ status: "idle", data: undefined, error: undefined }),
-    [],
-  );
-  return { state, setState, reset };
-}
-
-export interface WriteVariables<TParams, TPayload> {
-  params: TParams;
-  payload: TPayload;
-}
-
-export interface EntityMutationConfig<TParams> {
-  op: Exclude<TransactionOp, "delete">;
-  method: "post" | "put" | "patch";
-  url: (params: TParams) => string;
-  /** For updates: extract the row id from the call params. */
-  id?: (params: TParams) => string | number | undefined;
-}
-
-/**
- * Optimistic write for a sync-mode entity. The store updates immediately,
- * the transaction persists locally (offline writes replay on reconnect),
- * and the change is sent through the entity's normal REST endpoint.
- * Server rejection rolls back and reports through the error state.
- */
-export function useEntityMutation<TParams, TPayload, TResult = any>(
-  entity: EntityDescriptor,
-  config: EntityMutationConfig<TParams>,
-): EntityMutationResult<WriteVariables<TParams, TPayload>, TResult> {
-  const engine = useSyncEngine();
-  const key = entityKey(entity);
-  const { state, setState, reset } = useMutationState<TResult>();
-
-  const mutateAsync = useCallback(
-    async (variables: WriteVariables<TParams, TPayload>): Promise<TResult> => {
-      const idField = entity.idField || "id";
-      const payload = (variables.payload || {}) as Record<string, any>;
-      let id: string;
-      let original: Record<string, any> | null = null;
-
-      if (config.op === "create") {
-        if (entity.clientIds) {
-          // Client-generated UUID pk: the id is real from the start and is
-          // sent to the server with the payload.
-          id = (payload[idField] as string) || uuid4();
-          payload[idField] = id;
-        } else {
-          id = tempId();
-        }
-      } else {
-        const rawId =
-          config.id?.(variables.params) ??
-          (payload as any)[idField] ??
-          (variables.params as any)?.[idField];
-        if (rawId === undefined || rawId === null) {
-          throw new Error(
-            `Cannot resolve the ${idField} of the ${key} row being updated`,
-          );
-        }
-        id = engine.queue.resolveAlias(String(rawId));
-        const current = engine.store.get(key, id);
-        if (current) {
-          original = {};
-          Object.keys(payload).forEach((field) => {
-            original![field] = current[field];
-          });
-        }
-      }
-
-      setState({ status: "loading", data: undefined, error: undefined });
-      try {
-        const data = (await engine.queue.enqueue({
-          entity: key,
-          op: config.op,
-          id,
-          method: config.method,
-          url: config.url(variables.params),
-          payload,
-          original,
-        })) as TResult;
-        setState({ status: "success", data, error: undefined });
-        return data;
-      } catch (error) {
-        setState({ status: "error", data: undefined, error });
-        throw error;
-      }
-    },
-    [engine, key, config.op, config.method], // eslint-disable-line react-hooks/exhaustive-deps
-  );
-
-  const mutate = useCallback(
-    (
-      variables: WriteVariables<TParams, TPayload>,
-      callbacks?: {
-        onSuccess?: (data: TResult) => void;
-        onError?: (error: unknown) => void;
-      },
-    ) => {
-      mutateAsync(variables)
-        .then((data) => callbacks?.onSuccess?.(data))
-        .catch((error) => {
-          if (callbacks?.onError) {
-            callbacks.onError(error);
-          }
-        });
-    },
-    [mutateAsync],
-  );
-
-  return {
-    mutate,
-    mutateAsync,
-    isLoading: state.status === "loading",
-    isError: state.status === "error",
-    isSuccess: state.status === "success",
-    data: state.data,
-    error: state.error,
-    status: state.status,
-    reset,
-  };
-}
-
-export interface EntityDeleteConfig {
-  url: (id: string) => string;
-}
-
-/** Optimistic delete for a sync-mode entity (server-side it's a soft delete). */
-export function useEntityDelete<TResult = any>(
-  entity: EntityDescriptor,
-  config: EntityDeleteConfig,
-): EntityMutationResult<{ id?: string }, TResult> {
-  const engine = useSyncEngine();
-  const key = entityKey(entity);
-  const { state, setState, reset } = useMutationState<TResult>();
-
-  const mutateAsync = useCallback(
-    async (variables: { id?: string }): Promise<TResult> => {
-      if (variables.id === undefined) {
-        throw new Error("ID is required for delete operation");
-      }
-      const id = engine.queue.resolveAlias(String(variables.id));
-      const original = engine.store.get(key, id) || null;
-      setState({ status: "loading", data: undefined, error: undefined });
-      try {
-        const data = (await engine.queue.enqueue({
-          entity: key,
-          op: "delete",
-          id,
-          method: "delete",
-          url: config.url(id),
-          payload: null,
-          original,
-        })) as TResult;
-        setState({ status: "success", data, error: undefined });
-        return data;
-      } catch (error) {
-        setState({ status: "error", data: undefined, error });
-        throw error;
-      }
-    },
-    [engine, key], // eslint-disable-line react-hooks/exhaustive-deps
-  );
-
-  const mutate = useCallback(
-    (
-      variables: { id?: string },
-      callbacks?: {
-        onSuccess?: (data: TResult) => void;
-        onError?: (error: unknown) => void;
-      },
-    ) => {
-      mutateAsync(variables)
-        .then((data) => callbacks?.onSuccess?.(data))
-        .catch((error) => {
-          if (callbacks?.onError) {
-            callbacks.onError(error);
-          }
-        });
-    },
-    [mutateAsync],
-  );
-
-  return {
-    mutate,
-    mutateAsync,
-    isLoading: state.status === "loading",
-    isError: state.status === "error",
-    isSuccess: state.status === "success",
-    data: state.data,
-    error: state.error,
-    status: state.status,
-    reset,
-  };
-}
-
-export interface ConfirmedMutationConfig<TParams> {
-  method: "post" | "put" | "patch" | "delete";
-  url: (params: TParams) => string;
-}
-
-/**
- * A confirmed ("sync") operation — e.g. a password change. No optimistic
- * apply, no queue, online-only: resolves only when the server has accepted
- * the write. Anything it changed flows back through the changefeed like any
- * other write.
- */
-export function useConfirmedMutation<TParams, TPayload, TResult = any>(
-  config: ConfirmedMutationConfig<TParams>,
-): EntityMutationResult<WriteVariables<TParams, TPayload>, TResult> {
-  const engine = useSyncEngineOptional();
-  const { state, setState, reset } = useMutationState<TResult>();
-
-  const mutateAsync = useCallback(
-    async (variables: WriteVariables<TParams, TPayload>): Promise<TResult> => {
-      if (typeof navigator !== "undefined" && navigator.onLine === false) {
-        throw new Error("This operation requires a network connection");
-      }
-      const api = engine?.api || API;
-      const url = config.url(variables.params);
-      setState({ status: "loading", data: undefined, error: undefined });
-      try {
-        const response =
-          config.method === "delete"
-            ? await api.delete<TResult>(url)
-            : await api[config.method]<TResult>(url, variables.payload);
-        setState({ status: "success", data: response.data, error: undefined });
-        // Whatever the operation changed will arrive via the changefeed;
-        // kick the engine so it lands promptly.
-        engine?.wake();
-        return response.data;
-      } catch (error) {
-        setState({ status: "error", data: undefined, error });
-        throw error;
-      }
-    },
-    [engine, config.method], // eslint-disable-line react-hooks/exhaustive-deps
-  );
-
-  const mutate = useCallback(
-    (
-      variables: WriteVariables<TParams, TPayload>,
-      callbacks?: {
-        onSuccess?: (data: TResult) => void;
-        onError?: (error: unknown) => void;
-      },
-    ) => {
-      mutateAsync(variables)
-        .then((data) => callbacks?.onSuccess?.(data))
-        .catch((error) => {
-          if (callbacks?.onError) {
-            callbacks.onError(error);
-          }
-        });
-    },
-    [mutateAsync],
-  );
-
-  return {
-    mutate,
-    mutateAsync,
-    isLoading: state.status === "loading",
-    isError: state.status === "error",
-    isSuccess: state.status === "success",
-    data: state.data,
-    error: state.error,
-    status: state.status,
-    reset,
-  };
-}
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import { API } from "../hooks/query/api";
+import { useSyncEngine, useSyncEngineOptional } from "./provider";
+import { tempId, uuid4 } from "./transactions";
+import {
+  EngineStatus,
+  EntityDescriptor,
+  entityKey,
+  TransactionOp,
+} from "./types";
+
+export function useEngineStatus(): EngineStatus {
+  const engine = useSyncEngine();
+  return useSyncExternalStore(
+    (listener) => engine.subscribeStatus(listener),
+    () => engine.getStatus(),
+    () => engine.getStatus(),
+  );
+}
+
+export interface EntityListOptions<TRow> {
+  /** Local predicate applied to every row. */
+  filter?: (row: TRow) => boolean;
+  /** Local comparator. */
+  sort?: (a: TRow, b: TRow) => number;
+  /** Local search text, matched with searchFunction (or against searchFields). */
+  search?: string;
+  searchFields?: (keyof TRow)[];
+  searchFunction?: (search: string, row: TRow) => boolean;
+}
+
+export interface EntityListResult<TRow> {
+  data: TRow[] | undefined;
+  isLoading: boolean;
+  isReady: boolean;
+}
+
+/**
+ * List read for a sync-mode entity — served from the local store: instant
+ * after bootstrap, reactive to every delta and optimistic write thereafter.
+ * Filtering, sorting and search all run locally.
+ */
+export function useEntityList<TRow = any>(
+  entity: EntityDescriptor<TRow>,
+  options?: EntityListOptions<TRow>,
+): EntityListResult<TRow> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+
+  // Lazy entities partial-bootstrap the first time a component asks.
+  useEffect(() => {
+    void engine.ensureEntity(key).catch(() => {});
+  }, [engine, key]);
+
+  const rows = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () => engine.store.getList(key),
+    () => engine.store.getList(key),
+  ) as TRow[];
+  const isReady = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () => engine.store.isReady(key),
+    () => engine.store.isReady(key),
+  );
+
+  const { filter, sort, search, searchFields, searchFunction } = options || {};
+  const data = useMemo(() => {
+    let result = rows;
+    if (filter) {
+      result = result.filter(filter);
+    }
+    if (search) {
+      const lowered = search.toLowerCase();
+      const matches =
+        searchFunction ||
+        ((text: string, row: TRow) => {
+          const fields = searchFields || (Object.keys(row as any) as any[]);
+          return fields.some((field: any) =>
+            String((row as any)[field] ?? "")
+              .toLowerCase()
+              .includes(text.toLowerCase()),
+          );
+        });
+      result = result.filter((row) => matches(lowered, row));
+    }
+    if (sort) {
+      result = [...result].sort(sort);
+    }
+    return result;
+  }, [rows, filter, sort, search, searchFields, searchFunction]);
+
+  return {
+    data: isReady ? data : undefined,
+    isLoading: !isReady,
+    isReady,
+  };
+}
+
+export interface EntityRecordResult<TRow> {
+  data: TRow | undefined;
+  isLoading: boolean;
+  isReady: boolean;
+}
+
+/** Single-record read for a sync-mode entity, served from the local store. */
+export function useEntityRecord<TRow = any>(
+  entity: EntityDescriptor<TRow>,
+  id: string | number | undefined,
+): EntityRecordResult<TRow> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+
+  useEffect(() => {
+    void engine.ensureEntity(key).catch(() => {});
+  }, [engine, key]);
+
+  const resolvedId =
+    id === undefined ? undefined : engine.queue.resolveAlias(String(id));
+
+  const data = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () =>
+      resolvedId === undefined
+        ? undefined
+        : (engine.store.get(key, resolvedId) as TRow | undefined),
+    () =>
+      resolvedId === undefined
+        ? undefined
+        : (engine.store.get(key, resolvedId) as TRow | undefined),
+  );
+  const isReady = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () => engine.store.isReady(key),
+    () => engine.store.isReady(key),
+  );
+
+  return { data, isLoading: !isReady && data === undefined, isReady };
+}
+
+export interface MutationState<TResult> {
+  status: "idle" | "loading" | "success" | "error";
+  data: TResult | undefined;
+  error: unknown;
+}
+
+export interface EntityMutationResult<TVariables, TResult> {
+  /**
+   * Fire-and-forget: applies locally at once and syncs in the background.
+   * This is the default write mode.
+   */
+  mutate: (
+    variables: TVariables,
+    callbacks?: {
+      onSuccess?: (data: TResult) => void;
+      onError?: (error: unknown) => void;
+    },
+  ) => void;
+  /** Awaits the server acknowledgement (the local apply already happened). */
+  mutateAsync: (variables: TVariables) => Promise<TResult>;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+  data: TResult | undefined;
+  error: unknown;
+  status: MutationState<TResult>["status"];
+  reset: () => void;
+}
+
+function useMutationState<TResult>() {
+  const [state, setState] = useState<MutationState<TResult>>({
+    status: "idle",
+    data: undefined,
+    error: undefined,
+  });
+  const reset = useCallback(
+    () => setState({ status: "idle", data: undefined, error: undefined }),
+    [],
+  );
+  return { state, setState, reset };
+}
+
+export interface WriteVariables<TParams, TPayload> {
+  params: TParams;
+  payload: TPayload;
+}
+
+export interface EntityMutationConfig<TParams> {
+  op: Exclude<TransactionOp, "delete">;
+  method: "post" | "put" | "patch";
+  url: (params: TParams) => string;
+  /** For updates: extract the row id from the call params. */
+  id?: (params: TParams) => string | number | undefined;
+}
+
+/**
+ * Optimistic write for a sync-mode entity. The store updates immediately,
+ * the transaction persists locally (offline writes replay on reconnect),
+ * and the change is sent through the entity's normal REST endpoint.
+ * Server rejection rolls back and reports through the error state.
+ */
+export function useEntityMutation<TParams, TPayload, TResult = any>(
+  entity: EntityDescriptor,
+  config: EntityMutationConfig<TParams>,
+): EntityMutationResult<WriteVariables<TParams, TPayload>, TResult> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+  const { state, setState, reset } = useMutationState<TResult>();
+
+  const mutateAsync = useCallback(
+    async (variables: WriteVariables<TParams, TPayload>): Promise<TResult> => {
+      const idField = entity.idField || "id";
+      const payload = (variables.payload || {}) as Record<string, any>;
+      let id: string;
+      let original: Record<string, any> | null = null;
+
+      if (config.op === "create") {
+        if (entity.clientIds) {
+          // Client-generated UUID pk: the id is real from the start and is
+          // sent to the server with the payload.
+          id = (payload[idField] as string) || uuid4();
+          payload[idField] = id;
+        } else {
+          id = tempId();
+        }
+      } else {
+        const rawId =
+          config.id?.(variables.params) ??
+          (payload as any)[idField] ??
+          (variables.params as any)?.[idField];
+        if (rawId === undefined || rawId === null) {
+          throw new Error(
+            `Cannot resolve the ${idField} of the ${key} row being updated`,
+          );
+        }
+        id = engine.queue.resolveAlias(String(rawId));
+        const current = engine.store.get(key, id);
+        if (current) {
+          original = {};
+          Object.keys(payload).forEach((field) => {
+            original![field] = current[field];
+          });
+        }
+      }
+
+      setState({ status: "loading", data: undefined, error: undefined });
+      try {
+        const data = (await engine.queue.enqueue({
+          entity: key,
+          op: config.op,
+          id,
+          method: config.method,
+          url: config.url(variables.params),
+          payload,
+          original,
+        })) as TResult;
+        setState({ status: "success", data, error: undefined });
+        return data;
+      } catch (error) {
+        setState({ status: "error", data: undefined, error });
+        throw error;
+      }
+    },
+    [engine, key, config.op, config.method], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const mutate = useCallback(
+    (
+      variables: WriteVariables<TParams, TPayload>,
+      callbacks?: {
+        onSuccess?: (data: TResult) => void;
+        onError?: (error: unknown) => void;
+      },
+    ) => {
+      mutateAsync(variables)
+        .then((data) => callbacks?.onSuccess?.(data))
+        .catch((error) => {
+          if (callbacks?.onError) {
+            callbacks.onError(error);
+          }
+        });
+    },
+    [mutateAsync],
+  );
+
+  return {
+    mutate,
+    mutateAsync,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    data: state.data,
+    error: state.error,
+    status: state.status,
+    reset,
+  };
+}
+
+export interface EntityDeleteConfig {
+  url: (id: string) => string;
+}
+
+/** Optimistic delete for a sync-mode entity (server-side it's a soft delete). */
+export function useEntityDelete<TResult = any>(
+  entity: EntityDescriptor,
+  config: EntityDeleteConfig,
+): EntityMutationResult<{ id?: string }, TResult> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+  const { state, setState, reset } = useMutationState<TResult>();
+
+  const mutateAsync = useCallback(
+    async (variables: { id?: string }): Promise<TResult> => {
+      if (variables.id === undefined) {
+        throw new Error("ID is required for delete operation");
+      }
+      const id = engine.queue.resolveAlias(String(variables.id));
+      const original = engine.store.get(key, id) || null;
+      setState({ status: "loading", data: undefined, error: undefined });
+      try {
+        const data = (await engine.queue.enqueue({
+          entity: key,
+          op: "delete",
+          id,
+          method: "delete",
+          url: config.url(id),
+          payload: null,
+          original,
+        })) as TResult;
+        setState({ status: "success", data, error: undefined });
+        return data;
+      } catch (error) {
+        setState({ status: "error", data: undefined, error });
+        throw error;
+      }
+    },
+    [engine, key], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const mutate = useCallback(
+    (
+      variables: { id?: string },
+      callbacks?: {
+        onSuccess?: (data: TResult) => void;
+        onError?: (error: unknown) => void;
+      },
+    ) => {
+      mutateAsync(variables)
+        .then((data) => callbacks?.onSuccess?.(data))
+        .catch((error) => {
+          if (callbacks?.onError) {
+            callbacks.onError(error);
+          }
+        });
+    },
+    [mutateAsync],
+  );
+
+  return {
+    mutate,
+    mutateAsync,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    data: state.data,
+    error: state.error,
+    status: state.status,
+    reset,
+  };
+}
+
+export interface ConfirmedMutationConfig<TParams> {
+  method: "post" | "put" | "patch" | "delete";
+  url: (params: TParams) => string;
+}
+
+/**
+ * A confirmed ("sync") operation — e.g. a password change. No optimistic
+ * apply, no queue, online-only: resolves only when the server has accepted
+ * the write. Anything it changed flows back through the changefeed like any
+ * other write.
+ */
+export function useConfirmedMutation<TParams, TPayload, TResult = any>(
+  config: ConfirmedMutationConfig<TParams>,
+): EntityMutationResult<WriteVariables<TParams, TPayload>, TResult> {
+  const engine = useSyncEngineOptional();
+  const { state, setState, reset } = useMutationState<TResult>();
+
+  const mutateAsync = useCallback(
+    async (variables: WriteVariables<TParams, TPayload>): Promise<TResult> => {
+      if (typeof navigator !== "undefined" && navigator.onLine === false) {
+        throw new Error("This operation requires a network connection");
+      }
+      const api = engine?.api || API;
+      const url = config.url(variables.params);
+      setState({ status: "loading", data: undefined, error: undefined });
+      try {
+        const response =
+          config.method === "delete"
+            ? await api.delete<TResult>(url)
+            : await api[config.method]<TResult>(url, variables.payload);
+        setState({ status: "success", data: response.data, error: undefined });
+        // Whatever the operation changed will arrive via the changefeed;
+        // kick the engine so it lands promptly.
+        engine?.wake();
+        return response.data;
+      } catch (error) {
+        setState({ status: "error", data: undefined, error });
+        throw error;
+      }
+    },
+    [engine, config.method], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const mutate = useCallback(
+    (
+      variables: WriteVariables<TParams, TPayload>,
+      callbacks?: {
+        onSuccess?: (data: TResult) => void;
+        onError?: (error: unknown) => void;
+      },
+    ) => {
+      mutateAsync(variables)
+        .then((data) => callbacks?.onSuccess?.(data))
+        .catch((error) => {
+          if (callbacks?.onError) {
+            callbacks.onError(error);
+          }
+        });
+    },
+    [mutateAsync],
+  );
+
+  return {
+    mutate,
+    mutateAsync,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    data: state.data,
+    error: state.error,
+    status: state.status,
+    reset,
+  };
+}