@deterministic-code/datasources-sqlite 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@deterministic-code/datasources-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deterministic-code/datasources": "^0.1.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.10.0"
+  }
+}

package/src/SqliteCreateTableStatementRenderer.ts

@@ -0,0 +1,24 @@
+import { CreateTableStatement, CreateTableStatementTextRenderer, PrimaryKey, type Column } from "@deterministic-code/datasources";
+import { columnTypes } from "./columnTypes.ts";
+
+export class SqliteCreateTableStatementRenderer extends CreateTableStatementTextRenderer {
+  override render(statement: CreateTableStatement): string {
+    const identity = new Set(statement.columns.filter((column) => column.identity).map((column) => column.name));
+    const constraints = statement.constraints.filter(
+      (constraint) => !(constraint instanceof PrimaryKey) || !constraint.columns.every((column) => identity.has(column)),
+    );
+    return super.render(
+      constraints.length === statement.constraints.length
+        ? statement
+        : new CreateTableStatement(statement.table, statement.columns, constraints),
+    );
+  }
+
+  protected typeName(column: Column): string {
+    return columnTypes[column.type] ?? column.type;
+  }
+
+  protected identity(column: Column): string {
+    return column.identity ? " PRIMARY KEY AUTOINCREMENT" : "";
+  }
+}

package/src/SqliteDriver.ts

@@ -0,0 +1,53 @@
+import {
+  DatasourceError,
+  StatementTextRenderer,
+  type Cell,
+  type DatasourceOptions,
+  type ICommand,
+  type IConnection,
+  type IDriver,
+  type Information,
+  type ITransaction,
+  type IsolationLevel,
+  type TypeConverter,
+} from "@deterministic-code/datasources";
+import { SqliteConnection } from "./connection.ts";
+import { SqliteCommand } from "./command.ts";
+import { SqliteTransaction } from "./transaction.ts";
+import { SqliteRowTypeConverters } from "./converters/SqliteRowTypeConverters.ts";
+import { SqliteStatementRenderer } from "./SqliteStatementRenderer.ts";
+import { columnTypes } from "./columnTypes.ts";
+
+export { columnTypes };
+
+const statements = new StatementTextRenderer(t => new SqliteStatementRenderer(t));
+
+export class SqliteDriver implements IDriver {
+  readonly statementRenderer = statements;
+  readonly information: Information = {
+    descriptions: [
+      "Embedded SQL database for local development and tests.",
+      "Full connection, command, transaction, and repository support.",
+    ],
+    overrides: [
+      "Overrides SelectInsertedIdStatement to SELECT last_insert_rowid() AS {column}",
+      "Overrides CreateTableStatement type mapping (int→INTEGER, bool→BOOLEAN, uuid/string/datetime→TEXT, decimal→NUMERIC, float→REAL, binary→BLOB)",
+    ],
+    changeLogs: [],
+  };
+  rowTypeConverters: Record<string, TypeConverter<Cell, Cell>> = SqliteRowTypeConverters;
+  columnType = (name: string): string =>
+    columnTypes[name] ??
+    (() => {
+      throw new DatasourceError(`Unknown sqlite type "${name}"`);
+    })();
+  connection = (options?: DatasourceOptions): IConnection =>
+    SqliteConnection.from(options);
+  command = (connection: IConnection): ICommand =>
+    new SqliteCommand(connection as SqliteConnection, statements);
+  transaction = (
+    connection: IConnection,
+    isolation: IsolationLevel = "readCommitted",
+  ): ITransaction =>
+    new SqliteTransaction(connection as SqliteConnection, isolation);
+}

package/src/SqliteStatementRenderer.ts

@@ -0,0 +1,28 @@
+import {
+  CreateTableStatement,
+  SelectInsertedIdStatement,
+  SelectInsertedIdStatementTextRenderer,
+  StatementRenderer,
+  type StatementTextRenderer,
+} from "@deterministic-code/datasources";
+import { SqliteCreateTableStatementRenderer } from "./SqliteCreateTableStatementRenderer.ts";
+
+class SqliteSelectInsertedIdStatementTextRenderer extends SelectInsertedIdStatementTextRenderer {
+  override render(statement: SelectInsertedIdStatement): string {
+    return `SELECT last_insert_rowid() AS ${statement.column}`;
+  }
+}
+
+export class SqliteStatementRenderer extends StatementRenderer {
+  constructor(text: StatementTextRenderer) {
+    super(text);
+  }
+
+  protected override visitSelectInsertedId(inserted: SelectInsertedIdStatement): string {
+    return new SqliteSelectInsertedIdStatementTextRenderer().render(inserted);
+  }
+
+  protected override visitCreateTable(create: CreateTableStatement): string {
+    return new SqliteCreateTableStatementRenderer().render(create);
+  }
+}

