@hexaijs/postgres 0.4.0 → 0.5.0

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,8 +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 "./types";
-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 };