@crvouga/mockingbird-service-sqlite 0.1.0

package/dist/indexes/index.d.ts

@@ -0,0 +1,48 @@
+import type { Rowid } from "../storage/row.js";
+import { type SqlValue } from "../types/value.js";
+export declare class IndexStore {
+    readonly name: string;
+    private entries;
+    private keyValues;
+    private sortedKeys;
+    private mapsShared;
+    frozen: boolean;
+    constructor(name?: string, entries?: ReadonlyMap<string, readonly Rowid[]>, keyValues?: ReadonlyMap<string, readonly SqlValue[]>);
+    checkUnique(values: readonly SqlValue[], rowid?: Rowid): void;
+    insert(values: readonly SqlValue[], rowid: Rowid, unique?: boolean): void;
+    lookup(values: readonly SqlValue[]): readonly Rowid[];
+    /** Leftmost prefix match: INDEX(a,b) used for WHERE a = ?. */
+    lookupPrefix(values: readonly SqlValue[]): readonly Rowid[];
+    /**
+     * Ordered scan of rowids for a single-column comparison.
+     * `op` applies to the first key component.
+     */
+    rangeLookup(op: ">" | ">=" | "<" | "<=" | "between", bound: SqlValue, bound2?: SqlValue): readonly Rowid[];
+    orderedRowids(desc?: boolean): readonly Rowid[];
+    remove(values: readonly SqlValue[], rowid?: Rowid): boolean;
+    clear(): void;
+    clone(): IndexStore;
+    freeze(): void;
+    /** Sorted entries for SQLM v3 persistence. */
+    snapshotEntries(): Array<{
+        key: string;
+        rowids: Rowid[];
+        values: SqlValue[];
+    }>;
+    /** Sorted keys + rowids for SQLM v4 (values rebuilt from the table). */
+    snapshotKeys(): Array<{
+        key: string;
+        rowids: Rowid[];
+    }>;
+    rememberKeyValues(key: string, values: readonly SqlValue[]): void;
+    /** Key component values for snapshot encode (binary keys). */
+    keyValuesFor(key: string): SqlValue[];
+    get size(): number;
+    private orderedKeys;
+    private assertMutable;
+    private forkMaps;
+}
+/** Hash-join / covering-hash key: NULL components never match. */
+export declare function serializeIndexKey(values: readonly SqlValue[]): string | null;
+/** Index-store key: NULL is a distinct component so composite prefix lookups still hit. */
+export declare function serializeIndexEntry(values: readonly SqlValue[]): string;

package/dist/indexes/keys.d.ts

@@ -0,0 +1,15 @@
+import type { IndexedColumn } from "../ast/nodes.js";
+import type { Cell, ExecutionEnv } from "../executor/env.js";
+import type { EvalContext } from "../expressions/context.js";
+import type { IndexInfo } from "../storage/database-state.js";
+import { type Row } from "../storage/row.js";
+import type { Table } from "../storage/table.js";
+import { type SqlValue } from "../types/value.js";
+/** Heap cells for evaluating index expressions / partial `WHERE` via `ExecutionEnv`. */
+export declare function heapRowCells(table: Table, row: Row, env?: ExecutionEnv): Cell[];
+/** Indexed-column values for one heap row (expression indexes included when `ctx` is set). */
+export declare function indexKeyValues(columns: readonly IndexedColumn[], row: Row, ctx?: EvalContext | null, table?: Table): SqlValue[];
+/** Rebuild `index.store` from `table` using the same keys as DML maintenance. */
+export declare function rebuildIndexFromTable(index: IndexInfo, table: Table, ctxForRow: (row: Row) => EvalContext): void;
+/** Snapshot / no-`ExecutionEnv` evaluator for index expressions / partial predicates. */
+export declare function tableRowEvalContext(table: Table, row: Row): EvalContext;

package/dist/json/index.d.ts

