The store

The store is the UI's state. Every response becomes records keyed by type and id; records are observable objects; a view body that read a field is invalidated when that field of that record changes, and at no other time. This chapter follows a record from the bytes to the body, then to the disk and the next launch.

Records and keys#

A record is Type:id by default. baton.json configures identity for types keyed otherwise, by one field, by several, or for an interface whose implementers share a key; the compiler selects the key fields wherever the type is read, so a response always carries what the ingest needs. An object without a key gets a client id from its path, client:root:characters(page:1), as in Relay.

{
  "schema": "schema.graphql",
  "identity": {
    "types": {
      "Asset": ["uuid"],
      "Quote": ["base", "quote"]
    }
  }
}

A field is stored under its name, or under its name and its arguments when it has any: notes(first:2) and notes(after:"c2",first:2) are two slots of one record, and an argument whose value is null is left out, so the same page is the same slot whether or not the document mentioned after. The compiler computes every storage key without a variable in it and emits a constant, which the process numbers on first use; a key with variables is rendered once per owner and numbered by the store; a read hashes nothing.

{
  "data": {
    "character": {
      "name": "Agency Director",
      "status": "Dead",
      "species": "Human",
      "image": "https://rickandmortyapi.com/api/character/avatar/9.jpeg",
      "origin": {
        "name": "Earth (Replacement Dimension)",
        "id": "20"
      },
      "id": "9"
    }
  }
}

The commit#

A response's bytes are decoded straight into record slots, off the main actor, by the plan the compiler emitted, with no model tree in between: that is the ingest. What it produces is a change set, and the commit applies it on the main actor as one batch: a write of each slot that changed, nothing for a slot whose value is equal, and a notification for each observed field that changed, once, when the batch ends. A view never sees half a response.

{
  "data": {
    "character": {
      "id": "1",
      "name": "Rick Sanchez",
      "notes": {
        "totalCount": 5,
        "edges": [
          {
            "cursor": "c1",
            "node": {
              "__typename": "Note",
              "id": "n1",
              "text": "Wubba lubba dub dub"
            }
          },
          {
            "cursor": "c2",
            "node": {
              "__typename": "Note",
              "id": "n2",
              "text": "Portal gun needs charging"
            }
          }
        ],
        "pageInfo": {
          "endCursor": "c2",
          "hasNextPage": true
        }
      }
    }
  }
}

{
  "data": {
    "character": {
      "id": "1",
      "name": "Rick Sanchez",
      "notes": {
        "totalCount": 5,
        "edges": [
          {
            "cursor": "c1",
            "node": {
              "__typename": "Note",
              "id": "n1",
              "text": "Wubba lubba dub dub"
            }
          },
          {
            "cursor": "c2",
            "node": {
              "__typename": "Note",
              "id": "n2",
              "text": "Portal gun needs charging"
            }
          }
        ],
        "pageInfo": {
          "endCursor": "c2",
          "hasNextPage": true
        }
      }
    }
  }
}

{
  "data": {
    "character": {
      "id": "1",
      "name": "Rick C-137",
      "notes": {
        "totalCount": 5,
        "edges": [
          {
            "cursor": "c1",
            "node": {
              "__typename": "Note",
              "id": "n1",
              "text": "Wubba lubba dub dub"
            }
          },
          {
            "cursor": "c2",
            "node": {
              "__typename": "Note",
              "id": "n2",
              "text": "Portal gun needs charging"
            }
          }
        ],
        "pageInfo": {
          "endCursor": "c2",
          "hasNextPage": true
        }
      }
    }
  }
}

{
  "data": {
    "character": {
      "id": "1",
      "name": "Rick Sanchez",
      "origin": {
        "id": "1",
        "name": "Earth (C-137)"
      },
      "status": "Alive",
      "image": null,
      "location": {
        "id": "20",
        "name": null,
        "dimension": "Replacement Dimension"
      },
      "gender": null,
      "species": "Human",
      "type": null
    }
  },
  "errors": [
    {
      "message": "image service unavailable",
      "path": [
        "character",
        "image"
      ],
      "locations": [
        {
          "line": 1,
          "column": 1
        }
      ]
    },
    {
      "message": "location name redacted",
      "path": [
        "character",
        "location",
        "name"
      ]
    },
    {
      "message": "gender is private",
      "path": [
        "character",
        "gender"
      ]
    }
  ]
}

{
  "data": {
    "character": {
      "id": "1",
      "name": "Rick Sanchez",
      "origin": {
        "id": "1",
        "name": "Earth (C-137)"
      },
      "status": "Alive",
      "image": null,
      "location": {
        "id": "20",
        "name": null,
        "dimension": "Replacement Dimension"
      },
      "gender": null,
      "species": "Human",
      "type": null
    }
  }
}

Three kinds of batch: a server batch, which is written to the image; an optimistic one, which keeps its undo log with its layer and is never written to the image; a local one, the runtime's own writes, a page's loading flag or a lookup's link bound, which never reaches the image.

What a view observes#

