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

package/README.md

@@ -1,6 +1,6 @@
 # @rebasepro/client
 
-HTTP SDK client for the Rebase backend — typed CRUD, auth, storage, realtime WebSockets, admin, cron, and custom functions.
+HTTP SDK client for the Rebase backend — typed CRUD, auth, storage, realtime WebSockets, offline / local-first sync, admin, cron, and custom functions.
 
 ## Installation
 
@@ -17,6 +17,7 @@ pnpm add @rebasepro/client
 - **Admin** — user CRUD for admins
 - **Storage** — file upload, download, delete, list
 - **Realtime** — WebSocket subscriptions for collection and snapshot changes
+- **Offline / local-first sync** (opt-in) — a local row database, writes that apply instantly offline and replay when the connection returns, and live queries
 - **Cron** — list, trigger, and manage cron jobs
 - **Custom functions** — invoke server-side Hono route functions
 - **Type-safe data proxy** — `client.data.products` auto-maps to the `products` collection
@@ -41,6 +42,9 @@ pnpm add @rebasepro/client
 | `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
 | `onUnauthorized` | `() => Promise<boolean>` | auto-refresh | Handler for 401 responses |
 | `websocketUrl` | `string` | derived from `baseUrl` | WebSocket URL for realtime |
+| `realtime` | `boolean` | `true` | Open the WebSocket — `false` lets a one-shot script exit |
+| `collections` | `Record<string, string>` | — | Maps accessor names to collection slugs |
+| `offline` | `boolean \| OfflineConfig` | `false` | Local-first sync — see [the docs](https://rebase.pro/docs/sdk/offline) |
 
 ### Collection Client
 
@@ -61,6 +65,8 @@ pnpm add @rebasepro/client
 | `include(...rels)` | Include related snapshots — returns `QueryBuilder` |
 | `listen(params, onUpdate, onError?)` | Realtime subscription (requires WebSocket) |
 | `listenById(id, onUpdate, onError?)` | Realtime single-snapshot subscription |
+| `observe(params, onResult, onError?, options?)` | Live query — local-first when `offline` is on, otherwise fetch + `listen` |
+| `observeById(id, onResult, onError?, options?)` | Live query for a single row |
 
 ### Auth Module (`client.auth`)
 
@@ -116,6 +122,8 @@ pnpm add @rebasepro/client
 |---|---|
 | `RebaseApiError` | Error class with `status`, `message`, `code`, `details` |
 | `RebaseWebSocketClient` | WebSocket client for realtime subscriptions |
+| `isOfflineError(error)` | True when a read failed with no network *and* nothing cached |
+| `MemoryOfflineStore` | Reference `OfflineStore`; the IndexedDB one is wired automatically |
 | `createCookieStorage(options?)` | Cookie-based auth storage adapter |
 | `createMemoryStorage()` | In-memory auth storage adapter |
 | `QueryBuilder` | Fluent query builder (also re-exported from `@rebasepro/common`) |

package/dist/collection.d.ts

@@ -1,6 +1,40 @@
 import { FindParams, Transport } from "./transport";
 import { RebaseWebSocketClient } from "./websocket";
-import { SDKCollectionClient } from "@rebasepro/types";
+import { FindResult, SDKCollectionClient } from "@rebasepro/types";
+/**
+ * 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
@@ -8,10 +42,28 @@ import { SDKCollectionClient } from "@rebasepro/types";
  *
  * 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>, I = Partial<M>, 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 declare function createCollectionClient<M extends Record<string, unknown> = Record<string, unknown>>(transport: Transport, slug: string, ws?: RebaseWebSocketClient): CollectionClient<M>;

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { CollectionClient } from "./collection";
 import { createFunctionsClient } from "./functions";
 import { RebaseWebSocketClient } from "./websocket";
 import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel";
+import { type OfflineApi, type OfflineConfig } from "./offline";
 import { InsertOf, RebaseClient, RebaseSdkData, RowOf, StorageSource, StorageSourceDefinition, StorageSourceRegistry, UpdateOf } from "@rebasepro/types";
 export { RebaseApiError } from "./transport";
 export { RebaseClientError } from "./errors";
@@ -30,6 +31,11 @@ export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 export { RebaseWebSocketClient } from "./websocket";
 export { RebaseRealtimeChannel } from "./realtime-channel";
 export type { PresenceState, PresenceDiff, BroadcastEvent, ChannelTransport, ChannelOptions, ChannelHistoryEntry, ChannelHistoryResult } from "./realtime-channel";
+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;
@@ -50,6 +56,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;
 }
 type KebabToCamelCase<S extends string> = S extends `${infer T}-${infer U}` ? `${T}${Capitalize<KebabToCamelCase<U>>}` : S;
 type DBEntry<DB, S extends string> = KebabToCamelCase<S> extends keyof DB ? DB[KebabToCamelCase<S>] : unknown;
@@ -110,5 +131,7 @@ 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;
 };
 export declare function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): CreateRebaseClientResult<DB>;