@rebasepro/client 0.10.0 → 0.10.1-canary.31c773c

package/src/offline-connectivity.ts

@@ -0,0 +1,207 @@
+import { RebaseApiError } from "./transport";
+
+/**
+ * Whether the network is worth trying, and when to try again after it wasn't.
+ *
+ * `navigator.onLine` is necessary but not sufficient: it reports the state of
+ * the network interface, so it stays `true` behind a captive portal, on a
+ * connection that resolves DNS but reaches nothing, and while the API itself
+ * is down. This tracks what actually happened to requests as well, so the
+ * first failure is the only one an app pays for — everything after it inside
+ * the backoff window skips the doomed round trip and answers from the local
+ * store immediately, which is the difference between an app that freezes when
+ * the wifi drops and one that does not.
+ */
+
+/** The request never reached the server, so nothing was decided by it. */
+export function isNetworkError(error: unknown): boolean {
+    if (error instanceof RebaseApiError) {
+        // A 0 status is what a transport reports when it has no response at all.
+        return error.status === 0;
+    }
+    // fetch rejects with TypeError on network failure in every runtime we
+    // support (browsers: "Failed to fetch"/"Load failed"; undici: "fetch
+    // failed").
+    if (error instanceof TypeError) return true;
+    const name = (error as { name?: string } | undefined)?.name;
+    // AbortError covers both an explicit abort and a fetch timeout; the others
+    // are what Node and Safari surface for a dropped connection.
+    return name === "AbortError" || name === "TimeoutError" || name === "NetworkError";
+}
+
+/**
+ * Statuses that mean "not now" rather than "not ever": a queued write that
+ * gets one of these is worth replaying, while a 400 or a 403 never will be.
+ * 500 is deliberately absent — an unhandled server error is far more often a
+ * bug the same payload will hit again than a blip, and retrying it forever
+ * jams every write behind it.
+ */
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
+
+/** Is this failure worth another attempt later? */
+export function isRetryableError(error: unknown): boolean {
+    if (isNetworkError(error)) return true;
+    if (error instanceof RebaseApiError) return error.status !== undefined && RETRYABLE_STATUSES.has(error.status);
+    return false;
+}
+
+export interface ConnectivityOptions {
+    /** First retry delay after a failure. Defaults to 1 000 ms. */
+    initialBackoffMs?: number;
+    /** Ceiling for the doubling retry delay. Defaults to 60 000 ms. */
+    maxBackoffMs?: number;
+    /**
+     * Let a known-failed connection suppress further attempts until the
+     * backoff window opens. On by default — it is what makes a read or write
+     * during an outage instant instead of a timeout. Turn it off when nothing
+     * will ever wake the client up again (no retry timer, no `online` event),
+     * where suppressing attempts would mean never recovering.
+     */
+    respectBackoff?: boolean;
+    /** Injected for tests. */
+    now?: () => number;
+    /** Injected for tests; must return a handle `clearTimeout` accepts. */
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+
+export class ConnectivityMonitor {
+    private state: "online" | "offline" = "online";
+    private backoffMs: number;
+    private readonly initialBackoffMs: number;
+    private readonly maxBackoffMs: number;
+    private retryAt = 0;
+    private timer?: ReturnType<typeof setTimeout>;
+    private listeners = new Set<(online: boolean) => void>();
+    private readonly respectBackoff: boolean;
+    private readonly now: () => number;
+    private readonly setTimer: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    private readonly clearTimer: (handle: ReturnType<typeof setTimeout>) => void;
+    /** Called when the backoff window expires, to drive an automatic retry. */
+    onRetryDue?: () => void;
+
+    private readonly handleOnline = () => {
+        // The OS says the interface is back. Trust it enough to try
+        // immediately rather than sitting out the rest of the backoff — and to
+        // say so, or a client with nothing queued would have no request whose
+        // success could ever flip the badge back to "online".
+        this.retryAt = 0;
+        this.backoffMs = this.initialBackoffMs;
+        this.clearPendingTimer();
+        this.setState("online");
+        this.onRetryDue?.();
+    };
+    private readonly handleOffline = () => {
+        this.setState("offline");
+    };
+
+    constructor(options: ConnectivityOptions = {}) {
+        this.initialBackoffMs = options.initialBackoffMs ?? 1_000;
+        this.maxBackoffMs = Math.max(this.initialBackoffMs, options.maxBackoffMs ?? 60_000);
+        this.backoffMs = this.initialBackoffMs;
+        this.respectBackoff = options.respectBackoff ?? true;
+        this.now = options.now ?? (() => Date.now());
+        this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+
+        if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+            window.addEventListener("online", this.handleOnline);
+            window.addEventListener("offline", this.handleOffline);
+        }
+        if (typeof navigator !== "undefined" && navigator.onLine === false) {
+            this.state = "offline";
+        }
+    }
+
+    /** What the app should be told: are we connected? */
+    isOnline(): boolean {
+        if (typeof navigator !== "undefined" && navigator.onLine === false) return false;
+        return this.state === "online";
+    }
+
+    /**
+     * Should this request even be sent? False means "answer from the local
+     * store instead" — the request would only burn a timeout to reach the same
+     * conclusion the last one already did.
+     */
+    shouldAttempt(): boolean {
+        if (typeof navigator !== "undefined" && navigator.onLine === false) return false;
+        if (this.state === "online" || !this.respectBackoff) return true;
+        // Exactly one request is let through when the window opens; it is the
+        // probe whose outcome decides whether we are back.
+        return this.now() >= this.retryAt;
+    }
+
+    /** A request reached the server. */
+    markSuccess(): void {
+        this.backoffMs = this.initialBackoffMs;
+        this.retryAt = 0;
+        this.clearPendingTimer();
+        this.setState("online");
+    }
+
+    /** A request did not reach the server: we are offline until proven otherwise. */
+    markFailure(): void {
+        this.deferRetry();
+        this.setState("offline");
+    }
+
+    /**
+     * Back off and try again later without claiming the connection is gone.
+     * This is what a 429 or a 503 deserves — the server answered, so the app
+     * is demonstrably online; it just should not hammer.
+     */
+    deferRetry(): void {
+        const jitter = 0.8 + Math.random() * 0.4;
+        this.retryAt = this.now() + this.backoffMs * jitter;
+        const delay = Math.max(0, this.retryAt - this.now());
+        this.backoffMs = Math.min(this.maxBackoffMs, this.backoffMs * 2);
+        this.scheduleRetry(delay);
+    }
+
+    /** Milliseconds until the next attempt is allowed; 0 when one is allowed now. */
+    msUntilRetry(): number {
+        if (this.state === "online") return 0;
+        return Math.max(0, this.retryAt - this.now());
+    }
+
+    onChange(listener: (online: boolean) => void): () => void {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    dispose(): void {
+        if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+            window.removeEventListener("online", this.handleOnline);
+            window.removeEventListener("offline", this.handleOffline);
+        }
+        this.clearPendingTimer();
+        this.listeners.clear();
+        this.onRetryDue = undefined;
+    }
+
+    private scheduleRetry(delay: number): void {
+        this.clearPendingTimer();
+        if (!this.onRetryDue) return;
+        this.timer = this.setTimer(() => {
+            this.timer = undefined;
+            this.onRetryDue?.();
+        }, delay);
+        // A retry timer must never be the reason a Node script refuses to exit.
+        (this.timer as unknown as { unref?: () => void }).unref?.();
+    }
+
+    private clearPendingTimer(): void {
+        if (this.timer !== undefined) {
+            this.clearTimer(this.timer);
+            this.timer = undefined;
+        }
+    }
+
+    private setState(next: "online" | "offline"): void {
+        if (this.state === next) return;
+        this.state = next;
+        const online = this.isOnline();
+        for (const listener of this.listeners) listener(online);
+    }
+}

