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

package/src/collection.ts

@@ -11,6 +11,43 @@ import {
 
 import { SDKQueryBuilder } from "./sdk_query_builder";
 
+/**
+ * A live query result: a normal {@link FindResult} plus what an interface
+ * needs to decide whether to show a "saving…" or "offline" affordance over it.
+ *
+ * The three flags are always `false` on a client without offline support —
+ * every result there came straight from the server.
+ */
+export interface LiveResult<M extends Record<string, unknown>> extends FindResult<M> {
+    /** The data came from the local database, not from a completed request. */
+    fromCache: boolean;
+    /** At least one row here carries a write the server has not accepted yet. */
+    hasPendingWrites: boolean;
+    /**
+     * The local database may not hold every row the server would have
+     * returned, so treat this as a best effort rather than a complete answer.
+     */
+    partial: boolean;
+    /** The most recent revalidation failure, when the last one failed. */
+    error?: Error;
+}
+
+/** Snapshot metadata for a single observed row. */
+export interface RowSnapshotMeta {
+    fromCache: boolean;
+    hasPendingWrites: boolean;
+}
+
+export interface ObserveOptions {
+    /**
+     * Keep the subscription live off the realtime socket, so changes made by
+     * other clients arrive without a refetch. On by default whenever realtime
+     * is enabled on the client; pass `false` for a one-shot read that still
+     * reports offline/pending metadata.
+     */
+    realtime?: boolean;
+}
+
 /**
  * The concrete, HTTP-backed implementation of the public
  * {@link SDKCollectionClient} contract — flat rows (no Entity wrapper), plus
@@ -18,8 +55,8 @@ import { SDKQueryBuilder } from "./sdk_query_builder";
  *
  * This is what `createRebaseClient().data.<collection>` returns. It is not a
  * separate API from {@link SDKCollectionClient}; it only widens it with
- * `count()`. Program against {@link SDKCollectionClient} when you want a
- * transport-agnostic type.
+ * `count()` and the reactive `observe()` pair. Program against
+ * {@link SDKCollectionClient} when you want a transport-agnostic type.
  */
 export interface CollectionClient<
     M extends Record<string, unknown> = Record<string, unknown>,
@@ -27,6 +64,36 @@ export interface CollectionClient<
     U = Partial<M>
 > extends SDKCollectionClient<M, I, U> {
     count(params?: FindParams): Promise<number>;
+
+    /**
+     * Subscribe to a query's results.
+     *
+     * This is the reactive read primitive, and the one to reach for in a UI:
+     * unlike `find()` it keeps emitting. On a client with `offline` enabled it
+     * is local-first — the first emission comes from the local database, with
+     * no request in the way — and re-emits on every local write, every queued
+     * write reaching the server, and every rollback. With realtime enabled it
+     * also re-emits on changes made by other clients.
+     *
+     * Emissions are de-duplicated: a refresh that changes nothing does not
+     * call back.
+     *
+     * @returns An unsubscribe function.
+     */
+    observe(
+        params: FindParams | undefined,
+        onResult: (result: LiveResult<M>) => void,
+        onError?: (error: Error) => void,
+        options?: ObserveOptions
+    ): () => void;
+
+    /** {@link CollectionClient.observe} for a single row. */
+    observeById(
+        id: string | number,
+        onResult: (row: M | undefined, meta: RowSnapshotMeta) => void,
+        onError?: (error: Error) => void,
+        options?: ObserveOptions
+    ): () => void;
 }
 
 export function createCollectionClient<M extends Record<string, unknown> = Record<string, unknown>>(transport: Transport, slug: string, ws?: RebaseWebSocketClient): CollectionClient<M> {
@@ -111,6 +178,55 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             return raw.count ?? 0;
         },
 
+        // Reactive reads. Without the offline layer there is no local database
+        // to read from, so this is a fetch plus — when realtime is available —
+        // the live subscription that keeps it current.
+        observe(
+            params: FindParams | undefined,
+            onResult: (result: LiveResult<M>) => void,
+            onError?: (error: Error) => void,
+            options?: ObserveOptions
+        ) {
+            let closed = false;
+            const emit = (result: FindResult<M>) => {
+                if (closed) return;
+                onResult({ ...result, fromCache: false, hasPendingWrites: false, partial: false });
+            };
+            client.find(params).then(emit).catch((error) => {
+                if (!closed) onError?.(error as Error);
+            });
+            const live = options?.realtime !== false && client.listen
+                ? client.listen(params, emit, onError)
+                : undefined;
+            return () => {
+                closed = true;
+                live?.();
+            };
+        },
+
+        observeById(
+            id: string | number,
+            onResult: (row: M | undefined, meta: RowSnapshotMeta) => void,
+            onError?: (error: Error) => void,
+            options?: ObserveOptions
+        ) {
+            let closed = false;
+            const emit = (row: M | undefined) => {
+                if (closed) return;
+                onResult(row, { fromCache: false, hasPendingWrites: false });
+            };
+            client.findById(id).then(emit).catch((error) => {
+                if (!closed) onError?.(error as Error);
+            });
+            const live = options?.realtime !== false && client.listenById
+                ? client.listenById(id, emit, onError)
+                : undefined;
+            return () => {
+                closed = true;
+                live?.();
+            };
+        },
+
         // Fluent builder instantiation
         where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
             const builder = new SDKQueryBuilder<M>(client);

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,20 @@ export type {
     ChannelHistoryResult
 } from "./realtime-channel";
 
+// Offline: config, the `client.offline` surface, and the metadata a UI needs
+// to reflect sync state. `isOfflineError` distinguishes "there was no network
+// and nothing local to answer with" from a request that genuinely failed.
+// The store contract is public so other environments (React Native/
+// AsyncStorage, Electron, …) can supply their own persistence;
+// `MemoryOfflineStore` is exported for tests and as the reference
+// implementation, while the IndexedDB store is wired automatically in the
+// browser and needs no direct construction.
+export type { OfflineApi, OfflineConfig, OfflineStatus } from "./offline";
+export { isOfflineError } from "./offline";
+export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
+export type { OfflineStore, OfflineCacheEntry, OfflineCacheRecord, PendingMutation, MutationRollback } from "./offline-store";
+export { MemoryOfflineStore } from "./offline-store";
+
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
     admin?: CreateAdminOptions;
@@ -108,6 +123,21 @@ export interface CreateRebaseClientOptions extends RebaseClientConfig {
      * correct slugs via this map before falling back to automatic snake_casing.
      */
     collections?: Record<string, string>;
+    /**
+     * Local-first sync for the data layer.
+     *
+     * `true` enables it with defaults: reads populate a local row database and
+     * fall back to it (evaluating filters and sorts locally) when the network
+     * is gone, writes made offline apply immediately and replay in order when
+     * it returns, and `observe()` becomes a live query that emits from the
+     * local database first. A rejected write is rolled back. Pass an
+     * {@link OfflineConfig} to control the store, cache sizes, retry backoff,
+     * or rejection handling.
+     *
+     * Local rows and queued writes are partitioned per signed-in user, and
+     * shared across tabs. Off by default.
+     */
+    offline?: boolean | OfflineConfig;
 }
 
 // ─── Typed Data Proxy ────────────────────────────────────────────────────────
@@ -186,6 +216,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 +430,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 +563,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 +582,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-codec.ts

@@ -0,0 +1,79 @@
+import { EntityReference, EntityRelation, GeoPoint, Vector } from "@rebasepro/types";
+import { rebaseReviver } from "./reviver";
+
+/**
+ * Lossless round-tripping of rows through the offline store.
+ *
+ * Both persistence backends move values by structured clone, which keeps
+ * `Date` but flattens every class instance to a plain object. For
+ * `EntityReference`/`EntityRelation` that is harmless — they carry their own
+ * `__type` discriminator, so the JSON reviver can rebuild them — but
+ * `GeoPoint` and `Vector` do not, and would come back out of the cache as
+ * anonymous `{ latitude, longitude }` / `{ value }` bags. A row read from the
+ * cache must be indistinguishable from the same row read from the network, so
+ * those two are tagged on the way in and revived on the way out.
+ *
+ * Type tests here are structural rather than `instanceof`, because a structured
+ * clone can arrive from another realm — an iframe, a worker, or the polyfill
+ * the tests run against — where the constructor identity differs but the value
+ * is the real thing. Only *plain* objects are walked; anything else is passed
+ * through whole, so a class instance is never quietly reduced to `{}`.
+ */
+
+function isDate(value: unknown): value is Date {
+    return Object.prototype.toString.call(value) === "[object Date]";
+}
+
+/** An object literal — not a Date, RegExp, Map, or any class instance. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+    const proto = Object.getPrototypeOf(value) as { constructor?: { name?: string } } | null;
+    if (proto === null || proto === Object.prototype) return true;
+    // A literal cloned out of another realm has a different `Object.prototype`
+    // but is still, in every way that matters here, a plain object.
+    return proto.constructor?.name === "Object";
+}
+
+function dehydrateValue(value: unknown): unknown {
+    if (value === null || value === undefined) return value;
+    if (value instanceof GeoPoint) {
+        return { __type: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+    }
+    if (value instanceof Vector) return { __type: "Vector", value: [...value.value] };
+    // EntityReference/EntityRelation already serialize themselves via `__type`
+    // own properties, so a structured clone is enough for the reviver below.
+    if (value instanceof EntityReference || value instanceof EntityRelation) return value;
+    if (Array.isArray(value)) return value.map(dehydrateValue);
+    if (isPlainObject(value)) {
+        const out: Record<string, unknown> = {};
+        for (const [key, inner] of Object.entries(value)) out[key] = dehydrateValue(inner);
+        return out;
+    }
+    return value;
+}
+
+function hydrateValue(value: unknown): unknown {
+    if (value === null || value === undefined || isDate(value)) return value;
+    if (Array.isArray(value)) return value.map(hydrateValue);
+    if (typeof value === "object") {
+        const revived = rebaseReviver("", value);
+        // The reviver recognised it — hand back the class instance untouched
+        // rather than walking into its (now private) internals.
+        if (revived !== value) return revived;
+        if (!isPlainObject(value)) return value;
+        const out: Record<string, unknown> = {};
+        for (const [key, inner] of Object.entries(value)) out[key] = hydrateValue(inner);
+        return out;
+    }
+    return value;
+}
+
+/** Prepare a row for the store. */
+export function dehydrateRow<T extends Record<string, unknown>>(row: T): Record<string, unknown> {
+    return dehydrateValue(row) as Record<string, unknown>;
+}
+
+/** Restore a row read back from the store. */
+export function hydrateRow<T extends Record<string, unknown>>(row: Record<string, unknown>): T {
+    return hydrateValue(row) as T;
+}

package/src/offline-connectivity.test.ts

@@ -0,0 +1,157 @@
+import { ConnectivityMonitor, isNetworkError, isRetryableError } from "./offline-connectivity";
+import { RebaseApiError } from "./transport";
+
+/**
+ * The monitor decides whether a request is worth sending at all, so getting it
+ * wrong is either an app that hangs on every read during an outage, or one that
+ * never notices the network came back.
+ */
+describe("network error classification", () => {
+    it("recognises a request that never reached the server", () => {
+        expect(isNetworkError(new TypeError("Failed to fetch"))).toBe(true);
+        expect(isNetworkError(new TypeError("fetch failed"))).toBe(true);
+        expect(isNetworkError(Object.assign(new Error("aborted"), { name: "AbortError" }))).toBe(true);
+        expect(isNetworkError(Object.assign(new Error("timed out"), { name: "TimeoutError" }))).toBe(true);
+        expect(isNetworkError(new RebaseApiError("no response", { status: 0 }))).toBe(true);
+    });
+
+    it("does not mistake a server's answer for a dead network", () => {
+        expect(isNetworkError(new RebaseApiError("nope", { status: 403 }))).toBe(false);
+        expect(isNetworkError(new RebaseApiError("boom", { status: 500 }))).toBe(false);
+        // A programming error must propagate, not be swallowed as "offline".
+        expect(isNetworkError(new RangeError("bug"))).toBe(false);
+    });
+
+    it("retries what will pass and gives up on what will not", () => {
+        expect(isRetryableError(new TypeError("Failed to fetch"))).toBe(true);
+        expect(isRetryableError(new RebaseApiError("busy", { status: 429 }))).toBe(true);
+        expect(isRetryableError(new RebaseApiError("down", { status: 503 }))).toBe(true);
+        expect(isRetryableError(new RebaseApiError("gateway", { status: 502 }))).toBe(true);
+
+        expect(isRetryableError(new RebaseApiError("invalid", { status: 400 }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("denied", { status: 403 }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("gone", { status: 404 }))).toBe(false);
+        // A 500 is far more often a bug the same payload will hit again than a
+        // blip, and retrying it forever jams every write queued behind it.
+        expect(isRetryableError(new RebaseApiError("boom", { status: 500 }))).toBe(false);
+    });
+});
+
+describe("ConnectivityMonitor", () => {
+    function createMonitor(overrides: Partial<ConstructorParameters<typeof ConnectivityMonitor>[0]> = {}) {
+        let now = 1_000_000;
+        const timers: { fn: () => void; at: number }[] = [];
+        const monitor = new ConnectivityMonitor({
+            initialBackoffMs: 100,
+            maxBackoffMs: 800,
+            now: () => now,
+            setTimer: ((fn: () => void, ms: number) => {
+                timers.push({ fn, at: now + ms });
+                return timers.length as unknown as ReturnType<typeof setTimeout>;
+            }) as never,
+            clearTimer: (() => undefined) as never,
+            ...overrides
+        });
+        const advance = (ms: number) => {
+            now += ms;
+            for (const timer of timers.splice(0)) {
+                if (timer.at <= now) timer.fn();
+                else timers.push(timer);
+            }
+        };
+        return { monitor, advance, at: () => now };
+    }
+
+    it("starts willing to try", () => {
+        const { monitor } = createMonitor();
+        expect(monitor.isOnline()).toBe(true);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+
+    it("stops attempting after a failure, until the backoff window opens", () => {
+        const { monitor, advance } = createMonitor();
+        monitor.markFailure();
+
+        expect(monitor.isOnline()).toBe(false);
+        // This is the whole point: the second read during an outage costs
+        // nothing instead of another timeout.
+        expect(monitor.shouldAttempt()).toBe(false);
+
+        advance(200);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+
+    it("doubles the delay on repeated failures and caps it", () => {
+        const { monitor, advance } = createMonitor();
+        monitor.markFailure();
+        const first = monitor.msUntilRetry();
+        advance(first);
+
+        monitor.markFailure();
+        const second = monitor.msUntilRetry();
+        expect(second).toBeGreaterThan(first);
+
+        for (let i = 0; i < 10; i++) {
+            advance(monitor.msUntilRetry());
+            monitor.markFailure();
+        }
+        // 800 plus the 20% jitter ceiling.
+        expect(monitor.msUntilRetry()).toBeLessThanOrEqual(800 * 1.2);
+    });
+
+    it("resets the backoff once a request gets through", () => {
+        const { monitor, advance } = createMonitor();
+        monitor.markFailure();
+        advance(monitor.msUntilRetry());
+        monitor.markFailure();
+        monitor.markSuccess();
+
+        expect(monitor.isOnline()).toBe(true);
+        expect(monitor.shouldAttempt()).toBe(true);
+        monitor.markFailure();
+        // Back to the initial delay, not to where the doubling had reached.
+        expect(monitor.msUntilRetry()).toBeLessThanOrEqual(100 * 1.2);
+    });
+
+    it("fires the retry hook when the window opens", () => {
+        const { monitor, advance } = createMonitor();
+        let retries = 0;
+        monitor.onRetryDue = () => { retries++; };
+
+        monitor.markFailure();
+        expect(retries).toBe(0);
+        advance(200);
+        expect(retries).toBe(1);
+    });
+
+    it("backs off without claiming the connection is gone", () => {
+        const { monitor } = createMonitor();
+        // A 429 means the server answered — the app is demonstrably online and
+        // an "offline" badge would be a lie.
+        monitor.deferRetry();
+        expect(monitor.isOnline()).toBe(true);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+
+    it("notifies listeners on each transition, and only on transitions", () => {
+        const { monitor } = createMonitor();
+        const seen: boolean[] = [];
+        monitor.onChange((online) => seen.push(online));
+
+        monitor.markFailure();
+        monitor.markFailure();
+        monitor.markSuccess();
+        monitor.markSuccess();
+
+        expect(seen).toEqual([false, true]);
+    });
+
+    it("keeps attempting when backoff suppression is off", () => {
+        // Without a retry timer nothing would ever reopen the window, so
+        // suppressing attempts would strand the client offline forever.
+        const { monitor } = createMonitor({ respectBackoff: false });
+        monitor.markFailure();
+        expect(monitor.isOnline()).toBe(false);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+});