@crvouga/postgres-mem 1.0.1 → 1.1.0

package/dist/indexes/index.d.ts

@@ -0,0 +1,14 @@
+/** Btree / hash index over row indices. Keys are pre-serialized (datumKey tuples). */
+export declare class IndexStore {
+    readonly name: string;
+    readonly unique: boolean;
+    private entries;
+    constructor(name: string, unique?: boolean);
+    get size(): number;
+    checkUnique(key: string, rowIdx?: number): void;
+    insert(key: string, rowIdx: number): void;
+    remove(key: string, rowIdx: number): void;
+    lookup(key: string): readonly number[];
+    clear(): void;
+    clone(): IndexStore;
+}

package/dist/indexes/maintain.d.ts

@@ -0,0 +1,11 @@
+import { type UniqueSpec } from "../constraints/enforce.js";
+import type { ExecEnv } from "../executor/relation.js";
+import type { TableData } from "../storage/database-state.js";
+import type { Datum } from "../types/value.js";
+import { IndexStore } from "./index.js";
+export declare function invalidateTableIndexes(table: TableData): void;
+export declare function indexStoreFor(env: ExecEnv, table: TableData, spec: UniqueSpec): IndexStore;
+export declare function indexInsertRow(env: ExecEnv, table: TableData, rowIdx: number, row: Datum[]): void;
+export declare function indexRemoveRow(env: ExecEnv, table: TableData, rowIdx: number, row: Datum[]): void;
+export declare function indexUpdateRow(env: ExecEnv, table: TableData, rowIdx: number, oldRow: Datum[], newRow: Datum[]): void;
+export declare function rebuildTableIndexes(env: ExecEnv, table: TableData): void;

package/dist/parser/parser.d.ts

