# AshBackendDrivenOptimisticUi v0.1.0 - API Reference

## Modules

- [AshBackendDrivenOptimisticUi.Change](AshBackendDrivenOptimisticUi.Change.md): Lets a change module describe its effect for the client, once, next to its
code. The client cannot run Elixir, so without this every `optimistic` block
of every action that uses the change repeats the effect as a `set`.

- Public API
  - [AshBackendDrivenOptimisticUi.Info](AshBackendDrivenOptimisticUi.Info.md): Read a resource's `optimistic_ui do ... end` block.
  - [AshBackendDrivenOptimisticUi.NotOptimistic](AshBackendDrivenOptimisticUi.NotOptimistic.md): Says an action deliberately has no `optimistic` rule, and why.
  - [AshBackendDrivenOptimisticUi.PushCollector](AshBackendDrivenOptimisticUi.PushCollector.md): A per-process list of the pushes sent while handling one request.
  - [AshBackendDrivenOptimisticUi.Registry](AshBackendDrivenOptimisticUi.Registry.md): Every rule of the host app in one payload, with a version.
  - [AshBackendDrivenOptimisticUi.Resource](AshBackendDrivenOptimisticUi.Resource.md): Declare, next to an action, what the client may show the moment the user
calls it, before the server answers.
  - [AshBackendDrivenOptimisticUi.RuleSet](AshBackendDrivenOptimisticUi.RuleSet.md): A ready Ash resource that serves the rules.
  - [AshBackendDrivenOptimisticUi.Test](AshBackendDrivenOptimisticUi.Test.md): One-line checks that make refactoring an action safe. `use` this module
inside an ExUnit module.

- Rules and reactions
  - [AshBackendDrivenOptimisticUi.Reaction](AshBackendDrivenOptimisticUi.Reaction.md): This resource's effects when any resource's rule pushes `event`.
Reactions see only this resource's record and the context, never action
arguments.

  - [AshBackendDrivenOptimisticUi.Rule](AshBackendDrivenOptimisticUi.Rule.md): What the client may show the moment it calls `action`, before the server
answers. Derived sets come first in `effects`, then the declared ones in
order.

- Effects
  - [AshBackendDrivenOptimisticUi.Effect](AshBackendDrivenOptimisticUi.Effect.md): One thing a rule does on the client: set, push or where, and in an
`optimistic` only, insert (a create), remove, clear or edit on a list.

  - [AshBackendDrivenOptimisticUi.Effect.Clear](AshBackendDrivenOptimisticUi.Effect.Clear.md): Empties a list nested inside the one record the client holds, for an action
that deletes every row of it at once: `clear from: [:messages]`.

  - [AshBackendDrivenOptimisticUi.Effect.Edit](AshBackendDrivenOptimisticUi.Effect.Edit.md): Applies the rule's sets to the record's own row in a list nested inside the
one record the client holds, for an update of a row there:
`edit from: [:meals, :ingredients]` finds the row by id on that path.

  - [AshBackendDrivenOptimisticUi.Effect.Insert](AshBackendDrivenOptimisticUi.Effect.Insert.md): Puts the record a create makes, built from the rule's sets, into the list
the client holds of this resource, at its start or end, or, with
`at: {:sorted_by, field}`, before the first row whose `field` sorts after
its own, for a list the server orders by that field. The client gives it a
temporary id that the saved record replaces.
  - [AshBackendDrivenOptimisticUi.Effect.Push](AshBackendDrivenOptimisticUi.Effect.Push.md): Plays a websocket push on the client, the same event the server's notifier
sends, with a payload of expressions or literals.

  - [AshBackendDrivenOptimisticUi.Effect.Remove](AshBackendDrivenOptimisticUi.Effect.Remove.md): Takes the record out of the list the client holds of this resource: a destroy
deletes it, an update can leave it where that list no longer shows it.

  - [AshBackendDrivenOptimisticUi.Effect.Set](AshBackendDrivenOptimisticUi.Effect.Set.md): Sets one of the declaring resource's own attributes to the value of an
expression. `derived?` marks a set read from the action's own changes
rather than written in the `optimistic_ui` block. `from` is the change
module it was read from, when it came from one.

  - [AshBackendDrivenOptimisticUi.Effect.Where](AshBackendDrivenOptimisticUi.Effect.Where.md): Applies the nested effects only when `condition` holds.

