DocsRealtime

Sync

Lists of records kept current in the browser over one WebSocket, in memory, and kept across visits when you ask.

A synced list (a shape) is a filtered view of a collection. The server sends its rows, then every row that enters, changes or leaves it, so you never fetch, fetch again or patch lists by hand. In React, use useLive:

app.tsx
import { useLive } from "@sluurp/react";

function Orders() {
  const { rows } = useLive("orders", { filter: 'customer = "cust000000001"' });
  return <ul>{rows.map((o) => <li key={o.id}>{o.total}</li>)}</ul>;
}

Outside React, new Sync().shape("orders", { filter }) gives the same rows as a signal, and shape.update(id, { total: 8 }, { reason: "Discount" }) writes optimistically: the change shows at once.

Features include:

  • One WebSocket for every list on the page, reconnecting on its own
  • Rows read as the signed-in user, every change checked again per client
  • Optimistic writes, taken back if the server refuses them
  • Lists answered in the browser first, and loaded before a click
  • Windows, related records kept current, and a signal per row
  • Live cursors, with shared state

How it behaves

  • One WebSocket (/api/sync) carries every list on the page, and reconnects on its own.
  • Rows are read as the signed-in user, through the collection’s rules. Each change is checked again for each client before it is sent, so an update can never leak a row the user can’t see.
  • No stale overwrites. The server sends the current row, not the event, so an older version never replaces a newer one.
  • Optimistic writes go through the usual API, and are taken back if the server refuses them.
  • keep: true shows the last rows at once on the next visit, from IndexedDB, until the server’s arrive. It is off by default, since the data stays on the device. Only small lists (up to 2,000 rows) are kept. The store is per user, so the next person on a shared computer never sees it, and signing out clears it.

Every list kept current

In the browser, listAll is backed by a synced list too. The first time a screen runs a query (a collection, a filter and a sort), the rows arrive over the sync socket. After that, the same query is answered locally, from rows kept up to date, with no request. In a single-page app, going back to a screen shows its data at once, with the changes other people made meanwhile. Right after the page writes to a collection, the next read goes to the server, so it includes the write.

Each kept query is a live subscription: it holds rows in memory, and the server checks it again on every write to that collection. So the store is limited by the memory its rows take (about 16 MB, or 32 MB on devices that report 8 GB of RAM or more) and by count (128). When either limit is reached, the query read least recently is dropped. Many small queries fit; a few large ones take the whole budget.

To always go to the server, set sluurp.syncedReads = false.

To make the page follow the rows, use useLive in React, or live (a signal) anywhere. A value made from two lists is worked out again when either changes, and only then:

app.tsx
import { live } from "@sluurp/client/sync";
import { computed } from "@sluurp/twist/signals";

const orders = live(sluurp.collection("orders"), { filter: 'region = "north"' });
const customers = live(sluurp.collection("customers"), { filter: 'region = "north"' });
const average = computed(() => mean(orders().filter((o) => customers().some((c) => c.id === o.customer)).map((o) => o.total)));

Answered in the browser first

A new list that only narrows one the page already holds is answered in the browser, at once, without waiting for the server. If the page holds every task, then the open tasks, or your open tasks, are there straight away. The server’s answer still follows, and keeps the list current.

app.ts
const tasks = live(sluurp.collection("tasks"));
// later, on another screen: answered from the rows above
const open = live(sluurp.collection("tasks"), { filter: "done = false" });

A list narrows another when its filter keeps every condition of the other and adds its own with &&. The browser checks the filter the way the server does. It leaves the answer to the server whenever it can’t be sure, for example for a relation path such as customer.region, or a number compared with text.

Writes work the same way. Mark a task done, and it leaves the open list at once. Create one, and it shows at once in every list whose filter takes it. If the server refuses the write, the change is taken back.

Loaded before the click

The browser notes which lists each address of your app reads in its first seconds. When someone is about to follow a link to that address, those lists start loading before the click, so the screen opens with its rows already there. “About to follow” means the pointer rests on the link, a finger touches it, or the keyboard moves to it.

There is nothing to declare: a screen says what it reads by reading it. The notes are kept per person, in the browser, and go when they sign out. Loading ahead is skipped when the browser asks to save data. To turn it off for one link, add data-preload="false", as for pages rendered on the server.

Loading and empty states

ready() says whether the server’s rows have arrived. Use it to show “No tasks yet” only when there really are none, not while the list is still loading:

app.tsx
const open = live(sluurp.collection("tasks"), { filter: "done = false" });

{open.ready() && !open().length ? <p>No open tasks.</p> : ""}

A single row works the same way. liveRow(collection, id).ready() says whether the row is known. Until then, undefined means “not here yet”; after that, it means there is no such row for you, and it’s safe to show “Not found”. A row that no list on the page holds is asked for on its own.

