@uniflowed/sql 0.14.0

package/adapters/better-sqlite3.js

@@ -0,0 +1,80 @@
+// @flow
+//
+// `@uniflowed/sql/better-sqlite3`: the `better-sqlite3` package.
+//
+//   import Database from "better-sqlite3";
+//   import { fromBetterSqlite3 } from "@uniflowed/sql/better-sqlite3";
+//
+//   const db = fromBetterSqlite3(new Database("app.db"));
+//
+// Experimental: typed against better-sqlite3's documented `Statement` API
+// (`raw`, `safeIntegers`, `reader`); this repository's CI does not install it.
+
+import type { Queryable, SqlParam } from "../index.js";
+import { SqlError, singleConnection } from "../index.js";
+import { DEFAULT_STATEMENT_CACHE, count, rowId, statementCache } from "../internal/statements.js";
+
+/** The part of better-sqlite3's `Statement` this uses. */
+export interface BetterSqlite3Statement {
+  readonly reader: boolean;
+  all(...params: $ReadOnlyArray<SqlParam>): $ReadOnlyArray<mixed>;
+  run(...params: $ReadOnlyArray<SqlParam>): {
+    readonly changes: number,
+    readonly lastInsertRowid: number | bigint,
+    ...
+  };
+  raw(enabled: boolean): mixed;
+  safeIntegers(enabled: boolean): mixed;
+}
+
+/** The part of better-sqlite3's `Database` this uses. */
+export interface BetterSqlite3Database {
+  prepare(text: string): BetterSqlite3Statement;
+}
+
+export type BetterSqlite3Options = {|
+  readonly begin?: string,
+  readonly statementCache?: number,
+  readonly maxParams?: number,
+|};
+
+/** A [`Queryable`] over one better-sqlite3 `Database`. */
+export function fromBetterSqlite3(
+  database: BetterSqlite3Database,
+  options: BetterSqlite3Options = {},
+): Queryable {
+  const statement = statementCache((text) => {
+    const prepared = database.prepare(text);
+    prepared.safeIntegers(true);
+    // `raw` throws on a statement that returns no data, so only a reader
+    // gets it — and only a reader is ever asked for rows.
+    if (prepared.reader) {
+      prepared.raw(true);
+    }
+    return prepared;
+  }, options.statementCache ?? DEFAULT_STATEMENT_CACHE);
+  return singleConnection({
+    engine: "sqlite",
+    maxParams: options.maxParams ?? 32766,
+    begin: options.begin,
+    run: async (text, params, mode) => {
+      const prepared = statement(text);
+      if (mode === "rows" && prepared.reader) {
+        const rows: Array<$ReadOnlyArray<mixed>> = [];
+        for (const row of prepared.all(...params)) {
+          if (!Array.isArray(row)) {
+            throw new SqlError({ kind: "unsupported", feature: "better-sqlite3 rows as objects" });
+          }
+          rows.push(row);
+        }
+        return { rows, rowsAffected: 0, lastInsertId: null };
+      }
+      const result = prepared.run(...params);
+      return {
+        rows: [],
+        rowsAffected: count(result.changes),
+        lastInsertId: rowId(result.lastInsertRowid),
+      };
+    },
+  });
+}

package/adapters/bun-sqlite.js