package/src/columnTypes.ts

@@ -0,0 +1,10 @@
+export const columnTypes: Record<string, string> = {
+  int: "INTEGER",
+  uuid: "TEXT",
+  string: "TEXT",
+  bool: "BOOLEAN",
+  decimal: "NUMERIC",
+  float: "REAL",
+  datetime: "TEXT",
+  binary: "BLOB",
+};

package/src/command.ts

@@ -0,0 +1,231 @@
+import {
+  ArrayReader,
+  CommandMiddlewareHost,
+  FirstResultReader,
+  DatasourceError,
+  Native,
+  ReturnStatement,
+  SelectStatement,
+  StatementTextRenderer,
+  parametersToRecord,
+  Response,
+  splitStatements,
+  statementParameters,
+  StreamingReader,
+  type Cell,
+  type Cells,
+  type Scalar,
+  type ICommand,
+  type IReader,
+  type IStatement,
+  type Parameter,
+} from "@deterministic-code/datasources";
+import type { SqliteConnection } from "./connection.ts";
+import type { SqliteStatement } from "./i-sqlite-driver.ts";
+import { reverse, SqliteRowTypeConverters } from "./converters/SqliteRowTypeConverters.ts";
+import { SqliteStatementRenderer } from "./SqliteStatementRenderer.ts";
+
+const bound = (parameters?: Parameter[]): Record<string, Scalar> => {
+  const record = parametersToRecord(parameters);
+  return Object.fromEntries(
+    Object.entries(record).map(([name, value]) => [name, reverse(value)]),
+  ) as Record<string, Scalar>;
+};
+
+const toSqlite = (sql: string, params: Record<string, Scalar>): { text: string; values: Scalar[] } => {
+  const values: Scalar[] = [];
+  const text = sql.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, name: string) => {
+    values.push(params[name] ?? null);
+    return "?";
+  });
+  return { text, values };
+};
+
+export class SqliteCommand extends CommandMiddlewareHost implements ICommand {
+  private readonly statements: StatementTextRenderer;
+
+  constructor(readonly connection: SqliteConnection, statements?: StatementTextRenderer) {
+    super();
+    this.statements = statements ?? new StatementTextRenderer(t => new SqliteStatementRenderer(t));
+  }
+
+  async executeReaderNative(
+    text: Native,
+    parameters?: Parameter[],
+  ): Promise<IReader<Cells>> {
+    return this.run(text.text, parameters, async (query, params) => {
+      if (!query.trim()) return { value: new ArrayReader([]), rows: [] };
+      this.connection.ensureOpen();
+      const statements = splitStatements(query);
+      if (statements.length === 0) return { value: new ArrayReader([]), rows: [] };
+      const paramsBound = bound(params);
+      let index = 0;
+      let iter = this.iterate(statements[0] as string, paramsBound);
+      return FirstResultReader.capture(
+        new StreamingReader(
+          async () => {
+            const step = iter.next();
+            return step.done ? undefined : step.value;
+          },
+          async () => {
+            iter.return();
+            index += 1;
+            const sql = statements[index];
+            if (!sql) return false;
+            iter = this.iterate(sql, paramsBound);
+            return true;
+          },
+          async () => {
+            iter.return();
+          },
+        ),
+      );
+    });
+  }
+
+  async executeReaderStatement(
+    statement: IStatement,
+    parameters?: Parameter[],
+  ): Promise<IReader<Cells>> {
+    return this.executeReaderNative(new Native(this.statements.render(statement)), parameters);
+  }
+
+  async executeStatement(statement: IStatement, parameters?: Parameter[]): Promise<Response> {
+    return statement instanceof SelectStatement || statement instanceof ReturnStatement
+      ? this.firstCell(statement, parameters)
+      : this.executeNative(new Native(this.statements.render(statement)), parameters);
+  }
+
+  private async firstCell(statement: IStatement, parameters?: Parameter[]): Promise<Response> {
+    const reader = await this.executeReaderStatement(statement, parameters);
+    try {
+      if (!(await reader.next())) return new Response(null, 0, parameters);
+      const row = reader.current;
+      /* v8 ignore next */
+      if (!row) throw new DatasourceError("Reader current must be a row");
+      const values = Object.values(row);
+      return new Response(values.length === 0 ? null : values[0], 1, parameters);
+    } finally {
+      await reader.dispose();
+    }
+  }
+
+  async executeNative(text: Native, parameters?: Parameter[]): Promise<Response> {
+    return this.run(text.text, parameters, async (query, params) => {
+      if (!query.trim()) return { value: new Response(undefined, 0, params), rows: [] };
+      this.connection.ensureOpen();
+      const db = this.connection.require();
+      const named = bound(params);
+      let changes = 0;
+      for (const sql of splitStatements(query)) {
+        const names = new Set(statementParameters(sql));
+        const used = Object.fromEntries(
+          Object.entries(named).filter(([name]) => names.has(name.replace(/^[$:@]/, ""))),
+        );
+        const { text, values } = toSqlite(sql, used);
+        changes += db.prepare(text).run(...values).changes;
+      }
+      return { value: new Response(null, changes, params), rows: [] };
+    });
+  }
+
+  private iterate(sql: string, params: Record<string, Scalar>): IterableIterator<Cells> & {
+    return(): IteratorResult<Cells>;
+  } {
+    const statement = this.connection.require().prepare(sql) as ColumnStatement;
+    const columns = statement.columns?.() ?? [];
+    const names = qualified(columns);
+    const declared = columns.map((column) => column.type ?? null);
+    const raw = names.some((name, index) => name !== columns[index]?.name)
+      ? statement.raw?.(true).iterate(params)
+      : undefined;
+    const rows = raw ? namedRows(raw, names, declared) : closable(statement.iterate(params), columns);
+    return rows[Symbol.iterator]();
+  }
+}
+
+type SqliteColumn = { name: string; column: string | null; table: string | null; type?: string | null };
+
+const booleanDeclared = (declared?: string | null): boolean =>
+  declared?.toUpperCase() === "BOOLEAN";
+
+const cell = (value: Cell | null | undefined, declared?: string | null): Cell | null =>
+  value == null ? null : booleanDeclared(declared) ? SqliteRowTypeConverters.bool.convert(value) : value;
+
+type ColumnStatement = SqliteStatement & {
+  columns?: () => SqliteColumn[];
+  raw?: (enabled: boolean) => {
+    iterate(params?: Record<string, Scalar>): IterableIterator<Cell[]>;
+  };
+};
+
+const closable = (
+  iter: IterableIterator<Cells>,
+  columns: SqliteColumn[],
+): IterableIterator<Cells> & { return(): IteratorResult<Cells> } => {
+  const stop = iter.return ? iter.return.bind(iter) : undefined;
+  const rows: IterableIterator<Cells> & { return(): IteratorResult<Cells> } = {
+    next: () => {
+      const step = iter.next();
+      if (step.done || !step.value) return step;
+      const value = Object.fromEntries(
+        Object.entries(step.value).map(([name, item]) => [
+          name,
+          cell(item, columns.find((column) => column.name === name)?.type),
+        ]),
+      ) as Cells;
+      return { done: false, value };
+    },
+    return: () => {
+      if (stop) stop();
+      return { done: true, value: undefined };
+    },
+    [Symbol.iterator]() {
+      return rows;
+    },
+  };
+  return rows;
+};
+
+const namedRows = (
+  iter: IterableIterator<Cell[]>,
+  names: string[],
+  declared: (string | null)[],
+): IterableIterator<Cells> & { return(): IteratorResult<Cells> } => {
+  /* v8 ignore next */
+  const stop = iter.return ? iter.return.bind(iter) : undefined;
+  const rows: IterableIterator<Cells> & { return(): IteratorResult<Cells> } = {
+    next: () => {
+      const step = iter.next();
+      return step.done
+        ? { done: true, value: undefined }
+        : {
+            done: false,
+            value: Object.fromEntries(
+              names.map((name, index) => [name, cell(step.value[index], declared[index])]),
+            ),
+          };
+    },
+    return: () => {
+      /* v8 ignore next */
+      if (stop) stop();
+      return { done: true, value: undefined };
+    },
+    [Symbol.iterator]() {
+      return rows;
+    },
+  };
+  return rows;
+};
+
+const qualified = (columns: SqliteColumn[]): string[] => {
+  const names = columns.map((column) => column.name);
+  const duplicated = new Set(names.filter((name, index) => names.indexOf(name) !== index));
+  return duplicated.size === 0
+    ? names
+    : columns.map((column, index) =>
+        duplicated.has(names[index]!) && column.table && column.column
+          ? `${column.table}.${column.column}`
+          : names[index]!
+      );
+};

