@rebasepro/client 0.10.0 → 0.10.1-canary.a54c057

package/dist/offline-store.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Persistence backends for the SDK's offline support.
+ *
+ * The store is a dumb, namespaced key/value surface with two areas: a read
+ * cache (query results, LRU-evicted) and a mutation queue (writes made while
+ * offline, replayed in order). All scoping — per-user prefixes, sequence
+ * numbers, key layout — is owned by the `OfflineManager`; the store only
+ * promises that `listQueue` returns entries in lexicographic key order, which
+ * is what makes the padded sequence numbers a FIFO.
+ *
+ * Two implementations ship with the SDK:
+ * - {@link IndexedDBOfflineStore} — the browser default; survives reloads.
+ * - {@link MemoryOfflineStore} — the fallback everywhere IndexedDB does not
+ *   exist (Node, React Native, tests); survives only the process.
+ *
+ * Environments with neither (React Native + AsyncStorage, Electron main, …)
+ * implement this interface and pass it via `offline.store`.
+ */
+/** A cached value plus the moment it was written, for LRU eviction. */
+export interface OfflineCacheEntry {
+    value: unknown;
+    cachedAt: number;
+}
+/**
+ * A write made while offline, waiting to be replayed against the server.
+ *
+ * `seq` orders the queue globally (not per collection): a create in one
+ * collection may be the parent a later insert in another references, so
+ * replay must preserve the order the app issued the writes in.
+ */
+export interface PendingMutation {
+    seq: number;
+    collection: string;
+    type: "create" | "createMany" | "update" | "delete";
+    /** Target row id for update/delete, and the (client-generated) id of an offline create. */
+    id?: string | number;
+    /**
+     * True when the SDK minted this create's id itself. Only such creates may
+     * cancel out against a later offline delete: a freshly generated UUID
+     * cannot name a row the server already has, while a caller-supplied id
+     * can — and there the delete must still replay to remove the server row.
+     */
+    generatedId?: boolean;
+    /** The payload: a row for create/update, an array of rows for createMany. */
+    data?: Record<string, unknown> | Record<string, unknown>[];
+    upsert?: boolean;
+    queuedAt: number;
+}
+export interface OfflineStore {
+    getCache(key: string): Promise<OfflineCacheEntry | undefined>;
+    setCache(key: string, entry: OfflineCacheEntry): Promise<void>;
+    deleteCache(keys: string[]): Promise<void>;
+    /** Every cache key starting with `prefix`, with its write time (for eviction). */
+    listCache(prefix: string): Promise<{
+        key: string;
+        cachedAt: number;
+    }[]>;
+    enqueue(key: string, mutation: PendingMutation): Promise<void>;
+    dequeue(key: string): Promise<void>;
+    /** Queued mutations whose key starts with `prefix`, in lexicographic key order. */
+    listQueue(prefix: string): Promise<PendingMutation[]>;
+    /** Remove every cache entry and queued mutation whose key starts with `prefix`. */
+    clear(prefix: string): Promise<void>;
+}
+/**
+ * In-memory store: the default outside the browser and the workhorse of the
+ * test suite. Values are deep-copied on the way in and out so a caller
+ * mutating a returned row cannot silently edit the "persisted" copy — the
+ * IndexedDB implementation gets the same guarantee for free from structured
+ * cloning, and the two must not differ in aliasing behaviour.
+ */
+export declare class MemoryOfflineStore implements OfflineStore {
+    private cache;
+    private queue;
+    getCache(key: string): Promise<OfflineCacheEntry | undefined>;
+    setCache(key: string, entry: OfflineCacheEntry): Promise<void>;
+    deleteCache(keys: string[]): Promise<void>;
+    listCache(prefix: string): Promise<{
+        key: string;
+        cachedAt: number;
+    }[]>;
+    enqueue(key: string, mutation: PendingMutation): Promise<void>;
+    dequeue(key: string): Promise<void>;
+    listQueue(prefix: string): Promise<PendingMutation[]>;
+    clear(prefix: string): Promise<void>;
+}
+/**
+ * IndexedDB-backed store — the browser default, so cached reads and queued
+ * writes survive a reload or a browser restart. Everything lives in one
+ * database with two object stores; keys are the manager's full prefixed
+ * strings, so multiple users (scopes) share the database without ever
+ * sharing entries.
+ */
+export declare class IndexedDBOfflineStore implements OfflineStore {
+    private dbPromise?;
+    private open;
+    private store;
+    getCache(key: string): Promise<OfflineCacheEntry | undefined>;
+    setCache(key: string, entry: OfflineCacheEntry): Promise<void>;
+    deleteCache(keys: string[]): Promise<void>;
+    listCache(prefix: string): Promise<{
+        key: string;
+        cachedAt: number;
+    }[]>;
+    enqueue(key: string, mutation: PendingMutation): Promise<void>;
+    dequeue(key: string): Promise<void>;
+    listQueue(prefix: string): Promise<PendingMutation[]>;
+    clear(prefix: string): Promise<void>;
+}

