palgres 0.0.0-stage → 0.1.0

package/types/palgres/src/query/errors.d.ts

@@ -0,0 +1,168 @@
+/** The brand an HTTP refusal is known by, across package copies. */
+export declare const HTTP_ERROR_BRAND: unique symbol;
+/**
+ * Set on a refusal the ENGINE built — out of a driver failure, or of a filter
+ * it would not run — as opposed to one the author threw to answer a request.
+ * A status cannot tell them apart — the author's `Conflict` and the engine's
+ * `UniqueViolation` are both 409 — so the framework logs the engine's by this
+ * mark.
+ */
+export declare const ENGINE_RAISED: unique symbol;
+/** Postgres' five-character codes the engine maps or retries on. */
+export declare const SQLSTATE: Readonly<{
+    readonly uniqueViolation: '23505';
+    readonly foreignKeyViolation: '23503';
+    readonly serializationFailure: '40001';
+    readonly deadlockDetected: '40P01';
+    readonly queryCancelled: '57014';
+    readonly lockNotAvailable: '55P03';
+    readonly inFailedTransaction: '25P02';
+    readonly insufficientPrivilege: '42501';
+}>;
+/**
+ * An HTTP refusal, in palbase/backend's shape — status, the wire code
+ * (`error`), its description, an optional typed `data` and `retryAfter` —
+ * so the framework sends it in its envelope. palbase/backend re-exports
+ * these classes rather than declaring its own: the class a handler imports is
+ * the class the engine throws, and `instanceof` holds.
+ */
+export declare class HttpError extends Error {
+    readonly [HTTP_ERROR_BRAND] = true;
+    readonly status: number;
+    readonly error: string;
+    readonly errorDescription: string;
+    readonly data?: unknown;
+    /** Seconds the caller should wait, sent as Retry-After. */
+    readonly retryAfter?: number;
+    constructor(status: number, error: string, errorDescription: string, data?: unknown, retryAfter?: number);
+}
+export declare function markEngineRaised<E extends object>(e: E): E;
+export declare function isEngineRaised(e: unknown): boolean;
+export interface FieldError {
+    /** The field's name (a dotted path when nested). */
+    field: string;
+    message: string;
+}
+export interface BadRequestData {
+    fields: FieldError[];
+}
+/** 400 — malformed or invalid; carries the fields. */
+export declare class BadRequest extends HttpError {
+    readonly data: BadRequestData;
+    constructor(data: BadRequestData, message?: string);
+}
+/** 404. */
+export declare class NotFound extends HttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 409 — the request conflicts with the current state. */
+export declare class Conflict extends HttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/**
+ * 409 — a write would duplicate a row: SQLSTATE 23505, converted by the
+ * engine so nobody has to match the driver's prose. `constraint` is the name
+ * Postgres gave ("" when the driver did not say). It is a field and stays out
+ * of the message: an uncaught duplicate puts the message in front of the
+ * app's user, and a constraint name tells them how the schema is built.
+ *
+ *   try { await Database.public.users.insert({ email }); }
+ *   catch (e) { if (UniqueViolation.is(e) && e.constraint === 'users_email_key') throw new Conflict('That email is taken', 'email_taken'); throw e; }
+ */
+export declare class UniqueViolation extends Conflict {
+    readonly constraint: string;
+    readonly sqlstate: "23505";
+    /** Whether `e` is one, whichever copy of the package made it. */
+    static is(e: unknown): e is UniqueViolation;
+    constructor(constraint: string, message?: string, code?: string, data?: unknown);
+}
+/**
+ * A failure Postgres says is cured by running the whole transaction again
+ * (40001, 40P01). The set is narrow on purpose: retrying a duplicate (23505)
+ * gives the same answer forever.
+ */
+export interface RetryableError extends Error {
+    readonly retryable: true;
+    /** The five-character SQLSTATE: which concurrency failure it was. */
+    readonly sqlstate: string;
+}
+/** By shape, not instanceof: the engine and the caller may hold different copies of the class. */
+export declare function isRetryable(e: unknown): e is RetryableError;
+/** 40001 — under SERIALIZABLE or REPEATABLE READ, a concurrent transaction invalidated this one. */
+export declare class SerializationFailure extends Conflict implements RetryableError {
+    readonly retryable: true;
+    readonly sqlstate: string;
+    static is(e: unknown): e is SerializationFailure;
+    constructor(sqlstate?: string, message?: string, data?: unknown);
+}
+/** 40P01 — two transactions waited on each other's locks and Postgres cancelled this one: a lock-order signal. */
+export declare class DeadlockDetected extends Conflict implements RetryableError {
+    readonly retryable: true;
+    readonly sqlstate: string;
+    static is(e: unknown): e is DeadlockDetected;
+    constructor(sqlstate?: string, message?: string, data?: unknown);
+}
+/**
+ * 25P02 at COMMIT: a statement of the transaction failed and the code went
+ * on, so Postgres answered the COMMIT with ROLLBACK — nothing the transaction
+ * wrote is kept. `cause` is the statement's failure. Bun reports such a
+ * COMMIT as a success; the engine refuses it itself.
+ */
+export declare class TransactionAborted extends Error {
+    readonly sqlstate: "25P02";
+    static is(e: unknown): e is TransactionAborted;
+    constructor(message: string, cause: unknown);
+}
+export interface TooManyRequestsData {
+    /** Seconds the caller should wait. */
+    retryAfter: number;
+}
+/** 429 — the database queue is full or its wait ran out. */
+export declare class TooManyRequests extends HttpError {
+    readonly data: TooManyRequestsData;
+    constructor(data: TooManyRequestsData, message?: string);
+}
+/**
+ * The five-character SQLSTATE, wherever the driver put it: postgres.js in
+ * `.code`, Bun in `.errno` (its `.code` is its own, "ERR_POSTGRES_SERVER_ERROR").
+ * The shape decides — a SQLSTATE is five of [0-9A-Z].
+ */
+export declare function sqlstateOf(e: unknown): string | undefined;
+/** Failures that prove the statement never reached a backend: replaying the request cannot apply anything twice. */
+export declare const NEVER_REACHED_A_BACKEND: ReadonlySet<string>;
+/** An established connection died under the request: the database is as unavailable, but a COMMIT may have landed. */
+export declare const LOST_MID_REQUEST: ReadonlySet<string>;
+/**
+ * A connection Bun's pool lent with no connection under it (Bun 1.4.2): one
+ * the server ended in the very read that finished opening it — its
+ * ReadyForQuery and a FATAL in one packet, as a switchover terminating a
+ * backend that has just started sends them. The pool hears the close, then the
+ * open, and keeps the slot as open with nothing under it: it lends it again and
+ * again and never opens it anew, and its close() waits for it forever
+ * (oven-sh/bun#42804; the fix, oven-sh/bun#40913, is not in a release). A
+ * statement given it is refused before anything is written, in these words
+ * and with no code. The database is reachable — only that connection is not —
+ * so it is no connectionFailure: the driver takes another (bunDriver).
+ */
+export declare function bunSlotWithoutConnection(e: unknown): boolean;
+/**
+ * How the connection failed, as opposed to Postgres refusing a statement on
+ * it: `lost` — an established one died, as a pooled connection the server
+ * closed does at once on its next use; `never` — a new one did not open, the
+ * database is not reachable now. Read off the driver's error, or the cause of
+ * the 503 the engine made of it.
+ */
+export declare function connectionFailure(e: unknown): 'lost' | 'never' | undefined;
+/**
+ * Whether Postgres itself refused a statement — the transaction lives on,
+ * aborted — as opposed to the connection failing under it. Read off the
+ * driver's SQLSTATE, or off a refusal the engine made of one (its `sqlstate`,
+ * its `cause`). Class 08 and 57P01–57P03 are the connection going away.
+ */
+export declare function refusedByPostgres(e: unknown): boolean;
+/**
+ * The constraint a 23505 names: the driver's own field first (Bun's
+ * `constraint`, postgres.js' `constraint_name`, a UniqueViolation's), the
+ * message's prose only as the fallback; "" when nothing says.
+ */
+export declare function constraintOf(e: unknown): string;

