@crvouga/mockingbird-service-postgres 0.1.0

package/dist/api/bind.d.ts

@@ -0,0 +1,11 @@
+import type { Int8Mode } from "../runtime/options.js";
+import { type Datum, type OutputCtx, type TypedValue, type TypeId } from "../types/value.js";
+/** JavaScript values accepted as query parameters (`$1..$n`). */
+export type BindValue = null | undefined | boolean | number | bigint | string | Uint8Array | Date;
+/** JavaScript values produced in query result rows. */
+export type JsValue = null | boolean | number | bigint | string | Uint8Array;
+/** A result row keyed by column name. */
+export type QueryRow = Record<string, JsValue>;
+export declare function bindValueToTyped(value: BindValue, index: number): TypedValue;
+/** Convert an engine datum to the public JS value for result rows. */
+export declare function datumToJs(t: TypeId, v: Datum, ctx: OutputCtx, int8?: Int8Mode): JsValue;

package/dist/api/database.d.ts

@@ -0,0 +1,87 @@
+import { type DatabaseOptions, type Int8Mode, type RandomMode } from "../runtime/index.js";
+import type { BindValue, JsValue, QueryRow } from "./bind.js";
+import { type Snapshot } from "./snapshot.js";
+import { Statement } from "./statement.js";
+/**
+ * Pure TypeScript in-memory PostgreSQL database.
+ *
+ * Deterministic by default: `random()` / `gen_random_uuid()` use a seeded PRNG
+ * (`seed` defaults to `1`) and `now()` / `current_timestamp` use a fixed clock
+ * (`2000-01-01T00:00:00.000Z`). Pass `{ random: "os" }` and `{ now: "system" }`
+ * for PostgreSQL-like entropy and wall-clock time. No filesystem, no WASM.
+ *
+ * @example
+ * ```ts
+ * import { Database } from "@crvouga/mockingbird-service-postgres";
+ *
+ * const db = new Database();
+ * db.exec("CREATE TABLE users (id serial PRIMARY KEY, name text NOT NULL)");
+ * db.prepare("INSERT INTO users (name) VALUES ($1)").run("Alice");
+ * const users = db.query<{ id: number; name: string }>("SELECT * FROM users");
+ * ```
+ */
+export declare class Database {
+    /** Seed used to construct the PRNG. Ignored when {@link randomMode} is `"os"`. */
+    readonly seed: number | bigint;
+    /** Entropy mode for `random()` / `gen_random_uuid()`. */
+    readonly randomMode: RandomMode;
+    /** How `int8` columns surface in query rows. */
+    readonly int8Mode: Int8Mode;
+    private closed;
+    private transactionSequence;
+    private apiTransactionDepth;
+    constructor(options?: DatabaseOptions);
+    /**
+     * Execute SQL for its side effects. Multiple semicolon-separated statements
+     * are allowed. Does not accept bind parameters — use {@link prepare} / {@link query}.
+     */
+    exec(sql: string): void;
+    /**
+     * Register a JavaScript function callable from SQL. Not encoded in PGMM
+     * snapshots — re-register after {@link Snapshot.decode} / {@link Snapshot.open}.
+     * {@link Snapshot.open} copies the implementation by reference when opening
+     * a live in-memory snapshot.
+     */
+    registerFunction(spec: RegisterFunctionOptions): void;
+    /** Execute a single-statement query and return all rows keyed by column name. */
+    query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[];
+    /** Compile a single SQL statement into a reusable {@link Statement}. */
+    prepare(sql: string): Statement;
+    /**
+     * Run `fn` inside a transaction. Commits on success; rolls back if `fn`
+     * throws. Nested calls use savepoints.
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Freeze this database into a reusable {@link Snapshot} template.
+     * Does not encode PGMM bytes. Call {@link Snapshot.encode} to persist, or
+     * {@link Snapshot.open} for a copy-on-write fork.
+     */
+    snapshot(): Snapshot;
+    /** Close the database. Further SQL throws. Idempotent. */
+    close(): void;
+    /**
+     * Execute `COPY table [(cols)] FROM STDIN` with the given text/csv payload
+     * (the API-level analog of psql's `\copy` / the wire-protocol copy-in stream).
+     * Returns the number of rows copied.
+     *
+     * @example
+     * ```ts
+     * db.copyFrom("COPY t (a, b) FROM STDIN", "1\tx\n2\ty\n");
+     * ```
+     */
+    copyFrom(sql: string, data: string): number;
+    /** Rows affected by the most recent INSERT / UPDATE / DELETE. */
+    get changes(): number;
+    private prepareSingle;
+}
+export { Snapshot } from "./snapshot.js";
+/** Options for {@link Database.registerFunction}. */
+export interface RegisterFunctionOptions {
+    name: string;
+    args: string[];
+    returns: string;
+    strict?: boolean;
+    fn: (...args: JsValue[]) => JsValue;
+}
+export type { DatabaseOptions };

