@crvouga/postgres-mem 0.1.0

package/dist/api/bind.d.ts

@@ -0,0 +1,10 @@
+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): JsValue;

package/dist/api/database.d.ts

@@ -0,0 +1,69 @@
+import { type DatabaseOptions, type RandomMode } from "../runtime/index.js";
+import type { BindValue, QueryRow } from "./bind.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/postgres-mem";
+ *
+ * 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;
+    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;
+    /** 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;
+    /**
+     * Serialize schema, rows, PRNG state, and clock into a `PGMM` snapshot blob.
+     * Restore with {@link restore}. Not an on-disk PostgreSQL format.
+     */
+    snapshot(): Uint8Array;
+    /** Replace this database's contents with a blob from {@link snapshot}. */
+    restore(snapshot: Uint8Array): void;
+    /** 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 type { DatabaseOptions };

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;
+}