AshBackendDrivenOptimisticUi.Resource

Copy Markdown View Source

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

optimistic_ui do
  optimistic :award_xp do
    push :xp_awarded, xp_amount: expr(arg(:xp_amount))

    where expr(arg(:xp_amount) >= xp_to_next_level) do
      set :current_level, expr(current_level + 1)
      push :level_up, message: expr(^context(:level_up_message))
    end
  end

  on :level_up do
    set :balance, expr(balance + 1)
  end
end

An action that should have no rule says so with not_optimistic :create_from_image, because: :ai_result. The reason must be one of AshBackendDrivenOptimisticUi.NotOptimistic.reasons/0; the client never sees it.

Readable changes on the action become set effects by themselves, ahead of the declared ones: atomic_update(attr, expr) and set_attribute(attr, v) where v is a literal or arg(...). Opaque change modules and conditional changes yield nothing. A declared set for the same attribute, anywhere in the optimistic, replaces the derived one.

An expression may read the record's own attributes, calculations and aggregates, the action's arguments (arg/1, not inside on), the context (^context/1) and, inside on only, the pushed event's payload (event/1). Never relationships or the actor: the client does not hold them. AshBackendDrivenOptimisticUi.Compiler lists the functions the client can run.

optimistic_ui

Client-side rules of this resource's actions, shipped to the client as data.

Nested DSLs

optimistic_ui.optimistic

optimistic action

The client-side effects of calling a create, update, destroy or generic action.

Nested DSLs

Arguments

NameTypeDefaultDocs
actionatomA create, update, destroy or generic action on this resource.

optimistic_ui.optimistic.set

set attribute, value

Set one of this resource's attributes.

Examples

set :current_level, expr(current_level + 1)

Arguments

NameTypeDefaultDocs
attributeatomAn attribute of this resource.
valueanyAn expr(...), an arg(...) or a literal.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Set

optimistic_ui.optimistic.push

push event, payload \\ []

Play a websocket push on the client.

Examples

push :xp_awarded, xp_amount: expr(arg(:xp_amount))

Arguments

NameTypeDefaultDocs
eventatomThe push event name, e.g. :xp_awarded.
payloadkeyword[]Payload fields as key: expr(...) or key: literal pairs.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Push

optimistic_ui.optimistic.where

where condition

Apply the nested effects only when the condition holds.

Nested DSLs

Examples

where expr(arg(:xp_amount) >= xp_to_next_level) do ... end

Arguments

NameTypeDefaultDocs
conditionanyAn expr(...) that must be true for the nested effects to apply.

optimistic_ui.optimistic.where.set

set attribute, value

Set one of this resource's attributes.

Examples

set :current_level, expr(current_level + 1)

Arguments

NameTypeDefaultDocs
attributeatomAn attribute of this resource.
valueanyAn expr(...), an arg(...) or a literal.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Set

optimistic_ui.optimistic.where.push

push event, payload \\ []

Play a websocket push on the client.

Examples

push :xp_awarded, xp_amount: expr(arg(:xp_amount))

Arguments

NameTypeDefaultDocs
eventatomThe push event name, e.g. :xp_awarded.
payloadkeyword[]Payload fields as key: expr(...) or key: literal pairs.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Push

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Where

optimistic_ui.optimistic.insert

Put the new record into the client's list of this resource.

Examples

insert at: :start
insert at: {:sorted_by, :name}
insert at: :end, into: [{:groups, id: expr(arg(:group_id))}, :items]

Options

NameTypeDefaultDocs
at:start | :end | {:sorted_by, atom}Where the list shows a new row: :start, :end or {:sorted_by, field}.
intolist(any)A list nested inside the one record the client holds, as keys from its top: {key, field: expr(...)} steps into the rows of key whose field equals the value.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Insert

optimistic_ui.optimistic.remove

Take the record out of the client's list of this resource.

Examples

remove()
remove from: [:groups, :items]

Options

NameTypeDefaultDocs
fromlist(any)A list nested inside the one record the client holds, as keys from its top: {key, field: expr(...)} steps into the rows of key whose field equals the value.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Remove

optimistic_ui.optimistic.clear

Empty a list nested inside the one record the client holds.

Examples

clear from: [:messages]

Options

NameTypeDefaultDocs
fromlist(any)The list, as keys from the top of the record: {key, field: expr(...)} steps into the rows of key whose field equals the value.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Clear

optimistic_ui.optimistic.edit

Apply the rule's sets to the record's row in a list nested inside the one record the client holds.

Examples

edit from: [:meals, :ingredients]

Options

NameTypeDefaultDocs
fromlist(any)The list the row is in, as keys from the top of the record: {key, field: expr(...)} steps into the rows of key whose field equals the value.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Edit

Introspection

Target: AshBackendDrivenOptimisticUi.Rule

optimistic_ui.on

on event

This resource's effects when another resource's rule pushes the event.

Nested DSLs

Arguments

NameTypeDefaultDocs
eventatomThe pushed event this reaction answers, e.g. :level_up.

optimistic_ui.on.set

set attribute, value

Set one of this resource's attributes.

Examples

set :current_level, expr(current_level + 1)

Arguments

NameTypeDefaultDocs
attributeatomAn attribute of this resource.
valueanyAn expr(...), an arg(...) or a literal.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Set

optimistic_ui.on.push

push event, payload \\ []

Play a websocket push on the client.

Examples

push :xp_awarded, xp_amount: expr(arg(:xp_amount))

Arguments

NameTypeDefaultDocs
eventatomThe push event name, e.g. :xp_awarded.
payloadkeyword[]Payload fields as key: expr(...) or key: literal pairs.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Push

optimistic_ui.on.where

where condition

Apply the nested effects only when the condition holds.

Nested DSLs

Examples

where expr(arg(:xp_amount) >= xp_to_next_level) do ... end

Arguments

NameTypeDefaultDocs
conditionanyAn expr(...) that must be true for the nested effects to apply.

optimistic_ui.on.where.set

set attribute, value

Set one of this resource's attributes.

Examples

set :current_level, expr(current_level + 1)

Arguments

NameTypeDefaultDocs
attributeatomAn attribute of this resource.
valueanyAn expr(...), an arg(...) or a literal.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Set

optimistic_ui.on.where.push

push event, payload \\ []

Play a websocket push on the client.

Examples

push :xp_awarded, xp_amount: expr(arg(:xp_amount))

Arguments

NameTypeDefaultDocs
eventatomThe push event name, e.g. :xp_awarded.
payloadkeyword[]Payload fields as key: expr(...) or key: literal pairs.

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Push

Introspection

Target: AshBackendDrivenOptimisticUi.Effect.Where

Introspection

Target: AshBackendDrivenOptimisticUi.Reaction

optimistic_ui.not_optimistic

not_optimistic action

Opts a create, update, destroy or generic action out of optimistic UI, with a reason.

Arguments

NameTypeDefaultDocs
actionatomThe action that has no optimistic rule.

Options

NameTypeDefaultDocs
because:ai_result | :server_decides | :background | :admin | :not_yetWhy it has none.

Introspection

Target: AshBackendDrivenOptimisticUi.NotOptimistic