@jarenjs/db 0.34.0

package/src/dialect.js

@@ -0,0 +1,297 @@
+//@ts-check
+/**
+ * @file The dialect seam: the ONLY place SQL text is produced. A
+ * dialect is data plus a small emitter — a spelling spec (how to quote
+ * an identifier, reference a parameter, extract a JSON member, open a
+ * savepoint) composed by {@link createDialect} into the DDL and DML
+ * statement builders the store consumes. Nothing outside a dialect
+ * concatenates SQL; that costs one indirection now, and without it a
+ * second backend is a rewrite.
+ *
+ * Deliberately NOT in the dialect, because they are behavioural rather
+ * than syntactic: whether functions can be registered per connection,
+ * whether change capture exists and in what form, and whether tables
+ * can be restructured in place. Those are capabilities on the
+ * connection.
+ */
+
+/**
+ * A typed member path into the JSON document column: name segments for
+ * object members, index segments for array positions. Produced by the
+ * DDL planner (from analyzed index paths) and the patch translator
+ * (from pointers discriminated against the live document).
+ * @typedef {{ name: string } | { index: number }} JsonPathSegment
+ */
+
+/**
+ * Compose a dialect from its spelling spec. Every statement the store
+ * ever runs is built here from the spec's primitives, so a spec with
+ * different quoting or parameter style produces correspondingly
+ * different SQL from the same model — the property the test-double
+ * dialect pins.
+ * @param {{
+ *   name: string,
+ *   capabilities: Record<string, any>,
+ *   tableSuffix: string,
+ *   docColumnType: string,
+ *   quoteIdentifier: (s: string) => string,
+ *   parameterRef: (i: number, name: string) => string,
+ *   stringLiteral: (s: string) => string,
+ *   booleanLiteral: (b: boolean) => string,
+ *   typeFor: (schemaType: string | undefined, hint: string) => string,
+ *   limitClause: (limit: number, offset?: number) => string,
+ *   jsonPathText: (segments: JsonPathSegment[]) => string | null,
+ *   jsonExtract: (columnSql: string, pathText: string) => string,
+ *   jsonSet: (exprSql: string, pathText: string, valueSql: string) => string,
+ *   jsonRemove: (exprSql: string, pathText: string) => string,
+ *   jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string,
+ *   jsonEncode: (paramSql: string) => string,
+ *   jsonText: (columnSql: string) => string,
+ *   jsonAgg: (exprSql: string) => string,
+ *   jsonTypeOf: (columnSql: string, pathText: string) => string,
+ *   valueTypeOf: (paramSql: string) => string,
+ *   strStartsWith: (valueSql: string, patternA: string, patternB: string) => string,
+ *   strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string,
+ *   strContains: (valueSql: string, patternSql: string) => string,
+ *   orderNulls: (nullsFirst: boolean) => string,
+ *   rowIdentity: () => string,
+ *   explainQuery: (sql: string) => string,
+ *   excludedRef: (columnSql: string) => string,
+ *   tx: { begin: string, beginImmediate: string, commit: string,
+ *     rollback: string,
+ *     savepoint: (n: string) => string, release: (n: string) => string,
+ *     rollbackTo: (n: string) => string },
+ *   pragma: { busyTimeout: (ms: number) => string,
+ *     journalMode: (mode: string) => string,
+ *     foreignKeys: (on: boolean) => string },
+ *   introspect: { version: () => string, compileOptions: () => string,
+ *     tableExists: () => string, columns: (table: string) => string,
+ *     indexes: (table: string) => string,
+ *     indexColumns: (index: string) => string,
+ *     foreignKeysOn: () => string,
+ *     foreignKeyList: (table: string) => string },
+ * }} spec
+ * @returns {any} the frozen dialect
+ */
+export function createDialect(spec) {
+  const q = spec.quoteIdentifier;
+  const p = spec.parameterRef;
+
+  const ddl = Object.freeze({
+    /**
+     * One collection's physical table: a key column, the JSON document
+     * column, and a virtual generated column per indexed path.
+     * @param {{ table: string, keyColumn: string, keyType: string,
+     *   docColumn: string, generated: { name: string, type: string,
+     *   pathText: string }[] }} shape
+     * @returns {string}
+     */
+    createTable({ table, keyColumn, keyType, docColumn, generated }) {
+      const columns = [
+        `${q(keyColumn)} ${keyType} PRIMARY KEY`,
+        `${q(docColumn)} ${spec.docColumnType} NOT NULL`,
+        ...generated.map((g) =>
+          `${q(g.name)} ${g.type} GENERATED ALWAYS AS `
+          + `(${spec.jsonExtract(q(docColumn), g.pathText)}) VIRTUAL`),
+      ];
+      return `CREATE TABLE ${q(table)} (${columns.join(', ')})${spec.tableSuffix}`;
+    },
+    /**
+     * @param {{ name: string, table: string, columns: string[],
+     *   unique: boolean }} shape
+     * @returns {string}
+     */
+    createIndex({ name, table, columns, unique }) {
+      return `CREATE ${unique ? 'UNIQUE ' : ''}INDEX ${q(name)} `
+        + `ON ${q(table)} (${columns.map(q).join(', ')})`;
+    },
+    /**
+     * Add one virtual generated column to an existing table (a new
+     * indexed path arriving through a migration).
+     * @param {{ table: string, docColumn: string,
+     *   column: { name: string, type: string, pathText: string } }} shape
+     * @returns {string}
+     */
+    addGeneratedColumn({ table, docColumn, column }) {
+      return `ALTER TABLE ${q(table)} ADD COLUMN ${q(column.name)} ${column.type} `
+        + `GENERATED ALWAYS AS (${spec.jsonExtract(q(docColumn), column.pathText)}) VIRTUAL`;
+    },
+    /**
+     * @param {string} table
+     * @param {string} column
+     * @returns {string}
+     */
+    dropColumn(table, column) {
+      return `ALTER TABLE ${q(table)} DROP COLUMN ${q(column)}`;
+    },
+    /**
+     * Add one plain (non-generated) column — the additive migration
+     * strategy. The column shape matches `createRelationalTable`'s.
+     * @param {{ table: string, column: { name: string, type: string,
+     *   check?: string, references?: { table: string, column: string,
+     *   onDelete: 'cascade' | 'restrict' | 'setNull' } } }} shape
+     * @returns {string}
+     */
+    addColumn({ table, column }) {
+      const onDeleteSql = { cascade: 'CASCADE', restrict: 'RESTRICT', setNull: 'SET NULL' };
+      let sql = `ALTER TABLE ${q(table)} ADD COLUMN ${q(column.name)} ${column.type}`;
+      if (column.check !== undefined) sql += ` CHECK (${column.check})`;
+      if (column.references !== undefined) {
+        sql += ` REFERENCES ${q(column.references.table)} (${q(column.references.column)})`
+          + ` ON DELETE ${onDeleteSql[column.references.onDelete]}`;
+      }
+      return sql;
+    },
+    /**
+     * @param {string} name
+     * @returns {string}
+     */
+    dropIndex(name) {
+      return `DROP INDEX ${q(name)}`;
+    },
+    /**
+     * @param {string} table
+     * @returns {string}
+     */
+    dropTable(table) {
+      return `DROP TABLE ${q(table)}`;
+    },
+    /**
+     * @param {string} from
+     * @param {string} to
+     * @returns {string}
+     */
+    renameTable(from, to) {
+      return `ALTER TABLE ${q(from)} RENAME TO ${q(to)}`;
+    },
+    /**
+     * @param {string} table
+     * @param {string} from
+     * @param {string} to
+     * @returns {string}
+     */
+    renameColumn(table, from, to) {
+      return `ALTER TABLE ${q(table)} RENAME COLUMN ${q(from)} TO ${q(to)}`;
+    },
+    /**
+     * A relational entity table: typed columns (keys, mapped scalars,
+     * foreign keys), per-column CHECKs, real REFERENCES clauses with
+     * declared on-delete behaviour, and the JSONB document column for
+     * everything unmapped. One generator, both document kinds.
+     * @param {{ table: string, columns: {
+     *   name: string, type: string, notNull?: boolean,
+     *   primaryKey?: boolean, check?: string,
+     *   references?: { table: string, column: string,
+     *     onDelete: 'cascade' | 'restrict' | 'setNull' } }[],
+     *   compositeKey?: string[] }} shape
+     * @returns {string}
+     */
+    createRelationalTable({ table, columns, compositeKey }) {
+      const onDeleteSql = { cascade: 'CASCADE', restrict: 'RESTRICT', setNull: 'SET NULL' };
+      const rendered = columns.map((column) => {
+        let sql = `${q(column.name)} ${column.type}`;
+        if (column.primaryKey === true) sql += ' PRIMARY KEY';
+        if (column.notNull === true) sql += ' NOT NULL';
+        if (column.check !== undefined) sql += ` CHECK (${column.check})`;
+        if (column.references !== undefined) {
+          sql += ` REFERENCES ${q(column.references.table)} (${q(column.references.column)})`
+            + ` ON DELETE ${onDeleteSql[column.references.onDelete]}`;
+        }
+        return sql;
+      });
+      if (compositeKey !== undefined && compositeKey.length > 0)
+        rendered.push(`PRIMARY KEY (${compositeKey.map(q).join(', ')})`);
+      return `CREATE TABLE ${q(table)} (${rendered.join(', ')})${spec.tableSuffix}`;
+    },
+    /**
+     * A plain (non-collection) table — the migration history table.
+     * @param {{ table: string, columns: { name: string, type: string,
+     *   primaryKey?: boolean }[] }} shape
+     * @returns {string}
+     */
+    createPlainTable({ table, columns }) {
+      const rendered = columns.map((column) =>
+        `${q(column.name)} ${column.type}${column.primaryKey === true ? ' PRIMARY KEY' : ''}`);
+      return `CREATE TABLE IF NOT EXISTS ${q(table)} (${rendered.join(', ')})${spec.tableSuffix}`;
+    },
+  });
+
+  const dml = Object.freeze({
+    /** @param {{ table: string, keyColumn: string, docColumn: string }} s */
+    insert({ table, keyColumn, docColumn }) {
+      return `INSERT INTO ${q(table)} (${q(keyColumn)}, ${q(docColumn)}) `
+        + `VALUES (${p(1, 'key')}, ${spec.jsonEncode(p(2, 'doc'))})`;
+    },
+    /**
+     * Insert with a database-allocated key, read back in the same
+     * statement.
+     * @param {{ table: string, keyColumn: string, docColumn: string }} s
+     */
+    insertAllocated({ table, keyColumn, docColumn }) {
+      return `INSERT INTO ${q(table)} (${q(docColumn)}) `
+        + `VALUES (${spec.jsonEncode(p(1, 'doc'))}) RETURNING ${q(keyColumn)} AS ${q('key')}`;
+    },
+    /** @param {{ table: string, keyColumn: string, docColumn: string }} s */
+    upsert({ table, keyColumn, docColumn }) {
+      return `INSERT INTO ${q(table)} (${q(keyColumn)}, ${q(docColumn)}) `
+        + `VALUES (${p(1, 'key')}, ${spec.jsonEncode(p(2, 'doc'))}) `
+        + `ON CONFLICT (${q(keyColumn)}) DO UPDATE SET `
+        + `${q(docColumn)} = ${spec.excludedRef(q(docColumn))}`;
+    },
+    /** @param {{ table: string, keyColumn: string, docColumn: string }} s */
+    get({ table, keyColumn, docColumn }) {
+      return `SELECT ${spec.jsonText(q(docColumn))} AS ${q('doc')} `
+        + `FROM ${q(table)} WHERE ${q(keyColumn)} = ${p(1, 'key')}`;
+    },
+    /** @param {{ table: string, keyColumn: string }} s */
+    del({ table, keyColumn }) {
+      return `DELETE FROM ${q(table)} WHERE ${q(keyColumn)} = ${p(1, 'key')}`;
+    },
+    /**
+     * Rewrite the document column through a JSON-set expression chain
+     * (the translated-patch path) or a bound parameter (the fallback).
+     * @param {{ table: string, keyColumn: string, docColumn: string }} s
+     * @param {string} expression - SQL over the document column
+     * @param {number} keyIndex - 1-based position of the key parameter
+     */
+    updateDoc({ table, keyColumn, docColumn }, expression, keyIndex) {
+      return `UPDATE ${q(table)} SET ${q(docColumn)} = ${expression} `
+        + `WHERE ${q(keyColumn)} = ${p(keyIndex, 'key')}`;
+    },
+  });
+
+  return Object.freeze({
+    name: spec.name,
+    capabilities: Object.freeze({ ...spec.capabilities }),
+    docColumnType: spec.docColumnType,
+    quoteIdentifier: q,
+    parameterRef: p,
+    stringLiteral: spec.stringLiteral,
+    booleanLiteral: spec.booleanLiteral,
+    typeFor: spec.typeFor,
+    limitClause: spec.limitClause,
+    jsonPathText: spec.jsonPathText,
+    jsonExtract: spec.jsonExtract,
+    jsonSet: spec.jsonSet,
+    jsonRemove: spec.jsonRemove,
+    jsonAppend: spec.jsonAppend,
+    jsonEncode: spec.jsonEncode,
+    jsonText: spec.jsonText,
+    jsonAgg: spec.jsonAgg,
+    jsonTypeOf: spec.jsonTypeOf,
+    valueTypeOf: spec.valueTypeOf,
+    strStartsWith: spec.strStartsWith,
+    strEndsWith: spec.strEndsWith,
+    strContains: spec.strContains,
+    orderNulls: spec.orderNulls,
+    rowIdentity: spec.rowIdentity,
+    explainQuery: spec.explainQuery,
+    excludedRef: spec.excludedRef,
+    epochFromRfc3339: spec.epochFromRfc3339,
+    tx: Object.freeze({ ...spec.tx }),
+    pragma: Object.freeze({ ...spec.pragma }),
+    introspect: Object.freeze({ ...spec.introspect }),
+    ddl,
+    dml,
+  });
+}

