better-supabase 0.13.0 → 0.15.0

package/dist/data-engine-BWoz9lED.d.ts

@@ -0,0 +1,273 @@
+import { b as DbError, f as Result, x as DbErrorKind } from "./result-DZeA5KS6.js";
+import { Bt as Executor } from "./types-DFdg_4yN.js";
+//#region src/powersync/connector.d.ts
+/** A queued local change: PowerSync's `CrudEntry`. */
+interface CrudEntryLike {
+  /** `PUT`, `PATCH` or `DELETE` (PowerSync's `UpdateType`). */
+  readonly op: string;
+  readonly table: string;
+  readonly id: string;
+  readonly opData?: Readonly<Record<string, unknown>> | undefined;
+}
+/** The part of a PowerSync database the connector reads the queue from. */
+interface CrudQueueLike {
+  getCrudBatch(limit?: number): Promise<{
+    readonly crud: readonly CrudEntryLike[];
+    complete(): Promise<void>;
+  } | null>;
+}
+/**
+ * A repository a table's changes replay through (`bsb.db.customers`), so RLS,
+ * plugins and validation run as they do online. `I` is the table's insert type
+ * and `K` its primary key; every generated repository fits.
+ */
+interface UploadRepository<I = Record<string, unknown>, K = string> {
+  upsert(data: I): PromiseLike<Result<unknown>>;
+  update(id: K, patch: Partial<I>): PromiseLike<Result<unknown>>;
+  delete(id: K): PromiseLike<Result<unknown>>;
+}
+/**
+ * A repository for a table whose rows are written once (attachments, events): a
+ * `PUT` inserts with `create`, and a `DELETE` calls `delete`.
+ */
+interface CreateUploadRepository<I = Record<string, unknown>, K = string> {
+  create(data: I): PromiseLike<Result<unknown>>;
+  delete(id: K): PromiseLike<Result<unknown>>;
+}
+/** Replays one queued change. */
+type UploadFunction = (entry: CrudEntryLike) => PromiseLike<Result<unknown>>;
+/** A table's route: its repository, or a function for custom replay. */
+type UploadRoute<I = Record<string, unknown>, K = string> = UploadRepository<I, K> | UploadFunction;
+interface UploadRouteOptions<P extends "upsert" | "create"> {
+  /**
+   * What a `PUT` calls. `upsert` (the default) inserts or replaces the row.
+   * `create` inserts it and counts a `conflict` as applied, since the row is
+   * already on the server (an earlier upload of the same change); a `PATCH`
+   * then fails with `unsupported` and is discarded.
+   */
+  readonly put?: P;
+}
+/** What an upload error means for the queued change. */
+type UploadOutcome = "retry" | "conflict" | "discard";
+/** A change the server refused, kept for the UI. */
+interface RejectedChange {
+  readonly entry: CrudEntryLike;
+  readonly error: DbError;
+  readonly outcome: "conflict" | "discard";
+}
+/** A `useSyncExternalStore`-compatible list of refused changes. */
+interface RejectedStore {
+  readonly current: () => readonly RejectedChange[];
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Forgets one change, or all of them. */
+  readonly dismiss: (change?: RejectedChange) => void;
+}
+interface SessionClient {
+  readonly auth: {
+    getSession(): Promise<{
+      readonly data: {
+        readonly session: {
+          readonly access_token: string;
+          readonly expires_at?: number | undefined;
+        } | null;
+      };
+      readonly error?: {
+        readonly name?: string;
+        readonly message: string;
+      } | null;
+    }>;
+  };
+}
+/** Where the connector met an error it reports to `onError`. */
+interface UploadErrorContext {
+  /**
+   * `credentials`: reading the Supabase session failed, so sync and uploads
+   * wait for PowerSync's next try. `upload`: a change failed with an error that
+   * keeps the batch queued for a retry.
+   */
+  readonly phase: "credentials" | "upload";
+}
+interface UploadConnectorOptions {
+  /** The PowerSync service URL. */
+  readonly endpoint: string;
+  /** The supabase-js client whose session authenticates sync and uploads. */
+  readonly supabase: SessionClient;
+  /** Every synced table that takes local writes, by its SQLite name. */
+  readonly tables: Readonly<Record<string, UploadRoute>>;
+  /** Changes per upload batch. Defaults to 100. */
+  readonly batchSize?: number;
+  /** Overrides `uploadOutcome` for some errors. */
+  readonly classify?: (error: DbError, entry: CrudEntryLike) => UploadOutcome | undefined;
+  readonly onConflict?: (change: RejectedChange) => void;
+  readonly onDiscard?: (change: RejectedChange) => void;
+  /**
+   * Called when reading the session fails (kind `unauthorized`, or `network`
+   * when the Auth server is unreachable) and when an upload error keeps the
+   * batch queued. PowerSync retries both on its own; this is for logging. A
+   * signed-out session is not an error.
+   */
+  readonly onError?: (error: DbError, context: UploadErrorContext) => void;
+}
+/** PowerSync's `PowerSyncBackendConnector`. */
+interface UploadConnector {
+  fetchCredentials(): Promise<{
+    readonly endpoint: string;
+    readonly token: string;
+    readonly expiresAt?: Date;
+  } | null>;
+  uploadData(database: CrudQueueLike): Promise<void>;
+  /** Changes the server refused since the app started. */
+  readonly rejected: RejectedStore;
+}
+/**
+ * The default for a failed upload: transient errors retry, a newer server row
+ * is a conflict, and a change the server will never accept is discarded so it
+ * doesn't block the queue.
+ */
+declare function uploadOutcome(kind: DbErrorKind): UploadOutcome;
+/**
+ * Turns a repository into a function route. By default a `PUT` upserts, a
+ * `PATCH` updates and a `DELETE` deletes, as a bare repository in `tables`
+ * does. With `put: "create"`, a `PUT` inserts and a `conflict` counts as
+ * applied, for tables whose rows are written once.
+ *
+ * ```ts
+ * tables: {
+ *   customers: bsb.db.customers,
+ *   attachments: uploadRoute(bsb.db.attachments, { put: "create" }),
+ * }
+ * ```
+ */
+declare function uploadRoute(repository: CreateUploadRepository<never, never>, options: UploadRouteOptions<"create"> & {
+  readonly put: "create";
+}): UploadFunction;
+declare function uploadRoute(repository: UploadRepository<never, never>, options?: UploadRouteOptions<"upsert">): UploadFunction;
+/**
+ * A PowerSync connector that authenticates with the Supabase session and
+ * replays queued changes through repositories. Changes upload in batches; a
+ * transient error keeps the batch queued for PowerSync's retry, and refused
+ * changes land in `rejected` instead of blocking the queue. A table without a
+ * route stops the upload with an error, so no change is dropped silently. When
+ * the session is gone (the refresh token was revoked), the upload stops until
+ * the user signs in again.
+ *
+ * ```ts
+ * const connector = createUploadConnector({
+ *   endpoint: process.env.EXPO_PUBLIC_POWERSYNC_URL,
+ *   supabase,
+ *   tables: { customers: bsb.db.customers },
+ * });
+ * await powersync.connect(connector);
+ * ```
+ */
+declare function createUploadConnector(options: UploadConnectorOptions): UploadConnector;
+//#endregion
+//#region src/bindings/data-engine.d.ts
+/** One cached read: the last data stays while it loads again. */
+interface DataEntry {
+  readonly status: "idle" | "loading" | "success" | "error";
+  readonly data: unknown;
+  readonly error: DbError | undefined;
+}
+/** A cache key: `["bsb", source, verb, ...args]`. */
+type DataKey = readonly unknown[];
+/**
+ * Tells an engine which tables changed outside the hooks' own writes:
+ * `realtimeChanges()` from `better-supabase/realtime` for Supabase Realtime, or
+ * a local database's change events. The engine reads again every followed
+ * source whose name matches a changed table.
+ */
+interface DataChanges {
+  /**
+   * Calls `onChange` with the changed tables (`customers`, `client_notes`).
+   * Returns the function that stops.
+   */
+  subscribe(onChange: (tables: readonly string[]) => void): () => void;
+}
+/** A local database's connection and sync progress. */
+interface DataSyncState {
+  readonly connected: boolean;
+  readonly connecting: boolean;
+  /** The first full sync finished; before it, local reads may be empty. */
+  readonly hasSynced: boolean;
+  readonly uploading: boolean;
+  readonly downloading: boolean;
+  readonly error: Error | undefined;
+}
+/** What `useSyncStatus()` and `useConflicts()` read from an engine. */
+interface DataSync {
+  /** The same object until a field changes. */
+  readonly current: () => DataSyncState;
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Changes the server refused, from `createUploadConnector`. */
+  readonly conflicts?: RejectedStore;
+}
+/** What every engine takes. */
+interface DataEngineOptions extends LiveEngineOptions {
+  /** Reads followed sources again when their tables change elsewhere. */
+  readonly live?: DataChanges;
+}
+/**
+ * Where the data hooks keep their reads. `memoryEngine()` is the default;
+ * `queryEngine(queryClient)` from `better-supabase/query` keeps them in
+ * TanStack Query; `powersyncEngine`, `sqliteEngine` and `tanstackDbEngine` read
+ * a local database. Every engine passes the same contract suite.
+ */
+interface DataEngine {
+  readonly apiVersion: 1;
+  /**
+   * Runs the client's `db` on a local database. `server` is the PostgREST
+   * executor for what the local one can't run. Without it, `db` runs on the
+   * server.
+   */
+  readonly connect?: (server: Executor) => Executor;
+  /** Connection and sync progress, for engines over a synced database. */
+  readonly sync?: DataSync;
+  /**
+   * Follows `key`, loading it with `load` when it has no data yet. `load`
+   * rejects with a `DbException`. Returns the function that stops following.
+   */
+  watch(key: DataKey, load: () => Promise<unknown>, listener: () => void): () => void;
+  /** The entry under `key`, the same object until it changes. */
+  entry(key: DataKey): DataEntry;
+  /** Loads `key` again. */
+  refetch(key: DataKey): void;
+  /**
+   * Rewrites the data of every loaded entry whose key starts with `prefix`.
+   * Returns the function that puts the old data back.
+   */
+  rewrite(prefix: DataKey, update: (data: unknown) => unknown): () => void;
+  /** Marks every entry under `prefix` stale and loads the followed ones again. */
+  invalidate(prefix: DataKey): void;
+}
+/** What `liveEngine` takes besides the changes. */
+interface LiveEngineOptions {
+  /**
+   * The tables each source reads, by source name, when they differ from its
+   * name: `{ tickets: ["tasks"] }`. A source matches a table whose name equals
+   * its own, ignoring case, `_` and `-`.
+   */
+  readonly tables?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * `engine`, reading followed sources again when `changes` reports one of their
+ * tables. It subscribes while a hook follows a read, and stops after the last
+ * one.
+ */
+declare function liveEngine(engine: DataEngine, changes: DataChanges | undefined, options?: LiveEngineOptions): DataEngine;
+/** What an engine over a local database is made of. */
+interface LocalTablesOption {
+  /**
+   * The table keys the local database holds. `db` reads and writes every other
+   * table on the server. Default: every table runs locally.
+   */
+  readonly local?: readonly string[] | undefined;
+}
+/**
+ * The data hooks' default engine: an in-memory cache per client. Reads are
+ * shared by key and dropped once nothing follows them. `live` reads followed
+ * sources again when their tables change elsewhere.
+ */
+declare function memoryEngine(options?: DataEngineOptions): DataEngine;
+//#endregion
+export { UploadRouteOptions as C, uploadRoute as E, UploadRoute as S, uploadOutcome as T, UploadConnectorOptions as _, DataSync as a, UploadOutcome as b, LocalTablesOption as c, CreateUploadRepository as d, CrudEntryLike as f, UploadConnector as g, RejectedStore as h, DataEntry as i, liveEngine as l, RejectedChange as m, DataEngine as n, DataSyncState as o, CrudQueueLike as p, DataEngineOptions as r, LiveEngineOptions as s, DataChanges as t, memoryEngine as u, UploadErrorContext as v, createUploadConnector as w, UploadRepository as x, UploadFunction as y };

package/dist/data-engine-D1BkmBoR.js

@@ -0,0 +1,173 @@
+import { t as DbException } from "./db-exception-Lngc1W49.js";
+import { n as dbError, r as dbErrorOf } from "./errors-BVFgt8BZ.js";
+//#region src/bindings/data-engine.ts
+const IDLE = {
+	status: "idle",
+	data: void 0,
+	error: void 0
+};
+/** A stable string for a key; a `bigint` becomes its digits. */
+function dataKeyHash(key) {
+	return JSON.stringify(key, (_key, value) => typeof value === "bigint" ? `${value.toString()}n` : value);
+}
+function startsWith(key, prefix) {
+	return prefix.every((part, index) => dataKeyHash([part]) === dataKeyHash([key[index]]));
+}
+/** The `DbError` a rejected load carries. */
+function loadError(cause) {
+	return dbErrorOf(cause) ?? dbError("unexpected", cause instanceof Error ? cause.message : String(cause));
+}
+const normalName = (name) => name.replaceAll(/[_-]/g, "").toLowerCase();
+/**
+* `engine`, reading followed sources again when `changes` reports one of their
+* tables. It subscribes while a hook follows a read, and stops after the last
+* one.
+*/
+function liveEngine(engine, changes, options = {}) {
+	if (changes === void 0) return engine;
+	const watched = /* @__PURE__ */ new Map();
+	let stop;
+	const onChange = (tables) => {
+		const changed = new Set(tables.map(normalName));
+		for (const name of watched.keys()) if ((options.tables?.[name] ?? [name]).some((table) => changed.has(normalName(table)))) engine.invalidate(["bsb", name]);
+	};
+	return {
+		...engine,
+		watch: (key, load, listener) => {
+			const unwatch = engine.watch(key, load, listener);
+			const name = key[1];
+			if (typeof name !== "string") return unwatch;
+			watched.set(name, (watched.get(name) ?? 0) + 1);
+			stop ??= changes.subscribe(onChange);
+			let done = false;
+			return () => {
+				if (done) return;
+				done = true;
+				unwatch();
+				const left = (watched.get(name) ?? 1) - 1;
+				if (left === 0) watched.delete(name);
+				else watched.set(name, left);
+				if (watched.size === 0 && stop !== void 0) {
+					const unsubscribe = stop;
+					stop = void 0;
+					unsubscribe();
+				}
+			};
+		}
+	};
+}
+/** Runs the `local` tables on `executor` and the rest on `server`. */
+function routeTables(executor, server, local) {
+	const keys = new Set(local);
+	const onDevice = (op) => keys.has(op.table.key);
+	return {
+		...executor,
+		execute: (op, context) => (onDevice(op) ? executor : server).execute(op, context),
+		batch: async (ops, context) => executor.batch !== void 0 && ops.every(onDevice) ? executor.batch(ops, context) : Promise.all(ops.map((op) => (onDevice(op) ? executor : server).execute(op, context)))
+	};
+}
+/**
+* An engine whose `db` runs on a local database: `cache` keeps the reads, and
+* the database's changes read followed sources again.
+*/
+function localEngine(parts) {
+	const live = liveEngine(parts.cache ?? memoryEngine(), parts.changes, parts.tables === void 0 ? {} : { tables: parts.tables });
+	const { connect, local } = parts;
+	return {
+		...live,
+		connect: local === void 0 ? connect : (server) => routeTables(connect(server), server, local),
+		...parts.sync === void 0 ? {} : { sync: parts.sync }
+	};
+}
+/**
+* The data hooks' default engine: an in-memory cache per client. Reads are
+* shared by key and dropped once nothing follows them. `live` reads followed
+* sources again when their tables change elsewhere.
+*/
+function memoryEngine(options = {}) {
+	const records = /* @__PURE__ */ new Map();
+	const recordOf = (key) => {
+		const hash = dataKeyHash(key);
+		let record = records.get(hash);
+		if (record === void 0) {
+			record = {
+				key,
+				entry: IDLE,
+				load: void 0,
+				run: 0,
+				listeners: /* @__PURE__ */ new Set()
+			};
+			records.set(hash, record);
+		}
+		return record;
+	};
+	const set = (record, entry) => {
+		record.entry = {
+			...record.entry,
+			...entry
+		};
+		for (const listener of [...record.listeners]) listener();
+	};
+	const fetch = (record) => {
+		const load = record.load;
+		if (load === void 0) return;
+		record.run += 1;
+		const run = record.run;
+		set(record, { status: "loading" });
+		load().then((data) => {
+			if (run === record.run) set(record, {
+				status: "success",
+				data,
+				error: void 0
+			});
+		}, (cause) => {
+			if (run === record.run) set(record, {
+				status: "error",
+				error: loadError(cause)
+			});
+		});
+	};
+	return liveEngine({
+		apiVersion: 1,
+		watch: (key, load, listener) => {
+			const record = recordOf(key);
+			record.load = load;
+			record.listeners.add(listener);
+			if (record.entry.status === "idle") fetch(record);
+			return () => {
+				record.listeners.delete(listener);
+				if (record.listeners.size === 0) {
+					record.run += 1;
+					records.delete(dataKeyHash(key));
+				}
+			};
+		},
+		entry: (key) => records.get(dataKeyHash(key))?.entry ?? IDLE,
+		refetch: (key) => {
+			const record = records.get(dataKeyHash(key));
+			if (record !== void 0) fetch(record);
+		},
+		rewrite: (prefix, update) => {
+			const previous = [];
+			for (const record of records.values()) {
+				if (record.entry.data === void 0 || !startsWith(record.key, prefix)) continue;
+				previous.push([record, record.entry.data]);
+				set(record, { data: update(record.entry.data) });
+			}
+			return () => {
+				for (const [record, data] of previous) set(record, { data });
+			};
+		},
+		invalidate: (prefix) => {
+			for (const record of records.values()) if (startsWith(record.key, prefix)) fetch(record);
+		}
+	}, options.live, options);
+}
+/** `result.data`, or a rejection with the `DbException` of `result.error`. */
+async function unwrap(result) {
+	const settled = await result;
+	if (!settled.ok) throw new DbException(settled.error);
+	return settled.data;
+}
+//#endregion
+export { memoryEngine as a, localEngine as i, liveEngine as n, unwrap as o, loadError as r, dataKeyHash as t };