@@ -0,0 +1,7 @@
+export { decodeJsonb, encodeJsonb, jsonbToText, looksLikeJsonb, textToJsonb, walkJsonbTree, } from "./jsonb.js";
+export { arrayInsertJson, ensureJson, extractOne, jsonArrowPath, jsonNodeToSql, mutateJson, patchJson, removeJson, sqlToJsonInput, sqlValueToJsonNode, toJsonbBlob, toJsonText, wrapJsonError, } from "./ops.js";
+export { isValidJsonText, JsonParseError, jsonErrorPosition, parseJsonText } from "./parse.js";
+export { parseJsonPath, pathGet } from "./path.js";
+export { jsonQuoteString, prettyJson, stringifyJson } from "./stringify.js";
+export { jsonEachRows, jsonTreeRows } from "./tvf.js";
+export type { JsonNode, JsonTypeName } from "./types.js";

package/dist/json/jsonb.d.ts

@@ -0,0 +1,42 @@
+import type { JsonNode } from "./types.js";
+/** JSONB element types (low nibble). */
+export declare const JB: {
+    readonly NULL: 0;
+    readonly TRUE: 1;
+    readonly FALSE: 2;
+    readonly INT: 3;
+    readonly INT5: 4;
+    readonly FLOAT: 5;
+    readonly FLOAT5: 6;
+    readonly TEXT: 7;
+    readonly TEXTJ: 8;
+    readonly TEXT5: 9;
+    readonly TEXTRAW: 10;
+    readonly ARRAY: 11;
+    readonly OBJECT: 12;
+};
+export declare function encodeJsonb(node: JsonNode): Uint8Array;
+export interface JsonbElement {
+    offset: number;
+    end: number;
+    type: number;
+    payloadOffset: number;
+    payloadSize: number;
+}
+export declare function readHeader(blob: Uint8Array, offset: number): JsonbElement;
+export declare function looksLikeJsonb(blob: Uint8Array): boolean;
+export declare function decodeJsonb(blob: Uint8Array): JsonNode;
+/** Walk JSONB and collect element metadata for TVF id/parent assignment. */
+export interface JsonbWalkEntry {
+    offset: number;
+    parent: number | null;
+    node: JsonNode;
+    key: string | number | null;
+    path: string;
+    fullkey: string;
+    /** For object entries, offset of the key header (used as id). */
+    idOffset: number;
+}
+export declare function walkJsonbTree(blob: Uint8Array): JsonbWalkEntry[];
+export declare function jsonbToText(blob: Uint8Array): string;
+export declare function textToJsonb(text: string): Uint8Array;

package/dist/json/ops.d.ts

@@ -0,0 +1,24 @@
+import { SqlJsonText, type SqlValue } from "../types/value.js";
+import { type JsonNode } from "./types.js";
+export declare function sqlToJsonInput(value: SqlValue): JsonNode;
+export declare function trySqlToJsonInput(value: SqlValue): JsonNode | null;
+/** VALUE arg for insert/set/array/object — literal unless JSON subtype / JSONB. */
+export declare function sqlValueToJsonNode(value: SqlValue): JsonNode;
+export declare function jsonNodeToSql(node: JsonNode, mode: "sql" | "json" | "jsonb"): SqlValue;
+export declare function jsonArrowPath(right: SqlValue): string;
+export declare function extractOne(root: JsonNode, path: string): JsonNode | undefined;
+export type MutateMode = "insert" | "replace" | "set";
+/**
+ * json_array_insert / jsonb_array_insert — like json_replace, but PATH must end
+ * with an array index and the value is spliced in (existing elements shift right).
+ * https://www.sqlite.org/json1.html#jarrins
+ */
+export declare function arrayInsertJson(root: JsonNode, path: string, value: JsonNode): JsonNode;
+export declare function mutateJson(root: JsonNode, path: string, value: JsonNode, mode: MutateMode): JsonNode;
+export declare function removeJson(root: JsonNode, path: string): JsonNode;
+/** RFC7396-ish JSON Merge Patch as implemented by SQLite json_patch. */
+export declare function patchJson(target: JsonNode, patch: JsonNode): JsonNode;
+export declare function wrapJsonError(e: unknown): never;
+export declare function ensureJson(value: SqlValue): JsonNode;
+export declare function toJsonbBlob(value: SqlValue): Uint8Array;
+export declare function toJsonText(value: SqlValue): SqlJsonText;

