better-supabase 0.7.1 → 0.9.0

package/dist/better-result/index.js

@@ -0,0 +1,64 @@
+import { o as toBetterResult, t as AsyncResult } from "../result-BlgnMB0H.js";
+//#region src/better-result/better-result.ts
+const HELPERS = [
+	"$rpc",
+	"$run",
+	"$many",
+	"$search"
+];
+function converterOf(toResult) {
+	if (typeof toResult === "function") return (result) => toResult(result);
+	return (result) => toBetterResult(result, toResult.Result, toResult.mapError);
+}
+function view(db, convert) {
+	const wrap = (value) => value instanceof AsyncResult ? convert(value) : value;
+	const call = (target, method, name) => {
+		if (typeof method !== "function") throw new TypeError(`better-supabase: ${name} is not a function`);
+		return (...args) => wrap(method.apply(target, args));
+	};
+	const repositories = /* @__PURE__ */ new WeakMap();
+	const repository = (target, name) => {
+		if (typeof target !== "object" || target === null) throw new TypeError(`better-supabase: unknown table ${name}`);
+		const cached = repositories.get(target);
+		if (cached) return cached;
+		const wrapped = Object.fromEntries(Object.entries(target).map(([key, value]) => [key, typeof value === "function" ? call(target, value, key) : value]));
+		repositories.set(target, wrapped);
+		return wrapped;
+	};
+	const result = {
+		$db: db,
+		$from: convert,
+		$table: (name) => repository(db.$table(name), name),
+		$list: (list, query, extra) => wrap(list.run(db, query, extra))
+	};
+	for (const key of HELPERS) result[key] = call(db, db[key], `db.${key}`);
+	for (const key in db) {
+		if (key.startsWith("$")) continue;
+		Object.defineProperty(result, key, {
+			enumerable: true,
+			get: () => repository(db.$table(key), key)
+		});
+	}
+	return result;
+}
+/**
+* A view of `db` whose repository methods, `$rpc`, `$run`, `$many`,
+* `$search` and list queries (`$list`) return better-result `Result`
+* values. `toResult` is a `defineBetterResultErrors` converter or
+* `{ Result, mapError }`. `db` itself is unchanged, and `$db` returns it.
+*
+* ```ts
+* import { Result, TaggedError } from 'better-result';
+* import { defineBetterResultErrors } from 'better-supabase';
+* import { withBetterResult } from 'better-supabase/better-result';
+*
+* const toResult = defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure);
+* const rdb = withBetterResult(db, toResult);
+* const customer = await rdb.customers.findById(id); // Result<Customer, NotFound | DbFailure>
+* ```
+*/
+function withBetterResult(db, toResult) {
+	return view(db, converterOf(toResult));
+}
+//#endregion
+export { withBetterResult };

package/dist/bind-a7sUgvf4.d.ts

@@ -0,0 +1,70 @@
+import { a as AnyModels, i as AnyFunctions } from "./types-YfwpIE-d.js";
+import { _ as Db, t as BetterSupabase } from "./define-DxHHbNEb.js";
+import { t as ClientPorts } from "./ports-DAdQyjZz.js";
+import { s as BetterQueries } from "./index-DygICr8c.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/client/bind.d.ts
+interface AuthUser {
+  readonly id: string;
+  readonly email?: string;
+  readonly role?: string;
+}
+/**
+ * What the UI needs to know. Claims are decoded, not verified: RLS enforces
+ * access. A token refresh that changes only `exp`, `iat`, `nbf` or `jti`
+ * keeps the previous snapshot, so read expiry from the session, not here.
+ */
+type AuthSnapshot = {
+  readonly status: "loading";
+  readonly user: null;
+  readonly claims: null;
+} | {
+  readonly status: "signed-out";
+  readonly user: null;
+  readonly claims: null;
+} | {
+  readonly status: "signed-in";
+  readonly user: AuthUser;
+  readonly claims: Readonly<Record<string, unknown>>;
+};
+interface ClientAuth {
+  readonly current: () => AuthSnapshot;
+  /** `useSyncExternalStore`-compatible. */
+  readonly subscribe: (listener: () => void) => () => void;
+}
+interface BetterClient<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
+  /** The definition the client was created from (schema metadata, specs, live queries). */
+  readonly betterSupabase: BetterSupabase<M, unknown, F, E, C, P>;
+  readonly supabase: SupabaseClient;
+  /** Repositories with the current session's actor and claims. */
+  readonly db: Db<M, F, E, SupabaseClient>;
+  /** TanStack Query option factories over `db`. */
+  readonly queries: BetterQueries<M, E, F>;
+  readonly auth: ClientAuth;
+  /** The platform services block controllers use: storage, shortcuts, files, push, links. */
+  readonly ports: ClientPorts;
+  /**
+   * Stops following `supabase`'s session. Call it when the client goes away
+   * before the app does: Fast Refresh, tests, a client per account.
+   */
+  readonly dispose: () => void;
+}
+interface BindClientOptions {
+  /**
+   * `staleTime` for every query option in `queries`. Above zero, a remount
+   * or a window focus reuses cached rows instead of refetching them.
+   */
+  readonly staleTime?: number;
+  /**
+   * Platform services for the block hooks. React Native apps pass
+   * `nativePorts()` from `better-supabase/client/native`.
+   */
+  readonly ports?: ClientPorts;
+}
+/**
+ * Repositories that follow `supabase`'s session, TanStack Query options and
+ * an auth store, for a supabase-js client you created yourself.
+ */
+declare function bindClient<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, supabase: SupabaseClient, options?: BindClientOptions): BetterClient<M, F, E, C, P>;
+//#endregion
+export { ClientAuth as a, BindClientOptions as i, AuthUser as n, bindClient as o, BetterClient as r, AuthSnapshot as t };

