@zocomputer/system-api 0.0.0-stage → 0.1.0

package/dist/core/client.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The typed invocation client.
+ *
+ * `call` is correlated by action and version: the action comes from the first
+ * argument and the version from the (optional) options, never from the input.
+ * The input is checked for an exact match against that action/version's
+ * contract — a foreign action's input, a wrong version's input, or an excess
+ * property is a compile error — and a union-valued action or version is
+ * rejected so a single call always resolves one concrete contract. Omitting
+ * options uses the action's declared default-version pin.
+ */
+import type { DefaultVersionsShape, GuaranteedPinKeys, OperationsShape, PinnedVersion, RuntimeCatalog, TypedCatalog, TypedCatalogBase } from "./catalog.ts";
+import type { JsonObject } from "./json.ts";
+import { type AccessTokenProvider, type FetchLike } from "./transport.ts";
+import type { InvocationValidator } from "./validator.ts";
+export interface ClientConfig<C> {
+    /** The generated (or fixture) typed catalog. Supplies default-version pins. */
+    readonly catalog: C;
+    /** Application-provided bearer token source; the SDK never obtains tokens itself. */
+    readonly accessToken: AccessTokenProvider;
+    /** Override the default `https://api.zo.computer/zo-system-api/v1` base URL. */
+    readonly baseUrl?: string;
+    /** Select a workspace covered by a multi-workspace access token. */
+    readonly workspaceId?: string;
+    /** Inject a `fetch` implementation (tests, non-browser runtimes). */
+    readonly fetch?: FetchLike;
+    /**
+     * Optional structural validator. When present, its hooks validate the exact
+     * request/response bytes; when absent, the same client runs with no validation
+     * and bundles nothing from a validator. Typing (above) is orthogonal to this.
+     */
+    readonly validator?: InvocationValidator;
+}
+/** True iff `T` is a union type (used to reject union-valued action/version). */
+type IsUnion<T, B = T> = T extends B ? ([B] extends [T] ? false : true) : never;
+/** `Shape`, but any key present on `I` and absent from `Shape` is rejected. */
+type Exact<I, Shape> = Shape & Record<Exclude<keyof I, keyof Shape>, never>;
+/** The Zo built-in whose envelope may carry a caller idempotency key. */
+declare const IDEMPOTENT_ACTION = "zo.function.invoke";
+/**
+ * Zo built-ins other than `zo.function.invoke` reject keys. Custom action
+ * names may carry one; the server checks whether their binding is a run.
+ */
+type KeyOption<A> = A extends string ? A extends `zo.${string}` ? A extends typeof IDEMPOTENT_ACTION ? {
+    idempotencyKey?: string;
+} : {
+    idempotencyKey?: never;
+} : {
+    idempotencyKey?: string;
+} : {
+    idempotencyKey?: never;
+};
+/**
+ * A version that declares list query options takes `query` of its declared
+ * type; any other version takes none.
+ */
+type QueryOption<E> = E extends {
+    readonly query: infer Q;
+} ? {
+    query?: Q;
+} : {
+    query?: never;
+};
+/** When `T` is a union, demand an impossible property so the call fails. */
+type SingleOnly<T, Tag extends string> = IsUnion<T> extends true ? Record<Tag, never> : unknown;
+export interface TypedClient<Ops extends OperationsShape, Defaults extends DefaultVersionsShape<Ops>> {
+    /** Invoke `action` at an explicit `version`. Input must match that version exactly. */
+    call<A extends keyof Ops, V extends keyof Ops[A] & number, I>(action: A, input: I & Exact<I, Ops[A][V]["input"]> & SingleOnly<A, "action must be a single literal">, options: {
+        version: V;
+    } & KeyOption<A> & QueryOption<Ops[A][V]> & SingleOnly<V, "version must be a single literal">): Promise<Ops[A][V]["output"]>;
+    /**
+     * Invoke `action` at its default-version pin (options omitted). Available only
+     * for an action with a *guaranteed* pin ({@link GuaranteedPinKeys}); a visible
+     * but unpinned action is excluded here, so omitting the version for it is a
+     * compile error and the explicit-version overload above must be used. A
+     * widened/optional `Defaults` exposes no default calls at all.
+     */
+    call<A extends GuaranteedPinKeys<Defaults> & keyof Ops, I>(action: A, input: I & Exact<I, Ops[A][PinnedVersion<Ops, A, Defaults>]["input"]> & SingleOnly<A, "action must be a single literal">, options?: KeyOption<A> & QueryOption<Ops[A][PinnedVersion<Ops, A, Defaults>]>): Promise<Ops[A][PinnedVersion<Ops, A, Defaults>]["output"]>;
+}
+/** Version, idempotency key and exact query JSON for a runtime invocation. */
+export interface JsonCallOptions {
+    readonly version?: number;
+    readonly idempotencyKey?: string;
+    readonly queryJson?: string;
+}
+/** A correlated response with exact JSON text and request metadata. */
+export interface JsonCallResult {
+    readonly envelopeJson: string;
+    readonly resultJson: string;
+    readonly requestId: string;
+    readonly action: string;
+    readonly version: number;
+    /** The query the server applied, present exactly when a query was sent. */
+    readonly queryJson?: string;
+    readonly httpStatus: number;
+}
+/**
+ * The untyped invocation client, built from a server-loaded `RuntimeCatalog`.
+ * The wire behavior is identical to `TypedClient` — same transport, envelope,
+ * and digest-bound target — but with no generated types the action is an
+ * arbitrary string, the input is `unknown`, and the result is `unknown` (never
+ * `any`). This surface is reachable only through a runtime catalog; a typed
+ * client has no `call(string, unknown)` escape hatch.
+ */
+export interface RuntimeClient {
+    /** Invoke exact JSON without converting input, query or result numbers to JS numbers. */
+    callJson(action: string, inputJson: string, options?: JsonCallOptions): Promise<JsonCallResult>;
+    /**
+     * Custom action keys are sent for server-side run eligibility; other Zo
+     * built-ins reject them before sending. `query` is sent as `options.query`;
+     * the server refuses it for an action without list query options.
+     */
+    call(action: string, input: unknown, options?: {
+        version?: number;
+        idempotencyKey?: string;
+        query?: JsonObject;
+    }): Promise<unknown>;
+}
+/**
+ * Every catalog `createClient` accepts: a generated typed one, or a runtime one.
+ * The typed member is the shallow {@link TypedCatalogBase}, not a fully
+ * pin-parameterized `TypedCatalog`, so a concrete typed catalog — pinned or with
+ * unpinned actions — is assignable to the accept-constraint; `createClient`'s
+ * conditional still infers `Ops`/`Defaults` from the concrete argument type.
+ */
+type AnyCatalog = TypedCatalogBase | RuntimeCatalog;
+/**
+ * The single public client constructor, with two ways to fix the call types.
+ *
+ * Inference form (no explicit type arguments): the catalog value's brand selects
+ * the client type — a `TypedCatalog` yields a `TypedClient` (compile-time-checked
+ * calls, typed results); a server-loaded `RuntimeCatalog` yields a `RuntimeClient`
+ * (string action, `unknown` result). There is one runtime — the untyped surface
+ * is not a catch-all overload that bypasses typing on a typed client.
+ *
+ * Explicit operation-map form (explicit type arguments): a consumer that already
+ * has an `Operations` map type — hand-written, or imported ahead of a generated
+ * catalog — binds it directly, `createClient<Ops, Defaults>(config)`, and gets a
+ * `TypedClient<Ops, Defaults>` regardless of the catalog value's own brand. The
+ * declared `Operations` are the caller's asserted contract; no authority is taken
+ * from the catalog value. Both type arguments are required: generics are erased,
+ * so they cannot invent the runtime default-version pins (`Defaults`) the way the
+ * inference form reads them off a typed catalog value — the widened
+ * `DefaultVersionsShape<Ops>` has no guaranteed pin for any action, so a default
+ * (options-omitted) call would resolve for none of them. The pins must be stated
+ * explicitly, so a consumer over a runtime catalog value passes both `Ops` and
+ * `Defaults`.
+ *
+ * The inference form is declared first, so overload resolution keeps the exact
+ * prior behavior when no type arguments are given; the explicit form is reachable
+ * only through explicit type arguments (its two-parameter arity does not match a
+ * bare or single-argument call against the inference form).
+ */
+export declare function createClient<C extends AnyCatalog>(config: ClientConfig<C>): C extends TypedCatalog<infer Ops, infer Defaults> ? TypedClient<Ops, Defaults> : RuntimeClient;
+export declare function createClient<Ops extends OperationsShape, Defaults extends DefaultVersionsShape<Ops>>(config: ClientConfig<TypedCatalog<Ops, Defaults> | RuntimeCatalog>): TypedClient<Ops, Defaults>;
+export {};