package/src/connection-options.ts

@@ -0,0 +1,7 @@
+import type { SqliteDatabaseCtor } from "./i-sqlite-driver.ts";
+
+export interface SqliteConnectionOptions {
+  filename?: string;
+  url?: string;
+  Database?: SqliteDatabaseCtor;
+}

package/src/connection.ts

@@ -0,0 +1,83 @@
+import {
+  DatasourceError,
+  IsolationLevel,
+  StatementTextRenderer,
+  type DatasourceOptions,
+  type ICommand,
+  type IConnection,
+  type IsolationLevelName,
+  type ITransaction,
+} from "@deterministic-code/datasources";
+import { createRequire } from "node:module";
+import { SqliteCommand } from "./command.ts";
+import type { SqliteConnectionOptions } from "./connection-options.ts";
+import type { SqliteDatabase, SqliteDatabaseCtor } from "./i-sqlite-driver.ts";
+import { filenameOf } from "./sqlitePath.ts";
+import { SqliteStatementRenderer } from "./SqliteStatementRenderer.ts";
+import { SqliteTransaction } from "./transaction.ts";
+
+const require = createRequire(import.meta.url);
+
+const pragma = (isolation: IsolationLevelName): string =>
+  isolation === IsolationLevel.ReadUncommitted
+    ? "PRAGMA read_uncommitted = 1"
+    : "PRAGMA read_uncommitted = 0";
+
+export class SqliteConnection implements IConnection {
+  readonly provider = "sqlite";
+  filename: string;
+  isOpen = false;
+  private db?: SqliteDatabase;
+  private readonly Database?: SqliteDatabaseCtor;
+
+  static from = (options?: DatasourceOptions): SqliteConnection =>
+    new SqliteConnection({
+      url: options?.DATASOURCE_URL,
+      Database: require("better-sqlite3") as SqliteDatabaseCtor,
+    });
+
+  constructor(options: SqliteConnectionOptions = {}) {
+    this.filename = filenameOf(options);
+    this.Database = options.Database;
+  }
+
+  createCommand = (): ICommand =>
+    new SqliteCommand(this, new StatementTextRenderer(t => new SqliteStatementRenderer(t)));
+
+  async open(): Promise<void> {
+    if (this.isOpen) throw new DatasourceError("Connection is already open");
+    if (!this.Database) throw new DatasourceError("SQLite driver is required");
+    this.db = new this.Database(this.filename, { timeout: 0 });
+    this.isOpen = true;
+  }
+
+  async close(): Promise<void> {
+    this.db?.close();
+    this.db = undefined;
+    this.isOpen = false;
+  }
+
+  [Symbol.asyncDispose] = (): Promise<void> => this.close();
+
+  async startTransaction(
+    isolation: IsolationLevelName = IsolationLevel.ReadCommitted,
+  ): Promise<ITransaction> {
+    this.ensureOpen();
+    this.exec(pragma(isolation));
+    this.exec("BEGIN");
+    return new SqliteTransaction(this, isolation);
+  }
+
+  ensureOpen(): void {
+    if (!this.isOpen) throw new DatasourceError("Connection is not open");
+  }
+
+  require(): SqliteDatabase {
+    if (!this.db) throw new DatasourceError("Connection is not open");
+    return this.db;
+  }
+
+  exec(sql: string): void {
+    this.require().exec(sql);
+  }
+}

