@spec diff(t(), %{optional(ref()) => record()}, keyword()) ::
  {:ok, [Ramal.Change.t()]} | {:error, Ramal.Error.t()}

The overlay as a list of Ramal.Change structs, computed against the base rows as the branch first saw them.

base maps each ref the branch touched on an existing row to that row's snapshot. It never queries anything: the snapshot is what the branch kept at first touch. Created rows need no snapshot. Rows whose updates netted out to no difference are left out.

The result is sorted by ref so it is deterministic. The overlay is a map and does not remember the order of writes; Ramal.diff/1 orders changes by the branch log.

Returns {:error, %Ramal.Error{reason: :missing_snapshot}} when an updated or deleted entry has no snapshot, which means the write layer forgot to record one.

Options

• :attributes - a function from a record to a %{atom => value} map. Defaults to the record's own keys without the __meta__-style ones. The Ash-aware caller passes one built from the resource's attributes.

Example

iex> overlay = %{{MyApp.Herd, 1} => {:updated, %{id: 1, name: "b"}}}
iex> base = %{{MyApp.Herd, 1} => %{id: 1, name: "a"}}
iex> {:ok, [change]} = Ramal.Overlay.diff(overlay, base)
iex> {change.kind, change.changes}
{:updated, %{name: {"a", "b"}}}

@spec merge_into(t(), t()) :: t()

Applies other's entries on top of overlay, as if each had been put in turn.

Forking uses it: a fork starts as merge_into(new(), parent). Because overlays are immutable maps, the fork and the parent never see each other's later changes. The combination rules are the ones in the module doc, so merging a :deleted entry over a :created one removes the row from the result.

Example

iex> parent = %{{MyApp.Herd, 1} => {:created, %{id: 1}}}
iex> Ramal.Overlay.merge_into(Ramal.Overlay.new(), parent) == parent
true

@spec new() :: t()

An empty overlay.

Example

iex> Ramal.Overlay.new()
%{}

@spec patch([record()], slice(), (record() -> as_boolean(term())), keyword()) :: [
  record()
]

Applies a resource's overlay slice to the rows the base returned for a query.

base_rows are the rows the data layer returned for the query's filter, without limit and offset. The result is what the same query would return on a base that already held the branch's changes:

1. a base row whose key is :deleted in the slice is dropped;
2. a base row whose key is :updated is replaced by the overlay record, or dropped when that record no longer satisfies predicate;
3. an overlay record the base did not return is added when it satisfies predicate. This covers created rows and updated rows that only match the filter after the update;
4. the rows are sorted, then offset and limit are applied. Doing that last is what lets a row created in the branch appear in a limited query.

predicate is called only on overlay records, since the base already applied the filter to its own rows. Callers evaluate the query's filter in it, for example with Ash.Filter.Runtime.

Options

• :key (required) - a function returning the primary key of a row, the same keys the slice uses
• :sort - a comparator (a, b -> boolean) as Enum.sort/2 takes it; return true when a goes before or equal to b, which keeps the sort stable. Without it, base order is kept and added rows follow in key order
• :offset - rows to skip after sorting, default 0
• :limit - the maximum number of rows, default no limit
• :replace - a function (base_row, overlay_record -> record) that builds the row that takes a base row's place, for state the base row carries and the overlay record cannot, default the overlay record itself

Example

iex> base = [%{id: 1, n: 10}, %{id: 2, n: 20}]
iex> slice = %{2 => :deleted, 3 => {:created, %{id: 3, n: 30}}}
iex> Ramal.Overlay.patch(base, slice, fn _ -> true end, key: & &1.id, sort: &(&1.n >= &2.n), limit: 2)
[%{id: 3, n: 30}, %{id: 1, n: 10}]

@spec put_created(t(), ref(), record()) :: t()

Records that the branch created the row ref with record.

See the table in the module doc for how it combines with an existing entry.

Example

iex> Ramal.Overlay.put_created(%{}, {MyApp.Herd, 1}, %{id: 1})
%{{MyApp.Herd, 1} => {:created, %{id: 1}}}

@spec put_deleted(t(), ref()) :: t()

Records that the branch deleted the row ref.

Deleting a row the branch itself created removes the entry: the base never had that row, so there is nothing to hide.

Example

iex> overlay = Ramal.Overlay.put_deleted(%{}, {MyApp.Herd, 1})
iex> overlay
%{{MyApp.Herd, 1} => :deleted}
iex> overlay |> Ramal.Overlay.put_created({MyApp.Herd, 2}, %{id: 2}) |> Ramal.Overlay.put_deleted({MyApp.Herd, 2})
%{{MyApp.Herd, 1} => :deleted}

@spec put_updated(t(), ref(), record()) :: t()

Records that the branch updated the row ref; record is the row as the update left it.

A row the branch created stays :created, with the new record.

Example

iex> overlay = Ramal.Overlay.put_created(%{}, {MyApp.Herd, 1}, %{id: 1, v: 1})
iex> Ramal.Overlay.put_updated(overlay, {MyApp.Herd, 1}, %{id: 1, v: 2})
%{{MyApp.Herd, 1} => {:created, %{id: 1, v: 2}}}

@spec slice(t(), resource()) :: slice()

The entries for one resource, keyed by primary key.

Example

iex> overlay = %{{MyApp.Herd, 1} => :deleted, {MyApp.Paddock, 9} => {:created, %{id: 9}}}
iex> Ramal.Overlay.slice(overlay, MyApp.Herd)
%{1 => :deleted}