@@ -0,0 +1,73 @@
+// @flow
+//
+// `@uniflowed/sql/bun-sqlite`: Bun's built-in `bun:sqlite`.
+//
+//   import { Database } from "bun:sqlite";
+//   import { fromBunSqlite } from "@uniflowed/sql/bun-sqlite";
+//
+//   const db = fromBunSqlite(new Database("app.db"));
+//
+// Safe integers are turned on per statement, so the `Database` does not have
+// to be opened with `safeIntegers: true` — though it does no harm.
+
+import type { Queryable, SqlParam } from "../index.js";
+import { SqlError, singleConnection } from "../index.js";
+import { DEFAULT_STATEMENT_CACHE, count, rowId, statementCache } from "../internal/statements.js";
+
+/** The part of `bun:sqlite`'s `Statement` this uses. */
+export interface BunSqliteStatement {
+  values(...params: $ReadOnlyArray<SqlParam>): $ReadOnlyArray<mixed>;
+  run(...params: $ReadOnlyArray<SqlParam>): {
+    readonly changes: number | bigint,
+    readonly lastInsertRowid: number | bigint,
+    ...
+  };
+  safeIntegers(enabled: boolean): mixed;
+}
+
+/** The part of `bun:sqlite`'s `Database` this uses. */
+export interface BunSqliteDatabase {
+  prepare(text: string): BunSqliteStatement;
+}
+
+export type BunSqliteOptions = {|
+  readonly begin?: string,
+  readonly statementCache?: number,
+  readonly maxParams?: number,
+|};
+
+/** A [`Queryable`] over one `bun:sqlite` `Database`. */
+export function fromBunSqlite(
+  database: BunSqliteDatabase,
+  options: BunSqliteOptions = {},
+): Queryable {
+  const statement = statementCache((text) => {
+    const prepared = database.prepare(text);
+    prepared.safeIntegers(true);
+    return prepared;
+  }, options.statementCache ?? DEFAULT_STATEMENT_CACHE);
+  return singleConnection({
+    engine: "sqlite",
+    maxParams: options.maxParams ?? 32766,
+    begin: options.begin,
+    run: async (text, params, mode) => {
+      const prepared = statement(text);
+      if (mode === "rows") {
+        const rows: Array<$ReadOnlyArray<mixed>> = [];
+        for (const row of prepared.values(...params)) {
+          if (!Array.isArray(row)) {
+            throw new SqlError({ kind: "unsupported", feature: "bun:sqlite rows as objects" });
+          }
+          rows.push(row);
+        }
+        return { rows, rowsAffected: 0, lastInsertId: null };
+      }
+      const result = prepared.run(...params);
+      return {
+        rows: [],
+        rowsAffected: count(result.changes),
+        lastInsertId: rowId(result.lastInsertRowid),
+      };
+    },
+  });
+}

package/adapters/d1.js

@@ -0,0 +1,71 @@
+// @flow
+//
+// `@uniflowed/sql/d1`: a Cloudflare D1 binding.
+//
+//   import { fromD1 } from "@uniflowed/sql/d1";
+//
+//   export default { fetch: (request, env) => handle(request, fromD1(env.DB)) };
+//
+// Experimental, and narrower than the other adapters in three ways D1 decides:
+//
+//   * **No interactive transactions.** The returned `Queryable` has no
+//     `transaction`, so `:batch*` and `:copyfrom` run their statements in order
+//     without one. Use D1's own `batch()` where atomicity matters.
+//   * **100 bound parameters per statement**, which `:copyfrom` chunks under.
+//   * **No `bigint`.** D1 returns every INTEGER as a `number`, so the checked
+//     `INTEGER` codec throws on a value past 2^53 instead of rounding it, and a
+//     `bigint` parameter is sent as its digits, which INTEGER affinity stores
+//     exactly.
+
+import type { Queryable, SqlParam } from "../index.js";
+import { SqlError } from "../index.js";
+import { count, rowId } from "../internal/statements.js";
+
+/** The part of a D1 prepared statement this uses. */
+export interface D1Statement {
+  bind(...params: $ReadOnlyArray<mixed>): D1Statement;
+  raw(): Promise<$ReadOnlyArray<mixed>>;
+  run(): Promise<{
+    readonly meta: { readonly changes?: number, readonly last_row_id?: number, ... },
+    ...
+  }>;
+}
+
+/** The part of a D1 database binding this uses. */
+export interface D1Database {
+  prepare(text: string): D1Statement;
+}
+
+function toD1(param: SqlParam): mixed {
+  if (typeof param === "bigint") {
+    return String(param);
+  }
+  return param;
+}
+
+/** A [`Queryable`] over a D1 binding. */
+export function fromD1(database: D1Database): Queryable {
+  return {
+    engine: "sqlite",
+    maxParams: 100,
+    query: async (text, params, mode) => {
+      const statement = database.prepare(text).bind(...params.map(toD1));
+      if (mode === "rows") {
+        const rows: Array<$ReadOnlyArray<mixed>> = [];
+        for (const row of await statement.raw()) {
+          if (!Array.isArray(row)) {
+            throw new SqlError({ kind: "unsupported", feature: "D1 rows as objects" });
+          }
+          rows.push(row);
+        }
+        return { rows, rowsAffected: 0, lastInsertId: null };
+      }
+      const { meta } = await statement.run();
+      return {
+        rows: [],
+        rowsAffected: count(meta.changes ?? 0),
+        lastInsertId: rowId(meta.last_row_id),
+      };
+    },
+  };
+}