package/src/offline-idb-store.test.ts

@@ -0,0 +1,286 @@
+import "fake-indexeddb/auto";
+import { IndexedDBOfflineStore, PendingMutation } from "./offline-store";
+import { OfflineManager } from "./offline";
+import { RebaseApiError } from "./transport";
+import { dehydrateRow, hydrateRow } from "./offline-codec";
+import { EntityReference, EntityRelation, GeoPoint, Vector } from "@rebasepro/types";
+import type { CollectionClient } from "./collection";
+
+/**
+ * The IndexedDB store against fake-indexeddb — the same structured-clone
+ * semantics and key ordering as a real browser, without one. All tests share
+ * one fake database (like real tabs share one), so each uses its own key
+ * prefix; the prefix isolation test is exactly what makes that safe.
+ */
+describe("IndexedDBOfflineStore", () => {
+    const store = new IndexedDBOfflineStore();
+
+    function mutation(seq: number, extra: Partial<PendingMutation> = {}): PendingMutation {
+        return {
+            mutationId: String(seq).padStart(10, "0"),
+            collection: "posts",
+            type: "create",
+            id: `id-${seq}`,
+            data: { id: `id-${seq}` },
+            queuedAt: Date.now(),
+            ...extra
+        };
+    }
+
+    function queueKey(scope: string, seq: number): string {
+        return `${scope}|${String(seq).padStart(10, "0")}`;
+    }
+
+    it("round-trips cache entries, including Date values", async () => {
+        const createdAt = new Date("2026-07-01T12:00:00Z");
+        await store.setCache("t1|find|posts|", { value: { data: [{ id: "p1", createdAt }] }, cachedAt: 111 });
+
+        const entry = await store.getCache("t1|find|posts|");
+        expect(entry?.cachedAt).toBe(111);
+        const row = (entry?.value as { data: { id: string; createdAt: Date }[] }).data[0];
+        // Not toBeInstanceOf: fake-indexeddb clones through another realm, so
+        // the constructor identity differs while the value is a real Date.
+        expect(Object.prototype.toString.call(row.createdAt)).toBe("[object Date]");
+        expect(row.createdAt.toISOString()).toBe(createdAt.toISOString());
+    });
+
+    it("returns undefined for a missing cache key", async () => {
+        expect(await store.getCache("t2|nope")).toBeUndefined();
+    });
+
+    it("lists only the keys under a prefix, with their write times", async () => {
+        await store.setCache("t3|find|posts|a", { value: 1, cachedAt: 10 });
+        await store.setCache("t3|find|posts|b", { value: 2, cachedAt: 20 });
+        await store.setCache("t3|find|users|a", { value: 3, cachedAt: 30 });
+
+        const listed = await store.listCache("t3|find|posts|");
+        expect(listed.map((e) => e.key).sort()).toEqual(["t3|find|posts|a", "t3|find|posts|b"]);
+        expect(listed.find((e) => e.key.endsWith("|a"))?.cachedAt).toBe(10);
+    });
+
+    it("deletes several cache keys at once", async () => {
+        await store.setCache("t4|x", { value: 1, cachedAt: 1 });
+        await store.setCache("t4|y", { value: 2, cachedAt: 2 });
+        await store.deleteCache(["t4|x", "t4|y"]);
+        expect(await store.getCache("t4|x")).toBeUndefined();
+        expect(await store.getCache("t4|y")).toBeUndefined();
+    });
+
+    it("returns the queue in mutation-id order even when written out of order", async () => {
+        await store.enqueue(queueKey("t5", 2), mutation(2));
+        await store.enqueue(queueKey("t5", 10), mutation(10));
+        await store.enqueue(queueKey("t5", 1), mutation(1));
+
+        const queue = await store.listQueue("t5|");
+        expect(queue.map((m) => m.id)).toEqual(["id-1", "id-2", "id-10"]);
+    });
+
+    it("dequeues a single mutation", async () => {
+        await store.enqueue(queueKey("t6", 1), mutation(1));
+        await store.enqueue(queueKey("t6", 2), mutation(2));
+        await store.dequeue(queueKey("t6", 1));
+        expect((await store.listQueue("t6|")).map((m) => m.id)).toEqual(["id-2"]);
+    });
+
+    it("clear() removes one prefix's cache and queue and nothing else", async () => {
+        await store.setCache("t7a|find|posts|", { value: 1, cachedAt: 1 });
+        await store.enqueue(queueKey("t7a", 1), mutation(1));
+        await store.setCache("t7b|find|posts|", { value: 2, cachedAt: 2 });
+        await store.enqueue(queueKey("t7b", 1), mutation(1));
+
+        await store.clear("t7a|");
+
+        expect(await store.getCache("t7a|find|posts|")).toBeUndefined();
+        expect(await store.listQueue("t7a|")).toHaveLength(0);
+        expect(await store.getCache("t7b|find|posts|")).toBeDefined();
+        expect(await store.listQueue("t7b|")).toHaveLength(1);
+    });
+
+    it("persists across store instances", async () => {
+        await store.setCache("t8|find|posts|", { value: 42, cachedAt: 1 });
+        await store.enqueue(queueKey("t8", 1), mutation(1));
+
+        const reopened = new IndexedDBOfflineStore();
+        expect((await reopened.getCache("t8|find|posts|"))?.value).toBe(42);
+        expect(await reopened.listQueue("t8|")).toHaveLength(1);
+    });
+
+    it("writes a batch in one transaction and reads the values back by prefix", async () => {
+        await store.setCacheMany([
+            { key: "t9|row|posts|a", entry: { value: { id: "a", n: 1 }, cachedAt: 5 } },
+            { key: "t9|row|posts|b", entry: { value: { id: "b", n: 2 }, cachedAt: 6 } },
+            { key: "t9|row|users|c", entry: { value: { id: "c" }, cachedAt: 7 } }
+        ]);
+
+        const entries = await store.listCacheEntries("t9|row|posts|");
+        expect(entries.map((e) => e.key)).toEqual(["t9|row|posts|a", "t9|row|posts|b"]);
+        expect(entries.map((e) => (e.value as { n: number }).n)).toEqual([1, 2]);
+        expect(entries[1].cachedAt).toBe(6);
+    });
+});
+
+describe("row codec round-trip", () => {
+    /**
+     * Both stores move values by structured clone, which keeps `Date` but
+     * flattens class instances. A row read back from the cache has to be
+     * indistinguishable from the same row read from the network, or an app
+     * that calls `row.point.latitude` works online and throws offline.
+     */
+    it("survives the store as the same shapes it went in as", async () => {
+        const store = new IndexedDBOfflineStore();
+        const row = {
+            id: "r1",
+            at: new Date("2026-07-01T00:00:00Z"),
+            point: new GeoPoint(41.4, 2.2),
+            embedding: new Vector([0.1, 0.2]),
+            author: new EntityReference({ id: "u1", path: "users" }),
+            tag: new EntityRelation("t1", "tags"),
+            nested: { deep: [new GeoPoint(1, 2)] },
+            plain: "text"
+        };
+
+        await store.setCache("codec|row|things|r1", { value: dehydrateRow(row), cachedAt: 1 });
+        const back = hydrateRow((await store.getCache("codec|row|things|r1"))!.value as Record<string, unknown>);
+
+        expect(back.point).toBeInstanceOf(GeoPoint);
+        expect((back.point as GeoPoint).latitude).toBe(41.4);
+        expect(back.embedding).toBeInstanceOf(Vector);
+        expect((back.embedding as Vector).value).toEqual([0.1, 0.2]);
+        expect(back.author).toBeInstanceOf(EntityReference);
+        expect((back.author as EntityReference).pathWithId).toBe("users/u1");
+        expect(back.tag).toBeInstanceOf(EntityRelation);
+        expect(((back.nested as { deep: GeoPoint[] }).deep[0])).toBeInstanceOf(GeoPoint);
+        expect(Object.prototype.toString.call(back.at)).toBe("[object Date]");
+        expect(back.plain).toBe("text");
+    });
+});
+
+describe("two tabs over one database", () => {
+    /** BroadcastChannel delivery is asynchronous; give it a macrotask or two. */
+    const settle = async () => {
+        for (let i = 0; i < 3; i++) await new Promise((resolve) => setTimeout(resolve, 0));
+    };
+
+    function createServer() {
+        const table = new Map<string, Record<string, unknown>>();
+        const state = { online: true };
+        const client = {
+            async find() {
+                if (!state.online) throw new TypeError("fetch failed");
+                const data = [...table.values()];
+                return { data, meta: { total: data.length, limit: 20, offset: 0, hasMore: false } };
+            },
+            async findById(id: string | number) {
+                if (!state.online) throw new TypeError("fetch failed");
+                return table.get(String(id));
+            },
+            async create(data: Record<string, unknown>) {
+                if (!state.online) throw new TypeError("fetch failed");
+                table.set(String(data.id), data);
+                return data;
+            },
+            async createMany() { throw new RebaseApiError("unused", { status: 500 }); },
+            async update() { throw new RebaseApiError("unused", { status: 500 }); },
+            async delete() { throw new RebaseApiError("unused", { status: 500 }); },
+            async count() { return table.size; }
+        } as unknown as CollectionClient<Record<string, unknown>>;
+        return { table, state, client };
+    }
+
+    /**
+     * Web Locks is how two tabs avoid replaying the same queue at the same
+     * time. Node has no implementation, so this is the browser's — a plain
+     * mutex keyed by name, which is all the manager asks of it.
+     */
+    function installWebLocks(): () => void {
+        const held = new Map<string, Promise<unknown>>();
+        const locks = {
+            request: (name: string, fn: () => Promise<unknown>) => {
+                const previous = held.get(name) ?? Promise.resolve();
+                const next = previous.then(fn, fn);
+                held.set(name, next.then(() => undefined, () => undefined));
+                return next;
+            }
+        };
+        Object.defineProperty(globalThis.navigator, "locks", { value: locks, configurable: true });
+        return () => { delete (globalThis.navigator as { locks?: unknown }).locks; };
+    }
+
+    it("shows one tab's offline write in the other, and queues it only once", async () => {
+        const uninstall = installWebLocks();
+        const server = createServer();
+        const tabA = new OfflineManager({ store: new IndexedDBOfflineStore(), syncIntervalMs: 0 }, () => server.client);
+        const tabB = new OfflineManager({ store: new IndexedDBOfflineStore(), syncIntervalMs: 0 }, () => server.client);
+        const postsA = tabA.wrap("xtab", server.client);
+        const postsB = tabB.wrap("xtab", server.client);
+
+        await postsA.find();
+        await postsB.find();
+
+        server.state.online = false;
+        await postsA.create({ title: "from tab A" }, "xt1");
+        await settle();
+
+        // Without cross-tab propagation this tab would be showing a list that
+        // is already wrong, and would keep showing it until a refetch.
+        expect((await postsB.find()).data.map((r) => r.id)).toContain("xt1");
+        expect(await tabB.api.pending()).toHaveLength(1);
+
+        // Both tabs share the queue, so the write must reach the server once —
+        // the lock serialises them, and the loser re-reads a drained queue.
+        server.state.online = true;
+        const [a, b] = await Promise.all([tabA.sync(), tabB.sync()]);
+        expect(a.flushed + b.flushed).toBe(1);
+        expect(server.table.get("xt1")).toMatchObject({ title: "from tab A" });
+
+        tabA.dispose();
+        tabB.dispose();
+        uninstall();
+    });
+});
+
+describe("OfflineManager over IndexedDB", () => {
+    it("queues offline writes in one manager and replays them from a fresh one", async () => {
+        const table = new Map<string, Record<string, unknown>>();
+        const state = { online: true };
+        const fakeClient = {
+            async find() {
+                if (!state.online) throw new TypeError("fetch failed");
+                const data = [...table.values()];
+                return { data, meta: { total: data.length, limit: 20, offset: 0, hasMore: false } };
+            },
+            async findById(id: string | number) {
+                if (!state.online) throw new TypeError("fetch failed");
+                return table.get(String(id));
+            },
+            async create(data: Record<string, unknown>) {
+                if (!state.online) throw new TypeError("fetch failed");
+                table.set(String(data.id), data);
+                return data;
+            },
+            async createMany() { throw new RebaseApiError("unused", { status: 500 }); },
+            async update() { throw new RebaseApiError("unused", { status: 500 }); },
+            async delete() { throw new RebaseApiError("unused", { status: 500 }); },
+            async count() { return table.size; }
+        } as unknown as CollectionClient<Record<string, unknown>>;
+
+        const first = new OfflineManager(
+            { store: new IndexedDBOfflineStore(), syncIntervalMs: 0 },
+            () => fakeClient
+        );
+        state.online = false;
+        const posts = first.wrap("posts", fakeClient);
+        const row = await posts.create({ title: "persisted offline" });
+        expect(await posts.findById(row.id as string)).toMatchObject({ title: "persisted offline" });
+        first.dispose();
+
+        state.online = true;
+        const second = new OfflineManager(
+            { store: new IndexedDBOfflineStore(), syncIntervalMs: 0 },
+            () => fakeClient
+        );
+        expect(await second.sync()).toEqual({ flushed: 1, remaining: 0 });
+        expect(table.get(String(row.id))).toMatchObject({ title: "persisted offline" });
+        second.dispose();
+    });
+});