package/dist/offline.d.ts

@@ -0,0 +1,129 @@
+import { SDKCollectionClient } from "@rebasepro/types";
+import { CollectionClient } from "./collection";
+import { OfflineStore, PendingMutation } from "./offline-store";
+/**
+ * Offline support for the SDK data layer.
+ *
+ * Reads are network-first: a successful `find`/`findById`/`count` refreshes a
+ * local cache, and a network failure falls back to the last cached answer.
+ * Writes made while offline are queued and replayed, in the order the app
+ * issued them, when connectivity returns. Until then every read — cached or
+ * fresh — has the queued writes overlaid, so the app sees its own changes
+ * immediately instead of watching them flicker away on the next fetch.
+ *
+ * What this deliberately is NOT (yet): a local query engine. A cached query
+ * is only ever answered for the exact same parameters, and queued creates are
+ * folded into filtered queries' totals never — we cannot evaluate a `where`
+ * clause client-side, so filtered results only overlay updates and deletes by
+ * row id, which are always safe.
+ */
+export interface OfflineConfig {
+    /**
+     * Persistence backend. Defaults to IndexedDB in the browser and an
+     * in-memory store elsewhere; pass a custom implementation (e.g. backed by
+     * AsyncStorage in React Native) to persist in other environments.
+     */
+    store?: OfflineStore;
+    /**
+     * Cached query results kept per collection; the least recently written
+     * are evicted beyond this. Defaults to 50.
+     */
+    maxCachedQueriesPerCollection?: number;
+    /**
+     * How often to retry replaying the queue while it is non-empty, in
+     * milliseconds. The `online` browser event and a sign-in also trigger a
+     * replay; this timer is the safety net for environments with neither.
+     * Defaults to 30 000.
+     */
+    syncIntervalMs?: number;
+    /**
+     * Called when the server *rejects* a queued mutation during replay (a
+     * 4xx/5xx response — validation, RLS, a since-deleted row). The mutation
+     * is dropped: keeping it would jam the queue behind an error that will
+     * never resolve. Network failures are not errors — the mutation stays
+     * queued for the next attempt.
+     */
+    onSyncError?: (error: Error, mutation: PendingMutation) => void;
+}
+/** What `client.offline` exposes to the app. */
+export interface OfflineApi {
+    /** Replay the queue now. Resolves with what was flushed and what remains. */
+    sync(): Promise<{
+        flushed: number;
+        remaining: number;
+    }>;
+    /** The queued mutations for the current user, oldest first. */
+    pending(): Promise<PendingMutation[]>;
+    /**
+     * Drop the current user's queued mutations AND cached reads. Destructive:
+     * queued writes are lost, not replayed. For "discard my offline changes"
+     * flows, not for sign-out (scoping already isolates users).
+     */
+    clear(): Promise<void>;
+    /** Subscribe to queue-size changes (for a "pending changes" badge). */
+    onQueueChange(listener: (count: number) => void): () => void;
+}
+type AnyRow = Record<string, unknown>;
+type InnerFactory = (slug: string) => SDKCollectionClient<AnyRow>;
+export declare class OfflineManager {
+    private readonly store;
+    private readonly maxCachedQueries;
+    private readonly onSyncError?;
+    private readonly syncIntervalMs;
+    private readonly createInner;
+    private readonly inners;
+    private scope;
+    /** In-memory mirror of the current scope's queue, kept in seq order. */
+    private queue;
+    private loadPromise?;
+    private nextSeq;
+    /** Serializes enqueues so concurrent writes get distinct, ordered seqs. */
+    private enqueueChain;
+    private flushPromise?;
+    private queueListeners;
+    private syncTimer?;
+    private readonly onOnline;
+    readonly api: OfflineApi;
+    constructor(config: OfflineConfig, createInner: InnerFactory);
+    /**
+     * Cache and queue are partitioned per signed-in user: cached rows are
+     * RLS-filtered for the user who fetched them, and queued writes must
+     * replay under the credentials that made them — so neither may ever leak
+     * across a sign-out/sign-in on a shared browser.
+     */
+    setScope(uid: string | undefined): void;
+    /** Release the online listener and retry timer (client.close()). */
+    dispose(): void;
+    wrap<M extends AnyRow>(slug: string, inner: CollectionClient<M>): CollectionClient<M>;
+    private pendingFor;
+    private overlayFind;
+    private overlayCount;
+    /**
+     * Fold the queued ops for one row into a base value. `touched` separates
+     * "the queue says this row does not exist" (a pending delete → undefined)
+     * from "the queue has nothing to say" — the caller falls back differently.
+     */
+    private composeRowFromQueue;
+    private overlayRow;
+    private ensureLoaded;
+    private enqueue;
+    sync(): Promise<{
+        flushed: number;
+        remaining: number;
+    }>;
+    private replay;
+    private drop;
+    /** Replay uses unwrapped clients: a failure must never re-enqueue itself. */
+    private innerFor;
+    private notifyQueue;
+    private startTimer;
+    private stopTimer;
+    private findKey;
+    private countKey;
+    private rowKey;
+    private queueKey;
+    private cacheGet;
+    private cacheSet;
+    private cacheDelete;
+}
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.10.1-canary.a54c057",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,9 +29,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/utils": "0.10.0",
-    "@rebasepro/types": "0.10.0",
-    "@rebasepro/common": "0.10.0"
+    "@rebasepro/common": "0.10.1-canary.a54c057",
+    "@rebasepro/types": "0.10.1-canary.a54c057",
+    "@rebasepro/utils": "0.10.1-canary.a54c057"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -39,6 +39,7 @@
     "@types/node": "^25.9.3",
     "@types/ws": "^8.18.1",
     "cross-env": "^10.1.0",