package/types/palgres/src/query/guards.d.ts

@@ -0,0 +1,62 @@
+import type { TxWireExpr } from './tx-plan.js';
+export declare function brandRef<T extends object>(v: T, kind: 'col' | 'sql' | 'ref' | 'expr'): T;
+export declare function isColRef(v: unknown): v is {
+    readonly $col: string;
+};
+export declare function isSqlFragment(v: unknown): v is {
+    readonly $sql: {
+        text: string[];
+        values: unknown[];
+    };
+};
+/** A plan reference — `{ $ref: { op, field } }` — that this process's plan builder made. */
+export declare function isPlanRef(v: unknown): v is {
+    readonly $ref: {
+        op: number;
+        field: string;
+    };
+};
+/** A plan's `{ $expr }` that its builder made: a request body's look-alike is data, never an expression. */
+export declare function isPlanExpr(v: unknown): v is {
+    readonly $expr: TxWireExpr['$expr'];
+};
+/** `{ $ref: … }` without the mark: refused by name rather than bound as a value, which would compare against another row's value. */
+export declare function looksLikeUnbrandedPlanRef(v: unknown): boolean;
+/** `{ $col }` / `{ $sql }` / `{ $expr }` without the mark, as an operator's operand. */
+export declare function looksLikeUnbrandedRef(v: unknown): 'col' | 'sql' | 'expr' | null;
+export declare function isColumnExpr(v: unknown): boolean;
+/** now(): the server's clock — a comparison value too, where increment() is only a write. */
+export declare function isNowExpr(v: unknown): boolean;
+/** A value-taking write path given an expression handle or col(), refused with the path that takes it. */
+export declare function assertNoExpressionHandles(caller: string, table: string, cols: readonly string[], data: Record<string, unknown>): void;
+/**
+ * A filter that would compile to something other than what it reads like:
+ * `{ col: undefined }` binds NULL, and `= NULL` matches nothing, silently;
+ * `{ col: {} }` produces no term — every row on a read, a dropped condition
+ * on a write; an undefined operand or `in` element is the same NULL, one
+ * level down.
+ */
+export declare function assertUsableFilter(caller: string, table: string, where: Record<string, unknown> | undefined): void;
+/** ago()'s units: the only keys of a span anything reads. */
+export declare const SPAN_UNITS: readonly string[];
+/**
+ * A span as one rule reads it — where ago() makes it, and again where a
+ * statement is written, since a handle can be made by hand: a plain object of
+ * the four units alone, each a whole number from 0 to what an int holds, and
+ * at least one. The answer is a copy, each value read once, so a getter
+ * cannot tell the check one thing and the statement another; or why the
+ * span is none.
+ */
+export declare function readSpan(span: unknown): {
+    span: Readonly<Record<string, number>>;
+} | {
+    refused: string;
+};
+/** undefined is nobody saying anything; null is someone saying "empty this column". Only the second is a write. */
+export declare function assertUsableWriteValues(caller: string, table: string, cols: readonly string[], data: Record<string, unknown>): void;
+/**
+ * The id `update({ where, set })` updates by — one row, by its id alone. A
+ * key beside it, `{ id, org_id }` meant as a scope, would be dropped and the
+ * row updated whatever its org.
+ */
+export declare function updateTarget(table: string, where: unknown): string;

