@crvouga/sqlite-mem 1.2.0 → 1.3.0

package/README.md

@@ -6,10 +6,11 @@ Pure TypeScript, completely in-memory SQLite implementation aiming for **full SQ
 - **Zero** WASM, native bindings, workers, or filesystem dependencies
 - Entire database stored in memory
 - **Synchronous** ESM-only API (no Promises, no `require`)
-- **Verified against SQLite 3.51.0** (`bun:sqlite`) via differential contracts + fail-closed gate
+- **SQL dialect verified** against SQLite 3.51.0 / 3.53.0 (`bun:sqlite`) via differential contracts + fail-closed gate
+- **Not** a drop-in for `sql.js` / `sqlite-wasm` APIs, on-disk `.sqlite` files, or user-defined functions
 - Intentional differences: deterministic `random()` / `'now'` by default, and a custom snapshot format (not `.sqlite` files)
 
-See [COMPATIBILITY.md](COMPATIBILITY.md) for the matrix and [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) for the audit report. Agents contributing to this repo: start with [AGENTS.md](AGENTS.md).
+See [COMPATIBILITY.md](COMPATIBILITY.md) for the matrix, [docs/DROP-IN-CONTRACT.md](docs/DROP-IN-CONTRACT.md) for the falsifiable claim, and [docs/GAP-ANALYSIS.md](docs/GAP-ANALYSIS.md) for what is still unproven. Agents: [AGENTS.md](AGENTS.md).
 
 ## Documentation
 