package/dist/block-env-CBd_SoL5.js

@@ -0,0 +1,29 @@
+import { t as topicPort } from "./watch-topic-miuymrli.js";
+//#region src/blocks/block-env.ts
+/** The client's session and ports; the topic port defaults to its supabase-js client. */
+function blockEnv(client) {
+	return {
+		supabase: client.supabase,
+		auth: client.auth,
+		ports: {
+			...client.ports,
+			topic: client.ports?.topic ?? topicPort(client.supabase)
+		}
+	};
+}
+/**
+* Fills `auth` and `ports` from `env` when `options` leaves them out; `env`
+* runs only then. Without `env` the controller takes neither key.
+*/
+function withEnv(options, env) {
+	const given = new Map(Object.entries(options));
+	if (env === void 0 || given.get("auth") !== void 0 && given.get("ports") !== void 0) return options;
+	const { auth, ports } = env();
+	return {
+		auth,
+		ports,
+		...options
+	};
+}
+//#endregion
+export { withEnv as n, blockEnv as t };

package/dist/block-env-Dxl7rsI0.d.ts

@@ -0,0 +1,10 @@
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/blocks/block-env.d.ts
+type EnvKey = "auth" | "ports";
+/**
+ * A controller's options as a binding takes them: `auth` and `ports` come
+ * from the provider unless the caller passes its own.
+ */
+type BlockOptions<O> = Omit<O, EnvKey> & Partial<Pick<O, Extract<keyof O, EnvKey>>>;
+//#endregion
+export { BlockOptions as t };

package/dist/block-events-DD9Q_NUz.js