package/dist/json/parse.d.ts

@@ -0,0 +1,13 @@
+import { SqliteError } from "../errors/index.js";
+import type { JsonNode } from "./types.js";
+export declare class JsonParseError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/** Parse JSON / JSON5-ish input into a JsonNode. Position is 1-based for errors. */
+export declare function parseJsonText(input: string, options?: {
+    strictCanonical?: boolean;
+}): JsonNode;
+export declare function jsonErrorPosition(input: string): number;
+export declare function isValidJsonText(input: string, flags?: number): boolean;
+export declare function malformedJsonError(position?: number): SqliteError;

package/dist/json/path.d.ts

@@ -0,0 +1,26 @@
+import type { JsonNode } from "./types.js";
+export type PathStep = {
+    kind: "root";
+} | {
+    kind: "key";
+    key: string;
+} | {
+    kind: "index";
+    index: number;
+} | {
+    kind: "append";
+} | {
+    kind: "fromEnd";
+    n: number;
+};
+export declare function parseJsonPath(path: string): PathStep[];
+/** Resolve path for read; returns undefined if missing. */
+export declare function pathGet(root: JsonNode, steps: PathStep[]): JsonNode | undefined;
+export interface PathParent {
+    parent: JsonNode;
+    step: PathStep;
+    /** For object: entry index; for array: element index (may be length for append). */
+    index: number;
+}
+/** Locate parent container for the final path step (for mutate). */
+export declare function pathParent(root: JsonNode, steps: PathStep[]): PathParent | null;

package/dist/json/stringify.d.ts

@@ -0,0 +1,4 @@
+import type { JsonNode } from "./types.js";
+export declare function stringifyJson(node: JsonNode): string;
+export declare function jsonQuoteString(value: string): string;
+export declare function prettyJson(node: JsonNode, indent?: string): string;

package/dist/json/tvf.d.ts

@@ -0,0 +1,13 @@
+import type { SqlValue } from "../types/value.js";
+export interface JsonTvfRow {
+    key: SqlValue;
+    value: SqlValue;
+    type: string;
+    atom: SqlValue;
+    id: number;
+    parent: SqlValue;
+    fullkey: string;
+    path: string;
+}
+export declare function jsonEachRows(json: SqlValue, path?: SqlValue): JsonTvfRow[];
+export declare function jsonTreeRows(json: SqlValue, path?: SqlValue): JsonTvfRow[];

package/dist/json/types.d.ts

@@ -0,0 +1,29 @@
+/** Internal JSON value tree used by sqlite-mem JSON1/JSONB. */
+export type JsonNode = {
+    kind: "null";
+} | {
+    kind: "true";
+} | {
+    kind: "false";
+} | {
+    kind: "integer";
+    text: string;
+} | {
+    kind: "real";
+    text: string;
+} | {
+    kind: "string";
+    value: string;
+} | {
+    kind: "array";
+    elements: JsonNode[];
+} | {
+    kind: "object";
+    entries: Array<{
+        key: string;
+        value: JsonNode;
+    }>;
+};
+export type JsonTypeName = "null" | "true" | "false" | "integer" | "real" | "text" | "array" | "object";
+export declare function jsonTypeName(node: JsonNode): JsonTypeName;
+export declare function cloneJson(node: JsonNode): JsonNode;

package/dist/lexer/tokenize.d.ts