package/src/dialects/sqlite.js

@@ -0,0 +1,175 @@
+//@ts-check
+/**
+ * @file The SQLite dialect — the first spelling of the dialect
+ * contract, not the only conceivable one. Documents are stored JSONB
+ * in a BLOB column of a STRICT table; indexed paths become virtual
+ * generated columns over `jsonb_extract`; reads render back to text
+ * through `json()`. Parameters are positional (`?`) because every
+ * binding this package ships binds arrays.
+ */
+
+import { createDialect } from '../dialect.js';
+
+/** @param {string} s */
+function quoteIdentifier(s) {
+  return `"${String(s).replace(/"/g, '""')}"`;
+}
+
+/** @param {string} s */
+function stringLiteral(s) {
+  return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+/**
+ * SQLite JSON path text from typed segments. Object members are always
+ * quoted (`$."name"`), which covers spaces, dots and leading digits; a
+ * member name SQLite's path grammar cannot carry (an embedded `"` or a
+ * control character) returns `null` so the caller falls back to a
+ * whole-document strategy instead of emitting a wrong path.
+ * @param {import('../dialect.js').JsonPathSegment[]} segments
+ * @returns {string | null}
+ */
+function jsonPathText(segments) {
+  let text = '$';
+  for (const segment of segments) {
+    if ('index' in segment) {
+      text += `[${segment.index}]`;
+      continue;
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/["\u0000-\u001f]/.test(segment.name)) return null;
+    text += `."${segment.name}"`;
+  }
+  return text;
+}
+
+/**
+ * The declared column type for a schema-declared value type. Under
+ * STRICT tables every column needs a type from the strict set; a path
+ * whose schema declares none is honestly `ANY`.
+ * @param {string | undefined} schemaType
+ * @param {string} hint - `'key'` or `'generated'`
+ * @returns {string}
+ */
+function typeFor(schemaType, hint) {
+  switch (schemaType) {
+    case 'string': return 'TEXT';
+    case 'integer': return 'INTEGER';
+    case 'number': return 'REAL';
+    case 'boolean': return 'INTEGER';
+    default: return hint === 'key' ? 'TEXT' : 'ANY';
+  }
+}
+
+/**
+ * A guarded PRAGMA argument: journal modes and similar keywords are a
+ * closed word set, never interpolated user text.
+ * @param {string} word
+ * @returns {string}
+ */
+function pragmaWord(word) {
+  if (!/^[a-z_]+$/i.test(String(word)))
+    throw new TypeError(`not a PRAGMA keyword: '${word}'`);
+  return String(word);
+}
+
+export const sqliteDialect = createDialect({
+  name: 'sqlite',
+  capabilities: {
+    jsonb: true,
+    generatedColumns: true,
+    returning: true,
+    upsert: true,
+    savepoints: true,
+    alterTableFull: false,
+  },
+  tableSuffix: ' STRICT',
+  // RFC 3339 text → epoch milliseconds, in SQL: the migration planner
+  // populates derived instant columns with it (rounded to the ms;
+  // finer precision is the write contract's business, §10.3)
+  epochFromRfc3339: (valueSql) =>
+    `CAST(round((julianday(${valueSql}) - 2440587.5) * 86400000.0) AS INTEGER)`,
+  docColumnType: 'BLOB',
+  quoteIdentifier,
+  parameterRef: () => '?',
+  stringLiteral,
+  booleanLiteral: (b) => (b ? '1' : '0'),
+  typeFor,
+  limitClause: (limit, offset) => (offset !== undefined && offset > 0
+    ? `LIMIT ${limit === null ? -1 : limit} OFFSET ${offset}`
+    : `LIMIT ${limit === null ? -1 : limit}`),
+  jsonPathText,
+  jsonExtract: (columnSql, pathText) =>
+    `jsonb_extract(${columnSql}, ${stringLiteral(pathText)})`,
+  jsonSet: (exprSql, pathText, valueSql) =>
+    `jsonb_set(${exprSql}, ${stringLiteral(pathText)}, ${valueSql})`,
+  jsonRemove: (exprSql, pathText) =>
+    `jsonb_remove(${exprSql}, ${stringLiteral(pathText)})`,
+  jsonAppend: (exprSql, arrayPathText, valueSql) =>
+    `jsonb_insert(${exprSql}, ${stringLiteral(`${arrayPathText}[#]`)}, ${valueSql})`,
+  jsonEncode: (paramSql) => `jsonb(${paramSql})`,
+  jsonText: (columnSql) => `json(${columnSql})`,
+  jsonAgg: (exprSql) => `json_group_array(${exprSql})`,
+  jsonTypeOf: (columnSql, pathText) =>
+    `json_type(${columnSql}, ${stringLiteral(pathText)})`,
+  valueTypeOf: (paramSql) => `typeof(${paramSql})`,
+  strStartsWith: (valueSql, patternA, patternB) =>
+    `substr(${valueSql}, 1, length(${patternA})) = ${patternB}`,
+  strEndsWith: (valueSql, patternA, patternB, patternC) =>
+    `(length(${patternA}) = 0 OR substr(${valueSql}, -length(${patternB})) = ${patternC})`,
+  strContains: (valueSql, patternSql) => `instr(${valueSql}, ${patternSql}) > 0`,
+  orderNulls: (nullsFirst) => (nullsFirst ? ' NULLS FIRST' : ' NULLS LAST'),
+  rowIdentity: () => '"rowid"',
+  explainQuery: (sql) => `EXPLAIN QUERY PLAN ${sql}`,
+  excludedRef: (columnSql) => `excluded.${columnSql}`,
+  tx: {
+    begin: 'BEGIN',
+    beginImmediate: 'BEGIN IMMEDIATE',
+    commit: 'COMMIT',
+    rollback: 'ROLLBACK',
+    savepoint: (n) => `SAVEPOINT ${quoteIdentifier(n)}`,
+    release: (n) => `RELEASE SAVEPOINT ${quoteIdentifier(n)}`,
+    rollbackTo: (n) => `ROLLBACK TO SAVEPOINT ${quoteIdentifier(n)}`,
+  },
+  pragma: {
+    busyTimeout: (ms) => `PRAGMA busy_timeout = ${Math.trunc(ms)}`,
+    journalMode: (mode) => `PRAGMA journal_mode = ${pragmaWord(mode)}`,
+    foreignKeys: (on) => `PRAGMA foreign_keys = ${on ? 'ON' : 'OFF'}`,
+    foreignKeyCheck: () => 'PRAGMA foreign_key_check',
+  },
+  introspect: {
+    version: () => 'SELECT sqlite_version() AS version',
+    compileOptions: () =>
+      'SELECT compile_options AS name FROM pragma_compile_options',
+    tableExists: () =>
+      "SELECT name FROM sqlite_schema WHERE type = 'table' AND name = ?",
+    columns: (table) =>
+      `SELECT name, type, hidden FROM pragma_table_xinfo(${stringLiteral(table)})`,
+    indexes: (table) =>
+      `SELECT name, "unique" AS uniq, origin FROM pragma_index_list(${stringLiteral(table)})`,
+    indexColumns: (index) =>
+      `SELECT name FROM pragma_index_info(${stringLiteral(index)})`,
+    foreignKeysOn: () => 'SELECT foreign_keys AS enabled FROM pragma_foreign_keys',
+    dataVersion: () => 'SELECT data_version AS v FROM pragma_data_version',
+    foreignKeyList: (table) =>
+      `SELECT "table" AS target, "from" AS source_column, "to" AS target_column, `
+      + `on_delete, on_update, seq FROM pragma_foreign_key_list(${stringLiteral(table)}) `
+      + 'ORDER BY id, seq',
+    // Every schema object one table owns, with the CREATE text SQLite
+    // stored verbatim. That text is where the physical facts no pragma
+    // reports actually live — STRICT, CHECK, a generated column's
+    // expression, a partial index predicate, an index term's collation
+    // and direction, the primary key's position — so comparing it against
+    // the planned statements is what makes "verify, never alter" true
+    // rather than approximately true.
+    declaredSql: (table) =>
+      'SELECT type, name, sql FROM sqlite_schema '
+      + `WHERE tbl_name = ${stringLiteral(table)} AND sql IS NOT NULL `
+      + 'ORDER BY type, name',
+    // the whole declared schema, for shape-equality comparison after a
+    // rebuild: every object that carries SQL text, in a stable order
+    schemaDump: () =>
+      "SELECT type, name, tbl_name AS owner, sql FROM sqlite_schema "
+      + "WHERE sql IS NOT NULL ORDER BY type, name",
+  },
+});