@warlock.js/cascade 4.0.171 → 4.1.1

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

@@ -0,0 +1,424 @@
+import { ModelDefaults } from "../../types.mjs";
+import { DriverBlueprintContract } from "../../contracts/driver-blueprint.contract.mjs";
+import { MigrationDriverContract } from "../../contracts/migration-driver.contract.mjs";
+import { DatabaseDriver } from "../../utils/connect-to-database.mjs";
+import { SQLSerializer } from "../../migration/sql-serializer.mjs";
+import { QueryBuilderContract } from "../../contracts/query-builder.contract.mjs";
+import { SyncAdapterContract } from "../../contracts/sync-adapter.contract.mjs";
+import { CreateDatabaseOptions, DriverContract, DriverEventListener, DriverTransactionContract, DropDatabaseOptions, InsertResult, TransactionContext, UpdateOperations, UpdateResult } from "../../contracts/database-driver.contract.mjs";
+import { SqlDatabaseDirtyTracker } from "../../sql-database-dirty-tracker.mjs";
+import { PostgresDialect } from "./postgres-dialect.mjs";
+import { PostgresPoolConfig, PostgresQueryResult, PostgresTransactionOptions } from "./types.mjs";
+
+//#region ../../@warlock.js/cascade/src/drivers/postgres/postgres-driver.d.ts
+/**
+ * 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();
+ * ```
+ */
+declare class PostgresDriver implements DriverContract {
+  private readonly config;
+  /**
+   * Driver name identifier.
+   */
+  readonly name: DatabaseDriver;
+  /**
+   * SQL dialect for PostgreSQL-specific syntax.
+   */
+  readonly dialect: PostgresDialect;
+  /**
+   * PostgreSQL driver model defaults.
+   *
+   * PostgreSQL follows SQL conventions:
+   * - snake_case naming for columns (created_at, updated_at, deleted_at)
+   * - Native AUTO_INCREMENT for IDs (no manual generation)
+   * - Timestamps enabled by default
+   * - Permanent delete strategy (hard deletes)
+   */
+  readonly modelDefaults: Partial<ModelDefaults>;
+  /**
+   * 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;
+  /**
+   * Get database native client
+   */
+  getClient<Client = PgPool>(): Client;
+  /**
+   * 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>;
+  /**
+   * Get the dirty tracker for this driver.
+   */
+  getDirtyTracker(data: Record<string, unknown>): SqlDatabaseDirtyTracker;
+  /**
+   * 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>;
+  /**
+   * Find one and update a single row matching the filter and return the updated row
+   * @param table - Target table name
+   * @param filter - Filter conditions
+   * @param update - Update operations ($set, $unset, $inc)
+   * @param options - Optional update options
+   * @returns The updated row or null
+   */
+  findOneAndUpdate<T = unknown>(table: string, filter: Record<string, unknown>, update: UpdateOperations, _options?: Record<string, unknown>): Promise<T | null>;
+  /**
+   * 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>;
+  /**
+   * Upsert (insert or update) a single row.
+   *
+   * Uses PostgreSQL's INSERT ... ON CONFLICT ... DO UPDATE syntax.
+   *
+   * @param table - Target table name
+   * @param filter - Filter conditions to find existing row (used for conflict detection)
+   * @param document - Document data to insert or update
+   * @param options - Upsert options (conflictColumns for conflict target)
+   * @returns The upserted row
+   */
+  upsert<T = unknown>(table: string, filter: Record<string, unknown>, document: Record<string, unknown>, options?: Record<string, unknown>): Promise<T>;
+  /**
+   * Find one and delete a single row matching the filter and return the deleted row.
+   *
+   * @param table - Target table name
+   * @param filter - Filter conditions
+   * @param options - Optional delete options
+   * @returns The deleted row or null
+   */
+  findOneAndDelete<T = unknown>(table: string, filter: 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
+   * @param options.cascade - If true, automatically truncate all tables with foreign key references (use with caution)
+   * @returns Number of deleted rows (always 0 for TRUNCATE)
+   */
+  truncateTable(table: string, options?: {
+    cascade?: boolean;
+  }): 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>>;
+  /**
+   * Execute a function within a transaction scope (recommended pattern).
+   *
+   * Automatically commits on success, rolls back on any error, and guarantees
+   * resource cleanup. This is the recommended way to use transactions.
+   *
+   * @param fn - Async function to execute within transaction
+   * @param options - Transaction options (isolation level, read-only, etc.)
+   * @returns The return value of the callback function
+   * @throws {Error} If transaction fails or is explicitly rolled back
+   */
+  transaction<T>(fn: (ctx: TransactionContext) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  /**
+   * Perform an atomic update operation.
+   *
+   * Builds and executes an UPDATE query for the given filter and operations.
+   *
+   * @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;
+  /**
+   * Return a SQL serializer for this driver's dialect.
+   * Used by Migration.toSQL() to convert pending operations to SQL strings.
+   */
+  getSQLSerializer(): SQLSerializer;
+  /**
+   * 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>;
+}
+//#endregion
+export { PostgresDriver };
+//# sourceMappingURL=postgres-driver.d.mts.map

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

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