@anabranch/db-postgres 0.1.5 → 0.1.7

package/esm/db/index.d.ts

@@ -1,61 +1,81 @@
 /**
- * @abranch/db
+ * @anabranch/db
  *
  * Database primitives with Task/Stream semantics for error-tolerant async operations.
+ * Integrates with anabranch's {@link Task}, {@link Stream}, {@link Source}, and
+ * {@link Channel} types for composable error handling and concurrent processing.
  *
  * ## Adapters vs Connectors
  *
  * A **DBConnector** produces connected **DBAdapter** instances. Use connectors for
  * production code to properly manage connection lifecycles:
  *
+ * - **Connector**: Manages connection pool/lifecycle, produces adapters
+ * - **Adapter**: Low-level query/execute/close interface
+ * - **DB**: Wrapper providing Task/Stream semantics over an adapter
+ *
+ * ## Core Types
+ *
+ * - {@link DBConnector} - Interface for connection factories
+ * - {@link DBAdapter} - Low-level database operations interface
+ * - {@link DB} - High-level wrapper with Task/Stream methods
+ * - {@link DBTransaction} - Transaction scope with commit/rollback
+ *
+ * ## Error Types
+ *
+ * All errors are typed for catchable handling:
+ * - {@link ConnectionFailed} - Connection establishment failed
+ * - {@link QueryFailed} - Query execution error
+ * - {@link ConstraintViolation} - Constraint violation (UNIQUE, FOREIGN KEY, etc.)
+ * - {@link TransactionFailed} - Transaction error
+ *
+ * @example Basic query with Task semantics
  * ```ts
  * import { DB, createInMemory } from "@anabranch/db";
  *
- * // Idiomatic usage with connector (recommended)
- * const result = await DB.withConnection(createInMemory(), (db) =>
- *   db.query("SELECT * FROM users")
+ * const users = await DB.withConnection(createInMemory(), (db) =>
+ *   db.query("SELECT * FROM users WHERE active = ?", [true])
  * ).run();
- *
- * // Bare adapter for testing or custom lifecycle management
- * const adapter = await createInMemory().connect();
- * const db = new DB(adapter);
  * ```
  *
- * ## Usage
- *
+ * @example Streaming large result sets with error collection
  * ```ts
  * import { DB, createInMemory } from "@anabranch/db";
  *
- * // Using withConnection for automatic lifecycle management
- * await DB.withConnection(createInMemory(), async (db) => {
- *   await db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)").run();
- *   await db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]).run();
- *   return db.query("SELECT * FROM users").run();
- * }).run();
+ * const { successes, errors } = await DB.withConnection(createInMemory(), (db) =>
+ *   db.stream("SELECT * FROM large_table")
+ *     .withConcurrency(10)
+ *     .map(row => processRow(row))
+ *     .partition()
+ * ).run();
+ * ```
  *
- * // Stream large result sets
- * const { successes, errors } = await db.stream("SELECT * FROM users")
- *   .map(u => processUser(u))
- *   .partition();
+ * @example Transactions with automatic rollback on error
+ * ```ts
+ * import { DB, ConstraintViolation, createInMemory } from "@anabranch/db";
  *
- * // Transactions with automatic rollback on error
  * const result = await DB.withConnection(createInMemory(), (db) =>
  *   db.withTransaction(async (tx) => {
- *     await tx.execute("INSERT INTO users (name) VALUES (?)", ["Bob"]).run();
- *     return tx.query("SELECT last_insert_rowid()").run();
+ *     await tx.execute("INSERT INTO orders (user_id) VALUES (?)", [userId]);
+ *     await tx.execute("UPDATE users SET order_count = order_count + 1 WHERE id = ?", [userId]);
+ *     return tx.query("SELECT last_insert_rowid()");
  *   })
+ * ).recoverWhen(
+ *   (e) => e instanceof ConstraintViolation,
+ *   (e) => ({ id: 0, error: e.message })
  * ).run();
  * ```
  *
- * ## Error Types
- *
- * The following error types are exported for adapter implementors:
+ * @example Retry with exponential backoff
+ * ```ts
+ * import { DB, createPostgres } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
  *
- * - {@link ConnectionFailed} - Throw from connector's `connect()` on failure
- * - {@link CloseError} - Throw from adapter's `close()` on failure
- * - {@link QueryFailed} - Thrown for query execution errors
- * - {@link ConstraintViolation} - Thrown for constraint violations (e.g., UNIQUE, FOREIGN KEY)
- * - {@link TransactionFailed} - Thrown for transaction errors
+ * const users = await DB.withConnection(createPostgres(), (db) =>
+ *   db.query("SELECT * FROM users")
+ *     .retry({ attempts: 3, delay: (attempt) => 100 * Math.pow(2, attempt) })
+ * ).run();
+ * ```
  *
  * @module
  */

