better-supabase 0.13.0 → 0.15.0

package/dist/sqlite/index.d.ts

@@ -0,0 +1,126 @@
+import { Bt as Executor } from "../types-DFdg_4yN.js";
+import { c as LocalTablesOption, n as DataEngine, s as LiveEngineOptions } from "../data-engine-BWoz9lED.js";
+import { i as fromSqliteError, n as SqliteDatabaseLike, o as CheckSqliteOptions, r as SqliteExecutorOptions, s as checkSqlite, t as SqliteContextLike } from "../executor-CVIn6JHa.js";
+//#region src/sqlite/engine.d.ts
+/** A SQLite database that may report which tables changed. */
+interface ChangingSqliteDatabase extends SqliteDatabaseLike {
+  onChange?(handler: {
+    onChange: (event: {
+      changedTables: string[];
+    }) => Promise<void> | void;
+  }, options?: {
+    tables?: string[];
+    throttleMs?: number;
+    signal?: AbortSignal;
+  }): () => void;
+}
+interface SqliteEngineOptions extends Omit<SqliteExecutorOptions, "fallback">, LiveEngineOptions, LocalTablesOption {
+  /**
+   * Where reads are kept: `queryEngine(queryClient)` to share them with
+   * TanStack Query. Default one in memory.
+   */
+  readonly cache?: DataEngine;
+  /** The least time between two reads after changes. Default 30 ms. */
+  readonly throttleMs?: number;
+  /**
+   * Reads that SQLite can't run and `db.$rpc` go to the server: the client's
+   * PostgREST executor unless `fallback` names another. `false` keeps every
+   * call local, for a database the app owns alone.
+   */
+  readonly fallback?: Executor | false;
+}
+/**
+ * The data hooks and `db` on a SQLite database the app holds: Expo SQLite
+ * (`expoSqliteDatabase`), Supabase Lite (`liteDatabase`) or any database in the
+ * same shape. Reads return rows in the PostgREST shape and writes run locally.
+ * The database's change events, or else `db`'s own writes, refresh every hook
+ * that follows the table. An insert that leaves out a text or uuid key gets
+ * `crypto.randomUUID()`, else a UUID from SQLite.
+ *
+ * ```ts
+ * export const bsb = createNativeClient(betterSupabase, supabase, {
+ *   engine: sqliteEngine(
+ *     expoSqliteDatabase(sqlite, { addDatabaseChangeListener }),
+ *   ),
+ * });
+ * ```
+ */
+export declare function sqliteEngine(database: ChangingSqliteDatabase, options?: SqliteEngineOptions): DataEngine;
+//#endregion
+//#region src/sqlite/expo.d.ts
+/** What an expo-sqlite database or exclusive transaction can run. */
+interface ExpoSqliteContextLike {
+  getAllAsync<T>(source: string, params: unknown[]): Promise<T[]>;
+  runAsync(source: string, params: unknown[]): Promise<unknown>;
+}
+/**
+ * The part of expo-sqlite's `SQLiteDatabase` the executor uses. Typed by shape,
+ * so better-supabase doesn't depend on expo-sqlite.
+ */
+interface ExpoSqliteDatabaseLike extends ExpoSqliteContextLike {
+  /** Filters change events to this database when several are open. */
+  readonly databasePath?: string;
+  withTransactionAsync(task: () => Promise<void>): Promise<void>;
+  /** Native only: isolates the transaction from other queries on `db`. */
+  withExclusiveTransactionAsync?(task: (txn: ExpoSqliteContextLike) => Promise<void>): Promise<void>;
+}
+/** The fields of an expo-sqlite change event the watcher reads. */
+interface DatabaseChangeEventLike {
+  readonly tableName: string;
+  readonly databaseFilePath?: string;
+}
+/**
+ * Expo-sqlite's `addDatabaseChangeListener`. Open the database with `{
+ * enableChangeListener: true }` so it reports changes.
+ */
+type AddDatabaseChangeListener = (listener: (event: DatabaseChangeEventLike) => void) => {
+  remove(): void;
+};
+interface ExpoSqliteOptions {
+  /**
+   * Reports the database's changes, so the engine reads followed sources again
+   * after writes from elsewhere (a sync job, another screen's `db`).
+   */
+  readonly addDatabaseChangeListener?: AddDatabaseChangeListener;
+}
+/**
+ * An expo-sqlite database in the shape `sqliteEngine` reads. Writes run in
+ * `withExclusiveTransactionAsync` on native and `withTransactionAsync` on web.
+ *
+ * ```ts
+ * const sqlite = await openDatabaseAsync("app.db", {
+ *   enableChangeListener: true,
+ * });
+ * const engine = sqliteEngine(
+ *   expoSqliteDatabase(sqlite, { addDatabaseChangeListener }),
+ * );
+ * ```
+ */
+export declare function expoSqliteDatabase(db: ExpoSqliteDatabaseLike, options?: ExpoSqliteOptions): ChangingSqliteDatabase;
+//#endregion
+//#region src/sqlite/lite.d.ts
+/**
+ * The part of a Supabase Lite SQLite connection (`createConnection` from
+ * `@supabase/lite/sqlite`) the engine uses. Typed by shape, so better-supabase
+ * doesn't depend on Supabase Lite.
+ */
+interface LiteConnectionLike {
+  exec<T = {
+    rows: unknown[];
+  }>(query: string, ...parameters: readonly unknown[]): Promise<T>;
+}
+/**
+ * A Supabase Lite SQLite connection in the shape `sqliteEngine` reads, so an
+ * app that embeds Lite runs its data hooks and `db` on the same file. Write
+ * transactions run one at a time.
+ *
+ * ```ts
+ * const connection = await createConnection({ url: "file:app.db" });
+ * const engine = sqliteEngine(liteDatabase(connection), {
+ *   fallback: false,
+ * });
+ * ```
+ */
+export declare function liteDatabase(connection: LiteConnectionLike): ChangingSqliteDatabase;
+//#endregion
+export { type AddDatabaseChangeListener, type ChangingSqliteDatabase, type CheckSqliteOptions, type DatabaseChangeEventLike, type ExpoSqliteContextLike, type ExpoSqliteDatabaseLike, type ExpoSqliteOptions, type LiteConnectionLike, type SqliteContextLike, type SqliteDatabaseLike, type SqliteEngineOptions, type SqliteExecutorOptions, checkSqlite, fromSqliteError };

