@warlock.js/cascade 4.0.174 → 4.1.2

package/esm/drivers/postgres/postgres-migration-driver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-migration-driver.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/postgres/postgres-migration-driver.ts"],"sourcesContent":["/**\r\n * PostgreSQL Migration Driver\r\n *\r\n * Implements the MigrationDriverContract for PostgreSQL DDL operations.\r\n * Provides methods for creating/dropping tables, columns, indexes,\r\n * and constraints.\r\n *\r\n * @module cascade/drivers/postgres\r\n */\r\n\r\nimport { databaseTransactionContext } from \"../../context/database-transaction-context\";\r\nimport type {\r\n  ColumnDefinition,\r\n  ColumnType,\r\n  ForeignKeyDefinition,\r\n  FullTextIndexOptions,\r\n  GeoIndexOptions,\r\n  IndexDefinition,\r\n  MigrationDriverContract,\r\n  TableIndexInformation,\r\n  VectorIndexOptions,\r\n} from \"../../contracts/migration-driver.contract\";\r\nimport type { MigrationDefaults, UuidStrategy } from \"../../types\";\r\nimport type { PostgresDriver } from \"./postgres-driver\";\r\n\r\n/**\r\n * PostgreSQL Migration Driver.\r\n *\r\n * Handles database schema operations for PostgreSQL including:\r\n * - Table creation and deletion\r\n * - Column management\r\n * - Index creation (B-tree, GIN, GiST, etc.)\r\n * - Constraint management (foreign keys, unique, etc.)\r\n *\r\n * @example\r\n * ```typescript\r\n * const migrationDriver = driver.migrationDriver();\r\n *\r\n * // Create a table\r\n * await migrationDriver.createTable('users');\r\n *\r\n * // Add columns\r\n * await migrationDriver.addColumn('users', {\r\n *   name: 'email',\r\n *   type: 'string',\r\n *   length: 255,\r\n *   nullable: false\r\n * });\r\n *\r\n * // Create unique index\r\n * await migrationDriver.createUniqueIndex('users', ['email']);\r\n * ```\r\n */\r\nexport class PostgresMigrationDriver implements MigrationDriverContract {\r\n  /**\r\n   * Active transaction client (if any).\r\n   */\r\n  private get transactionClient(): unknown {\r\n    return databaseTransactionContext.getSession();\r\n  }\r\n\r\n  /**\r\n   * Create a new migration driver.\r\n   *\r\n   * @param driver - The PostgreSQL driver instance\r\n   */\r\n  public constructor(public readonly driver: PostgresDriver) {}\r\n\r\n  // ============================================================================\r\n  // TABLE OPERATIONS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Create a new table with a default id column.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async createTable(table: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    // Create empty table - columns are added via addColumn operations\r\n    await this.execute(`CREATE TABLE ${quotedTable} ()`);\r\n  }\r\n\r\n  /**\r\n   * Create table if it doesn't exist.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async createTableIfNotExists(table: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    // Create empty table if not exists - columns are added via addColumn operations\r\n    await this.execute(`CREATE TABLE IF NOT EXISTS ${quotedTable} ()`);\r\n  }\r\n\r\n  /**\r\n   * Drop an existing table.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async dropTable(table: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    await this.execute(`DROP TABLE ${quotedTable} CASCADE`);\r\n  }\r\n\r\n  /**\r\n   * Drop table if it exists.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async dropTableIfExists(table: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    await this.execute(`DROP TABLE IF EXISTS ${quotedTable} CASCADE`);\r\n  }\r\n\r\n  /**\r\n   * Rename a table.\r\n   *\r\n   * @param from - Current table name\r\n   * @param to - New table name\r\n   */\r\n  public async renameTable(from: string, to: string): Promise<void> {\r\n    const quotedFrom = this.driver.dialect.quoteIdentifier(from);\r\n    const quotedTo = this.driver.dialect.quoteIdentifier(to);\r\n    await this.execute(`ALTER TABLE ${quotedFrom} RENAME TO ${quotedTo}`);\r\n  }\r\n\r\n  /**\r\n   * Truncate a table — remove all rows efficiently.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async truncateTable(table: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    await this.execute(`TRUNCATE TABLE ${quotedTable}`);\r\n  }\r\n\r\n  /**\r\n   * Check if a table exists.\r\n   *\r\n   * @param table - Table name\r\n   * @returns Whether the table exists\r\n   */\r\n  public async tableExists(table: string): Promise<boolean> {\r\n    const result = await this.driver.query<{ exists: boolean }>(\r\n      `SELECT EXISTS (\r\n        SELECT FROM information_schema.tables\r\n        WHERE table_schema = 'public'\r\n        AND table_name = $1\r\n      )`,\r\n      [table],\r\n    );\r\n    return result.rows[0]?.exists ?? false;\r\n  }\r\n\r\n  /**\r\n   * List all columns in a table.\r\n   *\r\n   * @param table - Table name\r\n   * @returns Array of column definitions\r\n   */\r\n  public async listColumns(table: string): Promise<ColumnDefinition[]> {\r\n    const result = await this.driver.query<{\r\n      column_name: string;\r\n      data_type: string;\r\n      character_maximum_length: number | null;\r\n      numeric_precision: number | null;\r\n      numeric_scale: number | null;\r\n      is_nullable: string;\r\n      column_default: string | null;\r\n    }>(\r\n      `SELECT\r\n        column_name,\r\n        data_type,\r\n        character_maximum_length,\r\n        numeric_precision,\r\n        numeric_scale,\r\n        is_nullable,\r\n        column_default\r\n      FROM information_schema.columns\r\n      WHERE table_schema = 'public'\r\n      AND table_name = $1\r\n      ORDER BY ordinal_position`,\r\n      [table],\r\n    );\r\n\r\n    return result.rows.map((row) => ({\r\n      name: row.column_name,\r\n      type: this.mapPostgresTypeToColumnType(row.data_type),\r\n      length: row.character_maximum_length ?? undefined,\r\n      precision: row.numeric_precision ?? undefined,\r\n      scale: row.numeric_scale ?? undefined,\r\n      nullable: row.is_nullable === \"YES\",\r\n      defaultValue: row.column_default ?? undefined,\r\n    }));\r\n  }\r\n\r\n  /**\r\n   * List all tables in the current database.\r\n   *\r\n   * @returns Array of table names\r\n   */\r\n  public async listTables(): Promise<string[]> {\r\n    const result = await this.driver.query<{ table_name: string }>(\r\n      `SELECT table_name\r\n       FROM information_schema.tables\r\n       WHERE table_schema = 'public'\r\n       ORDER BY table_name`,\r\n    );\r\n\r\n    return result.rows.map((row) => row.table_name);\r\n  }\r\n\r\n  /**\r\n   * Ensure the migrations tracking table exists.\r\n   *\r\n   * Creates the table with proper schema if it doesn't exist.\r\n   *\r\n   * @param tableName - Name of the migrations table\r\n   */\r\n  public async ensureMigrationsTable(tableName: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(tableName);\r\n\r\n    await this.execute(`\r\n      CREATE TABLE IF NOT EXISTS ${quotedTable} (\r\n        \"id\" SERIAL PRIMARY KEY,\r\n        \"name\" VARCHAR(255) NOT NULL UNIQUE,\r\n        \"batch\" INTEGER NOT NULL,\r\n        \"executedAt\" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),\r\n        \"createdAt\" TIMESTAMP WITH TIME ZONE\r\n      )\r\n    `);\r\n  }\r\n\r\n  // ============================================================================\r\n  // COLUMN OPERATIONS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Add a column to an existing table.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Column definition\r\n   */\r\n  public async addColumn(table: string, column: ColumnDefinition): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(column.name);\r\n\r\n    // For auto-increment integers, use SERIAL/BIGSERIAL instead of INTEGER/BIGINT\r\n    let sqlType: string;\r\n    if (column.autoIncrement) {\r\n      if (column.type === \"bigInteger\") {\r\n        sqlType = \"BIGSERIAL\";\r\n      } else {\r\n        sqlType = \"SERIAL\";\r\n      }\r\n    } else {\r\n      sqlType = this.driver.dialect.getSqlType(column.type, {\r\n        length: column.length,\r\n        precision: column.precision,\r\n        scale: column.scale,\r\n        dimensions: column.dimensions,\r\n      });\r\n    }\r\n\r\n    let sql = `ALTER TABLE ${quotedTable} ADD COLUMN ${quotedColumn} ${sqlType}`;\r\n\r\n    // Handle generated columns\r\n    if (column.generated) {\r\n      sql += ` GENERATED ALWAYS AS (${column.generated.expression})`;\r\n      if (column.generated.stored) {\r\n        sql += \" STORED\";\r\n      }\r\n      // PostgreSQL only supports STORED, not VIRTUAL\r\n      // If virtual is requested, it's simply ignored (PostgreSQL doesn't support it)\r\n    } else {\r\n      // SERIAL/BIGSERIAL are always NOT NULL, so skip for those\r\n      if (!column.autoIncrement && column.nullable === false) {\r\n        sql += \" NOT NULL\";\r\n      }\r\n\r\n      if (column.defaultValue !== undefined) {\r\n        // Check for special CURRENT_TIMESTAMP marker\r\n        if (\r\n          typeof column.defaultValue === \"object\" &&\r\n          column.defaultValue !== null &&\r\n          (column.defaultValue as any).__type === \"CURRENT_TIMESTAMP\"\r\n        ) {\r\n          sql += \" DEFAULT NOW()\";\r\n        } else if (column.isRawDefault === false) {\r\n          // Explicit string literal - escape it properly\r\n          const escaped = String(column.defaultValue).replace(/'/g, \"''\");\r\n          sql += ` DEFAULT '${escaped}'`;\r\n        } else if (typeof column.defaultValue === \"boolean\") {\r\n          // Boolean values\r\n          sql += ` DEFAULT ${column.defaultValue ? \"TRUE\" : \"FALSE\"}`;\r\n        } else if (typeof column.defaultValue === \"number\") {\r\n          // Numeric values\r\n          sql += ` DEFAULT ${column.defaultValue}`;\r\n        } else {\r\n          // Raw SQL expression (default behavior when isRawDefault is true or undefined)\r\n          sql += ` DEFAULT ${column.defaultValue}`;\r\n        }\r\n      }\r\n\r\n      // Handle primary key\r\n      if (column.primary) {\r\n        sql += \" PRIMARY KEY\";\r\n      }\r\n\r\n      // Handle unique constraint\r\n      if (column.unique) {\r\n        sql += \" UNIQUE\";\r\n      }\r\n    }\r\n\r\n    await this.execute(sql);\r\n  }\r\n\r\n  /**\r\n   * Drop a column from a table.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Column name\r\n   */\r\n  public async dropColumn(table: string, column: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(column);\r\n    await this.execute(`ALTER TABLE ${quotedTable} DROP COLUMN ${quotedColumn}`);\r\n  }\r\n\r\n  /**\r\n   * Drop multiple columns from a table.\r\n   *\r\n   * @param table - Table name\r\n   * @param columns - Column names\r\n   */\r\n  public async dropColumns(table: string, columns: string[]): Promise<void> {\r\n    for (const column of columns) {\r\n      await this.dropColumn(table, column);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Rename a column.\r\n   *\r\n   * @param table - Table name\r\n   * @param from - Current column name\r\n   * @param to - New column name\r\n   */\r\n  public async renameColumn(table: string, from: string, to: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedFrom = this.driver.dialect.quoteIdentifier(from);\r\n    const quotedTo = this.driver.dialect.quoteIdentifier(to);\r\n    await this.execute(`ALTER TABLE ${quotedTable} RENAME COLUMN ${quotedFrom} TO ${quotedTo}`);\r\n  }\r\n\r\n  /**\r\n   * Modify an existing column.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - New column definition\r\n   */\r\n  public async modifyColumn(table: string, column: ColumnDefinition): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(column.name);\r\n    const sqlType = this.driver.dialect.getSqlType(column.type, {\r\n      length: column.length,\r\n      precision: column.precision,\r\n      scale: column.scale,\r\n      dimensions: column.dimensions,\r\n    });\r\n\r\n    // PostgreSQL requires separate ALTER statements for type and nullability\r\n    await this.execute(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedColumn} TYPE ${sqlType}`);\r\n\r\n    if (column.nullable === false) {\r\n      await this.execute(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedColumn} SET NOT NULL`);\r\n    } else if (column.nullable === true) {\r\n      await this.execute(`ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedColumn} DROP NOT NULL`);\r\n    }\r\n\r\n    if (column.defaultValue !== undefined) {\r\n      let defaultVal: string;\r\n\r\n      // Check for special CURRENT_TIMESTAMP marker\r\n      if (\r\n        typeof column.defaultValue === \"object\" &&\r\n        column.defaultValue !== null &&\r\n        (column.defaultValue as any).__type === \"CURRENT_TIMESTAMP\"\r\n      ) {\r\n        defaultVal = \"NOW()\";\r\n      } else if (typeof column.defaultValue === \"string\") {\r\n        defaultVal = `'${column.defaultValue}'`;\r\n      } else {\r\n        defaultVal = String(column.defaultValue);\r\n      }\r\n\r\n      await this.execute(\r\n        `ALTER TABLE ${quotedTable} ALTER COLUMN ${quotedColumn} SET DEFAULT ${defaultVal}`,\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Create standard timestamp columns (created_at, updated_at).\r\n   *\r\n   * PostgreSQL implementation creates TIMESTAMPTZ columns with NOW() defaults.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async createTimestampColumns(table: string): Promise<void> {\r\n    await this.addColumn(table, {\r\n      name: \"created_at\",\r\n      type: \"timestamp\",\r\n      nullable: false,\r\n      defaultValue: \"NOW()\",\r\n      isRawDefault: true,\r\n    });\r\n\r\n    await this.addColumn(table, {\r\n      name: \"updated_at\",\r\n      type: \"timestamp\",\r\n      nullable: false,\r\n      defaultValue: \"NOW()\",\r\n      isRawDefault: true,\r\n    });\r\n  }\r\n\r\n  // ============================================================================\r\n  // INDEX OPERATIONS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Create an index on one or more columns.\r\n   *\r\n   * Supports:\r\n   * - Regular column indexes\r\n   * - Expression-based indexes (e.g., `lower(email)`)\r\n   * - Covering indexes (INCLUDE clause)\r\n   * - Concurrent index creation (CONCURRENTLY keyword)\r\n   *\r\n   * @param table - Table name\r\n   * @param index - Index definition\r\n   */\r\n  public async createIndex(table: string, index: IndexDefinition): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const indexName = index.name ?? `idx_${table}_${index.columns.join(\"_\")}`;\r\n    const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);\r\n    const uniqueKeyword = index.unique ? \"UNIQUE \" : \"\";\r\n    const concurrentlyKeyword = index.concurrently ? \"CONCURRENTLY \" : \"\";\r\n\r\n    let columnsPart: string;\r\n\r\n    // Handle expression-based indexes\r\n    if (index.expressions && index.expressions.length > 0) {\r\n      // Wrap each expression in parentheses\r\n      columnsPart = index.expressions.map((expr) => `(${expr})`).join(\", \");\r\n    } else {\r\n      // Regular column indexes\r\n      const columns = index.columns.map((col, i) => {\r\n        const quotedCol = this.driver.dialect.quoteIdentifier(col);\r\n        const direction = index.directions?.[i]?.toUpperCase() ?? \"\";\r\n        return direction ? `${quotedCol} ${direction}` : quotedCol;\r\n      });\r\n      columnsPart = columns.join(\", \");\r\n    }\r\n\r\n    let sql = `CREATE ${uniqueKeyword}INDEX ${concurrentlyKeyword}${quotedIndexName} ON ${quotedTable} (${columnsPart})`;\r\n\r\n    // Add INCLUDE clause for covering indexes\r\n    if (index.include && index.include.length > 0) {\r\n      const includeCols = index.include\r\n        .map((col) => this.driver.dialect.quoteIdentifier(col))\r\n        .join(\", \");\r\n      sql += ` INCLUDE (${includeCols})`;\r\n    }\r\n\r\n    // Add partial index condition\r\n    if (index.where && Object.keys(index.where).length > 0) {\r\n      const conditions = Object.entries(index.where)\r\n        .map(([key, value]) => {\r\n          const quotedKey = this.driver.dialect.quoteIdentifier(key);\r\n          return typeof value === \"string\"\r\n            ? `${quotedKey} = '${value}'`\r\n            : `${quotedKey} = ${value}`;\r\n        })\r\n        .join(\" AND \");\r\n      sql += ` WHERE ${conditions}`;\r\n    }\r\n\r\n    await this.execute(sql);\r\n  }\r\n\r\n  /**\r\n   * Drop an index.\r\n   *\r\n   * @param table - Table name\r\n   * @param indexNameOrColumns - Index name or columns\r\n   */\r\n  public async dropIndex(table: string, indexNameOrColumns: string | string[]): Promise<void> {\r\n    let indexName: string;\r\n\r\n    if (typeof indexNameOrColumns === \"string\") {\r\n      indexName = indexNameOrColumns;\r\n    } else {\r\n      indexName = `idx_${table}_${indexNameOrColumns.join(\"_\")}`;\r\n    }\r\n\r\n    const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);\r\n    await this.execute(`DROP INDEX IF EXISTS ${quotedIndexName}`);\r\n  }\r\n\r\n  /**\r\n   * Create a unique index.\r\n   *\r\n   * @param table - Table name\r\n   * @param columns - Columns to include\r\n   * @param name - Optional index name\r\n   */\r\n  public async createUniqueIndex(table: string, columns: string[], name?: string): Promise<void> {\r\n    await this.createIndex(table, { columns, unique: true, name });\r\n  }\r\n\r\n  /**\r\n   * Drop a unique index.\r\n   *\r\n   * @param table - Table name\r\n   * @param columns - Columns in the index\r\n   */\r\n  public async dropUniqueIndex(table: string, columns: string[]): Promise<void> {\r\n    await this.dropIndex(table, columns);\r\n  }\r\n\r\n  // ============================================================================\r\n  // SPECIALIZED INDEXES\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Create a full-text search index using GIN.\r\n   *\r\n   * @param table - Table name\r\n   * @param columns - Columns to index\r\n   * @param options - Full-text options\r\n   */\r\n  public async createFullTextIndex(\r\n    table: string,\r\n    columns: string[],\r\n    options?: FullTextIndexOptions,\r\n  ): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const indexName = options?.name ?? `idx_${table}_fulltext_${columns.join(\"_\")}`;\r\n    const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);\r\n    const language = options?.language ?? \"english\";\r\n\r\n    const tsvectors = columns.map((col) => {\r\n      const weight = options?.weights?.[col] ?? \"A\";\r\n      return `setweight(to_tsvector('${language}', COALESCE(${this.driver.dialect.quoteIdentifier(col)}, '')), '${weight}')`;\r\n    });\r\n\r\n    await this.execute(\r\n      `CREATE INDEX ${quotedIndexName} ON ${quotedTable} USING GIN ((${tsvectors.join(\" || \")}))`,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Drop a full-text search index.\r\n   *\r\n   * @param table - Table name\r\n   * @param name - Index name\r\n   */\r\n  public async dropFullTextIndex(table: string, name: string): Promise<void> {\r\n    await this.dropIndex(table, name);\r\n  }\r\n\r\n  /**\r\n   * Create a geo-spatial index using GiST.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Geo column\r\n   * @param options - Geo index options\r\n   */\r\n  public async createGeoIndex(\r\n    table: string,\r\n    column: string,\r\n    options?: GeoIndexOptions,\r\n  ): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(column);\r\n    const indexName = options?.name ?? `idx_${table}_geo_${column}`;\r\n    const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);\r\n\r\n    await this.execute(\r\n      `CREATE INDEX ${quotedIndexName} ON ${quotedTable} USING GIST (${quotedColumn})`,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Drop a geo-spatial index.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Geo column\r\n   */\r\n  public async dropGeoIndex(table: string, column: string): Promise<void> {\r\n    await this.dropIndex(table, `idx_${table}_geo_${column}`);\r\n  }\r\n\r\n  /**\r\n   * Create a vector search index (requires pgvector extension).\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Vector column\r\n   * @param options - Vector index options\r\n   */\r\n  public async createVectorIndex(\r\n    table: string,\r\n    column: string,\r\n    options: VectorIndexOptions,\r\n  ): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(column);\r\n    const indexName = options.name ?? `idx_${table}_vector_${column}`;\r\n    const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);\r\n\r\n    // Map similarity to pgvector operator class\r\n    const opClass =\r\n      options.similarity === \"euclidean\"\r\n        ? \"vector_l2_ops\"\r\n        : options.similarity === \"dotProduct\"\r\n          ? \"vector_ip_ops\"\r\n          : \"vector_cosine_ops\";\r\n\r\n    const lists = options.lists ?? 100;\r\n\r\n    await this.execute(\r\n      `CREATE INDEX ${quotedIndexName} ON ${quotedTable} USING ivfflat (${quotedColumn} ${opClass}) WITH (lists = ${lists})`,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Drop a vector search index.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Vector column\r\n   */\r\n  public async dropVectorIndex(table: string, column: string): Promise<void> {\r\n    await this.dropIndex(table, `idx_${table}_vector_${column}`);\r\n  }\r\n\r\n  /**\r\n   * Create a TTL index (not natively supported in PostgreSQL).\r\n   *\r\n   * Note: PostgreSQL doesn't have native TTL indexes like MongoDB.\r\n   * This creates a partial index and requires a scheduled job for cleanup.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Date column\r\n   * @param expireAfterSeconds - Expiration time in seconds\r\n   */\r\n  public async createTTLIndex(\r\n    table: string,\r\n    column: string,\r\n    expireAfterSeconds: number,\r\n  ): Promise<void> {\r\n    // Create a partial index for expired rows (for efficient cleanup queries)\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(column);\r\n    const indexName = `idx_${table}_ttl_${column}`;\r\n    const quotedIndexName = this.driver.dialect.quoteIdentifier(indexName);\r\n\r\n    await this.execute(\r\n      `CREATE INDEX ${quotedIndexName} ON ${quotedTable} (${quotedColumn}) WHERE ${quotedColumn} < NOW() - INTERVAL '${expireAfterSeconds} seconds'`,\r\n    );\r\n\r\n    // Note: User must set up a scheduled job (pg_cron, etc.) to:\r\n    // DELETE FROM table WHERE column < NOW() - INTERVAL 'X seconds'\r\n  }\r\n\r\n  /**\r\n   * Drop a TTL index.\r\n   *\r\n   * @param table - Table name\r\n   * @param column - Column with TTL index\r\n   */\r\n  public async dropTTLIndex(table: string, column: string): Promise<void> {\r\n    await this.dropIndex(table, `idx_${table}_ttl_${column}`);\r\n  }\r\n\r\n  /**\r\n   * List all indexes on a table.\r\n   *\r\n   * @param table - Table name\r\n   * @returns Array of index metadata\r\n   */\r\n  public async listIndexes(table: string): Promise<TableIndexInformation[]> {\r\n    const result = await this.driver.query<{ indexname: string; indexdef: string }>(\r\n      `SELECT indexname, indexdef FROM pg_indexes WHERE schemaname = 'public' AND tablename = $1`,\r\n      [table],\r\n    );\r\n\r\n    return result.rows.map((row) => {\r\n      const isUnique = row.indexdef.includes(\"UNIQUE\");\r\n      const isPrimary = row.indexname.endsWith(\"_pkey\");\r\n      const columnsMatch = row.indexdef.match(/\\(([^)]+)\\)/);\r\n      const columns = columnsMatch\r\n        ? columnsMatch[1].split(\",\").map((c) => c.trim().replace(/\"/g, \"\"))\r\n        : [];\r\n\r\n      let type = \"btree\";\r\n      if (row.indexdef.includes(\"USING GIN\")) type = \"gin\";\r\n      else if (row.indexdef.includes(\"USING GIST\")) type = \"gist\";\r\n      else if (row.indexdef.includes(\"USING HASH\")) type = \"hash\";\r\n      else if (row.indexdef.includes(\"USING ivfflat\")) type = \"ivfflat\";\r\n\r\n      return {\r\n        name: row.indexname,\r\n        columns,\r\n        type,\r\n        unique: isUnique || isPrimary,\r\n        partial: row.indexdef.includes(\"WHERE\"),\r\n        options: { primary: isPrimary, definition: row.indexdef },\r\n      };\r\n    });\r\n  }\r\n\r\n  // ============================================================================\r\n  // EXTENSIONS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Check if a PostgreSQL extension is available on the database server.\r\n   *\r\n   * @param extension - Extension name (e.g., \"vector\")\r\n   */\r\n  public async isExtensionAvailable(extension: string): Promise<boolean> {\r\n    try {\r\n      const result = await this.driver.query<{ name: string }>(\r\n        `SELECT name FROM pg_available_extensions WHERE name = $1`,\r\n        [extension],\r\n      );\r\n\r\n      return result?.rows?.length > 0;\r\n    } catch {\r\n      // If we can't check (e.g., permissions issue or pg_available_extensions not accessible),\r\n      // we return true to avoid false positives. Execution will just proceed and fail naturally if it's missing.\r\n      return true;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get the official documentation or installation URL for a PostgreSQL extension.\r\n   *\r\n   * @param extension - Extension name\r\n   */\r\n  public getExtensionDocsUrl(extension: string): string | undefined {\r\n    const guideUrls: Record<string, string> = {\r\n      vector: \"https://github.com/pgvector/pgvector#installation\",\r\n      postgis: \"https://postgis.net/documentation/getting_started/\",\r\n      pg_trgm: \"https://www.postgresql.org/docs/current/pgtrgm.html\",\r\n      uuid_ossp: \"https://www.postgresql.org/docs/current/uuid-ossp.html\",\r\n    };\r\n\r\n    return guideUrls[extension] ?? `https://www.postgresql.org/docs/current/${extension}.html`;\r\n  }\r\n\r\n  // ============================================================================\r\n  // CONSTRAINTS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Add a foreign key constraint.\r\n   *\r\n   * @param table - Table name\r\n   * @param foreignKey - Foreign key definition\r\n   */\r\n  public async addForeignKey(table: string, foreignKey: ForeignKeyDefinition): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumn = this.driver.dialect.quoteIdentifier(foreignKey.column);\r\n    const quotedRefTable = this.driver.dialect.quoteIdentifier(foreignKey.referencesTable);\r\n    const quotedRefColumn = this.driver.dialect.quoteIdentifier(foreignKey.referencesColumn);\r\n\r\n    const constraintName =\r\n      foreignKey.name ?? `fk_${table}_${foreignKey.column}_${foreignKey.referencesTable}`;\r\n    const quotedConstraint = this.driver.dialect.quoteIdentifier(constraintName);\r\n\r\n    let sql = `ALTER TABLE ${quotedTable} ADD CONSTRAINT ${quotedConstraint} FOREIGN KEY (${quotedColumn}) REFERENCES ${quotedRefTable} (${quotedRefColumn})`;\r\n\r\n    if (foreignKey.onDelete) {\r\n      sql += ` ON DELETE ${this.mapForeignKeyAction(foreignKey.onDelete)}`;\r\n    }\r\n\r\n    if (foreignKey.onUpdate) {\r\n      sql += ` ON UPDATE ${this.mapForeignKeyAction(foreignKey.onUpdate)}`;\r\n    }\r\n\r\n    await this.execute(sql);\r\n  }\r\n\r\n  /**\r\n   * Drop a foreign key constraint.\r\n   *\r\n   * @param table - Table name\r\n   * @param name - Constraint name\r\n   */\r\n  public async dropForeignKey(table: string, name: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedConstraint = this.driver.dialect.quoteIdentifier(name);\r\n    await this.execute(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quotedConstraint}`);\r\n  }\r\n\r\n  /**\r\n   * Add a primary key constraint.\r\n   *\r\n   * @param table - Table name\r\n   * @param columns - Primary key columns\r\n   */\r\n  public async addPrimaryKey(table: string, columns: string[]): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedColumns = columns.map((c) => this.driver.dialect.quoteIdentifier(c)).join(\", \");\r\n    const constraintName = `pk_${table}`;\r\n    const quotedConstraint = this.driver.dialect.quoteIdentifier(constraintName);\r\n\r\n    await this.execute(\r\n      `ALTER TABLE ${quotedTable} ADD CONSTRAINT ${quotedConstraint} PRIMARY KEY (${quotedColumns})`,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Drop the primary key constraint.\r\n   *\r\n   * @param table - Table name\r\n   */\r\n  public async dropPrimaryKey(table: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const constraintName = `pk_${table}`;\r\n    const quotedConstraint = this.driver.dialect.quoteIdentifier(constraintName);\r\n\r\n    await this.execute(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quotedConstraint}`);\r\n  }\r\n\r\n  /**\r\n   * Add a CHECK constraint.\r\n   *\r\n   * @param table - Table name\r\n   * @param name - Constraint name\r\n   * @param expression - SQL CHECK expression\r\n   */\r\n  public async addCheck(table: string, name: string, expression: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedName = this.driver.dialect.quoteIdentifier(name);\r\n    const sql = `ALTER TABLE ${quotedTable} ADD CONSTRAINT ${quotedName} CHECK (${expression})`;\r\n    await this.execute(sql);\r\n  }\r\n\r\n  /**\r\n   * Drop a CHECK constraint.\r\n   *\r\n   * @param table - Table name\r\n   * @param name - Constraint name\r\n   */\r\n  public async dropCheck(table: string, name: string): Promise<void> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedName = this.driver.dialect.quoteIdentifier(name);\r\n    await this.execute(`ALTER TABLE ${quotedTable} DROP CONSTRAINT ${quotedName}`);\r\n  }\r\n\r\n  // ============================================================================\r\n  // SCHEMA VALIDATION (NOT APPLICABLE FOR PostgreSQL)\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Set schema validation (no-op for PostgreSQL).\r\n   *\r\n   * PostgreSQL uses column constraints instead.\r\n   */\r\n  public async setSchemaValidation(_table: string, _schema: object): Promise<void> {\r\n    // No-op: PostgreSQL doesn't have MongoDB-style schema validation\r\n    // Use CHECK constraints instead\r\n  }\r\n\r\n  /**\r\n   * Remove schema validation (no-op for PostgreSQL).\r\n   */\r\n  public async removeSchemaValidation(_table: string): Promise<void> {\r\n    // No-op\r\n  }\r\n\r\n  // ============================================================================\r\n  // TRANSACTIONS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Begin a transaction.\r\n   */\r\n  public async beginTransaction(): Promise<void> {\r\n    await this.execute(\"BEGIN\");\r\n  }\r\n\r\n  /**\r\n   * Commit the current transaction.\r\n   */\r\n  public async commit(): Promise<void> {\r\n    await this.execute(\"COMMIT\");\r\n  }\r\n\r\n  /**\r\n   * Rollback the current transaction.\r\n   */\r\n  public async rollback(): Promise<void> {\r\n    await this.execute(\"ROLLBACK\");\r\n  }\r\n\r\n  /**\r\n   * Whether transactions are supported.\r\n   */\r\n  public supportsTransactions(): boolean {\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Get the default transactional behavior for PostgreSQL.\r\n   *\r\n   * PostgreSQL supports transactional DDL operations, so migrations\r\n   * are wrapped in transactions by default for atomicity and safety.\r\n   *\r\n   * @returns true (PostgreSQL DDL is transactional)\r\n   */\r\n  public getDefaultTransactional(): boolean {\r\n    return true;\r\n  }\r\n\r\n  // ============================================================================\r\n  // DEFAULTS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Get the default UUID generation expression for PostgreSQL.\r\n   *\r\n   * Resolution order:\r\n   * 1. `migrationDefaults.uuidExpression` → raw expression (escape hatch)\r\n   * 2. `migrationDefaults.uuidStrategy` → mapped to PG function\r\n   * 3. Fallback → `gen_random_uuid()` (v4, PG 13+)\r\n   *\r\n   * @param migrationDefaults - Optional overrides from DataSource config\r\n   * @returns PostgreSQL SQL expression for UUID generation\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * driver.getUuidDefault(); // \"gen_random_uuid()\"\r\n   * driver.getUuidDefault({ uuidStrategy: \"v7\" }); // \"uuidv7()\"\r\n   * driver.getUuidDefault({ uuidExpression: \"uuid_generate_v1mc()\" }); // \"uuid_generate_v1mc()\"\r\n   * ```\r\n   */\r\n  public getUuidDefault(migrationDefaults?: MigrationDefaults): string {\r\n    // Escape hatch: raw expression takes highest precedence\r\n    if (migrationDefaults?.uuidExpression) {\r\n      return migrationDefaults.uuidExpression;\r\n    }\r\n\r\n    const strategy = migrationDefaults?.uuidStrategy ?? \"v4\";\r\n\r\n    const strategyMap: Record<UuidStrategy, string> = {\r\n      v4: \"gen_random_uuid()\",\r\n      v7: \"uuidv7()\",\r\n    };\r\n\r\n    return strategyMap[strategy];\r\n  }\r\n\r\n  // ============================================================================\r\n  // RAW ACCESS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Execute raw operations with direct driver access.\r\n   *\r\n   * @param callback - Callback receiving the driver\r\n   */\r\n  public async raw<T>(callback: (connection: unknown) => Promise<T>): Promise<T> {\r\n    return callback(this.driver);\r\n  }\r\n\r\n  // ============================================================================\r\n  // HELPERS\r\n  // ============================================================================\r\n\r\n  /**\r\n   * Execute a SQL statement.\r\n   *\r\n   * @param sql - SQL to execute\r\n   * @param params - Query parameters\r\n   */\r\n  private async execute(sql: string, params: unknown[] = []): Promise<void> {\r\n    await this.driver.query(sql, params);\r\n  }\r\n\r\n  /**\r\n   * Map foreign key action to PostgreSQL syntax.\r\n   */\r\n  private mapForeignKeyAction(action: \"cascade\" | \"restrict\" | \"setNull\" | \"noAction\"): string {\r\n    const mapping: Record<string, string> = {\r\n      cascade: \"CASCADE\",\r\n      restrict: \"RESTRICT\",\r\n      setNull: \"SET NULL\",\r\n      noAction: \"NO ACTION\",\r\n    };\r\n    return mapping[action] ?? \"NO ACTION\";\r\n  }\r\n\r\n  /**\r\n   * Map PostgreSQL data type to ColumnType.\r\n   */\r\n  private mapPostgresTypeToColumnType(pgType: string): ColumnType {\r\n    const typeMap: Record<string, ColumnType> = {\r\n      \"character varying\": \"string\",\r\n      varchar: \"string\",\r\n      character: \"char\",\r\n      char: \"char\",\r\n      text: \"text\",\r\n      integer: \"integer\",\r\n      int: \"integer\",\r\n      smallint: \"smallInteger\",\r\n      bigint: \"bigInteger\",\r\n      real: \"float\",\r\n      \"double precision\": \"double\",\r\n      numeric: \"decimal\",\r\n      decimal: \"decimal\",\r\n      boolean: \"boolean\",\r\n      date: \"date\",\r\n      timestamp: \"dateTime\",\r\n      \"timestamp without time zone\": \"dateTime\",\r\n      \"timestamp with time zone\": \"timestamp\",\r\n      time: \"time\",\r\n      \"time without time zone\": \"time\",\r\n      json: \"json\",\r\n      jsonb: \"json\",\r\n      bytea: \"binary\",\r\n      uuid: \"uuid\",\r\n      inet: \"ipAddress\",\r\n      macaddr: \"macAddress\",\r\n      point: \"point\",\r\n      polygon: \"polygon\",\r\n      line: \"lineString\",\r\n      geometry: \"geometry\",\r\n      // PostgreSQL array types\r\n      \"integer[]\": \"arrayInt\",\r\n      \"int[]\": \"arrayInt\",\r\n      \"bigint[]\": \"arrayBigInt\",\r\n      \"real[]\": \"arrayFloat\",\r\n      \"decimal[]\": \"arrayDecimal\",\r\n      \"numeric[]\": \"arrayDecimal\",\r\n      \"boolean[]\": \"arrayBoolean\",\r\n      \"text[]\": \"arrayText\",\r\n      \"date[]\": \"arrayDate\",\r\n      \"timestamp with time zone[]\": \"arrayTimestamp\",\r\n      \"timestamptz[]\": \"arrayTimestamp\",\r\n      \"uuid[]\": \"arrayUuid\",\r\n      \"jsonb[]\": \"arrayJson\",\r\n      \"json[]\": \"arrayJson\",\r\n    };\r\n\r\n    return typeMap[pgType.toLowerCase()] ?? \"string\";\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/drivers/postgres/postgres-query-builder.d.mts