package/dist/api/snapshot.d.ts

@@ -0,0 +1,21 @@
+import { type DatabaseOptions } from "../runtime/index.js";
+import { type Database } from "./database.js";
+/**
+ * Frozen in-memory database template. {@link open} is a copy-on-write fork.
+ * Encoded PGMM bytes are produced lazily via {@link encode}.
+ */
+export declare class Snapshot {
+    private cachedBytes;
+    /** Encoded PGMM blob. Computed once; never mutates a buffer passed to {@link decode}. */
+    encode(): Uint8Array;
+    /**
+     * Copy-on-write database from this frozen template. Does not re-encode or re-decode.
+     */
+    open(options?: DatabaseOptions): Database;
+    /**
+     * Decode `bytes` once and freeze the result. The same `Uint8Array` object
+     * returns the same {@link Snapshot} (WeakMap), so later {@link open} calls
+     * are copy-on-write forks after the first hydrate.
+     */
+    static decode(bytes: Uint8Array): Snapshot;
+}

package/dist/api/statement.d.ts

@@ -0,0 +1,51 @@
+import { type BindValue, type QueryRow } from "./bind.js";
+/** Row-count summary returned by {@link Statement.run}. */
+export interface RunResult {
+    /** Rows affected by the last statement (PostgreSQL command tag count). */
+    rowCount: number;
+    /** Command tag of the last statement, e.g. `"INSERT"`. */
+    command: string;
+}
+/** {@link Statement.textResult}: rows as canonical PostgreSQL text. */
+export interface TextResultSet {
+    columns: string[];
+    columnTypes: string[];
+    rows: (string | null)[][];
+    rowCount: number;
+    command: string;
+}
+/** Full result including column metadata (useful for zero-row results). */
+export interface ResultSet {
+    columns: string[];
+    /** canonical type names per column (PG internal names, e.g. "int4") */
+    columnTypes: string[];
+    rows: QueryRow[];
+    rowCount: number;
+    command: string;
+}
+/**
+ * Prepared SQL statement bound to a {@link Database}. Parameters are
+ * positional PostgreSQL placeholders `$1..$n`, passed per call (stateless).
+ */
+export declare class Statement {
+    private readonly database;
+    private statements;
+    /** The source SQL this statement was prepared from. */
+    readonly sql: string;
+    private constructor();
+    /** Execute for side effects; returns the affected row count. */
+    run(...params: BindValue[]): RunResult;
+    /** Execute and return all rows as objects keyed by column name. */
+    all<T = QueryRow>(...params: BindValue[]): T[];
+    /** Execute and return the first row, or `undefined`. */
+    get<T = QueryRow>(...params: BindValue[]): T | undefined;
+    /**
+     * Execute and return rows rendered as canonical PostgreSQL text (psql-style),
+     * plus column metadata. NULLs stay `null`.
+     */
+    textResult(...params: BindValue[]): TextResultSet;
+    /** Execute and return the full {@link ResultSet} with column metadata. */
+    result(...params: BindValue[]): ResultSet;
+    private execute;
+    private toRows;
+}