+    "fake-indexeddb": "^6.2.5",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "tsd": "^0.33.0",

package/src/index.ts

@@ -11,6 +11,7 @@ import { createStorage } from "./storage";
 import { ClientStorageSourceRegistry } from "./storage-registry";
 import { RebaseWebSocketClient } from "./websocket";
 import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel";
+import { OfflineManager, type OfflineApi, type OfflineConfig } from "./offline";
 import {
     DEFAULT_STORAGE_SOURCE_KEY,
     InsertOf,
@@ -88,6 +89,15 @@ export type {
     ChannelHistoryResult
 } from "./realtime-channel";
 
+// Offline: config + the `client.offline` surface, plus the store contract so
+// other environments (React Native/AsyncStorage, Electron, …) can supply
+// their own persistence. `MemoryOfflineStore` is exported for tests and as
+// the reference implementation; the IndexedDB store is wired automatically
+// in the browser and needs no direct construction.
+export type { OfflineApi, OfflineConfig } from "./offline";
+export type { OfflineStore, OfflineCacheEntry, PendingMutation } from "./offline-store";
+export { MemoryOfflineStore } from "./offline-store";
+
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
     admin?: CreateAdminOptions;
@@ -108,6 +118,15 @@ export interface CreateRebaseClientOptions extends RebaseClientConfig {
      * correct slugs via this map before falling back to automatic snake_casing.
      */
     collections?: Record<string, string>;
+    /**
+     * Offline support for the data layer. `true` enables it with defaults
+     * (network-first reads served from cache on network failure, writes
+     * queued and replayed when connectivity returns); pass an
+     * {@link OfflineConfig} to control the store, cache size, or sync error
+     * handling. Cached reads and queued writes are partitioned per signed-in
+     * user. Off by default.
+     */
+    offline?: boolean | OfflineConfig;
 }
 
 // ─── Typed Data Proxy ────────────────────────────────────────────────────────
@@ -186,6 +205,8 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
     collection: <M extends Record<string, unknown> = Record<string, unknown>>(slug: string) => CollectionClient<M>;
     data: TypedDataLayer<DB>;
+    /** Present only when the client was created with `offline` enabled. */
+    offline?: OfflineApi;
 };
 
 // ─── Factory ─────────────────────────────────────────────────────────────────