package/adapters/mysql2.js

@@ -0,0 +1,140 @@
+// @flow
+//
+// `@uniflowed/sql/mysql2`: the `mysql2` package's promise API.
+//
+//   import mysql from "mysql2/promise";
+//   import { fromMysql2Pool } from "@uniflowed/sql/mysql2";
+//
+//   const db = fromMysql2Pool(mysql.createPool(url));
+//
+// `tests/sqlc/mysql.test.js` runs it against the MySQL 8.4 server CI's
+// `sqlc Flow target` job provides; locally it needs `UF_SQLC_MYSQL_URL`.
+//
+// Statements are server-side prepared (`execute`) and rows are arrays. Each
+// statement asks for big numbers and dates as strings, and its `typeCast`
+// reads `JSON` and `DECIMAL` columns as their text: the text MySQL sent, which
+// `@uniflowed/sql/mysql` decodes, whatever the pool was configured with.
+// mysql2 reads `jsonStrings` and `decimalNumbers` from the connection's
+// config only, so asking for them per statement would be silently ignored,
+// and a pool opened without them would hand the codecs a parsed object.
+//
+// A parameterless statement run for its effect goes over the text protocol
+// (`query`) instead: MySQL refuses to prepare `SAVEPOINT`, `RELEASE
+// SAVEPOINT` and `ROLLBACK TO SAVEPOINT`, and such a statement returns no rows
+// whose representation could differ.
+
+import type { Connection, QueryResult, Queryable, Run } from "../index.js";
+import { transactionOn } from "../index.js";
+
+/** What a `typeCast` function is handed for one column. */
+export type Mysql2Field = {
+  readonly type: string,
+  string(encoding?: string): string | null,
+  ...
+};
+
+type Mysql2Options = {|
+  readonly sql: string,
+  readonly values: $ReadOnlyArray<mixed>,
+  readonly rowsAsArray: true,
+  readonly supportBigNumbers: true,
+  readonly bigNumberStrings: true,
+  readonly dateStrings: true,
+  readonly typeCast: (field: Mysql2Field, next: () => mixed) => mixed,
+|};
+
+type Mysql2Result =
+  | $ReadOnlyArray<mixed>
+  | { readonly affectedRows: number, readonly insertId: number | string, ... };
+
+/** A `mysql2/promise` connection. */
+export interface Mysql2Connection {
+  execute(options: Mysql2Options): Promise<[Mysql2Result, mixed]>;
+  query(options: Mysql2Options): Promise<[Mysql2Result, mixed]>;
+}
+
+/** A connection checked out of a `mysql2/promise` pool. */
+export interface Mysql2PoolConnection extends Mysql2Connection {
+  release(): void;
+}
+
+/** A `mysql2/promise` pool. */
+export interface Mysql2Pool extends Mysql2Connection {
+  getConnection(): Promise<Mysql2PoolConnection>;
+}
+
+/**
+ * `JSON` and `DECIMAL` columns as the text MySQL sent; everything else as the
+ * statement's options already ask. `JSON` arrives with the binary charset, so
+ * it is read as UTF-8, which is what the JSON type stores.
+ */
+export function typeCast(field: Mysql2Field, next: () => mixed): mixed {
+  switch (field.type) {
+    case "JSON":
+      return field.string("utf8");
+    case "NEWDECIMAL":
+    case "DECIMAL":
+      return field.string();
+    default:
+      return next();
+  }
+}
+
+function lastId(value: number | string): bigint | null {
+  if (typeof value === "string" && /^\d+$/.test(value)) {
+    return BigInt(value);
+  }
+  if (typeof value === "number" && Number.isSafeInteger(value)) {
+    return BigInt(value);
+  }
+  return null;
+}
+
+function runOn(connection: Mysql2Connection): Run {
+  return async (text, params, mode): Promise<QueryResult> => {
+    const options: Mysql2Options = {
+      sql: text,
+      values: params,
+      rowsAsArray: true,
+      supportBigNumbers: true,
+      bigNumberStrings: true,
+      dateStrings: true,
+      typeCast,
+    };
+    const [result] =
+      mode === "exec" && params.length === 0
+        ? await connection.query(options)
+        : await connection.execute(options);
+    if (Array.isArray(result)) {
+      const rows: Array<$ReadOnlyArray<mixed>> = [];
+      for (const row of result) {
+        if (Array.isArray(row)) {
+          rows.push(row);
+        }
+      }
+      return { rows, rowsAffected: 0, lastInsertId: null };
+    }
+    return { rows: [], rowsAffected: result.affectedRows, lastInsertId: lastId(result.insertId) };
+  };
+}
+
+function connection(client: Mysql2Connection): Connection {
+  return { engine: "mysql", maxParams: 65535, run: runOn(client) };
+}
+
+/** A [`Queryable`] over a `mysql2/promise` pool. */
+export function fromMysql2Pool(pool: Mysql2Pool): Queryable {
+  return {
+    engine: "mysql",
+    maxParams: 65535,
+    query: runOn(pool),
+    transaction: async <T>(body: (tx: Queryable) => Promise<T>): Promise<T> => {
+      const client = await pool.getConnection();
+      try {
+        return await transactionOn(connection(client), body);
+      } finally {
+        client.release();
+      }
+    },
+  };
+}

