better-supabase 0.7.1 → 0.9.0

package/dist/plugin-CDLJRFFg.d.ts

@@ -0,0 +1,190 @@
+/// <reference lib="esnext.temporal" />
+import { w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { B as TableMeta, P as SchemaMeta, R as TableFlags, a as AnyModels } from "./types-YfwpIE-d.js";
+import { _ as MutationOp, g as MutationKind, h as MutationIntent, r as Executor, v as Operation } from "./executor-DoE-5iM8.js";
+//#region src/core/plugin.d.ts
+/** Who is making the request. */
+interface Actor {
+  readonly id: string;
+  readonly kind: "user" | "service" | "anon";
+  readonly role?: string;
+  readonly email?: string;
+  /** The admin acting as this user (the `act` claim's `sub`). */
+  readonly impersonator?: string;
+}
+/**
+ * Per-connection context. Server adapters fill it from the verified JWT;
+ * plugins read it (`tenant()` reads `tenant`, `actor()` reads `actor`).
+ */
+interface RequestContext {
+  readonly actor?: Actor;
+  readonly tenant?: string;
+  readonly claims?: Readonly<Record<string, unknown>>;
+  readonly [key: string]: unknown;
+}
+/** Plugin-specific per-call options (`withDeleted`, `hard`, ...). */
+type CallOptions = Readonly<Record<string, unknown>>;
+interface HookArgs {
+  readonly table: TableMeta;
+  readonly schema: SchemaMeta;
+  readonly context: RequestContext;
+  readonly options: CallOptions;
+  readonly now: () => Temporal.Instant;
+  /** The caller's `signal`, when it passed one. Hooks that do I/O should honor it. */
+  readonly signal?: AbortSignal;
+}
+interface MutationEvent {
+  readonly table: TableMeta;
+  /** The statement that ran. */
+  readonly kind: MutationKind;
+  /** What the caller asked for; differs from `kind` when a plugin rewrote the mutation. */
+  readonly intent?: MutationIntent;
+  /** App-cased rows returned by the mutation. A copy: changing it never changes the result. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * App-cased primary keys of the changed rows, when they are known: from
+   * the returned rows, or from a `where` on the primary key when nothing is
+   * returned (soft deletes, `returning: false`).
+   */
+  readonly keys?: readonly Readonly<Record<string, unknown>>[];
+  /** The tenant of the write: `context.tenant`, which `tenant()` fills from the claims. */
+  readonly tenant?: string;
+  readonly context: RequestContext;
+}
+/** Runtime handle passed to `Plugin.repository`. */
+interface RepositoryApi {
+  readonly table: TableMeta;
+  readonly base: Readonly<Record<string, (...args: never[]) => unknown>>;
+}
+/**
+ * Type-level repository extension, applied per table. Implement it as an
+ * interface that reads `this['M']` and `this['T']`:
+ *
+ * ```ts
+ * interface RestoreExtension extends RepositoryExtension {
+ *   readonly methods: HasFlag<this['M'], this['T'], 'softDelete'> extends true
+ *     ? { restore(id: string): AsyncResult<unknown> }
+ *     : unknown;
+ * }
+ * ```
+ */
+interface RepositoryExtension {
+  readonly M: AnyModels;
+  readonly T: string;
+  readonly methods: unknown;
+  readonly findArgs: unknown;
+  readonly deleteArgs: unknown;
+}
+/**
+ * Applies the extensions in `E` to table `T`. `E` is a tuple of extensions (as
+ * built by `use()`) or a single extension. Each is applied on its own because
+ * indexing an intersection of `this`-typed interfaces overflows TS < 7.
+ */
+/** Default extension of plugins that add no repository types. */
+interface NoExtension extends RepositoryExtension {
+  readonly "~none": true;
+}
+type ApplyExtension<E, M extends AnyModels, T extends keyof M, K extends "methods" | "findArgs" | "deleteArgs"> = E extends readonly [infer Head, ...infer Rest] ? ApplyOne<Head, M, T, K> & ApplyExtension<Rest, M, T, K> : ApplyOne<E, M, T, K>;
+type ApplyOne<E, M extends AnyModels, T extends keyof M, K extends "methods" | "findArgs" | "deleteArgs"> = E extends RepositoryExtension ? (E & {
+  readonly M: M;
+  readonly T: T;
+})[K] : unknown;
+/** True when table `T` has the flag set by codegen. */
+type HasFlag<M, T, F extends string> = M extends AnyModels ? T extends keyof M ? M[T]["Flags"] extends { readonly [K in F]: unknown; } ? true : false : false : false;
+/** A parameter a plugin adds to the operations of a table in the API spec. */
+interface DescribeParameter {
+  readonly name: string;
+  readonly in: "query" | "header" | "cookie";
+  readonly required?: boolean;
+  readonly description?: string;
+  /** JSON Schema 2020-12. */
+  readonly schema: Readonly<Record<string, unknown>>;
+}
+/**
+ * What `Plugin.describe` can change in the API model `defineApi` builds.
+ * Every method ignores tables and columns the API does not serve.
+ */
+interface PluginDescribeApi {
+  readonly schema: SchemaMeta;
+  /** Prefix of generated `x-` fields, e.g. `x-better-supabase-`. */
+  readonly extensionPrefix: string;
+  /** The served tables, with the names of their operations and actions. */
+  readonly resources: readonly {
+    readonly table: TableMeta;
+    readonly operations: readonly string[];
+  }[];
+  /** Adds a parameter to the table's operations, or to the named ones. */
+  addParameter(table: string, parameter: DescribeParameter, operations?: readonly string[]): void;
+  /**
+   * Marks a column `readOnly` in the table's schemas and drops it from the
+   * required fields of request bodies. `description` is used when the
+   * column has none.
+   */
+  markReadOnly(table: string, column: string, description?: string): void;
+  /** Deep-merges JSON Schema fields into the column's schemas. */
+  describeColumn(table: string, column: string, patch: Readonly<Record<string, unknown>>): void;
+}
+declare const PLUGIN_API_VERSION = 1;
+/**
+ * Plugin API v1. Every hook is optional. Hooks run in `use()` order.
+ */
+interface Plugin<Name extends string = string, Ext extends RepositoryExtension = NoExtension> {
+  readonly apiVersion: 1;
+  readonly name: Name;
+  /**
+   * Hook order: `first`, then `pre`, then unmarked plugins, then `post`;
+   * plugins at the same level keep `use()` order. `first` is for plugins
+   * that check the query as the caller wrote it, before a `pre` plugin
+   * rewrites it (`rules()`). Validation is `post` so it sees columns other
+   * plugins fill.
+   */
+  readonly enforce?: "first" | "pre" | "post";
+  /**
+   * The table flags whose tables this plugin's `transformQuery` filters
+   * (`tenant()` declares `['tenant']`). Read sets warn when they read such a
+   * table, because their generated SQL function runs without the plugin.
+   * `[]` means the plugin only inspects queries. A plugin with
+   * `transformQuery` that leaves this out is assumed to filter every table.
+   */
+  readonly scopes?: readonly (keyof TableFlags)[];
+  /**
+   * `context`: derive values from the connection's context once per
+   * `connect()` and `$with()`, so `db.$context` carries them (`tenant()`
+   * adds the tenant it resolved). Runs in hook order on the context the
+   * caller passed. A throw is logged and leaves the context unchanged.
+   */
+  readonly context?: (context: RequestContext, args: {
+    readonly schema: SchemaMeta;
+  }) => RequestContext;
+  /** `ir`: rewrite an operation before it runs (filters, defaults). */
+  readonly transformQuery?: (op: Operation, args: HookArgs) => Operation;
+  /** `mutation`: rewrite a mutation or reject it by throwing a `DbException`. */
+  readonly beforeMutation?: (op: MutationOp, args: HookArgs) => MutationOp | Promise<MutationOp>;
+  /** `mutation`: observe a finished mutation. Cannot change the result. */
+  readonly afterMutation?: (event: MutationEvent) => void | Promise<void>;
+  /** `execute`: wrap the executor for tracing, caching or retries. */
+  readonly wrapExecutor?: (executor: Executor) => Executor;
+  /** `errors`: map custom SQLSTATE or hint codes to `DbError`s. */
+  readonly mapError?: ErrorMapper;
+  /** `repository`: add methods to the repositories of matching tables. */
+  readonly repository?: (api: RepositoryApi) => Readonly<Record<string, (...args: never[]) => unknown>> | undefined;
+  /**
+   * `spec`: describe what the plugin does to the served tables in the API
+   * model (`defineApi`, `createOpenApi`): parameters it reads, columns it
+   * manages. A throw is reported as `plugin-describe-failed`.
+   */
+  readonly describe?: (api: PluginDescribeApi) => void;
+  /** Phantom carrying the repository extension type. */
+  readonly "~ext"?: Ext;
+}
+type AnyPlugin = Plugin<string, any>;
+/** The plugin's repository extension; `unknown` for plugins that add none. */
+type ExtensionOf<P> = P extends Plugin<string, infer E> ? E extends NoExtension ? unknown : E : never;
+/** `E` with extension `X` appended, as a tuple. */
+type WithExtension<E, X> = unknown extends X ? E : E extends readonly unknown[] ? readonly [...E, X] : unknown extends E ? readonly [X] : readonly [E, X];
+/** Identity helper that fixes `apiVersion` and infers the plugin types. */
+declare function definePlugin<const Name extends string, Ext extends RepositoryExtension = NoExtension>(plugin: Omit<Plugin<Name, Ext>, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): Plugin<Name, Ext>;
+//#endregion
+export { ExtensionOf as a, MutationEvent as c, Plugin as d, RepositoryApi as f, definePlugin as g, WithExtension as h, CallOptions as i, NoExtension as l, RequestContext as m, AnyPlugin as n, HasFlag as o, RepositoryExtension as p, ApplyExtension as r, HookArgs as s, Actor as t, PLUGIN_API_VERSION as u };

package/dist/plugins/actor/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Plugin, m as RequestContext } from "../../plugin-FGY8UhYm.js";
+import { d as Plugin, m as RequestContext } from "../../plugin-CDLJRFFg.js";
 //#region src/plugins/actor/index.d.ts
 export interface ActorOptions {
   /** Custom actor id resolution. Defaults to `context.actor.id` for users and services. */

package/dist/plugins/actor/index.js

@@ -1,5 +1,5 @@
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { a as insertsOnly, i as guardManaged, t as dbName, u as withDefault } from "../../shared-CxWmcyqB.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-as0EG51f.js";
 //#region src/plugins/actor/index.ts
 function defaultActor(context) {
 	const actor = context.actor;

package/dist/plugins/rules/index.d.ts

@@ -1,5 +1,5 @@
-import { v as Operation } from "../../executor-DvsBbNBS.js";
-import { d as Plugin, p as RepositoryExtension } from "../../plugin-FGY8UhYm.js";
+import { v as Operation } from "../../executor-DoE-5iM8.js";
+import { d as Plugin, p as RepositoryExtension } from "../../plugin-CDLJRFFg.js";
 //#region src/plugins/rules/index.d.ts
 export type RuleLevel = "off" | "warn" | "error";
 /** A level, or a level with the rule's option: `['error', 500]`. */

package/dist/plugins/rules/index.js

@@ -1,5 +1,5 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-B11Duf73.js";
+import { n as dbError } from "../../errors-8i6tSICm.js";
 import { t as lookupOf } from "../../lookup-BaP5bI27.js";
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
 import { t as simplify } from "../../simplify-DDO0j0LI.js";
@@ -109,7 +109,7 @@ function urlColumns(table) {
 }
 function storedObjectColumn(op, schema) {
 	const rows = op.kind === "insert" ? op.rows : op.kind === "update" ? [op.set] : [];
-	if (rows.length === 0) return void 0;
+	if (rows.length === 0) return;
 	for (const column of urlColumns(op.table)) {
 		if (!rows.some((row) => column.db in row)) continue;
 		const path = `${column.db.slice(0, -4)}_path`;

package/dist/plugins/soft-delete/index.d.ts

@@ -1,6 +1,6 @@
-import { t as AsyncResult } from "../../result-D7y2fT87.js";
-import { E as PrimaryKeyValue } from "../../types-6BdhkmZe.js";
-import { d as Plugin, o as HasFlag, p as RepositoryExtension } from "../../plugin-FGY8UhYm.js";
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { E as PrimaryKeyValue } from "../../types-YfwpIE-d.js";
+import { d as Plugin, o as HasFlag, p as RepositoryExtension } from "../../plugin-CDLJRFFg.js";
 //#region src/plugins/soft-delete/index.d.ts
 export interface SoftDeleteFindArgs {
   /** Include soft-deleted rows of the queried table. */

package/dist/plugins/soft-delete/index.js

@@ -1,8 +1,8 @@
-import { t as and } from "../../types-6cYK9pbJ.js";
-import { a as ok, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { t as and } from "../../types-R6syp1el.js";
+import { a as ok, t as AsyncResult } from "../../result-BlgnMB0H.js";
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { n as scopeOperation } from "../../scope-CDHcS7dE.js";
-import { a as insertsOnly, i as guardManaged, o as isNotNull, s as isNull, t as dbName, u as withDefault } from "../../shared-CxWmcyqB.js";
+import { n as scopeOperation } from "../../scope-DgWjuXUw.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, o as isNotNull, s as isNull, t as dbName } from "../../shared-as0EG51f.js";
 //#region src/plugins/soft-delete/index.ts
 function deletedColumn(table) {
 	return dbName(table, table.flags.softDelete);
@@ -28,6 +28,13 @@ function softDelete() {
 		name: "softDelete",
 		enforce: "pre",
 		scopes: ["softDelete"],
+		describe(api) {
+			for (const { table } of api.resources) {
+				const flag = table.flags.softDelete;
+				if (!flag) continue;
+				api.markReadOnly(table.key, flag, "Set when the row is deleted. Deleted rows are not returned, and delete sets this column instead of removing the row.");
+			}
+		},
 		transformQuery(op, { options }) {
 			const hardDelete = op.kind === "delete" && options["hard"] === true;
 			const withDeleted = options["withDeleted"] === true || hardDelete;

package/dist/plugins/tenant/index.d.ts

@@ -1,5 +1,5 @@
-import { P as SchemaMeta } from "../../types-6BdhkmZe.js";
-import { d as Plugin, m as RequestContext, o as HasFlag, p as RepositoryExtension } from "../../plugin-FGY8UhYm.js";
+import { P as SchemaMeta } from "../../types-YfwpIE-d.js";
+import { d as Plugin, m as RequestContext, o as HasFlag, p as RepositoryExtension } from "../../plugin-CDLJRFFg.js";
 //#region src/plugins/tenant/index.d.ts
 /**
  * Dotted paths to the string claims of `C` (up to three levels), e.g.
@@ -23,6 +23,11 @@ export interface TenantOptions<C = unknown> {
    * `error` (default) fails with `forbidden`; `skip` leaves it to RLS.
    */
   readonly onMissing?: "error" | "skip";
+  /**
+   * The request header `resolve` reads the tenant from. The plugin does not
+   * read it; `defineApi` documents it as a parameter of tenant tables.
+   */
+  readonly header?: string;
 }
 export interface TenantFindArgs {
   /** Skip the tenant filter for this call (admin tooling, jobs). RLS still applies. */
@@ -46,4 +51,5 @@ export declare function resolveTenant<C = unknown>(context: RequestContext, opti
  * it.
  */
 export declare function tenant<C = unknown>(options?: TenantOptions<C>): Plugin<"tenant", TenantExtension>;
-//#endregion
+//#endregion
+export {};

package/dist/plugins/tenant/index.js

@@ -1,9 +1,9 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-B11Duf73.js";
+import { n as dbError } from "../../errors-8i6tSICm.js";
 import { a as spansAllTenants, r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { n as scopeOperation } from "../../scope-CDHcS7dE.js";
+import { n as scopeOperation } from "../../scope-DgWjuXUw.js";
 import { o as tenantFrom, s as tenantPathsFor } from "../../claims-PqzCxaTD.js";
-import { a as insertsOnly, n as equals, r as forbidden, t as dbName } from "../../shared-CxWmcyqB.js";
+import { a as insertsOnly, n as equals, r as forbidden, t as dbName } from "../../shared-as0EG51f.js";
 //#region src/plugins/tenant/index.ts
 /**
 * The tenant for a request: `context.tenant`, then the configured claim.
@@ -52,6 +52,20 @@ function tenant(options = {}) {
 	return definePlugin({
 		name: "tenant",
 		scopes: ["tenant"],
+		describe(api) {
+			for (const { table } of api.resources) {
+				const flag = table.flags.tenant;
+				if (!flag) continue;
+				api.markReadOnly(table.key, flag, "Set from the request's tenant.");
+				if (options.header) api.addParameter(table.key, {
+					name: options.header,
+					in: "header",
+					required: onMissing === "error",
+					description: "The tenant the request acts for.",
+					schema: { type: "string" }
+				});
+			}
+		},
 		context(context, { schema }) {
 			if (spansAllTenants(context)) return context;
 			const id = resolvedFor(context, schema);

package/dist/plugins/timestamps/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Plugin } from "../../plugin-FGY8UhYm.js";
+import { d as Plugin } from "../../plugin-CDLJRFFg.js";
 //#region src/plugins/timestamps/index.d.ts
 /**
  * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,

package/dist/plugins/timestamps/index.js

@@ -1,5 +1,5 @@
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { a as insertsOnly, i as guardManaged, t as dbName, u as withDefault } from "../../shared-CxWmcyqB.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-as0EG51f.js";
 //#region src/plugins/timestamps/index.ts
 /**
 * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,
@@ -11,6 +11,13 @@ import { a as insertsOnly, i as guardManaged, t as dbName, u as withDefault } fr
 function timestamps() {
 	return definePlugin({
 		name: "timestamps",
+		describe(api) {
+			for (const { table } of api.resources) {
+				const flags = table.flags.timestamps;
+				if (flags?.createdAt) api.markReadOnly(table.key, flags.createdAt, "Set by the server when the row is created.");
+				if (flags?.updatedAt) api.markReadOnly(table.key, flags.updatedAt, "Set by the server on every write.");
+			}
+		},
 		beforeMutation(op, { table, now, options }) {
 			const flags = table.flags.timestamps;
 			if (!flags) return op;

package/dist/plugins/validation/index.d.ts

@@ -1,5 +1,5 @@
-import { d as Plugin } from "../../plugin-FGY8UhYm.js";
-import { t as StandardSchemaV1 } from "../../standard-CYsm7xpT.js";
+import { d as Plugin } from "../../plugin-CDLJRFFg.js";
+import { t as StandardSchemaV1 } from "../../standard-C3_AAF3g.js";
 //#region src/plugins/validation/index.d.ts
 export interface TableValidators {
   /** Validates inserts and upserts, with app-cased keys. */

package/dist/plugins/validation/index.js

@@ -1,9 +1,9 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-B11Duf73.js";
-import { i as encodeValue, r as decodeValue } from "../../wire-DtZQ4sdE.js";
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { i as encodeValue, r as decodeValue } from "../../wire-DEY0ajW9.js";
 import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { n as validate } from "../../standard-BK0cqJ7y.js";
-import { c as toApp, l as toDb } from "../../shared-CxWmcyqB.js";
+import { n as validate } from "../../standard-B5fe2gnW.js";
+import { n as toDb, t as toApp } from "../../casing-DdFWEtqr.js";
 //#region src/plugins/validation/index.ts
 /**
 * Rows reach plugins in wire form (ISO text, decimal text), while generated

package/dist/pool-CwOCsX9e.d.ts

@@ -0,0 +1,114 @@
+import { r as Executor } from "./executor-DoE-5iM8.js";
+import { o as EventHub } from "./events-CTreRrgP.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as SqlClient } from "./executor-BBHgjUJu.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`, then `$DATABASE_URL`. */
+  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-GMjlCN0d.js

@@ -0,0 +1,27 @@
+import { c as mapDbError } from "./errors-8i6tSICm.js";
+import { s as toDbError } from "./result-BlgnMB0H.js";
+import { t as consoleLogger } from "./logger-glM28NVN.js";
+import { n as errorEvent } from "./events-xbpHkcK9.js";
+import { t as fromPgError } from "./pg-error-BV_X8Isq.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 };