@uniflowed/sql 0.14.0

package/internal/shared.js

@@ -0,0 +1,191 @@
+// @flow
+//
+// Checks every engine's codecs share. Each one either returns the value it was
+// asked for or throws a `SqlError` that names what it expected — never a
+// rounded number, a `NaN` or an `Invalid Date` handed on as if it were data.
+
+import type { JsonValue } from "../index.js";
+import { decodeError, encodeError } from "../index.js";
+
+const INTEGER = /^[-+]?\d+$/;
+
+/** A string of decimal digits as a `number`, which must be exactly representable. */
+export function integerFromText(expected: string, value: mixed): number {
+  if (typeof value === "number") {
+    return safeInteger(expected, value);
+  }
+  if (typeof value === "bigint") {
+    return safeInteger(expected, value);
+  }
+  if (typeof value !== "string" || !INTEGER.test(value)) {
+    return decodeError(expected, value);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    return decodeError(`${expected} within ±2^53 (use the bigint representation)`, value);
+  }
+  return parsed;
+}
+
+/** A string of decimal digits, a `bigint` or a safe `number` as a `bigint`. */
+export function bigintFrom(expected: string, value: mixed): bigint {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number") {
+    // A number past 2^53 may already have been rounded by the driver, so it
+    // cannot be trusted to be the integer the database holds.
+    if (!Number.isSafeInteger(value)) {
+      return decodeError(`${expected} (the driver returned a rounded number)`, value);
+    }
+    return BigInt(value);
+  }
+  if (typeof value !== "string" || !INTEGER.test(value)) {
+    return decodeError(expected, value);
+  }
+  return BigInt(value);
+}
+
+/** A `number` or `bigint` that is an integer a `number` holds exactly. */
+export function safeInteger(expected: string, value: number | bigint): number {
+  if (typeof value === "bigint") {
+    const asNumber = Number(value);
+    if (!Number.isSafeInteger(asNumber)) {
+      return decodeError(`${expected} within ±2^53 (use the bigint representation)`, value);
+    }
+    return asNumber;
+  }
+  if (!Number.isSafeInteger(value)) {
+    return decodeError(`${expected} within ±2^53 (use the bigint representation)`, value);
+  }
+  return value;
+}
+
+/** Encode a `number` that must be an integer, for an integer column. */
+export function integerParam(expected: string, value: mixed): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+    return encodeError(expected, value);
+  }
+  return value;
+}
+
+/** Encode a `bigint`. */
+export function bigintParam(expected: string, value: mixed): bigint {
+  if (typeof value !== "bigint") {
+    return encodeError(expected, value);
+  }
+  return value;
+}
+
+/** A string, unchanged. */
+export function stringFrom(expected: string, value: mixed): string {
+  if (typeof value !== "string") {
+    return decodeError(expected, value);
+  }
+  return value;
+}
+
+/** Encode a string. */
+export function stringParam(expected: string, value: mixed): string {
+  if (typeof value !== "string") {
+    return encodeError(expected, value);
+  }
+  return value;
+}
+
+/** Encode a finite or non-finite `number`. */
+export function numberParam(expected: string, value: mixed): number {
+  if (typeof value !== "number") {
+    return encodeError(expected, value);
+  }
+  return value;
+}
+
+/** Parse a JSON document the database returned as text. */
+export function jsonFromText(value: mixed): JsonValue {
+  if (typeof value !== "string") {
+    return decodeError("JSON text", value);
+  }
+  try {
+    const parsed: JsonValue = JSON.parse(value);
+    return parsed;
+  } catch {
+    return decodeError("JSON text", value);
+  }
+}
+
+/** Serialise a JSON parameter. `undefined`, functions and symbols have no JSON. */
+export function jsonParam(value: mixed): string {
+  let text: string | void;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    // A cycle, or a `bigint`, which JSON has no spelling for.
+    return encodeError("a JSON value", value);
+  }
+  if (text === undefined) {
+    return encodeError("a JSON value", value);
+  }
+  return text;
+}
+
+/** Bytes, from a `Uint8Array` (a Node `Buffer` is one), an `ArrayBuffer` or an array of octets. */
+export function bytesFrom(expected: string, value: mixed): Uint8Array {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  if (Array.isArray(value)) {
+    const out = new Uint8Array(value.length);
+    for (let i = 0; i < value.length; i += 1) {
+      const octet = value[i];
+      if (typeof octet !== "number" || !Number.isInteger(octet) || octet < 0 || octet > 255) {
+        return decodeError(expected, value);
+      }
+      out[i] = octet;
+    }
+    return out;
+  }
+  return decodeError(expected, value);
+}
+
+/** Encode bytes. */
+export function bytesParam(expected: string, value: mixed): Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    return encodeError(expected, value);
+  }
+  return value;
+}
+
+/** One of an enum's labels. */
+export function label<T extends string>(
+  values: $ReadOnlyArray<T>,
+  expected: string,
+  value: mixed,
+): T {
+  const index = typeof value === "string" ? values.findIndex((item) => item === value) : -1;
+  if (index < 0) {
+    return decodeError(expected, value);
+  }
+  return values[index];
+}
+
+/** Encode one of an enum's labels, refusing a string that is not one. */
+export function labelParam<T extends string>(
+  values: $ReadOnlyArray<T>,
+  expected: string,
+  value: mixed,
+): T {
+  const index = typeof value === "string" ? values.findIndex((item) => item === value) : -1;
+  if (index < 0) {
+    return encodeError(expected, value);
+  }
+  return values[index];
+}
+
+/** How an enum is described in a message. */
+export function enumName(values: $ReadOnlyArray<string>): string {
+  return `one of ${values.map((value) => JSON.stringify(value)).join(", ")}`;
+}

