SSSync

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Learning from Electric (TypeScript client)

A study of Electric’s TypeScript client (@electric-sql/client), read from source (electric-sql/electric@main, packages/typescript-client). Same goal as LEARN.md (Replicache/Zero), TINYBASE.md, and POWERSYNC.md: understand what a mature local-first sync system decided its users needed, to inform sssync.

Electric is the smallest and most opinionated-by-omission of the five systems studied. Its entire premise: sync a single Postgres query (a “Shape”) to the client over plain HTTP as a log of row changes. That’s it. There is:

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

PouchDB — public API surface

A rundown of PouchDB’s public API, from the official API reference. Same goal as the other notes in this repo (ROCICORP.md, TINYBASE.md, POWERSYNC.md, ELECTRIC.md, RX.md): understand what a mature local-first database exposes to users, to inform sssync.

PouchDB is the JavaScript implementation of CouchDB’s data model and replication protocol, designed to run in the browser (IndexedDB), Node (LevelDB), or against a remote CouchDB over HTTP. Its defining characteristics: every document is a JSON doc with an _id and a revision _rev; writes are MVCC (multi-version concurrency control — you must supply the current _rev to update, and conflicts are first-class, not errors); and sync is the CouchDB replication protocol — bidirectional, incremental, checkpoint-based, and able to run against any CouchDB-compatible server with no custom backend code. Every method returns a Promise and also accepts a Node-style callback; the streaming methods (changes, replicate, sync) return event emitters.

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Learning from PowerSync (Web SDK)

A study of PowerSync’s public API, read from source (powersync-ja/powersync-js@main). The Web SDK (@powersync/web) is a thin platform shim over @powersync/common, which holds essentially the whole public surface. Same goal as LEARN.md (Replicache/Zero) and TINYBASE.md: understand what a mature local-first sync library decided its users needed, to inform sssync.

PowerSync’s defining bet, and the thing that makes it different from all three prior systems: the local store is a real SQLite database, and the developer talks to it in SQL. There is no KV API (Replicache), no relational query DSL (Zero/ZQL), no reactive-cell tree (TinyBase). You write SELECT ... FROM todos WHERE ..., you get rows, and you watch() the SQL to make it reactive. Sync is server-driven (a PowerSync Service streams “buckets” of rows down; local writes queue up and you upload them yourself). The mental model is closest to Zero’s server-authoritative sync, but the client API is “SQLite that happens to sync.”

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Learning from Replicache & Zero

A study of the public APIs of @rocicorp/replicache and @rocicorp/zero (the rocicorp/mono monorepo), done to understand what a mature sync library decided its users needed. The goal is to inform sssync’s own public surface.

Replicache is the older, lower-level KV-sync engine (a sorted key/value cache with mutators + pull/push). Zero is the newer, higher-level system built on the same persistence/sync machinery but exposing a typed relational query language (ZQL), server-authoritative incremental view maintenance (IVM), and a schema/permissions system. Reading them side-by-side is essentially watching the same team’s opinion evolve from “sync a KV store” to “sync the results of relational queries.”

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Learning from RxDB

A study of RxDB’s public API, read from source (pubkey/rxdb@main, src/ + src/types). Same goal as LEARN.md (Replicache/Zero), TINYBASE.md, POWERSYNC.md, and ELECTRIC.md: understand what a mature local-first database decided its users needed, to inform sssync.

RxDB (“Reactive Database”) is the oldest and most batteries-included of the systems studied — a full client-side NoSQL document database whose defining traits are: everything is an RxJS Observable (queries, documents, even individual fields emit), a MongoDB-style query language (Mango), a pluggable storage engine abstraction underneath, and a generic, transport-agnostic replication protocol on top. Where Electric is “just a change-log” and TinyBase is “just a reactive store,” RxDB is the maximalist: schema + ORM + reactive queries + migrations + attachments + encryption + conflict handling + a dozen replication backends, all assembled from plugins.

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Learning from TinyBase

A study of TinyBase’s public API (essentials guide), read from source (tinyplex/tinybase@main, the published type definitions in src/@types/<module>/index.d.ts). Same goal as LEARN.md (Replicache/Zero): understand what a mature local-first data library decided its users needed, to inform sssync.

TinyBase is a different animal from Replicache/Zero. It is a reactive in-memory data store first, with sync/persistence/CRDT as optional layers bolted on, not the core premise. Where Zero starts from “sync relational queries” and works inward, TinyBase starts from “a tiny reactive store” and works outward. It has no server, no mutators, no optimistic-rollback model in the core — those are someone else’s concern. Its bet is: give people a fast, fully-reactive, schema-optional local store with a rich set of derived data structures (queries, indexes, metrics, relationships, undo), and let sync/persistence plug in underneath via small interfaces.