@@ -19,6 +20,11 @@ See [COMPATIBILITY.md](COMPATIBILITY.md) for the matrix and [COMPATIBILITY-AUDIT
 | [AGENTS.md](AGENTS.md) | Architecture, how to change code, test/compat gates |
 | [COMPATIBILITY.md](COMPATIBILITY.md) | Feature matrix + verify commands |
 | [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) | Audit evidence |
+| [docs/DROP-IN-CONTRACT.md](docs/DROP-IN-CONTRACT.md) | Falsifiable drop-in claim (what “same” means) |
+| [docs/PROOF.md](docs/PROOF.md) | Evidence argument + what is not proven |
+| [docs/GAP-ANALYSIS.md](docs/GAP-ANALYSIS.md) | Phase 0 gap analysis vs full drop-in catalog |
+| [docs/GAP-CATALOG.md](docs/GAP-CATALOG.md) | Current unproven / thin / intentional inventory |
+| [DIVERGENCES.md](DIVERGENCES.md) | Auto-generated intentional divergences |
 | [docs/SECRETS.md](docs/SECRETS.md) | npm / CI publish setup |
 | [benchmarks/PERFORMANCE.md](benchmarks/PERFORMANCE.md) | Performance notes |
 
@@ -208,9 +214,11 @@ The exports of the main entry (`@crvouga/sqlite-mem`) are **frozen**:
 
 ## Compatibility notes for integrators
 
-Goal: drop-in SQL behavior vs SQLite **3.51.0**. Full matrix: [COMPATIBILITY.md](COMPATIBILITY.md).
+Goal: **SQL dialect** behavioral parity vs SQLite **3.51.0** / **3.53.0** for the `@crvouga/sqlite-mem` sync API. Full matrix: [COMPATIBILITY.md](COMPATIBILITY.md). Contract: [docs/DROP-IN-CONTRACT.md](docs/DROP-IN-CONTRACT.md).
 
-**Intentional differences:** custom `SQLM` snapshots; seeded `random()` / fixed `'now'` by default (`{ random: "os" }` / `{ now: "system" }` match SQLite entropy and wall clock); no C API / on-disk DB / VFS.
+This is **not** a drop-in replacement for `sql.js`, `@sqlite.org/sqlite-wasm`, or better-sqlite3’s full Node API. There is no `.sqlite` file codec, no `create_function` / custom collations, no `stmt.step()` / `iterate()`, and `ATTACH 'file'` opens an empty in-memory schema.
+
+**Intentional differences:** custom `SQLM` snapshots; seeded `random()` / fixed `'now'` by default (`{ random: "os" }` / `{ now: "system" }` match SQLite entropy and wall clock); no C API / on-disk DB / VFS. Machine-readable list: [DIVERGENCES.md](DIVERGENCES.md).
 
 **Know these thin or partial areas** (do not assume full oracle fidelity):
 

package/compat/divergences.json

@@ -48,7 +48,7 @@
       "scope": "select",
       "predicate": "INDEXED BY / NOT INDEXED is accepted and ignored",
       "specifiedBehavior": "Query results match the unhinted plan; missing-index errors are not raised.",
-      "pinnedBy": ["COMPATIBILITY.md"]
+      "pinnedBy": ["indexes/indexed-by.test.ts", "COMPATIBILITY.md"]
     },
     {
       "id": "materialized-hint-ignored",

package/dist/api/statement.d.ts

@@ -31,6 +31,7 @@ export declare class Statement {
     private namedPlan;
     private env;
     private statements;
+    private statementSqls;
     private schemaVersion;
     private constructor();
     /**

package/dist/executor/env.d.ts

@@ -51,6 +51,8 @@ export declare class ExecutionEnv {
     maxRows: number;
     includeNamedRows: boolean;
     includeValues: boolean;
+    /** Source text of the statement currently executing (for sqlite_master.sql). */
+    statementSql: string | null;
     constructor(state: DatabaseState, transactions: TransactionManager, params?: readonly unknown[], functions?: FunctionRegistry, hooks?: ExecutionHooks);
     reset(params: readonly unknown[]): void;
     getBoundParameter(name: string | number): SqlValue;

package/dist/index.js

@@ -640,10 +640,12 @@ var PREC = {
   JSON_ARROW: 80
 };
 var Parser = class {
-  constructor(tokens) {
+  constructor(tokens, source = "") {
     this.tokens = tokens;
+    this.source = source;
   }
   tokens;
+  source;
   pos = 0;
   current() {
     return this.tokens[this.pos] ?? this.tokens[this.tokens.length - 1];
@@ -727,13 +729,21 @@ var Parser = class {
   }
   // ── Statements ──────────────────────────────────────────────────────────
   parseStatements() {
-    const stmts = [];
+    return this.parseUnits().map((unit) => unit.statement);
+  }
+  /** Parse statements with per-statement source slices for catalog `sql` text. */
+  parseUnits() {
+    const units = [];
     while (!this.at("EOF")) {
       if (this.match("SEMI")) continue;
-      stmts.push(this.parseStatement());
+      const start = this.current().start;
+      const statement = this.parseStatement();
+      const end = this.pos > 0 ? this.tokens[this.pos - 1].end : this.current().end;
       this.match("SEMI");
+      const sql = this.source ? this.source.slice(start, end).trimEnd() : "";
+      units.push({ statement, sql });
     }
-    return stmts;
+    return units;
   }
   parseStatement() {
     if (this.match("EXPLAIN")) {
@@ -2359,14 +2369,13 @@ var Parser = class {
     return { kind: "following", expr };
   }
 };
-function parseTokens(tokens) {
-  return new Parser(tokens).parseStatements();
+function parseTokenUnits(tokens, source) {
+  return new Parser(tokens, source).parseUnits();
 }
 
 // src/parser/index.ts
-function parse(sql) {
-  const tokens = tokenize(sql);
-  return parseTokens(tokens);
+function parseUnits(sql) {
+  return parseTokenUnits(tokenize(sql), sql);
 }
 
 // src/runtime/clock.ts
@@ -9160,6 +9169,8 @@ var ExecutionEnv = class {
   maxRows = Number.POSITIVE_INFINITY;
   includeNamedRows = true;
   includeValues = true;
+  /** Source text of the statement currently executing (for sqlite_master.sql). */
+  statementSql = null;
   constructor(state, transactions, params = [], functions = defaultFunctionRegistry, hooks = {}) {
     this.state = state;
     this.transactions = transactions;
@@ -9178,6 +9189,7 @@ var ExecutionEnv = class {
     this.maxRows = Number.POSITIVE_INFINITY;
     this.includeNamedRows = true;
     this.includeValues = true;
+    this.statementSql = null;
   }
   getBoundParameter(name) {
     if (typeof name === "number") {
@@ -9410,6 +9422,78 @@ function executeDetach(stmt, env) {
   return emptyResult(0, env.state.lastInsertRowid);
 }
 
+// src/schema/master-sql.ts
+function normalizeMasterSql(sql) {
+  const trimmed = sql.trim().replace(/;+\s*$/u, "").trim();
+  if (!trimmed) return trimmed;
+  const tokens = tokenize(trimmed);
+  if (tokens.length === 0 || tokens[0].kind === "EOF") return trimmed;
+  let i = 0;
+  const at = (offset, ...kinds) => {
+    const tok = tokens[i + offset];
+    return tok !== void 0 && kinds.includes(tok.kind);
+  };
+  if (!at(0, "CREATE")) return trimmed;
+  i++;
+  if (at(0, "TEMP", "TEMPORARY")) i++;
+  let headKind = "table";
+  if (at(0, "UNIQUE") && at(1, "INDEX")) {
+    headKind = "unique_index";
+    i += 2;
+  } else if (at(0, "VIRTUAL") && at(1, "TABLE")) {
+    headKind = "vtable";
+    i += 2;
+  } else if (at(0, "TABLE")) {
+    headKind = "table";
+    i++;
+  } else if (at(0, "VIEW")) {
+    headKind = "view";
+    i++;
+  } else if (at(0, "INDEX")) {
+    headKind = "index";
+    i++;
+  } else if (at(0, "TRIGGER")) {
+    headKind = "trigger";
+    i++;
+  } else {
+    return trimmed;
+  }
+  if (at(0, "IF") && at(1, "NOT") && at(2, "EXISTS")) i += 3;
+  let nameText = "";
+  let nameEnd = 0;
+  if (tokens[i] && tokens[i].kind !== "EOF" && at(1, "DOT") && tokens[i + 2] && tokens[i + 2].kind !== "EOF") {
+    nameText = trimmed.slice(tokens[i + 2].start, tokens[i + 2].end);
+    nameEnd = tokens[i + 2].end;
+    i += 3;
+  } else if (tokens[i] && tokens[i].kind !== "EOF") {
+    nameText = trimmed.slice(tokens[i].start, tokens[i].end);
+    nameEnd = tokens[i].end;
+    i++;
+  }
+  const body = nameEnd < trimmed.length ? trimmed.slice(nameEnd) : "";
+  const needsSpace = body.length > 0 && !/^[\s(]/u.test(body);
+  const head = headKind === "unique_index" ? "CREATE UNIQUE INDEX" : headKind === "vtable" ? "CREATE VIRTUAL TABLE" : headKind === "view" ? "CREATE VIEW" : headKind === "index" ? "CREATE INDEX" : headKind === "trigger" ? "CREATE TRIGGER" : "CREATE TABLE";
+  if (body.length === 0) return `${head} ${nameText}`;
+  return needsSpace ? `${head} ${nameText} ${body}` : `${head} ${nameText}${body}`;
+}
+function appendAddColumnToMasterSql(originalSql, alterSql) {
+  if (!originalSql || !alterSql) return originalSql;
+  const match = alterSql.match(/\bADD\s+(?:COLUMN\s+)?(.+)$/iu);
+  if (!match?.[1]) return originalSql;
+  const colDef = match[1].trim().replace(/;+\s*$/u, "").trim();
+  const close = originalSql.lastIndexOf(")");
+  if (close < 0) return originalSql;
+  return `${originalSql.slice(0, close)}, ${colDef}${originalSql.slice(close)}`;
+}
+function synthesizeCtasMasterSql(tableName, columnNames) {
+  const cols = columnNames.map(quoteIdentIfNeeded).join(",");
+  return `CREATE TABLE ${quoteIdentIfNeeded(tableName)}(${cols})`;
+}
+function quoteIdentIfNeeded(name) {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) return name;
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
 // src/functions/window.ts
 function rowsEqual(left, right) {
   if (left.length !== right.length) return false;
@@ -11991,14 +12075,17 @@ function scanFtsVocab(db, alias, vocab) {
 
 // src/executor/ddl.ts
 function executeCreateTable(stmt, env) {
+  const sourceSql = env.statementSql ? normalizeMasterSql(env.statementSql) : null;
   if (!stmt.asSelect) {
-    env.state.createTable(stmt);
+    env.state.createTable(stmt, sourceSql);
     env.state.recordChange(0);
     return emptyResult(0, env.state.lastInsertRowid);
   }
   const result = executeSelect2(stmt.asSelect, env);
   const columns = result.columns.map((name) => ({ name, typeName: null, constraints: [] }));
-  const table = env.state.createTable({ ...stmt, columns, constraints: [], asSelect: null });
+  const bareName = stmt.name.includes(".") ? stmt.name.split(".").pop() ?? stmt.name : stmt.name;
+  const ctasSql = synthesizeCtasMasterSql(bareName, result.columns);
+  const table = env.state.createTable({ ...stmt, columns, constraints: [], asSelect: null }, ctasSql);
   for (const values of resultValues(result)) {
     table.insert(
       new Map(table.columns.map((column, index) => [normalizeColumnName(column.name), values[index] ?? null]))
@@ -12023,7 +12110,7 @@ function executeCreateTable(stmt, env) {
   return emptyResult(0, env.state.lastInsertRowid);
 }
 function executeCreateIndex(stmt, env) {
-  const index = env.state.createIndex(stmt);
+  const index = env.state.createIndex(stmt, env.statementSql ? normalizeMasterSql(env.statementSql) : null);
   const table = env.state.getTable(stmt.table);
   try {
     for (const row of table.scan()) {
@@ -12103,6 +12190,7 @@ function executeAlterTable(stmt, env) {
       throw new SqliteError("Cannot add a NOT NULL column with default value NULL", "other");
     table.columns.push(column);
     for (const row of table.rows.values()) row.values.set(normalizeColumnName(column.name), defaultValue);
+    table.originalSql = appendAddColumnToMasterSql(table.originalSql, env.statementSql);
     table.clearEqualityHashes();
     env.state.schemaVersion++;
   } else {
@@ -12150,7 +12238,7 @@ function executeDropIndex(stmt, env) {
   return emptyResult(0, env.state.lastInsertRowid);
 }
 function executeCreateView(stmt, env) {
-  env.state.createView(stmt);
+  env.state.createView(stmt, env.statementSql ? normalizeMasterSql(env.statementSql) : null);
   return emptyResult(0, env.state.lastInsertRowid);
 }
 function executeDropView(stmt, env) {
@@ -12243,7 +12331,7 @@ function executeCreateTrigger(stmt, env) {
     forEachRow: stmt.forEachRow,
     body: stmt.body,
     updateColumns: stmt.updateColumns,
-    originalSql: null
+    originalSql: env.statementSql ? normalizeMasterSql(env.statementSql) : null
   });
   return emptyResult(0, env.state.lastInsertRowid);
 }
@@ -12340,7 +12428,7 @@ function triggerScope(table, oldRow, newValues) {
 
 // src/executor/vtable.ts
 function executeCreateVirtualTable(stmt, env) {
-  env.state.createVirtualTable(stmt);
+  env.state.createVirtualTable(stmt, env.statementSql ? normalizeMasterSql(env.statementSql) : null);
   env.state.recordChange(0);
   return emptyResult(0, env.state.lastInsertRowid);
 }
@@ -13642,10 +13730,11 @@ function executeAnalyze(stmt, env) {
 
 // src/api/statement.ts
 var Statement = class _Statement {
-  constructor(database, sql, statements) {
+  constructor(database, sql, statements, statementSqls) {
     this.database = database;
     this.sql = sql;
     this.statements = statements;
+    this.statementSqls = statementSqls;
     this.schemaVersion = database.state.schemaVersion;
   }
   database;
@@ -13653,13 +13742,24 @@ var Statement = class _Statement {
   namedPlan = null;
   env = null;
   statements;
+  statementSqls;
   schemaVersion;
   /**
    * Construct a {@link Statement} for {@link Database.prepare} / {@link Database.exec}.
    * @internal
    */
-  static create(database, sql, statements) {
-    return new _Statement(database, sql, statements);
+  static create(database, sql, statements, statementSqls) {
+    return new _Statement(database, sql, statements, statementSqls ?? statements.map(() => sql));
+  }
+  /** @internal Build from {@link parseUnits}. */
+  static createFromSql(database, sql) {
+    const units = parseUnits(sql);
+    return new _Statement(
+      database,
+      sql,
+      units.map((u) => u.statement),
+      units.map((u) => u.sql)
+    );
   }
   /**
    * Execute for side effects (INSERT / UPDATE / DELETE / DDL).
@@ -13722,9 +13822,11 @@ var Statement = class _Statement {
     env.includeValues = true;
     this.bindNamed(env, params);
     let result;
-    for (const statement of this.statements) {
-      result = executeStatement(statement, env);
+    for (let i = 0; i < this.statements.length; i++) {
+      env.statementSql = this.statementSqls[i] ?? this.sql;
+      result = executeStatement(this.statements[i], env);
     }
+    env.statementSql = null;
     return result;
   }
   obtainEnv(params) {
@@ -13744,7 +13846,9 @@ var Statement = class _Statement {
   }
   reprepareIfSchemaChanged() {
     if (this.schemaVersion === this.database.state.schemaVersion) return;
-    this.statements = parse(this.sql);
+    const units = parseUnits(this.sql);
+    this.statements = units.map((u) => u.statement);
+    this.statementSqls = units.map((u) => u.sql);
     this.env = null;
     this.namedPlan = null;
     this.schemaVersion = this.database.state.schemaVersion;
@@ -13835,7 +13939,7 @@ var Database = class {
     if (arguments.length > 1) {
       throw new SqliteError("exec() does not accept parameters; use prepare() or query()", "misuse");
     }
-    Statement.create(this, sql, parse(sql)).run();
+    Statement.createFromSql(this, sql).run();
   }
   /**
    * Execute a single-statement query and return all rows as objects keyed by column name.
@@ -13985,14 +14089,19 @@ var Database = class {
     if (this.closed) throw new SqliteError("Database is closed", "misuse");
   }
   prepareSingle(sql) {
-    const statements = parse(sql);
-    if (statements.length === 0) {
+    const units = parseUnits(sql);
+    if (units.length === 0) {
       throw new SqliteError("empty statement", "misuse");
     }
-    if (statements.length > 1) {
+    if (units.length > 1) {
       throw new SqliteError("query()/prepare() accept a single statement only; use exec() for scripts", "misuse");
     }
-    return Statement.create(this, sql, statements);
+    return Statement.create(
+      this,
+      sql,
+      units.map((u) => u.statement),
+      units.map((u) => u.sql)
+    );
   }
 };
 var disposeKey = Symbol.dispose;