package/internal/statements.js

@@ -0,0 +1,55 @@
+// @flow
+//
+// A bounded cache of prepared statements, for the SQLite adapters.
+//
+// Generated code runs the same few dozen statements over and over, and
+// preparing one costs a parse and a plan. The texts are constants in the
+// generated modules, so the cache's key space is the application's queries —
+// except for `sqlc.slice` and `:copyfrom`, whose text grows with the input.
+// The bound keeps those from growing it without limit; the least recently
+// used statement goes first.
+
+export const DEFAULT_STATEMENT_CACHE = 256;
+
+export function statementCache<S>(
+  prepare: (text: string) => S,
+  limit: number,
+): (text: string) => S {
+  const cache: Map<string, S> = new Map();
+  return (text) => {
+    const hit = cache.get(text);
+    if (hit !== undefined) {
+      // Re-insert, so iteration order is least recently used first.
+      cache.delete(text);
+      cache.set(text, hit);
+      return hit;
+    }
+    const statement = prepare(text);
+    if (limit > 0) {
+      if (cache.size >= limit) {
+        const oldest = cache.keys().next();
+        if (!oldest.done) {
+          cache.delete(oldest.value);
+        }
+      }
+      cache.set(text, statement);
+    }
+    return statement;
+  };
+}
+
+/** A driver's row count or row id, which may be a `number` or a `bigint`, as a `number`. */
+export function count(value: number | bigint): number {
+  return typeof value === "bigint" ? Number(value) : value;
+}
+
+/** A driver's last row id as a `bigint`, or `null` when it reported none. */
+export function rowId(value: mixed): bigint | null {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number" && Number.isSafeInteger(value)) {
+    return BigInt(value);
+  }
+  return null;
+}

package/mysql.js

