Offline Mode

Opt in, and the SDK keeps a local copy of the data this browser has seen in IndexedDB, answers reads from it when the server cannot be reached, and queues writes made offline to replay in order when the connection is back. It is the data half of working offline; the page cache is the files half, and it is on by default.

const client = await createClient({ offline: { enabled: true } });
// or, with a URL:  createClient(url, { offline: { enabled: true, maxBytes: 50 * 1024 * 1024 } })

// Reads answered from the cache say so
const r = await client.get(["notes", "n1"]);
if (r.fromCache) showStaleHint(r.cachedAt);

// Writes made offline are accepted locally and replay later
const w = await client.set(["notes", "n1"], { text: "written on the train" });
if (w.status === "Queued") showPendingBadge();

client.offline.onSync((e) => {
  if (e.type === "failed") toast("A change could not be saved: " + JSON.stringify(e.op.path));
  if (e.type === "drained") hidePendingBadge();
});

Reads

While the socket is open, get and query go to the server exactly as before, and the reply refreshes the cache on its way back. A promise resolves once, and a stale answer on a realtime database is a bug, so online reads are never served from the cache. When the socket is down — or dies with the request in flight — the SDK answers from the cache if it can, and the reply carries fromCache: true and cachedAt (the time the cached copy was fetched). When it cannot, the reply is { status: "Offline" }, as it always was.

The cache is one tree, in the same shape the engine keeps on disk, plus a coverage set: the paths that were read in full. A path is answerable offline when it, or any ancestor, is covered. What covers a path:

• a get of it (including one that answered "Path not found" — the cache then knows it is absent);
• the first payload or any push of a getSub on it;
• a set or remove of it that the server accepted, or that is queued;
• a query or querySub result covers each matched record, not the collection. So after only a query, a read of one matched record works offline and a read of the whole collection does not.

An update or increment covers its path only when nothing existed there before (then the value is entirely yours). getSubChanged and querySubChanged pushes merge into the tree but cover nothing, because a delta is not a full value.

Queries offline

The server's filter grammar (comparisons, && || !, .includes(), child.field.path) and its ordering rules (type rank, then value, then key; integer-looking keys before others) are implemented in the SDK, so orderBy, desc, limit, startAt and count behave the same offline, over the records the cache holds. An offline query reply carries plan: "cache" and partial: true when the collection itself is not covered, meaning records the browser never fetched cannot be in the result. cursor queries are online-only (a cursor is a position in the server's index) and answer "Offline".

Subscriptions

A subscription made with offline mode on fires once from the cache as soon as it is made, with fromCache: true on the payload, and then exactly as before: the server's first payload when the socket is open, every push after that. The screen has content while a slow socket catches up. The cached payload has the same shape as the server's, including the echoed window fields on querySub. A subscription with nothing cached under it simply waits for the server. Show the flag: a quiet "updating" state keeps values from changing under the user with no explanation.

A queued write also fires the subscriptions on its path and every ancestor, locally, with fromCache: true — the engine's bubble-up, without the engine. Deeper subscriptions are not fired, which is also the engine's rule.

Writes

With the socket open and nothing queued, a write goes straight to the server and the local tree is updated only when the server says "Success". Otherwise — offline, or while a replay is in progress, or when the socket died with the write in flight — the write is applied to the local tree at once, stored in IndexedDB, and resolved { status: "Queued", action, path, opId }. A queued increment carries the locally computed result in data, and the engine's checks (a finite number or an object of them, no more than 256 fields, never against a non-number) run locally so an increment the server would refuse resolves "Failed" right away instead of queueing.

On the next open the queue replays in order, before the subscriptions are restored, so the first server values the app sees already include its own writes. Each op on the wire carries its opId and the browser's clientId; the engine remembers the ops it applied and answers a replay from memory without applying it again. That is what makes a lost reply safe: an increment whose acknowledgement never arrived is sent again and lands exactly once. The durable flag replays with the op; a queued durable write resolves "Queued", never "Success".

What happens to each op at replay:

One cache per browser, wiped on sign-out

The cache is not namespaced by user. It is emptied — tree, coverage and queue — by logout(), by client.offline.clear(), and when the server closes the socket with code 4001, which it does when a session is revoked or expires while connected. login() and createUser() empty the tree and coverage but keep queued writes, which then replay as the new user. A session that expires while the tab is closed sends no 4001, so on a shared device the next person can see cached values until the server replaces them; it is data that was already on that device, and their own writes are judged by the server as them.

API

Storage is one IndexedDB database per origin, nukebase-offline, with stores tree (one record per top-level key, the subtree as it is on the engine's disk), coverage, meta and outbox. A schema change wipes it rather than migrating; nothing in it is the source of truth. The SDK also exports createMemoryStorage(), the adapter the tests use to run offline mode in Node.

Offline mode: troubleshooting