AshBackendDrivenOptimisticUi

Optimistic UI for Ash. The app shows a change the moment the user taps, using rules you write once, on the server.

The problem

A user adds a todo. The app sends it to the server, waits for the answer, and only then shows the new row. On a phone that wait can be a second after every tap.

The usual fix is to show the row first and save it after. But then the app has to know the server's rules: where the row goes, what else changes. The rules get written twice, once on the server and once in the app, and the two drift apart.

What this library does

You write the rule next to the Ash action. The app downloads the rules and applies one when the user taps. After the save, the server sends the real data and the app keeps that.

Example

defmodule MyApp.Todo do
  use Ash.Resource,
    domain: MyApp.Tasks,
    notifiers: [Ash.Notifier.PubSub],
    extensions: [AshBackendDrivenOptimisticUi.Resource]

  optimistic_ui do
    optimistic :create do
      insert at: :end
    end
  end

  pub_sub do
    module MyAppWeb.Endpoint
    prefix "todo"

    publish :create, "created"
  end
end

When the user adds a todo, the app puts it at the end of the list at once, built from what the user typed.

The pub_sub block is plain Ash, not this library: after the save it sends the saved todo to the app, and the app swaps its guess for it. A resource that does not send its changes cannot have a rule.

The app gets the rules from one more line in the domain:

defmodule MyApp.Tasks do
  use Ash.Domain

  resources do
    resource MyApp.Todo
    resource AshBackendDrivenOptimisticUi.RuleSet
  end
end

RuleSet has one action, :rules. Expose it with the API layer you already use, like any other action. One piece is left, described in Send two things to the client.

Installation

With Igniter in your deps, one command does it:

mix igniter.install ash_backend_driven_optimistic_ui

It adds the dependency, writes the config and adds the formatter import. Running it twice changes nothing. It then prints what is left for you: the two things your app sends to the client.

By hand

Add it to your deps:

def deps do
  [
    {:ash_backend_driven_optimistic_ui, "~> 0.1"}
  ]
end

Add import_deps: [:ash_backend_driven_optimistic_ui] to your .formatter.exs, so the formatter leaves the rules without parentheses.

Tell the library which app's domains to read:

config :ash_backend_driven_optimistic_ui, otp_app: :my_app, pubsub: MyApp.PubSub

Send two things to the client

The library does not care how your app talks to the client (HTTP, gRPC, a channel, GraphQL). Your app carries two things over that transport.

1. The rules. Add one line to a domain:

resources do
  resource AshBackendDrivenOptimisticUi.RuleSet
end

Then expose its :rules action with your API layer, like any other action. The client downloads the rules at start, and again when the version changes.

2. What happened to the guesses. With the answer to each save, send what was pushed and which guesses did not happen. Call AshBackendDrivenOptimisticUi.PushCollector.open() before the action. After it, call AshBackendDrivenOptimisticUi.PushCollector.drain_reconciliation(optimistic_ids_the_client_sent) and put the result in the answer. Whatever sends your pushes must call AshBackendDrivenOptimisticUi.PushCollector.record/2 for each one.

What your app needs

Usage

Add or remove a row

optimistic :create do
  insert at: :start
end

optimistic :destroy

A destroy rule with no effects takes the row out of the list.

Change a field

optimistic :rename do
  set :title, expr(arg(:title))
end

You can often leave this out: simple changes on the action, and the fields a create accepts, are added to the rule for you.

Show a toast at once

optimistic :complete do
  set :done, true
  push :xp_awarded, amount: 10
end

The app shows the "+10 XP" toast right away. When the server sends the real one, the app knows it already showed it.

Say why an action has no rule

not_optimistic :create_from_image, because: :ai_result

For actions whose result the app can't know in advance.

More rules, with explanations, are in Examples.

What you don't write twice

You do write one thing twice: a push repeats the name and fields of the event your notifier sends. The test helper fails if the name, the id or a field doesn't match. Details: What is written once.

Limits

Learn more

For AI assistants

Point your coding agent at usage-rules.md, in the library folder next to this README.

License

MIT. See the LICENSE file in the library folder.