package/esm/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5C,YAAY,EACV,SAAS,EACT,WAAW,EACX,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5C,YAAY,EACV,SAAS,EACT,WAAW,EACX,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/esm/db/index.js

@@ -1,61 +1,81 @@
 /**
- * @abranch/db
+ * @anabranch/db
  *
  * Database primitives with Task/Stream semantics for error-tolerant async operations.
+ * Integrates with anabranch's {@link Task}, {@link Stream}, {@link Source}, and
+ * {@link Channel} types for composable error handling and concurrent processing.
  *
  * ## Adapters vs Connectors
  *
  * A **DBConnector** produces connected **DBAdapter** instances. Use connectors for
  * production code to properly manage connection lifecycles:
  *
+ * - **Connector**: Manages connection pool/lifecycle, produces adapters
+ * - **Adapter**: Low-level query/execute/close interface
+ * - **DB**: Wrapper providing Task/Stream semantics over an adapter
+ *
+ * ## Core Types
+ *
+ * - {@link DBConnector} - Interface for connection factories
+ * - {@link DBAdapter} - Low-level database operations interface
+ * - {@link DB} - High-level wrapper with Task/Stream methods
+ * - {@link DBTransaction} - Transaction scope with commit/rollback
+ *
+ * ## Error Types
+ *
+ * All errors are typed for catchable handling:
+ * - {@link ConnectionFailed} - Connection establishment failed
+ * - {@link QueryFailed} - Query execution error
+ * - {@link ConstraintViolation} - Constraint violation (UNIQUE, FOREIGN KEY, etc.)
+ * - {@link TransactionFailed} - Transaction error
+ *
+ * @example Basic query with Task semantics
  * ```ts
  * import { DB, createInMemory } from "@anabranch/db";
  *
- * // Idiomatic usage with connector (recommended)
- * const result = await DB.withConnection(createInMemory(), (db) =>
- *   db.query("SELECT * FROM users")
+ * const users = await DB.withConnection(createInMemory(), (db) =>
+ *   db.query("SELECT * FROM users WHERE active = ?", [true])
  * ).run();
- *
- * // Bare adapter for testing or custom lifecycle management
- * const adapter = await createInMemory().connect();
- * const db = new DB(adapter);
  * ```
  *
- * ## Usage
- *
+ * @example Streaming large result sets with error collection
  * ```ts
  * import { DB, createInMemory } from "@anabranch/db";
  *
- * // Using withConnection for automatic lifecycle management
- * await DB.withConnection(createInMemory(), async (db) => {
- *   await db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)").run();
- *   await db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]).run();
- *   return db.query("SELECT * FROM users").run();
- * }).run();
+ * const { successes, errors } = await DB.withConnection(createInMemory(), (db) =>
+ *   db.stream("SELECT * FROM large_table")
+ *     .withConcurrency(10)
+ *     .map(row => processRow(row))
+ *     .partition()
+ * ).run();
+ * ```
  *
- * // Stream large result sets
- * const { successes, errors } = await db.stream("SELECT * FROM users")
- *   .map(u => processUser(u))
- *   .partition();
+ * @example Transactions with automatic rollback on error
+ * ```ts
+ * import { DB, ConstraintViolation, createInMemory } from "@anabranch/db";
  *
- * // Transactions with automatic rollback on error
  * const result = await DB.withConnection(createInMemory(), (db) =>
  *   db.withTransaction(async (tx) => {
- *     await tx.execute("INSERT INTO users (name) VALUES (?)", ["Bob"]).run();
- *     return tx.query("SELECT last_insert_rowid()").run();
+ *     await tx.execute("INSERT INTO orders (user_id) VALUES (?)", [userId]);
+ *     await tx.execute("UPDATE users SET order_count = order_count + 1 WHERE id = ?", [userId]);
+ *     return tx.query("SELECT last_insert_rowid()");
  *   })
+ * ).recoverWhen(
+ *   (e) => e instanceof ConstraintViolation,
+ *   (e) => ({ id: 0, error: e.message })
  * ).run();
  * ```
  *
- * ## Error Types
- *
- * The following error types are exported for adapter implementors:
+ * @example Retry with exponential backoff
+ * ```ts
+ * import { DB, createPostgres } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
  *
- * - {@link ConnectionFailed} - Throw from connector's `connect()` on failure
- * - {@link CloseError} - Throw from adapter's `close()` on failure
- * - {@link QueryFailed} - Thrown for query execution errors
- * - {@link ConstraintViolation} - Thrown for constraint violations (e.g., UNIQUE, FOREIGN KEY)
- * - {@link TransactionFailed} - Thrown for transaction errors
+ * const users = await DB.withConnection(createPostgres(), (db) =>
+ *   db.query("SELECT * FROM users")
+ *     .retry({ attempts: 3, delay: (attempt) => 100 * Math.pow(2, attempt) })
+ * ).run();
+ * ```
  *
  * @module
  */