package/dist/sqlite/index.js

@@ -0,0 +1,197 @@
+import { i as localEngine } from "../data-engine-D1BkmBoR.js";
+import { i as checkSqlite, r as sqliteExecutor, t as fromSqliteError } from "../executor-BQ7dYw4E.js";
+//#region src/sqlite/engine.ts
+/**
+* A UUID v4 from SQLite's `randomblob`, for runtimes without
+* `crypto.randomUUID`.
+*/
+const UUID_SQL = "select lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)), 2) || '-' || substr('89ab', 1 + (abs(random()) % 4), 1) || substr(hex(randomblob(2)), 2) || '-' || hex(randomblob(6))) as id";
+/** Hermes has no `crypto` unless the app installs a polyfill. */
+function randomId() {
+	const { crypto } = globalThis;
+	return crypto?.randomUUID?.();
+}
+function newIdOn(database) {
+	return async () => {
+		const random = randomId();
+		if (random !== void 0) return random;
+		const [row] = await database.getAll(UUID_SQL);
+		if (!row) throw new TypeError("SQLite returned no id");
+		return row.id;
+	};
+}
+/**
+* The tables `db` writes through the executor, for a database without change
+* events.
+*/
+function writeEvents() {
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		subscribe: (onChange) => {
+			listeners.add(onChange);
+			return () => {
+				listeners.delete(onChange);
+			};
+		},
+		wrap: (executor) => ({
+			...executor,
+			execute: async (op, context) => {
+				const result = await executor.execute(op, context);
+				if (result.ok && op.kind !== "select") for (const listener of listeners) listener([op.table.name]);
+				return result;
+			}
+		})
+	};
+}
+/**
+* The data hooks and `db` on a SQLite database the app holds: Expo SQLite
+* (`expoSqliteDatabase`), Supabase Lite (`liteDatabase`) or any database in the
+* same shape. Reads return rows in the PostgREST shape and writes run locally.
+* The database's change events, or else `db`'s own writes, refresh every hook
+* that follows the table. An insert that leaves out a text or uuid key gets
+* `crypto.randomUUID()`, else a UUID from SQLite.
+*
+* ```ts
+* export const bsb = createNativeClient(betterSupabase, supabase, {
+*   engine: sqliteEngine(
+*     expoSqliteDatabase(sqlite, { addDatabaseChangeListener }),
+*   ),
+* });
+* ```
+*/
+function sqliteEngine(database, options = {}) {
+	const { cache, throttleMs, tables, local, fallback, ...executor } = options;
+	const writes = database.onChange === void 0 ? writeEvents() : void 0;
+	return localEngine({
+		cache,
+		changes: writes ?? { subscribe: (onChange) => database.onChange?.({ onChange: (event) => {
+			onChange(event.changedTables);
+		} }, throttleMs === void 0 ? {} : { throttleMs }) ?? (() => void 0) },
+		...tables === void 0 ? {} : { tables },
+		...local === void 0 ? {} : { local },
+		connect: (server) => {
+			const onDevice = sqliteExecutor(database, {
+				...executor,
+				newId: executor.newId ?? newIdOn(database),
+				...fallback === false ? {} : { fallback: fallback ?? server }
+			});
+			return writes === void 0 ? onDevice : writes.wrap(onDevice);
+		}
+	});
+}
+//#endregion
+//#region src/sqlite/expo.ts
+const DEFAULT_THROTTLE_MS = 30;
+function contextOf(db) {
+	return {
+		getAll: (sql, parameters = []) => db.getAllAsync(sql, parameters),
+		execute: (sql, parameters = []) => db.runAsync(sql, parameters)
+	};
+}
+function changesOf(db, addListener) {
+	return (handler, options = {}) => {
+		const tables = options.tables ? new Set(options.tables) : void 0;
+		const throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+		let pending = /* @__PURE__ */ new Set();
+		let timer;
+		const flush = () => {
+			timer = void 0;
+			const changedTables = [...pending];
+			pending = /* @__PURE__ */ new Set();
+			if (changedTables.length > 0) handler.onChange({ changedTables });
+		};
+		const subscription = addListener((event) => {
+			if (event.databaseFilePath !== void 0 && db.databasePath !== void 0 && event.databaseFilePath !== db.databasePath) return;
+			if (tables && !tables.has(event.tableName)) return;
+			pending.add(event.tableName);
+			timer ??= setTimeout(flush, throttleMs);
+		});
+		const stop = () => {
+			subscription.remove();
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+			pending = /* @__PURE__ */ new Set();
+		};
+		options.signal?.addEventListener("abort", stop, { once: true });
+		return stop;
+	};
+}
+/**
+* An expo-sqlite database in the shape `sqliteEngine` reads. Writes run in
+* `withExclusiveTransactionAsync` on native and `withTransactionAsync` on web.
+*
+* ```ts
+* const sqlite = await openDatabaseAsync("app.db", {
+*   enableChangeListener: true,
+* });
+* const engine = sqliteEngine(
+*   expoSqliteDatabase(sqlite, { addDatabaseChangeListener }),
+* );
+* ```
+*/
+function expoSqliteDatabase(db, options = {}) {
+	const context = contextOf(db);
+	const database = {
+		...context,
+		async writeTransaction(callback) {
+			let box;
+			if (db.withExclusiveTransactionAsync) await db.withExclusiveTransactionAsync(async (txn) => {
+				box = { value: await callback(contextOf(txn)) };
+			});
+			else await db.withTransactionAsync(async () => {
+				box = { value: await callback(context) };
+			});
+			if (!box) throw new TypeError("expo-sqlite skipped the transaction");
+			return box.value;
+		}
+	};
+	const addListener = options.addDatabaseChangeListener;
+	return addListener ? {
+		...database,
+		onChange: changesOf(db, addListener)
+	} : database;
+}
+//#endregion
+//#region src/sqlite/lite.ts
+/**
+* A Supabase Lite SQLite connection in the shape `sqliteEngine` reads, so an
+* app that embeds Lite runs its data hooks and `db` on the same file. Write
+* transactions run one at a time.
+*
+* ```ts
+* const connection = await createConnection({ url: "file:app.db" });
+* const engine = sqliteEngine(liteDatabase(connection), {
+*   fallback: false,
+* });
+* ```
+*/
+function liteDatabase(connection) {
+	const context = {
+		getAll: async (sql, parameters = []) => {
+			return (await connection.exec(sql, ...parameters))?.rows ?? [];
+		},
+		execute: (sql, parameters = []) => connection.exec(sql, ...parameters)
+	};
+	let queue = Promise.resolve();
+	return {
+		...context,
+		writeTransaction: (callback) => {
+			const run = async () => {
+				await connection.exec("begin");
+				try {
+					const value = await callback(context);
+					await connection.exec("commit");
+					return value;
+				} catch (error) {
+					await connection.exec("rollback");
+					throw error;
+				}
+			};
+			const next = queue.then(run, run);
+			queue = next.catch(() => void 0);
+			return next;
+		}
+	};
+}
+//#endregion
+export { checkSqlite, expoSqliteDatabase, fromSqliteError, liteDatabase, sqliteEngine };