@@ -0,0 +1,96 @@
+import { t as cloneValue } from "./clone-dN9XOL1K.js";
+import { s as nowInstant } from "./temporal-CB5Fpo5d.js";
+//#region src/core/block-events.ts
+/**
+* Event types that changed name in 0.6, old to new, for sinks and consumers
+* that still receive the old ones (`BLOCK_EVENT_RENAMES[type] ?? type`).
+* `better-supabase codemod 0.6` rewrites the string literals.
+*/
+const BLOCK_EVENT_RENAMES = {
+	"org.created": "organization.created",
+	"org.updated": "organization.updated",
+	"org.deleted": "organization.deleted",
+	"org.member_added": "organization.member_added",
+	"org.member_removed": "organization.member_removed",
+	"org.member_left": "organization.member_left",
+	"org.role_changed": "organization.role_changed",
+	"org.ownership_transferred": "organization.ownership_transferred",
+	"org.switched": "organization.switched"
+};
+/**
+* Fixed OpenTelemetry attribute names for block work, so dashboards and
+* queries can rely on them.
+*/
+const BLOCK_ATTRIBUTES = {
+	event: "better_supabase.block.event",
+	tenant: "better_supabase.tenant",
+	actor: "better_supabase.actor.id",
+	supportSessionId: "better_supabase.support.session_id",
+	organizationId: "better_supabase.organization.id",
+	invitationId: "better_supabase.invitation.id",
+	notificationType: "better_supabase.notification.type",
+	webhookEndpointId: "better_supabase.webhook.endpoint_id"
+};
+/** The `BLOCK_ATTRIBUTES` an event carries. */
+function blockEventAttributes(event) {
+	const attributes = { [BLOCK_ATTRIBUTES.event]: event.type };
+	if (event.tenant) attributes[BLOCK_ATTRIBUTES.tenant] = event.tenant;
+	if (event.actorId) attributes[BLOCK_ATTRIBUTES.actor] = event.actorId;
+	const data = Object.fromEntries(Object.entries(event.data));
+	const add = (key, value) => {
+		if (typeof value === "string" && value.length > 0) attributes[key] = value;
+	};
+	add(BLOCK_ATTRIBUTES.supportSessionId, data["sessionId"]);
+	add(BLOCK_ATTRIBUTES.organizationId, data["organizationId"]);
+	add(BLOCK_ATTRIBUTES.invitationId, data["invitationId"]);
+	add(BLOCK_ATTRIBUTES.notificationType, data["type"]);
+	add(BLOCK_ATTRIBUTES.webhookEndpointId, data["endpointId"]);
+	return attributes;
+}
+/**
+* Emits a block event on `events` with a copy of `data`. Does nothing without
+* a `block` handler, so blocks call it unconditionally. `M` is the emitting
+* block's event map.
+*/
+function emitBlockEvent(events, type, data, meta = {}) {
+	if (!events.has("block")) return;
+	const copy = cloneValue(data);
+	const event = {
+		...meta,
+		type,
+		data: copy,
+		time: (events.now ?? nowInstant)()
+	};
+	events.emit("block", event);
+}
+/**
+* The `emit` a block creator calls with its own event map: skips the work
+* without an event hub and adds the actor and request context from the
+* block's options.
+*/
+function blockEmitter(options) {
+	return (type, data, subject, tenant) => {
+		if (!options.events) return;
+		emitBlockEvent(options.events, type, data, {
+			subject,
+			...tenant ? { tenant } : {},
+			...options.actorId ? { actorId: options.actorId } : {},
+			...options.context ? { context: options.context } : {}
+		});
+	};
+}
+const matches = (pattern, type) => pattern.endsWith(".*") ? type.startsWith(pattern.slice(0, -1)) : pattern === type;
+/**
+* Listens to the block events that match `pattern` (`'support.started'` or
+* `'support.*'`), typed by `events`: a block's events, `defineBlocks(...)`
+* or `defineEvents(...)`. Returns a function that stops listening.
+*/
+function onBlockEvent(betterSupabase, events, pattern, handler) {
+	const known = new Set(events.types);
+	return betterSupabase.events.on("block", (event) => {
+		if (!known.has(event.type) || !matches(pattern, event.type)) return;
+		handler(event);
+	});
+}
+//#endregion
+export { emitBlockEvent as a, blockEventAttributes as i, BLOCK_EVENT_RENAMES as n, onBlockEvent as o, blockEmitter as r, BLOCK_ATTRIBUTES as t };

package/dist/block-fields-5UA84ZUg.d.ts