@@ -0,0 +1,399 @@
+import { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, DriverQuery, GroupByInput, PaginationOptions, PaginationResult, QueryBuilderContract, RawExpression } from "../../contracts/query-builder.contract.mjs";
+import { DataSource } from "../../data-source/data-source.mjs";
+import { ModelRef } from "../../model/register-model.mjs";
+import { Op, QueryBuilder } from "../../query-builder/query-builder.mjs";
+import { GenericObject } from "@mongez/reinforcements";
+
+//#region ../../@warlock.js/cascade/src/drivers/postgres/postgres-query-builder.d.ts
+type JoinRelationConfig = {
+  alias: string;
+  type: "belongsTo" | "hasOne" | "hasMany";
+  model?: ModelRef;
+  localKey?: string;
+  foreignKey?: string;
+  ownerKey?: string;
+  parentPath?: string | null;
+  relationName?: string;
+  parentModel?: ModelRef;
+  select?: string[]; /** Operations recorded by a joinWith constraint callback. */
+  constraintOps?: Op[];
+};
+/**
+ * PostgreSQL Query Builder.
+ *
+ * Collects query operations (via the base class) and delegates SQL generation
+ * to `PostgresQueryParser`. Owns execution, hydration, and relation loading.
+ *
+ * @example
+ * ```typescript
+ * const users = await User.query()
+ *   .select(["id", "name", "email"])
+ *   .where("status", "active")
+ *   .orderBy("createdAt", "desc")
+ *   .limit(10)
+ *   .get();
+ * ```
+ */
+declare class PostgresQueryBuilder<T = unknown> extends QueryBuilder<T> implements QueryBuilderContract<T> {
+  readonly table: string;
+  /** Data source backing this builder. */
+  readonly dataSource: DataSource;
+  /** Hydration callback for transforming result rows into model instances. */
+  hydrateCallback?: (data: unknown, index: number) => unknown;
+  /** Invoked before query execution. */
+  private fetchingCallback?;
+  /** Invoked after fetch but before hydration. */
+  private hydratingCallback?;
+  /** Invoked after fetch and hydration. */
+  private fetchedCallback?;
+  /**
+   * Map of relations registered via `joinWith()`.
+   * Keyed by dot-notation path (e.g. "organizationAiModel.aiModel").
+   */
+  joinRelations: Map<string, JoinRelationConfig>;
+  /**
+   * Idempotency guard for `applyJoinRelations()` so calling `parse()` then
+   * `get()` (or `parse()` twice) doesn't double-emit `selectRelatedColumns`
+   * operations.
+   */
+  private joinRelationsApplied;
+  /**
+   * Idempotency guard for `applyCountRelations()` — see `joinRelationsApplied`.
+   */
+  private countRelationsApplied;
+  /**
+   * Idempotency guard for `applyHasRelations()` — see `joinRelationsApplied`.
+   */
+  private hasRelationsApplied;
+  /**
+   * Alias → SQL expression for two-arg `groupBy` aggregates. Recorded by the
+   * `groupBy` override; consumed by `applyGroupByAggregates` to rewrite a
+   * `having()` on the alias into the underlying expression (Postgres forbids
+   * SELECT aliases in HAVING).
+   */
+  private aggregateAliases;
+  /**
+   * Idempotency guard for `applyGroupByAggregates()` — see `joinRelationsApplied`.
+   */
+  private groupByAggregatesApplied;
+  /**
+   * @param table - Target table name
+   * @param dataSource - Optional (uses default data source from registry if omitted)
+   */
+  constructor(table: string, dataSource?: DataSource);
+  private get driver();
+  clone(): this;
+  /**
+   * Native-query escape hatch. Passes `operations[]` to the callback for
+   * direct manipulation. Use sparingly — only when fluent API is insufficient.
+   *
+   * @example
+   * q.raw(ops => ops.push({ type: "whereRaw", data: { expression: "1=1" } }))
+   */
+  raw(callback: (operations: Op[]) => void): this;
+  /**
+   * Record a DISTINCT flag AND auto-select the field(s).
+   * In PostgreSQL, DISTINCT ON (col) requires the col to appear in SELECT.
+   *
+   * @example
+   * q.distinctValues("category")               // SELECT category … DISTINCT ON (category)
+   * q.distinctValues(["category", "status"])   // both fields in DISTINCT ON and SELECT
+   */
+  distinctValues(fields?: string | string[]): this;
+  /**
+   * GROUP BY with computed aggregates.
+   *
+   * Single-arg form defers to the base builder. With `aggregates`, each entry
+   * is translated to SQL — via the dialect for `$agg.*` helpers, verbatim for
+   * a raw SQL string — and pushed through the proven `selectRaw` projection
+   * (the same plumbing `similarTo` / `applyCountRelations` rely on). The
+   * grouped columns are projected explicitly because `SELECT *` is invalid
+   * alongside `GROUP BY`. The alias → expression map is recorded so
+   * `applyGroupByAggregates` can later rewrite `having()` on the alias.
+   *
+   * `$agg.distinct/floor/first/last` throw (MongoDB-only on Postgres v1);
+   * MongoDB operator objects throw (not portable to SQL).
+   *
+   * @example
+   * Order.query().groupBy("category", {
+   *   orders: $agg.count(),
+   *   revenue: $agg.sum("amount"),
+   * }).having("revenue", ">", 1000);
+   */
+  groupBy(fields: GroupByInput): this;
+  groupBy(fields: GroupByInput, aggregates: Record<string, RawExpression>): this;
+  /**
+   * Nearest-neighbour vector similarity search via pgvector cosine distance.
+   *
+   * Adds two operations atomically:
+   * 1. `selectRaw` → `1 - (column <=> $n::vector) AS <alias>`
+   *    Makes the similarity score available on every returned row.
+   * 2. `orderByRaw` → `column <=> $n::vector`
+   *    Tells the PostgreSQL query planner to use the IVFFlat/HNSW vector index.
+   *    Using the alias in ORDER BY would bypass the index — the raw expression is required.
+   *
+   * @example
+   * ```typescript
+   * const results = await Vector.query()
+   *   .where({ organization_id: "org-123", content_type: "summary" })
+   *   .similarTo("embedding", queryEmbedding)
+   *   .limit(5)
+   *   .get<VectorRow & { score: number }>();
+   * ```
+   */
+  similarTo(column: string, embedding: number[], alias?: string): this;
+  /** Set a hydration callback that transforms each result row. */
+  hydrate(callback: (data: unknown, index: number) => unknown): this;
+  /** Register a callback invoked before query execution. */
+  onFetching(callback: (query: this) => void | Promise<void>): () => void;
+  /** Register a callback invoked after fetch but before hydration. */
+  onHydrating(callback: (records: unknown[], context: unknown) => void | Promise<void>): () => void;
+  /** Register a callback invoked after fetch and hydration. */
+  onFetched(callback: (records: unknown[], context: unknown) => void | Promise<void>): () => void;
+  /** Apply pending global scopes to the operations list. */
+  private applyPendingScopes;
+  /** Array field contains a value (or object with key). */
+  whereArrayContains(field: string, value: unknown, key?: string): this;
+  /** Array field does NOT contain a value (or object with key). */
+  whereArrayNotContains(field: string, value: unknown, key?: string): this;
+  /** Array field contains value OR is empty. */
+  whereArrayHasOrEmpty(field: string, value: unknown, key?: string): this;
+  /** Array field does NOT contain value OR is empty. */
+  whereArrayNotHaveOrEmpty(field: string, value: unknown, key?: string): this;
+  /**
+   * Load relations via SQL JOINs (single query) with optional per-relation constraints.
+   *
+   * Supports:
+   * - `joinWith("author")` / `joinWith(["author", "category"])`
+   * - `joinWith({ actions: q => q.where("status", "pending").limit(5) })`
+   * - `joinWith({ organizationAiModel: "id,name", actions: q => q.orderBy("sort_order") })`
+   *
+   * @example
+   * ChatMessage.joinWith({
+   *   actions: q => q.where("status", "pending").orderBy("sort_order", "asc").limit(5),
+   *   organizationAiModel: "id,createdAt",
+   * })
+   */
+  joinWith(...args: unknown[]): this;
+  /** Run a joinWith constraint callback against a sub-QB and capture its operations. */
+  private _resolveConstraintOps;
+  /**
+   * Execute the query and return all matching rows.
+   */
+  get<TResult = T>(): Promise<TResult[]>;
+  /** Get first result. */
+  first<TResult = T>(): Promise<TResult | null>;
+  /** Get last result (by id desc). */
+  last<TResult = T>(): Promise<TResult | null>;
+  /** Get random results. */
+  random<TResult = T>(limit?: number): Promise<TResult[]>;
+  /** Get first or throw. */
+  firstOrFail<TResult = T>(): Promise<TResult>;
+  /** Get first or call callback. */
+  firstOr<TResult = T>(callback: () => TResult | Promise<TResult>): Promise<TResult>;
+  /** Get first or return null. */
+  firstOrNull<TResult = T>(): Promise<TResult | null>;
+  /** Get first or return default. */
+  firstOrNew<TResult = T>(defaults: GenericObject): Promise<TResult>;
+  /** Find by primary key. */
+  find<TResult = T>(id: number | string): Promise<TResult | null>;
+  /** Count matching rows. */
+  count(): Promise<number>;
+  /** SUM a numeric field. */
+  sum(field: string): Promise<number>;
+  /** AVG of a numeric field. */
+  avg(field: string): Promise<number>;
+  /** MIN of a numeric field. */
+  min(field: string): Promise<number>;
+  /** MAX of a numeric field. */
+  max(field: string): Promise<number>;
+  /** Get distinct values for a field. */
+  distinct<TResult = unknown>(field: string): Promise<TResult[]>;
+  /** Get array of all values for a single field. */
+  pluck(field: string): Promise<unknown[]>;
+  /** Get a single scalar value. */
+  value<TResult = unknown>(field: string): Promise<TResult | null>;
+  /** Check whether any matching rows exist. */
+  exists(): Promise<boolean>;
+  /** Check whether NO matching rows exist. */
+  notExists(): Promise<boolean>;
+  /** COUNT DISTINCT a field. */
+  countDistinct(field: string): Promise<number>;
+  /** Get latest records ordered by a column. */
+  latest(column?: string): Promise<T[]>;
+  /** Increment a numeric field. Returns new value. */
+  increment(field: string, amount?: number): Promise<number>;
+  /** Decrement a numeric field. Returns new value. */
+  decrement(field: string, amount?: number): Promise<number>;
+  /** Increment a field for all matching rows. Returns affected row count. */
+  incrementMany(field: string, amount?: number): Promise<number>;
+  /** Decrement a field for all matching rows. Returns affected row count. */
+  decrementMany(field: string, amount?: number): Promise<number>;
+  /**
+   * Process results in memory-efficient chunks.
+   *
+   * @example
+   * await User.query().chunk(100, async (rows, idx) => { ... })
+   */
+  chunk(size: number, callback: ChunkCallback<T>): Promise<void>;
+  /** Page-based pagination. */
+  paginate(options?: PaginationOptions): Promise<PaginationResult<T>>;
+  /**
+   * Set cursor pagination hints fluently.
+   * The recorded values are picked up by `cursorPaginate()` when no explicit
+   * options are passed.
+   *
+   * @example
+   * User.query().cursor(lastId).cursorPaginate({ limit: 20 })
+   */
+  cursor(after?: unknown, before?: unknown): this;
+  /** Cursor-based pagination. */
+  cursorPaginate(options?: CursorPaginationOptions): Promise<CursorPaginationResult<T>>;
+  /** Delete matching rows. Returns deleted count. */
+  delete(): Promise<number>;
+  /** Delete the first matching row. */
+  deleteOne(): Promise<number>;
+  /** Update matching rows. */
+  update(fields: Record<string, unknown>): Promise<number>;
+  /** Unset fields from matching rows. */
+  unset(...fields: string[]): Promise<number>;
+  /**
+   * Return the SQL + bindings without executing.
+   *
+   * Runs the same prelude as `get()` (scopes, joinWith expansion, joinRelations,
+   * countRelations) so the preview matches what would actually be sent to the
+   * database. The apply* methods are idempotent — calling `parse()` then `get()`
+   * does not double-emit operations.
+   */
+  parse(): DriverQuery;
+  /** Formatted SQL string (for logging/debugging). */
+  pretty(): string;
+  /** Run EXPLAIN ANALYZE on the query. */
+  explain(): Promise<unknown>;
+  /** Extend the builder with a driver-specific extension. */
+  extend<R>(extension: string, ..._args: unknown[]): R;
+  /** Pluck scalar values for a single field (alias for pluck). */
+  pluckOne<TResult = unknown>(field: string): Promise<TResult[]>;
+  /**
+   * Before `get()` runs the parser, consume any joinWith ops recorded by the base
+   * class and expand them into the joinRelations Map.
+   */
+  private _processJoinWithOps;
+  /**
+   * Translate each entry in `joinRelations` into actual JOIN + selectRelatedColumns operations.
+   *
+   * Idempotent — guarded by `joinRelationsApplied` so repeat calls (e.g.
+   * `parse()` followed by `get()`) don't double-emit operations.
+   */
+  private applyJoinRelations;
+  /**
+   * Translate every `has` / `whereHas` / `orWhereHas` / `doesntHave` /
+   * `whereDoesntHave` operation into an equivalent `whereRaw` (or
+   * `orWhereRaw`) carrying an EXISTS / NOT EXISTS / COUNT-comparison
+   * subquery. Keeps the parser pure (no schema awareness) — same pattern as
+   * `applyJoinRelations` and `applyCountRelations`.
+   *
+   * In-place rewrite preserves position so the boolean (AND/OR) stays
+   * correctly slotted relative to other where conditions.
+   *
+   * Idempotent — guarded by `hasRelationsApplied` so repeat calls (e.g.
+   * `parse()` followed by `get()`) don't double-translate.
+   */
+  private applyHasRelations;
+  /**
+   * Translate one has-family operation into its `whereRaw`/`orWhereRaw`
+   * equivalent. Resolves the relation definition, builds the EXISTS or
+   * COUNT-comparison subquery, and returns the replacement op.
+   */
+  private translateHasOp;
+  /**
+   * Build the SQL fragment that goes inside a `whereRaw` op for a has-family
+   * translation. Branches on relation type AND on the operation type:
+   *
+   * - `has` with default operator/count → `EXISTS (SELECT 1 FROM ...)`
+   * - `has` with custom operator/count → `(SELECT COUNT(*) FROM ...) <op> <count>`
+   * - `whereHas` / `orWhereHas` → `EXISTS (SELECT 1 ... AND <constraint>)`
+   * - `doesntHave` → `NOT EXISTS (SELECT 1 FROM ...)`
+   * - `whereDoesntHave` → `NOT EXISTS (SELECT 1 ... AND <constraint>)`
+   */
+  private buildHasSubquery;
+  /**
+   * Translate each entry in `countRelations` into a correlated COUNT subquery
+   * emitted as a `selectRaw` operation. Runs after `applyJoinRelations` so the
+   * "preserve main table columns" guard sees any joins already in place.
+   *
+   * Idempotent — guarded by `countRelationsApplied` so repeat calls (e.g.
+   * `parse()` followed by `get()`) don't double-emit operations.
+   */
+  private applyCountRelations;
+  /**
+   * Without an explicit `select(...)` or any `selectRaw`/`selectRelatedColumns`
+   * already pushed, the parser's "no selects → SELECT *" fallback would be
+   * suppressed once we add count expressions. Push `<table>.*` first so the
+   * caller's columns survive.
+   */
+  private ensureMainColumnsForCount;
+  /**
+   * Build a single correlated-subquery expression for a count entry. Branches
+   * on relation type (hasMany/hasOne/belongsTo/belongsToMany). The optional
+   * constraint callback's where-ops are translated via a sub-parser and
+   * spliced into the subquery's WHERE clause.
+   */
+  private buildCountSubquery;
+  /**
+   * Run a constraint's where-ops through a fresh sub-parser to obtain a SQL
+   * WHERE-fragment plus bindings. Strips the leading `WHERE ` and rewrites
+   * `$N` placeholders back to `?` so the outer parser renumbers them
+   * consistently when it processes the enclosing `selectRaw` operation.
+   *
+   * Non-where ops (orderBy / limit / etc.) are silently dropped — they have
+   * no meaning inside a COUNT subquery.
+   */
+  private extractCountWhereFragment;
+  /**
+   * Rewrite every `having` op whose field matches a recorded aggregate alias
+   * into a `havingRaw` carrying the underlying SQL expression. PostgreSQL
+   * forbids SELECT aliases in HAVING, so `having("revenue", ">", 1000)` on a
+   * `groupBy` aggregate would otherwise throw at runtime. A `having` on a
+   * grouped column (no alias match) is left untouched. Runs at parse time
+   * (not in the `groupBy` override) so it is independent of fluent call order.
+   *
+   * Idempotent — guarded by `groupByAggregatesApplied` so repeat calls (e.g.
+   * `parse()` followed by `get()`) don't double-process.
+   */
+  private applyGroupByAggregates;
+  /**
+   * Run the RelationLoader against the fetched rows for every relation
+   * registered via `with()`. Mutates each model instance in place — attaches
+   * loaded relations onto `model.loadedRelations` and as direct properties.
+   *
+   * Lives here (not in `buildQuery`'s `onFetched` callback as it did
+   * historically) so any code path that calls `get()` — including
+   * `Model.newQueryBuilder()` direct instantiation, custom builder subclasses
+   * via `static builder`, or any `eagerLoadRelations`-bearing builder — gets
+   * eager-loading. Previously the loader was only installed when the builder
+   * was constructed via `Model.query()` / `buildQuery`, so bypassing that
+   * factory made `with()` a silent no-op.
+   *
+   * Skipped silently when `modelClass` is absent (raw driver-level
+   * `queryBuilder()` usage has no relations map to consult).
+   */
+  private applyEagerLoading;
+  /**
+   * Extract per-relation data from raw DB rows (before hydration).
+   * Returns a Map of row index → nested relation data tree.
+   */
+  private extractJoinedRelationData;
+  /**
+   * Attach extracted relation data to hydrated model instances.
+   */
+  private attachJoinedRelations;
+  /**
+   * Build a WHERE-only SQL fragment from `where*` operations on the current builder.
+   * Used by DELETE / UPDATE / increment paths.
+   */
+  private buildFilter;
+}
+//#endregion
+export { PostgresQueryBuilder };
+//# sourceMappingURL=postgres-query-builder.d.mts.map

