better-supabase 0.13.0 → 0.15.0

package/dist/otel/index.js

@@ -1,6 +1,6 @@
-import { r as definePlugin } from "../plugin-D9bYbYli.js";
-import { t as SPEC_PINS } from "../spec-pins-D3Tm6HJi.js";
-import { i as blockEventAttributes } from "../block-events-BURaqwyp.js";
+import { r as definePlugin } from "../plugin-AKwwe2gF.js";
+import { t as SPEC_PINS } from "../spec-pins-C1Vm8OBl.js";
+import { i as blockEventAttributes } from "../block-events-pBXPzwnW.js";
 import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
 //#endregion
 //#region src/otel/index.ts
@@ -40,9 +40,9 @@ function systemOf(executor) {
 * ```
 */
 function otel(options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.13.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.15.0");
 	let histogram;
-	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.13.0")).createHistogram("db.client.operation.duration", {
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.15.0")).createHistogram("db.client.operation.duration", {
 		unit: "s",
 		description: "Duration of database client operations.",
 		advice: { explicitBucketBoundaries: [
@@ -219,7 +219,7 @@ function otel(options = {}) {
 * `betterSupabase.events`. Returns a function that stops listening.
 */
 function traceAuth(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.13.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.15.0");
 	const offAuth = betterSupabase.events.on("auth", (event) => {
 		const span = tracer.startSpan("auth.resolve", {
 			kind: SpanKind.INTERNAL,
@@ -257,7 +257,7 @@ function traceAuth(betterSupabase, options = {}) {
 * an error status. Returns a function that stops listening.
 */
 function traceBlockEvents(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.13.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.15.0");
 	return betterSupabase.events.on("block", (event) => {
 		const attributes = {
 			...options.attributes,

package/dist/outbox-HvGAJuBe.d.ts

@@ -0,0 +1,199 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CursorPageOptions, n as BlockOptions } from "./block-helpers-CRpAHrp_.js";
+import { n as BlockHooks } from "./block-hooks-DZN2w69m.js";
+import { t as BlockProblemOptions } from "./problem-DNwN8iGz.js";
+import { i as EventSink, t as CloudEvent } from "./cloud-event-CzZTJkXv.js";
+import { g as SubscriberPolicy, i as AuthorizationHooks } from "./authorization-hooks-Cs1vP_ej.js";
+//#region src/blocks/outbox/outbox.d.ts
+/** One row of the outbox, as `outbox_claim` and `outbox_history` return it. */
+interface OutboxEvent {
+  /** The cursor value: increases with every event. */
+  readonly position: number;
+  readonly id: string;
+  readonly type: string;
+  readonly payload: unknown;
+  /**
+   * The module or function that wrote it, e.g.
+   * `better-supabase/blocks/organizations`.
+   */
+  readonly source: string | null;
+  readonly subject: string | null;
+  readonly tenant: string | null;
+  readonly key: string | null;
+  readonly actorId: string | null;
+  readonly createdAt: Temporal.Instant;
+}
+interface EmitOptions {
+  readonly subject?: string;
+  readonly tenant?: string;
+  /** With a key, emitting again (per tenant) returns the first event. */
+  readonly key?: string;
+  readonly source?: string;
+}
+/**
+ * `transport` writes (`emit`) and reads (`history`); `service`, which defaults
+ * to `transport`, runs the consumer calls (`register`, `relay`, `consume`,
+ * `deadLetters`, `purge`), which need the service role.
+ */
+interface OutboxOptions extends BlockOptions {
+  /** CloudEvents `source` of the relayed events, e.g. `https://crm.example.com`. */
+  readonly source: string;
+  /**
+   * Prepended to each type with a dot when relaying, e.g. `com.example`.
+   * Defaults to `dev.better-supabase`.
+   */
+  readonly typePrefix?: string;
+  /**
+   * Decides, per event, whether a consumer gets it. The consumer is the
+   * subscriber `{ principal: <consumer name>, kind: "service" }`. An event it
+   * leaves out is skipped and the cursor moves past it; a throw counts as a
+   * failed attempt. Defaults to `authorization.delivery.subscribers`.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** `server.authorization`, for its `delivery.subscribers` policy. */
+  readonly authorization?: Pick<AuthorizationHooks, "delivery">;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Outbox>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface RegisterOptions {
+  /**
+   * Type patterns such as `organization.*` or `invoice.paid`. Defaults to every
+   * event.
+   */
+  readonly types?: readonly string[];
+  /** Start at the first kept event instead of after the latest one. */
+  readonly fromStart?: boolean;
+}
+interface RelayOptions {
+  /** Events per claim and per `sink.send`. Defaults to 100. */
+  readonly batch?: number;
+  /** How long a claim holds the consumer. Defaults to `1 minute`. */
+  readonly lease?: string;
+  /** Stops claiming after this many milliseconds. */
+  readonly budgetMs?: number;
+  /** Identifies this worker in the lease. Defaults to a random id. */
+  readonly owner?: string;
+  /**
+   * Failures in a row before the event that keeps failing goes to the dead
+   * letters and the cursor moves past it. Defaults to 10.
+   */
+  readonly maxAttempts?: number;
+  /** The longest wait between failed attempts. Defaults to `10 minutes`. */
+  readonly maxBackoff?: string;
+}
+interface RelayResult {
+  /** Events handed to the sink or handler. */
+  readonly delivered: number;
+  /**
+   * Events the `subscribers` policy kept from the consumer, when there were
+   * any.
+   */
+  readonly refused?: number;
+  /**
+   * Set when the sink threw: the consumer backs off and retries the batch one
+   * event at a time.
+   */
+  readonly error?: DbError;
+  /** 1 when this run moved the failing event to the dead letters. */
+  readonly deadLettered?: number;
+}
+/** An event a consumer skipped after `maxAttempts` failures. */
+interface OutboxDeadLetter {
+  readonly consumer: string;
+  readonly event: OutboxEvent;
+  readonly attempts: number;
+  readonly error: string | null;
+  readonly deadAt: Temporal.Instant;
+}
+interface OutboxPurgeOptions {
+  /**
+   * A consumer that hasn't claimed for this long (a Postgres interval such as
+   * `30 days`) no longer holds events back. Defaults to waiting for every
+   * consumer.
+   */
+  readonly ignoreIdle?: string;
+}
+/**
+ * Takes a batch of outbox rows, with the actor and tenant that CloudEvents
+ * leave out. Throwing counts a failed attempt: the consumer backs off, then
+ * retries one event at a time until the event that fails goes to the dead
+ * letters.
+ */
+type OutboxHandler = (events: readonly OutboxEvent[]) => unknown;
+interface OutboxRouteOptions extends Omit<RelayOptions, "owner">, BlockProblemOptions {
+  /** The bearer secret, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /**
+   * Consumer name to the sink its events go to, or a handler that takes the
+   * rows.
+   */
+  readonly consumers: Readonly<Record<string, EventSink | OutboxHandler>>;
+  readonly onError?: (error: DbError, consumer: string) => void;
+}
+interface OutboxRouteResult {
+  readonly consumers: Readonly<Record<string, RelayResult>>;
+  readonly budgetExhausted: boolean;
+}
+interface HistoryFilter extends CursorPageOptions<number> {
+  readonly subject?: string;
+  readonly type?: string;
+  /** Only events after this position. */
+  readonly cursor?: number;
+  readonly limit?: number;
+}
+interface Outbox {
+  /** Writes an event in the current transaction and returns its id. */
+  emit(type: string, payload?: unknown, options?: EmitOptions): AsyncResult<string>;
+  /** Creates the consumer, or changes its types. Returns its cursor position. */
+  register(consumer: string, options?: RegisterOptions): AsyncResult<number>;
+  /** Removes the consumer, so purges stop waiting for it. */
+  unregister(consumer: string): AsyncResult<boolean>;
+  /**
+   * Claims the consumer's next events, sends them to `sink` as CloudEvents and
+   * moves the cursor, until none are left or the budget runs out. A sink that
+   * throws leaves the batch for a later run with backoff, so delivery is at
+   * least once; an event that fails `maxAttempts` times goes to the dead
+   * letters.
+   */
+  relay(consumer: string, sink: EventSink, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * Like `relay`, but hands `handler` the outbox rows themselves, with
+   * `actorId`, `tenant` and `key`, for consumers inside the app (search
+   * indexing, notifications) that need the actor.
+   */
+  consume(consumer: string, handler: OutboxHandler, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * A `GET`/`POST` handler for a cron that relays every consumer at once,
+   * within one budget.
+   */
+  relayRoute(options: OutboxRouteOptions): (request: Request) => Promise<Response>;
+  history(filter?: HistoryFilter): AsyncResult<readonly OutboxEvent[]>;
+  /** The consumer's dead letters, newest first (default 100, at most 1000). */
+  deadLetters(consumer: string, limit?: number): AsyncResult<readonly OutboxDeadLetter[]>;
+  /**
+   * Deletes up to `batch` events (default 10,000) older than `olderThan` that
+   * every consumer has passed, and dead letters older than `olderThan`. Call it
+   * again while it returns `batch`.
+   */
+  purge(olderThan?: string, batch?: number, options?: OutboxPurgeOptions): AsyncResult<number>;
+}
+/**
+ * The CloudEvent for an outbox row: the row id as `id` (stable, so receivers
+ * can deduplicate), the payload as `data`, the tenant as `partitionkey` and the
+ * writing module as `producer`. The actor stays out of the context attributes,
+ * which must not carry personal data.
+ */
+declare function outboxCloudEvent(event: OutboxEvent, options: Pick<OutboxOptions, "source" | "typePrefix">): CloudEvent;
+/**
+ * The outbox over a `BlockTransport`: `sqlTransport(postgres)` on a server
+ * connection, where `emit` joins the caller's transaction, or
+ * `rpcTransport(serviceClient)` for apps that reach the database only through
+ * the Data API, where `emit` writes in its own transaction.
+ */
+declare function createOutbox(options: OutboxOptions): Outbox;
+//#endregion
+export { OutboxEvent as a, OutboxPurgeOptions as c, RegisterOptions as d, RelayOptions as f, outboxCloudEvent as h, OutboxDeadLetter as i, OutboxRouteOptions as l, createOutbox as m, HistoryFilter as n, OutboxHandler as o, RelayResult as p, Outbox as r, OutboxOptions as s, EmitOptions as t, OutboxRouteResult as u };

package/dist/payments-BXvabJOw.js

@@ -0,0 +1,16 @@
+import { n as dbError } from "./errors-BVFgt8BZ.js";
+import { c as isMoney } from "./money-BZl985O-.js";
+//#region src/commerce/payments.ts
+/** Checks the provider's `apiVersion` before a block uses it. */
+function paymentProviderOf(provider) {
+	const version = provider.apiVersion;
+	if (version !== 1) throw new TypeError(`payments "${provider.name}" targets payment provider API ${String(version)}; this better-supabase supports 1. Upgrade better-supabase or use a release of the provider for API 1.`);
+	return provider;
+}
+/** The error for an amount a payment can't carry: not money, or not above zero. */
+function invalidPaymentAmount(amount) {
+	if (!isMoney(amount)) return dbError("invalid_input", "A payment amount is Money: a bigint of minor units and an ISO 4217 currency", { hint: "PAYMENT_AMOUNT_INVALID" });
+	if (amount.amount <= 0n) return dbError("invalid_input", "A payment amount must be more than zero", { hint: "PAYMENT_AMOUNT_INVALID" });
+}
+//#endregion
+export { paymentProviderOf as n, invalidPaymentAmount as t };

package/dist/payments-BYcN34Fp.d.ts

@@ -0,0 +1,114 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { n as Money } from "./money-BNRdJQzA.js";
+import { r as WebhookInput } from "./signatures-Dkx9OE8j.js";
+//#region src/commerce/payments.d.ts
+/**
+ * Where a payment stands. `requires_action`: the customer still has to act
+ * (pick a method, confirm, pass 3-D Secure). `authorized`: the funds are held
+ * and wait for `capture`.
+ */
+type PaymentStatus = "requires_action" | "processing" | "authorized" | "succeeded" | "failed" | "canceled";
+interface Payment {
+  /** The provider's id, stored with the order as its payment reference. */
+  readonly id: string;
+  /** The provider's `name`. */
+  readonly provider: string;
+  readonly status: PaymentStatus;
+  readonly amount: Money;
+  /** What was captured so far; zero until the payment succeeds. */
+  readonly captured: Money;
+  /** What was refunded so far. */
+  readonly refunded: Money;
+  /** The order or cart the payment is for, as `createPayment` got it. */
+  readonly reference: string;
+  /**
+   * The secret a client confirms the payment with (Stripe's `client_secret`).
+   * Hand it to the paying browser only; never store or log it.
+   */
+  readonly clientSecret?: string;
+  /** Where to send the customer to finish, when the provider redirects. */
+  readonly redirectUrl?: string;
+  readonly metadata: Readonly<Record<string, string>>;
+}
+interface CreatePaymentInput {
+  /** More than zero, in a currency the provider charges. */
+  readonly amount: Money;
+  /** The order or cart this pays for. Webhook events carry it back. */
+  readonly reference: string;
+  /** `manual` holds the funds until `capture`. Defaults to `automatic`. */
+  readonly capture?: "automatic" | "manual";
+  /** The provider's customer id. */
+  readonly customer?: string;
+  readonly description?: string;
+  /** Where a redirecting payment method returns the customer. */
+  readonly returnUrl?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+interface PaymentCallOptions {
+  /** The same key returns the first call's result instead of paying twice. */
+  readonly idempotencyKey?: string;
+  readonly signal?: AbortSignal;
+}
+type RefundStatus = "pending" | "succeeded" | "failed" | "canceled";
+interface Refund {
+  readonly id: string;
+  readonly paymentId: string;
+  readonly amount: Money;
+  readonly status: RefundStatus;
+}
+interface RefundInput {
+  /** Defaults to what is left of the captured amount. */
+  readonly amount?: Money;
+  readonly reason?: string;
+}
+type PaymentEventType = "payment.requires_action" | "payment.processing" | "payment.authorized" | "payment.succeeded" | "payment.failed" | "payment.canceled" | "refund.succeeded" | "refund.failed";
+/** A provider's webhook event in one shape for every provider. */
+interface PaymentEvent {
+  /**
+   * The provider's event id. A redelivered event repeats it, so key the
+   * handling on it (the webhook inbox and the `idempotency` module do).
+   */
+  readonly id: string;
+  readonly type: PaymentEventType;
+  readonly paymentId: string;
+  /** The payment's `reference`, when the event carries it. */
+  readonly reference?: string;
+  /** The payment's amount, or the refund's for `refund.*`. */
+  readonly amount?: Money;
+  readonly refundId?: string;
+  readonly occurredAt: Temporal.Instant;
+}
+/**
+ * Takes payments for orders. Versioned: a breaking change ships a new
+ * `apiVersion`. Every method returns a `Result`: `invalid_input` for an amount
+ * the provider can't charge or a refund above what was captured, `not_found`
+ * for an unknown payment, `unauthorized` for a webhook whose signature fails,
+ * and `raised` with the hint `PAYMENT_DECLINED` when the provider declines.
+ */
+interface PaymentProvider {
+  readonly apiVersion: 1;
+  readonly name: string;
+  createPayment(input: CreatePaymentInput, options?: PaymentCallOptions): AsyncResult<Payment>;
+  /** Captures an authorized payment, all of it unless `amount` is less. */
+  capture(paymentId: string, input?: {
+    readonly amount?: Money;
+  }, options?: PaymentCallOptions): AsyncResult<Payment>;
+  refund(paymentId: string, input?: RefundInput, options?: PaymentCallOptions): AsyncResult<Refund>;
+  /**
+   * Verifies a webhook delivery with the provider's secret and returns its
+   * events, none for types the contract doesn't cover.
+   */
+  parseWebhook(input: WebhookInput): AsyncResult<readonly PaymentEvent[]>;
+  /** Releases a payment that was not captured yet. */
+  cancel?(paymentId: string, options?: PaymentCallOptions): AsyncResult<Payment>;
+  get?(paymentId: string, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<Payment>;
+}
+/** Checks the provider's `apiVersion` before a block uses it. */
+declare function paymentProviderOf(provider: PaymentProvider): PaymentProvider;
+/** The error for an amount a payment can't carry: not money, or not above zero. */
+declare function invalidPaymentAmount(amount: unknown): DbError | undefined;
+//#endregion
+export { PaymentEventType as a, Refund as c, invalidPaymentAmount as d, paymentProviderOf as f, PaymentEvent as i, RefundInput as l, Payment as n, PaymentProvider as o, PaymentCallOptions as r, PaymentStatus as s, CreatePaymentInput as t, RefundStatus as u };

package/dist/permissions-controller-BMsqIE5T.js

@@ -0,0 +1,34 @@
+//#region src/blocks/permissions/permissions-controller.ts
+/**
+* Whether a granted key covers a wanted one: the same rule as the SQL
+* `permission_matches`, where `*` grants every key and `prefix.*` every key
+* under `prefix`.
+*/
+function permissionMatches(granted, wanted) {
+	return granted === "*" || granted === wanted || granted.endsWith(".*") && wanted.startsWith(granted.slice(0, -1));
+}
+/**
+* Whether `set` holds `key`. UX only: RLS and the SQL functions check the key
+* again.
+*
+* ```ts
+* if (can(permissionSet, permissions.customers.write)) showEditButton();
+* ```
+*/
+function can(set, key) {
+	return set?.keys.some((granted) => permissionMatches(granted, key)) ?? false;
+}
+/**
+* One `can<Name>` boolean per entry of `flags`, for a payload query that
+* returns data and what the caller may do with it.
+*
+* ```ts
+* permissionFlags(set, { edit: permissions.customers.write });
+* // { canEdit: true }
+* ```
+*/
+function permissionFlags(set, flags) {
+	return Object.fromEntries(Object.entries(flags).map(([name, key]) => [`can${name.charAt(0).toUpperCase()}${name.slice(1)}`, can(set, key)]));
+}
+//#endregion
+export { permissionFlags as n, permissionMatches as r, can as t };

package/dist/plugin-AKwwe2gF.js

@@ -0,0 +1,48 @@
+//#region src/core/plugin.ts
+const PLUGIN_API_VERSION = 1;
+const RANK = {
+	first: 0,
+	pre: 1,
+	normal: 2,
+	post: 3
+};
+function rankOf(plugin) {
+	return RANK[plugin.enforce ?? "normal"];
+}
+/**
+* Plugins in hook order: `first`, `pre`, unmarked, then `post`, each level in
+* `use()` order.
+*/
+function orderPlugins(plugins) {
+	return plugins.map((plugin, index) => ({
+		plugin,
+		index
+	})).toSorted((a, b) => rankOf(a.plugin) - rankOf(b.plugin) || a.index - b.index).map(({ plugin }) => plugin);
+}
+/** Identity helper that fixes `apiVersion` and infers the plugin types. */
+function definePlugin(plugin) {
+	return {
+		...plugin,
+		apiVersion: 1
+	};
+}
+/**
+* A symbol key, so JSON, claims and spread request data can't set it, while
+* `$with` copies it to the derived context.
+*/
+const ALL_TENANTS = Symbol("better-supabase.allTenants");
+/**
+* `context`, marked so `membershipsExtension()` and tenant buckets skip their
+* tenant scope.
+*/
+function allTenantsContext(context) {
+	return {
+		...context,
+		[ALL_TENANTS]: true
+	};
+}
+function spansAllTenants(context) {
+	return Object.hasOwn(context, ALL_TENANTS);
+}
+//#endregion
+export { spansAllTenants as a, orderPlugins as i, allTenantsContext as n, definePlugin as r, PLUGIN_API_VERSION as t };

package/dist/pool-CrtT4dg-.d.ts

@@ -0,0 +1,123 @@
+import { Bt as Executor } from "./types-DFdg_4yN.js";
+import { o as EventHub } from "./events-vcqenSYU.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as SqlClient } from "./executor-hGjrop3A.js";
+//#region src/postgres/pool.d.ts
+/** The part of a `pg` pool client `createPostgres` uses. */
+interface PgPoolClient {
+  query(text: string, values?: unknown[]): Promise<{
+    rows: unknown[];
+  }>;
+  release(): void;
+}
+/** The part of a `pg.Pool` `createPostgres` uses. */
+interface PgPool {
+  connect(): Promise<PgPoolClient>;
+  end(): Promise<void>;
+  /** `pg.Pool` reports errors of idle connections here. */
+  on?(event: "error", listener: (error: Error) => void): unknown;
+}
+/** Statement timeouts in milliseconds by the role a transaction runs as. */
+interface PostgresTimeouts {
+  /**
+   * The connection-string role (`admin` and `transaction` without claims).
+   * Unset by default.
+   */
+  readonly admin?: number;
+  /** Defaults to 8000, Supabase's setting for the role. */
+  readonly authenticated?: number;
+  /** Defaults to 3000, Supabase's setting for the role. */
+  readonly anon?: number;
+}
+interface PostgresOptions {
+  /**
+   * Defaults to `$SUPABASE_DB_URL`, `$DATABASE_URL`, `$POSTGRES_URL`, then
+   * `$POSTGRES_URL_NON_POOLING`, the first one set.
+   */
+  readonly connectionString?: string;
+  /** An existing pool to run on instead of opening one. `end()` ends it. */
+  readonly pool?: PgPool;
+  readonly max?: number;
+  /**
+   * Statement timeout in milliseconds, applied per transaction: one value for
+   * every role, or one per role. `set role` doesn't apply the role's own
+   * `statement_timeout`, so `authenticated` and `anon` get Supabase's 8 s and 3
+   * s unless you set them.
+   */
+  readonly statementTimeout?: number | PostgresTimeouts;
+  /**
+   * Ends a session that stays idle inside a transaction this long, in
+   * milliseconds, so `transaction(fn)` can't hold a connection while `fn` waits
+   * on something else. Defaults to 15000; `0` turns it off. Statements outside
+   * a transaction don't set it.
+   */
+  readonly idleInTransactionTimeout?: number;
+  /** How long `connect` waits for a connection, in milliseconds. Defaults to 10000. */
+  readonly connectionTimeout?: number;
+  /** How long an unused connection stays open, in milliseconds. Defaults to 10000. */
+  readonly idleTimeout?: number;
+  /**
+   * `betterSupabase.events`: an error on an idle pooled connection arrives as
+   * an `error` event instead of crashing the process.
+   */
+  readonly events?: EventHub;
+  /**
+   * Where idle-connection errors go without `error` handlers. Defaults to the
+   * console.
+   */
+  readonly logger?: Logger;
+}
+/** JWT claims to run as. `role` must be `authenticated` or `anon`. */
+interface SqlClaims {
+  readonly sub?: string;
+  readonly role?: string;
+  readonly [claim: string]: unknown;
+}
+/** What every transaction of a user session sets besides the claims and role. */
+interface SessionOptions {
+  /**
+   * Transaction-local settings, e.g. `{ 'better_supabase.tenant': id }`. Names
+   * need a dot (custom settings); `role` and `request.jwt.claims` are set from
+   * the claims.
+   */
+  readonly settings?: Readonly<Record<string, string>>;
+  /** Runs every transaction with `begin read only`: writes fail with 25006. */
+  readonly readOnly?: boolean;
+  /**
+   * Statement timeout in milliseconds for this session's transactions, instead
+   * of the role's `statementTimeout` from `createPostgres`.
+   */
+  readonly statementTimeout?: number;
+}
+interface BetterPostgres {
+  /** Connects as the connection-string role. On Supabase that bypasses RLS. */
+  readonly admin: SqlClient;
+  /** Runs every query as the given user, with RLS, like PostgREST does. */
+  asUser(claims: SqlClaims, options?: SessionOptions): SqlClient;
+  /** Runs every query as `anon`. */
+  readonly anon: SqlClient;
+  /**
+   * Repositories' executor as the given user
+   * (`postgresExecutor(asUser(claims))`). `createServer` calls it for
+   * `ctx.sql`, so only apps that pass `postgres` bundle the SQL compiler.
+   */
+  executorFor(claims: SqlClaims, options?: SessionOptions): Executor;
+  /**
+   * Runs `fn` in one transaction. Pass claims to run it as a user; the session
+   * options apply with or without them.
+   */
+  transaction<T>(fn: (client: SqlClient) => Promise<T>, options?: {
+    readonly claims?: SqlClaims;
+  } & SessionOptions): Promise<T>;
+  end(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * A pooled Postgres connection for jobs, scripts and tests. Each query (or
+ * transaction) runs in its own transaction; claims and role are
+ * transaction-local, so nothing leaks back into the pool. An `admin` query with
+ * no timeout to set runs on its own, without `begin` and `commit`.
+ */
+declare function createPostgres(options?: PostgresOptions): BetterPostgres;
+//#endregion
+export { PostgresTimeouts as a, createPostgres as c, PostgresOptions as i, PgPool as n, SessionOptions as o, PgPoolClient as r, SqlClaims as s, BetterPostgres as t };

package/dist/pool-errors-JUBcGrre.js

@@ -0,0 +1,27 @@
+import { c as mapDbError } from "./errors-BVFgt8BZ.js";
+import { s as toDbError } from "./result-ntFBW2p2.js";
+import { t as consoleLogger } from "./logger-glM28NVN.js";
+import { n as errorEvent } from "./events-D6IZ5CE8.js";
+import { t as fromPgError } from "./pg-error-B5QLDcbG.js";
+//#region src/postgres/pool-errors.ts
+/**
+* Listens for errors on idle pooled connections, such as a server restart or an
+* ended session. `pg.Pool` emits them as an `error` event, and Node exits on an
+* `error` event nobody listens to. The listener reports the error and never
+* throws.
+*/
+function watchPoolErrors(pool, options) {
+	pool.on?.("error", (cause) => {
+		try {
+			const raw = fromPgError(cause);
+			const error = raw ? mapDbError(raw, []) : toDbError(cause);
+			if (options.events?.has("error")) {
+				options.events.emit("error", errorEvent(error));
+				return;
+			}
+			(options.logger ?? options.events?.logger ?? consoleLogger).error("an idle Postgres connection failed", { error });
+		} catch {}
+	});
+}
+//#endregion
+export { watchPoolErrors as t };