@@ -0,0 +1,23 @@
+/** Lexer token kind: keywords, literals, operators, and punctuation. */
+export type TokenKind = "EOF" | "IDENT" | "STRING" | "NUMBER" | "BLOB" | "PARAM_POS" | "PARAM_NAMED" | "DOT" | "COMMA" | "SEMI" | "LPAREN" | "RPAREN" | "PLUS" | "MINUS" | "STAR" | "SLASH" | "PERCENT" | "EQ" | "EQEQ" | "NE" | "LT" | "LE" | "GT" | "GE" | "CONCAT" | "AMP" | "PIPE" | "LSHIFT" | "RSHIFT" | "JSON_ARROW" | "JSON_ARROW2" | "TILDE" | "ABORT" | "ACTION" | "ADD" | "AFTER" | "ALL" | "ALTER" | "ANALYZE" | "AND" | "AS" | "ASC" | "ATTACH" | "AUTOINCREMENT" | "BEFORE" | "BEGIN" | "BETWEEN" | "BY" | "CASCADE" | "CASE" | "CAST" | "CHECK" | "COLLATE" | "COLUMN" | "COMMIT" | "CONFLICT" | "CONSTRAINT" | "CREATE" | "CROSS" | "CURRENT" | "CURRENT_DATE" | "CURRENT_TIME" | "CURRENT_TIMESTAMP" | "DATABASE" | "DEFAULT" | "DEFERRABLE" | "DEFERRED" | "DELETE" | "DESC" | "DETACH" | "DISTINCT" | "DO" | "DROP" | "EACH" | "ELSE" | "END" | "ESCAPE" | "EXCEPT" | "EXCLUDE" | "EXCLUSIVE" | "EXISTS" | "EXPLAIN" | "FAIL" | "FILTER" | "FIRST" | "FOLLOWING" | "FOR" | "FOREIGN" | "FROM" | "FULL" | "FALSE" | "GENERATED" | "GLOB" | "GROUP" | "GROUPS" | "HAVING" | "IF" | "IGNORE" | "IMMEDIATE" | "IN" | "INDEX" | "INDEXED" | "INITIALLY" | "INNER" | "INSERT" | "INSTEAD" | "INTERSECT" | "INTO" | "IS" | "ISNULL" | "JOIN" | "KEY" | "LAST" | "LEFT" | "LIKE" | "LIMIT" | "MATCH" | "MATERIALIZED" | "NATURAL" | "NO" | "NOT" | "NOTHING" | "NOTNULL" | "NULL" | "NULLS" | "OF" | "OFFSET" | "ON" | "OR" | "ORDER" | "OTHERS" | "OUTER" | "OVER" | "PARTITION" | "PLAN" | "PRAGMA" | "PRECEDING" | "PRIMARY" | "QUERY" | "RAISE" | "RANGE" | "RECURSIVE" | "REFERENCES" | "REGEXP" | "REINDEX" | "RELEASE" | "RENAME" | "REPLACE" | "RESTRICT" | "RESPECT" | "RETURNING" | "RIGHT" | "ROLLBACK" | "ROW" | "ROWS" | "SAVEPOINT" | "SELECT" | "SET" | "TABLE" | "TEMP" | "TEMPORARY" | "THEN" | "TIES" | "TO" | "TRANSACTION" | "TRIGGER" | "TRUE" | "UNBOUNDED" | "UNION" | "UNIQUE" | "UPDATE" | "USING" | "VACUUM" | "VALUES" | "VIEW" | "VIRTUAL" | "WHEN" | "WHERE" | "WINDOW" | "WITH" | "WITHOUT";
+/** A single lexer token from {@link tokenize}. */
+export interface Token {
+    kind: TokenKind;
+    value: string;
+    /** For NUMBER/BLOB/STRING, the parsed value */
+    literal?: string | number | bigint | Uint8Array | null;
+    /** True when a NUMBER token used float/scientific syntax. */
+    forceReal?: boolean;
+    index?: number;
+    line: number;
+    column: number;
+    start: number;
+    end: number;
+}
+/**
+ * Lex `input` into SQLite tokens (keywords, literals, operators, parameters).
+ *
+ * @param input - SQL source text.
+ */
+export declare function tokenize(input: string): Token[];
+export declare function isKeyword(kind: TokenKind): boolean;