@@ -0,0 +1,231 @@
+// @flow
+//
+// `@uniflowed/sql/mysql`: MySQL's text representation, both ways.
+//
+// The `mysql2` adapter reads every column as the string MySQL sent (binary
+// types as bytes) and sends parameters as strings, which MySQL converts to the
+// column's type — the conversion it applies to any literal, and the one that
+// keeps a `BIGINT UNSIGNED` or a `DECIMAL(65,30)` exact on the way in and out.
+//
+// `DATETIME` and `TIMESTAMP` stay strings. A `TIMESTAMP` is stored in UTC and
+// printed in the session's time zone, so the wall-clock text is the only
+// representation that does not depend on a setting of a connection the
+// generated code never sees.
+
+import type { JsonValue } from "./index.js";
+import { decodeError, encodeError } from "./index.js";
+import {
+  bigintFrom,
+  bytesFrom,
+  bytesParam,
+  enumName,
+  integerFromText,
+  jsonFromText,
+  jsonParam,
+  label,
+  labelParam,
+  stringFrom,
+  stringParam,
+} from "./internal/shared.js";
+
+/** What a MySQL parameter is sent as. */
+export type MysqlParam = null | string | Uint8Array;
+
+/** How one MySQL type becomes a Flow value and back. */
+export type Codec<T> = {|
+  readonly sqlType: string,
+  readonly decode: (value: mixed) => T,
+  readonly encode: (value: T) => MysqlParam,
+|};
+
+/** `TINYINT` through `INT`, signed or unsigned, and `YEAR`: all fit a `number`. */
+export function integer(sqlType: string): Codec<number> {
+  return {
+    sqlType,
+    decode: (value) => integerFromText(sqlType, value),
+    encode: (value) => {
+      if (!Number.isSafeInteger(value)) {
+        return encodeError(`${sqlType} (an integer)`, value);
+      }
+      return String(value);
+    },
+  };
+}
+
+/** `BIGINT`, signed or unsigned, exactly. */
+export const bigint: Codec<bigint> = {
+  sqlType: "bigint",
+  decode: (value) => bigintFrom("bigint", value),
+  encode: (value) => {
+    if (typeof value !== "bigint") {
+      return encodeError("bigint (a bigint)", value);
+    }
+    return String(value);
+  },
+};
+
+/** `BIGINT` as a `number`, for `int8: "number"`; throws past 2^53. */
+export const bigintAsNumber: Codec<number> = integer("bigint");
+
+/** `BIGINT` as its digits, for `int8: "string"`. */
+export const bigintAsString: Codec<string> = {
+  sqlType: "bigint",
+  decode: (value) => {
+    if (typeof value === "string" && /^[-+]?\d+$/.test(value)) {
+      return value;
+    }
+    return decodeError("bigint", value);
+  },
+  encode: (value) => stringParam("bigint (a string of digits)", value),
+};
+
+/** `TINYINT(1)` and `BOOL`, which MySQL spells `1` and `0`. */
+export const boolean: Codec<boolean> = {
+  sqlType: "tinyint(1)",
+  decode: (value) => {
+    if (value === "0" || value === 0) {
+      return false;
+    }
+    if (typeof value === "string" && /^-?\d+$/.test(value)) {
+      // MySQL's own truth test: any non-zero `TINYINT(1)` is true.
+      return true;
+    }
+    if (typeof value === "number" && Number.isInteger(value)) {
+      return true;
+    }
+    return decodeError("tinyint(1)", value);
+  },
+  encode: (value) => {
+    if (typeof value !== "boolean") {
+      return encodeError("tinyint(1) (a boolean)", value);
+    }
+    return value ? "1" : "0";
+  },
+};
+
+const DECIMAL = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+
+/** `DECIMAL`/`NUMERIC` as its exact decimal string. */
+export const decimal: Codec<string> = {
+  sqlType: "decimal",
+  decode: (value) => {
+    if (typeof value === "string" && DECIMAL.test(value)) {
+      return value;
+    }
+    return decodeError("decimal", value);
+  },
+  encode: (value) => {
+    if (typeof value !== "string" || !DECIMAL.test(value)) {
+      return encodeError("decimal (a decimal string)", value);
+    }
+    return value;
+  },
+};
+
+/** `FLOAT`, `DOUBLE`, and `DECIMAL` for `numeric: "number"`. */
+export function float(sqlType: string): Codec<number> {
+  return {
+    sqlType,
+    decode: (value) => {
+      if (typeof value === "number") {
+        return value;
+      }
+      if (typeof value === "string" && DECIMAL.test(value)) {
+        return Number(value);
+      }
+      return decodeError(sqlType, value);
+    },
+    encode: (value) => {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        // MySQL has no NaN or infinity.
+        return encodeError(`${sqlType} (a finite number)`, value);
+      }
+      return String(value);
+    },
+  };
+}
+
+/** Character types, `DATE`, `DATETIME`, `TIMESTAMP`, `TIME`, `SET`. */
+export function text(sqlType: string): Codec<string> {
+  return {
+    sqlType,
+    decode: (value) => stringFrom(sqlType, value),
+    encode: (value) => stringParam(`${sqlType} (a string)`, value),
+  };
+}
+
+/** The character types. */
+export const string: Codec<string> = text("varchar");
+
+/** `BLOB`, `BINARY`, `VARBINARY`, `BIT`. */
+export function bytes(sqlType: string): Codec<Uint8Array> {
+  return {
+    sqlType,
+    decode: (value) => bytesFrom(sqlType, value),
+    encode: (value) => bytesParam(`${sqlType} (a Uint8Array)`, value),
+  };
+}
+
+/** `JSON`. */
+export const json: Codec<JsonValue> = {
+  sqlType: "json",
+  decode: (value) => jsonFromText(value),
+  encode: (value) => jsonParam(value),
+};
+
+/** A result sqlc could not type. */
+export const unknown: Codec<mixed> = {
+  sqlType: "unknown",
+  decode: (value) => value,
+  encode: (value) => {
+    if (value === null || typeof value === "string" || value instanceof Uint8Array) {
+      return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+      return String(value);
+    }
+    if (typeof value === "boolean") {
+      return value ? "1" : "0";
+    }
+    return jsonParam(value);
+  },
+};
+
+/** An `ENUM(…)` column, from its values in declaration order. */
+export function enumeration<T extends string>(
+  sqlType: string,
+  values: $ReadOnlyArray<T>,
+): Codec<T> {
+  const expected = `${sqlType} (${enumName(values)})`;
+  return {
+    sqlType,
+    decode: (value) => label(values, expected, value),
+    encode: (value) => labelParam(values, expected, value),
+  };
+}
+
+/**
+ * An override's codec: `decode` narrows what `codec` read, `encode` widens a
+ * value back to what `codec` writes.
+ */
+export function map<T, U>(
+  codec: Codec<T>,
+  decode: (value: T) => U,
+  encode: (value: U) => T,
+): Codec<U> {
+  return {
+    sqlType: codec.sqlType,
+    decode: (value) => decode(codec.decode(value)),
+    encode: (value) => codec.encode(encode(value)),
+  };
+}
+
+/** Decode a nullable column. */
+export function nullable<T>(codec: Codec<T>, value: mixed): T | null {
+  return value === null ? null : codec.decode(value);
+}
+
+/** Encode a nullable parameter. */
+export function param<T>(codec: Codec<T>, value: T | null): MysqlParam {
+  return value === null ? null : codec.encode(value);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@uniflowed/sql",
+  "version": "0.14.0",
+  "description": "The runtime for sqlc's Flow target: exact codecs and driver adapters, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "npm/sql"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./postgresql": "./postgresql.js",
+    "./mysql": "./mysql.js",
+    "./sqlite": "./sqlite.js",
+    "./node-sqlite": "./adapters/node-sqlite.js",
+    "./bun-sqlite": "./adapters/bun-sqlite.js",
+    "./better-sqlite3": "./adapters/better-sqlite3.js",
+    "./d1": "./adapters/d1.js",
+    "./pglite": "./adapters/pglite.js",
+    "./pg": "./adapters/pg.js",
+    "./postgres": "./adapters/postgres.js",
+    "./mysql2": "./adapters/mysql2.js"
+  },
+  "files": [
+    "*.js",
+    "adapters",
+    "internal",
+    "!*.test.js"
+  ]
+}