palgres 0.0.0-stage → 0.1.0

package/types/palgres/src/query/tx-plan.d.ts

@@ -0,0 +1,229 @@
+import type { ColRefOf, Env, HasOnly, NoEnv, SqlFragment, WhereOpWith } from './typed.js';
+/** A plan handle was used as a value — awaited, coerced, serialised. Thrown while the plan is being built: nothing was sent. */
+export declare class TxRefError extends Error {
+    constructor(message: string);
+}
+/** The plan breaks a rule the executor would reject; named here, on the line that wrote it. */
+export declare class TxPlanError extends Error {
+    constructor(message: string);
+}
+/** A backwards reference to an earlier operation's single row. */
+export interface TxWireRef {
+    $ref: {
+        op: number;
+        field: string;
+    };
+}
+/** A call from the closed set: inc/dec read the column's current value, now() is the server's clock — less ago()'s span, when it has one. */
+export interface TxWireExpr {
+    $expr: {
+        fn: 'inc' | 'dec';
+        by: number | string;
+    } | {
+        fn: 'now';
+        minus?: TxSpan;
+    };
+}
+export type TxWireValue = TxWireRef | TxWireExpr | unknown;
+/** The author's expectation about an operation's row count; `slot` indexes the client-side error table — the Error object itself never travels. */
+export interface TxWireGuard {
+    kind: 'one' | 'none' | 'atLeast' | 'atMost';
+    n: number;
+    slot: number;
+}
+/** One operation. A field is omitted, never null: each kind carries exactly its own. */
+export interface TxWireOp {
+    /** upsert and insertMany: the columns a collision is matched on. An insertMany that ignores without them skips a collision with any unique key. */
+    onConflict?: readonly string[];
+    /** insertMany only: what a collision does. Absent: no ON CONFLICT at all. */
+    action?: 'ignore' | 'update';
+    op: 'insert' | 'insertMany' | 'upsert' | 'update' | 'delete' | 'select';
+    table: string;
+    values?: Record<string, TxWireValue>;
+    rows?: Record<string, TxWireValue>[];
+    set?: Record<string, TxWireValue>;
+    where?: Record<string, TxWireValue>;
+    limit?: number;
+    lock?: 'update';
+    guard?: TxWireGuard;
+}
+export interface TxPlanBody {
+    ops: TxWireOp[];
+}
+export interface TxPlanOpResult {
+    rows: Record<string, unknown>[];
+    rows_affected: number;
+}
+export interface TxPlanResponse {
+    results: TxPlanOpResult[];
+}
+/** What the executor's rejection carries: on a failed guard, the slot of the expectation, which maps back to the author's Error. */
+export interface TxPlanRejection {
+    error_code?: string;
+    slot?: number;
+}
+declare const refBrand: unique symbol;
+declare const rowBrand: unique symbol;
+declare const rowsBrand: unique symbol;
+/**
+ * Makes a handle a compile error to `await`: a callable `then` whose
+ * signature is not PromiseLike is exactly what TypeScript rejects (TS1320,
+ * and TS1058 for `async () => handle`).
+ */
+export interface NotAwaitable {
+    /** Not a promise. Nothing here has run yet; there is nothing to await. */
+    then(doNotAwaitAPlanHandle: 'a transaction plan is built synchronously'): never;
+}
+/** A value the server will produce for a column of a row this plan writes or reads. */
+export interface Ref<T> extends NotAwaitable {
+    readonly [refBrand]: T;
+}
+/** The brand of a single-row handle; `Materialized` turns `return row` into the whole row. */
+export interface TxRowHandle<Row> extends NotAwaitable {
+    readonly [rowBrand]: Row;
+}
+/** A row the plan is known to produce exactly one of; every property is a Ref. Only .expectOne(err) makes one. */
+export type TxRow<Row> = {
+    readonly [K in keyof Row]: Ref<Row[K]>;
+} & TxRowHandle<Row>;
+/** An operation's result before an expectation is declared about it — at most one expectation per operation. */
+export interface TxRows<Row> extends NotAwaitable {
+    readonly [rowsBrand]: Row;
+    /** Exactly one row, and read it; on any other count the plan rolls back and `error` is thrown. */
+    expectOne(error: Error): TxRow<Row>;
+    /** No row (e.g. "this membership must not exist yet"). */
+    expectNone(error: Error): void;
+    expectAtLeast(n: number, error: Error): void;
+    expectAtMost(n: number, error: Error): void;
+}
+/** now() — the server's clock, wherever a value goes; ago(span) is it less a span. */
+export interface TxNow extends NotAwaitable {
+    readonly $expr: {
+        fn: 'now';
+        minus?: TxSpan;
+    };
+}
+/** A span of the clock, in whole units: what ago() takes off now(). */
+export interface TxSpan {
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+}
+/** increment(n) / decrement(n): the column's current value, changed. Only in an update's set. */
+export interface TxColumnExpr extends NotAwaitable {
+    readonly $expr: {
+        fn: 'inc' | 'dec';
+        by: number | string;
+    };
+}
+/** The callback's return type as it comes back: a Ref is its value, a TxRow its row. */
+export type Materialized<T> = T extends Ref<infer U> ? U : T extends TxRowHandle<infer R> ? R : T extends TxRows<unknown> ? 'a TxRows cannot leave the transaction callback — read a row with .expectOne(err) first' : T extends Date ? T : T extends object ? {
+    [K in keyof T]: Materialized<T[K]>;
+} : T;
+/** An INSERT's value: a literal, an earlier row's field, or now(). inc/dec read a current value, which an inserted row has none of. */
+export type TxInsertValue<V> = V | Ref<V> | TxNow;
+/** An update's value: an insert's, plus increment()/decrement() on a numeric-like column. */
+export type TxSetValue<V> = V | Ref<V> | TxNow | (NonNullable<V> extends number | string ? TxColumnExpr : never);
+export type TxInsertShape<Insert> = {
+    [K in keyof Insert]: TxInsertValue<Insert[K]>;
+};
+export type TxSetShape<Insert> = {
+    [K in keyof Insert]?: TxSetValue<Insert[K]>;
+};
+type TxWhereField<Row, K extends keyof Row> = WhereOpWith<Row[K], ColRefOf<Row, Row[K]> | Ref<Row[K]>>;
+export type TxWhere<Row, Rels = unknown, E extends Env = NoEnv> = {
+    [K in keyof Row]?: TxWhereField<Row, K>;
+} & {
+    OR?: (TxWhere<Row, Rels, E> | SqlFragment)[];
+    AND?: (TxWhere<Row, Rels, E> | SqlFragment)[];
+    NOT?: TxWhere<Row, Rels, E> | SqlFragment;
+} & HasOnly<Rels, E>;
+/**
+ * What a collision of an insertMany does: matched on `onConflict`, it is
+ * ignored or overwritten ("ignore" unless said); `action: "ignore"` alone
+ * skips a collision with ANY unique key — an overwrite needs the columns it
+ * is matched on.
+ */
+export type TxInsertConflict<Key extends string = string> = {
+    onConflict: readonly Key[];
+    action?: 'ignore' | 'update';
+} | {
+    onConflict?: undefined;
+    action: 'ignore';
+};
+export interface TxSelectOptions {
+    limit?: number;
+    /** A real FOR UPDATE row lock for the rest of the transaction. */
+    lock?: 'update';
+}
+/** One table, as the plan sees it. */
+export interface TxTable<Row, Insert, Rels = unknown, E extends Env = NoEnv> {
+    /** Insert one row; .expectOne(err) to read its fields. */
+    insert(values: TxInsertShape<Insert>): TxRows<Row>;
+    /**
+     * Many rows in ONE statement, every row setting the same columns. Without
+     * opts a collision aborts the plan; `action: "ignore"` is ON CONFLICT DO
+     * NOTHING — the rows returned are the ones INSERTED, a collided row is
+     * absent — on the onConflict columns, or on any unique key without them;
+     * `action: "update"` sets every non-conflict column from the row.
+     * An empty list writes and sends nothing.
+     */
+    insertMany(rows: readonly TxInsertShape<Insert>[], opts?: TxInsertConflict<Extract<keyof Row, string>>): TxRows<Row>;
+    /** Insert, or overwrite on a collision of `onConflict` — the same as Database.<schema>.<table>.put(). */
+    put(values: TxInsertShape<Insert>, options: {
+        onConflict: readonly Extract<keyof Row, string>[];
+    }): TxRows<Row>;
+    /** Update every row matching `where` — the filter first, because it is the dangerous half. An unfiltered update is refused. */
+    updateWhere(where: TxWhere<Row, Rels, E>, set: TxSetShape<Insert>): TxRows<Row>;
+    /** Delete every row matching `where`; an unfiltered delete is refused. */
+    deleteWhere(where: TxWhere<Row, Rels, E>): TxRows<Row>;
+    /** Read rows, optionally locking them for the rest of the transaction. */
+    select(where?: TxWhere<Row, Rels, E>, options?: TxSelectOptions): TxRows<Row>;
+}
+/** The handle a plan callback gets: tables, nothing else — a read the plan does not write belongs outside it, as an ordinary value. */
+export interface TxPlanHandle<TTables> {
+    /** @deprecated public's alias; write `tx.public`. */
+    tables: TTables;
+}
+/** The server's now(). */
+export declare function now(): TxNow;
+/**
+ * The server's clock less a span — `{ at: { gt: ago({ hours: 1 }) } }` is
+ * `at > now() - interval '1 hour'` — wherever now() goes. Both sides are read
+ * where the data is: a window counted on the app's clock moves with every
+ * machine's drift from the database's, and a row stamped `defaultNow()` is
+ * stamped by the database. Whole units, none negative: a sign kept in the span
+ * is seen by no code that reads the word "ago".
+ */
+export declare function ago(span: TxSpan): TxNow;
+/** Add `by` to the column's current value. Only in an update's set. */
+export declare function increment(by: number | string): TxColumnExpr;
+/** Subtract `by` from the column's current value. Only in an update's set. */
+export declare function decrement(by: number | string): TxColumnExpr;
+/** The wire form of an increment()/decrement()/now() handle, or null. The direct path (updateMany) reads it too: one spelling of "add to the column". */
+export declare function columnExprOf(v: unknown): TxWireExpr['$expr'] | null;
+/** The operations and the error table of one plan, while its callback runs. */
+export declare class TxPlanBuilder {
+    private readonly ops;
+    /** Errors handed to expectations, by the slot a failed guard names. */
+    private readonly slots;
+    /** One table's operations, untyped; the public signatures put the schema's types on top. */
+    table(name: string): TxTable<Record<string, unknown>, Record<string, unknown>>;
+    private push;
+    attachGuard(opIndex: number, kind: TxWireGuard['kind'], n: number, error: Error): void;
+    body(): TxPlanBody;
+    errorForSlot(slot: number): Error | null;
+}
+/** The callback's return value with every handle replaced by what the server produced. Arrays and plain objects only: a class instance cannot hold a handle. */
+export declare function materializeResult(value: unknown, results: TxPlanOpResult[]): unknown;
+/** What runTxPlan needs: one call, one savepoint. */
+export interface TxPlanTransport {
+    txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
+}
+/**
+ * Builds the plan, runs it and resolves the callback's return value. A
+ * callback that throws, or describes nothing, sends nothing.
+ */
+export declare function runTxPlan<THandle>(transport: TxPlanTransport, handle: THandle, builder: TxPlanBuilder, fn: (tx: THandle) => unknown): Promise<unknown>;
+export {};