package/dist/parser/index.d.ts

@@ -0,0 +1,17 @@
+import type { Statement as ParsedStatement } from "../ast/nodes.js";
+import { type ParsedUnit } from "./parser.js";
+/** Parsed SQL statement AST (`SELECT`, `INSERT`, `CREATE TABLE`, …). */
+export type { Statement as ParsedStatement } from "../ast/nodes.js";
+export type { ParsedUnit } from "./parser.js";
+export { parseTokens, parseTokenUnits } from "./parser.js";
+/**
+ * Tokenize `sql` and parse every semicolon-separated statement.
+ *
+ * @param sql - SQLite SQL text.
+ * @returns AST statements in source order.
+ */
+export declare function parse(sql: string): ParsedStatement[];
+/**
+ * Parse SQL into AST + per-statement source slices (for `sqlite_master.sql`).
+ */
+export declare function parseUnits(sql: string): ParsedUnit[];

package/dist/parser/parser.d.ts

@@ -0,0 +1,115 @@
+import type { Expr, SelectStmt, Statement, WithClause } from "../ast/nodes.js";
+import type { Token } from "../lexer/tokenize.js";
+export interface ParsedUnit {
+    statement: Statement;
+    /** Source slice for this statement (no trailing semicolon); used for sqlite_master.sql. */
+    sql: string;
+}
+export declare class Parser {
+    private readonly tokens;
+    private readonly source;
+    private pos;
+    constructor(tokens: Token[], source?: string);
+    private current;
+    private peek;
+    private at;
+    private check;
+    private advance;
+    private match;
+    private expect;
+    syntaxError(message: string): never;
+    /** Accept IDENT or keyword tokens as identifier names. */
+    parseIdent(): string;
+    private parseQualifiedTableName;
+    private parseTableName;
+    private parseAttachStmt;
+    private parseDetachStmt;
+    private optionalAlias;
+    parseStatements(): Statement[];
+    /** Parse statements with per-statement source slices for catalog `sql` text. */
+    parseUnits(): ParsedUnit[];
+    parseStatement(): Statement;
+    private parseAnalyzeStmt;
+    private parseReindexStmt;
+    private parseVacuumStmt;
+    private parseWithClause;
+    private parseOptionalWith;
+    parseSelectStmt(withClause?: WithClause | null): SelectStmt;
+    private parseSelectCore;
+    private parseCompoundTail;
+    private parseResultColumns;
+    private isSelectClauseStart;
+    private parseFromItem;
+    private makeJoin;
+    private parseJoinOp;
+    private parseFromPrimary;
+    private parseValuesAsSelect;
+    private parseOrderBy;
+    private parseLimit;
+    private parseInsertStmt;
+    private parseUpsertClause;
+    private parseSetItems;
+    private parseReturning;
+    private parseUpdateStmt;
+    private parseDeleteStmt;
+    private parseCreateStmt;
+    private parseCreateVirtualTable;
+    /** One comma-separated CREATE VIRTUAL TABLE module argument (FTS options, columns, …). */
+    private parseVirtualTableArg;
+    private parseIdentOrQuoted;
+    private parseVirtualTableOptionValue;
+    private parseIfNotExists;
+    private parseIfExists;
+    private mapUpdateOr;
+    private parseCreateTable;
+    private parseColumnDef;
+    /** Type names may include optional precision/scale: VARCHAR(10), DECIMAL(10,2). */
+    private parseTypeName;
+    private isColumnConstraintStart;
+    private parseColumnConstraint;
+    private parseGeneratedConstraint;
+    private parseReferencesConstraint;
+    private parseTableConstraint;
+    private parseIndexedColumns;
+    private parseOnConflict;
+    private parseConflictAction;
+    private parseFkAction;
+    private parseFkActions;
+    private parseDeferrable;
+    private parseOrConflict;
+    private parseCreateIndex;
+    private parseCreateView;
+    private parseCreateTrigger;
+    private parseTriggerBody;
+    private parseDropStmt;
+    private parseDropTable;
+    private parseDropIndex;
+    private parseDropView;
+    private parseDropTrigger;
+    private parseAlterTableStmt;
+    private parseBeginStmt;
+    private parseCommitStmt;
+    private parseRollbackStmt;
+    private parseSavepointStmt;
+    private parseReleaseStmt;
+    private parsePragmaStmt;
+    parseExpr(): Expr;
+    private parseExprPrec;
+    private peekBinaryOp;
+    private parseIsRhs;
+    private parseInRhs;
+    private parseLikeRhs;
+    private parsePostfix;
+    private isNotKeywordCompound;
+    private parseUnaryExpr;
+    private parsePrimaryExpr;
+    private parseIdentOrFunction;
+    private finishCall;
+    private parseCaseExpr;
+    private parseWindowSpec;
+    private parseFrameSpec;
+    private parseFrameBound;
+}
+export declare function parseTokens(tokens: Token[], source?: string): Statement[];
+/** Parse SQL into AST statements paired with source slices. */
+export declare function parseTokenUnits(tokens: Token[], source: string): ParsedUnit[];

