lily/store

The Store holds your application state and update logic, shared across client and server. The mental model is very simple, each store holds a basic model type and an update function fn(model, message) -> model. The store is agnostic to how your frontend actually displays these components, with the view function or rendering completely detached (unlike Lustre and closer to Redux).

Here’s a minimal example of a counter:

pub type Model {
  Model(count: Int)
}

pub type Message {
  Increment
  Decrement
}

pub fn update(model: Model, message: Message) -> Model {
  case message {
    Increment -> Model(count: model.count + 1)
    Decrement -> Model(count: model.count - 1)
  }
}

// this should be in your client/frontend code
let store = store.new(Model(count: 0), with: update)

You wrap it with store.new on the client and pipe the result into client.start.

The server is then set up separately via server.new, where Wiring comes into play. Syncing your model with the server splits your model into a per-connection session slice and then shared topic slices (see the topic module for more info). For each message, the wiring allows us to figure out which message belongs where (through extract), how the slice should update (update), and how to read and write the slice on the outer model (field_get/field_set). It also merges server snapshots back into the right slice. server snapshots back into the right slice.

Build one Wiring in your shared package and hand the same value to both the client (passed to client.start) and the server (passed to server.new):

import lily/store

pub fn wiring() -> store.Wiring(Model, Message) {
  store.wiring()
  |> store.session(
    extract: fn(message) {
      case message {
        Session(inner) -> Ok(inner)
        _ -> Error(Nil)
      }
    },
    update: session_update,
    field_get: fn(model: Model) { model.session },
    field_set: fn(model, session) { Model(..model, session:) },
  )
  |> store.topic(
    id: "chat",
    extract: fn(message) {
      case message {
        Chat(inner) -> Ok(inner)
        _ -> Error(Nil)
      }
    },
    update: chat_update,
    field_get: fn(model: Model) { model.chat },
    field_set: fn(model, chat) { Model(..model, chat:) },
  )
  // you can chain more topics by determining a different topic id
}

Model fields that should not be synced to the server can be wrapped in Local. The server holds Local fields at their initial values and the client runtime preserves them when the server sends a snapshot on reconnect. Pair with client.session_field to persist them across page navigations.

The same store runs on the client via client.start and the server via server.start, meaning your update function works identically on both sides.

pub type Model {
  Model(count: Int, theme: store.Local(String))
}

pub type Local(a) {
  Local(a)
}

pub opaque type Store(model, message)

pub opaque type Wiring(model, message)

pub fn new(
  initial_model model: model,
  with update: fn(model, message) -> model,
) -> Store(model, message)

let app_store =
  Model(count: 0, user: "Guest")
  |> store.new(with: update)

pub fn session(
  wiring: Wiring(model, message),
  extract extract: fn(message) -> Result(session_message, Nil),
  update update: fn(session_model, session_message) -> session_model,
  field_get field_get: fn(model) -> session_model,
  field_set field_set: fn(model, session_model) -> model,
) -> Wiring(model, message)

store.wiring()
|> store.session(
  extract: fn(message) {
    case message {
      Session(inner) -> Ok(inner)
      _ -> Error(Nil)
    }
  },
  update: session_update,
  field_get: fn(model: Model) { model.session },
  field_set: fn(model, session) { Model(..model, session:) },
)

pub fn topic(
  wiring: Wiring(model, message),
  id id: String,
  extract extract: fn(message) -> Result(topic_message, Nil),
  update update: fn(topic_model, topic_message) -> topic_model,
  field_get field_get: fn(model) -> topic_model,
  field_set field_set: fn(model, topic_model) -> model,
) -> Wiring(model, message)

store.wiring()
|> store.topic(
  id: "chat",
  extract: fn(message) {
    case message {
      Chat(inner) -> Ok(inner)
      _ -> Error(Nil)
    }
  },
  update: chat_update,
  field_get: fn(model: Model) { model.chat },
  field_set: fn(model, chat) { Model(..model, chat:) },
)

pub fn topic_kind(
  wiring: Wiring(model, message),
  prefix prefix: String,
  extract extract: fn(message) -> Result(
    #(String, kind_message),
    Nil,
  ),
  update update: fn(kind_model, kind_message) -> kind_model,
  field_get field_get: fn(model, String) -> kind_model,
  field_set field_set: fn(model, String, kind_model) -> model,
) -> Wiring(model, message)

store.wiring()
|> store.topic_kind(
  prefix: "room:",
  extract: fn(message) {
    case message {
      Room(id, inner) -> Ok(#(int.to_string(id), inner))
      _ -> Error(Nil)
    }
  },
  update: room_update,
  field_get: fn(model: Model, key) {
    dict.get(model.rooms, key) |> result.unwrap(new_room())
  },
  field_set: fn(model, key, room) {
    Model(..model, rooms: dict.insert(model.rooms, key, room))
  },
)

pub fn unwrap_local(local: Local(a)) -> a

pub fn wiring() -> Wiring(model, message)

store.wiring()
|> store.session(extract:, update:, field_get:, field_set:)
|> store.topic(id: "chat", extract:, update:, field_get:, field_set:)