@webority/mobile-core 0.0.23

package/lib/module/sqlite/index.js

@@ -0,0 +1,594 @@
+"use strict";
+
+import * as ExpoSqlite from 'expo-sqlite';
+import { Logger } from "../logger/index.js";
+import { adaptExpoSqlite } from "./adapters/expo.js";
+
+/**
+ * expo-sqlite is the fleet's only sanctioned SQLite driver (react-native.md:
+ * "we will always use expo-sqlite, what Expo gives, we don't look elsewhere
+ * ever") — this module resolves it automatically, with no app-side wiring.
+ * `setSqliteImplementation` still exists, narrowed to tests and the showcase:
+ * it injects a denying/failing backend to reach error paths a healthy device
+ * never takes, the same pattern every other injectable surface in this
+ * library follows. It is not a way to pick an alternate real driver.
+ */
+
+/** Only what a test or an app injected; null means use expo-sqlite. */
+let backend = null;
+
+/** expo-sqlite, adapted once and memoised. The only driver this module resolves. */
+let expoDriver;
+
+/**
+ * Test/showcase-only injection point — see the module header. Not a way to
+ * pick an alternate real driver; `@webority/mobile-core` always
+ * resolves expo-sqlite when nothing is injected. Pass `null` to clear it.
+ */
+export const setSqliteImplementation = impl => {
+  backend = impl;
+};
+
+/**
+ * expo-sqlite is a required peer, so the JS module always resolves. What can be
+ * missing is the NATIVE side: an app that installed the package without running
+ * the native install gets a module without the one call the adapter needs.
+ * Checking it is what lets `isSqliteAvailable` mean something and makes the
+ * error below reachable.
+ *
+ * An INJECTED driver is taken on trust, like every other seam in this package.
+ */
+const hasNativeSqlite = mod => typeof mod?.openDatabaseAsync === 'function';
+const resolveDriver = () => {
+  if (backend) {
+    return backend;
+  }
+  if (expoDriver === undefined) {
+    const mod = ExpoSqlite;
+    expoDriver = hasNativeSqlite(mod) ? adaptExpoSqlite(mod) : null;
+  }
+  return expoDriver;
+};
+export const isSqliteAvailable = () => resolveDriver() !== null;
+const requireBackend = op => {
+  const b = resolveDriver();
+  if (!b) {
+    const err = new Error(`[@webority/mobile-core] No SQLite driver available; cannot ${op}. ` + 'Install expo-sqlite (the only sanctioned driver) in the consuming app.');
+    Logger.error(err.message);
+    throw err;
+  }
+  return b;
+};
+
+/** The ledger of applied migrations. Never emptied by `wipe`. */
+export const MIGRATIONS_TABLE = '_webority_migrations';
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * SQLite cannot bind an identifier to `?`, so every table/column name reaching
+ * a statement is concatenated. This is the ONE place that is allowed to happen,
+ * and it throws rather than quoting a hostile name into something executable.
+ */
+export const assertSqlIdentifier = (value, kind = 'identifier') => {
+  if (typeof value !== 'string' || !IDENTIFIER.test(value)) {
+    throw new Error(`[@webority/mobile-core] Invalid SQL ${kind} ${JSON.stringify(value)}. ` + 'Only letters, digits and underscores are allowed, and it must not start with a digit. ' + 'Pass values as bound parameters instead of building them into the name.');
+  }
+  return value;
+};
+const quoteIdentifier = (value, kind = 'identifier') => `"${assertSqlIdentifier(value, kind)}"`;
+
+/** For names read back out of sqlite_master, which may legitimately be quoted. */
+const escapeIdentifier = value => `"${value.replace(/"/g, '""')}"`;
+const COLUMN_DEFINITION = /^[A-Za-z0-9_ ,.()'"+*/=<>|%:$-]+$/;
+const assertColumnDefinition = (definition, column) => {
+  const trimmed = typeof definition === 'string' ? definition.trim() : '';
+  if (trimmed.length === 0 || !COLUMN_DEFINITION.test(trimmed) || trimmed.includes('--')) {
+    throw new Error(`[@webority/mobile-core] Invalid column definition for "${column}": ` + `${JSON.stringify(definition)}. A definition is raw SQL such as ` + "'INTEGER NOT NULL DEFAULT 0' and may not contain a statement separator or a comment.");
+  }
+  return trimmed;
+};
+
+/** Normalise a JS value into something every SQLite driver can bind. */
+export const toSqliteValue = value => {
+  if (value === undefined) {
+    return null;
+  }
+  if (typeof value === 'boolean') {
+    return value ? 1 : 0;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return value;
+};
+
+/** SQLite has no boolean type, so a stored flag comes back as 0/1 or '0'/'1'. */
+export const fromSqliteBoolean = value => {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return value !== 0;
+  }
+  if (typeof value === 'string') {
+    const normalised = value.trim().toLowerCase();
+    return normalised === '1' || normalised === 'true';
+  }
+  return false;
+};
+
+/**
+ * Build an `IN (...)` clause with one placeholder per value. An empty list
+ * yields a clause that matches nothing, because `IN ()` is a syntax error.
+ */
+export const whereIn = (column, values) => {
+  const quoted = quoteIdentifier(column, 'column name');
+  if (values.length === 0) {
+    return {
+      sql: '1 = 0',
+      params: []
+    };
+  }
+  return {
+    sql: `${quoted} IN (${values.map(() => '?').join(', ')})`,
+    params: values.map(toSqliteValue)
+  };
+};
+
+/**
+ * Either a map of column to value (ANDed, `null` meaning IS NULL) or a raw
+ * fragment for anything the object form cannot express.
+ */
+
+const isRawWhere = where => typeof where.sql === 'string' && Object.keys(where).every(key => key === 'sql' || key === 'params');
+const buildWhere = where => {
+  if (!where) {
+    return {
+      clause: '',
+      params: []
+    };
+  }
+  if (isRawWhere(where)) {
+    const sql = where.sql.trim();
+    if (sql.length === 0) {
+      return {
+        clause: '',
+        params: []
+      };
+    }
+    return {
+      clause: ` WHERE ${sql}`,
+      params: [...(where.params ?? [])]
+    };
+  }
+  const entries = Object.entries(where);
+  if (entries.length === 0) {
+    return {
+      clause: '',
+      params: []
+    };
+  }
+  const parts = [];
+  const params = [];
+  for (const [column, rawValue] of entries) {
+    const quoted = quoteIdentifier(column, 'column name');
+    const value = toSqliteValue(rawValue);
+    if (value === null) {
+      parts.push(`${quoted} IS NULL`);
+    } else {
+      parts.push(`${quoted} = ?`);
+      params.push(value);
+    }
+  }
+  return {
+    clause: ` WHERE ${parts.join(' AND ')}`,
+    params
+  };
+};
+const buildOrderBy = orderBy => {
+  if (orderBy === undefined) {
+    return '';
+  }
+  const terms = orderBy.split(',').map(term => term.trim()).filter(term => term.length > 0);
+  if (terms.length === 0) {
+    return '';
+  }
+  const rendered = terms.map(term => {
+    const [column, direction, ...rest] = term.split(/\s+/);
+    if (rest.length > 0) {
+      throw new Error(`[@webority/mobile-core] Invalid orderBy term ${JSON.stringify(term)}. ` + 'Expected a column name optionally followed by ASC or DESC.');
+    }
+    const quoted = quoteIdentifier(column, 'orderBy column');
+    if (direction === undefined) {
+      return quoted;
+    }
+    const upper = direction.toUpperCase();
+    if (upper !== 'ASC' && upper !== 'DESC') {
+      throw new Error(`[@webority/mobile-core] Invalid sort direction ${JSON.stringify(direction)} ` + `in orderBy ${JSON.stringify(orderBy)}. Expected ASC or DESC.`);
+    }
+    return `${quoted} ${upper}`;
+  });
+  return ` ORDER BY ${rendered.join(', ')}`;
+};
+const assertNonNegativeInteger = (value, kind) => {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`[@webority/mobile-core] Invalid ${kind} ${JSON.stringify(value)}. ` + 'Expected a non-negative integer.');
+  }
+  return value;
+};
+/**
+ * FNV-1a with the length mixed in, so two different bodies must also share a
+ * length before they can be mistaken for one another. Deliberately hand-rolled:
+ * this module ships with zero dependencies.
+ */
+const hashString = value => {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return `${hash.toString(16).padStart(8, '0')}-${value.length.toString(16)}`;
+};
+
+/**
+ * A function migration has no stable text: release bundles are minified, so
+ * hashing its source would report a mismatch on every production build. Its
+ * body is therefore unverifiable, and only the switch between a function and
+ * SQL is detected.
+ */
+const migrationChecksum = migration => {
+  if (typeof migration.up === 'function') {
+    return hashString('fn');
+  }
+  const sql = Array.isArray(migration.up) ? migration.up.join('\n') : migration.up;
+  return hashString(sql);
+};
+export const DEFAULT_PRAGMAS = {
+  journal_mode: 'WAL',
+  synchronous: 'NORMAL',
+  foreign_keys: 'ON',
+  busy_timeout: 5000
+};
+const PRAGMA_VALUE = /^[A-Za-z0-9_-]+$/;
+const renderPragmaValue = (name, value) => {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error(`[@webority/mobile-core] Invalid value for PRAGMA ${name}: ${value}.`);
+    }
+    return String(value);
+  }
+  if (!PRAGMA_VALUE.test(value)) {
+    throw new Error(`[@webority/mobile-core] Invalid value ${JSON.stringify(value)} for ` + `PRAGMA ${name}. PRAGMA values cannot be bound, so only letters, digits, ` + 'underscores and hyphens are accepted.');
+  }
+  return value;
+};
+const createDb = (name, raw) => {
+  // SQLite has ONE transaction per connection, so two concurrent transaction()
+  // calls would interleave their BEGIN/COMMIT and the second BEGIN would be
+  // rejected outright. An outbox flush racing a UI write is exactly that case,
+  // so transactions queue on this chain rather than run concurrently.
+  let txQueue = Promise.resolve();
+  const execute = async (sql, params) => {
+    try {
+      return await raw.execute(sql, params);
+    } catch (error) {
+      Logger.error(`[@webority/mobile-core] SQLite execute failed: ${sql}`, error);
+      throw error;
+    }
+  };
+  const select = async (sql, params) => {
+    const result = await execute(sql, params);
+    return result.rows;
+  };
+  const selectOne = async (sql, params) => {
+    const rows = await select(sql, params);
+    return rows.length > 0 ? rows[0] : null;
+  };
+  const runTransaction = async work => {
+    await raw.execute('BEGIN');
+    let result;
+    try {
+      result = await work({
+        execute,
+        select,
+        selectOne
+      });
+    } catch (error) {
+      try {
+        await raw.execute('ROLLBACK');
+      } catch (rollbackError) {
+        Logger.error('[@webority/mobile-core] SQLite ROLLBACK failed', rollbackError);
+      }
+      throw error;
+    }
+    try {
+      await raw.execute('COMMIT');
+    } catch (commitError) {
+      // A failed COMMIT leaves the transaction open, which would poison every
+      // later one on this connection. Roll back before surfacing it.
+      try {
+        await raw.execute('ROLLBACK');
+      } catch {
+        /* the connection is already in a bad state; the commit error is the useful one */
+      }
+      throw commitError;
+    }
+    return result;
+  };
+  const transaction = work => {
+    // A rejected link must not break the chain for everyone behind it.
+    const next = txQueue.then(() => runTransaction(work), () => runTransaction(work));
+    txQueue = next.catch(() => undefined);
+    return next;
+  };
+  const insertSql = (table, row) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const entries = Object.entries(row);
+    if (entries.length === 0) {
+      throw new Error(`[@webority/mobile-core] Cannot insert an empty row into ${table}. ` + 'Pass at least one column.');
+    }
+    const columns = entries.map(([column]) => quoteIdentifier(column, 'column name'));
+    const placeholders = entries.map(() => '?');
+    return {
+      sql: `INSERT INTO ${quotedTable} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`,
+      params: entries.map(([, value]) => toSqliteValue(value))
+    };
+  };
+  const insert = async (table, row) => {
+    const {
+      sql,
+      params
+    } = insertSql(table, row);
+    const result = await execute(sql, params);
+    return result.insertId;
+  };
+  const insertMany = async (table, rows) => {
+    if (rows.length === 0) {
+      return 0;
+    }
+    // Built before the transaction opens so a bad identifier throws without
+    // leaving a BEGIN behind.
+    const statements = rows.map(row => insertSql(table, row));
+    await transaction(async tx => {
+      for (const statement of statements) {
+        await tx.execute(statement.sql, statement.params);
+      }
+    });
+    return rows.length;
+  };
+  const update = async (table, values, where) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const entries = Object.entries(values);
+    if (entries.length === 0) {
+      throw new Error(`[@webority/mobile-core] Cannot update ${table} with no values. ` + 'Pass at least one column to set.');
+    }
+    const assignments = entries.map(([column]) => `${quoteIdentifier(column, 'column name')} = ?`);
+    const params = entries.map(([, value]) => toSqliteValue(value));
+    const built = buildWhere(where);
+    const result = await execute(`UPDATE ${quotedTable} SET ${assignments.join(', ')}${built.clause}`, [...params, ...built.params]);
+    return result.rowsAffected;
+  };
+  const remove = async (table, where) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const built = buildWhere(where);
+    const result = await execute(`DELETE FROM ${quotedTable}${built.clause}`, built.params);
+    return result.rowsAffected;
+  };
+  const upsert = async (table, row, conflictColumns) => {
+    if (conflictColumns.length === 0) {
+      throw new Error(`[@webority/mobile-core] upsert on ${table} needs at least one conflict ` + 'column; without one SQLite has no key to match an existing row on.');
+    }
+    const {
+      sql,
+      params
+    } = insertSql(table, row);
+    const conflictSet = new Set(conflictColumns);
+    const targets = conflictColumns.map(column => quoteIdentifier(column, 'column name'));
+    const updates = Object.keys(row).filter(column => !conflictSet.has(column)).map(column => {
+      const quoted = quoteIdentifier(column, 'column name');
+      return `${quoted} = excluded.${quoted}`;
+    });
+    const action = updates.length > 0 ? `DO UPDATE SET ${updates.join(', ')}` : 'DO NOTHING';
+    await execute(`${sql} ON CONFLICT (${targets.join(', ')}) ${action}`, params);
+  };
+  const findAll = async (table, where, options) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const built = buildWhere(where);
+    const params = [...built.params];
+    let sql = `SELECT * FROM ${quotedTable}${built.clause}${buildOrderBy(options?.orderBy)}`;
+    if (options?.limit !== undefined) {
+      assertNonNegativeInteger(options.limit, 'limit');
+      sql += ' LIMIT ?';
+      params.push(options.limit);
+    } else if (options?.offset !== undefined) {
+      // SQLite rejects OFFSET without LIMIT; -1 is its documented "no limit".
+      sql += ' LIMIT -1';
+    }
+    if (options?.offset !== undefined) {
+      assertNonNegativeInteger(options.offset, 'offset');
+      sql += ' OFFSET ?';
+      params.push(options.offset);
+    }
+    return select(sql, params);
+  };
+  const findOne = async (table, where) => {
+    const rows = await findAll(table, where, {
+      limit: 1
+    });
+    return rows.length > 0 ? rows[0] : null;
+  };
+  const count = async (table, where) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const built = buildWhere(where);
+    const row = await selectOne(`SELECT COUNT(*) AS cnt FROM ${quotedTable}${built.clause}`, built.params);
+    return Number(row?.cnt ?? 0);
+  };
+  const tableExists = async table => {
+    assertSqlIdentifier(table, 'table name');
+    const row = await selectOne("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?", [table]);
+    return row !== null;
+  };
+  const createTable = async (table, columns, options) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const entries = Object.entries(columns);
+    if (entries.length === 0) {
+      throw new Error(`[@webority/mobile-core] Cannot create table ${table} with no columns.`);
+    }
+    const definitions = entries.map(([column, definition]) => `${quoteIdentifier(column, 'column name')} ${assertColumnDefinition(definition, column)}`);
+    const guard = options?.ifNotExists === false ? '' : 'IF NOT EXISTS ';
+    await execute(`CREATE TABLE ${guard}${quotedTable} (${definitions.join(', ')})`);
+  };
+  const dropTable = async (table, options) => {
+    const quotedTable = quoteIdentifier(table, 'table name');
+    const guard = options?.ifExists === false ? '' : 'IF EXISTS ';
+    await execute(`DROP TABLE ${guard}${quotedTable}`);
+  };
+  const ensureLedger = async () => {
+    await execute(`CREATE TABLE IF NOT EXISTS ${escapeIdentifier(MIGRATIONS_TABLE)} (` + 'version INTEGER PRIMARY KEY, name TEXT, applied_at TEXT NOT NULL, checksum TEXT NOT NULL)');
+  };
+  const recordLedgerSql = `INSERT OR REPLACE INTO ${escapeIdentifier(MIGRATIONS_TABLE)} ` + '(version, name, applied_at, checksum) VALUES (?, ?, ?, ?)';
+  const wipe = async () => {
+    const pragmaRow = await selectOne('PRAGMA foreign_keys');
+    const wasOn = Number(pragmaRow?.foreign_keys ?? 0) === 1;
+    // PRAGMA foreign_keys is a documented no-op inside a transaction, so the
+    // toggle has to straddle it. Left on, deleting a parent table before its
+    // children aborts the run and leaves the database half emptied.
+    await execute('PRAGMA foreign_keys = OFF');
+    try {
+      await transaction(async tx => {
+        const tables = await tx.select("SELECT name FROM sqlite_master WHERE type = 'table' " + "AND name NOT LIKE 'sqlite_%' AND name <> ?", [MIGRATIONS_TABLE]);
+        for (const table of tables) {
+          await tx.execute(`DELETE FROM ${escapeIdentifier(table.name)}`);
+        }
+      });
+    } finally {
+      await execute(`PRAGMA foreign_keys = ${wasOn ? 'ON' : 'OFF'}`);
+    }
+  };
+  const migrate = async (migrations, options) => {
+    const seenVersions = new Set();
+    for (const migration of migrations) {
+      if (seenVersions.has(migration.version)) {
+        throw new Error(`[@webority/mobile-core] Duplicate migration version ${migration.version} ` + `for database "${name}".`);
+      }
+      seenVersions.add(migration.version);
+    }
+    const versionRow = await selectOne('PRAGMA user_version');
+    let currentVersion = Number(versionRow?.user_version ?? 0);
+    if (migrations.length > 0 && !options?.allowDowngrade) {
+      const highest = migrations.reduce((max, m) => Math.max(max, m.version), 0);
+      if (currentVersion > highest) {
+        throw new Error(`[@webority/mobile-core] Database "${name}" is at schema version ` + `${currentVersion}, which is newer than the highest migration supplied (${highest}). ` + 'This build would run old code against a newer schema. Ship the missing migrations, ' + 'or pass { allowDowngrade: true } if this build is known to be compatible.');
+      }
+    }
+    await ensureLedger();
+    const appliedRows = await select(`SELECT version, checksum FROM ${escapeIdentifier(MIGRATIONS_TABLE)}`);
+    const appliedChecksums = new Map(appliedRows.map(row => [Number(row.version), String(row.checksum)]));
+    for (const migration of migrations) {
+      if (migration.version > currentVersion) {
+        continue;
+      }
+      const recorded = appliedChecksums.get(migration.version);
+      // A database migrated before the ledger existed has no row to compare
+      // against, which is not a mismatch.
+      if (recorded === undefined) {
+        continue;
+      }
+      const checksum = migrationChecksum(migration);
+      if (recorded !== checksum) {
+        throw new Error(`[@webority/mobile-core] Migration ${migration.version} has changed since ` + `it was applied to database "${name}" (recorded ${recorded}, now ${checksum}). ` + 'A released migration must never be edited; add a new one instead.');
+      }
+    }
+    const pending = migrations.filter(migration => migration.version > currentVersion).sort((a, b) => a.version - b.version);
+    for (const migration of pending) {
+      const checksum = migrationChecksum(migration);
+      await transaction(async tx => {
+        if (typeof migration.up === 'function') {
+          await migration.up(tx);
+        } else {
+          const statements = Array.isArray(migration.up) ? migration.up : [migration.up];
+          for (const statement of statements) {
+            await tx.execute(statement);
+          }
+        }
+        // The ledger row is written inside the migration's own transaction so
+        // it can never disagree with user_version after a partial failure.
+        await tx.execute(recordLedgerSql, [migration.version, migration.name ?? null, new Date().toISOString(), checksum]);
+        // PRAGMA statements do not accept bound `?` parameters in SQLite, so the
+        // version (a validated integer from this module's own loop, never user
+        // input) is inlined rather than passed as a param.
+        await tx.execute(`PRAGMA user_version = ${migration.version}`);
+      });
+      currentVersion = migration.version;
+    }
+    return currentVersion;
+  };
+  const reset = async migrations => {
+    await wipe();
+    await ensureLedger();
+    await transaction(async tx => {
+      await tx.execute(`DELETE FROM ${escapeIdentifier(MIGRATIONS_TABLE)}`);
+      await tx.execute('PRAGMA user_version = 0');
+    });
+    return migrate(migrations);
+  };
+  const baseline = async (version, migrations) => {
+    assertNonNegativeInteger(version, 'baseline version');
+    await ensureLedger();
+    const appliedAt = new Date().toISOString();
+    await transaction(async tx => {
+      for (const migration of migrations ?? []) {
+        if (migration.version > version) {
+          continue;
+        }
+        await tx.execute(recordLedgerSql, [migration.version, migration.name ?? null, appliedAt, migrationChecksum(migration)]);
+      }
+      await tx.execute(`PRAGMA user_version = ${version}`);
+    });
+  };
+  const close = async () => {
+    await raw.close();
+  };
+  return {
+    name,
+    execute,
+    select,
+    selectOne,
+    transaction,
+    insert,
+    insertMany,
+    update,
+    remove,
+    upsert,
+    findAll,
+    findOne,
+    count,
+    tableExists,
+    createTable,
+    dropTable,
+    wipe,
+    reset,
+    migrate,
+    baseline,
+    close
+  };
+};
+export const openDatabase = async (name, options) => {
+  const driver = requireBackend('open');
+  const raw = await driver.open(name, options ? {
+    location: options.location
+  } : undefined);
+  const db = createDb(name, raw);
+  if (options?.pragmas !== false) {
+    const pragmas = {
+      ...DEFAULT_PRAGMAS,
+      ...(options?.pragmas ?? {})
+    };
+    for (const [pragma, value] of Object.entries(pragmas)) {
+      assertSqlIdentifier(pragma, 'PRAGMA name');
+      await db.execute(`PRAGMA ${pragma} = ${renderPragmaValue(pragma, value)}`);
+    }
+  }
+  return db;
+};
+//# sourceMappingURL=index.js.map