package/dist/planner/access.d.ts

@@ -0,0 +1,50 @@
+import type { Expr, FromItem, TableRef } from "../ast/nodes.js";
+import type { ExecutionEnv } from "../executor/env.js";
+import type { Row } from "../storage/row.js";
+import type { Table } from "../storage/table.js";
+import type { SqlValue } from "../types/value.js";
+export interface ConstEquality {
+    table: string | null;
+    column: string;
+    valueExpr: Expr;
+}
+export declare function conjunctions(expr: Expr): Expr[];
+export declare function equalityAgainstConst(expr: Expr): ConstEquality | null;
+export declare function equalityAgainstExpr(expr: Expr): {
+    expr: Expr;
+    valueExpr: Expr;
+} | null;
+export declare function whereFullyCovered(where: Expr, coveredColumns: Set<string>, alias: string, tableName: string): boolean;
+export interface TableRowLookup {
+    table: Table;
+    alias: string;
+    rows: Row[];
+    /** Lowercased columns whose equality predicates were applied by the access path. */
+    coveredColumns: Set<string>;
+}
+/** Look up rows for a simple `FROM table WHERE ...` using PK, a covering equality index, or an automatic hash. */
+export declare function tryIndexedTableRows(from: FromItem, where: Expr, env: ExecutionEnv): TableRowLookup | null;
+export declare function lookupTableRows(from: TableRef, where: Expr, env: ExecutionEnv): TableRowLookup | null;
+export declare function tryIndexedOrder(from: FromItem, order: {
+    expr: Expr;
+    dir: "ASC" | "DESC";
+}, env: ExecutionEnv, limit?: number): TableRowLookup | null;
+export interface JoinProbe {
+    table: Table;
+    alias: string;
+    /** When true, ON is fully applied by the probe (skip re-eval). */
+    covering: boolean;
+    lookup: (leftCellsValue: (table: string | null, name: string) => SqlValue) => Row[];
+}
+/** Equality join keys extracted from ON (column = column), for hash join when no index probe. */
+export interface JoinEqualityKeys {
+    /** Right-side column names in join-key order. */
+    rightColumns: string[];
+    /** Corresponding left-side (probe) column references. */
+    leftKeys: {
+        table: string | null;
+        column: string;
+    }[];
+}
+export declare function tryJoinEqualityKeys(right: FromItem, on: Expr | null, env?: ExecutionEnv): JoinEqualityKeys | null;
+export declare function tryJoinProbe(right: FromItem, on: Expr | null, env: ExecutionEnv): JoinProbe | null;

package/dist/planner/index.d.ts

@@ -0,0 +1,3 @@
+import type { Statement } from "../ast/nodes.js";
+export type Plan = Statement;
+export declare function preparePlan(statement: Statement): Plan;

