A write of a grid's rows: cells edited, new rows, rows deleted or brought back. Every change a person makes to the rows goes through one, whoever saves it.

The grid builds the write, and hands it to your function for its operation (on_update, on_create, on_delete, on_restore on Masu.Components.data_grid/1), which gives it back with a result for each change. Without one, the grid saves it its own way (Masu.Write.save/1: the repo of an Ecto source, or its copy of a list), with changeset.

<.data_grid id="orders" source={Order} repo={Repo} scope={@current_scope}
  on_update={&OrdersGrid.update/1}>

defmodule MyAppWeb.OrdersGrid do
  alias MyApp.Orders

  # A context function, row by row.
  def update(write) do
    Masu.Write.each(write, &Orders.update_order(write.scope, &1.row, &1.params))
  end
end

By the time your function gets it, the grid has done its part: each row is found again through the grid's own query (a person writes only the rows they may see), the cells that do not edit, or that the row's state makes read-only (row_editable, a column's editable), are refused, and so are the cells someone changed meanwhile (see "Two people, one cell" in the Editing guide). A change has only what is left.

What a write has

• op - :update, :create, :delete or :restore;
• changes - the Masu.Write.Changes, one for each row;
• origin - what the person did: :edit (typed in a cell), :paste, :fill, :clear, :undo, :redo (cells); :draft (a new row), :paste (rows of a paste); :rows (the rows of a range), :selection (the rows selected), :redo (a delete again); :undo (rows back); :test from Masu.Test;
• scope - the grid's scope: the current user, their organization, as your app has it (@current_scope);
• by - who makes it: on a grid in an Issho room (issho), and for an agent's tools, an Issho.Identity (a person, an agent and whom it acts for), the same as every component's callbacks get; else the grid's user;
• grid - the id of the grid;
• ref - the write's reference, for async/1 and Masu.reply/2.

Results

Each change gets one, from the function that writes it:

• each/2 - a function of each change, {:ok, row} or {:error, reason} (:ok for a delete);
• all/2 - one function of every change, for a transaction of the whole batch (Ecto.Multi): {:ok, rows}, in the order of the changes, or {:error, reason}, which refuses them all;
• ok/3 and error/3 - a result for one change;
• save/1 - the grid's own way, for the changes without a result;
• async/1 - the changes without a result are saved later, by a job of yours: the grid shows them saving until Masu.reply/2.

A reason is an Ecto.Changeset (its errors go on the cells of its fields), a message (on every cell of the row), or [{key, message}] of column keys. A change left without a result is a mistake, and the grid raises.

The results compose. Your function may save the grid's way and do more, or save each row its own way and the rest the grid's:

def update(write) do
  write
  |> Masu.Write.save()
  |> tap(&Audit.log(&1.scope, Masu.Write.saved(&1)))
end

def update(%Masu.Write{origin: :paste} = write) do
  Masu.Write.all(write, &Orders.update_many(write.scope, &1))
end

def update(write), do: Masu.Write.save(write)

Later: a job

A write that takes long (a paste of 5,000 cells into a system that takes its time, an import of new rows through a queue) can be saved by a job. async/1 says that the changes without a result will be saved; ref reaches the grid from any process (an Oban job, on any node of the cluster):

def update(write) do
  %{ref: write.ref, changes: Enum.map(write.changes, &Map.take(&1, [:id, :params]))}
  |> MyApp.Workers.SaveCells.new()
  |> Oban.insert!()

  Masu.Write.async(write)
end

# In the job:
Masu.reply(ref, :ok)
Masu.reply(ref, {:error, "The ledger is closed."})

The cells show saving until the reply; then the grid reads its rows again, and an error refuses the changes, which show their old values. New rows and rows brought back need their ids at once: they cannot be saved later.