@agentuity/postgres 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -32,10 +32,11 @@
  */
 export { postgres, default } from './postgres';
 export { PostgresClient, createCallableClient, type CallablePostgresClient } from './client';
+export { PostgresPool, Pool, createPool } from './pool';
 export { Transaction, Savepoint, ReservedConnection } from './transaction';
 export { patchBunSQL, isPatched, SQL } from './patch';
-export type { PostgresConfig, ReconnectConfig, ConnectionStats, TLSConfig, TransactionOptions, ReserveOptions, } from './types';
+export type { PostgresConfig, ReconnectConfig, ConnectionStats, TLSConfig, TransactionOptions, ReserveOptions, PoolConfig, PoolStats, PoolSSLConfig, } from './types';
 export { PostgresError, ConnectionClosedError, ReconnectFailedError, QueryTimeoutError, TransactionError, UnsupportedOperationError, isRetryableError, } from './errors';
 export { computeBackoff, sleep, mergeReconnectConfig, DEFAULT_RECONNECT_CONFIG } from './reconnect';
-export { shutdownAll, getClientCount, getClients, hasActiveClients } from './registry';
+export { shutdownAll, getClientCount, getClients, hasActiveClients, type Registrable, } from './registry';
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAG7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAG3E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAGtD,YAAY,EACX,cAAc,EACd,eAAe,EACf,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,cAAc,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,gBAAgB,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGpG,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAG7F,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAG3E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAGtD,YAAY,EACX,cAAc,EACd,eAAe,EACf,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,SAAS,EACT,aAAa,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,gBAAgB,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGpG,OAAO,EACN,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,KAAK,WAAW,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -34,6 +34,8 @@
 export { postgres, default } from './postgres';
 // Client class for advanced usage
 export { PostgresClient, createCallableClient } from './client';
+// Pool class for pg.Pool-based connections
+export { PostgresPool, Pool, createPool } from './pool';
 // Transaction and reserved connection classes
 export { Transaction, Savepoint, ReservedConnection } from './transaction';
 // Patch function for modifying Bun.SQL globally