package/adapters/node-sqlite.js

@@ -0,0 +1,93 @@
+// @flow
+//
+// `@uniflowed/sql/node-sqlite`: Node's built-in `node:sqlite`.
+//
+//   import { DatabaseSync } from "node:sqlite";
+//   import { fromNodeSqlite } from "@uniflowed/sql/node-sqlite";
+//
+//   const db = fromNodeSqlite(new DatabaseSync("app.db"));
+//
+// Needs `StatementSync#setReturnArrays`, which Node added in 24.0 and 22.16.
+// An older Node gets an error that says so, rather than rows keyed by column
+// name — which would silently merge two columns that share one.
+
+import type { Queryable, SqlParam } from "../index.js";
+import { SqlError, singleConnection } from "../index.js";
+import { DEFAULT_STATEMENT_CACHE, count, rowId, statementCache } from "../internal/statements.js";
+
+/** The part of `node:sqlite`'s `StatementSync` this uses. */
+export interface NodeSqliteStatement {
+  all(...params: $ReadOnlyArray<SqlParam>): $ReadOnlyArray<mixed>;
+  run(...params: $ReadOnlyArray<SqlParam>): {
+    readonly changes: number | bigint,
+    readonly lastInsertRowid: number | bigint,
+    ...
+  };
+  setReadBigInts(enabled: boolean): void;
+  setReturnArrays(enabled: boolean): void;
+}
+
+/** The part of `node:sqlite`'s `DatabaseSync` this uses. */
+export interface NodeSqliteDatabase {
+  prepare(text: string): NodeSqliteStatement;
+}
+
+export type NodeSqliteOptions = {|
+  /** How a transaction starts. `BEGIN IMMEDIATE` takes the write lock up front. */
+  readonly begin?: string,
+  /** Prepared statements kept; 0 turns the cache off. */
+  readonly statementCache?: number,
+  /** `SQLITE_MAX_VARIABLE_NUMBER` if the build changed it. */
+  readonly maxParams?: number,
+|};
+
+function prepared(database: NodeSqliteDatabase, text: string): NodeSqliteStatement {
+  const statement = database.prepare(text);
+  statement.setReadBigInts(true);
+  // Declared, so that a Node without it is refused with a reason rather than
+  // failing on the call below.
+  if (!("setReturnArrays" in statement)) {
+    throw new SqlError({
+      kind: "unsupported",
+      feature: "node:sqlite without StatementSync#setReturnArrays (Node 24.0 or 22.16 and newer)",
+    });
+  }
+  statement.setReturnArrays(true);
+  return statement;
+}
+
+/** A [`Queryable`] over one `DatabaseSync`. */
+export function fromNodeSqlite(
+  database: NodeSqliteDatabase,
+  options: NodeSqliteOptions = {},
+): Queryable {
+  const statement = statementCache(
+    (text) => prepared(database, text),
+    options.statementCache ?? DEFAULT_STATEMENT_CACHE,
+  );
+  return singleConnection({
+    engine: "sqlite",
+    maxParams: options.maxParams ?? 32766,
+    begin: options.begin,
+    run: async (text, params, mode) => {
+      const prepared = statement(text);
+      if (mode === "rows") {
+        const rows = prepared.all(...params);
+        const arrays: Array<$ReadOnlyArray<mixed>> = [];
+        for (const row of rows) {
+          if (!Array.isArray(row)) {
+            throw new SqlError({ kind: "unsupported", feature: "node:sqlite rows as objects" });
+          }
+          arrays.push(row);
+        }
+        return { rows: arrays, rowsAffected: 0, lastInsertId: null };
+      }
+      const result = prepared.run(...params);
+      return {
+        rows: [],
+        rowsAffected: count(result.changes),
+        lastInsertId: rowId(result.lastInsertRowid),
+      };
+    },
+  });
+}

