API Reference AshBackendDrivenOptimisticUi v#0.1.0

Copy Markdown View Source

Modules

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.

Compiles an unhydrated Ash.Expr term to JSON Logic, as plain maps and lists ready for Jason.

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.

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].

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.

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.

Plays a websocket push on the client, the same event the server's notifier sends, with a payload of expressions or literals.

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.

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.

Applies the nested effects only when condition holds.

Read a resource's optimistic_ui do ... end block.

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.

Says an action deliberately has no optimistic rule, and why.

A per-process list of the pushes sent while handling one request.

The id of an optimistic push, computed from the record as it was before the write: <type>:<record id>:<updated_at>:<event>:<label>.

This resource's effects when any resource's rule pushes event. Reactions see only this resource's record and the context, never action arguments.

Every rule of the host app in one payload, with a version.

Declare, next to an action, what the client may show the moment the user calls it, before the server answers.

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().

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.

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.

A ready Ash resource that serves the rules.

A resource's rules as JSON-ready data for the client.

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.

One-line checks that make refactoring an action safe. use this module inside an ExUnit module.

Mix Tasks

Installs AshBackendDrivenOptimisticUi: config and formatter.

Prints the compiled rule of one action, then the reactions that follow its pushes.

Compares every rule of AshBackendDrivenOptimisticUi.Registry.rules/0 with the files in test/optimistic_ui/__snapshots__.