package/esm/drivers/postgres/postgres-query-builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-query-builder.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/postgres/postgres-query-builder.ts"],"mappings":";;;;;;;KAqDK,kBAAA;EACH,KAAA;EACA,IAAA;EACA,KAAA,GAAQ,QAAA;EACR,QAAA;EACA,UAAA;EACA,QAAA;EACA,UAAA;EACA,YAAA;EACA,WAAA,GAAc,QAAA;EACd,MAAA,aADA;EAGA,aAAA,GAAgB,EAAA;AAAA;;;;AAAE;AAuBpB;;;;;;;;;;;;cAAa,oBAAA,sBACH,YAAA,CAAa,CAAA,aACV,oBAAA,CAAqB,CAAA;EAAA,SAkEd,KAAA;EAgMkC;EAAA,SA3PpC,UAAA,EAAY,UAAA;EA8QiC;EA3QtD,eAAA,IAAmB,IAAA,WAAe,KAAA;EAugBA;EAAA,QApgBjC,gBAAA;EAujBqB;EAAA,QApjBrB,iBAAA;EAojB2B;EAAA,QAjjB3B,eAAA;EAujBkC;;;;EAjjBnC,aAAA,EAAa,GAAA,SAAA,kBAAA;EA8jBe;;;;;EAAA,QAvjB3B,oBAAA;EA8jBoD;;;EAAA,QAzjBpD,qBAAA;EA+jByC;;;EAAA,QA1jBzC,mBAAA;EA+jB+D;;;;;;EAAA,QAvjB/D,gBAAA;EAulByB;;;EAAA,QAllBzB,wBAAA;EAumBiD;;;;cA5lBvC,KAAA,UAChB,UAAA,GAAa,UAAA;EAAA,YAUH,MAAA,CAAA;EAQL,KAAA,CAAA;EAinB4C;;;;;;;EA5kB5C,GAAA,CAAI,QAAA,GAAW,UAAA,EAAY,EAAA;EAgoB4B;;;;;;;;EAnnB9C,cAAA,CAAe,MAAA;EA6tBR;;;;;;;;;;;;;;;;;;;;EA9rBhB,OAAA,CAAQ,MAAA,EAAQ,YAAA;EAChB,OAAA,CAAQ,MAAA,EAAQ,YAAA,EAAc,UAAA,EAAY,MAAA,SAAe,aAAA;EA7JzD;;;;;;;;;;;;;;;;;;;EAoNA,SAAA,CAAU,MAAA,UAAgB,SAAA,YAAqB,KAAA;EApG/C;EAkIA,OAAA,CAAQ,QAAA,GAAW,IAAA,WAAe,KAAA;EAlInB;EAwIf,UAAA,CAAW,QAAA,GAAW,KAAA,kBAAuB,OAAA;EA3HpC;EAmIT,WAAA,CACL,QAAA,GAAW,OAAA,aAAoB,OAAA,qBAA4B,OAAA;EArGtD;EA8GA,SAAA,CACL,QAAA,GAAW,OAAA,aAAoB,OAAA,qBAA4B,OAAA;EA/G9C;EAAA,QA4HP,kBAAA;EA3He;EA0JhB,kBAAA,CAAmB,KAAA,UAAe,KAAA,WAAgB,GAAA;EA1JR;EA2K1C,qBAAA,CAAsB,KAAA,UAAe,KAAA,WAAgB,GAAA;EA3KvB;EA4L9B,oBAAA,CAAqB,KAAA,UAAe,KAAA,WAAgB,GAAA;EArI1C;EAsJV,wBAAA,CAAyB,KAAA,UAAe,KAAA,WAAgB,GAAA;EAtJT;;;;;;;;;;;;;;EAwLtC,QAAA,CAAA,GAAY,IAAA;EAjIf;EAAA,QA8OL,qBAAA;EA9OqD;;;EA4PhD,GAAA,WAAc,CAAA,CAAA,CAAA,GAAM,OAAA,CAAQ,OAAA;EAhNf;EAmQb,KAAA,WAAgB,CAAA,CAAA,CAAA,GAAM,OAAA,CAAQ,OAAA;EAnQc;EAyQ5C,IAAA,WAAe,CAAA,CAAA,CAAA,GAAM,OAAA,CAAQ,OAAA;EAxPb;EA8PhB,MAAA,WAAiB,CAAA,CAAA,CAAG,KAAA,YAAiB,OAAA,CAAQ,OAAA;EA9PE;EAqQ/C,WAAA,WAAsB,CAAA,CAAA,CAAA,GAAM,OAAA,CAAQ,OAAA;EApPrB;EA2Pf,OAAA,WAAkB,CAAA,CAAA,CAAG,QAAA,QAAgB,OAAA,GAAU,OAAA,CAAQ,OAAA,IAAW,OAAA,CAAQ,OAAA;EA3P5B;EAiQ9C,WAAA,WAAsB,CAAA,CAAA,CAAA,GAAM,OAAA,CAAQ,OAAA;EAhPjB;EAqPnB,UAAA,WAAqB,CAAA,CAAA,CAAG,QAAA,EAAU,aAAA,GAAgB,OAAA,CAAQ,OAAA;EArPR;EA2PlD,IAAA,WAAe,CAAA,CAAA,CAAG,EAAA,oBAAsB,OAAA,CAAQ,OAAA;EAzNjC;EA8Nf,KAAA,CAAA,GAAS,OAAA;EAnGT;EAiHA,GAAA,CAAI,KAAA,WAAgB,OAAA;EAjHN;EAwHd,GAAA,CAAI,KAAA,WAAgB,OAAA;EAxHQ;EA+H5B,GAAA,CAAI,KAAA,WAAgB,OAAA;EA5Ed;EAmFN,GAAA,CAAI,KAAA,WAAgB,OAAA;EAnFE;EA0FtB,QAAA,mBAAA,CAA4B,KAAA,WAAgB,OAAA,CAAQ,OAAA;EApFpD;EA2FA,KAAA,CAAM,KAAA,WAAgB,OAAA;EA3FP;EAiGf,KAAA,mBAAA,CAAyB,KAAA,WAAgB,OAAA,CAAQ,OAAA;EAjGpB;EAuG7B,MAAA,CAAA,GAAU,OAAA;EAjGH;EAuGP,SAAA,CAAA,GAAa,OAAA;EAvGO;EA4GpB,aAAA,CAAc,KAAA,WAAgB,OAAA;EA5Ge;EAsH7C,MAAA,CAAO,MAAA,YAAuB,OAAA,CAAQ,CAAA;EA/G1B;EAsHZ,SAAA,CAAU,KAAA,UAAe,MAAA,YAAa,OAAA;EAtHV;EAsI5B,SAAA,CAAU,KAAA,UAAe,MAAA,YAAa,OAAA;EA/HtC;EAoIA,aAAA,CAAc,KAAA,UAAe,MAAA,YAAa,OAAA;EApIxB;EAgJlB,aAAA,CAAc,KAAA,UAAe,MAAA,YAAa,OAAA;EAhJK;;;;;;EA4J/C,KAAA,CAAM,IAAA,UAAc,QAAA,EAAU,aAAA,CAAc,CAAA,IAAK,OAAA;EAtJ3B;EA0KtB,QAAA,CAAS,OAAA,GAAU,iBAAA,GAAoB,OAAA,CAAQ,gBAAA,CAAiB,CAAA;EA1K5B;;;;;;;;EAuM1C,MAAA,CAAO,KAAA,YAAiB,MAAA;EA5Lb;EAkML,cAAA,CACX,OAAA,GAAU,uBAAA,GACT,OAAA,CAAQ,sBAAA,CAAuB,CAAA;EApMH;EAqPlB,MAAA,CAAA,GAAU,OAAA;EArPsC;EA8PhD,SAAA,CAAA,GAAa,OAAA;EAzPJ;EA8PT,MAAA,CAAO,MAAA,EAAQ,MAAA,oBAA0B,OAAA;EAhPrC;EAuPJ,KAAA,CAAA,GAAS,MAAA,aAAmB,OAAA;EAhP5B;;;;;;;;EAkQN,KAAA,CAAA,GAAS,WAAA;EA7OH;EA6PN,MAAA,CAAA;EA7PkC;EAmQ5B,OAAA,CAAA,GAAW,OAAA;EAnQyC;EA+Q1D,MAAA,GAAA,CAAU,SAAA,aAAsB,KAAA,cAAmB,CAAA;EAxQvC;EA6QN,QAAA,mBAAA,CAA4B,KAAA,WAAgB,OAAA,CAAQ,OAAA;EAvQpD;;;;EAAA,QAoRL,mBAAA;EA9QK;;;;;;EAAA,QA2SL,kBAAA;EAtRK;;;;;;;;;;;;;EAAA,QA8WL,iBAAA;EAlVkC;;;;;EAAA,QAwXlC,cAAA;EAhWK;;;;;;;;;;EAAA,QAwZL,gBAAA;EApYqE;;;;;;;;EAAA,QA2frE,mBAAA;EAtd0B;;;;;;EAAA,QAwgB1B,yBAAA;EAzcY;;;;;;EAAA,QAgeZ,kBAAA;EAvbD;;;;;;;;;EAAA,QAiiBC,yBAAA;EA1gBiC;;;;;;;;;;;EAAA,QA0jBjC,sBAAA;EAAA;;;;;;AA8LW;;;;;;;;;;EA9LX,QAyDM,iBAAA;;;;;UAqBN,yBAAA;;;;UAiDA,qBAAA;;;;;UA+DA,WAAA;AAAA"}