@warlock.js/cascade 4.0.92 → 4.0.93

package/esm/drivers/postgres/postgres-driver.d.ts

@@ -0,0 +1,360 @@
+/**
+ * PostgreSQL Driver
+ *
+ * Main driver implementation for PostgreSQL database operations.
+ * Implements the DriverContract interface to provide a unified API
+ * for CRUD operations, transactions, and query building.
+ *
+ * Uses the `pg` package for database connectivity with connection pooling.
+ *
+ * @module cascade/drivers/postgres
+ */
+import type { CreateDatabaseOptions, DriverContract, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, UpdateOperations, UpdateResult } from "../../contracts/database-driver.contract";
+import type { DriverBlueprintContract } from "../../contracts/driver-blueprint.contract";
+import type { MigrationDriverContract } from "../../contracts/migration-driver.contract";
+import type { QueryBuilderContract } from "../../contracts/query-builder.contract";
+import type { SyncAdapterContract } from "../../contracts/sync-adapter.contract";
+import { PostgresDialect } from "./postgres-dialect";
+import type { PostgresPoolConfig, PostgresQueryResult, PostgresTransactionOptions } from "./types";
+/**
+ * Lazily loaded pg module types.
+ */
+type PgPool = import("pg").Pool;
+type PgPoolClient = import("pg").PoolClient;
+/**
+ * PostgreSQL database driver implementing the Cascade DriverContract.
+ *
+ * Provides connection pooling, CRUD operations, transactions, and
+ * integration with Cascade's query builder and migration systems.
+ *
+ * @example
+ * ```typescript
+ * const driver = new PostgresDriver({
+ *   host: 'localhost',
+ *   port: 5432,
+ *   database: 'myapp',
+ *   user: 'postgres',
+ *   password: 'secret'
+ * });
+ *
+ * await driver.connect();
+ *
+ * // Insert a document
+ * const result = await driver.insert('users', { name: 'Alice', email: 'alice@example.com' });
+ *
+ * // Query using the query builder
+ * const users = await driver.queryBuilder('users')
+ *   .where('name', 'Alice')
+ *   .get();
+ *
+ * await driver.disconnect();
+ * ```
+ */
+export declare class PostgresDriver implements DriverContract {
+    private readonly config;
+    /**
+     * Driver name identifier.
+     */
+    readonly name: "postgres";
+    /**
+     * SQL dialect for PostgreSQL-specific syntax.
+     */
+    readonly dialect: PostgresDialect;
+    /**
+     * Connection pool instance.
+     */
+    private _pool;
+    /**
+     * Event listeners for driver lifecycle events.
+     */
+    private readonly _eventListeners;
+    /**
+     * Whether the driver is currently connected.
+     */
+    private _isConnected;
+    /**
+     * Blueprint instance (lazy-loaded).
+     */
+    private _blueprint;
+    /**
+     * Migration driver instance (lazy-loaded).
+     */
+    private _migrationDriver;
+    /**
+     * Sync adapter instance (lazy-loaded).
+     */
+    private _syncAdapter;
+    /**
+     * Create a new PostgreSQL driver instance.
+     *
+     * @param config - PostgreSQL connection configuration
+     */
+    constructor(config: PostgresPoolConfig);
+    /**
+     * Get the connection pool instance.
+     *
+     * @throws Error if not connected
+     */
+    get pool(): PgPool;
+    /**
+     * Check if the driver is currently connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the driver blueprint (information schema).
+     */
+    get blueprint(): DriverBlueprintContract;
+    /**
+     * Establish connection to the PostgreSQL database.
+     *
+     * Creates a connection pool with the configured options.
+     * Emits 'connected' event on successful connection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the database connection pool.
+     *
+     * Waits for all active queries to complete before closing.
+     * Emits 'disconnected' event on successful disconnection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Register an event listener for driver lifecycle events.
+     *
+     * @param event - Event name ('connected', 'disconnected', etc.)
+     * @param listener - Callback function to invoke
+     */
+    on(event: string, listener: DriverEventListener): void;
+    /**
+     * Serialize data for storage in PostgreSQL.
+     *
+     * Handles Date objects, BigInt, and other JavaScript types
+     * that need special handling for PostgreSQL storage.
+     *
+     * @param data - The data object to serialize
+     * @returns Serialized data ready for PostgreSQL
+     */
+    serialize(data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Deserialize data retrieved from PostgreSQL.
+     *
+     * Converts PostgreSQL types back to JavaScript equivalents.
+     *
+     * @param data - The data object from PostgreSQL
+     * @returns Deserialized JavaScript object
+     */
+    deserialize(data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Insert a single row into a table.
+     *
+     * Uses INSERT ... RETURNING to get the inserted row with generated values.
+     *
+     * @param table - Target table name
+     * @param document - Data to insert
+     * @param options - Optional insertion options
+     * @returns The inserted document
+     */
+    insert(table: string, document: Record<string, unknown>, _options?: Record<string, unknown>): Promise<InsertResult>;
+    /**
+     * Insert multiple rows into a table.
+     *
+     * Uses a single INSERT statement with multiple value sets for efficiency.
+     *
+     * @param table - Target table name
+     * @param documents - Array of documents to insert
+     * @param options - Optional insertion options
+     * @returns Array of inserted documents
+     */
+    insertMany(table: string, documents: Record<string, unknown>[], _options?: Record<string, unknown>): Promise<InsertResult[]>;
+    /**
+     * Update a single row matching the filter.
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param update - Update operations ($set, $unset, $inc)
+     * @param options - Optional update options
+     * @returns Update result with modified count
+     */
+    update(table: string, filter: Record<string, unknown>, update: UpdateOperations, _options?: Record<string, unknown>): Promise<UpdateResult>;
+    /**
+     * Update multiple rows matching the filter.
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param update - Update operations
+     * @param options - Optional update options
+     * @returns Update result with modified count
+     */
+    updateMany(table: string, filter: Record<string, unknown>, update: UpdateOperations, _options?: Record<string, unknown>): Promise<UpdateResult>;
+    /**
+     * Replace a document matching the filter.
+     *
+     * Completely replaces the document (not a partial update).
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param document - New document data
+     * @param options - Optional options
+     * @returns The replaced document or null
+     */
+    replace<T = unknown>(table: string, filter: Record<string, unknown>, document: Record<string, unknown>, _options?: Record<string, unknown>): Promise<T | null>;
+    /**
+     * Delete a single row matching the filter.
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param options - Optional options
+     * @returns Number of deleted rows (0 or 1)
+     */
+    delete(table: string, filter?: Record<string, unknown>, _options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Delete multiple rows matching the filter.
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param options - Optional options
+     * @returns Number of deleted rows
+     */
+    deleteMany(table: string, filter?: Record<string, unknown>, _options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Truncate a table (remove all rows).
+     *
+     * Uses TRUNCATE TABLE for fast deletion with RESTART IDENTITY.
+     *
+     * @param table - Target table name
+     * @param options - Optional options
+     * @returns Number of deleted rows (always 0 for TRUNCATE)
+     */
+    truncateTable(table: string, _options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Get a query builder for the specified table.
+     *
+     * @param table - Target table name
+     * @returns Query builder instance
+     */
+    queryBuilder<T = unknown>(table: string): QueryBuilderContract<T>;
+    /**
+     * Begin a new database transaction.
+     *
+     * Acquires a client from the pool and starts a transaction.
+     * The client is stored in AsyncLocalStorage for automatic
+     * participation by subsequent queries.
+     *
+     * @param options - Optional transaction options
+     * @returns Transaction contract with commit/rollback methods
+     */
+    beginTransaction(options?: PostgresTransactionOptions): Promise<DriverTransactionContract<PgPoolClient>>;
+    /**
+     * Perform an atomic update operation.
+     *
+     * Uses PostgreSQL's row-level locking for atomicity.
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param operations - Update operations
+     * @param options - Optional options
+     * @returns Update result
+     */
+    atomic(table: string, filter: Record<string, unknown>, operations: UpdateOperations, _options?: Record<string, unknown>): Promise<UpdateResult>;
+    /**
+     * Get the sync adapter for bulk denormalized updates.
+     *
+     * @returns Sync adapter instance
+     */
+    syncAdapter(): SyncAdapterContract;
+    /**
+     * Get the migration driver for schema operations.
+     *
+     * @returns Migration driver instance
+     */
+    migrationDriver(): MigrationDriverContract;
+    /**
+     * Execute a raw SQL query.
+     *
+     * Automatically uses the transaction client if one is active.
+     *
+     * @param sql - SQL query string
+     * @param params - Query parameters
+     * @returns Query result
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<PostgresQueryResult<T>>;
+    /**
+     * Emit an event to all registered listeners.
+     *
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private emit;
+    /**
+     * Build a simple WHERE clause from a filter object.
+     *
+     * @param filter - Filter conditions
+     * @param startParamIndex - Starting parameter index
+     * @returns Object with WHERE clause string and parameters
+     */
+    private buildWhereClause;
+    /**
+     * Build an UPDATE query from update operations.
+     *
+     * @param table - Target table name
+     * @param filter - Filter conditions
+     * @param update - Update operations
+     * @param limit - Optional limit (for single row update)
+     * @returns Object with SQL and parameters
+     */
+    private buildUpdateQuery;
+    /**
+     * Create a new database.
+     *
+     * Note: This requires connecting to a system database (like 'postgres')
+     * since you cannot create a database while connected to it.
+     *
+     * @param name - Database name to create
+     * @param options - Creation options (encoding, template, etc.)
+     * @returns true if created, false if already exists
+     */
+    createDatabase(name: string, options?: CreateDatabaseOptions): Promise<boolean>;
+    /**
+     * Drop a database.
+     *
+     * @param name - Database name to drop
+     * @param options - Drop options
+     * @returns true if dropped, false if didn't exist
+     */
+    dropDatabase(name: string, options?: DropDatabaseOptions): Promise<boolean>;
+    /**
+     * Check if a database exists.
+     *
+     * @param name - Database name to check
+     * @returns true if database exists
+     */
+    databaseExists(name: string): Promise<boolean>;
+    /**
+     * List all databases.
+     *
+     * @returns Array of database names
+     */
+    listDatabases(): Promise<string[]>;
+    /**
+     * Drop a table.
+     *
+     * @param name - Table name to drop
+     * @throws Error if table doesn't exist
+     */
+    dropTable(name: string): Promise<void>;
+    /**
+     * Drop a table if it exists.
+     *
+     * @param name - Table name to drop
+     */
+    dropTableIfExists(name: string): Promise<void>;
+    /**
+     * Drop all tables in the current database.
+     *
+     * Uses CASCADE to handle foreign key dependencies.
+     * Useful for `migrate:fresh` command.
+     */
+    dropAllTables(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=postgres-driver.d.ts.map

package/esm/drivers/postgres/postgres-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-driver.d.ts","sourceRoot":"","sources":["../../../src/drivers/postgres/postgres-driver.ts"],"names":[],"mappings":"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"}