package/esm/db-postgres/index.d.ts

@@ -1,2 +1,29 @@
+/**
+ * @anabranch/db-postgres
+ *
+ * PostgreSQL database connector for the @anabranch/db package using `node:pg`.
+ *
+ * Provides a `DBConnector` implementation with connection pooling and
+ * cursor-based streaming via `pg-cursor` for memory-efficient processing
+ * of large result sets.
+ *
+ * @example
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const db = new DB(
+ *   await createPostgres({
+ *     connectionString: "postgresql://user:pass@localhost:5432/mydb",
+ *   }).connect(),
+ * );
+ *
+ * const users = await db
+ *   .query<{ id: number; name: string }>("SELECT * FROM users")
+ *   .run();
+ * ```
+ *
+ * @module
+ */
 export { createPostgres, type PostgresConnector, type PostgresOptions, } from "./postgres.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/db-postgres/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db-postgres/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db-postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EACL,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC"}

package/esm/db-postgres/index.js

@@ -1 +1,28 @@
+/**
+ * @anabranch/db-postgres
+ *
+ * PostgreSQL database connector for the @anabranch/db package using `node:pg`.
+ *
+ * Provides a `DBConnector` implementation with connection pooling and
+ * cursor-based streaming via `pg-cursor` for memory-efficient processing
+ * of large result sets.
+ *
+ * @example
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const db = new DB(
+ *   await createPostgres({
+ *     connectionString: "postgresql://user:pass@localhost:5432/mydb",
+ *   }).connect(),
+ * );
+ *
+ * const users = await db
+ *   .query<{ id: number; name: string }>("SELECT * FROM users")
+ *   .run();
+ * ```
+ *
+ * @module
+ */
 export { createPostgres, } from "./postgres.js";

package/esm/db-postgres/postgres.d.ts

@@ -1,19 +1,71 @@
 import type { DBAdapter } from "../db/index.js";
