@typesql/pg 0.0.4 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @typesql/pg
 
+## 0.1.0
+
+### Minor Changes
+
+- Queries run from the `sql` bound to your client: `createSql<DB>(client)` then `sql("…").execute()` (or `executeTakeFirst`, `executeTakeFirstOrThrow`, `executeCount`), and `sql.transaction(async (tx) => …)` for transactions, nested with savepoints; the `query`, `one`, `maybeOne`, `many`, `execute`, `transaction` and `RowCountError` exports of `@typesql/pg` and `@typesql/postgres`, `query` and `execute` of `@typesql/kysely`, and `queryRaw` and `executeRaw` of `@typesql/prisma` are removed.
+
+### Patch Changes
+
+- The README links to the type map tables on the new node-postgres and postgres.js adapter pages of the docs.
+
+- Updated dependencies:
+  - @typesql/core@0.1.0
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,7 @@
 
 [node-postgres](https://node-postgres.com) (`pg` 8.x) adapter for
 [`@typesql/core`](https://www.npmjs.com/package/@typesql/core): a `createSql` bound to the type
-map of `pg`'s default parsers, and helpers that run a query and return rows typed from it.
+map of `pg`'s default parsers, whose queries run on your pool and return rows typed from the SQL.
 
 ```sh
 pnpm add @typesql/core @typesql/pg pg
@@ -12,21 +12,20 @@ pnpm add @typesql/core @typesql/pg pg
 
 ```ts
 import { Pool } from "pg";
-import { createSql, execute, many, maybeOne, one, query, transaction } from "@typesql/pg";
+import { createSql } from "@typesql/pg";
 import type { DB } from "./schema";
 
 const pool = new Pool();
-const sql = createSql<DB>();
+const sql = createSql<DB>(pool);
 
-const users = await query(pool, sql("SELECT id, email FROM users")); // { id: number; email: string }[]
-const user = await one(pool, sql("SELECT id, email FROM users WHERE id = $1", 7)); // exactly one row, or throws
-const maybe = await maybeOne(pool, sql("SELECT id FROM users WHERE email = $1", "x")); // row | null
-const some = await many(pool, sql("SELECT id FROM posts")); // at least one row, or throws
-const changed = await execute(pool, sql("UPDATE users SET display_name = NULL")); // row count
+const users = await sql("SELECT id, email FROM users").execute(); // { id: number; email: string }[]
+const maybe = await sql("SELECT id FROM users WHERE email = $1", "x").executeTakeFirst(); // row | undefined
+const user = await sql("SELECT id, email FROM users WHERE id = $1", 7).executeTakeFirstOrThrow(); // row, or NoResultError
+const changed = await sql("UPDATE users SET display_name = NULL").executeCount(); // row count
 
-const id = await transaction(pool, async (client) => {
-  const { id } = await one(client, sql("INSERT INTO users (email) VALUES ($1) RETURNING id", "a@b.c"));
-  await execute(client, sql("INSERT INTO posts (author_id, title) VALUES ($1, $2)", id, "Hello"));
+const id = await sql.transaction(async (tx) => {
+  const { id } = await tx("INSERT INTO users (email) VALUES ($1) RETURNING id", "a@b.c").executeTakeFirstOrThrow();
+  await tx("INSERT INTO posts (author_id, title) VALUES ($1, $2)", id, "Hello").execute();
   return id;
 });
 ```
@@ -35,20 +34,18 @@ const id = await transaction(pool, async (client) => {
 
 | Export | |
 |---|---|
-| `createSql<DB>(pool?, options?)` | core's `createSql<DB, PgTypeMap>()`; `{ rowKeys: "camelCase" }` camelCases the row keys |
-| `query(client, q)` | `Promise<Row[]>` |
-| `one(client, q)` | `Promise<Row>`; `RowCountError` unless exactly one row |
-| `maybeOne(client, q)` | `Promise<Row \| null>`; `RowCountError` on more than one row |
-| `many(client, q)` | `Promise<[Row, ...Row[]]>`; `RowCountError` on zero rows |
-| `execute(client, q)` | `Promise<number>`, the affected row count |
-| `executor(client)` | an `Executor` for `q.execute()` and `q.executeCount()` (reports `rowCount`); `createSql<DB>(pool)` binds one |
-| `transaction(pool, fn)` | `BEGIN`, `fn(client)`, `COMMIT`; `ROLLBACK` and rethrow on error |
+| `createSql<DB>(client, options?)` | core's `createSql<DB, PgTypeMap>()` with the queries running on `client` (a `Pool`, `Client` or `PoolClient`); `{ rowKeys: "camelCase" }` camelCases the row keys |
+| `q.execute()`, `q.executeTakeFirst()`, `q.executeTakeFirstOrThrow()`, `q.executeCount()` | `Promise<Row[]>`, `Promise<Row \| undefined>`, `Promise<Row>` (`NoResultError` on 0 rows), `Promise<number>` (`rowCount`) |
+| `sql.transaction(fn)` | on a `Pool`: checks out a client, `BEGIN`, `fn(tx)`, `COMMIT`, releases it; `ROLLBACK` and rethrow on error. On a `Client` or `PoolClient`: the same on that connection. `tx` is `sql` bound to the transaction; `tx.transaction(fn)` uses a savepoint |
+| `executor(client)` | an `Executor` for `q.execute(executor)` and core's `createSql(executor)` (reports `rowCount`) |
 | `migrate(pool, m)` | runs `m.statements` (e.g. from core's `migrations()`) in one transaction |
+| `PgSql<DB, Keys>` | the type `createSql` returns |
 | `PgTypeMap`, `PgParamTypeMap`, `PgInterval` | the type map (rows), what parameters also accept, and the `postgres-interval` object type |
-| `RowCountError`, `PgQueryable`, `PgPoolLike`, `PgTransactionClient`, `PgResult`, `MigrationSource` | errors and parameter types |
+| `NoResultError`, `PgQueryable`, `PgPoolLike`, `PgTransactionClient`, `PgResult`, `MigrationSource` | errors and parameter types |
 
-`client` is anything with `query(text, values)`: a `Pool`, `Client` or `PoolClient`. The
-parameters are structural, so fakes work in tests.
+`client` is anything with `query(text, values)`. The parameters are structural, so fakes work
+in tests. If the `ROLLBACK` of a pool transaction fails, the client is released with the error
+so the pool discards the connection.
 
 ## `typesql introspect`
 
@@ -83,7 +80,7 @@ What `pg`'s default parsers return:
 | text-like and other types | `string` |
 
 Arrays map element-wise. The full table, including the array types `pg` leaves as raw text, is
-in the [Adapters guide](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/guide/adapters.md).
+on the [node-postgres adapter page](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/adapters/pg.md).
 
 Parameters accept the row type and what `pg` serializes for the type (`PgParamTypeMap`):
 `number | bigint | string` for `int8`, `numeric` and `money`, `Date | string` for dates and

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { type Executor, type Query, type RowType } from "@typesql/core";
-/** The subset of a `pg` query result the helpers rely on. */
+import { type Executor, type SqlDriver } from "@typesql/core";
+/** The subset of a `pg` query result the adapter relies on. */
 export interface PgResult {
     readonly rows: unknown[];
     readonly rowCount: number | null;
@@ -19,37 +19,13 @@ export interface PgTransactionClient extends PgQueryable {
 export interface PgPoolLike<C extends PgTransactionClient = PgTransactionClient> {
     connect(): Promise<C>;
 }
-/** Thrown by `one`, `maybeOne` and `many` when the row count does not match. */
-export declare class RowCountError extends Error {
-    readonly code: "NO_ROWS" | "TOO_MANY_ROWS";
-    readonly expected: string;
-    readonly actual: number;
-    readonly text: string;
-    readonly name = "RowCountError";
-    constructor(code: "NO_ROWS" | "TOO_MANY_ROWS", expected: string, actual: number, text: string);
-}
-type AnyQuery = Query<unknown, readonly unknown[]>;
 /**
  * An `Executor` for core's `q.execute()`: runs queries on `client` and resolves to
  * `{ rows, rowCount }` (pg's `rowCount`, so `q.executeCount()` works).
  */
 export declare function executor(client: PgQueryable): Executor;
-/** Run a query and return all rows, typed from the query. */
-export declare function query<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q>[]>;
-/** Exactly one row, otherwise throws `RowCountError`. */
-export declare function one<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q>>;
-/** Zero or one row (`null` for zero); throws `RowCountError` on more than one. */
-export declare function maybeOne<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q> | null>;
-/** At least one row, otherwise throws `RowCountError`. */
-export declare function many<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<[RowType<Q>, ...RowType<Q>[]]>;
-/** Run a statement for its side effect and return the affected row count (`rowCount ?? 0`). */
-export declare function execute(client: PgQueryable, q: AnyQuery): Promise<number>;
-/**
- * Check out a client, run `fn` inside BEGIN/COMMIT, ROLLBACK on error, and release the
- * client. If ROLLBACK itself fails the client is released with the error so the pool
- * discards the connection instead of reusing it.
- */
-export declare function transaction<C extends PgTransactionClient, T>(pool: PgPoolLike<C>, fn: (client: C) => Promise<T>): Promise<T>;
+/** How `createSql(client)` runs queries and transactions. */
+export declare const driver: SqlDriver<PgQueryable>;
 /** Anything carrying an ordered list of DDL statements, e.g. a `migrations()` builder from core. */
 export interface MigrationSource {
     readonly statements: readonly string[];
@@ -60,5 +36,4 @@ export interface MigrationSource {
  * with `$$`-quoted function bodies work.
  */
 export declare function migrate<C extends PgTransactionClient>(pool: PgPoolLike<C>, m: MigrationSource): Promise<void>;
-export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5D;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,6CAA6C;AAC7C,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAC7E,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAMtD;AA6CD,6DAA6D;AAC7D,eAAO,MAAM,MAAM,EAAE,SAAS,CAAC,WAAW,CAA6B,CAAC;AAExE,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,CAAC,SAAS,mBAAmB,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAInH"}

package/dist/client.js

@@ -1,101 +1,65 @@
-import { mapRows } from "@typesql/core";
-/** Thrown by `one`, `maybeOne` and `many` when the row count does not match. */
-export class RowCountError extends Error {
-    code;
-    expected;
-    actual;
-    text;
-    name = "RowCountError";
-    constructor(code, expected, actual, text) {
-        super(`Expected ${expected} row(s) but the query returned ${actual}`);
-        this.code = code;
-        this.expected = expected;
-        this.actual = actual;
-        this.text = text;
-    }
-}
-function run(client, q) {
-    // `pg` requires a mutable array (`QueryConfigValues<I>` matches `Array<U>` only).
-    return client.query(q.text, Array.from(q.values));
-}
+import { runTransaction } from "@typesql/core";
 /**
  * An `Executor` for core's `q.execute()`: runs queries on `client` and resolves to
  * `{ rows, rowCount }` (pg's `rowCount`, so `q.executeCount()` works).
  */
 export function executor(client) {
     return async (text, values) => {
+        // `pg` requires a mutable array (`QueryConfigValues<I>` matches `Array<U>` only).
         const { rows, rowCount } = await client.query(text, Array.from(values));
         return { rows, rowCount };
     };
 }
-/** Run a query and return all rows, typed from the query. */
-export async function query(client, q) {
-    const result = await run(client, q);
-    return mapRows(q, result.rows);
-}
-/** Exactly one row, otherwise throws `RowCountError`. */
-export async function one(client, q) {
-    const rows = await query(client, q);
-    if (rows.length !== 1) {
-        throw new RowCountError(rows.length === 0 ? "NO_ROWS" : "TOO_MANY_ROWS", "exactly 1", rows.length, q.text);
-    }
-    return rows[0];
-}
-/** Zero or one row (`null` for zero); throws `RowCountError` on more than one. */
-export async function maybeOne(client, q) {
-    const rows = await query(client, q);
-    if (rows.length > 1)
-        throw new RowCountError("TOO_MANY_ROWS", "at most 1", rows.length, q.text);
-    return rows.length === 0 ? null : rows[0];
+function isPool(client) {
+    // `pg.Client` has `connect()` too (it opens the socket), and `processID`; a `PoolClient` has `release()`.
+    return typeof client.connect === "function" && !("release" in client) && !("processID" in client);
 }
-/** At least one row, otherwise throws `RowCountError`. */
-export async function many(client, q) {
-    const rows = await query(client, q);
-    if (rows.length === 0)
-        throw new RowCountError("NO_ROWS", "at least 1", 0, q.text);
-    return rows;
-}
-/** Run a statement for its side effect and return the affected row count (`rowCount ?? 0`). */
-export async function execute(client, q) {
-    const result = await run(client, q);
-    return result.rowCount ?? 0;
+function isConnection(client) {
+    return "release" in client || "processID" in client;
 }
+const on = (c) => (statement) => c.query(statement);
 /**
- * Check out a client, run `fn` inside BEGIN/COMMIT, ROLLBACK on error, and release the
- * client. If ROLLBACK itself fails the client is released with the error so the pool
- * discards the connection instead of reusing it.
+ * Check out a client, run `fn` with it between `BEGIN` and `COMMIT`, and release it, with the
+ * error when `ROLLBACK` fails so the pool discards the connection instead of reusing it.
  */
-export async function transaction(pool, fn) {
-    const client = await pool.connect();
+async function inPoolTransaction(pool, fn) {
+    const conn = await pool.connect();
     let releaseWith;
     try {
-        await client.query("BEGIN");
-        try {
-            const result = await fn(client);
-            await client.query("COMMIT");
-            return result;
-        }
-        catch (err) {
-            try {
-                await client.query("ROLLBACK");
-            }
-            catch (rollbackErr) {
-                releaseWith = rollbackErr instanceof Error ? rollbackErr : new Error(String(rollbackErr));
-            }
-            throw err;
-        }
+        return await runTransaction(on(conn), () => fn(conn), {
+            onRollbackError: (err) => {
+                releaseWith = err instanceof Error ? err : new Error(String(err));
+            },
+        });
     }
     finally {
-        client.release(releaseWith);
+        conn.release(releaseWith);
+    }
+}
+/**
+ * Run `fn` inside a transaction: on a pool, on a client checked out of it; on a `Client` or
+ * `PoolClient`, on that connection. With `depth > 0` the client is already in a transaction,
+ * and `fn` runs in a savepoint.
+ */
+function transaction(client, depth, fn) {
+    if (depth > 0)
+        return runTransaction(on(client), () => fn(client), { savepoint: `typesql_${depth}` });
+    if (isPool(client))
+        return inPoolTransaction(client, fn);
+    if (!isConnection(client)) {
+        return Promise.reject(new Error("typesql: sql.transaction() needs a pg Pool, Client or PoolClient, so that BEGIN and COMMIT reach one connection"));
     }
+    return runTransaction(on(client), () => fn(client));
 }
+/** How `createSql(client)` runs queries and transactions. */
+export const driver = { executor, transaction };
 /**
  * Run a migration's statements in order on one connection, inside a single transaction
  * (all or nothing). Statements are sent as simple queries without parameters, so scripts
  * with `$$`-quoted function bodies work.
  */
 export async function migrate(pool, m) {
-    await transaction(pool, async (client) => {
+    await inPoolTransaction(pool, async (client) => {
         for (const statement of m.statements)
             await client.query(statement);
     });

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,18 +1,21 @@
-import { type Sql } from "@typesql/core";
+import { type RowKeys, type TransactionalSql } from "@typesql/core";
 import { type PgQueryable } from "./client.js";
 import type { PgTypeMap } from "./type-map.js";
-export { NoResultError, type Executor } from "@typesql/core";
+export { NoResultError, type Executor, type TransactionalSql } from "@typesql/core";
 export type { PgInterval, PgParamTypeMap, PgTypeMap } from "./type-map.js";
-export { query, one, maybeOne, many, execute, executor, transaction, migrate, type MigrationSource, RowCountError, type PgQueryable, type PgResult, type PgTransactionClient, type PgPoolLike, } from "./client.js";
+export { executor, migrate, type MigrationSource, type PgQueryable, type PgResult, type PgTransactionClient, type PgPoolLike, } from "./client.js";
+/** What `createSql<DB>(client)` returns: core's `Sql` under `PgTypeMap`, with `transaction(fn)`. */
+export type PgSql<DB, Keys extends RowKeys = "preserve"> = TransactionalSql<DB, PgTypeMap, Keys>;
 /**
  * `createSql<DB>()` from core, pre-bound to `PgTypeMap` (`count(*)` is `string`, `int8` is `string`, dates are `Date`).
- * With a `client` (a `Pool`, `Client` or `PoolClient`), the queries' `execute*` methods run on it.
+ * The queries' `execute*` methods run on `client` (a `Pool`, `Client` or `PoolClient`), and
+ * `sql.transaction(fn)` runs `fn` with a `sql` bound to one transaction.
  * `{ rowKeys: "camelCase" }` camelCases the rows' keys, in the types and at runtime.
  */
 export declare function createSql<DB>(client: PgQueryable | undefined, options: {
     readonly rowKeys: "camelCase";
-}): Sql<DB, PgTypeMap, "camelCase">;
+}): PgSql<DB, "camelCase">;
 export declare function createSql<DB>(client?: PgQueryable, options?: {
     readonly rowKeys?: "preserve";
-}): Sql<DB, PgTypeMap>;
+}): PgSql<DB>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,GAAG,EAAmB,MAAM,eAAe,CAAC;AACpG,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EACL,KAAK,EACL,GAAG,EACH,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,WAAW,EACX,OAAO,EACP,KAAK,eAAe,EACpB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAC5I,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC7G,OAAO,EAAU,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpF,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EACL,QAAQ,EACR,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB,oGAAoG;AACpG,MAAM,MAAM,KAAK,CAAC,EAAE,EAAE,IAAI,SAAS,OAAO,GAAG,UAAU,IAAI,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AAEjG;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,KAAK,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;AACnI,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC"}

package/dist/index.js

@@ -1,8 +1,8 @@
-import { createSql as createCoreSql } from "@typesql/core";
-import { executor } from "./client.js";
+import { createTransactionalSql } from "@typesql/core";
+import { driver } from "./client.js";
 export { NoResultError } from "@typesql/core";
-export { query, one, maybeOne, many, execute, executor, transaction, migrate, RowCountError, } from "./client.js";
+export { executor, migrate, } from "./client.js";
 export function createSql(client, options) {
-    return createCoreSql(client && executor(client), options);
+    return createTransactionalSql(client, driver, options);
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,aAAa,EAA2C,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,QAAQ,EAAoB,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,aAAa,EAAiB,MAAM,eAAe,CAAC;AAE7D,OAAO,EACL,KAAK,EACL,GAAG,EACH,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,WAAW,EACX,OAAO,EAEP,aAAa,GAKd,MAAM,aAAa,CAAC;AASrB,MAAM,UAAU,SAAS,CAAK,MAAoB,EAAE,OAAoB;IACtE,OAAO,aAAa,CAAgB,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,OAA4C,CAAC,CAAC;AAChH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAwD,MAAM,eAAe,CAAC;AAC7G,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,aAAa,EAAwC,MAAM,eAAe,CAAC;AAEpF,OAAO,EACL,QAAQ,EACR,OAAO,GAMR,MAAM,aAAa,CAAC;AAarB,MAAM,UAAU,SAAS,CAAK,MAAoB,EAAE,OAAoB;IACtE,OAAO,sBAAsB,CAA6B,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACrF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesql/pg",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "node-postgres (pg) adapter for typesql, with `typesql introspect` to generate a schema from a live database.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@typesql/core": "0.0.4"
+    "@typesql/core": "0.1.0"
   },
   "peerDependencies": {
     "pg": ">=8"

package/src/client.ts

@@ -1,6 +1,6 @@
-import { mapRows, type Executor, type Query, type RowType } from "@typesql/core";
+import { runTransaction, type Executor, type SqlDriver } from "@typesql/core";
 
-/** The subset of a `pg` query result the helpers rely on. */
+/** The subset of a `pg` query result the adapter relies on. */
 export interface PgResult {
   readonly rows: unknown[];
   readonly rowCount: number | null;
@@ -24,102 +24,64 @@ export interface PgPoolLike<C extends PgTransactionClient = PgTransactionClient>
   connect(): Promise<C>;
 }
 
-/** Thrown by `one`, `maybeOne` and `many` when the row count does not match. */
-export class RowCountError extends Error {
-  override readonly name = "RowCountError";
-  constructor(
-    readonly code: "NO_ROWS" | "TOO_MANY_ROWS",
-    readonly expected: string,
-    readonly actual: number,
-    readonly text: string,
-  ) {
-    super(`Expected ${expected} row(s) but the query returned ${actual}`);
-  }
-}
-
-type AnyQuery = Query<unknown, readonly unknown[]>;
-
-function run(client: PgQueryable, q: AnyQuery): Promise<PgResult> {
-  // `pg` requires a mutable array (`QueryConfigValues<I>` matches `Array<U>` only).
-  return client.query(q.text, Array.from(q.values));
-}
-
 /**
  * An `Executor` for core's `q.execute()`: runs queries on `client` and resolves to
  * `{ rows, rowCount }` (pg's `rowCount`, so `q.executeCount()` works).
  */
 export function executor(client: PgQueryable): Executor {
   return async (text, values) => {
+    // `pg` requires a mutable array (`QueryConfigValues<I>` matches `Array<U>` only).
     const { rows, rowCount } = await client.query(text, Array.from(values));
     return { rows, rowCount };
   };
 }
 
-/** Run a query and return all rows, typed from the query. */
-export async function query<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q>[]> {
-  const result = await run(client, q);
-  return mapRows(q, result.rows);
-}
-
-/** Exactly one row, otherwise throws `RowCountError`. */
-export async function one<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q>> {
-  const rows = await query(client, q);
-  if (rows.length !== 1) {
-    throw new RowCountError(rows.length === 0 ? "NO_ROWS" : "TOO_MANY_ROWS", "exactly 1", rows.length, q.text);
-  }
-  return rows[0] as RowType<Q>;
-}
-
-/** Zero or one row (`null` for zero); throws `RowCountError` on more than one. */
-export async function maybeOne<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<RowType<Q> | null> {
-  const rows = await query(client, q);
-  if (rows.length > 1) throw new RowCountError("TOO_MANY_ROWS", "at most 1", rows.length, q.text);
-  return rows.length === 0 ? null : (rows[0] as RowType<Q>);
+function isPool(client: PgQueryable): client is PgQueryable & PgPoolLike {
+  // `pg.Client` has `connect()` too (it opens the socket), and `processID`; a `PoolClient` has `release()`.
+  return typeof (client as Partial<PgPoolLike>).connect === "function" && !("release" in client) && !("processID" in client);
 }
 
-/** At least one row, otherwise throws `RowCountError`. */
-export async function many<Q extends AnyQuery>(client: PgQueryable, q: Q): Promise<[RowType<Q>, ...RowType<Q>[]]> {
-  const rows = await query(client, q);
-  if (rows.length === 0) throw new RowCountError("NO_ROWS", "at least 1", 0, q.text);
-  return rows as [RowType<Q>, ...RowType<Q>[]];
+function isConnection(client: PgQueryable): boolean {
+  return "release" in client || "processID" in client;
 }
 
-/** Run a statement for its side effect and return the affected row count (`rowCount ?? 0`). */
-export async function execute(client: PgQueryable, q: AnyQuery): Promise<number> {
-  const result = await run(client, q);
-  return result.rowCount ?? 0;
-}
+const on = (c: PgQueryable) => (statement: string) => c.query(statement);
 
 /**
- * Check out a client, run `fn` inside BEGIN/COMMIT, ROLLBACK on error, and release the
- * client. If ROLLBACK itself fails the client is released with the error so the pool
- * discards the connection instead of reusing it.
+ * Check out a client, run `fn` with it between `BEGIN` and `COMMIT`, and release it, with the
+ * error when `ROLLBACK` fails so the pool discards the connection instead of reusing it.
  */
-export async function transaction<C extends PgTransactionClient, T>(
-  pool: PgPoolLike<C>,
-  fn: (client: C) => Promise<T>,
-): Promise<T> {
-  const client = await pool.connect();
+async function inPoolTransaction<C extends PgTransactionClient, T>(pool: PgPoolLike<C>, fn: (conn: C) => Promise<T>): Promise<T> {
+  const conn = await pool.connect();
   let releaseWith: Error | undefined;
   try {
-    await client.query("BEGIN");
-    try {
-      const result = await fn(client);
-      await client.query("COMMIT");
-      return result;
-    } catch (err) {
-      try {
-        await client.query("ROLLBACK");
-      } catch (rollbackErr) {
-        releaseWith = rollbackErr instanceof Error ? rollbackErr : new Error(String(rollbackErr));
-      }
-      throw err;
-    }
+    return await runTransaction(on(conn), () => fn(conn), {
+      onRollbackError: (err) => {
+        releaseWith = err instanceof Error ? err : new Error(String(err));
+      },
+    });
   } finally {
-    client.release(releaseWith);
+    conn.release(releaseWith);
   }
 }
 
+/**
+ * Run `fn` inside a transaction: on a pool, on a client checked out of it; on a `Client` or
+ * `PoolClient`, on that connection. With `depth > 0` the client is already in a transaction,
+ * and `fn` runs in a savepoint.
+ */
+function transaction<T>(client: PgQueryable, depth: number, fn: (tx: PgQueryable) => Promise<T>): Promise<T> {
+  if (depth > 0) return runTransaction(on(client), () => fn(client), { savepoint: `typesql_${depth}` });
+  if (isPool(client)) return inPoolTransaction(client, fn);
+  if (!isConnection(client)) {
+    return Promise.reject(new Error("typesql: sql.transaction() needs a pg Pool, Client or PoolClient, so that BEGIN and COMMIT reach one connection"));
+  }
+  return runTransaction(on(client), () => fn(client));
+}
+
+/** How `createSql(client)` runs queries and transactions. */
+export const driver: SqlDriver<PgQueryable> = { executor, transaction };
+
 /** Anything carrying an ordered list of DDL statements, e.g. a `migrations()` builder from core. */
 export interface MigrationSource {
   readonly statements: readonly string[];
@@ -131,7 +93,7 @@ export interface MigrationSource {
  * with `$$`-quoted function bodies work.
  */
 export async function migrate<C extends PgTransactionClient>(pool: PgPoolLike<C>, m: MigrationSource): Promise<void> {
-  await transaction(pool, async (client) => {
+  await inPoolTransaction(pool, async (client) => {
     for (const statement of m.statements) await client.query(statement);
   });
 }

package/src/index.ts

@@ -1,33 +1,30 @@
-import { createSql as createCoreSql, type RowKeys, type Sql, type SqlOptions } from "@typesql/core";
-import { executor, type PgQueryable } from "./client.js";
+import { createTransactionalSql, type RowKeys, type SqlOptions, type TransactionalSql } from "@typesql/core";
+import { driver, type PgQueryable } from "./client.js";
 import type { PgTypeMap } from "./type-map.js";
 
-export { NoResultError, type Executor } from "@typesql/core";
+export { NoResultError, type Executor, type TransactionalSql } from "@typesql/core";
 export type { PgInterval, PgParamTypeMap, PgTypeMap } from "./type-map.js";
 export {
-  query,
-  one,
-  maybeOne,
-  many,
-  execute,
   executor,
-  transaction,
   migrate,
   type MigrationSource,
-  RowCountError,
   type PgQueryable,
   type PgResult,
   type PgTransactionClient,
   type PgPoolLike,
 } from "./client.js";
 
+/** What `createSql<DB>(client)` returns: core's `Sql` under `PgTypeMap`, with `transaction(fn)`. */
+export type PgSql<DB, Keys extends RowKeys = "preserve"> = TransactionalSql<DB, PgTypeMap, Keys>;
+
 /**
  * `createSql<DB>()` from core, pre-bound to `PgTypeMap` (`count(*)` is `string`, `int8` is `string`, dates are `Date`).
- * With a `client` (a `Pool`, `Client` or `PoolClient`), the queries' `execute*` methods run on it.
+ * The queries' `execute*` methods run on `client` (a `Pool`, `Client` or `PoolClient`), and
+ * `sql.transaction(fn)` runs `fn` with a `sql` bound to one transaction.
  * `{ rowKeys: "camelCase" }` camelCases the rows' keys, in the types and at runtime.
  */
-export function createSql<DB>(client: PgQueryable | undefined, options: { readonly rowKeys: "camelCase" }): Sql<DB, PgTypeMap, "camelCase">;
-export function createSql<DB>(client?: PgQueryable, options?: { readonly rowKeys?: "preserve" }): Sql<DB, PgTypeMap>;
-export function createSql<DB>(client?: PgQueryable, options?: SqlOptions): Sql<DB, PgTypeMap, RowKeys> {
-  return createCoreSql<DB, PgTypeMap>(client && executor(client), options as { readonly rowKeys: "camelCase" });
+export function createSql<DB>(client: PgQueryable | undefined, options: { readonly rowKeys: "camelCase" }): PgSql<DB, "camelCase">;
+export function createSql<DB>(client?: PgQueryable, options?: { readonly rowKeys?: "preserve" }): PgSql<DB>;
+export function createSql<DB>(client?: PgQueryable, options?: SqlOptions): PgSql<DB, RowKeys> {
+  return createTransactionalSql<DB, PgTypeMap, PgQueryable>(client, driver, options);
 }