live(…).error() says why the server refused a list, for example a filter it couldn’t read. The kit’s Loading takes a list directly: <Loading of={open}>…</Loading>.

Windows

A list with limit keeps only its first rows, in sort order, such as the newest 50 posts or an inbox’s latest messages. The window stays full: a new post at the top pushes the last one out, and when one leaves, the next moves in. The server sends only what changed in the window, not the whole list again.

app.tsx
const posts = live(sluurp.collection("posts"), { sort: "-created_at", limit: 50 });

{posts.hasMore() ? <Button onClick={() => posts.loadMore()}>Show more</Button> : ""}
  • hasMore() says whether there are rows past the window.
  • loadMore(count) makes the window longer by count rows (by default, by its first limit). The rows it adds stay current too.

Without a limit, a list holds every row that matches, up to 20,000. Past that, the server asks for a narrower filter or a limit. A window is answered in the browser first, as other lists are, when the page holds the whole list it comes from.

expand embeds each row’s related records, as it does for the API, and keeps them current. Rename a customer, and every order showing that customer updates, even though the orders themselves didn’t change:

app.ts
const orders = live(sluurp.collection("orders"), { filter: `region = "north"`, expand: "customer" });
// orders()[0].expand.customer.name

It also works from the records that point at a row: each post with its three newest comments, and a new comment shown under its post as soon as it’s made.

app.ts
const posts = live(sluurp.collection("posts"), {
  sort: "-created_at",
  limit: 20,
  expand: { comments_via_post: { sort: "-created_at", limit: 3 } },
});
// posts()[0].expand.comments_via_post

The server tracks which related records each row shows. A change to one of them sends those rows again, read through the rules as you, so a related record you can’t read never reaches you. (Supabase’s realtime sends only the changed table’s own row, and leaves this join to the client.)

A signal per row

Every row on the page has its own signal, shared by every list that holds it. The server says which row changed, and only what read that row is worked out again: changing one row never re-runs code that read another.

app.tsx
import { liveRow } from "@sluurp/client/sync";

const a1 = liveRow(sluurp.collection("cells"), "demoa1000000000");
const doubled = computed(() => Number(a1()?.formula ?? 0) * 2);

update and delete apply at once to every list and row that holds the record, before the server answers, and are taken back if it refuses them. A created row appears at once in every list whose filter the browser can check; in any other list, it appears once the server says it belongs there. getOne(id) is answered locally from any synced list that holds the row, with no request, except right after a write to that collection, when it asks the server.

A row receives changes only while it is in a list the page holds (through live, listAll or a shape). The sheet example is a spreadsheet built this way: each cell is a row, and formulas read the rows they name. Change a value or a formula anywhere, and every browser works out again just what depends on it, and nothing else. See Examples.

What is synced, and what it costs

The admin’s System screen lists, under Synced lists, every list a browser keeps current in the project, grouped by who is connected. For each list it shows:

  • what the list asks for, and how many rows it holds;
  • how many changes it was kept current through, and the time the server spent on them, the slowest included;
  • how the database reads it: by an index, by going through the whole table, or by sorting the rows itself. Point at the label to see the database’s own plan.

A whole-table read is fine for a small table. For a large one, add an index on the fields the list filters or sorts by. A list turns red when keeping it current took 50 ms or more for one change.

Superusers can read the same list at GET /api/sync/connections.

Live cursors

@sluurp/client/cursors shows everyone’s pointer over a page, each in their own colour with a name label:

app.ts
import { liveCursors } from "@sluurp/client/cursors";
const stop = liveCursors("todos:*", { over: document.querySelector("main") });
  • Positions go over /api/ws, not stored, at most once per frame, and are smoothed so motion stays even on a jittery network.
  • An idle pointer starts fading after three seconds, and comes back when it moves.
  • Selected text (in inputs too) is quoted next to the pointer, within the tracked element only.
  • A topic is a record (lists:abc) or a whole collection (todos:*). Anyone who can list it can join.

To share more state, pass state, which is read each frame and sent when it changes. onState receives everyone else’s, with their name and colour. The Sheet uses this to show each person’s selection in their colour:

app.ts
liveCursors("cells:*", { over: table, state: () => area(), onState: (others) => theirs.set(others) });

Something people pan and zoom, such as a whiteboard or a map, gives its own coordinates with space. Each pointer is then shared in those units, and drawn at the same place on every screen, however each person has panned or zoomed. from turns a point in the window into the space’s units, and to turns it back:

app.ts
liveCursors("boards:abc", { over: canvas, space: { from: toCanvas, to: toWindow } });

When several things share one topic, such as two boards on one page, give each a channel. Each then shows only its own pointers.

View as Markdown