package/src/converters/BinaryConverter.ts

@@ -0,0 +1,6 @@
+import { TypeConverter, type Cell } from "@deterministic-code/datasources";
+
+export class BinaryConverter extends TypeConverter<Cell, Cell> {
+  convert = (from: Cell): Cell => from;
+  reverseConvert = (to: Cell): Cell => to;
+}

package/src/converters/BoolConverter.ts

@@ -0,0 +1,6 @@
+import { TypeConverter, type Cell } from "@deterministic-code/datasources";
+
+export class BoolConverter extends TypeConverter<Cell, Cell> {
+  convert = (from: Cell): Cell => (typeof from === "number" ? from !== 0 : from);
+  reverseConvert = (to: Cell): Cell => (typeof to === "boolean" ? (to ? 1 : 0) : to);
+}

package/src/converters/DateTimeConverter.ts

@@ -0,0 +1,8 @@
+import { TypeConverter, type Cell } from "@deterministic-code/datasources";
+
+export class DateTimeConverter extends TypeConverter<Cell, Cell> {
+  convert = (from: Cell): Cell =>
+    typeof from === "string" ? new Date(from) : from;
+  reverseConvert = (to: Cell): Cell =>
+    to instanceof Date ? to.toISOString() : to;
+}

package/src/converters/DecimalConverter.ts

