@typesql/postgres 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @typesql/postgres
 
+## 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
+
+- Queries have `executeCount()`, which resolves to the affected row count: an `Executor` may resolve to `{ rows, rowCount }` instead of the rows, as the `executor()` of `@typesql/pg`, `@typesql/postgres` and `@typesql/kysely` now do.
+
+- `execute(db, q)` resolves to 0 instead of `null` for statements without a count, such as DDL, and `PostgresJsRows["count"]` is `number | null`.
+
+- `createSql(executor, { rowKeys: "camelCase" })` (and the adapters' `createSql(client, { rowKeys: "camelCase" })`) camelCases the top-level row keys the way Kysely's `CamelCasePlugin` does, in the row types and in the rows `execute*` and the `query`/`one`/`maybeOne`/`many` helpers return, leaving JSON values untouched.
+
+- The type maps declare what parameters accept (`PgParamTypeMap`, `PostgresJsParamTypeMap`), so `int8`/`numeric` parameters take numbers and bigints and timestamp parameters take strings; postgres.js timestamp parameters also take epoch milliseconds.
+
+- Updated dependencies:
+  - @typesql/core@0.0.4
+
 ## 0.0.3
 
 ### 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,17 +43,15 @@ const counts = await query(dbBig, big("SELECT author_id, count(*) AS n FROM post
 
 | Export | |
 |---|---|
-| `createSql<DB>()` | core's `createSql<DB, PostgresJsTypeMap>()` |
-| `createBigIntSql<DB>()` | 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 |
-| `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 |
-| `PostgresJsTypeMap`, `PostgresJsBigIntTypeMap` | the type maps |
-| `RowCountError`, `PostgresJsQueryable`, `PostgresJsTransactable`, `PostgresJsRows`, `MigrationSource` | errors and parameter types |
+| `PostgresJsSql<DB, Keys>`, `PostgresJsBigIntSql<DB, Keys>` | the types `createSql` and `createBigIntSql` return |
+| `PostgresJsTypeMap`, `PostgresJsBigIntTypeMap`, `PostgresJsParamTypeMap` | the type maps (rows), and what parameters also accept |
+| `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`.
@@ -72,4 +71,9 @@ 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`,
+`Date | string | number` (epoch ms) for dates and timestamps, `string` for `interval`,
+`Uint8Array` for `bytea`.

package/dist/client.d.ts

@@ -1,7 +1,10 @@
-import type { Executor, Query, RowType } from "@typesql/core";
-/** The shape of a resolved `sql.unsafe()` result the helpers rely on: an array with `count`. */
+import type { Executor, SqlDriver } from "@typesql/core";
+/**
+ * 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;
+    readonly count: number | null;
 };
 /**
  * Anything with postgres.js' `unsafe(query, parameters)` method: the `Sql` instance,
@@ -14,33 +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 the rows. */
-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`). */
-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.
+ * 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 transaction<Tx extends PostgresJsQueryable, T>(sql: PostgresJsTransactable<Tx>, fn: (tx: Tx) => Promise<T>): Promise<T>;
+export declare function executor(sql: PostgresJsQueryable): Executor;
+/** 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[];
@@ -51,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,71 +1,35 @@
-/** 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 the rows. */
+/**
+ * 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 function executor(sql) {
-    return async (text, values) => Array.from(await sql.unsafe(text, Array.from(values)));
-}
-/** 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 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`). */
-export async function execute(sql, q) {
-    const result = await run(sql, q);
-    return result.count;
+    return async (text, values) => {
+        const result = await sql.unsafe(text, Array.from(values));
+        return { rows: Array.from(result), rowCount: result.count ?? null };
+    };
 }
 /**
- * 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,14 +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 type { PostgresJsTypeMap, PostgresJsBigIntTypeMap } 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 { NoResultError, type Executor, type TransactionalSql } from "@typesql/core";
+export type { PostgresJsTypeMap, PostgresJsBigIntTypeMap, PostgresJsParamTypeMap } from "./type-map.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): Sql<DB, PostgresJsTypeMap>;
+export declare function createSql<DB>(sql: PostgresJsQueryable | undefined, options: {
+    readonly rowKeys: "camelCase";
+}): PostgresJsSql<DB, "camelCase">;
+export declare function createSql<DB>(sql?: PostgresJsQueryable, options?: {
+    readonly rowKeys?: "preserve";
+}): PostgresJsSql<DB>;
 /** For `postgres({ types: { bigint: postgres.BigInt } })` connections: `int8` and `count(*)` are `bigint`. */