package/dist/core/client.js

@@ -0,0 +1,87 @@
+import { SystemAPIError } from "./errors.js";
+import { createTransport, } from "./transport.js";
+/** The Zo built-in whose envelope may carry a caller idempotency key. */
+const IDEMPOTENT_ACTION = "zo.function.invoke";
+export function createClient(config) {
+    const transport = createTransport(config);
+    // One generic runtime body serves both surfaces; the overload signatures above
+    // are what distinguish the typed client from the untyped one.
+    const actions = config.catalog.actions;
+    function resolveTarget(action, options) {
+        const entry = actions[action];
+        if (entry === undefined) {
+            // Unreachable through the typed surface; guards a fixture/catalog mismatch.
+            throw new SystemAPIError({
+                code: "action_not_found",
+                message: `unknown action: ${action}`,
+                outcome: "not_started",
+            });
+        }
+        if (options?.idempotencyKey !== undefined &&
+            action.startsWith("zo.") &&
+            action !== IDEMPOTENT_ACTION) {
+            throw new SystemAPIError({
+                code: "invalid_envelope",
+                message: `action '${action}' does not accept an idempotency key`,
+                outcome: "not_started",
+            });
+        }
+        let version = options?.version;
+        if (version === undefined) {
+            version = entry.defaultVersion;
+            if (version === undefined)
+                // Reachable through the untyped surface or a fixture/catalog mismatch:
+                // an unpinned action has no default, so an omitted version is rejected
+                // before any request. The typed surface forbids this at compile time.
+                throw new SystemAPIError({
+                    code: "version_required",
+                    message: `action '${action}' has no default version; pass an explicit version`,
+                    outcome: "not_started",
+                });
+        }
+        // Resolve the contract the client is committing to — action, concrete
+        // version, and that version's catalog digest — so an optional validator can
+        // bind its schema bundle to this exact pinned entry (digest agreement).
+        const versionEntry = entry.versions[version];
+        if (versionEntry === undefined) {
+            // Unreachable through the typed surface; guards a fixture/catalog mismatch.
+            throw new SystemAPIError({
+                code: "unsupported_version",
+                message: `unknown version ${version} for action: ${action}`,
+                outcome: "not_started",
+            });
+        }
+        return {
+            action,
+            version,
+            digest: versionEntry.digest,
+        };
+    }
+    async function call(action, input, options) {
+        const target = resolveTarget(action, options);
+        const envelope = {
+            action,
+            input: input,
+            options: {
+                version: target.version,
+                ...(options?.idempotencyKey !== undefined
+                    ? { idempotency_key: options.idempotencyKey }
+                    : {}),
+                // The server reads `query: null` as no query and echoes none, so
+                // null is left off like undefined.
+                ...(options?.query !== undefined && options.query !== null
+                    ? { query: options.query }
+                    : {}),
+            },
+        };
+        const success = await transport.invoke(envelope, target);
+        return success.result;
+    }
+    async function callJson(action, inputJson, options) {
+        const target = resolveTarget(action, options);
+        const { invokeJson } = await import("./json-call.js");
+        return invokeJson(transport, target, inputJson, options);
+    }
+    // The overloads expose callJson only for runtime catalogs.
+    return { call, callJson };
+}

