better-supabase 0.7.1 → 0.9.0

package/dist/block-helpers-CfG_MvDR.js

@@ -0,0 +1,264 @@
+import { c as mapDbError, n as dbError, r as dbErrorOf } from "./errors-8i6tSICm.js";
+import { l as provideTemporal } from "./temporal-CB5Fpo5d.js";
+import { t as temporal } from "./temporal-required-DqRzr7i0.js";
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "./result-BlgnMB0H.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { t as fromPgError } from "./pg-error-BV_X8Isq.js";
+import { n as rawError } from "./block-transport-G4t1umrR.js";
+//#region src/core/block-helpers.ts
+/** Provides `options.temporal`, when set, for the block's time values. */
+function applyTemporal(options) {
+	if (options?.temporal !== void 0) provideTemporal(options.temporal);
+}
+/** The block schema when the options name none. */
+const DEFAULT_BLOCK_SCHEMA = "better_supabase";
+/**
+* A thrown error as a `DbError`: a database error goes through the app's
+* mappers first, and a `DbError` a transport already built stays as it is.
+*/
+function toBlockError(cause, mappers = []) {
+	const known = dbErrorOf(cause);
+	if (known) return known;
+	const raw = rawError(cause);
+	return raw ? mapDbError(raw, mappers) : toDbError(cause);
+}
+/** A `BlockCall` over `transport`, in `schema`, with the app's error mappers first. */
+function blockCall(transport, schema = DEFAULT_BLOCK_SCHEMA, mappers = []) {
+	return (fn, args, then) => AsyncResult.from(async () => {
+		let value;
+		try {
+			value = await transport.call(schema, fn, args);
+		} catch (cause) {
+			return err(toBlockError(cause, mappers));
+		}
+		return ok(await then(value));
+	});
+}
+/** A budget of `ms` milliseconds from now, or none for `undefined`. `now` is injectable for tests. */
+function budget(ms, now = Date.now) {
+	const deadline = ms === void 0 ? Number.POSITIVE_INFINITY : now() + ms;
+	return {
+		deadline,
+		expired: () => now() >= deadline,
+		remaining: () => deadline - now()
+	};
+}
+/**
+* Calls `extend` at half the lease (at least every second) until the returned
+* function is called, so work that outlasts its lease keeps it.
+*/
+function leaseHeartbeat(leaseSeconds, extend) {
+	const timer = setInterval(extend, Math.max(1e3, leaseSeconds * 1e3 / 2));
+	return () => {
+		clearInterval(timer);
+	};
+}
+const textOf = (value) => typeof value === "string" ? value : String(value);
+const optionalText = (value) => value === null || value === void 0 ? void 0 : textOf(value);
+/** A function result that must be an object. */
+function recordOf(value, fn) {
+	if (!isRecord(value)) throw new TypeError(`${fn} returned ${JSON.stringify(value)}`);
+	return value;
+}
+/** A function result that must be an array of objects. */
+function recordsOf(value, fn) {
+	if (value === null || value === void 0) return [];
+	if (!Array.isArray(value) || !value.every(isRecord)) throw new TypeError(`${fn} returned ${JSON.stringify(value)}`);
+	return value;
+}
+const stringsOf = (value) => Array.isArray(value) ? value.map(textOf) : [];
+/** `value` when it is one of `values`, otherwise `fallback`. */
+function oneOf(value, values, fallback) {
+	return values.find((item) => item === value) ?? fallback;
+}
+/** `value` when it is one of `values`; throws for anything else. */
+function enumOrThrow(value, values, what) {
+	const found = values.find((item) => item === value);
+	if (found === void 0) throw new TypeError(`unknown ${what} "${String(value)}"`);
+	return found;
+}
+/** A jsonb object column, or an empty object for anything else. */
+const recordOrEmpty = (value) => isRecord(value) ? value : {};
+/** A `credential_ref` column, or `undefined` when it names no provider. */
+function credentialRefOf(value) {
+	if (!isRecord(value) || typeof value["provider"] !== "string") return;
+	return {
+		...value,
+		provider: value["provider"]
+	};
+}
+/** The `not_found` error a block returns for a row the caller can't see. */
+const notFoundError = (message, hint) => dbError("not_found", message, hint === void 0 ? {} : { hint });
+/** A `timestamptz` from jsonb or `pg`, or `undefined` for null. */
+const optionalInstant = (value) => value === null || value === void 0 ? void 0 : value instanceof Date || typeof value === "string" ? toInstant(value) : void 0;
+/** Text from jsonb, or `null` when it is missing or not text. */
+const nullableText = (value) => optionalText(value) ?? null;
+/** A `timestamptz` from jsonb or `pg`, or `null` when it is missing. */
+const nullableInstant = (value) => optionalInstant(value) ?? null;
+/** A `timestamptz` that must be there; throws when it is null or missing. */
+function requiredInstant(value, field) {
+	const instant = optionalInstant(value);
+	if (instant === void 0) throw new TypeError(`${field} is missing`);
+	return instant;
+}
+/** A `timestamptz` from jsonb or `pg`; throws for null or text that isn't one. */
+const instantOf = (value) => value instanceof Date ? toInstant(value) : toInstant(textOf(value));
+const INTEGER = /^-?\d+$/;
+/**
+* An optional `int8` from jsonb or `pg`, or `undefined` for null. Block
+* functions send `int8` as text because a JSON number loses precision past
+* 2^53, so a number here is refused instead of read rounded.
+*/
+function optionalBigintOf(value, field) {
+	if (value === null || value === void 0) return;
+	if (typeof value === "bigint") return value;
+	if (typeof value === "string" && INTEGER.test(value)) return BigInt(value);
+	throw new TypeError(`${field} must be an integer sent as text, got ${typeof value === "string" ? JSON.stringify(value) : typeof value}`);
+}
+/** An `int8` that must be there; see `optionalBigintOf`. */
+function bigintOf(value, field) {
+	const found = optionalBigintOf(value, field);
+	if (found === void 0) throw new TypeError(`${field} is missing`);
+	return found;
+}
+/** An optional `timestamptz` as text for a function argument. */
+const instantArg = (value) => value === void 0 ? void 0 : value === null ? null : value.toString();
+/** SHA-256 of `value` as lowercase hex, with WebCrypto. */
+async function sha256Hex(value) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** `bytes` random bytes as base64url, for secrets and codes. */
+function randomToken(bytes = 24) {
+	const data = crypto.getRandomValues(new Uint8Array(bytes));
+	let binary = "";
+	for (const byte of data) binary += String.fromCodePoint(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function asDbError(cause) {
+	const raw = fromPgError(cause);
+	return raw ? mapDbError(raw) : toDbError(cause);
+}
+function run(fn) {
+	return AsyncResult.from(async () => {
+		try {
+			return ok(await fn());
+		} catch (cause) {
+			return err(asDbError(cause));
+		}
+	});
+}
+/**
+* The request body as text, or `undefined` once it is longer than `limit`
+* bytes. A larger `Content-Length` is refused before reading; otherwise
+* reading stops at the limit, so a body without one can't fill memory.
+*/
+async function readBodyCapped(request, limit) {
+	const length = Number(request.headers.get("content-length") ?? NaN);
+	if (Number.isFinite(length) && length > limit) return;
+	if (!request.body) return "";
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.byteLength;
+		if (size > limit) {
+			reader.cancel().catch(() => void 0);
+			return;
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+}
+function seconds(value) {
+	return typeof value === "number" ? `${String(value)} seconds` : value;
+}
+function workerId() {
+	return `worker-${crypto.randomUUID().slice(0, 8)}`;
+}
+/**
+* Runs `fn` over `items` with at most `limit` calls in flight. After the
+* first rejection no new item starts; the ones running finish, then it
+* rethrows.
+*/
+async function eachLimit(items, limit, fn) {
+	let next = 0;
+	let failure;
+	const lane = async () => {
+		while (failure === void 0 && next < items.length) {
+			const index = next++;
+			try {
+				await fn(items[index], index);
+			} catch (cause) {
+				failure ??= { cause };
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, lane));
+	if (failure) throw failure.cause;
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+	if (signal?.aborted) {
+		resolve();
+		return;
+	}
+	const timer = setTimeout(done, ms);
+	function done() {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", done);
+		resolve();
+	}
+	signal?.addEventListener("abort", done, { once: true });
+});
+/** pgmq and the inbox return `timestamptz` as text over RPC and as `Date` from `pg`. */
+const toInstant = (value) => value instanceof Date ? temporal().Instant.fromEpochMilliseconds(value.getTime()) : temporal().Instant.from(value);
+function errorText(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
+	return String(error);
+}
+function injectableOf(what, value) {
+	if (value === void 0) return;
+	const version = value.apiVersion;
+	if (version !== void 0 && version !== 1) throw new TypeError(`${what} targets API ${String(version)}; this better-supabase supports 1. Upgrade better-supabase or use a release built for API 1.`);
+	return value;
+}
+/** Reads `limit` and `cursor` from a list's options. */
+function pageOf(options = {}) {
+	return {
+		limit: options.limit,
+		cursor: options.cursor
+	};
+}
+/**
+* The per-event results of a batched block function (`audit_event_many`,
+* `publish_webhook_events`, `send_notifications`), in the order of the
+* events: `{ [key]: value }` becomes `ok(then(value))` and `{ error }` a
+* `DbError` through the app's mappers. An event the reply leaves out is
+* `unexpected`.
+*/
+function batchResultsOf(value, count, key, then, mappers = []) {
+	const rows = Array.isArray(value) ? value : [];
+	return Array.from({ length: count }, (_, index) => {
+		const row = rows[index];
+		if (isRecord(row) && isRecord(row["error"])) return err(toBlockError(row["error"], mappers));
+		if (isRecord(row) && key in row) return ok(then(row[key]));
+		return err(dbError("unexpected", `The batch reply has no result for event ${index}`));
+	});
+}
+/** `items` in consecutive chunks of at most `size`. */
+function chunksOf(items, size) {
+	const chunks = [];
+	for (let start = 0; start < items.length; start += size) chunks.push(items.slice(start, start + size));
+	return chunks;
+}
+//#endregion
+export { requiredInstant as A, optionalText as C, recordOf as D, readBodyCapped as E, stringsOf as F, textOf as I, toBlockError as L, seconds as M, sha256Hex as N, recordOrEmpty as O, sleep as P, toInstant as R, optionalInstant as S, randomToken as T, notFoundError as _, bigintOf as a, oneOf as b, chunksOf as c, enumOrThrow as d, errorText as f, leaseHeartbeat as g, instantOf as h, batchResultsOf as i, run as j, recordsOf as k, credentialRefOf as l, instantArg as m, applyTemporal as n, blockCall as o, injectableOf as p, asDbError as r, budget as s, DEFAULT_BLOCK_SCHEMA as t, eachLimit as u, nullableInstant as v, pageOf as w, optionalBigintOf as x, nullableText as y, workerId as z };

package/dist/block-hooks-BLPWD3Jt.d.ts

@@ -0,0 +1,107 @@
+import { b as DbError, f as Result, t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { t as BlockCall } from "./block-helpers-C86hPEjI.js";
+//#region src/core/block-hooks.d.ts
+/** A block method: anything that returns an `AsyncResult`. */
+type BlockMethod = (...args: never[]) => AsyncResult<unknown>;
+/** The names of a block client's methods that return an `AsyncResult`. */
+type BlockMethodName<C> = { [K in keyof C]: C[K] extends BlockMethod ? K : never; }[keyof C] & string;
+type ArgsOf<F> = F extends ((...args: infer A) => AsyncResult<unknown>) ? A : never;
+type DataOf<F> = F extends ((...args: never[]) => AsyncResult<infer T>) ? T : never;
+/** Which call a hook runs for. */
+interface BlockHookInfo {
+  /** The block, as `createBlocks` names it, or the name `withBlockHooks` got. */
+  readonly block: string;
+  readonly method: string;
+}
+/**
+ * Hooks for one block method. `before` runs first: return nothing to keep
+ * the arguments, a new argument list to replace them, or a `DbError` to
+ * refuse the call, which then returns that error without reaching the
+ * database. `after` observes a copy of the result and can't change it; when
+ * it throws, the logger gets the error and the caller still gets the result.
+ */
+interface BlockMethodHooks<A extends readonly unknown[], T> {
+  readonly before?: (args: A, info: BlockHookInfo) => Readonly<A> | DbError | void | Promise<Readonly<A> | DbError | void>;
+  readonly after?: (result: Result<T>, args: A, info: BlockHookInfo) => void | Promise<void>;
+}
+/** Hooks keyed by the block client's method names. */
+type BlockHooks<C> = { readonly [K in BlockMethodName<C>]?: BlockMethodHooks<ArgsOf<C[K]>, DataOf<C[K]>>; };
+interface WithBlockHooksOptions {
+  /** The block's name in `BlockHookInfo` and log messages. Default `block`. */
+  readonly block?: string;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/**
+ * Runs `hooks` around a block client's methods. Use it to add a rule the
+ * block doesn't know (refuse `invite` above a seat limit), rewrite arguments
+ * (fill a default), or observe results (metrics, an audit line). Methods
+ * without hooks are unchanged.
+ *
+ * ```ts
+ * const orgs = withBlockHooks(createOrganizations(options), {
+ *   invite: { before: ([input]) => (input.role === "owner" ? dbError("forbidden", "Owners are added by support") : undefined) },
+ * });
+ * ```
+ */
+declare function withBlockHooks<C extends object>(client: C, hooks: BlockHooks<C> | undefined, options?: WithBlockHooksOptions): C;
+/** What `extendBlock` hands the builder besides the base client. */
+interface ExtendBlockTools {
+  /**
+   * Calls a SQL function in the block's schema over its transport and maps a
+   * rejection to a `DbError`, as the block's own methods do. Needs the
+   * `transport` option.
+   */
+  readonly call: BlockCall;
+}
+interface ExtendBlockOptions {
+  /** The transport `call` uses: the one the block was created with. */
+  readonly transport?: BlockTransport;
+  /** The schema `call` targets. Default `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers `call` runs before the built-in ones. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * Adds methods to a block client. The builder gets the base client, so a
+ * new method can compose existing ones, and `call` for SQL functions the
+ * app adds to the block's schema. Redefining a base method throws: wrap it
+ * with `withBlockHooks` instead.
+ *
+ * ```ts
+ * const orgs = extendBlock(createOrganizations(options), (base, { call }) => ({
+ *   archive: (id: string) => call("archive_organization", { id }, () => undefined),
+ * }), { transport: options.transport });
+ * ```
+ */
+declare function extendBlock<C extends object, X extends object>(client: C, build: (base: C, tools: ExtendBlockTools) => X, options?: ExtendBlockOptions): C & X;
+/** One transport call, as middleware sees it. */
+interface BlockTransportRequest {
+  readonly schema: string;
+  readonly fn: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+/**
+ * Runs around every call a transport makes: tracing, a statement timeout,
+ * an extra argument every function takes. Pass a changed request to `next`
+ * to rewrite it. Reject with the error `next` rejected with so the block
+ * still maps it to a `DbError`.
+ */
+interface BlockTransportMiddleware {
+  readonly apiVersion: 1;
+  readonly name: string;
+  call(request: BlockTransportRequest, next: (request: BlockTransportRequest) => Promise<unknown>): Promise<unknown>;
+}
+/** Fills in `apiVersion: 1`. */
+declare function defineTransportMiddleware(middleware: Omit<BlockTransportMiddleware, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): BlockTransportMiddleware;
+/**
+ * A transport that runs `middleware` around `transport`, the first one
+ * outermost. Throws when a middleware targets an API other than 1.
+ */
+declare function wrapTransport(transport: BlockTransport, ...middleware: readonly BlockTransportMiddleware[]): BlockTransport;
+//#endregion
+export { BlockTransportMiddleware as a, ExtendBlockTools as c, extendBlock as d, withBlockHooks as f, BlockMethodName as i, WithBlockHooksOptions as l, BlockHooks as n, BlockTransportRequest as o, wrapTransport as p, BlockMethodHooks as r, ExtendBlockOptions as s, BlockHookInfo as t, defineTransportMiddleware as u };

package/dist/block-hooks-BsXncUlZ.js

@@ -0,0 +1,114 @@
+import { n as dbError, o as isDbError } from "./errors-8i6tSICm.js";
+import { r as err, t as AsyncResult } from "./result-BlgnMB0H.js";
+import { t as consoleLogger } from "./logger-glM28NVN.js";
+import { o as blockCall } from "./block-helpers-CfG_MvDR.js";
+//#region src/core/block-hooks.ts
+const isPlainObject = (value) => {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+/** A copy of plain objects and arrays; class instances (Temporal values) are immutable and stay shared. */
+function copyOf(value) {
+	if (Array.isArray(value)) return value.map(copyOf);
+	if (typeof value === "object" && value !== null && isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, copyOf(entry)]));
+	return value;
+}
+/** A new client with the same methods: a spread for object literals, a child object otherwise. */
+function cloneClient(client) {
+	if (isPlainObject(client)) return { ...client };
+	return Object.create(client);
+}
+/** The client's method named `name`, or undefined when it has none. */
+function methodOf(client, name) {
+	const value = client[name];
+	if (typeof value !== "function") return;
+	return value;
+}
+/**
+* Runs `hooks` around a block client's methods. Use it to add a rule the
+* block doesn't know (refuse `invite` above a seat limit), rewrite arguments
+* (fill a default), or observe results (metrics, an audit line). Methods
+* without hooks are unchanged.
+*
+* ```ts
+* const orgs = withBlockHooks(createOrganizations(options), {
+*   invite: { before: ([input]) => (input.role === "owner" ? dbError("forbidden", "Owners are added by support") : undefined) },
+* });
+* ```
+*/
+function withBlockHooks(client, hooks, options = {}) {
+	if (hooks === void 0) return client;
+	const block = options.block ?? "block";
+	const logger = options.logger ?? consoleLogger;
+	const wrapped = cloneClient(client);
+	for (const [method, hook] of Object.entries(hooks)) {
+		if (hook === void 0) continue;
+		const original = methodOf(client, method);
+		if (original === void 0) throw new TypeError(`better-supabase: ${block} has no method "${method}" to hook`);
+		const { before, after } = hook;
+		const info = {
+			block,
+			method
+		};
+		wrapped[method] = (...args) => AsyncResult.from(async () => {
+			let current = args;
+			if (before) {
+				const outcome = await before(current, info);
+				if (isDbError(outcome)) return err(outcome);
+				if (Array.isArray(outcome)) current = outcome;
+			}
+			const result = await original.apply(client, current);
+			if (after) try {
+				await after(copyOf(result), current, info);
+			} catch (cause) {
+				logger.error(`${block}.${method} after hook threw`, { cause });
+			}
+			return result;
+		});
+	}
+	return wrapped;
+}
+/**
+* Adds methods to a block client. The builder gets the base client, so a
+* new method can compose existing ones, and `call` for SQL functions the
+* app adds to the block's schema. Redefining a base method throws: wrap it
+* with `withBlockHooks` instead.
+*
+* ```ts
+* const orgs = extendBlock(createOrganizations(options), (base, { call }) => ({
+*   archive: (id: string) => call("archive_organization", { id }, () => undefined),
+* }), { transport: options.transport });
+* ```
+*/
+function extendBlock(client, build, options = {}) {
+	const { transport } = options;
+	const additions = build(client, { call: transport ? blockCall(transport, options.schema ?? "better_supabase", options.mappers ?? []) : () => AsyncResult.err(dbError("unsupported", "extendBlock needs the transport option to call SQL functions")) });
+	const taken = Object.keys(additions).filter((key) => key in client);
+	if (taken.length > 0) throw new TypeError(`better-supabase: extendBlock can't redefine ${taken.map((key) => `"${key}"`).join(", ")}; wrap a base method with withBlockHooks instead`);
+	return Object.assign(cloneClient(client), additions);
+}
+/** Fills in `apiVersion: 1`. */
+function defineTransportMiddleware(middleware) {
+	return {
+		...middleware,
+		apiVersion: 1
+	};
+}
+/**
+* A transport that runs `middleware` around `transport`, the first one
+* outermost. Throws when a middleware targets an API other than 1.
+*/
+function wrapTransport(transport, ...middleware) {
+	for (const entry of middleware) {
+		const version = entry.apiVersion;
+		if (version !== 1) throw new TypeError(`better-supabase: transport middleware "${entry.name}" targets API ${String(version)}; this better-supabase supports 1`);
+	}
+	const run = middleware.reduceRight((next, entry) => (request) => entry.call(request, next), (request) => transport.call(request.schema, request.fn, request.args));
+	return { call: (schema, fn, args) => run({
+		schema,
+		fn,
+		args
+	}) };
+}
+//#endregion
+export { wrapTransport as i, extendBlock as n, withBlockHooks as r, defineTransportMiddleware as t };

package/dist/block-transport-DaGGXjIw.d.ts

@@ -0,0 +1,70 @@
+import { r as Executor } from "./executor-DoE-5iM8.js";
+import { n as SqlClient } from "./executor-BBHgjUJu.js";
+//#region src/core/block-transport.d.ts
+/**
+ * Calls a block function as the current user and resolves with its result.
+ * Rejects with the raw database error (a `pg` error or a PostgREST error
+ * object), which the block maps to a `DbError`.
+ */
+interface BlockTransport {
+  call(schema: string, fn: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+/**
+ * Calls the functions over Postgres, as the user `client` runs as:
+ * `sqlTransport(postgres.asUser(ctx.auth.claims))`. Works for any schema.
+ */
+declare function sqlTransport(client: SqlClient): BlockTransport;
+interface RpcResponse {
+  readonly data: unknown;
+  readonly error: unknown;
+}
+/**
+ * The part of a supabase-js client `rpcTransport` uses. The parameters are
+ * `never` so a typed `SupabaseClient<Database>` fits too: its `schema` and
+ * `rpc` only take the names its `Database` declares, which never include the
+ * block functions of a schema the types leave out.
+ */
+interface RpcClient {
+  schema(name: never): {
+    rpc(fn: never, args: never): PromiseLike<RpcResponse>;
+  };
+}
+/** Options for `rpcTransport`. */
+interface RpcTransportOptions {
+  /**
+   * The exposed schema that holds the block's entry points, such as `api`
+   * from `blocks.<module>.api`. Every call goes there instead of the
+   * module schema, which stays out of `[api] schemas` (doctor BS312).
+   */
+  readonly schema?: string;
+}
+/**
+ * Calls the functions over the Data API with the user's session. Pass
+ * `schema` with the API schema that `blocks.<module>.api` writes
+ * wrappers into; without it the calls go to the module schema, which then
+ * has to be exposed.
+ */
+declare function rpcTransport(client: RpcClient, options?: RpcTransportOptions): BlockTransport;
+/** Options for `dbTransport`. */
+interface DbTransportOptions {
+  /**
+   * The schema every call goes to instead of the module schema, such as the
+   * API schema from `blocks.<module>.api`. Over PostgREST it has to be
+   * exposed; over Postgres any schema the caller may use works.
+   */
+  readonly schema?: string;
+}
+/** The part of a `Db` that `dbTransport` uses. */
+interface DbTransportSource {
+  readonly $executor: Executor;
+}
+/**
+ * Calls the functions through a `Db`'s executor, so a block runs wherever
+ * the `Db` does: over PostgREST for `ctx.db` in a normal request, and over
+ * direct Postgres as the target in a support session or for an API key.
+ * Rejects with the raw database error, like the other transports, so the
+ * block's error mappers see the same codes and hints.
+ */
+declare function dbTransport(db: DbTransportSource, options?: DbTransportOptions): BlockTransport;
+//#endregion
+export { dbTransport as a, RpcClient as i, DbTransportOptions as n, rpcTransport as o, DbTransportSource as r, sqlTransport as s, BlockTransport as t };

package/dist/block-transport-G4t1umrR.js

@@ -0,0 +1,85 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { i as sqlIdent } from "./template-DdgYjIZ5.js";
+//#region src/core/block-transport.ts
+/**
+* Calls the functions over Postgres, as the user `client` runs as:
+* `sqlTransport(postgres.asUser(ctx.auth.claims))`. Works for any schema.
+*/
+function sqlTransport(client) {
+	return { async call(schema, fn, args) {
+		const entries = Object.entries(args).filter(([, value]) => value !== void 0);
+		const params = entries.map(([, value]) => value !== null && typeof value === "object" && (!Array.isArray(value) || value.some((entry) => entry !== null && typeof entry === "object")) ? JSON.stringify(value) : value);
+		const list = entries.map(([name], index) => `${sqlIdent(name)} => $${String(index + 1)}`).join(", ");
+		const [row] = await client.queryRaw(`select ${sqlIdent(schema)}.${sqlIdent(fn)}(${list}) as value`, params);
+		return row?.value ?? null;
+	} };
+}
+/**
+* Calls the functions over the Data API with the user's session. Pass
+* `schema` with the API schema that `blocks.<module>.api` writes
+* wrappers into; without it the calls go to the module schema, which then
+* has to be exposed.
+*/
+function rpcTransport(client, options = {}) {
+	const untyped = client;
+	return { async call(schema, fn, args) {
+		const defined = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== void 0));
+		const { data, error } = await untyped.schema(options.schema ?? schema).rpc(fn, defined);
+		if (error) {
+			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
+			throw Object.assign(new Error(message), error);
+		}
+		return data;
+	} };
+}
+/**
+* Calls the functions through a `Db`'s executor, so a block runs wherever
+* the `Db` does: over PostgREST for `ctx.db` in a normal request, and over
+* direct Postgres as the target in a support session or for an API key.
+* Rejects with the raw database error, like the other transports, so the
+* block's error mappers see the same codes and hints.
+*/
+function dbTransport(db, options = {}) {
+	return { async call(schema, fn, args) {
+		const executor = db.$executor;
+		if (!executor.rpc) throw new TypeError(`dbTransport needs an executor with rpc(); the ${executor.name} executor has none`);
+		let raw;
+		const capture = (error) => {
+			raw = error;
+		};
+		const defined = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== void 0));
+		const result = await executor.rpc(fn, defined, {
+			schema: options.schema ?? schema,
+			errorMappers: [capture]
+		});
+		if (result.ok) return result.data;
+		if (raw === void 0) throw new DbException(result.error);
+		throw Object.assign(new Error(raw.message ?? result.error.message), raw);
+	} };
+}
+/** The Postgres or PostgREST error a transport rejected with, if it is one. */
+function rawError(cause) {
+	if (!isRecord(cause)) return;
+	const field = (key) => {
+		const value = cause[key];
+		return typeof value === "string" ? value : void 0;
+	};
+	if (field("code") === void 0) return;
+	const raw = {};
+	for (const key of [
+		"message",
+		"code",
+		"details",
+		"hint",
+		"constraint"
+	]) {
+		const value = field(key);
+		if (value !== void 0) raw[key] = value;
+	}
+	const detail = field("detail");
+	if (raw["details"] === void 0 && detail !== void 0) raw["details"] = detail;
+	return raw;
+}
+//#endregion
+export { sqlTransport as i, rawError as n, rpcTransport as r, dbTransport as t };