@typesql/postgres 0.0.4 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @typesql/postgres
 
+## 0.1.1
+
+### Patch Changes
+
+- Docs, package descriptions and error messages spell the project name TypeSQL.
+
+- Updated dependencies:
+  - @typesql/core@0.1.1
+
+## 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,8 @@
 
 [postgres.js](https://github.com/porsager/postgres) (`postgres` 3.x) adapter for
 [`@typesql/core`](https://www.npmjs.com/package/@typesql/core): a `createSql` bound to the type
-map of postgres.js' default parsers, and helpers that run a query and return rows typed from it.
+map of postgres.js' default parsers, whose queries run on your `sql` instance and return rows
+typed from the SQL.
 
 ```sh
 pnpm add @typesql/core @typesql/postgres postgres
@@ -12,29 +13,29 @@ pnpm add @typesql/core @typesql/postgres postgres
 
 ```ts
 import postgres from "postgres";
-import { createSql, execute, query, transaction } from "@typesql/postgres";
+import { createSql } from "@typesql/postgres";
 import type { DB } from "./schema";
 
 const db = postgres(process.env.DATABASE_URL!);
-const sql = createSql<DB>(); // PostgresJsTypeMap
+const sql = createSql<DB>(db); // PostgresJsTypeMap
 
-const posts = await query(db, sql("SELECT id, title FROM posts WHERE author_id = $1", 1));
+const posts = await sql("SELECT id, title FROM posts WHERE author_id = $1", 1).execute();
 // { id: string; title: string }[]   int8 is a string by default
 
-await transaction(db, async (tx) => {
-  await execute(tx, sql("UPDATE posts SET title = upper(title) WHERE author_id = $1", 1));
+await sql.transaction(async (tx) => {
+  await tx("UPDATE posts SET title = upper(title) WHERE author_id = $1", 1).execute();
 });
 ```
 
 With bigint parsing enabled on the connection, use `createBigIntSql`:
 
 ```ts
-import { createBigIntSql, query } from "@typesql/postgres";
+import { createBigIntSql } from "@typesql/postgres";
 
 const dbBig = postgres(process.env.DATABASE_URL!, { types: { bigint: postgres.BigInt } });
-const big = createBigIntSql<DB>(); // PostgresJsBigIntTypeMap
+const big = createBigIntSql<DB>(dbBig); // PostgresJsBigIntTypeMap
 
-const counts = await query(dbBig, big("SELECT author_id, count(*) AS n FROM posts GROUP BY author_id"));
+const counts = await big("SELECT author_id, count(*) AS n FROM posts GROUP BY author_id").execute();
 // { author_id: number; n: bigint }[]
 ```
 
@@ -42,18 +43,15 @@ const counts = await query(dbBig, big("SELECT author_id, count(*) AS n FROM post
 
 | Export | |
 |---|---|
-| `createSql<DB>(db?, options?)` | core's `createSql<DB, PostgresJsTypeMap>()`; `{ rowKeys: "camelCase" }` camelCases the row keys |
-| `createBigIntSql<DB>(db?, options?)` | core's `createSql<DB, PostgresJsBigIntTypeMap>()`, for `types: { bigint: postgres.BigInt }` |
-| `query(db, q)` | `Promise<Row[]>` (a plain array, result metadata stripped) |
-| `one(db, q)` | `Promise<Row>`; `RowCountError` unless exactly one row |
-| `maybeOne(db, q)` | `Promise<Row \| null>`; `RowCountError` on more than one row |
-| `many(db, q)` | `Promise<[Row, ...Row[]]>`; `RowCountError` on zero rows |
-| `execute(db, q)` | `Promise<number>`, the affected row count (0 for DDL) |
-| `executor(db)` | an `Executor` for `q.execute()` and `q.executeCount()` (reports `.count`); `createSql<DB>(db)` binds one |
-| `transaction(db, fn)` | `db.begin(fn)` |
+| `createSql<DB>(db, options?)` | core's `createSql<DB, PostgresJsTypeMap>()` with the queries running on `db`; `{ rowKeys: "camelCase" }` camelCases the row keys |
+| `createBigIntSql<DB>(db, options?)` | the same with `PostgresJsBigIntTypeMap`, for `types: { bigint: postgres.BigInt }` |
+| `q.execute()`, `q.executeTakeFirst()`, `q.executeTakeFirstOrThrow()`, `q.executeCount()` | `Promise<Row[]>` (a plain array, result metadata stripped), `Promise<Row \| undefined>`, `Promise<Row>` (`NoResultError` on 0 rows), `Promise<number>` (`.count`, 0 for DDL) |
+| `sql.transaction(fn)` | `db.begin(fn)` with `tx` bound to the transaction; `tx.transaction(fn)` is `savepoint(fn)` |
+| `executor(db)` | an `Executor` for `q.execute(executor)` and core's `createSql(executor)` (reports `.count`) |
 | `migrate(db, m)` | runs `m.statements` (e.g. from core's `migrations()`) in one transaction |
+| `PostgresJsSql<DB, Keys>`, `PostgresJsBigIntSql<DB, Keys>` | the types `createSql` and `createBigIntSql` return |
 | `PostgresJsTypeMap`, `PostgresJsBigIntTypeMap`, `PostgresJsParamTypeMap` | the type maps (rows), and what parameters also accept |
-| `RowCountError`, `PostgresJsQueryable`, `PostgresJsTransactable`, `PostgresJsRows`, `MigrationSource` | errors and parameter types |
+| `NoResultError`, `PostgresJsQueryable`, `PostgresJsTransactable`, `PostgresJsRows`, `MigrationSource` | errors and parameter types |
 
 Queries run with `db.unsafe(text, values)`, so the text reaches the server unchanged and values
 are bind parameters. `db` is the `Sql` instance, a `TransactionSql` or a `ReservedSql`.
@@ -73,7 +71,7 @@ postgres.js parses only a few types by default; everything else is the text Post
 | `numeric`, `interval`, `point`, text-like and other types | `string` | `string` |
 
 Arrays map element-wise. Details in the
-[Adapters guide](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/guide/adapters.md).
+[postgres.js adapter page](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/adapters/postgres.md).
 
 Parameters accept the row type and what postgres.js serializes for the type
 (`PostgresJsParamTypeMap`): `number | bigint | string` for `int8`, `numeric` and `money`,

package/dist/client.d.ts

@@ -1,6 +1,6 @@
-import { type Executor, type Query, type RowType } from "@typesql/core";
+import type { Executor, SqlDriver } from "@typesql/core";
 /**
- * The shape of a resolved `sql.unsafe()` result the helpers rely on: an array with `count`
+ * The shape of a resolved `sql.unsafe()` result the adapter relies on: an array with `count`
  * (`null` for statements without a count, such as DDL).
  */
 export type PostgresJsRows = readonly unknown[] & {
@@ -17,36 +17,13 @@ export interface PostgresJsQueryable {
 export interface PostgresJsTransactable<Tx extends PostgresJsQueryable = PostgresJsQueryable> {
     begin(fn: (tx: Tx) => Promise<unknown>): Promise<unknown>;
 }
-/** 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 through `sql.unsafe` and resolves to
  * `{ rows, rowCount }` (postgres.js' `.count`, so `q.executeCount()` works).
  */
 export declare function executor(sql: PostgresJsQueryable): Executor;
-/** Run a query and return all rows (a plain array, without postgres.js' result metadata). */
-export declare function query<Q extends AnyQuery>(sql: PostgresJsQueryable, q: Q): Promise<RowType<Q>[]>;
-/** Exactly one row, otherwise throws `RowCountError`. */
-export declare function one<Q extends AnyQuery>(sql: PostgresJsQueryable, 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>(sql: PostgresJsQueryable, q: Q): Promise<RowType<Q> | null>;
-/** At least one row, otherwise throws `RowCountError`. */
-export declare function many<Q extends AnyQuery>(sql: PostgresJsQueryable, q: Q): Promise<[RowType<Q>, ...RowType<Q>[]]>;
-/** Run a statement for its side effect and return the affected row count (postgres.js' `.count`, 0 when it is `null`). */
-export declare function execute(sql: PostgresJsQueryable, q: AnyQuery): Promise<number>;
-/**
- * Run `fn` inside `sql.begin()`: postgres.js issues BEGIN, runs the callback with a
- * transaction-bound `sql`, then COMMIT — or ROLLBACK and rethrow if the callback throws.
- */
-export declare function transaction<Tx extends PostgresJsQueryable, T>(sql: PostgresJsTransactable<Tx>, fn: (tx: Tx) => Promise<T>): Promise<T>;
+/** How `createSql(sql)` runs queries and transactions. */
+export declare const driver: SqlDriver<PostgresJsQueryable>;
 /** Anything carrying an ordered list of DDL statements, e.g. a `migrations()` builder from core. */
 export interface MigrationSource {
     readonly statements: readonly string[];
@@ -57,5 +34,4 @@ export interface MigrationSource {
  * `$$`-quoted function bodies work.
  */
 export declare function migrate<Tx extends PostgresJsQueryable>(sql: PostgresJsTransactable<Tx>, 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,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,OAAO,EAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEpF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;CAC5E;AAED,qFAAqF;AACrF,MAAM,WAAW,sBAAsB,CAAC,EAAE,SAAS,mBAAmB,GAAG,mBAAmB;IAC1F,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAOD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,mBAAmB,GAAG,QAAQ,CAK3D;AAcD,0DAA0D;AAC1D,eAAO,MAAM,MAAM,EAAE,SAAS,CAAC,mBAAmB,CAA6B,CAAC;AAEhF,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,GAAG,EAAE,sBAAsB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhI"}

package/dist/client.js

@@ -1,22 +1,3 @@
-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(sql, q) {
-    return sql.unsafe(q.text, Array.from(q.values));
-}
 /**
  * An `Executor` for core's `q.execute()`: runs queries through `sql.unsafe` and resolves to
  * `{ rows, rowCount }` (postgres.js' `.count`, so `q.executeCount()` works).
@@ -27,52 +8,28 @@ export function executor(sql) {
         return { rows: Array.from(result), rowCount: result.count ?? null };
     };
 }
-/** Run a query and return all rows (a plain array, without postgres.js' result metadata). */
-export async function query(sql, q) {
-    const result = await run(sql, q);
-    return mapRows(q, Array.from(result));
-}
-/** Exactly one row, otherwise throws `RowCountError`. */
-export async function one(sql, q) {
-    const rows = await query(sql, 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(sql, q) {
-    const rows = await query(sql, 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];
-}
-/** At least one row, otherwise throws `RowCountError`. */
-export async function many(sql, q) {
-    const rows = await query(sql, 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 (postgres.js' `.count`, 0 when it is `null`). */
-export async function execute(sql, q) {
-    const result = await run(sql, q);
-    return result.count ?? 0;
-}
 /**
- * Run `fn` inside `sql.begin()`: postgres.js issues BEGIN, runs the callback with a
- * transaction-bound `sql`, then COMMIT — or ROLLBACK and rethrow if the callback throws.
+ * Run `fn` inside a transaction: `tx.savepoint(fn)` on a `TransactionSql` (only those have it),
+ * otherwise `sql.begin(fn)`. postgres.js issues BEGIN (or SAVEPOINT), runs the callback with a
+ * transaction-bound `sql`, then COMMIT, or ROLLBACK and rethrow when the callback throws.
  */
-export async function transaction(sql, fn) {
-    return (await sql.begin(fn));
-}
+async function transaction(sql, _depth, fn) {
+    const { savepoint, begin } = sql;
+    if (savepoint)
+        return (await savepoint.call(sql, fn));
+    if (begin)
+        return (await begin.call(sql, fn));
+    throw new Error("typesql: sql.transaction() needs a postgres.js Sql, ReservedSql or TransactionSql (with begin or savepoint)");
+}
+/** How `createSql(sql)` runs queries and transactions. */
+export const driver = { executor, transaction };
 /**
  * Run a migration's statements in order inside one transaction (`sql.begin`), all or nothing.
  * Each statement goes through `unsafe` without parameters (simple protocol), so scripts with
  * `$$`-quoted function bodies work.
  */
 export async function migrate(sql, m) {
-    await transaction(sql, async (tx) => {
+    await sql.begin(async (tx) => {
         for (const statement of m.statements)
             await tx.unsafe(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":"AA0BA;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAwB;IAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC5B,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;IACtE,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CAAI,GAAwB,EAAE,MAAc,EAAE,EAA2C;IACjH,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,GAAgE,CAAC;IAC9F,IAAI,SAAS;QAAE,OAAO,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAM,CAAC;IAC3D,IAAI,KAAK;QAAE,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAM,CAAC;IACnD,MAAM,IAAI,KAAK,CAAC,6GAA6G,CAAC,CAAC;AACjI,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,MAAM,MAAM,GAAmC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AAOhF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAiC,GAA+B,EAAE,CAAkB;IAC/G,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QAC3B,KAAK,MAAM,SAAS,IAAI,CAAC,CAAC,UAAU;YAAE,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -1,25 +1,30 @@
-import { type Sql } from "@typesql/core";
+import { type RowKeys, type TransactionalSql } from "@typesql/core";
 import { type PostgresJsQueryable } from "./client.js";
 import type { PostgresJsBigIntTypeMap, PostgresJsTypeMap } from "./type-map.js";
-export { NoResultError, type Executor } from "@typesql/core";
+export { NoResultError, type Executor, type TransactionalSql } from "@typesql/core";
 export type { PostgresJsTypeMap, PostgresJsBigIntTypeMap, PostgresJsParamTypeMap } from "./type-map.js";
-export { query, one, maybeOne, many, execute, executor, transaction, migrate, type MigrationSource, RowCountError, type PostgresJsQueryable, type PostgresJsRows, type PostgresJsTransactable, } from "./client.js";
+export { executor, migrate, type MigrationSource, type PostgresJsQueryable, type PostgresJsRows, type PostgresJsTransactable, } from "./client.js";
+/** What `createSql<DB>(sql)` returns: core's `Sql` under `PostgresJsTypeMap`, with `transaction(fn)`. */
+export type PostgresJsSql<DB, Keys extends RowKeys = "preserve"> = TransactionalSql<DB, PostgresJsTypeMap, Keys>;
+/** What `createBigIntSql<DB>(sql)` returns: core's `Sql` under `PostgresJsBigIntTypeMap`, with `transaction(fn)`. */
+export type PostgresJsBigIntSql<DB, Keys extends RowKeys = "preserve"> = TransactionalSql<DB, PostgresJsBigIntTypeMap, Keys>;
 /**
  * `createSql<DB>()` from core, pre-bound to `PostgresJsTypeMap` (default parsers: `int8` and `count(*)` are `string`).
- * With a postgres.js `sql` instance, the queries' `execute*` methods run on it.
+ * The queries' `execute*` methods run on the postgres.js `sql` instance (or a `TransactionSql`,
+ * `ReservedSql`), 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>(sql: PostgresJsQueryable | undefined, options: {
     readonly rowKeys: "camelCase";
-}): Sql<DB, PostgresJsTypeMap, "camelCase">;
+}): PostgresJsSql<DB, "camelCase">;
 export declare function createSql<DB>(sql?: PostgresJsQueryable, options?: {
     readonly rowKeys?: "preserve";
-}): Sql<DB, PostgresJsTypeMap>;
+}): PostgresJsSql<DB>;
 /** For `postgres({ types: { bigint: postgres.BigInt } })` connections: `int8` and `count(*)` are `bigint`. */
 export declare function createBigIntSql<DB>(sql: PostgresJsQueryable | undefined, options: {
     readonly rowKeys: "camelCase";
-}): Sql<DB, PostgresJsBigIntTypeMap, "camelCase">;
+}): PostgresJsBigIntSql<DB, "camelCase">;
 export declare function createBigIntSql<DB>(sql?: PostgresJsQueryable, options?: {
     readonly rowKeys?: "preserve";
-}): Sql<DB, PostgresJsBigIntTypeMap>;
+}): PostgresJsBigIntSql<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,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EACL,KAAK,EACL,GAAG,EACH,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,WAAW,EACX,OAAO,EACP,KAAK,eAAe,EACpB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,mBAAmB,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,GAAG,CAAC,EAAE,EAAE,iBAAiB,EAAE,WAAW,CAAC,CAAC;AACzJ,wBAAgB,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,GAAG,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAC;AAKlI,8GAA8G;AAC9G,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,mBAAmB,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,GAAG,CAAC,EAAE,EAAE,uBAAuB,EAAE,WAAW,CAAC,CAAC;AACrK,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,GAAG,CAAC,EAAE,EAAE,uBAAuB,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,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpF,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EACL,QAAQ,EACR,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AAErB,yGAAyG;AACzG,MAAM,MAAM,aAAa,CAAC,EAAE,EAAE,IAAI,SAAS,OAAO,GAAG,UAAU,IAAI,gBAAgB,CAAC,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;AACjH,qHAAqH;AACrH,MAAM,MAAM,mBAAmB,CAAC,EAAE,EAAE,IAAI,SAAS,OAAO,GAAG,UAAU,IAAI,gBAAgB,CAAC,EAAE,EAAE,uBAAuB,EAAE,IAAI,CAAC,CAAC;AAE7H;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,mBAAmB,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,aAAa,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;AAChJ,wBAAgB,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;AAKzH,8GAA8G;AAC9G,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,mBAAmB,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,mBAAmB,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;AAC5J,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAC"}

package/dist/index.js

@@ -1,11 +1,11 @@
-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(sql, options) {
-    return createCoreSql(sql && executor(sql), options);
+    return createTransactionalSql(sql, driver, options);
 }
 export function createBigIntSql(sql, options) {
-    return createCoreSql(sql && executor(sql), options);
+    return createTransactionalSql(sql, 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,EAA4B,MAAM,aAAa,CAAC;AAGjE,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,GAId,MAAM,aAAa,CAAC;AASrB,MAAM,UAAU,SAAS,CAAK,GAAyB,EAAE,OAAoB;IAC3E,OAAO,aAAa,CAAwB,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,OAA4C,CAAC,CAAC;AAClH,CAAC;AAKD,MAAM,UAAU,eAAe,CAAK,GAAyB,EAAE,OAAoB;IACjF,OAAO,aAAa,CAA8B,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,OAA4C,CAAC,CAAC;AACxH,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,EAA4B,MAAM,aAAa,CAAC;AAG/D,OAAO,EAAE,aAAa,EAAwC,MAAM,eAAe,CAAC;AAEpF,OAAO,EACL,QAAQ,EACR,OAAO,GAKR,MAAM,aAAa,CAAC;AAerB,MAAM,UAAU,SAAS,CAAK,GAAyB,EAAE,OAAoB;IAC3E,OAAO,sBAAsB,CAA6C,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAClG,CAAC;AAKD,MAAM,UAAU,eAAe,CAAK,GAAyB,EAAE,OAAoB;IACjF,OAAO,sBAAsB,CAAmD,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACxG,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@typesql/postgres",
-  "version": "0.0.4",
-  "description": "postgres.js adapter for typesql.",
+  "version": "0.1.1",
+  "description": "postgres.js adapter for TypeSQL.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@typesql/core": "0.0.4"
+    "@typesql/core": "0.1.1"
   },
   "peerDependencies": {
     "postgres": ">=3"

package/src/client.ts

@@ -1,7 +1,7 @@
-import { mapRows, type Executor, type Query, type RowType } from "@typesql/core";
+import type { Executor, SqlDriver } from "@typesql/core";
 
 /**
- * The shape of a resolved `sql.unsafe()` result the helpers rely on: an array with `count`
+ * The shape of a resolved `sql.unsafe()` result the adapter relies on: an array with `count`
  * (`null` for statements without a count, such as DDL).
  */
 export type PostgresJsRows = readonly unknown[] & { readonly count: number | null };
@@ -19,23 +19,9 @@ export interface PostgresJsTransactable<Tx extends PostgresJsQueryable = Postgre
   begin(fn: (tx: Tx) => Promise<unknown>): Promise<unknown>;
 }
 
-/** 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(sql: PostgresJsQueryable, q: AnyQuery): PromiseLike<PostgresJsRows> {
-  return sql.unsafe(q.text, Array.from(q.values));
+/** A `TransactionSql`'s `savepoint(fn)`. */
+interface PostgresJsSavepointable {
+  savepoint(fn: (tx: PostgresJsQueryable) => Promise<unknown>): Promise<unknown>;
 }
 
 /**
@@ -49,52 +35,21 @@ export function executor(sql: PostgresJsQueryable): Executor {
   };
 }
 
-/** Run a query and return all rows (a plain array, without postgres.js' result metadata). */
-export async function query<Q extends AnyQuery>(sql: PostgresJsQueryable, q: Q): Promise<RowType<Q>[]> {
-  const result = await run(sql, q);
-  return mapRows(q, Array.from(result));
-}
-
-/** Exactly one row, otherwise throws `RowCountError`. */
-export async function one<Q extends AnyQuery>(sql: PostgresJsQueryable, q: Q): Promise<RowType<Q>> {
-  const rows = await query(sql, 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>(sql: PostgresJsQueryable, q: Q): Promise<RowType<Q> | null> {
-  const rows = await query(sql, 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>);
-}
-
-/** At least one row, otherwise throws `RowCountError`. */
-export async function many<Q extends AnyQuery>(sql: PostgresJsQueryable, q: Q): Promise<[RowType<Q>, ...RowType<Q>[]]> {
-  const rows = await query(sql, q);
-  if (rows.length === 0) throw new RowCountError("NO_ROWS", "at least 1", 0, q.text);
-  return rows as [RowType<Q>, ...RowType<Q>[]];
-}
-
-/** Run a statement for its side effect and return the affected row count (postgres.js' `.count`, 0 when it is `null`). */
-export async function execute(sql: PostgresJsQueryable, q: AnyQuery): Promise<number> {
-  const result = await run(sql, q);
-  return result.count ?? 0;
-}
-
 /**
- * Run `fn` inside `sql.begin()`: postgres.js issues BEGIN, runs the callback with a
- * transaction-bound `sql`, then COMMIT — or ROLLBACK and rethrow if the callback throws.
+ * Run `fn` inside a transaction: `tx.savepoint(fn)` on a `TransactionSql` (only those have it),
+ * otherwise `sql.begin(fn)`. postgres.js issues BEGIN (or SAVEPOINT), runs the callback with a
+ * transaction-bound `sql`, then COMMIT, or ROLLBACK and rethrow when the callback throws.
  */
-export async function transaction<Tx extends PostgresJsQueryable, T>(
-  sql: PostgresJsTransactable<Tx>,
-  fn: (tx: Tx) => Promise<T>,
-): Promise<T> {
-  return (await sql.begin(fn)) as T;
+async function transaction<T>(sql: PostgresJsQueryable, _depth: number, fn: (tx: PostgresJsQueryable) => Promise<T>): Promise<T> {
+  const { savepoint, begin } = sql as Partial<PostgresJsSavepointable & PostgresJsTransactable>;
+  if (savepoint) return (await savepoint.call(sql, fn)) as T;
+  if (begin) return (await begin.call(sql, fn)) as T;
+  throw new Error("typesql: sql.transaction() needs a postgres.js Sql, ReservedSql or TransactionSql (with begin or savepoint)");
 }
 
+/** How `createSql(sql)` runs queries and transactions. */
+export const driver: SqlDriver<PostgresJsQueryable> = { executor, transaction };
+
 /** Anything carrying an ordered list of DDL statements, e.g. a `migrations()` builder from core. */
 export interface MigrationSource {
   readonly statements: readonly string[];
@@ -106,7 +61,7 @@ export interface MigrationSource {
  * `$$`-quoted function bodies work.
  */
 export async function migrate<Tx extends PostgresJsQueryable>(sql: PostgresJsTransactable<Tx>, m: MigrationSource): Promise<void> {
-  await transaction(sql, async (tx) => {
+  await sql.begin(async (tx) => {
     for (const statement of m.statements) await tx.unsafe(statement);
   });
 }

package/src/index.ts

@@ -1,39 +1,38 @@
-import { createSql as createCoreSql, type RowKeys, type Sql, type SqlOptions } from "@typesql/core";
-import { executor, type PostgresJsQueryable } from "./client.js";
+import { createTransactionalSql, type RowKeys, type SqlOptions, type TransactionalSql } from "@typesql/core";
+import { driver, type PostgresJsQueryable } from "./client.js";
 import type { PostgresJsBigIntTypeMap, PostgresJsTypeMap } from "./type-map.js";
 
-export { NoResultError, type Executor } from "@typesql/core";
+export { NoResultError, type Executor, type TransactionalSql } from "@typesql/core";
 export type { PostgresJsTypeMap, PostgresJsBigIntTypeMap, PostgresJsParamTypeMap } from "./type-map.js";
 export {
-  query,
-  one,
-  maybeOne,
-  many,
-  execute,
   executor,
-  transaction,
   migrate,
   type MigrationSource,
-  RowCountError,
   type PostgresJsQueryable,
   type PostgresJsRows,
   type PostgresJsTransactable,
 } from "./client.js";
 
+/** What `createSql<DB>(sql)` returns: core's `Sql` under `PostgresJsTypeMap`, with `transaction(fn)`. */
+export type PostgresJsSql<DB, Keys extends RowKeys = "preserve"> = TransactionalSql<DB, PostgresJsTypeMap, Keys>;
+/** What `createBigIntSql<DB>(sql)` returns: core's `Sql` under `PostgresJsBigIntTypeMap`, with `transaction(fn)`. */
+export type PostgresJsBigIntSql<DB, Keys extends RowKeys = "preserve"> = TransactionalSql<DB, PostgresJsBigIntTypeMap, Keys>;
+
 /**
  * `createSql<DB>()` from core, pre-bound to `PostgresJsTypeMap` (default parsers: `int8` and `count(*)` are `string`).
- * With a postgres.js `sql` instance, the queries' `execute*` methods run on it.
+ * The queries' `execute*` methods run on the postgres.js `sql` instance (or a `TransactionSql`,
+ * `ReservedSql`), 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>(sql: PostgresJsQueryable | undefined, options: { readonly rowKeys: "camelCase" }): Sql<DB, PostgresJsTypeMap, "camelCase">;
-export function createSql<DB>(sql?: PostgresJsQueryable, options?: { readonly rowKeys?: "preserve" }): Sql<DB, PostgresJsTypeMap>;
-export function createSql<DB>(sql?: PostgresJsQueryable, options?: SqlOptions): Sql<DB, PostgresJsTypeMap, RowKeys> {
-  return createCoreSql<DB, PostgresJsTypeMap>(sql && executor(sql), options as { readonly rowKeys: "camelCase" });
+export function createSql<DB>(sql: PostgresJsQueryable | undefined, options: { readonly rowKeys: "camelCase" }): PostgresJsSql<DB, "camelCase">;
+export function createSql<DB>(sql?: PostgresJsQueryable, options?: { readonly rowKeys?: "preserve" }): PostgresJsSql<DB>;
+export function createSql<DB>(sql?: PostgresJsQueryable, options?: SqlOptions): PostgresJsSql<DB, RowKeys> {
+  return createTransactionalSql<DB, PostgresJsTypeMap, PostgresJsQueryable>(sql, driver, options);
 }
 
 /** For `postgres({ types: { bigint: postgres.BigInt } })` connections: `int8` and `count(*)` are `bigint`. */
-export function createBigIntSql<DB>(sql: PostgresJsQueryable | undefined, options: { readonly rowKeys: "camelCase" }): Sql<DB, PostgresJsBigIntTypeMap, "camelCase">;
-export function createBigIntSql<DB>(sql?: PostgresJsQueryable, options?: { readonly rowKeys?: "preserve" }): Sql<DB, PostgresJsBigIntTypeMap>;
-export function createBigIntSql<DB>(sql?: PostgresJsQueryable, options?: SqlOptions): Sql<DB, PostgresJsBigIntTypeMap, RowKeys> {
-  return createCoreSql<DB, PostgresJsBigIntTypeMap>(sql && executor(sql), options as { readonly rowKeys: "camelCase" });
+export function createBigIntSql<DB>(sql: PostgresJsQueryable | undefined, options: { readonly rowKeys: "camelCase" }): PostgresJsBigIntSql<DB, "camelCase">;
+export function createBigIntSql<DB>(sql?: PostgresJsQueryable, options?: { readonly rowKeys?: "preserve" }): PostgresJsBigIntSql<DB>;
+export function createBigIntSql<DB>(sql?: PostgresJsQueryable, options?: SqlOptions): PostgresJsBigIntSql<DB, RowKeys> {
+  return createTransactionalSql<DB, PostgresJsBigIntTypeMap, PostgresJsQueryable>(sql, driver, options);
 }