@@ -398,12 +419,33 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         return undefined;
     }
 
+    // Offline layer: wraps every collection client with a read cache and a
+    // write queue. Replay goes through *unwrapped* clients (the factory below)
+    // so a failing replay can never re-queue itself.
+    const offlineManager = options.offline
+        ? new OfflineManager(
+            typeof options.offline === "object" ? options.offline : {},
+            (slug) => createCollectionClient(transport, slug)
+        )
+        : undefined;
+
+    if (offlineManager) {
+        // Cache and queue are partitioned per user: cached rows are RLS-scoped
+        // to whoever fetched them, and queued writes must replay as the user
+        // who made them — a shared browser must never mix the two.
+        offlineManager.setScope(auth.getSession()?.user?.uid);
+        auth.onAuthStateChange((event, session) => {
+            offlineManager.setScope(event === "SIGNED_OUT" ? undefined : session?.user?.uid);
+        });
+    }
+
     const collectionClients = new Map<string, CollectionClient<Record<string, unknown>>>();
     let untypedWarned = false;
 
     function collection(slug: string): CollectionClient<Record<string, unknown>> {
         if (!collectionClients.has(slug)) {
-            collectionClients.set(slug, createCollectionClient(transport, slug, ws));
+            const inner = createCollectionClient(transport, slug, ws);
+            collectionClients.set(slug, offlineManager ? offlineManager.wrap(slug, inner) : inner);
         }
         return collectionClients.get(slug)!;
     }
@@ -510,6 +552,9 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             // Permanent: nothing queued afterwards may redial and keep the
             // event loop alive, which is the reason this method exists.
             ws?.disconnect(true);
+            // The offline retry timer is unref'd but the `online` listener is
+            // not, and neither should outlive the client.
+            offlineManager?.dispose();
         },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
@@ -526,6 +571,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             return res.data ?? (res as T);
         },
         data: dataProxy,
+        ...(offlineManager ? { offline: offlineManager.api } : {}),
     } as unknown as CreateRebaseClientResult<DB>;
 
     return target;

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

@@ -0,0 +1,151 @@
+import "fake-indexeddb/auto";
+import { IndexedDBOfflineStore, PendingMutation } from "./offline-store";
+import { OfflineManager } from "./offline";
+import { RebaseApiError } from "./transport";
+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(scope: string, seq: number, extra: Partial<PendingMutation> = {}): PendingMutation {
+        return {
+            seq,
+            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(16, "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 seq order even when written out of order", async () => {
+        await store.enqueue(queueKey("t5", 2), mutation("t5", 2));
+        await store.enqueue(queueKey("t5", 10), mutation("t5", 10));
+        await store.enqueue(queueKey("t5", 1), mutation("t5", 1));
+
+        const queue = await store.listQueue("t5|");
+        expect(queue.map((m) => m.seq)).toEqual([1, 2, 10]);
+    });
+
+    it("dequeues a single mutation", async () => {
+        await store.enqueue(queueKey("t6", 1), mutation("t6", 1));
+        await store.enqueue(queueKey("t6", 2), mutation("t6", 2));
+        await store.dequeue(queueKey("t6", 1));
+        expect((await store.listQueue("t6|")).map((m) => m.seq)).toEqual([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("t7a", 1));
+        await store.setCache("t7b|find|posts|", { value: 2, cachedAt: 2 });
+        await store.enqueue(queueKey("t7b", 1), mutation("t7b", 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("t8", 1));
+
+        const reopened = new IndexedDBOfflineStore();
+        expect((await reopened.getCache("t8|find|posts|"))?.value).toBe(42);
+        expect(await reopened.listQueue("t8|")).toHaveLength(1);
+    });
+});
+
+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,134 @@
+import { createRebaseClient, RebaseApiError } 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 };
+    }
+
+    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 different filter is a different cache key, so it must miss.
+        await expect(posts.where("title", "==", "other").find()).rejects.toThrow(TypeError);
+    });
+
+    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);
+    });
+});