@anabranch/db-postgres 0.1.6 → 0.1.7

package/esm/db/index.d.ts

@@ -2,22 +2,79 @@
  * @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.
+ * 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";
+ *
+ * const users = await DB.withConnection(createInMemory(), (db) =>
+ *   db.query("SELECT * FROM users WHERE active = ?", [true])
+ * ).run();
+ * ```
  *
- * @example
+ * @example Streaming large result sets with error collection
  * ```ts
  * import { DB, createInMemory } from "@anabranch/db";
  *
- * // Idiomatic usage with connector (recommended)
+ * const { successes, errors } = await DB.withConnection(createInMemory(), (db) =>
+ *   db.stream("SELECT * FROM large_table")
+ *     .withConcurrency(10)
+ *     .map(row => processRow(row))
+ *     .partition()
+ * ).run();
+ * ```
+ *
+ * @example Transactions with automatic rollback on error
+ * ```ts
+ * import { DB, ConstraintViolation, createInMemory } from "@anabranch/db";
+ *
  * const result = await DB.withConnection(createInMemory(), (db) =>
- *   db.query("SELECT * FROM users")
+ *   db.withTransaction(async (tx) => {
+ *     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();
+ * ```
+ *
+ * @example Retry with exponential backoff
+ * ```ts
+ * import { DB, createPostgres } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
  *
- * // Bare adapter for testing or custom lifecycle management
- * const adapter = await createInMemory().connect();
- * const db = new DB(adapter);
+ * 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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

@@ -2,22 +2,79 @@
  * @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.
+ * 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";
+ *
+ * const users = await DB.withConnection(createInMemory(), (db) =>
+ *   db.query("SELECT * FROM users WHERE active = ?", [true])
+ * ).run();
+ * ```
  *
- * @example
+ * @example Streaming large result sets with error collection
  * ```ts
  * import { DB, createInMemory } from "@anabranch/db";
  *
- * // Idiomatic usage with connector (recommended)
+ * const { successes, errors } = await DB.withConnection(createInMemory(), (db) =>
+ *   db.stream("SELECT * FROM large_table")
+ *     .withConcurrency(10)
+ *     .map(row => processRow(row))
+ *     .partition()
+ * ).run();
+ * ```
+ *
+ * @example Transactions with automatic rollback on error
+ * ```ts
+ * import { DB, ConstraintViolation, createInMemory } from "@anabranch/db";
+ *
  * const result = await DB.withConnection(createInMemory(), (db) =>
- *   db.query("SELECT * FROM users")
+ *   db.withTransaction(async (tx) => {
+ *     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();
+ * ```
+ *
+ * @example Retry with exponential backoff
+ * ```ts
+ * import { DB, createPostgres } from "@anabranch/db";
+ * import { createPostgres } from "@anabranch/db-postgres";
  *
- * // Bare adapter for testing or custom lifecycle management
- * const adapter = await createInMemory().connect();
- * const db = new DB(adapter);
+ * 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/postgres.d.ts

@@ -1,5 +1,48 @@
 import type { DBAdapter } from "../db/index.js";
-/** Creates a PostgreSQL connector with connection pooling. */
+/**
+ * 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;
 /** Connection options for PostgreSQL. */
 export type PostgresOptions = {

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,8DAA8D;AAC9D,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"}
+{"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,7 +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. */
+/**
+ * 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.6",
+  "version": "0.1.7",
   "description": "TODO: Add description",
   "repository": {
     "type": "git",