package/types/palgres/src/query/index.d.ts

@@ -0,0 +1,76 @@
+import type { Binding } from '../connect.js';
+import type { Roles } from '../plan.js';
+import type { SchemaDef } from '../dsl/schema.js';
+import { type DatabaseAdmissionOptions } from './admission.js';
+import type { DBClient } from './client.js';
+import { type SqlDriver } from './driver.js';
+import { type Identity, type RequestOptions } from './request.js';
+import { type Embed } from './search.js';
+import type { EnvTypedDatabase } from './typed.js';
+export interface DatabaseOptions {
+    /**
+     * The app's pool, logged in as the app's role (a member of anon,
+     * authenticated and service_role). It must send text parameters as they
+     * are, and run the opening of a transaction (its role, its caller) before
+     * the work: Bun.SQL with { prepare: false } through bunDriver(), postgres.js
+     * with { types: POSTGRES_JS_TYPES } through postgresJsDriver() —
+     * createDatabase checks.
+     */
+    sql: SqlDriver;
+    /** The schema files' default exports — the schema the binding's version was migrated from. */
+    schemas: readonly SchemaDef[];
+    /** The version this app serves: bind(sql, toModel(schemas)). */
+    binding: Binding;
+    /** The database's roles, when they are not anon, authenticated and service_role. */
+    roles?: Partial<Roles>;
+    /** The pool's queue: its size (default 10) and limits. Every database on one pool shares one queue. */
+    admission?: DatabaseAdmissionOptions;
+    /** The secret page() cursors are sealed with, the same on every replica; page() refuses without it. */
+    cursorSecret?: string;
+    /**
+     * What embeds a search's query — and, given to createSearchWorker, the
+     * rows: Palgres reaches no network and holds no key of its own. Without
+     * it, search() answers by word alone only when asked to (mode: "text").
+     */
+    embed?: Embed;
+    /** What the engine has to say outside any request's answer: a search answered by word alone because its query could not be embedded. */
+    log?: (line: string) => void;
+}
+/** One request's — or one job's — database. `T`, `S`: the project's tables (the framework's `Tables`, `Schemas`). */
+export interface RequestDatabase<T, S> {
+    /** What a handler reaches as `Database`: typed tables, the `$` operations, $atomic, $asService(). */
+    readonly database: EnvTypedDatabase<T, S>;
+    /** The string-keyed client the typed surface is built on. */
+    readonly client: DBClient;
+    /** Commits what was opened — nothing, if nothing was. Once, after the handler returns. */
+    commit(): Promise<void>;
+    /** Rolls back what was opened. Once, when the handler throws. */
+    rollback(reason: unknown): Promise<void>;
+}
+export interface AppDatabase<T, S> {
+    readonly binding: Binding;
+    request(identity: Identity, options?: RequestOptions): RequestDatabase<T, S>;
+}
+/** The engine over `binding`'s version, its `Database` typed by `T` (public's tables) and `S` (the other schemas'). */
+export declare function createDatabase<T = Record<never, never>, S = Record<never, never>>(options: DatabaseOptions): Promise<AppDatabase<T, S>>;
+export type { DatabaseAdmissionOptions } from './admission.js';
+export type { AtomicClient, DBClient, DBOps, FindManyOptions, RowLock, SearchOptions } from './client.js';
+export type { Embed } from './search.js';
+export type { DatabaseBudget, DatabaseDiagnostics, DatabaseDiagnosticsOptions, DatabaseQueryEvent } from './diagnostics.js';
+export { BUN_CLOSE_GRACE_MS, bunDriver, cancelBackendThrough, cancelOpeningThrough, closeBunPool, DriverRefused, encodeParam, encodePgArray, inlineParams, POSTGRES_JS_TYPES, postgresJsDriver, renewingBunPool, verifyDriver, type PostgresJs } from './driver.js';
+export type { BunPool, BunReserved, BunSqlPool, Opening, RenewingBunPool, Statement, StatementHint, SqlDriver, SqlTx } from './driver.js';
+export { makeEnvDts, ENV_BLOCK_END, ENV_BLOCK_START } from './env-gen.js';
+export { BadRequest, Conflict, connectionFailure, constraintOf, DeadlockDetected, ENGINE_RAISED, HTTP_ERROR_BRAND, HttpError, isEngineRaised, isRetryable, markEngineRaised, NotFound, SerializationFailure, SQLSTATE, sqlstateOf, TooManyRequests, TransactionAborted, UniqueViolation, } from './errors.js';
+export type { BadRequestData, FieldError, RetryableError, TooManyRequestsData } from './errors.js';
+export type { AtomicOptions, InsertConflict, InsertManyOptions, Page, PageInfo, PageNavigation, RawPageOptions, TransactionIsolation } from './options.js';
+export { buildRelations } from './relations.js';
+export { isData, markData } from './data-mark.js';
+export type { Relation } from './relations.js';
+export { defineRepository } from './repository.js';
+export type { DefaultRowKey, MissingRowKey, RepositoryOf, RepositoryTable, RowKey } from './repository.js';
+export type { Identity, RequestOptions } from './request.js';
+export { ago, decrement, increment, now, TxPlanError, TxRefError } from './tx-plan.js';
+export type { Materialized, Ref, TxColumnExpr, TxInsertConflict, TxNow, TxRow, TxRows, TxSpan, TxTable, TxWhere } from './tx-plan.js';
+export { col, isColRef, makeTypedDB, sqlFragment, withRetry } from './typed.js';
+export type { AggregateInput, AggregateResult, AtomicDatabase, ColRef, Env, EnvSchemaSurface, EnvServiceDatabase, EnvTables, EnvTypedDatabase, EnvTypedTable, InsertShape, InsertValues, MutateInput, NoEnv, QueryInput, RowShape, Searchable, SearchParams, SetShape, SqlFragment, TableTypes, TablesOf, TxPlan, TxSchemaSurface, TxTables, TypedDB, TypedTable, WhereFilter, WhereOp, WithInput, } from './typed.js';
+export type { UniqueWhere } from './unique.js';