package/dist/sso-B0Txid2-.d.ts

@@ -0,0 +1,161 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CRpAHrp_.js";
+import { t as BlockTransport } from "./block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "./block-hooks-DZN2w69m.js";
+//#region src/blocks/sso/sso.d.ts
+/** The DNS record that proves a domain belongs to the organization. */
+interface DomainRecord {
+  readonly type: "TXT";
+  readonly name: string;
+  readonly value: string;
+}
+interface OrganizationDomain {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly domain: string;
+  readonly verifiedAt: Temporal.Instant | undefined;
+  /** New users with a confirmed email at the domain join with this role. */
+  readonly autoJoinRole: string | undefined;
+  /** Sessions of users at the domain need SAML (`sso_access_token_check`). */
+  readonly enforceSso: boolean;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  /** Publish this TXT record, then call `verifyDomain`. */
+  readonly record: DomainRecord;
+}
+interface SsoProvider {
+  /** The Supabase Auth SSO provider id, for `signInWithSSO({ providerId })`. */
+  readonly id: string;
+  readonly organizationId: string;
+  readonly type: "saml";
+  readonly metadataUrl: string | undefined;
+  readonly domains: readonly string[];
+  readonly createdAt: Temporal.Instant;
+}
+/** The provider an email address signs in with. */
+interface SsoDomain {
+  readonly domain: string;
+  readonly organizationId: string;
+  readonly providerId: string;
+  readonly enforceSso: boolean;
+}
+interface SsoOptions extends BlockTemporalOptions {
+  /** The caller's transport (`rpcTransport(supabase)`). */
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * `withBlockHooks` hooks around the client's methods, such as a rule on which
+   * domains an organization may claim.
+   */
+  readonly hooks?: BlockHooks<Sso>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface Sso {
+  /** Claims a domain (needs `sso.manage`); publish its `record`, then verify it. */
+  addDomain(organizationId: string, domain: string): AsyncResult<OrganizationDomain>;
+  domains(organizationId: string): AsyncResult<readonly OrganizationDomain[]>;
+  /** Sets auto-join and SSO enforcement; both need a verified domain. */
+  updateDomain(domainId: string, settings: {
+    readonly autoJoinRole?: string | null;
+    readonly enforceSso?: boolean;
+  }): AsyncResult<OrganizationDomain>;
+  removeDomain(domainId: string): AsyncResult<boolean>;
+  providers(organizationId: string): AsyncResult<readonly SsoProvider[]>;
+  /**
+   * The SSO provider for an email address, for the sign-in page. Works signed
+   * out.
+   */
+  domainFor(email: string): AsyncResult<SsoDomain | undefined>;
+}
+/** Organization domains and SSO lookups as the caller. */
+declare function createSso(options: SsoOptions): Sso;
+/** Looks up the TXT strings at a name; an empty list when it has none. */
+type TxtResolver = (name: string, signal?: AbortSignal) => Promise<readonly string[]>;
+interface DohResolverOptions {
+  /**
+   * A DNS-over-HTTPS JSON endpoint. Default Cloudflare's
+   * `https://cloudflare-dns.com/dns-query`.
+   */
+  readonly endpoint?: string;
+  readonly fetch?: typeof fetch;
+}
+/** TXT lookups over DNS-over-HTTPS (the `application/dns-json` API). */
+declare function dohResolver(options?: DohResolverOptions): TxtResolver;
+interface SsoAuthAdmin {
+  /** The project URL (`SUPABASE_URL`). */
+  readonly url: string;
+  /** A secret or service-role key. Server-only. */
+  readonly secretKey: string;
+  readonly fetch?: typeof fetch;
+}
+interface SsoAdminOptions extends BlockTemporalOptions {
+  /**
+   * A service-role transport: these functions are granted to `service_role`
+   * only.
+   */
+  readonly transport: BlockTransport;
+  /** Supabase Auth's admin API, for SAML providers. */
+  readonly auth?: SsoAuthAdmin;
+  /** TXT lookups for `verifyDomain`. Default `dohResolver()`. */
+  readonly resolver?: TxtResolver;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** Who asked, so the database checks `sso.manage`; omit for app-owned calls. */
+interface SsoActor {
+  readonly actorId?: string;
+}
+type SamlMetadata = {
+  readonly metadataUrl: string;
+  readonly metadataXml?: never;
+} | {
+  readonly metadataXml: string;
+  readonly metadataUrl?: never;
+};
+type SamlProviderInput = SamlMetadata & {
+  /**
+   * Verified domains of the organization whose users sign in with this
+   * provider.
+   */
+  readonly domains: readonly string[];
+  /**
+   * Supabase Auth's `attribute_mapping`, such as `{ keys: { email: { name:
+   * "mail" } } }`.
+   */
+  readonly attributeMapping?: Readonly<Record<string, unknown>>;
+  readonly nameIdFormat?: string;
+};
+interface SsoAdmin {
+  /**
+   * Looks up the domain's TXT record and marks it verified when the token is
+   * there.
+   */
+  verifyDomain(domainId: string, options?: SsoActor & {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<OrganizationDomain>;
+  /**
+   * Creates a SAML provider in Supabase Auth and records it for the
+   * organization.
+   */
+  addSamlProvider(organizationId: string, input: SamlProviderInput, options?: SsoActor): AsyncResult<SsoProvider>;
+  updateSamlProvider(providerId: string, input: Partial<SamlProviderInput> & {
+    readonly domains: readonly string[];
+  }, options?: SsoActor): AsyncResult<SsoProvider>;
+  /**
+   * Deletes the provider from Supabase Auth; `undefined` when the organization
+   * has no such provider.
+   */
+  removeSamlProvider(providerId: string, options?: SsoActor): AsyncResult<SsoProvider | undefined>;
+}
+/** Domain verification and SAML providers with a service-role client. */
+declare function createSsoAdmin(options: SsoAdminOptions): SsoAdmin;
+//#endregion
+export { dohResolver as _, SamlProviderInput as a, SsoAdmin as c, SsoDomain as d, SsoOptions as f, createSsoAdmin as g, createSso as h, SamlMetadata as i, SsoAdminOptions as l, TxtResolver as m, DomainRecord as n, Sso as o, SsoProvider as p, OrganizationDomain as r, SsoActor as s, DohResolverOptions as t, SsoAuthAdmin as u };