1.0 Roadmap

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Schema

Mutators

Switch over to using mutators instead of the event/projector separation
Decide on a mutator design
Build type-safe mutator definitions, with a Standard Schema data field
Build cross-tab ordering system
Connect to IDB for persistence
Choose an incrementing Mutation ID format per (client|browser)
Connect mutations rebasing to store

Queries

Finalise design for query DSL
Design system for subscriptions
Make sure updates to queries are batched before revealing to the UI
Add lazy accessor to queries to track just insert/update/delete (like experimental watch() API)
Connect query layer with the coverage tracker

Batcher

Bootstrap

Handle the bootstraps Broadcast Channel updates
Build bootstrap lifecycle manager
Connect bootstrap layer to store
Persist and load BoostrapStatus(es) from IDB
Expose BoostrapStatus as an Observable

Store

Design APIs to write to the store from:
- Mutations
- Syncers
- Batch/bootstrap
Handle the store-updated Broadcast Channel coordinator

Persistence (IDB)

Handle the schema-changed Broadcast Channel coordinator
Build an IndexedDB database management system
Coordinate the startup sequence (check for database, create if needed)
Design API for storing mutation queue
Design API for persisting store data
Provide namespaced KV store

Integrations

Solid.js wrapper with Stores on the reactive layers
React wrapper with stable identity
Figure out how to play well with SSR:
- Surface query interface in a way that allows usage with a Loader function
- Make IDB storage purely pluggable
- Guard BroadcastChannel messages to only run on client

Performance

Make sure store APIs are fast
Add perf tests for store => query connection
Ensure that rebasing is fast

QoL

Add thorough docstrings to all files to drive agents and test creation
Come up with a minimal set of key/id formats for everything
Decide on a single format for passing along row changes
Design error types for library
Switch to using tagged union Result type for typed error handling
Flatten all table row vaildation into one shape (across network + persistence)

Future

Play code golf on largest modules to get things down to <10kb total
Add https://rxdb.info/key-compression.html
Go through https://github.com/rocicorp/replicache/releases and implement all useful features.
Eviction
Partial migrations
Give materializers access to the database
Figure out a syncgroups abstraction (with shared data)
Add IVM for where queries (store.issues.where(q => q.eq("status", "open"))) to the query language, with sorted-btree for indexing.
- gte
- lte
- eq
- in

Dead ends

Events & Projectors

~~Switch to using better-result for typed error handling~~
~~Decide on an event schema format~~
~~Figure out a nice projector API that is easy to use across backend and frontend~~
~~Build type-safe projectors that connect events and schema in a SSSync client~~

An Overview of the System

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

It is opinionated when being so helps enforce robustness, and very flexible otherwise.

Rebasing the offline event queue each time a loader or puller runs
Clearing confirmed events from the offline queue once the backend has confirmed them, rebase the rest
Making sure that puller data is queued and rebased over in-flight loaders

The core SSSync class looks like:

const sss = new SSSync({
  /**
     * A unique identifier for the user.
     *
     * Omit this, or set to `null`, for logged-out clients.
     *
     * Each userID gets its own client-side storage so that the app can switch
     * between users without losing state.
     */
  id: string | null, 
  schema: Tables,
  mutators: Mutators,
  storage: null | IDBStorage,
  /**
     * Distinguishes the storage used by this Zero instance from that of other
     * instances with the same userID. Useful in the case where the app wants to
     * have multiple Zero instances for the same user for different parts of the
     * app.
     */
  storageKey?: 
  mutationURL: "/mutate"
  /**
    * Custom headers to include in mutation requests sent to your API server.
    */
  mutateHeaders?: Record<string, string> | undefined;
  batchURL: "/batch",
  /**
     * Custom headers to include in query requests sent to your API server.
  */  
  batchHeaders?: Record<string, string> | undefined;

  bootstrapURL: "/bootstrap",
  handleErrors: (Error) => void
})

const {data, err} = sss.commit('eventName', eventArgs)
const meta = sss.metadata()
sss.loaders.loaderName(args)

Schemas are declared using Zero’s syntax:

Best Practices

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Ensure you actually want a local-first application

Bad fit for:

Random data access. Like Youtube, or Twitter.
Apps that interact with physical resources like money, or…a railwway crossing gate.
Domains that need to preserve invariants
Content websites. Try using a Service Worker cache instead.
Low session duration, many visitors.