package/dist/runtime/assert.d.ts

@@ -0,0 +1,11 @@
+import type { Row } from "../storage/row.js";
+import type { Table } from "../storage/table.js";
+/** Always-on invariant check (Tiger Style — not stripped in production). */
+export declare function assert(condition: boolean, message: string): asserts condition;
+/** Exhaustive switch helper — call when a union case should be impossible. */
+export declare function assertUnreachable(value: never, message?: string): never;
+/** Row payload must align with table column count after insert/update. */
+export declare function assertRowShape(table: Table, row: Row): void;
+/** Maximum blob/string length enforced before allocation (matches bun:sqlite TOOBIG). */
+export declare const SQLITE_MAX_LENGTH = 2147483647;
+export declare function assertBlobLength(length: number, _feature: string): void;

package/dist/runtime/catch.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorCategory } from "../errors/index.js";
+/** True when an error is an expected fast-path miss (fall through to full executor). */
+export declare function isExpectedFastPathMiss(error: unknown, categories?: readonly ErrorCategory[]): boolean;

package/dist/runtime/clock.d.ts

@@ -0,0 +1,14 @@
+/** Fixed reference instant used when callers do not supply a clock (`2000-01-01T00:00:00.000Z`). */
+export declare const DEFAULT_NOW: Date;
+/** Function that returns the current instant for `date('now')` and related builtins. */
+export type Clock = () => Date;
+/**
+ * Clock that always returns a copy of `instant` (default {@link DEFAULT_NOW}).
+ *
+ * @throws {RangeError} If `instant` is an invalid `Date`.
+ */
+export declare function fixedClock(instant?: Date): Clock;
+/** Wall-clock `'now'` matching SQLite (`new Date()` each call). */
+export declare function systemClock(): Clock;
+/** Normalize a `Date`, {@link Clock}, `"system"`, or `undefined` into a {@link Clock}. */
+export declare function resolveClock(now?: Date | Clock | "system"): Clock;

package/dist/runtime/index.d.ts

@@ -0,0 +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 { deriveSeed, OsEntropy, Prng } from "./prng.js";

package/dist/runtime/options.d.ts

@@ -0,0 +1,25 @@
+import type { Clock } from "./clock.js";
+/** Entropy source for `random()` / `randomblob()`. Default is seeded xorshift64*. */
+export type RandomMode = "deterministic" | "os";
+/** Options for {@link Database} construction. All fields are optional. */
+export interface DatabaseOptions {
+    /**
+     * Seed for deterministic `random()` (and any other PRNG-backed builtins).
+     * Defaults to {@link DEFAULT_DATABASE_SEED} (`1`). Ignored when {@link random} is `"os"`.
+     */
+    seed?: number | bigint;
+    /**
+     * Entropy for `random()` / `randomblob()`.
+     * `"deterministic"` (default) uses {@link seed}. `"os"` uses CSPRNG like SQLite
+     * (not rolled back with transactions; not restored from snapshots).
+     */
+    random?: RandomMode;
+    /**
+     * Clock for `date('now')` / `datetime('now')` / etc.
+     * Defaults to a fixed instant (`2000-01-01T00:00:00.000Z`).
+     * Pass a `Date`, `() => Date`, or `"system"` for wall-clock `'now'` like SQLite.
+     */
+    now?: Date | Clock | "system";
+}
+/** Default {@link DatabaseOptions.seed} when constructing a {@link Database}. */
+export declare const DEFAULT_DATABASE_SEED = 1;