package/types/palgres/src/query/options.d.ts

@@ -0,0 +1,75 @@
+export type TransactionIsolation = 'read committed' | 'repeatable read' | 'serializable';
+export interface AtomicOptions {
+    /** Each retry opens a fresh transaction and runs the whole callback again. Zero unless given: keep external effects outside, persist an outbox instead. */
+    retry?: number;
+    isolation?: TransactionIsolation;
+    readOnly?: boolean;
+    /** Longest wait for a lock (default 5000 ms). */
+    lockTimeoutMs?: number;
+    /** statement_timeout of every statement in the scope. */
+    statementTimeoutMs?: number;
+    /** Deadline of the whole scope, queueing and retries included. Statements in flight are cancelled; an in-flight COMMIT is awaited. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export declare function retryBudget(value: number | undefined): number;
+export declare function validateAtomicOptions(options: AtomicOptions): void;
+/** A plan is a savepoint: it cannot take a new snapshot or retry a COMMIT. */
+export declare function assertPlanRetry(options: {
+    retry?: number;
+} | undefined): void;
+/**
+ * What a collision does. Matched on `onConflict` — columns a unique
+ * constraint or index covers — it is ignored or overwritten ("ignore" unless
+ * said). `action: "ignore"` alone skips a row that collides with ANY unique
+ * key: Prisma's skipDuplicates, Drizzle's onConflictDoNothing(). An overwrite
+ * has to say which row it overwrites, so it needs the columns.
+ */
+export type InsertConflict<Key extends string = string> = {
+    onConflict: readonly Key[];
+    action?: 'ignore' | 'update';
+} | {
+    onConflict?: undefined;
+    action?: 'ignore';
+};
+export type InsertManyOptions<Key extends string = string> = InsertConflict<Key> & {
+    /** false: the affected row count, no rows serialized. */
+    returning?: boolean;
+};
+export declare function validateInsertManyOptions(opts: InsertManyOptions | undefined): void;
+/** Forward and backward are exclusive; without a size, 50 rows. */
+export type PageNavigation = {
+    first?: number;
+    after?: string;
+    last?: never;
+    before?: never;
+} | {
+    last?: number;
+    before?: string;
+    first?: never;
+    after?: never;
+};
+export interface PageInfo {
+    startCursor: string | null;
+    endCursor: string | null;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+}
+export interface Page<Row> {
+    rows: Row[];
+    pageInfo: PageInfo;
+}
+/** page()'s untyped options; the typed tables narrow column and relation names. */
+export type RawPageOptions = PageNavigation & {
+    orderBy?: {
+        column: string;
+        direction?: 'asc' | 'desc';
+        nulls?: 'first' | 'last';
+    } | readonly {
+        column: string;
+        direction?: 'asc' | 'desc';
+        nulls?: 'first' | 'last';
+    }[];
+    select?: readonly string[];
+    with?: Record<string, unknown>;
+};

package/types/palgres/src/query/relations.d.ts

@@ -0,0 +1,15 @@
+import { type SchemaDef } from '../dsl/schema.js';
+export type Relation = {
+    name: string;
+    /** The target's table key: bare in public, "schema.table" otherwise. */
+    to: string;
+    kind: 'one' | 'many';
+    /** The foreign-key column the relation runs through — on this table for `one`, on the target for `many`. */
+    via: string;
+};
+/**
+ * Every table's relations by table key. A name two relations would take is
+ * refused, never settled by declaration order: the forward name comes from
+ * the column (or `as`), the reverse one from the child table (or `reverseAs`).
+ */
+export declare function buildRelations(schemas: readonly SchemaDef[]): Map<string, Relation[]>;

package/types/palgres/src/query/repository.d.ts

@@ -0,0 +1,42 @@
+/** The four members a repository asks of `Database.public.<t>`. `NoInfer`: Row comes from insert alone — findMany's generics would widen it. */
+export interface RepositoryTable<Row, Insert, Patch> {
+    insert(data: Insert): Promise<Row>;
+    findMany(q: {
+        where: Record<string, unknown>;
+        limit?: number;
+    }): Promise<NoInfer<Row>[]>;
+    updateMany(q: {
+        where: Record<string, unknown>;
+        set: Patch;
+    }): Promise<NoInfer<Row>[]>;
+    deleteMany(q: {
+        where: Record<string, unknown>;
+    }): Promise<number>;
+}
+/** The row key by default: `id`, when the row has one. */
+export type DefaultRowKey<Row> = Extract<keyof Row & string, 'id'>;
+/** The refusal for a row without `id` and no `key`, with the remedy in its name. */
+export interface MissingRowKey {
+    'defineRepository: this row has no `id` column — name its key with { key: "..." }': never;
+}
+export type RowKey<Row, PK extends keyof Row & string> = [PK] extends [never] ? MissingRowKey : Row[PK];
+/**
+ * A tenant-scoped repository. The insert payload has no tenant column: the
+ * repository writes it. A patch has neither the tenant column nor the row key:
+ * the row stays the tenant's, under its key.
+ */
+export interface RepositoryOf<Row, Insert, Patch, K extends keyof Row & string, PK extends keyof Row & string = DefaultRowKey<Row>> {
+    list(tenant: Row[K]): Promise<Row[]>;
+    /** The tenant's row with this key, or null — absence is a value. */
+    find(tenant: Row[K], id: RowKey<Row, PK>): Promise<Row | null>;
+    insert(tenant: Row[K], values: Omit<Insert, K>): Promise<Row>;
+    /** The tenant's row updated; NotFound when there is none — updateScoped for null instead. */
+    update(tenant: Row[K], id: RowKey<Row, PK>, patch: Omit<Patch, K | PK>): Promise<Row>;
+    updateScoped(tenant: Row[K], id: RowKey<Row, PK>, patch: Omit<Patch, K | PK>): Promise<Row | null>;
+    delete(tenant: Row[K], id: RowKey<Row, PK>): Promise<void>;
+}
+/** An abstract base: the container resolves the subclass's name, not this anonymous one. */
+export declare function defineRepository<Row, Insert, Patch, K extends keyof Row & string, PK extends keyof Row & string = DefaultRowKey<Row>>(table: RepositoryTable<Row, Insert, Patch>, opts: {
+    tenant: K;
+    key?: PK;
+}): abstract new () => RepositoryOf<Row, Insert, Patch, K, PK>;

package/types/palgres/src/query/request.d.ts

@@ -0,0 +1,54 @@
+import type { Binding } from '../connect.js';
+import type { Roles } from '../plan.js';
+import type { DatabaseAdmission } from './admission.js';
+import type { Catalog } from './catalog.js';
+import type { DBClient } from './client.js';
+import { type DatabaseDiagnosticsOptions } from './diagnostics.js';
+import type { SqlDriver } from './driver.js';
+import type { SearchRuntime } from './search.js';
+/**
+ * Who a request is, as Postgres will see it: a signed-in caller is
+ * `authenticated` with their claims (sub, role, …), anyone else `anon`. An
+ * app whose every request is its operator's — Studio, whose tables are all
+ * service_role's (v2 ran it with DB_ROLE=service_role) — binds its requests
+ * as `service`.
+ */
+export interface Identity {
+    role: 'anon' | 'authenticated' | 'service';
+    claims: Record<string, unknown>;
+}
+export interface RequestOptions {
+    /** Statement events, totals and a budget — allocated only when given. */
+    diagnostics?: DatabaseDiagnosticsOptions;
+    /**
+     * Told once, with how long it has waited, when a transaction of the
+     * request that cannot be given back — it wrote, locked or took a
+     * savepoint — has sat HELD_IDLE_MS with nothing in flight: the handler is
+     * waiting on something else, and a database connection waits with it.
+     */
+    heldIdle?: (waitedMs: number) => void;
+    /**
+     * The request's signal. When it aborts, the statement in flight is
+     * cancelled (through the driver's cancelBackend) and every later one is
+     * refused; the commit is not — a handler that returned has its work
+     * committed, unless the cancelled statement aborted the transaction.
+     */
+    signal?: AbortSignal;
+}
+/** The two transactions of one request, and the client over them. */
+export interface RequestTransactions {
+    readonly client: DBClient;
+    /** Commits what was opened — the caller's transaction, then the service one. Once, after the handler returns. */
+    commit(): Promise<void>;
+    /** Rolls back what was opened. Once, when the handler throws. */
+    rollback(reason: unknown): Promise<void>;
+}
+export interface EngineContext {
+    readonly cat: Catalog;
+    readonly binding: Binding;
+    readonly roles: Roles;
+    readonly admission: DatabaseAdmission;
+    readonly cursorKey: Buffer | null;
+    readonly search: SearchRuntime;
+}
+export declare function createRequestTransactions(sql: SqlDriver, ctx: EngineContext, identity: Identity, options?: RequestOptions): RequestTransactions;

package/types/palgres/src/query/search.d.ts

@@ -0,0 +1,55 @@
+import type { SearchMetric } from '../model.js';
+import type { SearchOptions } from './client.js';
+/**
+ * Texts as vectors, by the model and in the dimensions a table declares:
+ * `document` for a row's text, `query` for what is searched for. The answer
+ * names the model that embedded them and holds one vector per text, in
+ * their order.
+ */
+export type Embed = (input: {
+    texts: string[];
+    model: string;
+    dimensions: number;
+    purpose: 'document' | 'query';
+}) => Promise<{
+    model: string;
+    vectors: number[][];
+}>;
+/** The generation of a table's vectors that serves, and the schema pgvector's types are in. */
+export interface ServingVectors {
+    gen: number;
+    model: string;
+    dimensions: number;
+    metric: SearchMetric;
+    types: string;
+}
+/** What every request's search of one database shares. */
+export interface SearchRuntime {
+    embed?: Embed;
+    /** The generation that serves each table ("schema.table"), as last read. */
+    readonly serving: Map<string, ServingVectors>;
+    /** When each table's search last said it fell back to words alone. */
+    readonly said: Map<string, number>;
+    log?: (line: string) => void;
+}
+export declare const searchRuntime: (embed: Embed | undefined, log: ((line: string) => void) | undefined) => SearchRuntime;
+/** A text longer than this is cut to it before it is embedded: a model reads so much at once. */
+export declare const SEARCH_TEXT_LIMIT = 30000;
+/**
+ * Which generation serves a table now, with what its index scan is told for
+ * this transaction: go on past the first candidates when a filter or a policy
+ * turns them away (iterative_scan), and how far.
+ */
+export declare const SERVING_SQL: string;
+export declare function servingOf(row: Record<string, unknown> | undefined): ServingVectors | undefined;
+/** What a caller asked, checked before anything is embedded or sent: a search box's text is the request's, and so is a 400. */
+export declare function searchRequest(key: string, query: unknown, opts: SearchOptions): {
+    text: string;
+    mode: NonNullable<SearchOptions['mode']>;
+    limit: number;
+    minScore?: number;
+};
+/** One embedded text as pgvector reads it, or why what the embedder answered is no vector of the generation's. */
+export declare function vectorLiteral(vector: unknown, dimensions: number): string;
+/** The query as a vector of the generation that serves. */
+export declare function embedQuery(embed: Embed, text: string, serving: ServingVectors): Promise<string>;

package/types/palgres/src/query/surface.d.ts

@@ -0,0 +1,9 @@
+import type { DBClient } from './client.js';
+import type { EnvTypedDatabase } from './typed.js';
+/**
+ * The typed `Database` over one request's client — what palbase/backend
+ * puts in its request scope, typed by the project's tables (`T` public's,
+ * `S` the other schemas'). `$asService()` is built on each call, over the
+ * request's one service transaction.
+ */
+export declare function typedDatabase<T, S>(client: DBClient): EnvTypedDatabase<T, S>;