Use grid mutation

useGridMutation, GridMutationOptions, GridMutationResult, GridMutationStrategy and 1 more: generated from the source of active-grid.

Exported by @workspace/active-grid. Generated from the package source; part of the index of every export.

Functions, hooks and constants#

useGridMutation

One-stop hook for the "run async mutation, then patch the grid" pattern.

Replaces direct gridRef.current?.removeRow(id) / .refetch() / .resetSelection() calls in consumer-code. The grid's imperative API remains as a package-internal primitive — consumers should reach for useGridMutation instead, so the strategy choice is named and reviewable.

(gridRef: RefObject<GridImperativeHandle | null>) => UseGridMutationResult

Returns

An object with these fields.

mutaterequired

Type: <TInput, TActionResult extends { …

Run a mutation. Applies onSuccess-strategy when the action resolves to success: true. Returns the action's result so the caller can decide on its own toast / dialog behavior.

The return type preserves the action's exact shape — typed errors like ActionError survive narrowing on result.success === false.

Throws are surfaced to the caller — the hook does not swallow unexpected errors. Use try/catch if the action might throw.

isPendingrequired

Type: boolean

Whether any mutation triggered by this hook is currently in flight.

Types#

GridMutationOptions

interface GridMutationOptions<TInput, TActionResult> {
  action: (input: TInput) => Promise<TActionResult>;
  onSuccess:
    | GridMutationStrategy<TInput, ExtractData<TActionResult>>
    | GridMutationStrategy<TInput, ExtractData<TActionResult>>[];
}

GridMutationResult

Structural mirror of ActionResult<T> from @workspace/active-types. Mirrored here so @workspace/active-grid stays platform-agnostic.

The mutate function preserves the consumer's exact return shape (via generic inference on the action callback) so error-narrowing — e.g. toastActionError(result, t, tDynamic) — keeps working with consumer-specific error types like ActionError.

type GridMutationResult<TData> =
  {success: true; data: TData} | {success: false; error: unknown};

GridMutationStrategy

Strategy applied to the grid after a successful mutation.

removeRow — drop one row from the local cache (server-mode) without refetching, preserving session-state (sort/filter/scroll). Like every strategy here it runs only AFTER the action resolved successfully; it is not optimistic. An optimistic path with rollback is the deferred F-13.
addRow — append a row to the local cache (server-mode), increments total-count.
refetch — invalidate cache and re-fetch the current page. Use when the change cascades to other rows (e.g. status transition affecting filters, or anonymize/restore).
resetSelection — clear all selected rows. Typical after a bulk action where the selection should not survive.
none — perform no grid action; consumer-side state is reconciled elsewhere (e.g. parent re-renders with new props).

type GridMutationStrategy<TInput, TData> =
  | {
      type: 'removeRow';
      rowId: string | ((input: TInput, data: TData) => string);
    }
  | {type: 'addRow'; row: (input: TInput, data: TData) => unknown}
  | {type: 'refetch'}
  | {type: 'resetSelection'}
  | {type: 'none'};

UseGridMutationResult

interface UseGridMutationResult {
  mutate: <
    TInput,
    TActionResult extends
      {success: true; data: unknown} | {success: false; error: unknown},
  >(
    input: TInput,
    options: GridMutationOptions<TInput, TActionResult>,
  ) => Promise<TActionResult>;
  isPending: boolean;
}