package/src/offline-integration.test.ts

@@ -0,0 +1,175 @@
+import { createRebaseClient, RebaseApiError, type LiveResult } from "./index";
+import { MemoryOfflineStore } from "./offline-store";
+
+/**
+ * End-to-end wiring test: a real client (real transport, real collection
+ * client, real offline manager) against a fetch stub, proving the `offline`
+ * option actually threads through `createRebaseClient` — the unit suite in
+ * offline.test.ts covers the manager against fakes, not this plumbing.
+ */
+describe("createRebaseClient({ offline })", () => {
+    function jsonResponse(body: unknown): Response {
+        return new Response(JSON.stringify(body), {
+            status: 200,
+            headers: { "Content-Type": "application/json" }
+        });
+    }
+
+    function createHarness(offline: boolean | { store: MemoryOfflineStore; syncIntervalMs: number } =
+        { store: new MemoryOfflineStore(), syncIntervalMs: 0 }) {
+        const network = { online: true, serverError: false };
+        const requests: { method: string; url: string; body?: unknown }[] = [];
+        const fetchStub: typeof fetch = async (input, init) => {
+            const url = String(input);
+            if (!network.online) throw new TypeError("fetch failed");
+            if (network.serverError) {
+                return new Response(JSON.stringify({ error: { message: "boom", code: "internal" } }), {
+                    status: 500,
+                    headers: { "Content-Type": "application/json" }
+                });
+            }
+            requests.push({
+                method: init?.method ?? "GET",
+                url,
+                body: init?.body ? JSON.parse(String(init.body)) : undefined
+            });
+            if (url.includes("/data/posts/count")) return jsonResponse({ count: 1 });
+            if (url.includes("/data/posts") && (init?.method ?? "GET") === "GET") {
+                return jsonResponse({
+                    data: [{ id: "p1", title: "hello" }],
+                    meta: { total: 1, limit: 20, offset: 0, hasMore: false }
+                });
+            }
+            if (url.includes("/data/posts") && init?.method === "POST") {
+                return jsonResponse(JSON.parse(String(init?.body)));
+            }
+            return jsonResponse({});
+        };
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:9999",
+            realtime: false,
+            fetch: fetchStub,
+            offline
+        });
+        return { client, network, requests, fetchStub };
+    }
+
+    it("exposes client.offline only when enabled", () => {
+        const { client } = createHarness();
+        expect(client.offline).toBeDefined();
+
+        const plain = createRebaseClient({
+            baseUrl: "http://localhost:9999",
+            realtime: false
+        });
+        expect(plain.offline).toBeUndefined();
+    });
+
+    it("serves cached reads and queues writes through the data proxy, then syncs", async () => {
+        const { client, network, requests } = createHarness();
+        const posts = client.data.collection("posts");
+
+        const online = await posts.find();
+        expect(online.data).toEqual([{ id: "p1", title: "hello" }]);
+
+        network.online = false;
+        const cached = await posts.find();
+        expect(cached.data).toEqual([{ id: "p1", title: "hello" }]);
+
+        const draft = await posts.create({ title: "offline draft" });
+        expect(draft.title).toBe("offline draft");
+        expect(await client.offline!.pending()).toHaveLength(1);
+
+        // The pending create is visible in the cached, filterless find.
+        const overlaid = await posts.find();
+        expect(overlaid.data.map((r) => r.title)).toEqual(["hello", "offline draft"]);
+        expect(overlaid.meta.total).toBe(2);
+
+        network.online = true;
+        const result = await client.offline!.sync();
+        expect(result).toEqual({ flushed: 1, remaining: 0 });
+
+        const replayed = requests.find((r) => r.method === "POST" && r.url.endsWith("/data/posts"));
+        expect(replayed?.body).toMatchObject({ title: "offline draft", id: draft.id });
+    });
+
+    it("offline: true works in Node via the in-memory fallback store", async () => {
+        const { client, network } = createHarness(true);
+        const posts = client.data.collection("posts");
+
+        await posts.find();
+        network.online = false;
+        expect((await posts.find()).data).toEqual([{ id: "p1", title: "hello" }]);
+
+        await posts.create({ title: "queued" });
+        expect(await client.offline!.pending()).toHaveLength(1);
+    });
+
+    it("routes fluent-builder queries through the cache", async () => {
+        const { client, network, requests } = createHarness();
+        const posts = client.data.collection("posts");
+
+        const online = await posts.where("title", "==", "hello").find();
+        expect(online.data).toHaveLength(1);
+        // The filter must actually reach the wire — otherwise this test would
+        // pass by caching an unfiltered query.
+        expect(requests.some((r) => r.url.includes("title="))).toBe(true);
+
+        network.online = false;
+        const cached = await posts.where("title", "==", "hello").find();
+        expect(cached.data).toEqual(online.data);
+        // A filter the server never answered here is still evaluated locally
+        // against the rows that *are* cached — and this one matches none.
+        expect((await posts.where("title", "==", "other").find()).data).toEqual([]);
+        expect((await posts.where("title", "==", "hello").limit(5).find()).data).toEqual(online.data);
+    });
+
+    it("does not serve cache on a server error — only on network failure", async () => {
+        const { client, network } = createHarness();
+        const posts = client.data.collection("posts");
+        await posts.find();
+
+        network.serverError = true;
+        await expect(posts.find()).rejects.toThrow(RebaseApiError);
+    });
+
+    it("drives a live query through the data proxy, offline included", async () => {
+        const { client, network } = createHarness();
+        const posts = client.data.collection("posts");
+        await posts.find();
+
+        const results: LiveResult<Record<string, unknown>>[] = [];
+        const stop = posts.observe(undefined, (r) => results.push(r));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(results[0].data.map((r) => r.id)).toEqual(["p1"]);
+
+        network.online = false;
+        await posts.create({ title: "written offline" });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        const last = results[results.length - 1];
+        expect(last.data.map((r) => r.title)).toEqual(["hello", "written offline"]);
+        expect(last.hasPendingWrites).toBe(true);
+        expect(client.offline!.status()).toMatchObject({ online: false, pending: 1 });
+        stop();
+    });
+
+    it("observes without offline support too, straight off the network", async () => {
+        const { fetchStub } = createHarness();
+        const plain = createRebaseClient({
+            baseUrl: "http://localhost:9999",
+            realtime: false,
+            fetch: fetchStub
+        });
+
+        const results: LiveResult<Record<string, unknown>>[] = [];
+        const stop = plain.data.collection("posts").observe(undefined, (r) => results.push(r));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        expect(results[0].data.map((r) => r.id)).toEqual(["p1"]);
+        // No local database, so nothing here is ever cached, pending or partial.
+        expect(results[0]).toMatchObject({ fromCache: false, hasPendingWrites: false, partial: false });
+        stop();
+    });
+});