@uniflowed/sql 0.34.0 → 0.36.0

package/adapters/better-sqlite3.js

@@ -22,7 +22,7 @@ export interface BetterSqlite3Statement {
   readonly reader: boolean;
   all(...params: $ReadOnlyArray<SqlParam>): $ReadOnlyArray<mixed>;
   run(...params: $ReadOnlyArray<SqlParam>): {
-    readonly changes: number,
+    readonly changes        : number,
     readonly lastInsertRowid: number | bigint,
     ...
   };
@@ -36,15 +36,15 @@ export interface BetterSqlite3Database {
 }
 
 export type BetterSqlite3Options = {|
-  readonly begin?: string,
+  readonly begin?         : string,
   readonly statementCache?: number,
-  readonly maxParams?: number,
+  readonly maxParams?     : number,
 |};
 
 /** A [`Queryable`] and a [`SyncQueryable`] over one better-sqlite3 `Database`. */
 export function fromBetterSqlite3(
   database: BetterSqlite3Database,
-  options: BetterSqlite3Options = {},
+  options : BetterSqlite3Options = {},
 ): Queryable & SyncQueryable {
   const statement = statementCache((text) => {
     const prepared = database.prepare(text);
@@ -70,16 +70,16 @@ export function fromBetterSqlite3(
     }
     const result = prepared.run(...params);
     return {
-      rows: [],
+      rows        : [],
       rowsAffected: count(result.changes),
       lastInsertId: rowId(result.lastInsertRowid),
     };
   };
   return singleConnectionSync({
-    engine: "sqlite",
+    engine   : "sqlite",
     maxParams: options.maxParams ?? 32766,
-    begin: options.begin,
-    run: async (text, params, mode) => runSync(text, params, mode),
+    begin    : options.begin,
+    run      : async (text, params, mode) => runSync(text, params, mode),
     runSync,
   });
 }

package/adapters/bun-sqlite.js

@@ -21,7 +21,7 @@ import { DEFAULT_STATEMENT_CACHE, count, rowId, statementCache } from "../intern
 export interface BunSqliteStatement {
   values(...params: $ReadOnlyArray<SqlParam>): $ReadOnlyArray<mixed>;
   run(...params: $ReadOnlyArray<SqlParam>): {
-    readonly changes: number | bigint,
+    readonly changes        : number | bigint,
     readonly lastInsertRowid: number | bigint,
     ...
   };
@@ -34,15 +34,15 @@ export interface BunSqliteDatabase {
 }
 
 export type BunSqliteOptions = {|
-  readonly begin?: string,
+  readonly begin?         : string,
   readonly statementCache?: number,
-  readonly maxParams?: number,
+  readonly maxParams?     : number,
 |};
 
 /** A [`Queryable`] and a [`SyncQueryable`] over one `bun:sqlite` `Database`. */
 export function fromBunSqlite(
   database: BunSqliteDatabase,
-  options: BunSqliteOptions = {},
+  options : BunSqliteOptions = {},
 ): Queryable & SyncQueryable {
   const statement = statementCache((text) => {
     const prepared = database.prepare(text);
@@ -63,16 +63,16 @@ export function fromBunSqlite(
     }
     const result = prepared.run(...params);
     return {
-      rows: [],
+      rows        : [],
       rowsAffected: count(result.changes),
       lastInsertId: rowId(result.lastInsertRowid),
     };
   };
   return singleConnectionSync({
-    engine: "sqlite",
+    engine   : "sqlite",
     maxParams: options.maxParams ?? 32766,
-    begin: options.begin,
-    run: async (text, params, mode) => runSync(text, params, mode),
+    begin    : options.begin,
+    run      : async (text, params, mode) => runSync(text, params, mode),
     runSync,
   });
 }

package/adapters/d1.js

@@ -47,7 +47,7 @@ function toD1(param: SqlParam): mixed {
 /** A [`Queryable`] over a D1 binding. */
 export function fromD1(database: D1Database): Queryable {
   return {
-    engine: "sqlite",
+    engine   : "sqlite",
     maxParams: 100,
     query: async (text, params, mode) => {
       const statement = database.prepare(text).bind(...params.map(toD1));
@@ -63,7 +63,7 @@ export function fromD1(database: D1Database): Queryable {
       }
       const { meta } = await statement.run();
       return {
-        rows: [],
+        rows        : [],
         rowsAffected: count(meta.changes ?? 0),
         lastInsertId: rowId(meta.last_row_id),
       };

package/adapters/mysql2.js

@@ -34,13 +34,13 @@ export type Mysql2Field = {
 };
 
 type Mysql2Options = {|
-  readonly sql: string,
-  readonly values: $ReadOnlyArray<mixed>,
-  readonly rowsAsArray: true,
+  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,
+  readonly bigNumberStrings : true,
+  readonly dateStrings      : true,
+  readonly typeCast         : (field: Mysql2Field, next: () => mixed) => mixed,
 |};
 
 type Mysql2Result =
@@ -93,12 +93,12 @@ function lastId(value: number | string): bigint | null {
 function runOn(connection: Mysql2Connection): Run {
   return async (text, params, mode): Promise<QueryResult> => {
     const options: Mysql2Options = {
-      sql: text,
-      values: params,
-      rowsAsArray: true,
+      sql              : text,
+      values           : params,
+      rowsAsArray      : true,
       supportBigNumbers: true,
-      bigNumberStrings: true,
-      dateStrings: true,
+      bigNumberStrings : true,
+      dateStrings      : true,
       typeCast,
     };
     const [result] =
@@ -125,9 +125,9 @@ function connection(client: Mysql2Connection): Connection {
 /** A [`Queryable`] over a `mysql2/promise` pool. */
 export function fromMysql2Pool(pool: Mysql2Pool): Queryable {
   return {
-    engine: "mysql",
+    engine   : "mysql",
     maxParams: 65535,
-    query: runOn(pool),
+    query    : runOn(pool),
     transaction: async <T>(body: (tx: Queryable) => Promise<T>): Promise<T> => {
       const client = await pool.getConnection();
       try {

package/adapters/node-sqlite.js

@@ -22,7 +22,7 @@ import { DEFAULT_STATEMENT_CACHE, count, rowId, statementCache } from "../intern
 export interface NodeSqliteStatement {
   all(...params: $ReadOnlyArray<SqlParam>): $ReadOnlyArray<mixed>;
   run(...params: $ReadOnlyArray<SqlParam>): {
-    readonly changes: number | bigint,
+    readonly changes        : number | bigint,
     readonly lastInsertRowid: number | bigint,
     ...
   };
@@ -51,7 +51,7 @@ function prepared(database: NodeSqliteDatabase, text: string): NodeSqliteStateme
   // failing on the call below.
   if (!("setReturnArrays" in statement)) {
     throw new SqlError({
-      kind: "unsupported",
+      kind   : "unsupported",
       feature: "node:sqlite without StatementSync#setReturnArrays (Node 24.0 or 22.16 and newer)",
     });
   }
@@ -62,7 +62,7 @@ function prepared(database: NodeSqliteDatabase, text: string): NodeSqliteStateme
 /** A [`Queryable`] and a [`SyncQueryable`] over one `DatabaseSync`. */
 export function fromNodeSqlite(
   database: NodeSqliteDatabase,
-  options: NodeSqliteOptions = {},
+  options : NodeSqliteOptions = {},
 ): Queryable & SyncQueryable {
   const statement = statementCache(
     (text) => prepared(database, text),
@@ -83,16 +83,16 @@ export function fromNodeSqlite(
     }
     const result = prepared.run(...params);
     return {
-      rows: [],
+      rows        : [],
       rowsAffected: count(result.changes),
       lastInsertId: rowId(result.lastInsertRowid),
     };
   };
   return singleConnectionSync({
-    engine: "sqlite",
+    engine   : "sqlite",
     maxParams: options.maxParams ?? 32766,
-    begin: options.begin,
-    run: async (text, params, mode) => runSync(text, params, mode),
+    begin    : options.begin,
+    run      : async (text, params, mode) => runSync(text, params, mode),
     runSync,
   });
 }

package/adapters/pg.js

@@ -11,22 +11,48 @@
 // 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.
+// `:copyfrom` is a `COPY FROM STDIN`: node-postgres runs it when the query
+// object supplies `submit` and `handleCopyInResponse`, which is the protocol
+// hook it already has and does not implement for a string query.
 
-import type { Connection, QueryResult, Queryable, Run } from "../index.js";
+import type { Connection, CopyIn, 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 text   : string,
+  readonly values : $ReadOnlyArray<mixed>,
   readonly rowMode: "array",
-  readonly types: {| readonly getTypeParser: () => (value: string) => string |},
+  readonly types  : {| readonly getTypeParser: () => (value: string) => string |},
 |};
 
+/** The connection methods a `COPY FROM STDIN` uses. `pg` passes its own. */
+type PgCopyConnection = {
+  query(text: string): mixed,
+  sendCopyFromChunk(chunk: Uint8Array): mixed,
+  endCopyFrom(): mixed,
+};
+
+/** A query object `pg` runs when `submit` is a function. */
+type PgCopyRequest = {
+  text    : string,
+  callback: ?(?mixed, ?PgResult) => mixed,
+  submit(connection: PgCopyConnection): null,
+  handleCopyInResponse(connection: PgCopyConnection): void,
+  handleCommandComplete(message: { text?: string, ... }): void,
+  handleReadyForQuery(): void,
+  handleError(error: mixed): void,
+  handleCopyData(): void,
+  handleRowDescription(): void,
+  handleDataRow(): void,
+  handleEmptyQuery(): void,
+  handlePortalSuspended(): void,
+};
+
 /** A connected `pg.Client` or a client checked out of a pool. */
 export interface PgClient {
-  query(config: PgQuery): Promise<PgResult>;
+  query(config: PgQuery | PgCopyRequest): Promise<PgResult> | void;
 }
 
 /** A client checked out of a `pg.Pool`. */
@@ -36,15 +62,99 @@ export interface PgPoolClient extends PgClient {
 
 /** A `pg.Pool`. */
 export interface PgPool {
-  query(config: PgQuery): Promise<PgResult>;
+  query(config: PgQuery | PgCopyRequest): Promise<PgResult>;
   connect(): Promise<PgPoolClient>;
 }
 
+const COPY_ROWS = /COPY (\d+)/;
+
+/**
+ * One `COPY FROM STDIN` on `runner`.
+ *
+ * The callback is left unset when `runner` is a pool: the pool sets it, and
+ * setting it here would skip the pool's own, which is what releases the
+ * client. A client sets it in the wrapper below, because `client.query` only
+ * returns a promise when the object does not already have one and nobody
+ * passed a callback.
+ */
+function copyRequest(statement: string, payload: string): PgCopyRequest {
+  let rowCount = 0;
+  let settled = false;
+  const request: PgCopyRequest = {
+    text    : statement,
+    callback: undefined,
+    submit(connection) {
+      connection.query(statement);
+      return null;
+    },
+    handleCopyInResponse(connection) {
+      // pg-protocol copies the chunk with `Buffer#copy`. A `Uint8Array` has
+      // no `copy`, and the throw leaves the backend waiting for `CopyData`.
+      connection.sendCopyFromChunk(Buffer.from(payload, "utf8"));
+      connection.endCopyFrom();
+    },
+    handleCommandComplete(message) {
+      const text = typeof message.text === "string" ? message.text : "";
+      const match = COPY_ROWS.exec(text);
+      if (match?.[1] !== undefined) {
+        rowCount = Number(match[1]);
+      }
+    },
+    handleReadyForQuery() {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      request.callback?.(null, { rows: [], rowCount });
+    },
+    handleError(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      request.callback?.(error, undefined);
+    },
+    handleCopyData() {},
+    handleRowDescription() {},
+    handleDataRow() {},
+    handleEmptyQuery() {},
+    handlePortalSuspended() {},
+  };
+  return request;
+}
+
+function copyOn(runner: PgClient): CopyIn {
+  return (statement, payload) =>
+    new Promise((resolve, reject) => {
+      const request = copyRequest(statement, payload);
+      request.callback = (error, result) => {
+        if (error != null) {
+          reject(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+        resolve(result?.rowCount ?? 0);
+      };
+      runner.query(request);
+    });
+}
+
+function copyOnPool(pool: PgPool): CopyIn {
+  return async (statement, payload) => {
+    const result = await pool.query(copyRequest(statement, payload));
+    return result.rowCount ?? 0;
+  };
+}
+
 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 });
+    // A `COPY` request returns void. This call is a normal query, which
+    // returns a result; the union is what `query` is declared as.
+    if (result == null) {
+      throw new Error("pg query returned no result");
+    }
     const rows: Array<$ReadOnlyArray<mixed>> = [];
     for (const row of result.rows) {
       if (Array.isArray(row)) {
@@ -56,7 +166,7 @@ function runOn(client: PgClient): Run {
 }
 
 function connection(client: PgClient): Connection {
-  return { engine: "postgresql", maxParams: 65535, run: runOn(client) };
+  return { engine: "postgresql", maxParams: 65535, run: runOn(client), copy: copyOn(client) };
 }
 
 /** A [`Queryable`] over one connected `pg.Client`, which it serialises. */
@@ -67,9 +177,10 @@ export function fromPgClient(client: PgClient): Queryable {
 /** A [`Queryable`] over a `pg.Pool`. */
 export function fromPgPool(pool: PgPool): Queryable {
   return {
-    engine: "postgresql",
+    engine   : "postgresql",
     maxParams: 65535,
-    query: runOn(pool),
+    query    : runOn(pool),
+    copy     : copyOnPool(pool),
     transaction: async <T>(body: (tx: Queryable) => Promise<T>): Promise<T> => {
       const client = await pool.connect();
       let broken: mixed = undefined;

package/adapters/pglite.js

@@ -10,7 +10,8 @@
 // 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.
+// exactly as with every other PostgreSQL adapter. `:copyfrom` uses PGlite's
+// `/dev/blob` device, which is how its `COPY FROM` reads a payload.
 
 import type { Queryable, SqlParam } from "../index.js";
 import { singleConnection } from "../index.js";
@@ -18,15 +19,16 @@ import { singleConnection } from "../index.js";
 /** The part of a `PGlite` instance this uses. */
 export interface PGliteDatabase {
   query(
-    text: string,
+    text  : string,
     params: $ReadOnlyArray<SqlParam>,
     options: {|
-      readonly rowMode: "array",
-      readonly parsers: { readonly [string]: (value: string) => mixed },
+      readonly rowMode    : "array",
+      readonly parsers    : { readonly [string]: (value: string) => mixed },
       readonly serializers: { readonly [string]: (value: mixed) => mixed },
+      readonly blob?      : Blob,
     |},
   ): Promise<{ readonly rows: $ReadOnlyArray<mixed>, readonly affectedRows?: number, ... }>;
-  readonly parsers: { readonly [string]: mixed };
+  readonly parsers    : { readonly [string]: mixed };
   readonly serializers: { readonly [string]: mixed };
 }
 
@@ -50,8 +52,29 @@ export function fromPGlite(database: PGliteDatabase): Queryable {
   let parsers: { readonly [string]: (value: mixed) => mixed } = {};
   let serializers: { readonly [string]: (value: mixed) => mixed } = {};
   return singleConnection({
-    engine: "postgresql",
+    engine   : "postgresql",
     maxParams: 65535,
+    copy: async (statement, payload) => {
+      // `COPY … FROM STDIN` is the wire form. PGlite reads the payload from
+      // the virtual file named here instead of a frontend COPY stream.
+      const text = statement.replace(" FROM STDIN", " FROM '/dev/blob'");
+      const result = await database.query(text, [], {
+        rowMode    : "array",
+        parsers    : {},
+        serializers: {},
+        blob       : new Blob([payload]),
+      });
+      if (typeof result.affectedRows === "number") {
+        return result.affectedRows;
+      }
+      let rows = 0;
+      for (let i = 0; i < payload.length; i += 1) {
+        if (payload[i] === "\n") {
+          rows += 1;
+        }
+      }
+      return rows;
+    },
     run: async (text, params) => {
       const size = Object.keys(database.parsers).length + Object.keys(database.serializers).length;
       if (size !== known) {

package/adapters/postgres.js

@@ -18,20 +18,36 @@
 // `bytea`, `x === true ? "t" : "f"` for `bool` — each of which would corrupt a
 // value the codecs already wrote as text. Declaring every parameter as
 // `unknown` (OID 705) leaves the server to infer the type, as an undeclared
-// one would, and leaves postgres.js nothing to serialise.
+// one would, and leaves postgres.js nothing to serialise. `:copyfrom` writes
+// the text-format payload to the stream `unsafe(statement, []).writable()`
+// opens for `COPY FROM STDIN`.
 
 import { SqlError } from "../index.js";
-import type { Queryable, SqlParam } from "../index.js";
+import type { CopyIn, Queryable, SqlParam } from "../index.js";
 
 type RawRows = Promise<$ReadOnlyArray<mixed> & { readonly count?: number | null, ... }>;
 
-type Unsafe = { raw(): RawRows, ... };
+/** The Node writable postgres.js resolves `COPY FROM STDIN` to. */
+type CopyWritable = {
+  write(chunk: string, callback: (error?: mixed) => mixed): mixed,
+  end(callback: (error?: mixed) => mixed): mixed,
+  once(event: "error", listener: (error: mixed) => mixed): mixed,
+  ...
+};
+
+type Unsafe = {
+  raw(): RawRows,
+  writable(): Promise<CopyWritable>,
+  /** Rejects the query. postgres.js calls it for a server error during `COPY`. */
+  reject: (error: mixed) => mixed,
+  ...
+};
 
 /** What postgres.js's `Sql` and its transaction handles have in common. */
 export interface PostgresQueries {
   unsafe(
-    text: string,
-    params: $ReadOnlyArray<mixed>,
+    text    : string,
+    params  : $ReadOnlyArray<mixed>,
     options?: {| readonly prepare?: boolean |},
   ): Unsafe;
   typed(value: SqlParam, oid: number): mixed;
@@ -56,6 +72,78 @@ function text(value: mixed): mixed {
 /** `unknown`: a parameter whose type the server decides. */
 const UNKNOWN = 705;
 
+function rowCount(payload: string): number {
+  let rows = 0;
+  for (let i = 0; i < payload.length; i += 1) {
+    if (payload[i] === "\n") {
+      rows += 1;
+    }
+  }
+  return rows;
+}
+
+/** Write `payload` and wait until the server finishes the `COPY`. */
+function writeCopy(writable: CopyWritable, payload: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error: mixed) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const succeed = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve();
+    };
+    writable.once("error", fail);
+    writable.write(payload, (error) => {
+      if (error != null) {
+        fail(error);
+        return;
+      }
+      writable.end((endError) => {
+        if (endError != null) {
+          fail(endError);
+        } else {
+          succeed();
+        }
+      });
+    });
+  });
+}
+
+function copyOn(sql: PostgresQueries): CopyIn {
+  return async (statement, payload) => {
+    const query = sql.unsafe(statement, []);
+    // CopyInResponse resolves the query with the writable, and sending
+    // CopyDone clears that stream before the server answers. A failure after
+    // the data is in (a foreign key) calls `query.reject` and never reaches
+    // the writable, so its end callback would wait forever.
+    let fail: (error: mixed) => void = () => {};
+    const failed = new Promise((resolve, reject) => {
+      void resolve;
+      fail = reject;
+    });
+    failed.catch(() => {});
+    const rejectQuery = query.reject.bind(query);
+    query.reject = (error) => {
+      fail(error);
+      return rejectQuery(error);
+    };
+    const writable = await query.writable();
+    await Promise.race([writeCopy(writable, payload), failed]);
+    // CommandComplete carries `COPY n`, and postgres.js keeps that count on
+    // its internal result. A `COPY` without `WHERE` accepts every row or
+    // fails, so the number of lines written is the number the server copied.
+    return rowCount(payload);
+  };
+}
+
 function run(sql: PostgresQueries): Queryable["query"] {
   return async (statement, params) => {
     const typed = params.map((param) => (param === null ? null : sql.typed(param, UNKNOWN)));
@@ -83,10 +171,12 @@ async function scoped<T>(tx: PostgresTransaction, body: (tx: Queryable) => Promi
   let open = true;
   const query = run(tx);
   const queryable: Queryable = {
-    engine: "postgresql",
+    engine   : "postgresql",
     maxParams: 65535,
     query: (statement, params, mode) =>
       open ? query(statement, params, mode) : Promise.reject(new SqlError({ kind: "closed" })),
+    copy: (statement, payload) =>
+      open ? copyOn(tx)(statement, payload) : Promise.reject(new SqlError({ kind: "closed" })),
     transaction: <U>(inner: (tx: Queryable) => Promise<U>): Promise<U> =>
       open
         ? tx.savepoint((savepoint) => scoped(savepoint, inner))
@@ -102,9 +192,10 @@ async function scoped<T>(tx: PostgresTransaction, body: (tx: Queryable) => Promi
 /** A [`Queryable`] over a postgres.js `Sql`. */
 export function fromPostgres(sql: PostgresSql): Queryable {
   return {
-    engine: "postgresql",
+    engine   : "postgresql",
     maxParams: 65535,
-    query: run(sql),
+    query    : run(sql),
+    copy     : copyOn(sql),
     transaction: <T>(body: (tx: Queryable) => Promise<T>): Promise<T> =>
       sql.begin((tx) => scoped(tx, body)),
   };