@@ -20,6 +20,8 @@ export declare class Parser {
     parseStatements(): Statement[];
     parseStatement(): Statement;
     private skipToStatementEnd;
+    /** Consume tokens until the matching `)` after an opening `(` already eaten. */
+    private skipBalancedCloseParen;
     private parseWithableStatement;
     private parseWithClause;
     parseSelectStmt(withClause?: WithClause | null): SelectStmt;

package/dist/planner/access.d.ts

@@ -0,0 +1,15 @@
+import type { Expr, FromItem } from "../ast/nodes.js";
+import { type ExecEnv } from "../executor/relation.js";
+import type { TableData } from "../storage/database-state.js";
+import { type Datum, type TypeId } from "../types/value.js";
+export interface ConstEquality {
+    column: string;
+    valueExpr: Expr;
+}
+export declare function equalityAgainstConst(expr: Expr): ConstEquality | null;
+export declare function conjunctions(expr: Expr): Expr[];
+/** Single-table PK / unique equality lookup: returns matching rows or null to scan. */
+export declare function tryIndexedTableRows(env: ExecEnv, table: TableData, alias: string, where: Expr): Datum[][] | null;
+export declare function tryIndexedFromItem(env: ExecEnv, item: FromItem, where: Expr | null): Datum[][] | null;
+export declare function joinKeyFromRow(row: Datum[], colIdxs: number[], srcTypes: TypeId[], unifiedTypes: TypeId[], ctx: import("../expressions/context.js").EngineCtx): string | null;
+export declare function rowsMatchEqKeys(ctx: import("../expressions/context.js").EngineCtx, left: Datum[], right: Datum[], leftIdxs: number[], rightIdxs: number[], leftTypes: TypeId[], rightTypes: TypeId[], unifiedTypes: TypeId[]): boolean;

package/dist/runtime/assert.d.ts

@@ -0,0 +1,5 @@
+/** Internal invariant failure — not a user SQL error. */
+export declare function assert(condition: boolean, message: string): asserts condition;
+export declare function assertDefined<T>(value: T | null | undefined, message: string): T;
+export declare function assertBounds(value: number, min: number, max: number, label: string): void;
+export declare function assertNever(value: never, message?: string): never;

package/dist/runtime/index.d.ts

@@ -1,3 +1,3 @@
 export { type Clock, DEFAULT_NOW, fixedClock, resolveClock, systemClock } from "./clock.js";
-export { type DatabaseOptions, DEFAULT_DATABASE_SEED, type RandomMode } from "./options.js";
+export { type DatabaseOptions, DEFAULT_DATABASE_SEED, type Int8Mode, type RandomMode } from "./options.js";
 export { deriveSeed, OsEntropy, Prng } from "./prng.js";

package/dist/runtime/options.d.ts

@@ -1,6 +1,8 @@
 import type { Clock } from "./clock.js";
 /** Entropy source for `random()` / `gen_random_uuid()`. Default is seeded xorshift64*. */
 export type RandomMode = "deterministic" | "os";
+/** How `int8` columns surface in query row objects. Default `"bigint"`. */
+export type Int8Mode = "bigint" | "number" | "string";
 /** Options for {@link Database} construction. All fields are optional. */
 export interface DatabaseOptions {
     /**
@@ -20,6 +22,13 @@ export interface DatabaseOptions {
      * Pass a `Date`, `() => Date`, or `"system"` for wall-clock `now()` like PostgreSQL.
      */
     now?: Date | Clock | "system";
+    /**
+     * How `int8` / `bigint` columns surface in query row objects.
+     * Default `"bigint"` matches PostgreSQL's JS-unsafe 64-bit integers.
+     * `"number"` uses IEEE number (unsafe beyond `Number.MAX_SAFE_INTEGER`).
+     * `"string"` is JSON-safe.
+     */
+    int8?: Int8Mode;
 }
 /** Default {@link DatabaseOptions.seed} when constructing a {@link Database}. */
 export declare const DEFAULT_DATABASE_SEED = 1;

package/dist/serialization/codec.d.ts

@@ -1,29 +1,22 @@
 import type { Clock } from "../runtime/clock.js";
 import type { Prng } from "../runtime/prng.js";
 import { DatabaseState } from "../storage/database-state.js";
-/** PRNG + clock captured alongside catalog/rows in a snapshot. */
+/** PRNG + clock captured alongside catalog/rows. */
 export interface SnapshotRuntime {
-    /** Unsigned 64-bit {@link Prng} state. */
     prngState: bigint;
-    /** Clock instant as milliseconds since Unix epoch. */
     nowMs: number;
 }
 /** Result of {@link decodeDatabaseState}. */
 export interface DecodedSnapshot {
-    /** Restored catalog and table data. */
     state: DatabaseState;
     runtime: SnapshotRuntime | null;
 }
 /**
  * Encode catalog, rows, and runtime into a postgres-mem `PGMM` snapshot blob
  * (not an on-disk PostgreSQL format).
- *
- * Prefer {@link Database.snapshot} unless you are serializing engine state directly.
  */
 export declare function encodeDatabaseState(state: DatabaseState, runtime: SnapshotRuntime): Uint8Array;
 /**
  * Decode a blob from {@link encodeDatabaseState} / {@link Database.snapshot}.
- *
- * @throws {PostgresError} If the magic, version, or payload is invalid.
  */
 export declare function decodeDatabaseState(snapshot: Uint8Array, prng: Prng, clock: Clock): DecodedSnapshot;

package/dist/serialization/wire.d.ts

@@ -0,0 +1,63 @@
+export declare function utf8Encode(s: string): Uint8Array;
+export declare function utf8Decode(b: Uint8Array): string;
+export declare function writeVarintU32(w: Writer, value: number): void;
+export declare function readVarintU32(r: Reader): number;
+export declare class Writer {
+    private buf;
+    private view;
+    private len;
+    constructor(capacity?: number);
+    get position(): number;
+    reserve(capacity: number): void;
+    private ensure;
+    align4(): void;
+    u8(value: number): void;
+    u32(value: number): void;
+    i32(value: number): void;
+    u64(value: bigint): void;
+    i64(value: bigint): void;
+    f64(value: number): void;
+    raw(value: Uint8Array): void;
+    /** Length-prefixed UTF-8. */
+    text(value: string): void;
+    /** Write UTF-8 at current position without length prefix (intern blob region). */
+    textBytes(value: string): void;
+    finish(): Uint8Array;
+    fail(): never;
+}
+export declare class Reader {
+    private readonly bytes;
+    private offset;
+    private readonly view;
+    constructor(bytes: Uint8Array);
+    get position(): number;
+    skipAlign4(): void;
+    u8(): number;
+    u32(): number;
+    i32(): number;
+    u64(): bigint;
+    i64(): bigint;
+    f64(): number;
+    raw(length: number): Uint8Array;
+    text(): string;
+    remaining(): number;
+    done(): boolean;
+    fail(): never;
+}
+export declare function writeBjv(w: Writer, value: unknown, forceIntern: (s: string) => number): void;
+export declare function readBjv(r: Reader, intern: readonly string[]): unknown;
+export declare class InternPool {
+    private readonly counts;
+    private readonly ids;
+    readonly list: string[];
+    constructor();
+    count(s: string): void;
+    /** Assign ids only to strings seen ≥2 times (plus empty string). */
+    finalize(): void;
+    /** Always intern (schema / catalog strings). */
+    forceId(s: string): number;
+    id(s: string): number;
+}
+/** Write intern table: count, offsets[], concatenated UTF-8 blob. */
+export declare function writeInternTable(w: Writer, strings: readonly string[]): void;
+export declare function readInternTable(r: Reader): string[];

package/dist/storage/columnar-slab.d.ts

@@ -0,0 +1,37 @@
+import type { Datum } from "../types/value.js";
+/** Column pack tags (PGMM v3). */
+export declare const PACK_NULL = 0;
+export declare const PACK_BOOL = 1;
+export declare const PACK_FLOAT = 2;
+export declare const PACK_INT = 3;
+export declare const PACK_TEXT_INTERN = 4;
+export declare const PACK_TEXT_INLINE = 5;
+export declare const PACK_BLOB = 6;
+export declare const PACK_TAGGED = 7;
+export interface SlabColumn {
+    pack: number;
+    nullBitmap: Uint8Array | null;
+    /** Prefix sum of non-null rows for O(1) null-index lookup. */
+    nonNullPrefix?: Uint32Array;
+    /** Typed payload or inline blob region inside `buffer`. */
+    payload: Uint8Array;
+    /** For PACK_TEXT_INLINE: u32 offsets into payload per row. */
+    inlineOffsets?: Uint32Array;
+    /** For PACK_TAGGED: decoded values per non-null row in order. */
+    tagged?: Datum[];
+    /** For PACK_BLOB: one entry per non-null row (zero-copy views). */
+    blobChunks?: Uint8Array[];
+}
+/** Frozen columnar row storage; zero-copy views into snapshot buffer. */
+export declare class ColumnarSlab {
+    readonly buffer: Uint8Array;
+    readonly rowCount: number;
+    readonly columns: SlabColumn[];
+    private readonly intern;
+    constructor(buffer: Uint8Array, rowCount: number, columns: SlabColumn[], intern: readonly string[]);
+    cell(rowIndex: number, col: number): Datum;
+    rowAt(rowIndex: number): Datum[];
+    scan(): Generator<Datum[]>;
+    materialize(): Datum[][];
+}
+export declare function packKindOf(value: Datum): number;

package/dist/storage/database-state.d.ts

@@ -1,6 +1,7 @@
 import type { CreateTriggerStmt, Expr, SelectStmt, Statement } from "../ast/nodes.js";
 import type { Clock } from "../runtime/clock.js";
 import type { Prng } from "../runtime/prng.js";
+import type { ColumnarSlab } from "./columnar-slab.js";
 import { type ColumnType, type Datum, type TypeId } from "../types/value.js";
 export interface ColumnMeta {
     name: string;
@@ -72,14 +73,33 @@ export declare class TableData {
     schema: string;
     columns: ColumnMeta[];
     rows: Datum[][];
+    /** Frozen columnar storage after snapshot hydrate; `rows` stays empty until materialized. */
+    slab: ColumnarSlab | null;
     constraints: ConstraintMeta[];
     triggers: TriggerMeta[];
     temp: boolean;
     /** monotonically increasing oid-like id for catalog output */
     readonly oid: number;
+    /** >0 while shared with a clone or transaction snapshot. */
+    shareCount: number;
+    /** Derived unique/btree index maps; null until built or invalidated. */
+    indexStores: Map<string, import("../indexes/index.js").IndexStore> | null;
     constructor(schema: string, name: string, columns: ColumnMeta[], oid: number, temp?: boolean);
+    rowCount(): number;
+    rowAt(index: number): Datum[];
+    /** All rows for scans; materializes slab once into `rows` when needed. */
+    allRows(): Datum[][];
+    attachSlab(slab: ColumnarSlab): void;
+    materializeSlab(): void;
+    /** Writable row storage; materializes slab if needed. */
+    mutableRows(): Datum[][];
+    get frozen(): boolean;
+    freeze(): void;
+    thaw(): void;
     columnIndex(name: string): number;
     clone(): TableData;
+    /** Independent writable copy (row tuples copied so ALTER COLUMN is isolated). */
+    cloneForWrite(): TableData;
 }
 export interface ViewData {
     name: string;
@@ -95,6 +115,7 @@ export interface ViewData {
     }> | null;
     temp: boolean;
     oid: number;
+    shareCount?: number;
 }
 export interface SequenceData {
     name: string;
@@ -114,12 +135,14 @@ export interface SequenceData {
     dataType: TypeId;
     temp: boolean;
     oid: number;
+    shareCount?: number;
 }
 export interface EnumData {
     name: string;
     schema: string;
     labels: string[];
     oid: number;
+    shareCount?: number;
 }
 export interface DomainData {
     name: string;
@@ -132,6 +155,7 @@ export interface DomainData {
         expr: Expr;
     }>;
     oid: number;
+    shareCount?: number;
 }
 export interface FunctionData {
     name: string;
@@ -150,6 +174,7 @@ export interface FunctionData {
     rawBody: string | null;
     strict: boolean;
     oid: number;
+    jsImpl?: (...args: Array<null | boolean | number | bigint | string | Uint8Array>) => null | boolean | number | bigint | string | Uint8Array;
 }
 export declare class SchemaData {
     name: string;
@@ -165,6 +190,8 @@ export declare class SchemaData {
     /** all relation names (tables, views, sequences, indexes share pg_class namespace) */
     hasRelation(name: string): boolean;
     clone(): SchemaData;
+    /** Share table/sequence objects; copy maps so CREATE/DROP is isolated. */
+    cloneShallow(): SchemaData;
 }
 export interface PreparedStatement {
     name: string;
@@ -209,8 +236,16 @@ export declare class DatabaseState {
     findEnumByKey(key: string): EnumData | null;
     /** format_type()-style display name for a type OID (builtin or enum). */
     typeNameForOid(oid: number): string | null;
-    /** deep clone for transaction snapshots (datums are immutable; rows copied) */
+    /** deep clone (datums are immutable; rows copied) */
     clone(): DatabaseState;
+    /** Share frozen catalog objects; copy maps so CREATE/DROP is isolated. */
+    cloneShallow(): DatabaseState;
+    freezeShared(): void;
+    thawShared(): void;
+    ensureWritableTable(table: TableData): TableData;
+    ensureWritableSequence(seq: SequenceData): SequenceData;
+    ensureWritableView(view: ViewData): ViewData;
+    ensureWritableEnum(en: EnumData): EnumData;
     /** copy the contents of `other` into this state (rollback restore) */
     restoreFrom(other: DatabaseState): void;
 }

package/dist/transactions/manager.d.ts

@@ -1,18 +1,19 @@
 import type { DatabaseState } from "../storage/database-state.js";
 /**
- * Single-session transaction manager: BEGIN clones the whole state (datums are
- * immutable; rows are copied), ROLLBACK restores it. Savepoints stack inner
- * snapshots. The PRNG state participates so `random()` draws rewind on
- * rollback (determinism invariant, mirrors sqlite-mem).
+ * Single-session transaction manager with copy-on-write snapshots: BEGIN /
+ * SAVEPOINT freeze shared catalog objects and capture a shallow clone; writes
+ * copy-on-write via ensureWritableTable. ROLLBACK restores the snapshot.
  */
 export declare class TransactionManager {
     private readonly state;
     private base;
     private savepoints;
+    private freezeDepth;
     constructor(state: DatabaseState);
     get inTransaction(): boolean;
     private takeSnapshot;
     private restore;
+    private thawOnce;
     begin(): void;
     commit(): void;
     rollback(): void;
@@ -20,6 +21,5 @@ export declare class TransactionManager {
     releaseSavepoint(name: string): void;
     rollbackToSavepoint(name: string): void;
     private findSavepoint;
-    /** abort any open transaction without restoring (used by Database.close) */
     reset(): void;
 }

package/dist/types/jsonpath.d.ts

@@ -0,0 +1,16 @@
+import type { JsonbValue } from "./jsonb.js";
+type PathStep = {
+    kind: "member";
+    name: string;
+} | {
+    kind: "index";
+    index: number;
+};
+/** Parse a SQL/JSON path subset: `$`, `.key`, `."key"`, `[n]`. */
+export declare function parseJsonpath(text: string): PathStep[];
+/**
+ * First match of a jsonpath against a jsonb document.
+ * Missing path → SQL NULL (`null` return). JSON null is `{ j: "null" }`.
+ */
+export declare function jsonpathQueryFirst(doc: JsonbValue, pathText: string): JsonbValue | null;
+export {};