-export declare function createBigIntSql<DB>(sql?: PostgresJsQueryable): Sql<DB, PostgresJsBigIntTypeMap>;
+export declare function createBigIntSql<DB>(sql: PostgresJsQueryable | undefined, options: {
+    readonly rowKeys: "camelCase";
+}): PostgresJsBigIntSql<DB, "camelCase">;
+export declare function createBigIntSql<DB>(sql?: PostgresJsQueryable, options?: {
+    readonly rowKeys?: "preserve";
+}): 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,EAA8B,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AACrE,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,MAAM,eAAe,CAAC;AAChF,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;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,mBAAmB,GAAG,GAAG,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAEnF;AAED,8GAA8G;AAC9G,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,mBAAmB,GAAG,GAAG,CAAC,EAAE,EAAE,uBAAuB,CAAC,CAE/F"}
+{"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,16 +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";
-/**
- * `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.
- */
-export function createSql(sql) {
-    return createCoreSql(sql && executor(sql));
+export { executor, migrate, } from "./client.js";
+export function createSql(sql, options) {
+    return createTransactionalSql(sql, driver, options);
 }
-/** For `postgres({ types: { bigint: postgres.BigInt } })` connections: `int8` and `count(*)` are `bigint`. */
-export function createBigIntSql(sql) {
-    return createCoreSql(sql && executor(sql));
+export function createBigIntSql(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,EAAY,MAAM,eAAe,CAAC;AACrE,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;AAErB;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAK,GAAyB;IACrD,OAAO,aAAa,CAAwB,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,eAAe,CAAK,GAAyB;IAC3D,OAAO,aAAa,CAA8B,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1E,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/dist/type-map.d.ts

@@ -1,4 +1,4 @@
-import type { DefaultTypeMap } from "@typesql/core";
+import type { DefaultParamTypeMap, DefaultTypeMap } from "@typesql/core";
 /**
  * Canonical Postgres type name → TS type as postgres.js 3.x returns it with its default
  * parsers. Verified against `postgres/src/types.js` (3.4.9), which parses only:
@@ -22,6 +22,8 @@ import type { DefaultTypeMap } from "@typesql/core";
  * element-type[] mapping is exact (int8[] → string[], timestamptz[] → Date[], ...).
  */
 export interface PostgresJsTypeMap extends Omit<DefaultTypeMap, "bytea" | "interval" | "point" | "circle" | "record" | "void"> {
+    /** What parameters accept on top of the row types. */
+    $params: PostgresJsParamTypeMap;
     bytea: Buffer;
     /** No default parser: the Postgres text form, e.g. `"1 day 02:00:00"`. */
     interval: string;
@@ -34,6 +36,25 @@ export interface PostgresJsTypeMap extends Omit<DefaultTypeMap, "bytea" | "inter
     /** `void`-returning functions (`pg_sleep`) yield an empty string. */
     void: string;
 }
+/**
+ * TS types postgres.js parameters accept on top of the row type
+ * (`PostgresJsTypeMap["$params"]`). Verified against `postgres/src/types.js` and `Bind` in
+ * `connection.js` (3.4.9): a value is serialized by the serializer of the parameter type the
+ * server reports, and types without one (int8, numeric, money, interval, …) with `'' + x`.
+ *
+ *   int8, numeric, money          number | bigint | string
+ *   date, timestamp, timestamptz  Date | string | number: serialized as `new Date(x).toISOString()`,
+ *                                 so a string must be one JS `Date` parses, a number is epoch ms
+ *   interval                      string
+ *   bytea                         Uint8Array, besides `Buffer`
+ *
+ * `bool` takes only booleans: its serializer sends `'f'` for anything but `true`.
+ */
+export interface PostgresJsParamTypeMap extends Omit<DefaultParamTypeMap, "date" | "timestamp" | "timestamptz"> {
+    date: Date | string | number;
+    timestamp: Date | string | number;
+    timestamptz: Date | string | number;
+}
 /**
  * Type map for connections created with `postgres({ types: { bigint: postgres.BigInt } })`,
  * which registers a parser for int8 (20) that returns JS `bigint`. `count(*)`, `sum(int4)`

package/dist/type-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-map.d.ts","sourceRoot":"","sources":["../src/type-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5H,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAC9E,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"type-map.d.ts","sourceRoot":"","sources":["../src/type-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5H,sDAAsD;IACtD,OAAO,EAAE,sBAAsB,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,mBAAmB,EAAE,MAAM,GAAG,WAAW,GAAG,aAAa,CAAC;IAC7G,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7B,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,WAAW,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAC9E,IAAI,EAAE,MAAM,CAAC;CACd"}

package/package.json

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

package/src/client.ts

@@ -1,7 +1,10 @@
-import type { Executor, Query, 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`. */
-export type PostgresJsRows = readonly unknown[] & { readonly count: number };
+/**
+ * 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 };
 
 /**
  * Anything with postgres.js' `unsafe(query, parameters)` method: the `Sql` instance,
@@ -16,76 +19,37 @@ 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>;
 }
 
-/** An `Executor` for core's `q.execute()`: runs queries through `sql.unsafe` and resolves to the rows. */
+/**
+ * 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 function executor(sql: PostgresJsQueryable): Executor {
-  return async (text, values) => Array.from(await sql.unsafe(text, Array.from(values)));
-}
-
-/** 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 Array.from(result) as RowType<Q>[];
-}
-
-/** 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`). */
-export async function execute(sql: PostgresJsQueryable, q: AnyQuery): Promise<number> {
-  const result = await run(sql, q);
-  return result.count;
+  return async (text, values) => {
+    const result = await sql.unsafe(text, Array.from(values));
+    return { rows: Array.from(result), rowCount: result.count ?? null };
+  };
 }
 
 /**
- * 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[];
@@ -97,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,34 +1,38 @@
-import { createSql as createCoreSql, type Sql } 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 type { PostgresJsTypeMap, PostgresJsBigIntTypeMap } from "./type-map.js";
+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): Sql<DB, PostgresJsTypeMap> {
-  return createCoreSql<DB, PostgresJsTypeMap>(sql && executor(sql));
+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): Sql<DB, PostgresJsBigIntTypeMap> {
-  return createCoreSql<DB, PostgresJsBigIntTypeMap>(sql && executor(sql));
+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);
 }

package/src/type-map.ts

@@ -1,4 +1,4 @@
-import type { DefaultTypeMap } from "@typesql/core";
+import type { DefaultParamTypeMap, DefaultTypeMap } from "@typesql/core";
 
 /**
  * Canonical Postgres type name → TS type as postgres.js 3.x returns it with its default
@@ -23,6 +23,8 @@ import type { DefaultTypeMap } from "@typesql/core";
  * element-type[] mapping is exact (int8[] → string[], timestamptz[] → Date[], ...).
  */
 export interface PostgresJsTypeMap extends Omit<DefaultTypeMap, "bytea" | "interval" | "point" | "circle" | "record" | "void"> {
+  /** What parameters accept on top of the row types. */
+  $params: PostgresJsParamTypeMap;
   bytea: Buffer;
   /** No default parser: the Postgres text form, e.g. `"1 day 02:00:00"`. */
   interval: string;
@@ -36,6 +38,26 @@ export interface PostgresJsTypeMap extends Omit<DefaultTypeMap, "bytea" | "inter
   void: string;
 }
 
+/**
+ * TS types postgres.js parameters accept on top of the row type
+ * (`PostgresJsTypeMap["$params"]`). Verified against `postgres/src/types.js` and `Bind` in
+ * `connection.js` (3.4.9): a value is serialized by the serializer of the parameter type the
+ * server reports, and types without one (int8, numeric, money, interval, …) with `'' + x`.
+ *
+ *   int8, numeric, money          number | bigint | string
+ *   date, timestamp, timestamptz  Date | string | number: serialized as `new Date(x).toISOString()`,
+ *                                 so a string must be one JS `Date` parses, a number is epoch ms
+ *   interval                      string
+ *   bytea                         Uint8Array, besides `Buffer`
+ *
+ * `bool` takes only booleans: its serializer sends `'f'` for anything but `true`.
+ */
+export interface PostgresJsParamTypeMap extends Omit<DefaultParamTypeMap, "date" | "timestamp" | "timestamptz"> {
+  date: Date | string | number;
+  timestamp: Date | string | number;
+  timestamptz: Date | string | number;
+}
+
 /**
  * Type map for connections created with `postgres({ types: { bigint: postgres.BigInt } })`,
  * which registers a parser for int8 (20) that returns JS `bigint`. `count(*)`, `sum(int4)`