@zubra/sync 5.6.0 → 5.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/sync",
-  "version": "5.6.0",
+  "version": "5.8.0",
   "description": "Local-first state for Zubra components: 'use collection' keeps a component's state in IndexedDB, across reloads, offline, and in step across tabs.",
   "type": "module",
   "main": "./src/index.js",
@@ -32,7 +32,7 @@
     "test:binary": "ZUBRA_SYNC_BACKEND=binary node --test test/browser.test.js"
   },
   "peerDependencies": {
-    "@zubra/runtime": "^5.6.0"
+    "@zubra/runtime": "^5.8.0"
   },
   "devDependencies": {
     "@zubra/compiler": "file:../compiler",

package/src/connect.d.ts

@@ -1,3 +1,5 @@
+import type { Scope } from './server.js';
+
 /**
  * Share 'use collection' documents through a log at `url` (default `/_zb/sync`), pulling every
  * `interval` ms (default 2000). Writes stay on the device first and go out when the network allows.
@@ -13,6 +15,12 @@ export function connect(options?: {
    * server carries introductions, goodbyes, signaling, and presence to anyone else.
    */
   webrtc?: boolean | { iceServers?: RTCIceServer[] };
+  /**
+   * Only what this page shows: per collection, `true` or a key prefix (or a list of them), e.g.
+   * `{ seats: 'showing-12/', brands: true }`. Changes and presence outside it aren't sent. Each
+   * scope keeps its own cursor. Leave it out for everything.
+   */
+  scope?: Scope;
 }): {
   flush(): Promise<void>;
   pull(): Promise<void>;

package/src/connect.js

@@ -7,13 +7,13 @@
 //
 // The protocol (plan/sync-design.md), plain HTTP so any server can keep the log:
 //   POST <url>/push  { changes: [Change] }            → { ok: true }
-//   GET  <url>/pull?since=<cursor>                     → { changes: [Change], cursor }
+//   GET  <url>/pull?since=<cursor>[&scope=<json>]      → { changes: [Change], cursor }
 //   Change = { collection, key, field, value, clock }  (clock: a hybrid logical clock, a string
 //   that sorts by time, then counter, then client id)
 //
 // Merging is last-writer-wins per field, by clock. A device that was offline pushes what it
 // wrote when it's back; whichever write has the later clock wins, on every device alike.
-import { onWrite, receive, currentStore, onPresence, receivePresence, peerId } from './index.js';
+import { onWrite, receive, currentStore, onPresence, receivePresence, peerId, startingPull } from './index.js';
 import { mesh } from './webrtc.js';
 
 const CLOCKS = '$clocks';
@@ -36,15 +36,22 @@ function clock(client) {
  * server has it, exactly those changes leave (`done`): by identity, not by count, so a change
  * added while an earlier push was out is never dropped by it. Two pushes can overlap (the debounce
  * and the poll loop); this is why that's safe.
+ *
+ * It keeps one change per field: a newer one replaces what's waiting for the same field (this
+ * device's later write wins anyway), so hours of typing offline wait as one change per field,
+ * not one per keystroke, and still fit in localStorage.
  */
 export function outboxOf(changes = [], persist = () => {}) {
-  let pending = changes;
+  const same = (a, b) => a.collection === b.collection && a.key === b.key && a.field === b.field;
+  let pending = [];
+  for (const change of changes) pending = [...pending.filter((other) => !same(other, change)), change];
   return {
     get size() {
       return pending.length;
     },
     pending: () => pending.slice(),
     add(change) {
+      pending = pending.filter((other) => !same(other, change));
       pending.push(change);
       persist(pending);
     },
@@ -64,27 +71,45 @@ const keep = (name, value) => { try { localStorage.setItem(name, value); } catch
 
 /**
  * Start sharing. `url`: where the log is (`/_zb/sync`). `interval`: how often to pull, in ms
- * (default 2000). Returns `{ flush, pull, stop }`.
+ * (default 2000). `scope`: only what this page shows, per collection `true` or a key prefix (or a
+ * list of them), e.g. `{ seats: 'showing-12/', brands: true }`; leave it out for everything.
+ * Returns `{ flush, pull, stop }`.
  */
-export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrtc = false } = {}) {
+export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrtc = false, scope = null } = {}) {
   const base = url.replace(/\/$/, '');
+  // The scope goes with every pull and live request. Each scope keeps its own cursor: a page that
+  // moves to another showing reads that showing from the start, not from where the last one was.
+  const scoped = scope ? `&scope=${encodeURIComponent(JSON.stringify(scope))}` : '';
+  const cursorName = scope ? `zubra-sync:cursor:${JSON.stringify(scope)}` : 'zubra-sync:cursor';
   const client = remember('zubra-sync:client', () => {
     const id = Math.random().toString(36).slice(2, 10);
     keep('zubra-sync:client', id);
     return id;
   });
   const clocks = clock(client);
-  let cursor = remember('zubra-sync:cursor', () => '0');
+  let cursor = remember(cursorName, () => '0');
   const outbox = outboxOf(JSON.parse(remember('zubra-sync:outbox', () => '[]')), (pending) =>
     keep('zubra-sync:outbox', JSON.stringify(pending)));
 
+  // This device's stamps, kept here the moment a field is edited. Storing them beside the document
+  // takes an await, and a change from elsewhere merged in that time must still lose to them.
+  const mine = new Map(); // JSON [collection, key] → { field: clock }
+  const newest = (a, b) => (a && (!b || a > b) ? a : b);
+  const own = ({ collection, key, field, clock: stamp }) => {
+    const id = JSON.stringify([collection, key]);
+    if (!mine.has(id)) mine.set(id, {});
+    mine.get(id)[field] = newest(stamp, mine.get(id)[field]);
+  };
+
   // Local writes: stamp each field, remember the stamp beside the document, queue it.
   const off = onWrite(async (collection, key, fields) => {
     const stamped = {};
     for (const [field, value] of Object.entries(fields)) {
       const stamp = clocks.tick();
       stamped[field] = stamp;
-      outbox.add({ collection, key, field, value, clock: stamp });
+      const change = { collection, key, field, value, clock: stamp };
+      own(change);
+      outbox.add(change);
     }
     const doc = (await currentStore().get(collection, key)) ?? {};
     await currentStore().set(collection, key, { [CLOCKS]: { ...doc[CLOCKS], ...stamped } });
@@ -116,7 +141,7 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
   async function pull() {
     let body;
     try {
-      const response = await fetch(`${base}/pull?since=${encodeURIComponent(cursor)}`);
+      const response = await fetch(`${base}/pull?since=${encodeURIComponent(cursor)}${scoped}`);
       if (!response.ok) return;
       body = await response.json();
     } catch {
@@ -139,22 +164,27 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
       if (!byDoc.has(id)) byDoc.set(id, []);
       byDoc.get(id).push(change);
     }
-    for (const changes of byDoc.values()) {
+    for (const [id, changes] of byDoc) {
       const { collection, key } = changes[0];
       const doc = (await currentStore().get(collection, key)) ?? {};
+      // What's stored, and what this device has stamped since that may not be stored yet.
       const known = { ...doc[CLOCKS] };
+      for (const [field, stamp] of Object.entries(mine.get(id) ?? {})) known[field] = newest(stamp, known[field]);
       const fields = {};
       for (const change of changes) {
         if (known[change.field] && known[change.field] >= change.clock) continue;
         known[change.field] = change.clock;
         fields[change.field] = change.value;
       }
-      if (Object.keys(fields).length) await receive(collection, key, { ...fields, [CLOCKS]: known });
+      // An edit made here while the change was being stored still wins on screen.
+      const stillNewer = (field) => field === CLOCKS || !(mine.get(id)?.[field] > known[field]);
+      if (Object.keys(fields).length) await receive(collection, key, { ...fields, [CLOCKS]: known }, stillNewer);
     }
-    // Never move the cursor back (a live backlog can arrive after a newer push).
+    // Never move the cursor back (a live backlog can arrive after a newer push), unless the server
+    // says this device's cursor was past the end of its log: then it starts over from what it sent.
     const next = String(body.cursor);
-    if (!(/^\d+$/.test(next) && /^\d+$/.test(cursor) && Number(next) < Number(cursor))) cursor = next;
-    keep('zubra-sync:cursor', cursor);
+    if (body.reset || !(/^\d+$/.test(next) && /^\d+$/.test(cursor) && Number(next) < Number(cursor))) cursor = next;
+    keep(cursorName, cursor);
   }
 
   // Live: a server-sent event stream brings changes as they're pushed, and other viewers'
@@ -164,7 +194,7 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
   let retry = null;
   const listen = () => {
     if (!live || typeof EventSource === 'undefined' || stopped) return;
-    source = new EventSource(`${base}/live?since=${encodeURIComponent(cursor)}&peer=${encodeURIComponent(peerId())}`);
+    source = new EventSource(`${base}/live?since=${encodeURIComponent(cursor)}&peer=${encodeURIComponent(peerId())}${scoped}`);
     source.addEventListener('open', () => (open = true));
     source.addEventListener('changes', (event) => apply(JSON.parse(event.data)));
     source.addEventListener('presence', (event) => {
@@ -215,7 +245,32 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
   const loop = setInterval(() => flush().then(() => (open ? undefined : pull())), interval);
   const online = () => flush().then(pull);
   addEventListener('online', online);
-  flush().then(pull).then(listen);
+  // What's still waiting to be sent is newer than what's stored wherever the store says otherwise:
+  // a tab that closed with writes queued can leave the stored value behind the outbox.
+  async function replay() {
+    const byDoc = new Map();
+    for (const change of outbox.pending()) {
+      const id = JSON.stringify([change.collection, change.key]);
+      byDoc.set(id, [...(byDoc.get(id) ?? []), change]);
+    }
+    for (const changes of byDoc.values()) {
+      const { collection, key } = changes[0];
+      const doc = (await currentStore().get(collection, key)) ?? {};
+      const known = { ...doc[CLOCKS] };
+      const fields = {};
+      for (const change of changes) {
+        if (known[change.field] && known[change.field] >= change.clock) continue;
+        known[change.field] = change.clock;
+        fields[change.field] = change.value;
+      }
+      if (Object.keys(fields).length) await receive(collection, key, { ...fields, [CLOCKS]: known });
+    }
+  }
+
+  // Components wait for this first pull before applying what's stored (index.js: fresh first).
+  const first = (applying = applying.then(replay).catch(() => {})).then(flush).then(pull);
+  startingPull(first);
+  first.then(listen);
   return {
     flush,
     pull,

package/src/durable-log.d.ts

@@ -7,7 +7,8 @@ export interface DurableObjectStorageLike {
 }
 
 /**
- * A sync log in a Durable Object's SQLite: the table and cursors `sqliteLog` uses. `table` names
- * the table (default `changes`), if the object keeps tables of its own.
+ * A sync log in a Durable Object's SQLite: the tables and cursors `sqliteLog` uses. `keep:
+ * 'latest'` keeps each field's latest value only. `table` names the table (default `changes`, or
+ * `latest`), if the object keeps tables of its own.
  */
-export function durableObjectLog(storage: DurableObjectStorageLike, options?: { table?: string }): Log;
+export function durableObjectLog(storage: DurableObjectStorageLike, options?: { table?: string; keep?: 'all' | 'latest' }): Log;

package/src/durable-log.js

@@ -1,44 +1,28 @@
-// A sync log in a Cloudflare Durable Object's own SQLite (`ctx.storage.sql`): the same table and
-// the same cursors as `sqliteLog`, so a log can move between Node and a Durable Object. It runs
-// anywhere a Durable Object's storage is passed in; nothing here imports Workers' modules.
+// A sync log in a Cloudflare Durable Object's own SQLite (`ctx.storage.sql`): the same tables and
+// cursors as `sqliteLog`, so a log can move between Node and a Durable Object. It runs anywhere a
+// Durable Object's storage is passed in; nothing here imports Workers' modules.
 //
 //   import { createSyncServer } from '@zubra/sync/server';
 //   import { durableObjectLog } from '@zubra/sync/durable';
-//   const sync = createSyncServer({ log: durableObjectLog(ctx.storage) });
+//   const sync = createSyncServer({ log: durableObjectLog(ctx.storage, { keep: 'latest' }) });
 //
-// `table` names the table, if the object keeps tables of its own (default `changes`). Appends are
-// one transaction (`transactionSync`): a batch is written whole or not at all.
-const NAME = /^[A-Za-z_][\w]{0,62}$/;
+// `keep: 'latest'` keeps each field's latest value only (see sql-log.js); by default every change
+// is kept. `table` names the table, if the object keeps tables of its own (default `changes`, or
+// `latest`). Appends are one transaction (`transactionSync`): a batch is written whole or not at all.
+import { sqlLog } from './sql-log.js';
 
-export function durableObjectLog(storage, { table = 'changes' } = {}) {
+export function durableObjectLog(storage, { table, keep = 'all' } = {}) {
   if (!storage?.sql || typeof storage.transactionSync !== 'function') {
     throw new TypeError("durableObjectLog(storage): pass a Durable Object's `ctx.storage` (SQLite-backed)");
   }
-  if (!NAME.test(table)) throw new TypeError('durableObjectLog: `table` is a plain SQL name (letters, digits, _)');
   const { sql } = storage;
-  sql.exec(`CREATE TABLE IF NOT EXISTS ${table} (
-    seq INTEGER PRIMARY KEY AUTOINCREMENT,
-    collection TEXT NOT NULL,
-    key TEXT NOT NULL,
-    field TEXT NOT NULL,
-    value TEXT,
-    clock TEXT NOT NULL
-  )`);
-  const last = () => Number(sql.exec(`SELECT COALESCE(MAX(seq), 0) AS seq FROM ${table}`).one().seq);
-  return {
-    async append(changes) {
-      return storage.transactionSync(() => {
-        for (const { collection, key, field, value, clock } of changes) {
-          sql.exec(`INSERT INTO ${table} (collection, key, field, value, clock) VALUES (?, ?, ?, ?, ?)`, collection, key, field, JSON.stringify(value ?? null), clock);
-        }
-        return last();
-      });
+  return sqlLog(
+    {
+      exec: (query) => sql.exec(query),
+      run: (query, ...args) => sql.exec(query, ...args),
+      all: (query, ...args) => sql.exec(query, ...args).toArray(),
+      transaction: (fn) => storage.transactionSync(fn),
     },
-    async after(cursor, limit = 1000) {
-      const from = Number(cursor) || 0;
-      const rows = sql.exec(`SELECT seq, collection, key, field, value, clock FROM ${table} WHERE seq > ? ORDER BY seq LIMIT ?`, from, limit).toArray();
-      const changes = rows.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value: JSON.parse(value), clock }));
-      return { changes, cursor: rows.length ? Number(rows[rows.length - 1].seq) : from };
-    },
-  };
+    { keep, table, label: 'durableObjectLog' },
+  );
 }

package/src/index.js

@@ -39,15 +39,48 @@ const theStore = () => (store ??= typeof indexedDB === 'undefined' ? memoryStore
 const writers = new Set();
 /** @internal Called with `(collection, key, fields)` on each local save. */
 export const onWrite = (fn) => (writers.add(fn), () => writers.delete(fn));
-/** @internal A change from elsewhere: store it, and show it in this tab and the others. */
-export async function receive(collection, key, fields) {
+/**
+ * @internal A change from elsewhere: store it, and show it in this tab and the others. `keep(field)`
+ * is asked again before showing it: a field edited here while it was being stored isn't shown.
+ */
+export async function receive(collection, key, fields, keep = () => true) {
   await theStore().set(collection, key, fields);
-  deliver(collection, key, fields, null);
-  channel?.postMessage({ collection, key, fields });
+  const shown = Object.fromEntries(Object.entries(fields).filter(([field]) => keep(field)));
+  deliver(collection, key, shown, null);
+  channel?.postMessage({ collection, key, fields: shown });
 }
 /** @internal The store in use. */
 export const currentStore = () => theStore();
 
+// Fresh first: a page connected to a log reads it before a component applies what this device
+// stored last time, so a returning visitor never sees last visit's state over the server's (or
+// over a page the server just rendered). Offline, the pull fails at once and stored values show.
+const FRESH_WAIT = 1500; // and never longer than this
+let firstPull = null;
+/** @internal connect() hands over its first pull, as it starts. */
+export const startingPull = (pull) => {
+  firstPull = Promise.resolve(pull).catch(() => {});
+};
+/**
+ * Before reading a stored document: wait until the page's own scripts have run (they finish before
+ * DOMContentLoaded, and connect() is one of them), then for the first pull if there is a connection.
+ */
+const fresh = () =>
+  scriptsDone().then(() => (firstPull ? Promise.race([firstPull, new Promise((done) => setTimeout(done, FRESH_WAIT))]) : undefined));
+let scripts = null;
+const scriptsDone = () =>
+  (scripts ??= (() => {
+    if (typeof document === 'undefined' || document.readyState === 'complete') return Promise.resolve();
+    // Navigation timing says whether DOMContentLoaded has already started (readyState is
+    // 'interactive' both while module scripts run and after).
+    const navigation = globalThis.performance?.getEntriesByType?.('navigation')?.[0];
+    if (navigation && navigation.domContentLoadedEventStart > 0) return Promise.resolve();
+    return new Promise((done) => {
+      document.addEventListener('DOMContentLoaded', done, { once: true });
+      setTimeout(done, FRESH_WAIT);
+    });
+  })());
+
 // Every bound element, by document, so a write reaches the others (this tab and, below, others).
 const bound = new Map();
 const docId = (collection, key) => `${collection}\u0000${key}`;
@@ -142,8 +175,8 @@ export function collection(name, keys, props, fields, presenceFields = null, pee
     let cancelled = false;
     // What the fields hold as loading starts, to tell what someone changed while it loaded.
     const before = Signal.subtle.untrack(values);
-    theStore()
-      .get(name, key)
+    fresh()
+      .then(() => theStore().get(name, key))
       .then((doc = {}) => {
         if (cancelled) return;
         // An edit made before the document arrived is newer than it: keep the edit (and save

package/src/server.d.ts

@@ -10,19 +10,36 @@ export interface Change {
 export interface Log {
   append(changes: Change[]): Promise<unknown>;
   after(cursor: string, limit?: number): Promise<{ changes: Change[]; cursor: number | string }>;
+  /**
+   * The cursor after the last change. Optional: with it, a device whose cursor is past the end
+   * (the log was replaced) is answered from the start, with `reset: true`.
+   */
+  head?(): Promise<number>;
 }
 
-export function memoryLog(): Log;
+/** A log in memory. `keep: 'latest'` keeps each field's latest value only. */
+export function memoryLog(options?: { keep?: 'all' | 'latest' }): Log;
 
 export interface Documents {
   /** A document's fields (a copy), or undefined when nothing has been written to it. */
   get(collection: string, key: string): Record<string, unknown> | undefined;
-  /** Every document in a collection, each with its key. */
-  all(collection: string): Array<{ key: string } & Record<string, unknown>>;
+  /**
+   * Every document in a collection whose key starts with `prefix` (all of them by default), each
+   * with its key, in the order they were first written to.
+   */
+  all(collection: string, prefix?: string): Array<{ key: string } & Record<string, unknown>>;
   /** The collections that have documents, in the order they were first written to. */
   collections(): string[];
 }
 
+/** Per collection, `true` (every document) or a key prefix, or a list of them. */
+export type Scope = Record<string, true | string | string[]>;
+
+/** A scope from a request's `?scope=` (JSON), or null for everything. Throws on anything else. */
+export function parseScope(text: string | null | undefined): Scope | null;
+/** Whether a document is in a scope (null is everything). */
+export function inScope(scope: Scope | null, collection: string, key: string): boolean;
+
 export function createSyncServer(options?: {
   log?: Log;
   /** Default `/_zb/sync`. */
@@ -34,6 +51,12 @@ export function createSyncServer(options?: {
    */
   authorize?: (from: { request: Request; collection: string; key: string; write: boolean; kind: 'change' | 'presence' | 'read' }) => boolean | Promise<boolean>;
   /** Other origins allowed to push. */
+  /**
+   * The scope a request may see and write (tenancy: a business's keys under its own prefix), or
+   * null for everything. A page's own `scope` can only narrow it; pushes and joins outside it are
+   * refused.
+   */
+  scope?: (from: { request: Request }) => Scope | null | Promise<Scope | null>;
   origins?: string[];
   /** How often the live stream sends a keep-alive comment (ms, default 15000). */
   heartbeat?: number;

package/src/server.js

@@ -20,6 +20,16 @@
 //   const left = docs.get('stock', 'eggs')?.qty ?? 0;   // read and write with no await between,
 //   if (left > 0) sync.write('stock', 'eggs', { qty: left - 1 });   // and no request interleaves
 //
+// Scope: a page asks only for what it shows. `?scope=` on pull and live is JSON, per collection
+// `true` or a key prefix (or a list of them): `{ "seats": "showing-12/", "brands": true }`.
+// Changes and presence outside it aren't sent. `scope({ request })` imposes one from the server
+// (tenancy: each business's keys under its own prefix), which the page's can only narrow; writes
+// and joins outside it are refused.
+//
+// A cursor past the end of the log (the log was replaced, or compacted, or this device's cursor
+// is from another log) starts over: pull and live answer from the beginning, with `reset: true`,
+// and the device takes the new cursor. Logs that can say where they end have `head()`.
+//
 // Live: `GET <mount>/live?since=<cursor>&peer=<id>` is a server-sent event stream: `changes` as
 // they're pushed, and `presence` from the other viewers (POST <mount>/presence). Subscribers are
 // this process's; several server processes need a shared log and a pub/sub between them.
@@ -27,8 +37,14 @@
 // On Node, `handle(req, res)` answers sync requests (streaming the live ones) and returns true.
 export const MOUNT = '/_zb/sync';
 
-/** A log in memory: `append(changes)` and `after(cursor)`. */
-export function memoryLog() {
+/**
+ * A log in memory: `append(changes)` and `after(cursor)`. `keep: 'latest'` keeps each field's
+ * latest value only (a newer clock replaces it and takes the next cursor, an older one is dropped),
+ * as `sqliteLog(path, { keep: 'latest' })` does.
+ */
+export function memoryLog({ keep = 'all' } = {}) {
+  if (keep === 'latest') return latestInMemory();
+  if (keep !== 'all') throw new TypeError("memoryLog: `keep` is 'all' or 'latest'");
   const changes = [];
   return {
     async append(more) {
@@ -39,9 +55,67 @@ export function memoryLog() {
       const from = Number(cursor) || 0;
       return { changes: changes.slice(from, from + limit), cursor: Math.min(changes.length, from + limit) };
     },
+    head: async () => changes.length,
   };
 }
 
+function latestInMemory() {
+  const rows = new Map(); // collection, key, field → { change, seq }
+  let seq = 0;
+  return {
+    async append(more) {
+      for (const change of more) {
+        const id = JSON.stringify([change.collection, change.key, change.field]);
+        const had = rows.get(id);
+        if (had && had.change.clock >= change.clock) continue;
+        rows.set(id, { change: structuredClone(change), seq: ++seq });
+      }
+      return seq;
+    },
+    async after(cursor, limit = 1000) {
+      const from = Number(cursor) || 0;
+      const page = [...rows.values()].filter((row) => row.seq > from).sort((a, b) => a.seq - b.seq).slice(0, limit);
+      return { changes: page.map((row) => structuredClone(row.change)), cursor: page.length ? page[page.length - 1].seq : from };
+    },
+    head: async () => seq,
+  };
+}
+
+/**
+ * A scope from a request's `?scope=`: `{ collection: true | prefix | [prefixes] }`, or null for
+ * everything. Throws on anything else.
+ */
+export function parseScope(text) {
+  if (text === null || text === undefined || text === '') return null;
+  let scope;
+  try {
+    scope = JSON.parse(text);
+  } catch {
+    throw new TypeError('scope is JSON');
+  }
+  if (scope === null) return null;
+  checkScope(scope);
+  return scope;
+}
+
+function checkScope(scope) {
+  const prefix = (each) => typeof each === 'string' && each.length <= 200;
+  const ok =
+    scope !== null && typeof scope === 'object' && !Array.isArray(scope) && Object.keys(scope).length <= 100 &&
+    Object.values(scope).every((each) => each === true || prefix(each) || (Array.isArray(each) && each.length <= 50 && each.every(prefix)));
+  if (!ok) throw new TypeError('scope is { collection: true | "key prefix" | ["prefixes"] }');
+}
+
+/** Whether a document is in a scope (null is everything). */
+export function inScope(scope, collection, key) {
+  if (!scope) return true;
+  const rule = scope[collection]; // inherited properties (constructor…) are none of these
+  if (rule === true) return true;
+  if (typeof rule === 'string') return key.startsWith(rule);
+  if (Array.isArray(rule)) return rule.some((prefix) => key.startsWith(prefix));
+  return false;
+}
+
 const json = (status, value) => new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json' } });
 
 // A clock is `<15-digit ms>-<5-digit counter>-<device>`, so clocks compare as strings.
@@ -71,8 +145,14 @@ export function documentsView({ find, list, names }) {
       const fields = find(collection, key);
       return fields && structuredClone(fields);
     },
-    /** Every document in a collection: `[{ key, ...fields }]`. */
-    all: (collection) => list(collection).map(({ key, fields }) => ({ key, ...structuredClone(fields) })),
+    /**
+     * Every document in a collection whose key starts with `prefix` (all of them by default):
+     * `[{ key, ...fields }]`, in the order they were first written to.
+     */
+    all: (collection, prefix = '') =>
+      list(collection)
+        .filter(({ key }) => key.startsWith(prefix))
+        .map(({ key, fields }) => ({ key, ...structuredClone(fields) })),
     /** The collections that have documents, in the order they were first written to. */
     collections: () => names(),
   };
@@ -108,7 +188,7 @@ function documentsOf() {
   };
 }
 
-export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize = () => true, origins = [], heartbeat = 15_000, device = 'server' } = {}) {
+export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize = () => true, scope: serverScope = () => null, origins = [], heartbeat = 15_000, device = 'server' } = {}) {
   if (!/^[\w-]{1,40}$/.test(device)) throw new Error('createSyncServer: `device` names the server in its clocks: letters, digits, - and _');
   const base = mount.replace(/\/$/, '');
   // Appends, one after another, so the log's order is the order they were made in.
@@ -175,22 +255,48 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
     const at = room.indexOf('/');
     return at > 0 ? { collection: room.slice(0, at), key: room.slice(at + 1) } : null;
   };
-  async function broadcastChanges(changes, cursor) {
-    for (const listener of listeners) {
-      const visible = [];
-      for (const change of changes) {
-        if (await authorize({ request: listener.request, collection: change.collection, key: change.key, write: false, kind: 'read' })) visible.push(change);
-      }
-      listener.send('changes', { changes: visible, cursor });
+  /**
+   * What a request may see: inside the server's scope for it and the page's own, and allowed by
+   * authorize. `where` is `{ request, scopes: [server, page] }`.
+   */
+  const sees = async ({ request, scopes }, collection, key) =>
+    scopes.every((scope) => inScope(scope, collection, key)) && (await authorize({ request, collection, key, write: false, kind: 'read' }));
+  async function visible(where, changes) {
+    const shown = [];
+    for (const change of changes) if (await sees(where, change.collection, change.key)) shown.push(change);
+    return shown;
+  }
+  /** The server's scope for a request and the page's (`?scope=`), or a Response refusing it. */
+  async function scopesOf(request, url) {
+    let page;
+    try {
+      page = parseScope(url.searchParams.get('scope'));
+    } catch (error) {
+      return json(400, { error: error.message });
     }
+    const server = (await serverScope({ request })) ?? null;
+    if (server) checkScope(server);
+    return [server, page];
+  }
+  /** Where to read from for a device at `since`: from the start if it's past the end of the log. */
+  async function startFrom(since) {
+    const head = await log.head?.();
+    const at = Number(since);
+    if (head === undefined || !/^\d+$/.test(String(since)) || at <= Number(head)) return { since, reset: false };
+    return { since: '0', reset: true };
+  }
+  async function broadcastChanges(changes, cursor) {
+    for (const listener of listeners) listener.send('changes', { changes: await visible(listener, changes), cursor });
   }
   async function broadcastPresence(message) {
     const { collection, key } = roomOf(message.room);
     for (const listener of listeners) {
       if (listener.peer === message.peer) continue;
-      if (await authorize({ request: listener.request, collection, key, write: false, kind: 'read' })) listener.send('presence', message);
+      if (await sees(listener, collection, key)) listener.send('presence', message);
     }
   }
+  /** Whether the server's scope lets this request write to (or join) a document. */
+  const mayWrite = async (request, collection, key) => inScope((await serverScope({ request })) ?? null, collection, key);
   const sameOrigin = (request) => {
     const site = request.headers.get('sec-fetch-site');
     if (site) return site === 'same-origin' || site === 'none';
@@ -211,6 +317,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       const changes = Array.isArray(body?.changes) ? body.changes : null;
       if (!changes || !changes.every(valid)) return json(400, { error: 'Expected { changes: [{ collection, key, field, value, clock }] }' });
       for (const change of changes) {
+        if (!(await mayWrite(request, change.collection, change.key))) return json(403, { error: 'Not yours to change' });
         if (!(await authorize({ request, collection: change.collection, key: change.key, write: true, kind: 'change' }))) return json(403, { error: 'Not yours to change' });
       }
       const appended = changes.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value, clock }));
@@ -233,7 +340,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!room || !okPeer || !okState || JSON.stringify(message.state).length > 4096) {
         return json(400, { error: 'Expected { room: "<collection>/<key>", peer, state: {…} | null }' });
       }
-      if (!(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
+      if (!(await mayWrite(request, room.collection, room.key)) || !(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
       const clean = { room: message.room, peer: message.peer, state: message.state };
       for (const listener of listeners) if (listener.peer === clean.peer) {
         if (clean.state === null) listener.rooms.delete(clean.room);
@@ -258,7 +365,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!room || !peerOk(message.from) || !peerOk(message.to) || !dataOk) {
         return json(400, { error: 'Expected { room, from, to, data: {…} }' });
       }
-      if (!(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
+      if (!(await mayWrite(request, room.collection, room.key)) || !(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
       const clean = { room: message.room, from: message.from, to: message.to, data: message.data };
       for (const listener of listeners) if (listener.peer === clean.to) listener.send('signal', clean);
       return json(200, { ok: true });
@@ -266,7 +373,9 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
     if (url.pathname === `${base}/live` && request.method === 'GET') {
       const peer = url.searchParams.get('peer') ?? '';
       if (!/^[\w-]{0,40}$/.test(peer)) return json(400, { error: 'Bad peer id' });
-      const since = url.searchParams.get('since') ?? '0';
+      const scopes = await scopesOf(request, url);
+      if (scopes instanceof Response) return scopes;
+      const { since, reset } = await startFrom(url.searchParams.get('since') ?? '0');
       let listener;
       let timer;
       const stream = new ReadableStream({
@@ -285,7 +394,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
             for (const room of listener.rooms) broadcastPresence({ room, peer, state: null });
             try { controller.close(); } catch {}
           };
-          listener = { peer, request, rooms: new Set(), send: (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`), close };
+          listener = { peer, request, scopes, rooms: new Set(), send: (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`), close };
           listeners.add(listener);
           request.signal?.addEventListener('abort', close);
           write('retry: 1000\n\n');
@@ -298,11 +407,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
           for (let first = true; ; first = false) {
             const backlog = await log.after(from);
             if (!backlog.changes.length && !first) break;
-            const visible = [];
-            for (const change of backlog.changes) {
-              if (await authorize({ request, collection: change.collection, key: change.key, write: false, kind: 'read' })) visible.push(change);
-            }
-            listener.send('changes', { changes: visible, cursor: backlog.cursor });
+            listener.send('changes', { changes: await visible(listener, backlog.changes), cursor: backlog.cursor, ...(reset && first ? { reset: true } : {}) });
             if (!backlog.changes.length || String(backlog.cursor) === String(from)) break;
             from = backlog.cursor;
           }
@@ -316,12 +421,11 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       });
     }
     if (url.pathname === `${base}/pull` && request.method === 'GET') {
-      const { changes, cursor } = await log.after(url.searchParams.get('since') ?? '0');
-      const visible = [];
-      for (const change of changes) {
-        if (await authorize({ request, collection: change.collection, key: change.key, write: false, kind: 'read' })) visible.push(change);
-      }
-      return json(200, { changes: visible, cursor });
+      const scopes = await scopesOf(request, url);
+      if (scopes instanceof Response) return scopes;
+      const { since, reset } = await startFrom(url.searchParams.get('since') ?? '0');
+      const { changes, cursor } = await log.after(since);
+      return json(200, { changes: await visible({ request, scopes }, changes), cursor, ...(reset ? { reset: true } : {}) });
     }
     if (url.pathname.startsWith(`${base}/`)) return json(404, { error: 'Not found' });
     return null;

package/src/sql-log.js

@@ -0,0 +1,86 @@
+// A sync log in SQL, over any SQLite: Node's and Bun's (sqliteLog) and a Durable Object's
+// (durableObjectLog) hand it the same three calls. Two ways to keep it:
+//
+// - `keep: 'all'` (the default): every change, in the order it came. A table `changes`, cursor =
+//   row id. What `sqliteLog()` has always written; the zubra-sync binary reads the same table.
+// - `keep: 'latest'`: each field's latest value only. A table `latest`, one row per field: a
+//   change with a newer clock replaces the row and takes the next cursor, an older one is dropped.
+//   `after(cursor)` hands out each field's latest value once, so a new device reads what's there
+//   now, not the whole evening's history. Opening it over a database that has a `changes` table
+//   and no `latest` one carries each field's latest value across, numbered after the old log's
+//   last cursor, so a device that had read the old log reads the carried values again and misses
+//   nothing.
+//
+// `db` is `{ exec(sql), run(sql, ...args), all(sql, ...args), transaction(fn) }`.
+const NAME = /^[A-Za-z_][\w]{0,62}$/;
+
+export function sqlLog(db, { keep = 'all', table, from = 'changes', label = 'log' } = {}) {
+  if (keep !== 'all' && keep !== 'latest') throw new TypeError(`${label}: \`keep\` is 'all' or 'latest'`);
+  table ??= keep === 'all' ? 'changes' : 'latest';
+  for (const name of [table, from]) if (!NAME.test(name)) throw new TypeError(`${label}: a table is a plain SQL name (letters, digits, _)`);
+  const json = (value) => JSON.stringify(value ?? null);
+  const read = (rows) => rows.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value: JSON.parse(value), clock }));
+  const last = () => Number(db.all(`SELECT COALESCE(MAX(seq), 0) AS seq FROM ${table}`)[0].seq);
+
+  if (keep === 'all') {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${table} (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      collection TEXT NOT NULL,
+      key TEXT NOT NULL,
+      field TEXT NOT NULL,
+      value TEXT,
+      clock TEXT NOT NULL
+    )`);
+  } else {
+    const exists = (name) => db.all(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`, name).length > 0;
+    const fresh = !exists(table);
+    db.exec(`CREATE TABLE IF NOT EXISTS ${table} (
+      collection TEXT NOT NULL,
+      key TEXT NOT NULL,
+      field TEXT NOT NULL,
+      value TEXT,
+      clock TEXT NOT NULL,
+      seq INTEGER NOT NULL UNIQUE,
+      PRIMARY KEY (collection, key, field)
+    )`);
+    if (fresh && from !== table && exists(from)) {
+      // Each field's latest change (the later clock; the later row if two share one), in log
+      // order, numbered after the old log's last cursor.
+      db.transaction(() =>
+        db.run(`INSERT INTO ${table} (collection, key, field, value, clock, seq)
+          SELECT collection, key, field, value, clock,
+                 (SELECT COALESCE(MAX(seq), 0) FROM ${from}) + ROW_NUMBER() OVER (ORDER BY seq)
+          FROM (SELECT *, ROW_NUMBER() OVER (PARTITION BY collection, key, field ORDER BY clock DESC, seq DESC) AS rank FROM ${from})
+          WHERE rank = 1`),
+      );
+    }
+  }
+
+  return {
+    async append(changes) {
+      return db.transaction(() => {
+        for (const { collection, key, field, value, clock } of changes) {
+          if (keep === 'all') {
+            db.run(`INSERT INTO ${table} (collection, key, field, value, clock) VALUES (?, ?, ?, ?, ?)`, collection, key, field, json(value), clock);
+          } else {
+            // A newer clock takes the row and the next cursor; an older or equal one changes nothing.
+            db.run(
+              `INSERT INTO ${table} (collection, key, field, value, clock, seq) VALUES (?, ?, ?, ?, ?, (SELECT COALESCE(MAX(seq), 0) + 1 FROM ${table}))
+               ON CONFLICT (collection, key, field) DO UPDATE SET value = excluded.value, clock = excluded.clock, seq = excluded.seq
+               WHERE excluded.clock > ${table}.clock`,
+              collection, key, field, json(value), clock,
+            );
+          }
+        }
+        return last();
+      });
+    },
+    async after(cursor, limit = 1000) {
+      const from = Number(cursor) || 0;
+      const rows = db.all(`SELECT seq, collection, key, field, value, clock FROM ${table} WHERE seq > ? ORDER BY seq LIMIT ?`, from, limit);
+      return { changes: read(rows), cursor: rows.length ? Number(rows[rows.length - 1].seq) : from };
+    },
+    /** The cursor after the last change. */
+    head: async () => last(),
+  };
+}

package/src/sqlite.d.ts

@@ -1,4 +1,9 @@
 import type { Log } from './server.js';
 
-/** A sync log in SQLite (`node:sqlite` on Node 22.5+, `bun:sqlite` on Bun). `:memory:` by default. */
-export function sqliteLog(path?: string): Promise<Log & { close(): void }>;
+/**
+ * A sync log in SQLite (`node:sqlite` on Node 22.5+, `bun:sqlite` on Bun). `:memory:` by default.
+ * `keep: 'latest'` keeps each field's latest value only: a newer clock replaces it and takes the
+ * next cursor, an older one is dropped. Switching an existing file over carries each field's
+ * latest value across. By default every change is kept.
+ */
+export function sqliteLog(path?: string, options?: { keep?: 'all' | 'latest' }): Promise<Log & { close(): void }>;

package/src/sqlite.js

@@ -1,46 +1,39 @@
-// A sync log that survives a restart: one SQLite table, through the runtime's own SQLite (Node's
-// `node:sqlite`, Bun's `bun:sqlite`), so there's nothing to install.
+// A sync log that survives a restart: SQLite, through the runtime's own (Node's `node:sqlite`,
+// Bun's `bun:sqlite`), so there's nothing to install.
 //
 //   import { createSyncServer } from '@zubra/sync/server';
 //   import { sqliteLog } from '@zubra/sync/sqlite';
 //   const sync = createSyncServer({ log: await sqliteLog('sync.db') });
 //
-// The cursor is the row id. Rows are only ever appended.
-export async function sqliteLog(path = ':memory:') {
+// `keep: 'latest'` keeps each field's latest value only, so the log doesn't grow with every
+// change and a new device reads what's there now (see sql-log.js). By default it keeps every
+// change, in a table `changes` that the zubra-sync binary reads too.
+import { sqlLog } from './sql-log.js';
+
+export async function sqliteLog(path = ':memory:', { keep = 'all' } = {}) {
   const db = await open(path);
-  db.exec(`CREATE TABLE IF NOT EXISTS changes (
-    seq INTEGER PRIMARY KEY AUTOINCREMENT,
-    collection TEXT NOT NULL,
-    key TEXT NOT NULL,
-    field TEXT NOT NULL,
-    value TEXT,
-    clock TEXT NOT NULL
-  )`);
-  const insert = db.prepare('INSERT INTO changes (collection, key, field, value, clock) VALUES (?, ?, ?, ?, ?)');
-  const select = db.prepare('SELECT seq, collection, key, field, value, clock FROM changes WHERE seq > ? ORDER BY seq LIMIT ?');
-  const last = db.prepare('SELECT COALESCE(MAX(seq), 0) AS seq FROM changes');
-  return {
-    async append(changes) {
-      db.exec('BEGIN');
-      try {
-        for (const { collection, key, field, value, clock } of changes) {
-          insert.run(collection, key, field, JSON.stringify(value ?? null), clock);
+  const statements = new Map();
+  const statement = (sql) => statements.get(sql) ?? statements.set(sql, db.prepare(sql)).get(sql);
+  const log = sqlLog(
+    {
+      exec: (sql) => db.exec(sql),
+      run: (sql, ...args) => statement(sql).run(...args),
+      all: (sql, ...args) => statement(sql).all(...args),
+      transaction(fn) {
+        db.exec('BEGIN');
+        try {
+          const result = fn();
+          db.exec('COMMIT');
+          return result;
+        } catch (error) {
+          db.exec('ROLLBACK');
+          throw error;
         }
-        db.exec('COMMIT');
-      } catch (error) {
-        db.exec('ROLLBACK');
-        throw error;
-      }
-      return Number(last.get().seq);
-    },
-    async after(cursor, limit = 1000) {
-      const rows = select.all(Number(cursor) || 0, limit);
-      const changes = rows.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value: JSON.parse(value), clock }));
-      const cursorNow = rows.length ? Number(rows[rows.length - 1].seq) : Number(cursor) || 0;
-      return { changes, cursor: cursorNow };
+      },
     },
-    close: () => db.close(),
-  };
+    { keep, label: 'sqliteLog' },
+  );
+  return { ...log, close: () => db.close() };
 }
 
 async function open(path) {