package/dist/runtime/prng.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Deterministic 64-bit PRNG (xorshift64*).
+ * Used for SQLite `random()` and any other nondeterministic builtins.
+ */
+export declare class Prng {
+    private state;
+    /**
+     * @param seed - Engine seed. `0` is replaced with a non-zero constant.
+     */
+    constructor(seed?: number | bigint);
+    /** Next unsigned 64-bit value. */
+    nextU64(): bigint;
+    /** SQLite `random()` style signed 64-bit integer in [-2^63+1, 2^63-1]. */
+    nextSqliteRandom(): bigint;
+    /** Next float in `[0, 1)` from 53 bits of {@link nextU64}. */
+    nextFloat(): number;
+    /**
+     * Next integer in `[min, max]` (inclusive).
+     *
+     * @throws {RangeError} If `max < min`.
+     */
+    nextInt(min: number, max: number): number;
+    /** Current unsigned 64-bit engine state (for snapshot / transaction rollback). */
+    getState(): bigint;
+    /** Restore unsigned 64-bit engine state from {@link getState}. */
+    setState(state: bigint): void;
+    /** Independent copy with the same engine state. */
+    clone(): Prng;
+}
+/**
+ * CSPRNG-backed entropy for `random()` / `randomblob()` when {@link DatabaseOptions.random}
+ * is `"os"`. `setState` is a no-op so ROLLBACK / snapshot restore do not rewind draws.
+ */
+export declare class OsEntropy extends Prng {
+    constructor();
+    nextU64(): bigint;
+    getState(): bigint;
+    setState(_state: bigint): void;
+    clone(): Prng;
+}
+/** FNV-1a hash of `parts` as a signed 32-bit seed (for tests and custom PRNGs). */
+export declare function deriveSeed(...parts: Array<number | string | bigint>): number;

package/dist/schema/catalog.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseState } from "../storage/database-state.js";
+import { Table } from "../storage/table.js";
+export type SchemaObjectType = "table" | "index" | "view" | "trigger";
+export interface SchemaCatalogRow {
+    type: SchemaObjectType;
+    name: string;
+    tbl_name: string;
+    rootpage: number;
+    sql: string | null;
+}
+export declare function schemaCatalogRows(state: DatabaseState): SchemaCatalogRow[];
+export declare function buildSchemaCatalog(state: DatabaseState, name?: string): Table;
+export declare function buildSqliteSchema(state: DatabaseState): Table;
+export declare function buildSqliteMaster(state: DatabaseState): Table;

package/dist/schema/master-sql.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalize CREATE source toward SQLite's `sqlite_master.sql` conventions:
+ * strip TEMP/TEMPORARY, IF NOT EXISTS, and schema qualifiers on the object name.
+ * Body text (from after the object name) is preserved byte-for-byte from the input.
+ */
+export declare function normalizeMasterSql(sql: string): string;
+/** Append an ALTER TABLE ADD COLUMN definition into CREATE TABLE master sql (SQLite style). */
+export declare function appendAddColumnToMasterSql(originalSql: string | null, alterSql: string | null): string | null;
+/** Synthesize CTAS catalog SQL: `CREATE TABLE name(col1, col2, ...)`. */
+export declare function synthesizeCtasMasterSql(tableName: string, columnNames: string[]): string;

package/dist/serialization/codec.d.ts

@@ -0,0 +1,19 @@
+import { DatabaseState } from "../storage/database-state.js";
+/** PRNG + clock captured alongside schema/rows. */
+export interface SnapshotRuntime {
+    prngState: bigint;
+    nowMs: number;
+}
+/** Result of {@link decodeDatabaseState}. */
+export interface DecodedSnapshot {
+    state: DatabaseState;
+    runtime: SnapshotRuntime;
+}
+/**
+ * Encode catalog, rows, and runtime into a sqlite-mem snapshot blob (not a `.sqlite` file).
+ */
+export declare function encodeDatabaseState(state: DatabaseState, runtime: SnapshotRuntime): Uint8Array;
+/**
+ * Decode a blob from {@link encodeDatabaseState} / {@link Database.snapshot}.
+ */
+export declare function decodeDatabaseState(snapshot: Uint8Array): DecodedSnapshot;

package/dist/serialization/index.d.ts

@@ -0,0 +1 @@
+export { type DecodedSnapshot, decodeDatabaseState, encodeDatabaseState, type SnapshotRuntime, } from "./codec.js";