- How it works
  - [AshBackendDrivenOptimisticUi.Compiler](AshBackendDrivenOptimisticUi.Compiler.md): Compiles an unhydrated `Ash.Expr` term to JSON Logic, as plain maps and
lists ready for `Jason`.
  - [AshBackendDrivenOptimisticUi.JsonLogic](AshBackendDrivenOptimisticUi.JsonLogic.md): Evaluates JSON Logic the way the client does: the full standard (`var`,
`missing`, `missing_some`, `if`, `?:`, `== != === !==`, `! !!`, `or`, `and`,
`> >= < <=` including the three-operand "between" form, `max`, `min`,
`+ - * / %`, `map`, `filter`, `reduce`, `all`, `none`, `some`, `merge`, `in`,
`cat`, `substr`, `log`), checked against the official JSON Logic test suite,
plus five custom operations: `has` (whether a dotted path's last key is
present, even with a null value), `abs`, `round` (one or two operands, half
away from zero), `to_string` (`nil` becomes empty text) and `now` (the
current UTC time as ISO 8601 text). Literals pass through and a list that is
not an operation evaluates each element.
  - [AshBackendDrivenOptimisticUi.PushId](AshBackendDrivenOptimisticUi.PushId.md): The id of an optimistic push, computed from the record as it was before the
write: `<type>:<record id>:<updated_at>:<event>:<label>`.
  - [AshBackendDrivenOptimisticUi.Resource.Transformers.DeriveSets](AshBackendDrivenOptimisticUi.Resource.Transformers.DeriveSets.md): Reads each optimistic action and prepends a derived `set` for every readable
change: `atomic_update(attr, expr)`, and `set_attribute(attr, v)` with a
literal or `arg(...)` value. A change module that implements
`AshBackendDrivenOptimisticUi.Change` describes its own sets. Other change
modules and changes guarded by `where` are skipped, so a rule never claims
more than the action shows. A create also gets `set attr, expr(arg(attr))` for every attribute it
accepts: the new record is built from the input. An update gets the same set
for each accepted attribute, inside `where expr(has_arg(attr))`: an update
changes a field only when the input carries it. A declared `set` for the
same attribute wins, and so does a readable change over an accepted one.
A destroy rule that declares no effect gets `remove()`.

  - [AshBackendDrivenOptimisticUi.Resource.Verifiers.ValidateRules](AshBackendDrivenOptimisticUi.Resource.Verifiers.ValidateRules.md): Rejects a `optimistic_ui` block the client could not run or that would drift
from the resource: an action that is missing or a read, a `set` on
something that is neither an attribute nor a public calculation, an `arg`
that is neither an argument nor an accepted attribute of the action (or any `arg` inside `on`), an `event` outside
`on`, a reference to an unknown field, through a relationship, or to the
actor.
  - [AshBackendDrivenOptimisticUi.Rules](AshBackendDrivenOptimisticUi.Rules.md): A resource's rules as JSON-ready data for the client.
  - [AshBackendDrivenOptimisticUi.Snapshot](AshBackendDrivenOptimisticUi.Snapshot.md): The committed copy of every rule, one pretty-printed JSON file per
rule at `<dir>/<type>.<action>.json`, keys sorted so a diff shows only real
changes. `AshBackendDrivenOptimisticUi.Test` compares against it, `mix optimistic_ui.snapshot`
rewrites it.

## Mix Tasks

- Mix tasks
  - [mix ash_backend_driven_optimistic_ui.install](Mix.Tasks.AshBackendDrivenOptimisticUi.Install.md): Installs AshBackendDrivenOptimisticUi: config and formatter.
  - [mix optimistic_ui.explain](Mix.Tasks.OptimisticUi.Explain.md): Prints the compiled rule of one action, then the reactions that follow its
pushes.
  - [mix optimistic_ui.snapshot](Mix.Tasks.OptimisticUi.Snapshot.md): Compares every rule of `AshBackendDrivenOptimisticUi.Registry.rules/0` with the files in
`test/optimistic_ui/__snapshots__`.