@@ -0,0 +1,7 @@
+import { TypeConverter, type Cell } from "@deterministic-code/datasources";
+
+export class DecimalConverter extends TypeConverter<Cell, Cell> {
+  convert = (from: Cell): Cell => from;
+  reverseConvert = (to: Cell): Cell =>
+    typeof to === "number" ? String(to) : to;
+}

package/src/converters/SqliteRowTypeConverters.ts

@@ -0,0 +1,24 @@
+import { type Cell, type TypeConverter } from "@deterministic-code/datasources";
+import { BinaryConverter } from "./BinaryConverter.ts";
+import { BoolConverter } from "./BoolConverter.ts";
+import { DateTimeConverter } from "./DateTimeConverter.ts";
+import { DecimalConverter } from "./DecimalConverter.ts";
+import { UuidConverter } from "./UuidConverter.ts";
+
+export const SqliteRowTypeConverters: Record<string, TypeConverter<Cell, Cell>> = {
+  bool: new BoolConverter(),
+  datetime: new DateTimeConverter(),
+  uuid: new UuidConverter(),
+  decimal: new DecimalConverter(),
+  binary: new BinaryConverter(),
+};
+
+export const reverse = (value: Cell): Cell =>
+  typeof value === "boolean"
+    ? SqliteRowTypeConverters.bool.reverseConvert(value)
+    : value instanceof Date
+      ? SqliteRowTypeConverters.datetime.reverseConvert(value)
+      : value instanceof Uint8Array
+        ? SqliteRowTypeConverters.binary.reverseConvert(value)
+        : value;
+

package/src/converters/UuidConverter.ts

@@ -0,0 +1,6 @@
+import { TypeConverter, type Cell } from "@deterministic-code/datasources";
+
+export class UuidConverter extends TypeConverter<Cell, Cell> {
+  convert = (from: Cell): Cell => from;
+  reverseConvert = (to: Cell): Cell => to;
+}

package/src/i-sqlite-driver.ts

@@ -0,0 +1,21 @@
+import type { Cell, Cells, Scalar } from "@deterministic-code/datasources";
+
+export interface SqliteStatement {
+  run(params?: Record<string, Scalar>): {
+    changes: number;
+    lastInsertRowid?: Cell;
+  };
+  all(params?: Record<string, Scalar>): Cells[];
+  iterate(params?: Record<string, Scalar>): IterableIterator<Cells>;
+}
+
+export interface SqliteDatabase {
+  prepare(sql: string): SqliteStatement;
+  exec(sql: string): void;
+  close(): void;
+}
+
+export type SqliteDatabaseCtor = new (
+  filename: string,
+  options?: { timeout?: number },
+) => SqliteDatabase;

package/src/index.ts

@@ -0,0 +1,2 @@
+export { SqliteDriver } from "./SqliteDriver.ts";
+export { SqliteStatementRenderer } from "./SqliteStatementRenderer.ts";

package/src/sqlitePath.ts

@@ -0,0 +1,8 @@
+export const sqliteFilename = (url: string): string | undefined => {
+  if (!/^sqlite:/i.test(url)) return undefined;
+  const path = url.replace(/^sqlite:(?:\/\/\/|\/\/)?/i, "");
+  return path === "" || path === ":memory" || path === ":memory:" ? ":memory:" : path;
+};
+
+export const filenameOf = (options: { filename?: string; url?: string }): string =>
+  options.filename ?? (options.url ? sqliteFilename(options.url) ?? ":memory:" : ":memory:");

package/src/transaction.ts

@@ -0,0 +1,21 @@
+import {
+  IsolationLevel,
+  type ITransaction,
+  type IsolationLevelName,
+} from "@deterministic-code/datasources";
+import type { SqliteConnection } from "./connection.ts";
+
+export class SqliteTransaction implements ITransaction {
+  constructor(
+    readonly connection: SqliteConnection,
+    readonly isolation: IsolationLevelName = IsolationLevel.ReadCommitted,
+  ) {}
+
+  async commit(): Promise<void> {
+    this.connection.exec("COMMIT");
+  }
+
+  async abort(): Promise<void> {
+    this.connection.exec("ROLLBACK");
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.