package/dist/core/database.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Decoding of database SQL results by column type.
+ *
+ * `zo.database.query`, `zo.database.execute` and `zo.database.migrate` return
+ * values in the System API's value encoding: `NULL` as `null`, `boolean` as a
+ * JSON boolean, `smallint` and `integer` as numbers, arrays as nested JSON
+ * arrays, and every other type as the string Postgres prints under Zo's output
+ * settings (`DateStyle = ISO`, `IntervalStyle = iso_8601`, `TimeZone = UTC`,
+ * `bytea_output = hex`, `extra_float_digits = 1`). These functions turn those
+ * strings into JavaScript values by `columns[].type` without losing anything
+ * by default: a `Date` would drop microseconds and cannot hold every Postgres
+ * year, so it is opt-in. A call that changes those settings itself gets text
+ * the parsers here refuse; decode it with the `"string"` modes.
+ */
+import type { JsonValue } from "./json.ts";
+/** One entry of a SQL result's `columns`. */
+export interface DatabaseColumn {
+    readonly name: string;
+    /** The type as `format_type` prints it, without modifiers: `integer`, `text[]`, `timestamp with time zone`. */
+    readonly type: string;
+}
+/** The part of one SQL result (an entry of `results`) that decoding reads. */
+export interface DatabaseResult {
+    readonly columns: readonly DatabaseColumn[];
+    readonly rows: readonly (readonly unknown[])[];
+}
+export interface DatabaseDecodeOptions {
+    /**
+     * `"parse"` (the default) returns `JSON.parse`'s result for `json` and
+     * `jsonb`. `"string"` keeps Postgres's text, for documents holding numbers a
+     * JavaScript number cannot represent exactly, such as integers past 2^53.
+     */
+    readonly json?: "parse" | "string";
+    /**
+     * How `date`, `timestamp` and `timestamp with time zone` values decode.
+     * `"parse"` (the default) returns a `DatabaseDate` or `DatabaseTimestamp`.
+     * `"string"` keeps Postgres's text. `"date"` returns a `Date`, dropping
+     * microseconds, and throws `RangeError` for a value past a `Date`'s range
+     * (after the year 275760). `infinity` and `-infinity` stay those strings in
+     * every mode.
+     */
+    readonly timestamps?: "parse" | "string" | "date";
+}
+/** A decoded value. Which member a column holds follows from its type; see `decodeDatabaseValue`. */
+export type DatabaseValue = JsonValue | bigint | Uint8Array | Date | DatabaseDate | DatabaseTimestamp | readonly DatabaseValue[];
+export interface DatabaseDateFields {
+    /** ISO year: 1 BC is 0, 2 BC is -1. */
+    readonly year: number;
+    /** 1 to 12. */
+    readonly month: number;
+    /** 1 to 31. */
+    readonly day: number;
+}
+export interface DatabaseTimestampFields extends DatabaseDateFields {
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    /** 0 to 999999. */
+    readonly microsecond: number;
+    /**
+     * Seconds east of UTC for a `timestamp with time zone`, whose other fields
+     * are local time at that offset (always 0 under Zo's settings). `null` for a
+     * `timestamp`, which has no zone.
+     */
+    readonly offsetSeconds: number | null;
+}
+/** A finite Postgres `date`, with every year Postgres holds. */
+export declare class DatabaseDate implements DatabaseDateFields {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    constructor(fields: DatabaseDateFields);
+    /** UTC midnight of this date. Throws `RangeError` past a `Date`'s range. */
+    toDate(): Date;
+    /** The date as Postgres prints it under `DateStyle = ISO`: `2026-11-02`, `0044-03-15 BC`. */
+    toString(): string;
+    toJSON(): string;
+}
+/** A finite Postgres `timestamp` or `timestamp with time zone`, to the microsecond. */
+export declare class DatabaseTimestamp implements DatabaseTimestampFields {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    readonly microsecond: number;
+    readonly offsetSeconds: number | null;
+    constructor(fields: DatabaseTimestampFields);
+    /**
+     * The instant as a `Date`, dropping microseconds. A `timestamp` without a
+     * zone is read as UTC. Throws `RangeError` past a `Date`'s range.
+     */
+    toDate(): Date;
+    /** The timestamp as Postgres prints it under `DateStyle = ISO`: `2026-11-02 18:04:11.52+00`. */
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * Decode one value of a column whose `columns[].type` is `type`.
+ *
+ * | Type | Decoded |
+ * | --- | --- |
+ * | any `NULL` | `null` |
+ * | `boolean`, `smallint`, `integer` | as sent |
+ * | `bigint` | `bigint` |
+ * | `real`, `double precision` | `number`, including `NaN`, `Infinity` and `-0` |
+ * | `json`, `jsonb` | the parsed document, or its text with `json: "string"` |
+ * | `date` | `DatabaseDate`, `Date`, or text, by `timestamps` |
+ * | `timestamp without time zone`, `timestamp with time zone` | `DatabaseTimestamp`, `Date`, or text, by `timestamps` |
+ * | `bytea` | `Uint8Array` |
+ * | arrays (`text[]`) | arrays, nested as sent, with elements decoded by the element type |
+ * | everything else, including `numeric` | the string as sent |
+ *
+ * Throws `TypeError` when the value does not have the form its type's encoding
+ * gives, and `RangeError` when `timestamps: "date"` meets a value a `Date`
+ * cannot hold.
+ */
+export declare function decodeDatabaseValue(type: string, value: unknown, options?: DatabaseDecodeOptions): DatabaseValue;
+/**
+ * Decode every row of one SQL result by its columns' types. Rows stay arrays
+ * in column order, as sent, so duplicate column names survive.
+ */
+export declare function decodeDatabaseRows(result: DatabaseResult, options?: DatabaseDecodeOptions): DatabaseValue[][];

package/dist/core/database.js

@@ -0,0 +1,314 @@
+/** A finite Postgres `date`, with every year Postgres holds. */
+export class DatabaseDate {
+    year;
+    month;
+    day;
+    constructor(fields) {
+        checkDateFields(fields);
+        this.year = fields.year;
+        this.month = fields.month;
+        this.day = fields.day;
+    }
+    /** UTC midnight of this date. Throws `RangeError` past a `Date`'s range. */
+    toDate() {
+        return utcDate(this, 0, 0, 0, 0, 0, this);
+    }
+    /** The date as Postgres prints it under `DateStyle = ISO`: `2026-11-02`, `0044-03-15 BC`. */
+    toString() {
+        return `${formatYearDate(this)}${bcSuffix(this.year)}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/** A finite Postgres `timestamp` or `timestamp with time zone`, to the microsecond. */
+export class DatabaseTimestamp {
+    year;
+    month;
+    day;
+    hour;
+    minute;
+    second;
+    microsecond;
+    offsetSeconds;
+    constructor(fields) {
+        checkDateFields(fields);
+        checkField("hour", fields.hour, 0, 23);
+        checkField("minute", fields.minute, 0, 59);
+        checkField("second", fields.second, 0, 59);
+        checkField("microsecond", fields.microsecond, 0, 999_999);
+        if (fields.offsetSeconds !== null)
+            checkField("offsetSeconds", fields.offsetSeconds, -MAX_OFFSET_SECONDS, MAX_OFFSET_SECONDS);
+        this.year = fields.year;
+        this.month = fields.month;
+        this.day = fields.day;
+        this.hour = fields.hour;
+        this.minute = fields.minute;
+        this.second = fields.second;
+        this.microsecond = fields.microsecond;
+        this.offsetSeconds = fields.offsetSeconds;
+    }
+    /**
+     * The instant as a `Date`, dropping microseconds. A `timestamp` without a
+     * zone is read as UTC. Throws `RangeError` past a `Date`'s range.
+     */
+    toDate() {
+        return utcDate(this, this.hour, this.minute, this.second, Math.floor(this.microsecond / 1000), this.offsetSeconds ?? 0, this);
+    }
+    /** The timestamp as Postgres prints it under `DateStyle = ISO`: `2026-11-02 18:04:11.52+00`. */
+    toString() {
+        const fraction = this.microsecond === 0
+            ? ""
+            : `.${String(this.microsecond).padStart(6, "0").replace(/0+$/, "")}`;
+        const offset = this.offsetSeconds === null ? "" : formatOffset(this.offsetSeconds);
+        return `${formatYearDate(this)} ${pad2(this.hour)}:${pad2(this.minute)}:${pad2(this.second)}${fraction}${offset}${bcSuffix(this.year)}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/**
+ * Decode one value of a column whose `columns[].type` is `type`.
+ *
+ * | Type | Decoded |
+ * | --- | --- |
+ * | any `NULL` | `null` |
+ * | `boolean`, `smallint`, `integer` | as sent |
+ * | `bigint` | `bigint` |
+ * | `real`, `double precision` | `number`, including `NaN`, `Infinity` and `-0` |
+ * | `json`, `jsonb` | the parsed document, or its text with `json: "string"` |
+ * | `date` | `DatabaseDate`, `Date`, or text, by `timestamps` |
+ * | `timestamp without time zone`, `timestamp with time zone` | `DatabaseTimestamp`, `Date`, or text, by `timestamps` |
+ * | `bytea` | `Uint8Array` |
+ * | arrays (`text[]`) | arrays, nested as sent, with elements decoded by the element type |
+ * | everything else, including `numeric` | the string as sent |
+ *
+ * Throws `TypeError` when the value does not have the form its type's encoding
+ * gives, and `RangeError` when `timestamps: "date"` meets a value a `Date`
+ * cannot hold.
+ */
+export function decodeDatabaseValue(type, value, options = {}) {
+    const settings = resolveOptions(options);
+    try {
+        return decodeAny(type, value, settings);
+    }
+    catch (error) {
+        throw withContext(error, `Cannot decode a value of type ${type}`);
+    }
+}
+/**
+ * Decode every row of one SQL result by its columns' types. Rows stay arrays
+ * in column order, as sent, so duplicate column names survive.
+ */
+export function decodeDatabaseRows(result, options = {}) {
+    const settings = resolveOptions(options);
+    const { columns } = result;
+    return result.rows.map((row, rowIndex) => {
+        if (row.length !== columns.length)
+            throw new TypeError(`Cannot decode row ${rowIndex}: it has ${row.length} values for ${columns.length} columns.`);
+        return columns.map((column, columnIndex) => {
+            try {
+                return decodeAny(column.type, row[columnIndex], settings);
+            }
+            catch (error) {
+                throw withContext(error, `Cannot decode row ${rowIndex}, column ${columnIndex} (${JSON.stringify(column.name)}, ${column.type})`);
+            }
+        });
+    });
+}
+const JSON_MODES = ["parse", "string"];
+const TIMESTAMP_MODES = ["parse", "string", "date"];
+/** Postgres refuses a UTC offset past 15:59:59. */
+const MAX_OFFSET_SECONDS = 15 * 3600 + 59 * 60 + 59;
+function resolveOptions(options) {
+    const json = options.json ?? "parse";
+    const timestamps = options.timestamps ?? "parse";
+    if (!JSON_MODES.includes(json))
+        throw new TypeError(`json must be "parse" or "string", not ${JSON.stringify(json)}.`);
+    if (!TIMESTAMP_MODES.includes(timestamps))
+        throw new TypeError(`timestamps must be "parse", "string" or "date", not ${JSON.stringify(timestamps)}.`);
+    return { json, timestamps };
+}
+function decodeAny(type, value, settings) {
+    if (value === null)
+        return null;
+    const element = type.replace(/(\[\])+$/, "");
+    if (element !== type)
+        return decodeArray(element, value, settings);
+    return decodeScalar(type, value, settings);
+}
+function decodeArray(element, value, settings) {
+    if (!Array.isArray(value))
+        throw new TypeError("expected an array");
+    return value.map((item) => {
+        if (item === null)
+            return null;
+        if (Array.isArray(item))
+            return decodeArray(element, item, settings);
+        return decodeScalar(element, item, settings);
+    });
+}
+function decodeScalar(type, value, settings) {
+    switch (type) {
+        case "boolean":
+            if (typeof value !== "boolean")
+                throw new TypeError("expected a boolean");
+            return value;
+        case "smallint":
+        case "integer":
+            if (typeof value !== "number" || !Number.isInteger(value))
+                throw new TypeError("expected an integer");
+            return value;
+        case "bigint":
+            return BigInt(match(value, BIGINT, "an integer string")[0]);
+        case "real":
+        case "double precision":
+            return Number(match(value, FLOAT, "a float string")[0]);
+        case "json":
+        case "jsonb":
+            return settings.json === "string" ? text(value) : parseJson(text(value));
+        case "bytea":
+            return decodeBytea(value);
+        case "date":
+            return decodeDate(value, settings);
+        case "timestamp without time zone":
+            return decodeTimestamp(value, settings, false);
+        case "timestamp with time zone":
+            return decodeTimestamp(value, settings, true);
+        default:
+            // `numeric` and every other type are sent as text. A domain is named
+            // by its base type, so only the cases above carry numbers or booleans.
+            return text(value);
+    }
+}
+const BIGINT = /^-?\d+$/;
+// Exactly what float8out prints; Number() also reads "infinity" and "nan" as NaN.
+const FLOAT = /^(?:-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|NaN|-?Infinity)$/;
+const BYTEA = /^\\x(?<hex>(?:[0-9a-f]{2})*)$/i;
+const DATE = /^(?<year>\d{4,})-(?<month>\d{2})-(?<day>\d{2})(?<bc> BC)?$/;
+const TIMESTAMP = /^(?<year>\d{4,})-(?<month>\d{2})-(?<day>\d{2}) (?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.(?<fraction>\d{1,6}))?(?:(?<sign>[+-])(?<offsetHour>\d{2})(?::(?<offsetMinute>\d{2}))?(?::(?<offsetSecond>\d{2}))?)?(?<bc> BC)?$/;
+function text(value) {
+    if (typeof value !== "string")
+        throw new TypeError("expected a string");
+    return value;
+}
+function match(value, pattern, expected) {
+    const found = pattern.exec(text(value));
+    if (!found)
+        throw new TypeError(`expected ${expected}`);
+    return found;
+}
+/** A matched pattern's named groups; an unmatched optional group is absent. */
+function groups(pattern, source) {
+    return pattern.exec(source)?.groups;
+}
+function parseJson(source) {
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new TypeError("expected a JSON document", { cause: error });
+    }
+}
+function decodeBytea(value) {
+    const hex = match(value, BYTEA, 'hex output ("\\x…")').groups?.hex ?? "";
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++)
+        bytes[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+    return bytes;
+}
+function isInfinity(value) {
+    return value === "infinity" || value === "-infinity";
+}
+function decodeDate(value, settings) {
+    const source = text(value);
+    if (settings.timestamps === "string" || isInfinity(source))
+        return source;
+    const parts = groups(DATE, source);
+    if (!parts)
+        throw new TypeError(NOT_ISO);
+    const { year = "", month, day, bc } = parts;
+    const date = new DatabaseDate({
+        year: isoYear(year, bc),
+        month: Number(month),
+        day: Number(day),
+    });
+    return settings.timestamps === "date" ? date.toDate() : date;
+}
+function decodeTimestamp(value, settings, zoned) {
+    const source = text(value);
+    if (settings.timestamps === "string" || isInfinity(source))
+        return source;
+    const parts = groups(TIMESTAMP, source);
+    if (!parts || (parts.sign !== undefined) !== zoned)
+        throw new TypeError(NOT_ISO);
+    const { year = "", month, day, hour, minute, second, fraction = "", sign, bc, } = parts;
+    let offsetSeconds = null;
+    if (sign !== undefined) {
+        const { offsetHour, offsetMinute = "0", offsetSecond = "0" } = parts;
+        const magnitude = Number(offsetHour) * 3600 +
+            Number(offsetMinute) * 60 +
+            Number(offsetSecond);
+        offsetSeconds = sign === "-" && magnitude !== 0 ? -magnitude : magnitude;
+    }
+    const timestamp = new DatabaseTimestamp({
+        year: isoYear(year, bc),
+        month: Number(month),
+        day: Number(day),
+        hour: Number(hour),
+        minute: Number(minute),
+        second: Number(second),
+        microsecond: Number(fraction.padEnd(6, "0")),
+        offsetSeconds,
+    });
+    return settings.timestamps === "date" ? timestamp.toDate() : timestamp;
+}
+const NOT_ISO = 'expected Postgres ISO output; if the call changed DateStyle or TimeZone, decode with timestamps: "string"';
+/** Postgres prints 1 BC as `0001 BC`; ISO numbers it 0. */
+function isoYear(digits, bc) {
+    const year = Number(digits);
+    return bc === undefined ? year : 1 - year;
+}
+function utcDate(date, hour, minute, second, millisecond, offsetSeconds, source) {
+    // Date.UTC maps years 0 to 99 onto 1900 to 1999, so set the year separately.
+    const local = new Date(0);
+    local.setUTCFullYear(date.year, date.month - 1, date.day);
+    local.setUTCHours(hour, minute, second, millisecond);
+    const instant = new Date(local.getTime() - offsetSeconds * 1000);
+    if (Number.isNaN(instant.getTime()))
+        throw new RangeError(`${source} is outside the range of a Date`);
+    return instant;
+}
+function checkDateFields(fields) {
+    checkField("year", fields.year, -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+    checkField("month", fields.month, 1, 12);
+    checkField("day", fields.day, 1, 31);
+}
+function checkField(name, value, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new RangeError(`${name} must be an integer from ${min} to ${max}, not ${value}.`);
+}
+function pad2(value) {
+    return String(value).padStart(2, "0");
+}
+function formatYearDate(date) {
+    const year = date.year > 0 ? date.year : 1 - date.year;
+    return `${String(year).padStart(4, "0")}-${pad2(date.month)}-${pad2(date.day)}`;
+}
+function bcSuffix(year) {
+    return year > 0 ? "" : " BC";
+}
+function formatOffset(offsetSeconds) {
+    const sign = offsetSeconds < 0 ? "-" : "+";
+    const total = Math.abs(offsetSeconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    return `${sign}${pad2(hours)}${minutes || seconds ? `:${pad2(minutes)}` : ""}${seconds ? `:${pad2(seconds)}` : ""}`;
+}
+function withContext(error, context) {
+    if (!(error instanceof Error))
+        return new TypeError(context, { cause: error });
+    const ErrorType = error instanceof RangeError ? RangeError : TypeError;
+    return new ErrorType(`${context}: ${error.message}`, { cause: error });
+}