Fractional indexes

Local-only events

Data modelling

Use junction tables and foreign keys instead of nested JSON objects.

Design Notes (June 2026)

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

How i’m thinking about things rn

Event lifecycle

Transactions progress through the following states during their lifecycle:

pending: Initial state when a transaction is created and optimistic mutations can be applied

persisting: Transaction is being persisted to the backend

completed: Transaction has been successfully persisted and any backend changes have been synced back

failed: An error was thrown while persisting or syncing back the transaction

Event compression

Existing → New Result Description insert + update insert Keeps insert type, merges changes, empty original insert + delete removed Mutations cancel each other out update + delete delete Delete dominates update + update update Union changes, keep first original

Design Notes (May 2026)

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

I need to reduce my operators to non-rescan ones

Reducing memory usage in the aggregate will include

Re-running queries against disk as much as possible to have the minimum in-use set.
BUT:
- If mutations can read local state before rebasing, then having everything in memory makes replaying mutations cheap.
- You can sometimes miss next-frame rendering

Possible solution: use Zero’s server tracking method

They track when data is a prefix, complete, etc. So my Zero query client can just pretend like going to disk is like going to the server. This will need testing

Mutators

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Writing data is done through mutators, these are named and versioned descriptions of user intent.

THese mutators are eventually sent to the backend in the form:

{
  name: 'v1_PostCreated'
  data: {
    title: "Mutators"
    description: "An explanation of the event system at the heart of SSSync"
  },
  id: "evt_01J...",
  time: "2026-06-22T10:15:30Z",
}```

- `experimentalPendingMutations()` — inspect not-yet-confirmed local mutations.
- `mutationID`, `reason` (`'initial' | 'rebase' | 'authoritative'`)

Querying data

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

subscribe(body, {onData, onError, isEqual}) onChange

initialValuesInFirstDiff— if true, the first callback synthesizes anadd` diff for all existing matching values, so a watcher can build initial state and then stay live from one code path.
DeepReadonly

Accessing all items in a collection:

// React: returns a tuple
function IssueList() {
  const [issues, pending] = SSS.useAll("issues")
  // issues: Issue[]        — empty [] until ready (or undefined; see note)
  // pending: boolean       — true on initial load, false once authoritative
  if (pending) return <Spinner />

  return (
    <div>
      {issues.map((issue) => (
        <div key={issue.id}>{issue.title}</div>
      ))}
    </div>
  )
}

// Solid: returns an async memo accessor
function IssueList() {
  const issues = SSS.useAll("issues")
  // issues: () => Issue[]   — async memo accessor; reading it suspends until ready
  return (
    <Loading fallback={<Spinner />}>
      <For each={issues()}>
        {(issue) => <div>{issue.title}</div>}
      </For>
    </Loading>
  )
}

Accessing a single item (and relations of an item):

Stats

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

June 29, 2026

Bundle size:

Core library: 12.5 KB raw / 3.5 KB gzip

Syncers

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Syncers are modules that keep the client database up to date. They get:

Direct, read-only access to the client database
Mediated write access in the form of CREATE, UPDATE, and DELETE operations passed to the SSSync client, along with a SyncCursor.

Tables & persistence

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

Schema is declared using Zero schema, which produces validators, etc.

Data is stored in IndexedDB tables, with the schema hash used as the database name. A “databases” table will keep track of upgrade version, schema hashing, etc.

Will need functions for bulk storing rows, reading all data out of the database into Map(), and validating all the time.

SSSync can be configured with either “idb” or “memory” adapters. Tree-shakeable.

{
  name: 'linear_296285d9d399ac9fa0a6ffa3912f109b',
  createdAt: 1782578364787,
  userId: 'a4fcb064-a41e-4082-9b47-9b10b2e66f29',
  schemaHash: 'bb68955e032c43a09a9e83c4f43da32a',
  schemaVersion: 3,
  version: 63
}

The SSSync Server Protocol

judah@example.org (Judah) — Mon, 01 Jan 0001 00:00:00 +0000

You will need to provide two endpoints.

Batch endpoint

The server receives {model: "issue", id: 1, relation?: "comments"} and has to be able to satisfy that request, for all relations that the client schema has. Possible return values are:

200 -> Array of relations object (will count as satisfaction)
400 -> Authorization error (will not be retried)
500 -> Server error (will be retried)

Bootstrap endpoint

/bootstrap?models=issue,project

These 3 things can be composed to achieve: