@hexaijs/postgres 0.3.0 → 0.5.0

package/README.md

@@ -30,20 +30,29 @@ The `PostgresUnitOfWork` implements `UnitOfWork` from `@hexaijs/core`. It manage
 
 ```typescript
 import * as pg from "pg";
-import { PostgresUnitOfWork } from "@hexaijs/postgres";
+import { createPostgresUnitOfWork } from "@hexaijs/postgres";
 
-// Create with a client factory
+// From connection pool (recommended for production)
 const pool = new pg.Pool({ connectionString: "postgres://..." });
-const unitOfWork = new PostgresUnitOfWork(
+const unitOfWork = createPostgresUnitOfWork(pool);
+
+// From connection string
+const unitOfWork = createPostgresUnitOfWork("postgres://user:pass@localhost:5432/mydb");
+
+// From PostgresConfig
+const unitOfWork = createPostgresUnitOfWork(PostgresConfig.fromEnv("DB"));
+```
+
+For advanced use cases, you can use `DefaultPostgresUnitOfWork` directly:
+
+```typescript
+import { DefaultPostgresUnitOfWork } from "@hexaijs/postgres";
+
+// Custom client factory with custom cleanup
+const unitOfWork = new DefaultPostgresUnitOfWork(
     () => new pg.Client({ connectionString: "postgres://..." }),
     (client) => client.end()  // cleanup function
 );
-
-// Or use a connection pool
-const pooledUnitOfWork = new PostgresUnitOfWork(
-    async () => await pool.connect(),
-    (client) => (client as pg.PoolClient).release()
-);
 ```
 
 The client factory creates a new client for each transaction. The optional cleanup function runs after the transaction completes (commit or rollback).
@@ -71,30 +80,30 @@ const client = ctx.getUnitOfWork().getClient();
 await client.query("UPDATE orders SET status = $1 WHERE id = $2", ["confirmed", orderId]);
 ```
 
-### Query Execution (No Transaction)
+### Client Access Without Transaction
 
-Use `query()` for read-only operations without transaction overhead. This implements the `QueryableUnitOfWork` interface from `@hexaijs/core`.
+Use `withClient()` for operations without transaction overhead. Useful for read-only queries or when you need direct client access.
 
 ```typescript
 // Simple read without transaction (autocommit)
