better-supabase 0.3.0 → 0.5.0

package/dist/events-aIO7vsIk.d.ts

@@ -0,0 +1,230 @@
+/// <reference lib="esnext.temporal" />
+import { U as Operation, _ as DbError } from "./executor-BunPOO-k.js";
+import { g as RequestContext, l as MutationIntent, u as MutationKind } from "./plugin-o144f322.js";
+//#region src/core/logger.d.ts
+type LogFields = Readonly<Record<string, unknown>>;
+/**
+ * Where better-supabase reports problems it swallows on purpose: event
+ * handlers, `afterMutation` hooks, sinks and cache adapters that throw.
+ * Structured loggers (pino, consola, OpenTelemetry logs) fit directly.
+ */
+interface Logger {
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+}
+/** The default: `console`, with a `better-supabase:` prefix. */
+declare const consoleLogger: Logger;
+declare const silentLogger: Logger;
+//#endregion
+//#region src/core/kit-events.d.ts
+/** `support.*`: support sessions, where a platform admin views the app as a user. */
+interface SupportEventData {
+  /** Absent on `support.denied`. */
+  readonly sessionId?: string;
+  readonly adminId: string;
+  readonly targetUserId: string;
+  readonly reason?: string;
+  readonly readOnly?: boolean;
+  readonly expiresAt?: Temporal.Instant;
+  /** `support.denied`: which check refused it. */
+  readonly denial?: "authorize" | "permission" | "policy" | "store";
+  /** `support.ended`: who or what ended it. */
+  readonly endedBy?: "admin" | "expired" | "revoked";
+}
+/** `org.*`: organizations and their members. */
+interface OrgEventData {
+  readonly organizationId: string;
+  /** The member the event is about. */
+  readonly userId?: string;
+  readonly role?: string;
+  readonly previousRole?: string;
+}
+/** `invitation.*`. The token is never part of the event. */
+interface InvitationEventData {
+  readonly invitationId: string;
+  /** Absent for a platform-scope invitation. */
+  readonly organizationId?: string;
+  readonly email?: string;
+  readonly role?: string;
+}
+/** `notification.*`. */
+interface NotificationEventData {
+  readonly notificationId: string;
+  readonly type: string;
+  readonly recipientIds?: readonly string[];
+  readonly channel?: string;
+  readonly error?: string;
+}
+/** `webhook.*`: outgoing webhooks. */
+interface WebhookEventData {
+  readonly endpointId: string;
+  readonly deliveryId?: string;
+  readonly eventType?: string;
+  /** The HTTP status of the attempt, when there was a response. */
+  readonly status?: number;
+  readonly attempt?: number;
+  readonly error?: string;
+}
+/** Every kit event type and its data. */
+interface KitEventMap {
+  "support.started": SupportEventData;
+  "support.ended": SupportEventData;
+  "support.denied": SupportEventData;
+  "org.created": OrgEventData;
+  "org.updated": OrgEventData;
+  "org.deleted": OrgEventData;
+  "org.member_added": OrgEventData;
+  "org.member_removed": OrgEventData;
+  "org.member_left": OrgEventData;
+  "org.role_changed": OrgEventData;
+  "org.ownership_transferred": OrgEventData;
+  "org.switched": OrgEventData;
+  "invitation.created": InvitationEventData;
+  "invitation.resent": InvitationEventData;
+  "invitation.accepted": InvitationEventData;
+  "invitation.declined": InvitationEventData;
+  "invitation.revoked": InvitationEventData;
+  "notification.created": NotificationEventData;
+  "notification.delivered": NotificationEventData;
+  "notification.failed": NotificationEventData;
+  "webhook.delivered": WebhookEventData;
+  "webhook.failed": WebhookEventData;
+  "webhook.disabled": WebhookEventData;
+}
+type KitEventType = keyof KitEventMap;
+/** Where an event came from, beyond its data. */
+interface KitEventMeta {
+  /** e.g. `organizations/<id>`; becomes the CloudEvents `subject`. */
+  readonly subject?: string;
+  readonly tenant?: string;
+  /** The user who caused it. */
+  readonly actorId?: string;
+  readonly context?: RequestContext;
+}
+/** A kit event as `betterSupabase.on('kit', handler)` receives it. */
+type KitEvent<K extends KitEventType = KitEventType> = { readonly [T in K]: KitEventMeta & {
+  readonly type: T;
+  /** A copy: changing it never changes what the kit does (invariant 5). */
+  readonly data: KitEventMap[T];
+  readonly time: Temporal.Instant;
+}; }[K];
+/** A type, or a `prefix.*` pattern such as `support.*`. */
+type KitEventPattern = KitEventType | `${KitEventType extends `${infer P}.${string}` ? P : never}.*`;
+/** The event types a pattern matches. */
+type KitEventsMatching<P extends KitEventPattern> = P extends `${infer Prefix}.*` ? Extract<KitEventType, `${Prefix}.${string}`> : Extract<P, KitEventType>;
+/**
+ * Fixed OpenTelemetry attribute names for kit work, so dashboards and
+ * queries can rely on them.
+ */
+declare const KIT_ATTRIBUTES: {
+  readonly event: "better_supabase.kit.event";
+  readonly tenant: "better_supabase.tenant";
+  readonly actor: "better_supabase.actor.id";
+  readonly supportSessionId: "better_supabase.support.session_id";
+  readonly orgId: "better_supabase.org.id";
+  readonly invitationId: "better_supabase.invitation.id";
+  readonly notificationType: "better_supabase.notification.type";
+  readonly webhookEndpointId: "better_supabase.webhook.endpoint_id";
+};
+/** The `KIT_ATTRIBUTES` an event carries. */
+declare function kitEventAttributes(event: KitEvent): Record<string, string>;
+/**
+ * Listens to the kit events that match `pattern` (`'support.started'` or
+ * `'support.*'`). Returns a function that stops listening.
+ */
+declare function onKitEvent<P extends KitEventPattern>(betterSupabase: {
+  readonly events: EventHub;
+}, pattern: P, handler: (event: KitEvent<KitEventsMatching<P>>) => void): () => void;
+//#endregion
+//#region src/core/events.d.ts
+interface QueryEvent {
+  readonly table: string;
+  readonly operation: Operation["kind"];
+  readonly ok: boolean;
+  readonly durationMs: number;
+  readonly rows: number;
+  /**
+   * An unbounded read returned `maxRows` rows: PostgREST's `db-max-rows`
+   * probably cut it short. Add `limit` or use `paginate`.
+   */
+  readonly truncated: boolean;
+}
+interface MutationNotice {
+  readonly table: string;
+  readonly kind: MutationKind;
+  /** See `MutationEvent.intent`. */
+  readonly intent?: MutationIntent;
+  /** A copy of the returned rows: changing it never changes the result. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  /** See `MutationEvent.keys`. */
+  readonly keys?: readonly Readonly<Record<string, unknown>>[];
+  /** See `MutationEvent.tenant`. */
+  readonly tenant?: string;
+  readonly context: RequestContext;
+}
+/** A successful RPC registered with `betterSupabase.defineRpc(name, { invalidates })`. */
+interface RpcNotice {
+  readonly name: string;
+  /** App keys of the tables the function changes. */
+  readonly invalidates: readonly string[];
+  readonly context: RequestContext;
+}
+interface ErrorEvent {
+  readonly table?: string;
+  readonly error: DbError;
+}
+interface AuthEvent {
+  readonly source: "bearer" | "cookie" | "none";
+  readonly ok: boolean;
+  readonly userId?: string;
+  /**
+   * Why there is no user: the anon reason (`expired`, `signed_out`, ...) or
+   * the invalid reason (`token`, `claims`, `actor`).
+   */
+  readonly reason?: "none" | "expired" | "signed_out" | "refresh_failed" | "token" | "claims" | "actor";
+  /** The user's `source` as the resolver set it, e.g. a custom resolver's name. */
+  readonly rawSource?: string;
+}
+interface RefreshEvent {
+  readonly ok: boolean;
+  readonly shared: boolean;
+  readonly durationMs: number;
+}
+interface BetterSupabaseEvents {
+  query: QueryEvent;
+  mutation: MutationNotice;
+  rpc: RpcNotice;
+  error: ErrorEvent;
+  auth: AuthEvent;
+  refresh: RefreshEvent;
+  /** Support sessions, organizations, invitations, notifications and webhooks. */
+  kit: KitEvent;
+}
+type EventName = keyof BetterSupabaseEvents;
+type EventHandler<K extends EventName> = (event: BetterSupabaseEvents[K]) => void;
+/**
+ * Observers only: a handler that throws is reported to the logger and never
+ * changes a result.
+ */
+declare class EventHub {
+  #private;
+  readonly logger: Logger;
+  constructor(logger?: Logger);
+  on<K extends EventName>(name: K, handler: EventHandler<K>): () => void;
+  has(name: EventName): boolean;
+  /**
+   * Keeps async work a handler started (a sink send) until it settles, so
+   * adapters can hand it to `after()` or `waitUntil`. Its outcome is ignored:
+   * handlers report their own failures.
+   */
+  track(work: PromiseLike<unknown>): void;
+  /** Whether tracked work is still running. */
+  get pending(): boolean;
+  /** Resolves once the work tracked so far has settled. Never rejects. */
+  settled(): Promise<void>;
+  emit<K extends EventName>(name: K, event: BetterSupabaseEvents[K]): void;
+}
+//#endregion
+export { kitEventAttributes as C, consoleLogger as D, Logger as E, silentLogger as O, WebhookEventData as S, LogFields as T, KitEventType as _, EventHub as a, OrgEventData as b, QueryEvent as c, InvitationEventData as d, KIT_ATTRIBUTES as f, KitEventPattern as g, KitEventMeta as h, EventHandler as i, RefreshEvent as l, KitEventMap as m, BetterSupabaseEvents as n, EventName as o, KitEvent as p, ErrorEvent as r, MutationNotice as s, AuthEvent as t, RpcNotice as u, KitEventsMatching as v, onKitEvent as w, SupportEventData as x, NotificationEventData as y };