Each record carries the UI framework's registrar, Observation's in Swift and a snapshot-state channel per slot in Kotlin, and each lens accessor registers the read of one field of one record. So the framework knows exactly which bodies depend on which slots, and the commit tells it which slots changed. There are no subscriptions of Baton's own, no snapshots to diff, and no watcher that re-executes a query.

CharactersQuery

Characters

Rick SanchezAlive · Human

CharactersScreen

Morty SmithAlive · Human

CharactersScreen

Summer SmithAlive · Human

CharactersScreen

Beth SmithAlive · Human

CharactersScreen

The store click a field to change it

client:rootQuery

characters(page:1)	client:root:characters(page:1)

client:root:characters(page:1)Characters

results	[ 4 links ]

Character:1Character

id	"1"
image	"https://rickandmortyapi.com/api/char…"
name	"Rick Sanchez"
species	"Human"
status	"Alive"

Character:2Character

id	"2"
image	"https://rickandmortyapi.com/api/char…"
name	"Morty Smith"
species	"Human"
status	"Alive"

Character:3Character

id	"3"
image	"https://rickandmortyapi.com/api/char…"
name	"Summer Smith"
species	"Human"
status	"Alive"

Character:4Character

id	"4"
image	"https://rickandmortyapi.com/api/char…"
name	"Beth Smith"
species	"Human"
status	"Alive"

0 of bodies re-ran

Nothing has changed yet.

A refetch answers with the same dataThe first row's name changesThe list gains a rowReset

A commit is ordinary main-actor state mutation, so a data-driven change animates like any other state change in the framework, with nothing of Baton's in the way.

Roots, retention, collection#

A record lives while a root reaches it. A root is an operation's selection and the record it starts from; a view holds a retention on its handle for its life, and when the last retention ends the root waits in a release buffer, ten by default, before its records become collectable, so going back to a screen just left is free. The store collects once per turn of the main thread after a root left or a commit dropped a link, marking from the roots, the optimistic layers and the image's write queue.

{
  "data": {
    "character": {
      "name": "Jerry Smith",
      "status": "Alive",
      "species": "Human",
      "image": "https://rickandmortyapi.com/api/character/avatar/5.jpeg",
      "origin": {
        "name": "Earth (Replacement Dimension)",
        "id": "20"
      },
      "id": "5"
    }
  }
}

The consequence for a scrolling list: memory plateaus, since the store releases what no view holds, and a page scrolled far out of view is a page that can go.

Ages and staleness#

The store stamps each root with the time of its last commit. A query's @cacheExpiration(seconds:), or the store's default, says how old its data may be before it reads as stale; environment.invalidate() marks everything stale and refetches what is retained; environment.revalidate() refetches what is stale or failed, for a return to the foreground or a connection regained. Stale data stays readable, and the age survives a launch, because the image keeps it.

{
  "data": {
    "character": {
      "name": "Jerry Smith",
      "status": "Alive",
      "species": "Human",
      "image": "https://rickandmortyapi.com/api/character/avatar/5.jpeg",
      "origin": {
        "name": "Earth (Replacement Dimension)",
        "id": "20"
      },
      "id": "5"
    }
  }
}

The image#

Every server batch is written behind to an image, one SQLite file, off the main actor: a row per record, a row per root field, each operation's fetch time. When a handle is made, the availability check reads from the image whatever memory lacks, so an operation an earlier launch fetched is ready before the first body, and the screen the user left is the screen they get back.

Store(persistence: Persistence(name: "App", version: Types.schemaDigest))

Store(persistence = Persistence.named("App", version = Types.schemaDigest, directory = cacheDir.path))

{
  "data": {
    "quotes": [
      {
        "rate": 1.5,
        "base": "BTC",
        "quote": "USD"
      },
      {
        "rate": 0.9,
        "base": "EUR",
        "quote": "USD"
      },
      {
        "rate": 2,
        "base": "A:B",
        "quote": "C\\D"
      }
    ]
  }
}

The image is a cache and nothing more. One written under another schema digest, another format or another identity configuration starts again rather than migrating; a record that goes a whole launch unread is dropped at the next; an image over its size limit evicts the rows of older launches first; optimistic layers never reach it. Types and root fields that must never touch the disk are named in baton.json under transient, and the lists join the schema's digest.

Client fields#

A field the server does not have, a pin or a draft, is described in a client schema extension named in baton.json and written by a payload committed by hand, environment.commitPayload(operation, payload), for an operation that selects it. It reads through a lens like any field, is left out of the text a server receives, and reaches the image like any record. There are no resolvers; a client field is data, described and committed.

extend type Character {
  """Whether the app pinned the character; the device's alone."""
  isPinned: Boolean
}

Looking inside#

StoreExport.text(of: environment.store), from BatonInspector, writes the store in the dump format every plate on this site uses: every record by key, sorted, one a line. A dump from a debug menu is a fixture a test can start from, and a diff of two dumps is a reviewable change to identity or layout. In Kotlin the same text is StoreExport.text(environment.store), from baton-inspector. Beside the export, StoreInspector is a live view of a store for a debug pane, a SwiftUI view in BatonInspector and a Compose one in baton-inspector.