@@ -43,5 +45,5 @@ export { PostgresError, ConnectionClosedError, ReconnectFailedError, QueryTimeou
 // Reconnection utilities
 export { computeBackoff, sleep, mergeReconnectConfig, DEFAULT_RECONNECT_CONFIG } from './reconnect';
 // Global registry for coordinated shutdown
-export { shutdownAll, getClientCount, getClients, hasActiveClients } from './registry';
+export { shutdownAll, getClientCount, getClients, hasActiveClients, } from './registry';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAwB;AACxB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE/C,kCAAkC;AAClC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAA+B,MAAM,UAAU,CAAC;AAE7F,8CAA8C;AAC9C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE3E,gDAAgD;AAChD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAYtD,SAAS;AACT,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,gBAAgB,GAChB,MAAM,UAAU,CAAC;AAElB,yBAAyB;AACzB,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEpG,2CAA2C;AAC3C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAwB;AACxB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE/C,kCAAkC;AAClC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAA+B,MAAM,UAAU,CAAC;AAE7F,2CAA2C;AAC3C,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAExD,8CAA8C;AAC9C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE3E,gDAAgD;AAChD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAetD,SAAS;AACT,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,gBAAgB,GAChB,MAAM,UAAU,CAAC;AAElB,yBAAyB;AACzB,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEpG,2CAA2C;AAC3C,OAAO,EACN,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,GAEhB,MAAM,YAAY,CAAC"}

package/dist/pool.d.ts

@@ -0,0 +1,194 @@
+import pg from 'pg';
+import type { PoolConfig, PoolStats } from './types';
+import { type Registrable } from './registry';
+/**
+ * A resilient PostgreSQL connection pool with automatic reconnection.
+ *
+ * Wraps the `pg` package's Pool and adds:
+ * - Automatic reconnection with exponential backoff
+ * - Connection state tracking
+ * - Pool statistics
+ *
+ * @example
+ * ```typescript
+ * const pool = new PostgresPool({
+ *   connectionString: process.env.DATABASE_URL,
+ *   max: 20,
+ *   reconnect: { maxAttempts: 5 }
+ * });
+ *
+ * // Execute queries
+ * const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
+ *
+ * // Close when done
+ * await pool.close();
+ * ```
+ */
+export declare class PostgresPool implements Registrable {
+    private _pool;
+    private _config;
+    private _connected;
+    private _reconnecting;
+    private _closed;
+    private _shuttingDown;
+    private _signalHandlers;
+    private _reconnectPromise;
+    private _connectPromise;
+    private _stats;
+    /**
+     * Creates a new PostgresPool.
+     *
+     * Note: By default, the actual connection is established lazily on first query.
+     * Set `preconnect: true` in config to verify connectivity immediately.
+     *
+     * @param config - Connection configuration. Can be a connection URL string or a config object.
+     *                 If not provided, uses `process.env.DATABASE_URL`.
+     */
+    constructor(config?: string | PoolConfig);
+    /**
+     * Whether the pool is currently connected.
+     */
+    get connected(): boolean;
+    /**
+     * Whether the pool is shutting down (won't attempt reconnection).
+     */
+    get shuttingDown(): boolean;
+    /**
+     * Whether a reconnection attempt is in progress.
+     */
+    get reconnecting(): boolean;
+    /**
+     * Pool statistics.
+     */
+    get stats(): Readonly<PoolStats>;
+    /**
+     * Execute a query on the pool.
+     * If reconnection is in progress, waits for it to complete before executing.
+     * Automatically retries on retryable errors.
+     *
+     * @param text - The query string or query config object
+     * @param values - Optional array of parameter values
+     * @returns The query result
+     *
+     * @example
+     * ```typescript
+     * const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
+     * console.log(result.rows);
+     * ```
+     */
+    query<T extends pg.QueryResultRow = pg.QueryResultRow>(text: string | pg.QueryConfig<unknown[]>, values?: unknown[]): Promise<pg.QueryResult<T>>;
+    /**
+     * Acquire a client from the pool.
+     * The client must be released back to the pool when done.
+     *
+     * @returns A pooled client
+     *
+     * @example
+     * ```typescript
+     * const client = await pool.connect();
+     * try {
+     *   await client.query('BEGIN');
+     *   await client.query('INSERT INTO users (name) VALUES ($1)', ['Alice']);
+     *   await client.query('COMMIT');
+     * } catch (error) {
+     *   await client.query('ROLLBACK');
+     *   throw error;
+     * } finally {
+     *   client.release();
+     * }
+     * ```
+     */
+    connect(): Promise<pg.PoolClient>;
+    /**
+     * Signal that the application is shutting down.
+     * This prevents reconnection attempts but doesn't immediately close the pool.
+     * Use this when you want to gracefully drain connections before calling close().
+     */
+    shutdown(): void;
+    /**
+     * Close the pool and release all connections.
+     * Alias for end() for compatibility with PostgresClient.
+     */
+    close(): Promise<void>;
+    /**
+     * Close the pool and release all connections.
+     */
+    end(): Promise<void>;
+    /**
+     * Access to the raw pg.Pool instance for advanced use cases.
+     * Returns the underlying pg.Pool instance.
+     */
+    get raw(): pg.Pool;
+    /**
+     * Wait for the connection to be established.
+     * If the connection hasn't been established yet (lazy connection), this will
+     * warm the connection by acquiring and releasing a client.
+     * If reconnection is in progress, waits for it to complete.
+     *
+     * @param timeoutMs - Optional timeout in milliseconds
+     * @throws {ConnectionClosedError} If the pool has been closed or connection fails
+     */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    /**
+     * Registers signal handlers to detect application shutdown.
+     * When shutdown is detected, reconnection is disabled.
+     */
+    private _registerShutdownHandlers;
+    /**
+     * Removes signal handlers registered for shutdown detection.
+     */
+    private _removeShutdownHandlers;
+    /**
+     * Initializes the pg.Pool instance.
+     */
+    private _initializePool;
+    /**
+     * Warms the connection by acquiring and releasing a client.
+     * This verifies the pool can connect to the database.
+     */
+    private _warmConnection;
+    /**
+     * Re-initializes the pool for reconnection.
+     */
+    private _reinitializePool;
+    /**
+     * Handles pool error events.
+     */
+    private _handlePoolError;
+    /**
+     * Starts the reconnection process.
+     */
+    private _startReconnect;
+    /**
+     * The main reconnection loop with exponential backoff.
+     */
+    private _reconnectLoop;
+    /**
+     * Ensures the pool is initialized and returns it.
+     */
+    private _ensureConnected;
+    /**
+     * Ensures the pool is connected and returns it.
+     * If reconnection is in progress, waits for it to complete.
+     * If connection hasn't been established yet, warms it first.
+     */
+    private _ensureConnectedAsync;
+    /**
+     * Executes an operation with retry logic for retryable errors.
+     * Waits for reconnection if one is in progress.
+     */
+    private _executeWithRetry;
+}
+/**
+ * Creates a new PostgresPool.
+ * This is an alias for `new PostgresPool(config)` for convenience.
+ *
+ * @param config - Connection configuration
+ * @returns A new PostgresPool instance
+ */
+export declare function createPool(config?: string | PoolConfig): PostgresPool;
+/**
+ * Alias for PostgresPool for convenient imports.
+ */
+export { PostgresPool as Pool };
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AASrD,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,YAAa,YAAW,WAAW;IAC/C,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAiD;IACxE,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,eAAe,CAA8B;IAErD,OAAO,CAAC,MAAM,CAUZ;IAEF;;;;;;;;OAQG;gBACS,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU;IAyBxC;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAAC,SAAS,CAAC,CAS/B;IAED;;;;;;;;;;;;;;OAcG;IACG,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,cAAc,GAAG,EAAE,CAAC,cAAc,EAC1D,IAAI,EAAE,MAAM,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,EACxC,MAAM,CAAC,EAAE,OAAO,EAAE,GAChB,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAO7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,IAAI,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC;IAOvC;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAIhB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB1B;;;OAGG;IACH,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAEjB;IAED;;;;;;;;OAQG;IACG,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiE1D;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAYjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAO/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAyCvB;;;OAGG;YACW,eAAe;IAkB7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8BxB;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;OAEG;YACW,cAAc;IAqE5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;OAIG;YACW,qBAAqB;IAsCnC;;;OAGG;YACW,iBAAiB;CA2D/B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,YAAY,CAErE;AAED;;GAEG;AACH,OAAO,EAAE,YAAY,IAAI,IAAI,EAAE,CAAC"}