@@ -0,0 +1,55 @@
+import { f as Result, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+//#region src/core/block-fields.d.ts
+/** The fields a `fields` schema adds, or none when the block has no schema. */
+type FieldsOf<S> = S extends StandardSchemaV1<unknown, infer O> ? O extends object ? O : never : Record<never, never>;
+/** The extra columns of a row, keyed by database name, typed by `F`. */
+type ExtraFields<F extends object = Record<never, never>> = Readonly<Record<string, unknown>> & F;
+/** A row whose extra columns a block read under `fields`. */
+interface WithExtraFields {
+  readonly fields: Readonly<Record<string, unknown>>;
+}
+/**
+ * Parses and validates the extra fields an app adds to a block's table,
+ * with any Standard Schema (zod, valibot, arktype) for an object.
+ */
+interface BlockFields<T extends object> {
+  /**
+   * Parses a row the block read: the schema's output replaces the fields it
+   * covers, and the other fields stay as read. A row the schema rejects is
+   * a `validation` error.
+   */
+  read<R extends object>(row: R): Promise<Result<R & T>>;
+  /**
+   * Validates the fields a write sets. Issues about fields the write leaves
+   * out are ignored, so partial updates pass; the database applies its
+   * defaults and `not null` checks. A rejected write is a `validation`
+   * error, and nothing is sent to the database.
+   */
+  write<A extends object>(attrs: A): Promise<Result<A>>;
+  /**
+   * Parses the `fields` of a row the block read: the extra columns its SQL
+   * returns under `fields`, keyed by database name.
+   */
+  readonly row: <R extends WithExtraFields>(row: R) => AsyncResult<R & {
+    readonly fields: ExtraFields<T>;
+  }>;
+  /** `row` for each row, stopping at the first rejected one. */
+  readonly rows: <R extends WithExtraFields>(rows: readonly R[]) => AsyncResult<(R & {
+    readonly fields: ExtraFields<T>;
+  })[]>;
+  /**
+   * Validates the extra fields a write sets, as the jsonb argument the SQL
+   * function takes; `undefined` without any, so the argument is left out.
+   */
+  readonly args: (fields: object | undefined) => AsyncResult<Readonly<Record<string, unknown>> | undefined>;
+}
+/** The extra columns a block row carries, by column name, typed by its `fields` schema. */
+type RowFields<F extends object> = Readonly<Record<string, unknown>> & F;
+/**
+ * The `fields` helper block creators use. Without a schema, reads and
+ * writes pass through unchanged.
+ */
+declare function blockFields<T extends object = Record<never, never>>(schema: StandardSchemaV1 | undefined, label: string): BlockFields<T>;
+//#endregion
+export { WithExtraFields as a, RowFields as i, ExtraFields as n, blockFields as o, FieldsOf as r, BlockFields as t };

package/dist/block-fields-ffD6Gxe4.js

@@ -0,0 +1,139 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-BlgnMB0H.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { t as toIssues } from "./standard-B5fe2gnW.js";
+//#region src/core/block-fields.ts
+/** Parses the `fields` of one row with `fields.read`. */
+function readFields(fields, row) {
+	return AsyncResult.from(() => fields.read(row.fields)).map((parsed) => ({
+		...row,
+		fields: parsed
+	}));
+}
+/** Parses the `fields` of each row; the first rejected row fails the read. */
+function readAllFields(fields, rows) {
+	return AsyncResult.from(async () => {
+		const out = [];
+		for (const row of rows) {
+			const parsed = await fields.read(row.fields);
+			if (!parsed.ok) return parsed;
+			out.push({
+				...row,
+				fields: parsed.data
+			});
+		}
+		return ok(out);
+	});
+}
+/**
+* Validates the `fields` a write sets with `fields.write`, then builds the
+* call. A write without fields skips the check and passes none.
+*/
+function writeFields(fields, values, then) {
+	if (values === void 0) return then(void 0);
+	return AsyncResult.from(() => fields.write({ ...values })).andThen(then);
+}
+/** The `fields` object of a row a block function returned, or none. */
+function rowFields(value) {
+	return isRecord(value) ? value : {};
+}
+async function run(schema, value) {
+	return schema["~standard"].validate(value);
+}
+const invalid = (label, issues) => err(dbError("validation", `Invalid ${label}`, { issues }));
+/**
+* The `fields` helper block creators use. Without a schema, reads and
+* writes pass through unchanged.
+*/
+function blockFields(schema, label) {
+	const fields = {
+		async read(row) {
+			if (schema === void 0) return ok(row);
+			const outcome = await run(schema, row);
+			if (outcome.issues) return invalid(label, toIssues(outcome.issues));
+			if (!isRecord(outcome.value)) return invalid(label, [{ message: "fields must parse to an object" }]);
+			return ok({
+				...row,
+				...outcome.value
+			});
+		},
+		async write(attrs) {
+			if (schema === void 0) return ok(attrs);
+			const outcome = await run(schema, attrs);
+			if (!outcome.issues) {
+				if (!isRecord(outcome.value)) return ok(attrs);
+				const parsed = outcome.value;
+				const picked = Object.fromEntries(Object.keys(attrs).filter((key) => key in parsed).map((key) => [key, parsed[key]]));
+				return ok({
+					...attrs,
+					...picked
+				});
+			}
+			const given = new Set(Object.keys(attrs));
+			const relevant = toIssues(outcome.issues).filter((issue) => {
+				const [first] = issue.path ?? [];
+				return first === void 0 || given.has(String(first));
+			});
+			if (relevant.length === 0) return ok(attrs);
+			return invalid(label, relevant);
+		},
+		row: (row) => AsyncResult.from(() => fields.read(row.fields)).map((parsed) => ({
+			...row,
+			fields: parsed
+		})),
+		rows: (rows) => AsyncResult.from(async () => {
+			const out = [];
+			for (const row of rows) {
+				const parsed = await fields.row(row);
+				if (!parsed.ok) return parsed;
+				out.push(parsed.data);
+			}
+			return ok(out);
+		}),
+		args: (extra) => AsyncResult.from(async () => {
+			if (extra === void 0 || Object.keys(extra).length === 0) return ok(void 0);
+			const checked = await fields.write({ ...extra });
+			return checked.ok ? ok(checked.data) : checked;
+		})
+	};
+	return fields;
+}
+/** The keys of a write the block doesn't type itself: its extra fields. */
+const extraOf = (input, known) => Object.fromEntries(Object.entries(input).filter(([key]) => !known.has(key)));
+/** The extra columns a block read returns under its `fields` key. */
+const extraFieldsOf = (value) => isRecord(value) && isRecord(value["fields"]) ? value["fields"] : {};
+/**
+* Parses the extra columns of `raw` (a row a block function returned) and
+* adds them to `row`, the block's typed row. The row's own keys win, so an
+* extra column never replaces one the block types.
+*/
+async function withFields(fields, raw, row) {
+	const parsed = await fields.read(extraFieldsOf(raw));
+	if (!parsed.ok) return parsed;
+	return ok({
+		...parsed.data,
+		...row
+	});
+}
+/** `withFields` over a list of pairs: the raw row and the typed row. */
+async function allWithFields(fields, rows) {
+	const out = [];
+	for (const [raw, row] of rows) {
+		const parsed = await withFields(fields, raw, row);
+		if (!parsed.ok) return parsed;
+		out.push(parsed.data);
+	}
+	return ok(out);
+}
+/**
+* Validates the extra fields of a write: `{ fields }` to spread into
+* the call's arguments, or `{}` when the write sets none, so a module
+* without extra columns is called as before.
+*/
+async function extraFieldsArg(fields, extra) {
+	if (Object.keys(extra).length === 0) return ok({});
+	const valid = await fields.write(extra);
+	return valid.ok ? ok({ fields: valid.data }) : valid;
+}
+//#endregion
+export { readAllFields as a, withFields as c, extraOf as i, writeFields as l, blockFields as n, readFields as o, extraFieldsArg as r, rowFields as s, allWithFields as t };

package/dist/block-helpers-C86hPEjI.d.ts

@@ -0,0 +1,37 @@
+import { t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+//#region src/core/block-helpers.d.ts
+/** The `temporal` option every block creator takes. */
+interface BlockTemporalOptions {
+  /**
+   * The Temporal namespace for runtimes without a global one, such as
+   * `import { Temporal } from "temporal-polyfill"`. Blocks use it instead of
+   * `globalThis.Temporal`, which stays untouched; like
+   * `defineSupabase(schema, { temporal })`, it applies to the whole process.
+   */
+  readonly temporal?: typeof Temporal;
+}
+/** The options every block creator shares. */
+interface BlockOptions extends BlockTemporalOptions {
+  /** `sqlTransport(ctx.postgres)` for members, or `rpcTransport` over an API schema. */
+  readonly transport: BlockTransport;
+  /** The transport for service-only calls (jobs, purges). Defaults to `transport`. */
+  readonly service?: BlockTransport;
+  /** The module's schema, or its API schema. Default `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers that run before the built-in ones. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** Calls one block function and maps a rejection to a `DbError`. */
+type BlockCall = <T>(fn: string, args: Readonly<Record<string, unknown>>, then: (value: unknown) => T | Promise<T>) => AsyncResult<T>;
+/**
+ * One page of a list. `cursor` is the previous page's `next` cursor or last
+ * item, in the shape each list documents.
+ */
+interface CursorPageOptions<Cursor> {
+  /** The most items to return. Each list documents its default and maximum. */
+  readonly limit?: number;
+  readonly cursor?: Cursor;
+}
+//#endregion
+export { CursorPageOptions as i, BlockOptions as n, BlockTemporalOptions as r, BlockCall as t };