@crvouga/mockingbird-service-sqlite 0.1.0

package/compat/smoke-baseline.json

@@ -0,0 +1,3 @@
+{
+  "ids": []
+}

package/compat/sqllogictest-skip.json

@@ -0,0 +1,5 @@
+{
+  "files": [],
+  "prefixes": [],
+  "notes": "Add vendor/sqllogictest/test/<file> or <file>#<line> entries when a record is intentionally unsupported."
+}

package/dist/api/database.d.ts

@@ -0,0 +1,112 @@
+import { type DatabaseOptions, type RandomMode } from "../runtime/index.js";
+import type { BindValue, QueryRow } from "../types/value.js";
+import { type Snapshot } from "./snapshot.js";
+import { Statement } from "./statement.js";
+/**
+ * Pure TypeScript in-memory SQLite database.
+ *
+ * Deterministic by default: `random()` / `randomblob()` use a seeded PRNG
+ * (`seed` defaults to `1`) and `date('now')` / friends use a fixed clock
+ * (`2000-01-01T00:00:00.000Z`). Pass `{ random: "os" }` and `{ now: "system" }`
+ * for SQLite-like CSPRNG and wall-clock `'now'`. There is no filesystem or WASM.
+ *
+ * @example
+ * ```ts
+ * import { Database } from "@crvouga/mockingbird-service-sqlite";
+ *
+ * const db = new Database();
+ * db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)");
+ * db.prepare("INSERT INTO users (name) VALUES (?)").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()` / `randomblob()`. */
+    readonly randomMode: RandomMode;
+    private closed;
+    private transactionSequence;
+    /** Depth of active {@link transaction} callbacks (not SQL BEGIN). */
+    private apiTransactionDepth;
+    /**
+     * Create an empty in-memory database.
+     *
+     * @param options - Determinism knobs. See {@link DatabaseOptions}.
+     */
+    constructor(options?: DatabaseOptions);
+    /**
+     * Execute SQL for its side effects (DDL/DML). Multiple statements are allowed.
+     *
+     * Does not accept bind parameters — use {@link prepare} or {@link query}.
+     *
+     * @param sql - SQL to run (semicolon-separated statements are ok).
+     * @throws {SqliteError} If the database is closed, extra arguments are passed, or the SQL fails.
+     */
+    exec(sql: string): void;
+    /**
+     * Execute a single-statement query and return all rows as objects keyed by column name.
+     *
+     * @typeParam T - Row shape. Defaults to {@link QueryRow}.
+     * @param sql - A single SQL statement (trailing `;` is fine).
+     * @param params - Bound parameters for `?` / `:name` placeholders.
+     * @returns All result rows.
+     * @throws {SqliteError} If the database is closed, `sql` is not a single statement, or execution fails.
+     */
+    query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[];
+    /**
+     * Compile a single SQL statement into a reusable {@link Statement}.
+     *
+     * @param sql - A single SQL statement (trailing `;` is fine). Multi-statement scripts are rejected.
+     * @throws {SqliteError} If the database is closed or `sql` cannot be prepared as one statement.
+     */
+    prepare(sql: string): Statement;
+    /**
+     * Run `fn` inside a transaction. Commits on success; rolls back if `fn` throws.
+     *
+     * Nested calls use SAVEPOINTs so an inner failure does not abort the outer
+     * transaction. Calling {@link close} from inside `fn` throws `misuse`.
+     *
+     * @param fn - Work to run while the transaction is open.
+     * @returns The value returned by `fn`.
+     * @throws {SqliteError} If the database is closed. Re-throws whatever `fn` throws after rollback.
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Freeze this database into a reusable {@link Snapshot} template.
+     *
+     * Does not encode SQLM bytes. Call {@link Snapshot.encode} to persist, or
+     * {@link Snapshot.open} for a copy-on-write fork.
+     *
+     * @throws {SqliteError} If the database is closed or a transaction is open.
+     */
+    snapshot(): Snapshot;
+    /**
+     * Close the database. Further SQL throws {@link SqliteError}. Idempotent.
+     *
+     * Rolls back an open SQL transaction, if any. Throws if called from inside
+     * a {@link transaction} callback.
+     */
+    close(): void;
+    /**
+     * Rows changed by the most recent INSERT / UPDATE / DELETE (SQLite `changes()`).
+     *
+     * @throws {SqliteError} If the database is closed.
+     */
+    get changes(): number;
+    /**
+     * Rowid of the most recent INSERT (SQLite `last_insert_rowid()`).
+     *
+     * @throws {SqliteError} If the database is closed.
+     */
+    get lastInsertRowid(): number | bigint;
+    /**
+     * Cumulative rows changed by INSERT / UPDATE / DELETE (SQLite `total_changes()`).
+     *
+     * @throws {SqliteError} If the database is closed.
+     */
+    get totalChanges(): number;
+    private prepareSingle;
+}
+export { Snapshot } from "./snapshot.js";
+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 SQLM bytes are produced lazily via {@link encode}.
+ */
+export declare class Snapshot {
+    private cachedBytes;
+    /** Encoded SQLM 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,75 @@
+import { type ResultSet } from "../executor/result.js";
+import type { BindValue, QueryRow } from "../types/value.js";
+/** Mutation counters returned by {@link Statement.run}. */
+export interface RunResult {
+    /** Rows changed by this execution (SQLite `changes()`). */
+    changes: number;
+    /** Rowid of the most recent INSERT in this execution. */
+    lastInsertRowid: number | bigint;
+}
+/**
+ * Prepared SQL statement bound to a {@link Database}.
+ *
+ * Create with {@link Database.prepare}. Pass bind values as rest arguments to
+ * {@link run}, {@link all}, {@link get}, or {@link result} on each call
+ * (stateless — there is no sticky `bind()`).
+ *
+ * @example
+ * ```ts
+ * import { Database } from "@crvouga/mockingbird-service-sqlite";
+ *
+ * const db = new Database();
+ * db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)");
+ * const insert = db.prepare("INSERT INTO t (name) VALUES (?)");
+ * insert.run("Ada");
+ * const row = db.prepare("SELECT id, name FROM t WHERE id = ?").get<{ id: number; name: string }>(1);
+ * ```
+ */
+export declare class Statement {
+    private readonly database;
+    private readonly sql;
+    private namedPlan;
+    private env;
+    private statements;
+    private statementSqls;
+    private schemaVersion;
+    private constructor();
+    /**
+     * Execute for side effects (INSERT / UPDATE / DELETE / DDL).
+     *
+     * @param params - Bind values for this call only.
+     * @returns Mutation counters for this execution.
+     * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+     */
+    run(...params: BindValue[]): RunResult;
+    /**
+     * Execute and return every result row as an object keyed by column name.
+     *
+     * @typeParam T - Row shape. Defaults to {@link QueryRow}.
+     * @param params - Bind values for this call only.
+     * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+     */
+    all<T = QueryRow>(...params: BindValue[]): T[];
+    /**
+     * Execute and return the full {@link ResultSet}, including column names.
+     *
+     * Use this when you need metadata for an empty result (column names with zero rows).
+     * {@link all} only returns row objects.
+     *
+     * @param params - Bind values for this call only.
+     * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+     */
+    result(...params: BindValue[]): ResultSet;
+    /**
+     * Execute and return the first row, or `undefined` if there are no rows.
+     *
+     * @typeParam T - Row shape. Defaults to {@link QueryRow}.
+     * @param params - Bind values for this call only.
+     * @throws {SqliteError} If the database is closed, the statement is empty, or execution fails.
+     */
+    get<T = QueryRow>(...params: BindValue[]): T | undefined;
+    private execute;
+    private obtainEnv;
+    private reprepareIfSchemaChanged;
+    private bindNamed;
+}

package/dist/ast/nodes.d.ts

@@ -0,0 +1,476 @@
+import type { SqlValue } from "../types/value.js";
+export type BinaryOp = "+" | "-" | "*" | "/" | "%" | "||" | "=" | "==" | "!=" | "<>" | "<" | "<=" | ">" | ">=" | "AND" | "OR" | "IS" | "IS NOT" | "IS DISTINCT FROM" | "IS NOT DISTINCT FROM" | "LIKE" | "NOT LIKE" | "GLOB" | "NOT GLOB" | "IN" | "NOT IN" | "MATCH" | "->" | "->>" | "&" | "|" | "<<" | ">>";
+export type UnaryOp = "+" | "-" | "~" | "NOT";
+/** Parsed SQL expression AST (literals, operators, functions, subqueries, …). */
+export type Expr = LiteralExpr | NullExpr | ColumnRefExpr | UnaryExpr | BinaryExpr | BetweenExpr | InExpr | LikeExpr | IsBoolExpr | FunctionExpr | AggregateExpr | WindowExpr | CaseExpr | CastExpr | ExistsExpr | SubqueryExpr | ParameterExpr | RowExpr | CollateExpr;
+export interface LiteralExpr {
+    type: "literal";
+    value: SqlValue;
+    /** True when the literal was written with float syntax (e.g. 1.0) or must be REAL. */
+    forceReal?: boolean;
+}
+export interface NullExpr {
+    type: "null";
+}
+export interface ColumnRefExpr {
+    type: "column";
+    table: string | null;
+    name: string;
+}
+export interface UnaryExpr {
+    type: "unary";
+    op: UnaryOp;
+    expr: Expr;
+}
+export interface BinaryExpr {
+    type: "binary";
+    op: BinaryOp;
+    left: Expr;
+    right: Expr;
+}
+/** `expr IS [NOT] TRUE` / `expr IS [NOT] FALSE` (truthiness, not equality to 1/0). */
+export interface IsBoolExpr {
+    type: "is_bool";
+    expr: Expr;
+    not: boolean;
+    /** `true` for TRUE, `false` for FALSE. */
+    sense: boolean;
+}
+export interface BetweenExpr {
+    type: "between";
+    not: boolean;
+    expr: Expr;
+    lower: Expr;
+    upper: Expr;
+}
+export interface InExpr {
+    type: "in";
+    not: boolean;
+    expr: Expr;
+    values: Expr[] | SelectStmt;
+}
+export interface LikeExpr {
+    type: "like";
+    not: boolean;
+    op: "LIKE" | "GLOB";
+    expr: Expr;
+    pattern: Expr;
+    escape: Expr | null;
+}
+export interface FunctionExpr {
+    type: "function";
+    name: string;
+    distinct: boolean;
+    args: Expr[] | "*";
+    orderBy: OrderByItem[];
+    filter: Expr | null;
+}
+export interface AggregateExpr {
+    type: "aggregate";
+    name: string;
+    distinct: boolean;
+    args: Expr[] | "*";
+    orderBy: OrderByItem[];
+    filter: Expr | null;
+}
+export interface WindowExpr {
+    type: "window";
+    func: FunctionExpr | AggregateExpr;
+    window: WindowSpec;
+}
+export interface WindowSpec {
+    partitionBy: Expr[];
+    orderBy: OrderByItem[];
+    frame: FrameSpec | null;
+    /** Named window reference for `OVER window_name`. */
+    ref?: string | null;
+}
+export interface FrameSpec {
+    type: "ROWS" | "RANGE" | "GROUPS";
+    start: FrameBound;
+    end: FrameBound;
+    exclude: "no_others" | "current_row" | "group" | "ties" | null;
+}
+export type FrameBound = {
+    kind: "unbounded_preceding";
+} | {
+    kind: "unbounded_following";
+} | {
+    kind: "current_row";
+} | {
+    kind: "preceding";
+    expr: Expr;
+} | {
+    kind: "following";
+    expr: Expr;
+};
+export interface CaseExpr {
+    type: "case";
+    base: Expr | null;
+    whens: {
+        when: Expr;
+        then: Expr;
+    }[];
+    else: Expr | null;
+}
+export interface CastExpr {
+    type: "cast";
+    expr: Expr;
+    typeName: string;
+}
+export interface ExistsExpr {
+    type: "exists";
+    not: boolean;
+    select: SelectStmt;
+}
+export interface SubqueryExpr {
+    type: "subquery";
+    select: SelectStmt;
+}
+export interface ParameterExpr {
+    type: "parameter";
+    /** 1-based positional index, or named key */
+    name: string | number;
+}
+export interface RowExpr {
+    type: "row";
+    values: Expr[];
+}
+export interface CollateExpr {
+    type: "collate";
+    expr: Expr;
+    collation: string;
+}
+export interface OrderByItem {
+    expr: Expr;
+    dir: "ASC" | "DESC";
+    nulls: "FIRST" | "LAST" | null;
+}
+export interface LimitClause {
+    limit: Expr;
+    offset: Expr | null;
+}
+export type Statement = SelectStmt | InsertStmt | UpdateStmt | DeleteStmt | CreateTableStmt | DropTableStmt | AlterTableStmt | CreateIndexStmt | DropIndexStmt | CreateViewStmt | DropViewStmt | CreateTriggerStmt | DropTriggerStmt | BeginStmt | CommitStmt | RollbackStmt | SavepointStmt | ReleaseStmt | PragmaStmt | AttachStmt | DetachStmt | CreateVirtualTableStmt | ExplainStmt | AnalyzeStmt | ReindexStmt | VacuumStmt;
+export interface AnalyzeStmt {
+    type: "analyze";
+    schema: string | null;
+    name: string | null;
+}
+export interface ReindexStmt {
+    type: "reindex";
+    schema: string | null;
+    name: string | null;
+}
+export interface VacuumStmt {
+    type: "vacuum";
+    schema: string | null;
+    into: string | null;
+}
+export interface SelectStmt {
+    type: "select";
+    with: WithClause | null;
+    distinct: boolean;
+    columns: ResultColumn[];
+    from: FromItem | null;
+    where: Expr | null;
+    groupBy: Expr[];
+    having: Expr | null;
+    windows: {
+        name: string;
+        spec: WindowSpec;
+    }[];
+    orderBy: OrderByItem[];
+    limit: LimitClause | null;
+    compound: CompoundTail | null;
+}
+export interface CompoundTail {
+    op: "UNION" | "UNION ALL" | "INTERSECT" | "EXCEPT";
+    select: SelectStmt;
+}
+export interface WithClause {
+    recursive: boolean;
+    ctes: Cte[];
+}
+export interface Cte {
+    name: string;
+    columns: string[] | null;
+    materialized: "materialized" | "not_materialized" | null;
+    select: SelectStmt;
+}
+export type ResultColumn = {
+    type: "star";
+    table: string | null;
+} | {
+    type: "expr";
+    expr: Expr;
+    alias: string | null;
+};
+export type FromItem = TableRef | JoinFrom | SubqueryFrom | TableFuncFrom;
+export interface TableRef {
+    type: "table";
+    schema: string | null;
+    name: string;
+    alias: string | null;
+}
+export interface SubqueryFrom {
+    type: "subquery";
+    select: SelectStmt;
+    alias: string;
+}
+export interface TableFuncFrom {
+    type: "table_func";
+    name: string;
+    args: Expr[];
+    alias: string | null;
+}
+export interface JoinFrom {
+    type: "join";
+    left: FromItem;
+    right: FromItem;
+    joinType: "CROSS" | "INNER" | "LEFT" | "RIGHT" | "FULL";
+    on: Expr | null;
+    using: string[] | null;
+}
+export interface InsertStmt {
+    type: "insert";
+    with: WithClause | null;
+    mode: "insert" | "replace" | "insert_or_replace" | "insert_or_ignore" | "insert_or_abort" | "insert_or_rollback" | "insert_or_fail";
+    table: string;
+    columns: string[] | null;
+    values: Expr[][] | null;
+    select: SelectStmt | null;
+    upsert: UpsertClause | null;
+    returning: ResultColumn[];
+}
+export interface UpsertClause {
+    targetColumns: string[] | null;
+    targetExprs: Expr[] | null;
+    targetWhere: Expr | null;
+    action: "nothing" | {
+        set: SetItem[];
+        where: Expr | null;
+    };
+}
+export interface SetItem {
+    columns: string[];
+    expr: Expr;
+}
+export interface UpdateStmt {
+    type: "update";
+    with: WithClause | null;
+    or: "replace" | "ignore" | "abort" | "rollback" | "fail" | null;
+    table: string;
+    alias: string | null;
+    set: SetItem[];
+    from: FromItem | null;
+    where: Expr | null;
+    returning: ResultColumn[];
+}
+export interface DeleteStmt {
+    type: "delete";
+    with: WithClause | null;
+    or: "replace" | "ignore" | "abort" | "rollback" | "fail" | null;
+    table: string;
+    alias: string | null;
+    where: Expr | null;
+    returning: ResultColumn[];
+}
+export interface CreateTableStmt {
+    type: "create_table";
+    ifNotExists: boolean;
+    temp: boolean;
+    name: string;
+    columns: ColumnDef[];
+    constraints: TableConstraint[];
+    asSelect: SelectStmt | null;
+    withoutRowid: boolean;
+    strict: boolean;
+}
+export interface ColumnDef {
+    name: string;
+    typeName: string | null;
+    constraints: ColumnConstraint[];
+}
+export type ColumnConstraint = {
+    type: "primary_key";
+    order: "ASC" | "DESC" | null;
+    autoincrement: boolean;
+    conflict: ConflictAction | null;
+} | {
+    type: "not_null";
+    conflict: ConflictAction | null;
+} | {
+    type: "unique";
+    conflict: ConflictAction | null;
+} | {
+    type: "check";
+    expr: Expr;
+} | {
+    type: "default";
+    expr: Expr;
+} | {
+    type: "collate";
+    name: string;
+} | {
+    type: "references";
+    table: string;
+    columns: string[] | null;
+    onDelete: FkAction | null;
+    onUpdate: FkAction | null;
+    match: FkMatch;
+    deferrable: boolean;
+    initiallyDeferred: boolean;
+} | {
+    type: "generated";
+    expr: Expr;
+    stored: boolean;
+};
+export type TableConstraint = {
+    type: "primary_key";
+    columns: IndexedColumn[];
+    conflict: ConflictAction | null;
+} | {
+    type: "unique";
+    columns: IndexedColumn[];
+    conflict: ConflictAction | null;
+    name: string | null;
+} | {
+    type: "check";
+    expr: Expr;
+    name: string | null;
+} | {
+    type: "foreign_key";
+    columns: string[];
+    refTable: string;
+    refColumns: string[] | null;
+    onDelete: FkAction | null;
+    onUpdate: FkAction | null;
+    match: FkMatch;
+    name: string | null;
+    deferrable: boolean;
+    initiallyDeferred: boolean;
+};
+export interface IndexedColumn {
+    name: string;
+    collate: string | null;
+    order: "ASC" | "DESC" | null;
+    /** Present when the index key is an expression rather than a bare column. */
+    expr?: Expr | null;
+}
+export type ConflictAction = "ROLLBACK" | "ABORT" | "FAIL" | "IGNORE" | "REPLACE";
+export type FkAction = "SET NULL" | "SET DEFAULT" | "CASCADE" | "RESTRICT" | "NO ACTION";
+/** SQLite MATCH clause; FULL rejects partial-NULL composite keys. PARTIAL is accepted as SIMPLE. */
+export type FkMatch = "SIMPLE" | "FULL" | "PARTIAL";
+export interface DropTableStmt {
+    type: "drop_table";
+    ifExists: boolean;
+    name: string;
+}
+export interface AlterTableStmt {
+    type: "alter_table";
+    table: string;
+    action: {
+        kind: "rename_table";
+        newName: string;
+    } | {
+        kind: "rename_column";
+        oldName: string;
+        newName: string;
+    } | {
+        kind: "add_column";
+        column: ColumnDef;
+    } | {
+        kind: "drop_column";
+        name: string;
+    };
+}
+export interface CreateIndexStmt {
+    type: "create_index";
+    unique: boolean;
+    ifNotExists: boolean;
+    name: string;
+    table: string;
+    columns: IndexedColumn[];
+    where: Expr | null;
+}
+export interface DropIndexStmt {
+    type: "drop_index";
+    ifExists: boolean;
+    name: string;
+}
+export interface CreateViewStmt {
+    type: "create_view";
+    ifNotExists: boolean;
+    temp: boolean;
+    name: string;
+    columns: string[] | null;
+    select: SelectStmt;
+}
+export interface DropViewStmt {
+    type: "drop_view";
+    ifExists: boolean;
+    name: string;
+}
+export interface CreateTriggerStmt {
+    type: "create_trigger";
+    ifNotExists: boolean;
+    temp: boolean;
+    name: string;
+    timing: "BEFORE" | "AFTER" | "INSTEAD";
+    event: "INSERT" | "UPDATE" | "DELETE";
+    table: string;
+    updateColumns: string[] | null;
+    forEachRow: boolean;
+    when: Expr | null;
+    body: Statement[];
+}
+export interface DropTriggerStmt {
+    type: "drop_trigger";
+    ifExists: boolean;
+    name: string;
+}
+export interface CreateVirtualTableStmt {
+    type: "create_virtual_table";
+    ifNotExists: boolean;
+    name: string;
+    module: string;
+    moduleArgs: string[];
+}
+export interface BeginStmt {
+    type: "begin";
+    mode: "DEFERRED" | "IMMEDIATE" | "EXCLUSIVE" | null;
+}
+export interface CommitStmt {
+    type: "commit";
+}
+export interface RollbackStmt {
+    type: "rollback";
+    savepoint: string | null;
+}
+export interface SavepointStmt {
+    type: "savepoint";
+    name: string;
+}
+export interface ReleaseStmt {
+    type: "release";
+    name: string;
+}
+export interface PragmaStmt {
+    type: "pragma";
+    name: string;
+    value: Expr | null;
+}
+export interface AttachStmt {
+    type: "attach";
+    filename: Expr;
+    schema: string;
+}
+export interface DetachStmt {
+    type: "detach";
+    schema: string;
+}
+export interface ExplainStmt {
+    type: "explain";
+    queryPlan: boolean;
+    statement: Statement;
+}

package/dist/constraints/check.d.ts

@@ -0,0 +1,11 @@
+import type { Expr } from "../ast/nodes.js";
+import type { IndexStore } from "../indexes/index.js";
+import type { Row, Rowid } from "../storage/row.js";
+import type { Table } from "../storage/table.js";
+import type { SqlValue } from "../types/value.js";
+export type CheckEvaluator = (expr: Expr, row: Row) => SqlValue;
+export declare function checkNotNull(table: Table, row: Row): void;
+export declare function checkPrimaryKey(table: Table, row: Row): void;
+export declare function checkUnique(index: IndexStore, values: readonly SqlValue[], rowid?: Rowid): void;
+export declare function checkExpressions(expressions: readonly Expr[], row: Row, evaluate: CheckEvaluator, constraintName?: string): void;
+export declare function checkTableConstraints(table: Table, row: Row, evaluate: CheckEvaluator): void;