+/**
+ * Creates a PostgreSQL connector with connection pooling.
+ *
+ * Returns a connector that can be used with {@link DB.withConnection} to
+ * acquire connections. Each call to `connect()` returns a new adapter with
+ * query, execute, and stream methods. The stream method uses pg-cursor for
+ * memory-efficient streaming of large result sets.
+ *
+ * @example Connect and query with error handling
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const users = await DB.withConnection(createPostgres(), (db) =>
+ *   db.query("SELECT * FROM users WHERE active = ?", [true])
+ * ).run();
+ * ```
+ *
+ * @example Stream large result sets with concurrency
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const { successes, errors } = await DB.withConnection(createPostgres(), (db) =>
+ *   db.stream("SELECT * FROM large_table")
+ *     .withConcurrency(10)
+ *     .map(row => processRow(row))
+ *     .partition()
+ * ).run();
+ * ```
+ *
+ * @example Transactions with automatic rollback
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const result = await DB.withConnection(createPostgres(), (db) =>
+ *   db.withTransaction(async (tx) => {
+ *     await tx.execute("INSERT INTO orders (user_id) VALUES (?)", [userId]);
+ *     return tx.query("SELECT last_insert_rowid()");
+ *   })
+ * ).run();
+ * ```
+ */
 export declare function createPostgres(options?: PostgresOptions): PostgresConnector;
-type PostgresOptions = {
+/** Connection options for PostgreSQL. */
+export type PostgresOptions = {
+    /** @default "localhost" */
     host?: string;
+    /** @default 5432 */
     port?: number;
+    /** @default "postgres" */
     user?: string;
+    /** @default "" */
     password?: string;
+    /** @default "postgres" */
     database?: string;
     connectionString?: string;
     max?: number;
     idleTimeoutMillis?: number;
     connectionTimeoutMillis?: number;
 };
+/** PostgreSQL database connector. */
 export interface PostgresConnector {
+    /** Connects and returns a DBAdapter for query execution. */
     connect(signal?: AbortSignal): Promise<DBAdapter>;
+    /** Closes the connection pool. */
     end(): Promise<void>;
 }
-export type { PostgresOptions };
 //# sourceMappingURL=postgres.d.ts.map

package/esm/db-postgres/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db-postgres/postgres.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,wBAAgB,cAAc,CAC5B,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CA4CnB;AAED,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAuBF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClD,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db-postgres/postgres.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CA4CnB;AAED,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG;IAC5B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClD,kCAAkC;IAClC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB"}

package/esm/db-postgres/postgres.js

@@ -2,6 +2,50 @@ import pg from "pg";
 import Cursor from "pg-cursor";
 import process from "node:process";
 const { Pool } = pg;
+/**
+ * Creates a PostgreSQL connector with connection pooling.
+ *
+ * Returns a connector that can be used with {@link DB.withConnection} to
+ * acquire connections. Each call to `connect()` returns a new adapter with
+ * query, execute, and stream methods. The stream method uses pg-cursor for
+ * memory-efficient streaming of large result sets.
+ *
+ * @example Connect and query with error handling
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const users = await DB.withConnection(createPostgres(), (db) =>
+ *   db.query("SELECT * FROM users WHERE active = ?", [true])
+ * ).run();
+ * ```
+ *
+ * @example Stream large result sets with concurrency
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const { successes, errors } = await DB.withConnection(createPostgres(), (db) =>
+ *   db.stream("SELECT * FROM large_table")
+ *     .withConcurrency(10)
+ *     .map(row => processRow(row))
+ *     .partition()
+ * ).run();
+ * ```
+ *
+ * @example Transactions with automatic rollback
+ * ```ts
+ * import { DB } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
+ *
+ * const result = await DB.withConnection(createPostgres(), (db) =>
+ *   db.withTransaction(async (tx) => {
+ *     await tx.execute("INSERT INTO orders (user_id) VALUES (?)", [userId]);
+ *     return tx.query("SELECT last_insert_rowid()");
+ *   })
+ * ).run();
+ * ```
+ */
 export function createPostgres(options = {}) {
     const pool = new Pool(toPoolConfig(options));
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anabranch/db-postgres",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "TODO: Add description",
   "repository": {
     "type": "git",