package/adapters/pg.js

@@ -0,0 +1,88 @@
+// @flow
+//
+// `@uniflowed/sql/pg`: node-postgres.
+//
+//   import pg from "pg";
+//   import { fromPgPool } from "@uniflowed/sql/pg";
+//
+//   const db = fromPgPool(new pg.Pool({ connectionString }));
+//
+// Every query asks for array rows and replaces node-postgres's type parsers
+// with the identity for that query alone, so the pool's own configuration is
+// left as the application set it, and generated code still sees the server's
+// text. A transaction checks a client out of the pool for its duration.
+
+import type { Connection, QueryResult, Queryable, Run } from "../index.js";
+import { singleConnection, transactionOn } from "../index.js";
+
+type PgResult = { readonly rows: $ReadOnlyArray<mixed>, readonly rowCount: number | null, ... };
+
+type PgQuery = {|
+  readonly text: string,
+  readonly values: $ReadOnlyArray<mixed>,
+  readonly rowMode: "array",
+  readonly types: {| readonly getTypeParser: () => (value: string) => string |},
+|};
+
+/** A connected `pg.Client` or a client checked out of a pool. */
+export interface PgClient {
+  query(config: PgQuery): Promise<PgResult>;
+}
+
+/** A client checked out of a `pg.Pool`. */
+export interface PgPoolClient extends PgClient {
+  release(error?: mixed): void;
+}
+
+/** A `pg.Pool`. */
+export interface PgPool {
+  query(config: PgQuery): Promise<PgResult>;
+  connect(): Promise<PgPoolClient>;
+}
+
+const RAW = { getTypeParser: () => (value: string) => value };
+
+function runOn(client: PgClient): Run {
+  return async (text, params): Promise<QueryResult> => {
+    const result = await client.query({ text, values: params, rowMode: "array", types: RAW });
+    const rows: Array<$ReadOnlyArray<mixed>> = [];
+    for (const row of result.rows) {
+      if (Array.isArray(row)) {
+        rows.push(row);
+      }
+    }
+    return { rows, rowsAffected: result.rowCount ?? 0, lastInsertId: null };
+  };
+}
+
+function connection(client: PgClient): Connection {
+  return { engine: "postgresql", maxParams: 65535, run: runOn(client) };
+}
+
+/** A [`Queryable`] over one connected `pg.Client`, which it serialises. */
+export function fromPgClient(client: PgClient): Queryable {
+  return singleConnection(connection(client));
+}
+
+/** A [`Queryable`] over a `pg.Pool`. */
+export function fromPgPool(pool: PgPool): Queryable {
+  return {
+    engine: "postgresql",
+    maxParams: 65535,
+    query: runOn(pool),
+    transaction: async <T>(body: (tx: Queryable) => Promise<T>): Promise<T> => {
+      const client = await pool.connect();
+      let broken: mixed = undefined;
+      try {
+        return await transactionOn(connection(client), body);
+      } catch (error) {
+        broken = error;
+        throw error;
+      } finally {
+        // Handing the error back makes the pool discard a connection that may
+        // still be inside a failed transaction rather than lend it out again.
+        client.release(broken);
+      }
+    },
+  };
+}