package/dist/executor-BunPOO-k.d.ts

@@ -0,0 +1,402 @@
+import { E as RelationMeta, F as TableMeta, l as Codec } from "./types-Dnf_wRDz.js";
+//#region src/ir/types.d.ts
+/**
+ * The query IR. Every repository call becomes one of these operations; the
+ * executor compiles it to PostgREST or SQL. Column names in the IR are
+ * database names; `Selection` carries the app aliases.
+ */
+type ColumnOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "is" | "like" | "ilike" | "contains" | "containedBy" | "overlaps" | "fts";
+type Quantifier = "some" | "none" | "every";
+type Condition = {
+  readonly kind: "and";
+  readonly items: readonly Condition[];
+} | {
+  readonly kind: "or";
+  readonly items: readonly Condition[];
+} | {
+  readonly kind: "not";
+  readonly item: Condition;
+} | {
+  readonly kind: "column";
+  readonly column: string;
+  readonly op: ColumnOp;
+  readonly value: unknown;
+  /** Full-text search configuration for `fts`. */
+  readonly config?: string;
+} | {
+  readonly kind: "relation";
+  readonly name: string;
+  readonly relation: RelationMeta;
+  readonly target: TableMeta;
+  readonly quantifier: Quantifier;
+  readonly where: Condition | undefined;
+};
+interface SelectColumn {
+  /** Key in the returned row. */
+  readonly alias: string;
+  /** Database column name. */
+  readonly column: string;
+  /** Read the column as text, so exact `int8`/`numeric` values survive JSON. */
+  readonly cast?: "text";
+  /** Decodes the returned value (see `ColumnMeta.codec`). */
+  readonly codec?: Codec;
+}
+interface OrderTerm {
+  readonly column: string;
+  readonly direction: "asc" | "desc";
+  readonly nulls?: "first" | "last";
+}
+interface Include {
+  readonly alias: string;
+  readonly relation: RelationMeta;
+  readonly target: TableMeta;
+  readonly selection: Selection;
+  readonly where: Condition | undefined;
+  readonly orderBy: readonly OrderTerm[];
+  readonly limit: number | undefined;
+  /** Drop parent rows without a match (`!inner`). */
+  readonly required: boolean;
+  /**
+   * `_count` include: returns the number of matching related rows instead of
+   * rows, folded into `row._count[count]` when decoded.
+   */
+  readonly count?: string;
+  /**
+   * `_sum`/`_avg`/`_min`/`_max` include: `selection.aggregate` holds the
+   * measures, folded into `row[`_${fn}`][name]` when decoded.
+   */
+  readonly aggregate?: {
+    readonly fn: AggregateFn;
+    readonly name: string;
+  };
+}
+type AggregateFn = "sum" | "avg" | "min" | "max";
+interface Measure {
+  readonly fn: AggregateFn;
+  /** Key in the returned row (`_sum_amount`, or the column alias in an include). */
+  readonly key: string;
+  /** App column name, the key under `_sum` in the decoded row. */
+  readonly alias: string;
+  /** Database column name. */
+  readonly column: string;
+  /** Read the result as text, so exact `int8`/`numeric` values survive JSON. */
+  readonly cast?: "text";
+  readonly codec?: Codec;
+}
+/**
+ * Aggregates instead of rows. `Selection.columns` become the grouping
+ * columns; without any, the result is exactly one row.
+ */
+interface Aggregation {
+  /** Also return `_count`, the number of rows in each group. */
+  readonly count: boolean;
+  readonly measures: readonly Measure[];
+}
+interface Selection {
+  readonly columns: readonly SelectColumn[];
+  readonly includes: readonly Include[];
+  readonly aggregate?: Aggregation;
+}
+type CountMode = "exact" | "planned" | "estimated";
+interface SelectOp {
+  readonly kind: "select";
+  readonly table: TableMeta;
+  readonly selection: Selection;
+  readonly where: Condition | undefined;
+  readonly orderBy: readonly OrderTerm[];
+  readonly limit: number | undefined;
+  readonly offset: number | undefined;
+  readonly count: CountMode | undefined;
+  /** Only count, return no rows. */
+  readonly head: boolean;
+  readonly single: "one" | "maybe" | undefined;
+  /** `limit` includes one row past the page, which `paginate()` reads to set `hasMore`. */
+  readonly lookAhead?: boolean;
+  /**
+   * Read from this set-returning function instead of the table (`db.$search`).
+   * Only executors with `functionSources` honor it.
+   */
+  readonly source?: FunctionSource;
+}
+/** A function returning `setof <table>`, called with named arguments. */
+interface FunctionSource {
+  readonly schema: string;
+  readonly name: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+interface InsertOp {
+  readonly kind: "insert";
+  readonly table: TableMeta;
+  /** Rows keyed by database column names. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly returning: Selection | undefined;
+  readonly onConflict: {
+    readonly columns: readonly string[];
+    readonly action: "update" | "ignore";
+  } | undefined;
+  /** Missing columns become `null` instead of their default in bulk inserts. */
+  readonly defaultToNull: boolean;
+}
+interface UpdateOp {
+  readonly kind: "update";
+  readonly table: TableMeta;
+  /** Keyed by database column names. */
+  readonly set: Readonly<Record<string, unknown>>;
+  readonly where: Condition | undefined;
+  readonly returning: Selection | undefined;
+}
+interface DeleteOp {
+  readonly kind: "delete";
+  readonly table: TableMeta;
+  readonly where: Condition | undefined;
+  readonly returning: Selection | undefined;
+}
+type Operation = SelectOp | InsertOp | UpdateOp | DeleteOp;
+type MutationOp = InsertOp | UpdateOp | DeleteOp;
+declare const and: (...items: (Condition | undefined)[]) => Condition | undefined;
+declare const or: (...items: Condition[]) => Condition;
+declare const not: (item: Condition) => Condition;
+declare const column: (name: string, op: ColumnOp, value: unknown) => Condition;
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * Extra fields carried by each error kind. Plugins can add kinds through the
+ * `errors` extension point; apps that want the new kinds in the union can add
+ * them to this interface.
+ */
+interface DbErrorKinds {
+  not_found: Record<never, never>;
+  unauthorized: Record<never, never>;
+  /**
+   * `required`: the assurance level the route needs, when a second factor is
+   * missing. `scopes`: the OAuth scopes the route needs, when a delegated
+   * token lacks one (`INSUFFICIENT_SCOPE`).
+   */
+  forbidden: {
+    required?: "aal1" | "aal2";
+    scopes?: readonly string[];
+  };
+  conflict: {
+    constraint?: string;
+    columns?: readonly string[];
+  };
+  foreign_key: {
+    constraint?: string;
+    columns?: readonly string[];
+  };
+  check: {
+    constraint?: string;
+  };
+  not_null: {
+    column?: string;
+  };
+  exclusion: {
+    constraint?: string;
+  };
+  invalid_input: Record<never, never>;
+  /** A stored value the app type can't hold, e.g. `infinity` for a Temporal timestamp. */
+  invalid_value: {
+    column?: string;
+  };
+  raised: Record<never, never>;
+  timeout: Record<never, never>;
+  serialization: Record<never, never>;
+  network: Record<never, never>;
+  aborted: Record<never, never>;
+  invalid_request: Record<never, never>;
+  validation: {
+    issues: readonly ValidationIssue[];
+  };
+  multiple_rows: Record<never, never>;
+  stale: Record<never, never>;
+  /** `retryAfter`: seconds until the window resets (the `Retry-After` header). */
+  rate_limited: {
+    retryAfter?: number;
+  };
+  unexpected: Record<never, never>;
+}
+type DbErrorKind = keyof DbErrorKinds;
+interface ValidationIssue {
+  readonly message: string;
+  readonly path?: readonly PropertyKey[];
+}
+interface DbErrorBase<K extends DbErrorKind> {
+  readonly kind: K;
+  readonly message: string;
+  /** SQLSTATE or PostgREST code (`23505`, `PGRST116`), when known. */
+  readonly code?: string;
+  /** Suggested HTTP status, used by the RFC 9457 mapping. */
+  readonly status: number;
+  readonly details?: string;
+  /** Postgres `HINT`. `raised` errors use it as an app-level error code. */
+  readonly hint?: string;
+  /** App-cased table key the operation ran against. */
+  readonly table?: string;
+}
+/**
+ * A database error as plain, serializable data. Safe to send across server
+ * action and RPC boundaries.
+ */
+type DbError = { [K in DbErrorKind]: DbErrorBase<K> & DbErrorKinds[K]; }[DbErrorKind];
+type DbErrorOf<K extends DbErrorKind> = Extract<DbError, {
+  kind: K;
+}>;
+declare function statusOf(kind: DbErrorKind): number;
+type ExtraOf<K extends DbErrorKind> = Record<never, never> extends DbErrorKinds[K] ? [extra?: DbErrorKinds[K] & Partial<Omit<DbErrorBase<K>, "kind">>] : [extra: DbErrorKinds[K] & Partial<Omit<DbErrorBase<K>, "kind">>];
+/** Creates a `DbError` with the default status for its kind. */
+declare function dbError<K extends DbErrorKind>(kind: K, message: string, ...[extra]: ExtraOf<K>): DbErrorOf<K>;
+declare function isDbError(value: unknown): value is DbError;
+/**
+ * A unique violation, optionally for one constraint. Accepts a `DbError` or a
+ * `DbException`. Pass the generated `UniqueConstraint` type to check names:
+ * `isConflict<UniqueConstraint>(error, 'customers_organization_id_kvk_key')`.
+ */
+declare const isConflict: <C extends string = string>(error: unknown, constraint?: NoInfer<C>) => error is DbErrorOf<"conflict"> & {
+  readonly constraint: C;
+};
+/** A CHECK violation, optionally for one constraint (`CheckConstraint`). */
+declare const isCheck: <C extends string = string>(error: unknown, constraint?: NoInfer<C>) => error is DbErrorOf<"check"> & {
+  readonly constraint: C;
+};
+/** A foreign key violation, optionally for one constraint (`ForeignKeyConstraint`). */
+declare const isForeignKey: <C extends string = string>(error: unknown, constraint?: NoInfer<C>) => error is DbErrorOf<"foreign_key"> & {
+  readonly constraint: C;
+};
+/** Thrown by `.orThrow()`. Carries the plain `DbError` as `error`. */
+declare class DbException extends Error {
+  override readonly name = "DbException";
+  readonly error: DbError;
+  constructor(error: DbError);
+  get kind(): DbErrorKind;
+}
+/** Raw error shape shared by PostgREST responses and `pg` errors. */
+interface RawDbError {
+  readonly message?: string;
+  readonly code?: string;
+  readonly details?: string | null;
+  readonly hint?: string | null;
+  readonly constraint?: string;
+  readonly column?: string;
+  readonly table?: string;
+  readonly name?: string;
+}
+type ErrorMapper = (raw: RawDbError, fallback: DbError) => DbError | undefined;
+/**
+ * Maps a PostgREST or Postgres error to a `DbError`. Custom mappers run
+ * first; the first one that returns an error wins.
+ */
+declare function mapDbError(raw: RawDbError, mappers?: readonly ErrorMapper[]): DbError;
+//#endregion
+//#region src/core/result.d.ts
+/** Turns a `DbError` into the error `.orThrow()` throws; set with `betterSupabase.mapError()`. */
+type ThrowMapper = (error: DbError) => unknown;
+type Ok<T> = {
+  readonly ok: true;
+  readonly data: T;
+  readonly error: null;
+};
+type Err<E = DbError> = {
+  readonly ok: false;
+  readonly data: null;
+  readonly error: E;
+};
+type Result<T, E = DbError> = Ok<T> | Err<E>;
+declare function ok<T>(data: T): Ok<T>;
+declare function err<E = DbError>(error: E): Err<E>;
+/**
+ * A lazy-free `PromiseLike<Result<T>>` with helpers. `await` gives the
+ * `Result`; `.orThrow()` gives the data or throws a `DbException`.
+ */
+declare class AsyncResult<T> implements PromiseLike<Result<T>> {
+  #private;
+  constructor(promise: Promise<Result<T>>);
+  static from<T>(run: () => Promise<Result<T>>): AsyncResult<T>;
+  static ok<T>(data: T): AsyncResult<T>;
+  static err<T = never>(error: DbError): AsyncResult<T>;
+  then<R1 = Result<T>, R2 = never>(onfulfilled?: ((value: Result<T>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+  /**
+   * Resolves with the data, or rejects with a `DbException`. Pass `factory`
+   * to throw your own error instead, e.g. an HTTP error for your framework;
+   * without it, the mapper from `betterSupabase.mapError()` applies when one is set.
+   */
+  orThrow(factory?: (error: DbError) => unknown): Promise<T>;
+  /** Resolves with the data, or `fallback` when the result is an error. */
+  unwrapOr<F>(fallback: F): Promise<T | F>;
+  map<U>(fn: (data: T) => U): AsyncResult<U>;
+  mapError(fn: (error: DbError) => DbError): AsyncResult<T>;
+  andThen<U>(fn: (data: T) => PromiseLike<Result<U>>): AsyncResult<U>;
+}
+/** What `toBetterResult` returns: the `status`/`value`/`error` fields every better-result value has. */
+type BetterResultValue<T, E> = {
+  readonly status: "ok";
+  readonly value: T;
+} | {
+  readonly status: "error";
+  readonly error: E;
+};
+/** The part of better-result's `Result` namespace `toBetterResult` calls. */
+interface BetterResultApi<T, E> {
+  ok(value: NoInfer<T>): unknown;
+  err(error: NoInfer<E>): unknown;
+}
+/**
+ * Builds a better-result value with the `Result` namespace you pass, so
+ * better-result stays your dependency. Errors go through `mapError`, or, for a
+ * result from a `db` of `betterSupabase.mapError(fn)`, through `fn` (typed `unknown`).
+ * The value is a real `Ok`/`Err`: cast it (`as Result<T, E>`) for its
+ * methods in types; the cast itself is not checked against `T`.
+ *
+ * ```ts
+ * import { Result } from 'better-result';
+ * const customer = toBetterResult(await db.customers.findById(id), Result, toAppError);
+ * ```
+ */
+declare function toBetterResult<T, E>(result: Result<T>, api: BetterResultApi<T, E>, mapError: (error: DbError) => E): BetterResultValue<T, E>;
+declare function toBetterResult<T>(result: Result<T>, api: BetterResultApi<T, DbError>): BetterResultValue<T, DbError>;
+declare function toBetterResult<T, E>(result: AsyncResult<T>, api: BetterResultApi<T, E>, mapError: (error: DbError) => E): Promise<BetterResultValue<T, E>>;
+declare function toBetterResult<T>(result: AsyncResult<T>, api: BetterResultApi<T, unknown>): Promise<BetterResultValue<T, unknown>>;
+/**
+ * Converts a better-result value back into a `Result`, by its `status`
+ * field, so it works across better-result versions. A `DbError`, or an
+ * error whose `cause` is one, is kept; others go through `mapError`
+ * (default `toDbError`).
+ */
+declare function fromBetterResult<T>(result: BetterResultValue<T, unknown>, mapError?: (error: unknown) => DbError): Result<T>;
+declare function toDbError(cause: unknown): DbError;
+//#endregion
+//#region src/core/executor.d.ts
+interface ExecuteContext {
+  readonly signal?: AbortSignal;
+  readonly errorMappers: readonly ErrorMapper[];
+}
+interface ExecuteResult {
+  /** Rows keyed by the aliases in the operation's selection. */
+  readonly rows: readonly Record<string, unknown>[];
+  readonly count: number | null;
+}
+/**
+ * Runs IR operations. PostgREST (`postgrestExecutor`) and SQL
+ * (`better-supabase/postgres`) are built in; any other backend can implement
+ * this interface and prove it with `testExecutor` from `better-supabase/testing`.
+ */
+interface Executor {
+  readonly name: string;
+  /** Honors `SelectOp.source`. `db.$search` fails on executors without it. */
+  readonly functionSources?: boolean;
+  execute(op: Operation, context: ExecuteContext): Promise<Result<ExecuteResult>>;
+  /** Calls a database function. Optional; `db.$rpc` fails without it. */
+  rpc?(name: string, args: Readonly<Record<string, unknown>>, context: RpcContext): Promise<Result<unknown>>;
+  /**
+   * Runs several reads together, for `db.$many`: one transaction on a SQL
+   * connection. Returns one result per operation, in order. Optional;
+   * without it `db.$many` runs the operations in parallel.
+   */
+  batch?(ops: readonly Operation[], context: ExecuteContext): Promise<readonly Result<ExecuteResult>[]>;
+}
+interface RpcContext extends ExecuteContext {
+  readonly schema: string;
+  /** The function is `stable`: send it as a GET, so read replicas can serve it. */
+  readonly get?: boolean;
+}
+//#endregion
+export { or as $, mapDbError as A, InsertOp as B, RawDbError as C, isConflict as D, isCheck as E, Condition as F, Quantifier as G, MutationOp as H, CountMode as I, Selection as J, SelectColumn as K, DeleteOp as L, AggregateFn as M, Aggregation as N, isDbError as O, ColumnOp as P, not as Q, FunctionSource as R, ErrorMapper as S, dbError as T, Operation as U, Measure as V, OrderTerm as W, and as X, UpdateOp as Y, column as Z, DbError as _, AsyncResult as a, DbErrorOf as b, Err as c, ThrowMapper as d, err as f, toDbError as g, toBetterResult as h, RpcContext as i, statusOf as j, isForeignKey as k, Ok as l, ok as m, ExecuteResult as n, BetterResultApi as o, fromBetterResult as p, SelectOp as q, Executor as r, BetterResultValue as s, ExecuteContext as t, Result as u, DbErrorKind as v, ValidationIssue as w, DbException as x, DbErrorKinds as y, Include as z };

package/dist/{executor-B26lgbHD.d.ts → executor-Cghdstwu.d.ts}

@@ -1,5 +1,4 @@
-import { r as Executor } from "./executor-DynmIWhq.js";
-import { y as RawDbError } from "./result-c2OYgCV2.js";
+import { C as RawDbError, r as Executor } from "./executor-BunPOO-k.js";
 //#region src/postgres/executor.d.ts
 /**
  * Anything that runs parameterized SQL: `ctx.postgres` from

package/dist/{executor-C57jx2pn.js → executor-XycESQPH.js}

@@ -1,6 +1,6 @@
-import { c as mapDbError, n as dbError } from "./errors-Bl3rkOzo.js";
-import { i as ok, n as err, o as toDbError } from "./result-DWXatkd6.js";
-import { t as compileSql } from "./sql-BIgk12ew.js";
+import { c as mapDbError, n as dbError } from "./errors-DtwXa6b8.js";
+import { i as ok, n as err, o as toDbError } from "./result-BKiliPY7.js";
+import { t as compileSql } from "./sql-Coh6n4cC.js";
 //#region src/postgres/executor.ts
 function isPgError(value) {
 	return typeof value === "object" && value !== null && typeof value.code === "string";