<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshBackendDrivenOptimisticUi.Resource

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](#optimistic_ui-optimistic)
   * set
   * push
   * where
     * set
     * push
   * insert
   * remove
   * clear
   * edit
 * [on](#optimistic_ui-on)
   * set
   * push
   * where
     * set
     * push
 * [not_optimistic](#optimistic_ui-not_optimistic)





### optimistic_ui.optimistic
```elixir
optimistic action
```


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

### Nested DSLs
 * [set](#optimistic_ui-optimistic-set)
 * [push](#optimistic_ui-optimistic-push)
 * [where](#optimistic_ui-optimistic-where)
   * set
   * push
 * [insert](#optimistic_ui-optimistic-insert)
 * [remove](#optimistic_ui-optimistic-remove)
 * [clear](#optimistic_ui-optimistic-clear)
 * [edit](#optimistic_ui-optimistic-edit)




### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`action`](#optimistic_ui-optimistic-action){: #optimistic_ui-optimistic-action .spark-required} | `atom` |  | A create, update, destroy or generic action on this resource. |



### optimistic_ui.optimistic.set
```elixir
set attribute, value
```


Set one of this resource's attributes.



### Examples
```
set :current_level, expr(current_level + 1)
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`attribute`](#optimistic_ui-optimistic-set-attribute){: #optimistic_ui-optimistic-set-attribute .spark-required} | `atom` |  | An attribute of this resource. |
| [`value`](#optimistic_ui-optimistic-set-value){: #optimistic_ui-optimistic-set-value .spark-required} | `any` |  | An `expr(...)`, an `arg(...)` or a literal. |






### Introspection

Target: `AshBackendDrivenOptimisticUi.Effect.Set`

### optimistic_ui.optimistic.push
```elixir
push event, payload \\ []
```


Play a websocket push on the client.



### Examples
```
push :xp_awarded, xp_amount: expr(arg(:xp_amount))
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`event`](#optimistic_ui-optimistic-push-event){: #optimistic_ui-optimistic-push-event .spark-required} | `atom` |  | The push event name, e.g. `:xp_awarded`. |
| [`payload`](#optimistic_ui-optimistic-push-payload){: #optimistic_ui-optimistic-push-payload } | `keyword` | `[]` | Payload fields as `key: expr(...)` or `key: literal` pairs. |






### Introspection

Target: `AshBackendDrivenOptimisticUi.Effect.Push`

### optimistic_ui.optimistic.where
```elixir
where condition
```


Apply the nested effects only when the condition holds.

### Nested DSLs
 * [set](#optimistic_ui-optimistic-where-set)
 * [push](#optimistic_ui-optimistic-where-push)


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



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`condition`](#optimistic_ui-optimistic-where-condition){: #optimistic_ui-optimistic-where-condition .spark-required} | `any` |  | An `expr(...)` that must be true for the nested effects to apply. |



### optimistic_ui.optimistic.where.set
```elixir
set attribute, value
```


Set one of this resource's attributes.



### Examples
```
set :current_level, expr(current_level + 1)
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`attribute`](#optimistic_ui-optimistic-where-set-attribute){: #optimistic_ui-optimistic-where-set-attribute .spark-required} | `atom` |  | An attribute of this resource. |
| [`value`](#optimistic_ui-optimistic-where-set-value){: #optimistic_ui-optimistic-where-set-value .spark-required} | `any` |  | An `expr(...)`, an `arg(...)` or a literal. |






### Introspection

Target: `AshBackendDrivenOptimisticUi.Effect.Set`

### optimistic_ui.optimistic.where.push
```elixir
push event, payload \\ []
```


Play a websocket push on the client.



### Examples
```
push :xp_awarded, xp_amount: expr(arg(:xp_amount))
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`event`](#optimistic_ui-optimistic-where-push-event){: #optimistic_ui-optimistic-where-push-event .spark-required} | `atom` |  | The push event name, e.g. `:xp_awarded`. |
| [`payload`](#optimistic_ui-optimistic-where-push-payload){: #optimistic_ui-optimistic-where-push-payload } | `keyword` | `[]` | 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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`at`](#optimistic_ui-optimistic-insert-at){: #optimistic_ui-optimistic-insert-at .spark-required} | `:start \| :end \| {:sorted_by, atom}` |  | Where the list shows a new row: `:start`, `:end` or `{:sorted_by, field}`. |
| [`into`](#optimistic_ui-optimistic-insert-into){: #optimistic_ui-optimistic-insert-into } | `list(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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`from`](#optimistic_ui-optimistic-remove-from){: #optimistic_ui-optimistic-remove-from } | `list(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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`from`](#optimistic_ui-optimistic-clear-from){: #optimistic_ui-optimistic-clear-from .spark-required} | `list(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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`from`](#optimistic_ui-optimistic-edit-from){: #optimistic_ui-optimistic-edit-from .spark-required} | `list(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
```elixir
on event
```


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

### Nested DSLs
 * [set](#optimistic_ui-on-set)
 * [push](#optimistic_ui-on-push)
 * [where](#optimistic_ui-on-where)
   * set
   * push




### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`event`](#optimistic_ui-on-event){: #optimistic_ui-on-event .spark-required} | `atom` |  | The pushed event this reaction answers, e.g. `:level_up`. |



### optimistic_ui.on.set
```elixir
set attribute, value
```


Set one of this resource's attributes.



### Examples
```
set :current_level, expr(current_level + 1)
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`attribute`](#optimistic_ui-on-set-attribute){: #optimistic_ui-on-set-attribute .spark-required} | `atom` |  | An attribute of this resource. |
| [`value`](#optimistic_ui-on-set-value){: #optimistic_ui-on-set-value .spark-required} | `any` |  | An `expr(...)`, an `arg(...)` or a literal. |






### Introspection

Target: `AshBackendDrivenOptimisticUi.Effect.Set`

### optimistic_ui.on.push
```elixir
push event, payload \\ []
```


Play a websocket push on the client.



### Examples
```
push :xp_awarded, xp_amount: expr(arg(:xp_amount))
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`event`](#optimistic_ui-on-push-event){: #optimistic_ui-on-push-event .spark-required} | `atom` |  | The push event name, e.g. `:xp_awarded`. |
| [`payload`](#optimistic_ui-on-push-payload){: #optimistic_ui-on-push-payload } | `keyword` | `[]` | Payload fields as `key: expr(...)` or `key: literal` pairs. |






### Introspection

Target: `AshBackendDrivenOptimisticUi.Effect.Push`

### optimistic_ui.on.where
```elixir
where condition
```


Apply the nested effects only when the condition holds.

### Nested DSLs
 * [set](#optimistic_ui-on-where-set)
 * [push](#optimistic_ui-on-where-push)


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



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`condition`](#optimistic_ui-on-where-condition){: #optimistic_ui-on-where-condition .spark-required} | `any` |  | An `expr(...)` that must be true for the nested effects to apply. |



### optimistic_ui.on.where.set
```elixir
set attribute, value
```


Set one of this resource's attributes.



### Examples
```
set :current_level, expr(current_level + 1)
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`attribute`](#optimistic_ui-on-where-set-attribute){: #optimistic_ui-on-where-set-attribute .spark-required} | `atom` |  | An attribute of this resource. |
| [`value`](#optimistic_ui-on-where-set-value){: #optimistic_ui-on-where-set-value .spark-required} | `any` |  | An `expr(...)`, an `arg(...)` or a literal. |






### Introspection

Target: `AshBackendDrivenOptimisticUi.Effect.Set`

### optimistic_ui.on.where.push
```elixir
push event, payload \\ []
```


Play a websocket push on the client.



### Examples
```
push :xp_awarded, xp_amount: expr(arg(:xp_amount))
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`event`](#optimistic_ui-on-where-push-event){: #optimistic_ui-on-where-push-event .spark-required} | `atom` |  | The push event name, e.g. `:xp_awarded`. |
| [`payload`](#optimistic_ui-on-where-push-payload){: #optimistic_ui-on-where-push-payload } | `keyword` | `[]` | 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
```elixir
not_optimistic action
```


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





### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`action`](#optimistic_ui-not_optimistic-action){: #optimistic_ui-not_optimistic-action .spark-required} | `atom` |  | The action that has no `optimistic` rule. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`because`](#optimistic_ui-not_optimistic-because){: #optimistic_ui-not_optimistic-because .spark-required} | `:ai_result \| :server_decides \| :background \| :admin \| :not_yet` |  | Why it has none. |





### Introspection

Target: `AshBackendDrivenOptimisticUi.NotOptimistic`





<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>