package/adapters/pglite.js

@@ -0,0 +1,72 @@
+// @flow
+//
+// `@uniflowed/sql/pglite`: PGlite, PostgreSQL compiled to WebAssembly.
+//
+//   import { PGlite } from "@electric-sql/pglite";
+//   import { fromPGlite } from "@uniflowed/sql/pglite";
+//
+//   const db = fromPGlite(await PGlite.create());
+//
+// PGlite parses and serialises values itself, by type. This adapter turns both
+// off — an identity parser and serialiser for every type it knows — so rows
+// arrive as the server's text and parameters leave as the codecs wrote them,
+// exactly as with every other PostgreSQL adapter.
+
+import type { Queryable, SqlParam } from "../index.js";
+import { singleConnection } from "../index.js";
+
+/** The part of a `PGlite` instance this uses. */
+export interface PGliteDatabase {
+  query(
+    text: string,
+    params: $ReadOnlyArray<SqlParam>,
+    options: {|
+      readonly rowMode: "array",
+      readonly parsers: { readonly [string]: (value: string) => mixed },
+      readonly serializers: { readonly [string]: (value: mixed) => mixed },
+    |},
+  ): Promise<{ readonly rows: $ReadOnlyArray<mixed>, readonly affectedRows?: number, ... }>;
+  readonly parsers: { readonly [string]: mixed };
+  readonly serializers: { readonly [string]: mixed };
+}
+
+const identity = (value: mixed) => value;
+
+function identities(table: { readonly [string]: mixed }): {
+  readonly [string]: (value: mixed) => mixed,
+} {
+  const out: { [string]: (value: mixed) => mixed } = {};
+  for (const key of Object.keys(table)) {
+    out[key] = identity;
+  }
+  return out;
+}
+
+/** A [`Queryable`] over one PGlite database. */
+export function fromPGlite(database: PGliteDatabase): Queryable {
+  // Rebuilt when PGlite learns a type (an extension, an array type it
+  // refreshes), which is rare; every other query reuses the same two tables.
+  let known = -1;
+  let parsers: { readonly [string]: (value: mixed) => mixed } = {};
+  let serializers: { readonly [string]: (value: mixed) => mixed } = {};
+  return singleConnection({
+    engine: "postgresql",
+    maxParams: 65535,
+    run: async (text, params) => {
+      const size = Object.keys(database.parsers).length + Object.keys(database.serializers).length;
+      if (size !== known) {
+        known = size;
+        parsers = identities(database.parsers);
+        serializers = identities(database.serializers);
+      }
+      const result = await database.query(text, params, { rowMode: "array", parsers, serializers });
+      const rows: Array<$ReadOnlyArray<mixed>> = [];
+      for (const row of result.rows) {
+        if (Array.isArray(row)) {
+          rows.push(row);
+        }
+      }
+      return { rows, rowsAffected: result.affectedRows ?? 0, lastInsertId: null };
+    },
+  });
+}