-const user = await unitOfWork.query(async (client) => {
+const user = await unitOfWork.withClient(async (client) => {
     const result = await client.query("SELECT * FROM users WHERE id = $1", [userId]);
     return result.rows[0];
 });
 ```
 
-The `query()` method is context-aware:
+The `withClient()` method is context-aware:
 
 | Context | Behavior |
 |---------|----------|
-| Outside transaction | New connection from factory → query → cleanup |
+| Outside transaction | New connection from factory → work → cleanup |
 | Inside transaction | Reuses existing transaction's client |
 
-This means you can safely use `query()` anywhere in your code:
+This means you can safely use `withClient()` anywhere in your code:
 
 ```typescript
 // Outside any transaction - gets its own connection
-const users = await unitOfWork.query(async (client) => {
+const users = await unitOfWork.withClient(async (client) => {
     return await client.query("SELECT * FROM users");
 });
 
@@ -103,19 +112,19 @@ await unitOfWork.wrap(async (txClient) => {
     await txClient.query("INSERT INTO orders (id) VALUES ($1)", [orderId]);
 
     // Uses the same txClient, sees uncommitted changes
-    const order = await unitOfWork.query(async (client) => {
+    const order = await unitOfWork.withClient(async (client) => {
         // client === txClient
         return await client.query("SELECT * FROM orders WHERE id = $1", [orderId]);
     });
 });
 ```
 
-**When to use `wrap()` vs `query()`:**
+**When to use `wrap()` vs `withClient()`:**
 
 | Method | Transaction | Overhead | Use Case |
 |--------|-------------|----------|----------|
 | `wrap()` | Yes | BEGIN + COMMIT | Commands (INSERT, UPDATE, DELETE) |
-| `query()` | No | Connection only | Queries (SELECT) |
+| `withClient()` | No | Connection only | Queries (SELECT) |
 
 ### Transaction Propagation
 
@@ -322,7 +331,7 @@ await ensureConnection(client);  // Safe to call multiple times
 
 ### PostgresUnitOfWorkForTesting
 
-A test-specific `QueryableUnitOfWork` implementation that runs inside an external transaction. This allows tests to rollback all changes after each test, keeping the database clean without truncating tables.
+A test-specific `PostgresUnitOfWork` implementation that runs inside an external transaction. This allows tests to rollback all changes after each test, keeping the database clean without truncating tables.
 
 ```typescript
 import { PostgresUnitOfWorkForTesting } from "@hexaijs/postgres/test";
@@ -368,7 +377,7 @@ describe("OrderService", () => {
 
 **Key behaviors:**
 
-- **`query()` method**: Uses the test client directly, always within the external transaction context.
+- **`withClient()` method**: Uses the test client directly, always within the external transaction context.
 - **abortError propagation**: When a nested `EXISTING` operation throws (even if caught), the entire transaction is marked as aborted and will rollback - matching production behavior.
 - **NESTED savepoints**: `Propagation.NESTED` creates independent savepoints that can rollback without affecting the parent.
 - **Propagation.NEW**: Logs a warning and creates a new savepoint instead (true separate transactions are not possible within the external transaction).
@@ -413,8 +422,10 @@ await uow.wrap(async (c) => {
 
 | Export | Description |
 |--------|-------------|
-| `PostgresUnitOfWork` | Transaction and query management implementing `QueryableUnitOfWork` |
-| `PostgresUnitOfWorkForTesting` | Test-specific QueryableUnitOfWork that runs inside external transaction |
+| `createPostgresUnitOfWork` | Factory function to create PostgresUnitOfWork from Pool or Config |
+| `PostgresUnitOfWork` | Interface extending UnitOfWork with `withClient()` method |
+| `DefaultPostgresUnitOfWork` | Default implementation of PostgresUnitOfWork with transaction management |
+| `PostgresUnitOfWorkForTesting` | Test-specific PostgresUnitOfWork that runs inside external transaction |
 | `PostgresEventStore` | Event store implementation with batch insert support |
 | `PostgresConfig` | Immutable configuration with builder pattern |
 | `postgresConfig` | Config spec for `defineConfig` integration |
@@ -425,8 +436,51 @@ await uow.wrap(async (c) => {
 | `IsolationLevel` | Transaction isolation level enum |
 | `ensureConnection` | Safe connection helper |
 
+## Migration Guide
+
+### v0.3.x → v0.4.0
+
+**Breaking Change: `PostgresUnitOfWork` class renamed**
+
+`PostgresUnitOfWork` is now an interface. The actual implementation is `DefaultPostgresUnitOfWork`.
+
+```typescript
+// Before (v0.3.x)
+import { PostgresUnitOfWork } from "@hexaijs/postgres";
+const uow = new PostgresUnitOfWork(factory, cleanup);
+
+// After (v0.4.0)
+import { DefaultPostgresUnitOfWork } from "@hexaijs/postgres";
+const uow = new DefaultPostgresUnitOfWork(factory, cleanup);
+
+// Type usage (unchanged)
+function doSomething(uow: PostgresUnitOfWork) { ... }
+```
+
+**Why this change?**
+
+The interface allows both `DefaultPostgresUnitOfWork` and `PostgresUnitOfWorkForTesting` to be used interchangeably where `PostgresUnitOfWork` type is expected.
+
+**Breaking Change: `query()` renamed to `withClient()`**
+
+The `query()` method has been renamed to `withClient()` for clarity. The name `query()` was confusing because inside the callback, you also call `client.query()`.
+
+```typescript
+// Before (v0.3.x)
+const user = await unitOfWork.query(async (client) => {
+    return client.query("SELECT * FROM users WHERE id = $1", [userId]);
+});
+
+// After (v0.4.0)
+const user = await unitOfWork.withClient(async (client) => {
+    return client.query("SELECT * FROM users WHERE id = $1", [userId]);
+});
+```
+
+The `QueryableUnitOfWork` interface has been removed from `@hexaijs/core`. The `withClient()` method is now specific to `@hexaijs/postgres`.
+
 ## See Also
 
-- [@hexaijs/core](../core/README.md) - Core interfaces (`UnitOfWork`, `QueryableUnitOfWork`, `EventStore`, `Propagation`)
+- [@hexaijs/core](../core/README.md) - Core interfaces (`UnitOfWork`, `EventStore`, `Propagation`)
 - [@hexaijs/sqlite](../sqlite/README.md) - SQLite implementation for testing
 - [@hexaijs/application](../application/README.md) - Application context that provides `getUnitOfWork()`

package/dist/helpers-vPAudN_S.d.ts

@@ -0,0 +1,125 @@
+import * as pg from 'pg';
+import { BaseUnitOfWorkOptions, UnitOfWork } from '@hexaijs/core';
+import { DatabaseConfig } from 'ezcfg';
+
+interface PoolOptions {
+    size?: number;
+    connectionTimeout?: number;
+    idleTimeout?: number;
+}
+interface FromEnvOptions {
+    /**
+     * Environment variable loading mode.
+     * - "url": Load from {PREFIX}_URL (default)
+     * - "fields": Load from {PREFIX}_HOST, {PREFIX}_PORT, {PREFIX}_DATABASE, {PREFIX}_USER, {PREFIX}_PASSWORD
+     */
+    mode?: "url" | "fields";
+}
+declare class PostgresConfig implements DatabaseConfig {
+    readonly host: string;
+    readonly database: string;
+    readonly user: string;
+    readonly port: number;
+    readonly password?: string;
+    readonly pool?: PoolOptions;
+    constructor(config: {
+        database: string;
+        user?: string;
+        host?: string;
+        port?: number;
+        password?: string;
+        pool?: PoolOptions;
+    });
+    static fromUrl(value: string): PostgresConfig;
+    /**
+     * Creates a PostgresConfig from environment variables.
+     *
+     * @param prefix - Environment variable prefix
+     * @param options - Loading options (mode: "url" | "fields")
+     * @throws Error if required environment variables are not set
+     *
+     * @example
+     * ```typescript
+     * // URL mode (default): reads ASSIGNMENT_DB_URL
+     * const config = PostgresConfig.fromEnv("ASSIGNMENT_DB");
+     *
+     * // Fields mode: reads POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DATABASE, POSTGRES_USER, POSTGRES_PASSWORD
+     * const config = PostgresConfig.fromEnv("POSTGRES", { mode: "fields" });
+     * ```
+     */
+    static fromEnv(prefix: string, options?: FromEnvOptions): PostgresConfig;
+    private static parseUrl;
+    withDatabase(database: string): PostgresConfig;
+    withUser(user: string): PostgresConfig;
+    withPassword(password: string): PostgresConfig;
+    withHost(host: string): PostgresConfig;
+    withPort(port: number): PostgresConfig;
+    withPoolSize(size: number): PostgresConfig;
+    withConnectionTimeout(connectionTimeout: number): PostgresConfig;
+    withIdleTimeout(idleTimeout: number): PostgresConfig;
+    toString(): string;
+}
+
+type ClientFactory = () => pg.ClientBase | Promise<pg.ClientBase>;
+type ClientCleanUp = (client: pg.ClientBase) => void | Promise<void>;
+declare enum IsolationLevel {
+    READ_UNCOMMITTED = "read uncommitted",
+    READ_COMMITTED = "read committed",
+    REPEATABLE_READ = "repeatable read",
+    SERIALIZABLE = "serializable"
+}
+interface PostgresTransactionOptions extends BaseUnitOfWorkOptions {
+    isolationLevel?: IsolationLevel;
+}
+
+interface PostgresUnitOfWork extends UnitOfWork<pg.ClientBase, PostgresTransactionOptions> {
+    withClient<T>(fn: (client: pg.ClientBase) => Promise<T>): Promise<T>;
+}
+declare class DefaultPostgresUnitOfWork implements PostgresUnitOfWork {
+    private clientFactory;
+    private clientCleanUp?;
+    private transactionStorage;
+    constructor(clientFactory: ClientFactory, clientCleanUp?: ClientCleanUp | undefined);
+    getClient(): pg.ClientBase;
+    wrap<T = unknown>(fn: (client: pg.ClientBase) => Promise<T>, options?: Partial<PostgresTransactionOptions>): Promise<T>;
+    withClient<T>(fn: (client: pg.ClientBase) => Promise<T>): Promise<T>;
+    private getCurrentTransaction;
+    private resolveOptions;
+    private resolveTransaction;
+    private createTransaction;
+    private executeInContext;
+}
+declare function createPostgresUnitOfWork(pool: pg.Pool): PostgresUnitOfWork;
+declare function createPostgresUnitOfWork(config: PostgresConfig | string): PostgresUnitOfWork;
+
+declare class ClientWrapper {
+    protected client: pg.Client;
+    getClient(): pg.Client;
+    constructor(urlOrClient: PostgresConfig | string | pg.Client);
+    protected withClient<T = unknown>(work: (client: pg.Client) => Promise<T>): Promise<T>;
+    query<R = any>(query: string, params?: any[]): Promise<Array<R>>;
+    close(): Promise<void>;
+}
+declare class DatabaseManager extends ClientWrapper {
+    createDatabase(name: string): Promise<void>;
+    dropDatabase(name: string): Promise<void>;
+}
+declare class TableManager extends ClientWrapper {
+    getTableSchema(tableName: string): Promise<Array<{
+        column: string;
+        type: string;
+    }>>;
+    tableExists(tableName: string): Promise<boolean>;
+    createTable(name: string, columns: Array<{
+        name: string;
+        property: string;
+    }>): Promise<void>;
+    dropTable(name: string): Promise<void>;
+    truncateTable(name: string): Promise<void>;
+    truncateAllTables(): Promise<void>;
+    dropAllTables(): Promise<void>;
+    private getTableNames;
+}
+declare function ensureConnection(client: pg.ClientBase): Promise<void>;
+
+export { type ClientCleanUp as C, DatabaseManager as D, type FromEnvOptions as F, IsolationLevel as I, PostgresConfig as P, TableManager as T, type ClientFactory as a, ClientWrapper as b, DefaultPostgresUnitOfWork as c, type PoolOptions as d, type PostgresTransactionOptions as e, type PostgresUnitOfWork as f, createPostgresUnitOfWork as g, ensureConnection as h };

package/dist/index.d.ts

@@ -1,7 +1,64 @@
-export * from "./postgres-unit-of-work";
-export * from "./run-migrations";
-export * from "./run-hexai-migrations";
-export { ClientWrapper, DatabaseManager, TableManager, ensureConnection, } from "./helpers";
-export * from "./postgres-event-store";
-export * from "./config";
-//# sourceMappingURL=index.d.ts.map
+import { P as PostgresConfig, F as FromEnvOptions } from './helpers-vPAudN_S.js';
+export { C as ClientCleanUp, a as ClientFactory, b as ClientWrapper, D as DatabaseManager, c as DefaultPostgresUnitOfWork, I as IsolationLevel, d as PoolOptions, e as PostgresTransactionOptions, f as PostgresUnitOfWork, T as TableManager, g as createPostgresUnitOfWork, h as ensureConnection } from './helpers-vPAudN_S.js';
+import { Client, PoolClient } from 'pg';
+import { EventStore, Message, StoredEvent, EventStoreFetchResult } from '@hexaijs/core';
+import { ConfigSpec } from 'ezcfg';
+
+declare class PostgresConfigSpec implements ConfigSpec<PostgresConfig> {
+    private readonly prefix;
+    private readonly mode;
+    readonly _type = "postgres";
+    constructor(prefix: string, mode?: FromEnvOptions["mode"]);
+    resolve(errors: string[]): PostgresConfig | undefined;
+}
+/**
+ * PostgreSQL database configuration from environment variables.
+ * Returns a PostgresConfig instance.
+ *
+ * @param prefix - Environment variable prefix
+ * @param mode - "url" reads {PREFIX}_URL, "fields" reads individual fields
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig, env } from "@hexaijs/core";
+ * import { postgresConfig } from "@hexaijs/postgres";
+ *
+ * const getConfig = defineConfig({
+ *     db: postgresConfig("ORDER_DB"),           // reads ORDER_DB_URL
+ *     db2: postgresConfig("PG", "fields"),      // reads PG_HOST, PG_PORT, etc.
+ * });
+ *
+ * getConfig().db.host;        // "localhost"
+ * getConfig().db.toString();  // "postgres://..."
+ * ```
+ */
+declare function postgresConfig(prefix: string, mode?: FromEnvOptions["mode"]): PostgresConfigSpec;
+
+interface MigrationOptions {
+    url: PostgresConfig | string;
+    dir: string;
+    namespace?: string;
+    direction?: "up" | "down";
+    count?: number;
+    dryRun?: boolean;
+}
+declare function runMigrations({ namespace, url, dir, direction, count, dryRun, }: MigrationOptions): Promise<void>;
+
+declare function runHexaiMigrations(dbUrl: string | PostgresConfig): Promise<void>;
+
+type PgClient = Client | PoolClient;
+interface PostgresEventStoreConfig {
+    tableName?: string;
+}
+declare class PostgresEventStore implements EventStore {
+    private readonly client;
+    private readonly tableName;
+    constructor(client: PgClient, config?: PostgresEventStoreConfig);
+    store(event: Message): Promise<StoredEvent>;
+    storeAll(events: Message[]): Promise<StoredEvent[]>;
+    fetch(afterPosition: number, limit?: number): Promise<EventStoreFetchResult>;
+    getLastPosition(): Promise<number>;
+    private deserializeRow;
+}
+
+export { FromEnvOptions, type MigrationOptions, PostgresConfig, PostgresConfigSpec, PostgresEventStore, type PostgresEventStoreConfig, postgresConfig, runHexaiMigrations, runMigrations };