@stravigor/core 0.1.0 → 0.2.0

package/src/database/query_builder.ts

@@ -2,6 +2,9 @@ import { DateTime } from 'luxon'
 import { toSnakeCase } from '../helpers/strings.ts'
 import type BaseModel from '../orm/base_model.ts'
 import { ModelNotFoundError } from '../exceptions/errors.ts'
+import { getReferenceMeta, getAssociates } from '../orm/decorators.ts'
+import type { ReferenceMetadata, AssociateMetadata } from '../orm/decorators.ts'
+import { hydrateRow } from '../orm/base_model.ts'
 
 type ModelStatic<T extends BaseModel> = (new (...args: any[]) => T) & typeof BaseModel
 
@@ -27,12 +30,15 @@ export interface PaginationResult<T> {
 // Internal types
 // ---------------------------------------------------------------------------
 
+type WhereBoolean = 'AND' | 'OR'
+
 type WhereClause =
-  | { kind: 'comparison'; column: string; operator: string; value: unknown }
-  | { kind: 'in' | 'not_in'; column: string; values: unknown[] }
-  | { kind: 'null' | 'not_null'; column: string }
-  | { kind: 'between'; column: string; low: unknown; high: unknown }
-  | { kind: 'raw'; sql: string; params: unknown[] }
+  | { kind: 'comparison'; column: string; operator: string; value: unknown; boolean: WhereBoolean }
+  | { kind: 'in' | 'not_in'; column: string; values: unknown[]; boolean: WhereBoolean }
+  | { kind: 'null' | 'not_null'; column: string; boolean: WhereBoolean }
+  | { kind: 'between'; column: string; low: unknown; high: unknown; boolean: WhereBoolean }
+  | { kind: 'raw'; sql: string; params: unknown[]; boolean: WhereBoolean }
+  | { kind: 'group'; clauses: WhereClause[]; boolean: WhereBoolean }
 
 interface JoinClause {
   type: 'LEFT JOIN' | 'INNER JOIN' | 'RIGHT JOIN'
@@ -81,6 +87,7 @@ export default class QueryBuilder<T extends BaseModel> {
   private models: Map<string, typeof BaseModel> = new Map()
 
   private wheres: WhereClause[] = []
+  private havings: WhereClause[] = []
   private joins: JoinClause[] = []
   private orderBys: OrderByClause[] = []
   private groupBys: string[] = []
@@ -90,6 +97,7 @@ export default class QueryBuilder<T extends BaseModel> {
   private isDistinct: boolean = false
   private includeTrashed: boolean = false
   private isOnlyTrashed: boolean = false
+  private eagerLoads: string[] = []
 
   constructor(modelClass: ModelStatic<T>) {
     this.modelClass = modelClass
@@ -101,42 +109,159 @@ export default class QueryBuilder<T extends BaseModel> {
   // WHERE
   // ---------------------------------------------------------------------------
 
-  where(column: string, operatorOrValue: unknown, value?: unknown): this {
+  where(
+    column: string | ((q: QueryBuilder<T>) => void),
+    operatorOrValue?: unknown,
+    value?: unknown
+  ): this {
+    if (typeof column === 'function') {
+      const sub = new QueryBuilder<T>(this.modelClass)
+      column(sub)
+      this.wheres.push({ kind: 'group', clauses: sub.wheres, boolean: 'AND' })
+      return this
+    }
     if (value === undefined) {
-      this.wheres.push({ kind: 'comparison', column, operator: '=', value: operatorOrValue })
+      this.wheres.push({
+        kind: 'comparison',
+        column,
+        operator: '=',
+        value: operatorOrValue,
+        boolean: 'AND',
+      })
     } else {
-      this.wheres.push({ kind: 'comparison', column, operator: operatorOrValue as string, value })
+      this.wheres.push({
+        kind: 'comparison',
+        column,
+        operator: operatorOrValue as string,
+        value,
+        boolean: 'AND',
+      })
     }
     return this
   }
 
   whereIn(column: string, values: unknown[]): this {
-    this.wheres.push({ kind: 'in', column, values })
+    this.wheres.push({ kind: 'in', column, values, boolean: 'AND' })
     return this
   }
 
   whereNotIn(column: string, values: unknown[]): this {
-    this.wheres.push({ kind: 'not_in', column, values })
+    this.wheres.push({ kind: 'not_in', column, values, boolean: 'AND' })
     return this
   }
 
   whereNull(column: string): this {
-    this.wheres.push({ kind: 'null', column })
+    this.wheres.push({ kind: 'null', column, boolean: 'AND' })
     return this
   }
 
   whereNotNull(column: string): this {
-    this.wheres.push({ kind: 'not_null', column })
+    this.wheres.push({ kind: 'not_null', column, boolean: 'AND' })
     return this
   }
 
   whereBetween(column: string, low: unknown, high: unknown): this {
-    this.wheres.push({ kind: 'between', column, low, high })
+    this.wheres.push({ kind: 'between', column, low, high, boolean: 'AND' })
     return this
   }
 
   whereRaw(sql: string, params: unknown[] = []): this {
-    this.wheres.push({ kind: 'raw', sql, params })
+    this.wheres.push({ kind: 'raw', sql, params, boolean: 'AND' })
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // OR WHERE
+  // ---------------------------------------------------------------------------
+
+  orWhere(
+    column: string | ((q: QueryBuilder<T>) => void),
+    operatorOrValue?: unknown,
+    value?: unknown
+  ): this {
+    if (typeof column === 'function') {
+      const sub = new QueryBuilder<T>(this.modelClass)
+      column(sub)
+      this.wheres.push({ kind: 'group', clauses: sub.wheres, boolean: 'OR' })
+      return this
+    }
+    if (value === undefined) {
+      this.wheres.push({
+        kind: 'comparison',
+        column,
+        operator: '=',
+        value: operatorOrValue,
+        boolean: 'OR',
+      })
+    } else {
+      this.wheres.push({
+        kind: 'comparison',
+        column,
+        operator: operatorOrValue as string,
+        value,
+        boolean: 'OR',
+      })
+    }
+    return this
+  }
+
+  orWhereIn(column: string, values: unknown[]): this {
+    this.wheres.push({ kind: 'in', column, values, boolean: 'OR' })
+    return this
+  }
+
+  orWhereNotIn(column: string, values: unknown[]): this {
+    this.wheres.push({ kind: 'not_in', column, values, boolean: 'OR' })
+    return this
+  }
+
+  orWhereNull(column: string): this {
+    this.wheres.push({ kind: 'null', column, boolean: 'OR' })
+    return this
+  }
+
+  orWhereNotNull(column: string): this {
+    this.wheres.push({ kind: 'not_null', column, boolean: 'OR' })
+    return this
+  }
+
+  orWhereBetween(column: string, low: unknown, high: unknown): this {
+    this.wheres.push({ kind: 'between', column, low, high, boolean: 'OR' })
+    return this
+  }
+
+  orWhereRaw(sql: string, params: unknown[] = []): this {
+    this.wheres.push({ kind: 'raw', sql, params, boolean: 'OR' })
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // HAVING
+  // ---------------------------------------------------------------------------
+
+  having(column: string, operatorOrValue: unknown, value?: unknown): this {
+    if (value === undefined) {
+      this.havings.push({
+        kind: 'comparison',
+        column,
+        operator: '=',
+        value: operatorOrValue,
+        boolean: 'AND',
+      })
+    } else {
+      this.havings.push({
+        kind: 'comparison',
+        column,
+        operator: operatorOrValue as string,
+        value,
+        boolean: 'AND',
+      })
+    }
+    return this
+  }
+
+  havingRaw(sql: string, params: unknown[] = []): this {
+    this.havings.push({ kind: 'raw', sql, params, boolean: 'AND' })
     return this
   }
 
@@ -214,7 +339,29 @@ export default class QueryBuilder<T extends BaseModel> {
   }
 
   // ---------------------------------------------------------------------------
-  // Terminal methods
+  // Eager loading
+  // ---------------------------------------------------------------------------
+
+  with(...relations: string[]): this {
+    this.eagerLoads.push(...relations)
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // Scopes
+  // ---------------------------------------------------------------------------
+
+  scope(name: string): this {
+    const scopes = (this.modelClass as any).scopes
+    if (!scopes || typeof scopes[name] !== 'function') {
+      throw new Error(`Unknown scope "${name}" on ${this.modelClass.name}`)
+    }
+    scopes[name](this)
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // Terminal methods — read
   // ---------------------------------------------------------------------------
 
   async all(): Promise<T[]> {
@@ -222,7 +369,9 @@ export default class QueryBuilder<T extends BaseModel> {
     const db = this.modelClass.db
     const rows = await db.sql.unsafe(sql, params)
     const Model = this.modelClass as any
-    return rows.map((row: Record<string, unknown>) => Model.hydrate(row) as T)
+    const results = rows.map((row: Record<string, unknown>) => Model.hydrate(row) as T)
+    await this.eagerLoad(results)
+    return results
   }
 
   async first(): Promise<T | null> {
@@ -275,19 +424,125 @@ export default class QueryBuilder<T extends BaseModel> {
     }
   }
 
+  async pluck<V = unknown>(column: string): Promise<V[]> {
+    const savedColumns = [...this.selectColumns]
+    this.selectColumns = [column]
+    const { sql, params } = this.build('select')
+    this.selectColumns = savedColumns
+
+    const db = this.modelClass.db
+    const rows = await db.sql.unsafe(sql, params)
+    const snakeCol = toSnakeCase(column.includes('.') ? column.split('.')[1]! : column)
+    return rows.map((row: Record<string, unknown>) => row[snakeCol] as V)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Terminal methods — aggregates
+  // ---------------------------------------------------------------------------
+
+  async sum(column: string): Promise<number> {
+    return this.aggregate('SUM', column)
+  }
+
+  async avg(column: string): Promise<number> {
+    return this.aggregate('AVG', column)
+  }
+
+  async min(column: string): Promise<number> {
+    return this.aggregate('MIN', column)
+  }
+
+  async max(column: string): Promise<number> {
+    return this.aggregate('MAX', column)
+  }
+
+  private async aggregate(fn: string, column: string): Promise<number> {
+    const col = this.resolveColumn(column)
+    const savedColumns = [...this.selectColumns]
+    const savedDistinct = this.isDistinct
+    this.selectColumns = [`${fn}(${col}) AS "result"`]
+    this.isDistinct = false
+
+    const { sql, params } = this.build('select')
+    this.selectColumns = savedColumns
+    this.isDistinct = savedDistinct
+
+    const db = this.modelClass.db
+    const rows = await db.sql.unsafe(sql, params)
+    return Number(rows[0]?.result ?? 0)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Terminal methods — mutations
+  // ---------------------------------------------------------------------------
+
+  async update(data: Record<string, unknown>): Promise<number> {
+    const { sql, params } = this.buildUpdate(data)
+    const db = this.modelClass.db
+    const result = await db.sql.unsafe(sql, params)
+    return result.count
+  }
+
+  async delete(): Promise<number> {
+    if (this.modelClass.softDeletes && !this.includeTrashed) {
+      return this.update({ deletedAt: DateTime.now() })
+    }
+    const { sql, params } = this.buildDelete()
+    const db = this.modelClass.db
+    const result = await db.sql.unsafe(sql, params)
+    return result.count
+  }
+
+  async forceDelete(): Promise<number> {
+    const { sql, params } = this.buildDelete()
+    const db = this.modelClass.db
+    const result = await db.sql.unsafe(sql, params)
+    return result.count
+  }
+
+  async increment(column: string, amount: number = 1): Promise<number> {
+    return this.adjustColumn(column, amount)
+  }
+
+  async decrement(column: string, amount: number = 1): Promise<number> {
+    return this.adjustColumn(column, -amount)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Terminal methods — iteration
+  // ---------------------------------------------------------------------------
+
+  async chunk(size: number, callback: (items: T[]) => Promise<void> | void): Promise<void> {
+    let page = 0
+    while (true) {
+      const savedLimit = this.limitValue
+      const savedOffset = this.offsetValue
+      this.limitValue = size
+      this.offsetValue = page * size
+      const items = await this.all()
+      this.limitValue = savedLimit
+      this.offsetValue = savedOffset
+
+      if (items.length === 0) break
+      await callback(items)
+      if (items.length < size) break
+      page++
+    }
+  }
+
   /** Return the generated SQL and params without executing. */
   toSQL(): { sql: string; params: unknown[] } {
     return this.build('select')
   }
 
   // ---------------------------------------------------------------------------
-  // SQL building
+  // SQL building — SELECT / COUNT
   // ---------------------------------------------------------------------------
 
   private build(mode: 'select' | 'count'): { sql: string; params: unknown[] } {
     const parts: string[] = []
     const params: unknown[] = []
-    let paramIdx = 1
+    const paramIdx = { value: 1 }
 
     // SELECT
     if (mode === 'count') {
@@ -310,102 +565,340 @@ export default class QueryBuilder<T extends BaseModel> {
     }
 
     // WHERE
-    const whereParts: string[] = []
+    const { parts: whereParts, booleans: whereBooleans } = this.buildClauseParts(
+      this.wheres,
+      params,
+      paramIdx,
+      true
+    )
+    if (whereParts.length > 0) {
+      parts.push(`WHERE ${this.joinWithBooleans(whereParts, whereBooleans)}`)
+    }
 
-    // Soft delete handling
-    if (this.modelClass.softDeletes && !this.includeTrashed) {
+    // GROUP BY
+    if (this.groupBys.length > 0) {
+      const cols = this.groupBys.map(c => this.resolveColumn(c))
+      parts.push(`GROUP BY ${cols.join(', ')}`)
+    }
+
+    // HAVING
+    if (this.havings.length > 0) {
+      const { parts: havingParts, booleans: havingBooleans } = this.buildClauseParts(
+        this.havings,
+        params,
+        paramIdx,
+        false,
+        true
+      )
+      if (havingParts.length > 0) {
+        parts.push(`HAVING ${this.joinWithBooleans(havingParts, havingBooleans)}`)
+      }
+    }
+
+    // count mode skips ORDER BY, LIMIT, OFFSET
+    if (mode === 'select') {
+      // ORDER BY
+      if (this.orderBys.length > 0) {
+        const clauses = this.orderBys.map(o => `${this.resolveColumn(o.column)} ${o.direction}`)
+        parts.push(`ORDER BY ${clauses.join(', ')}`)
+      }
+
+      // LIMIT
+      if (this.limitValue !== null) {
+        parts.push(`LIMIT ${this.limitValue}`)
+      }
+
+      // OFFSET
+      if (this.offsetValue !== null) {
+        parts.push(`OFFSET ${this.offsetValue}`)
+      }
+    }
+
+    return { sql: parts.join(' '), params }
+  }
+
+  // ---------------------------------------------------------------------------
+  // SQL building — UPDATE / DELETE / INCREMENT
+  // ---------------------------------------------------------------------------
+
+  private buildUpdate(data: Record<string, unknown>): { sql: string; params: unknown[] } {
+    const parts: string[] = []
+    const params: unknown[] = []
+    const paramIdx = { value: 1 }
+
+    parts.push(`UPDATE "${this.primaryTable}"`)
+
+    const setClauses: string[] = []
+    for (const [key, val] of Object.entries(data)) {
+      const col = toSnakeCase(key)
+      params.push(this.dehydrateValue(val))
+      setClauses.push(`"${col}" = $${paramIdx.value++}`)
+    }
+    parts.push(`SET ${setClauses.join(', ')}`)
+
+    const { parts: whereParts, booleans: whereBooleans } = this.buildClauseParts(
+      this.wheres,
+      params,
+      paramIdx,
+      true
+    )
+    if (whereParts.length > 0) {
+      parts.push(`WHERE ${this.joinWithBooleans(whereParts, whereBooleans)}`)
+    }
+
+    return { sql: parts.join(' '), params }
+  }
+
+  private buildDelete(): { sql: string; params: unknown[] } {
+    const parts: string[] = []
+    const params: unknown[] = []
+    const paramIdx = { value: 1 }
+
+    parts.push(`DELETE FROM "${this.primaryTable}"`)
+
+    const { parts: whereParts, booleans: whereBooleans } = this.buildClauseParts(
+      this.wheres,
+      params,
+      paramIdx,
+      true
+    )
+    if (whereParts.length > 0) {
+      parts.push(`WHERE ${this.joinWithBooleans(whereParts, whereBooleans)}`)
+    }
+
+    return { sql: parts.join(' '), params }
+  }
+
+  private async adjustColumn(column: string, amount: number): Promise<number> {
+    const col = toSnakeCase(column)
+    const parts: string[] = []
+    const params: unknown[] = []
+    const paramIdx = { value: 1 }
+
+    parts.push(`UPDATE "${this.primaryTable}"`)
+    params.push(Math.abs(amount))
+    const op = amount >= 0 ? '+' : '-'
+    parts.push(`SET "${col}" = "${col}" ${op} $${paramIdx.value++}`)
+
+    const { parts: whereParts, booleans: whereBooleans } = this.buildClauseParts(
+      this.wheres,
+      params,
+      paramIdx,
+      true
+    )
+    if (whereParts.length > 0) {
+      parts.push(`WHERE ${this.joinWithBooleans(whereParts, whereBooleans)}`)
+    }
+
+    const db = this.modelClass.db
+    const result = await db.sql.unsafe(parts.join(' '), params)
+    return result.count
+  }
+
+  // ---------------------------------------------------------------------------
+  // Shared clause building
+  // ---------------------------------------------------------------------------
+
+  private buildClauseParts(
+    clauses: WhereClause[],
+    params: unknown[],
+    paramIdx: { value: number },
+    includeSoftDeletes: boolean,
+    rawColumns: boolean = false
+  ): { parts: string[]; booleans: WhereBoolean[] } {
+    const parts: string[] = []
+    const booleans: WhereBoolean[] = []
+
+    if (includeSoftDeletes && this.modelClass.softDeletes && !this.includeTrashed) {
       if (this.isOnlyTrashed) {
-        whereParts.push(`"${this.primaryTable}"."deleted_at" IS NOT NULL`)
+        parts.push(`"${this.primaryTable}"."deleted_at" IS NOT NULL`)
       } else {
-        whereParts.push(`"${this.primaryTable}"."deleted_at" IS NULL`)
+        parts.push(`"${this.primaryTable}"."deleted_at" IS NULL`)
       }
+      booleans.push('AND')
     }
 
-    for (const w of this.wheres) {
+    const resolve = rawColumns
+      ? (ref: string) => this.resolveSelectColumn(ref)
+      : (ref: string) => this.resolveColumn(ref)
+
+    for (const w of clauses) {
+      booleans.push(w.boolean)
       switch (w.kind) {
         case 'comparison': {
-          const col = this.resolveColumn(w.column)
+          const col = resolve(w.column)
           params.push(this.dehydrateValue(w.value))
-          whereParts.push(`${col} ${w.operator} $${paramIdx++}`)
+          parts.push(`${col} ${w.operator} $${paramIdx.value++}`)
           break
         }
         case 'in': {
-          const col = this.resolveColumn(w.column)
+          const col = resolve(w.column)
           const placeholders = w.values.map(v => {
             params.push(this.dehydrateValue(v))
-            return `$${paramIdx++}`
+            return `$${paramIdx.value++}`
           })
-          whereParts.push(`${col} IN (${placeholders.join(', ')})`)
+          parts.push(`${col} IN (${placeholders.join(', ')})`)
           break
         }
         case 'not_in': {
-          const col = this.resolveColumn(w.column)
+          const col = resolve(w.column)
           const placeholders = w.values.map(v => {
             params.push(this.dehydrateValue(v))
-            return `$${paramIdx++}`
+            return `$${paramIdx.value++}`
           })
-          whereParts.push(`${col} NOT IN (${placeholders.join(', ')})`)
+          parts.push(`${col} NOT IN (${placeholders.join(', ')})`)
           break
         }
         case 'null': {
-          const col = this.resolveColumn(w.column)
-          whereParts.push(`${col} IS NULL`)
+          const col = resolve(w.column)
+          parts.push(`${col} IS NULL`)
           break
         }
         case 'not_null': {
-          const col = this.resolveColumn(w.column)
-          whereParts.push(`${col} IS NOT NULL`)
+          const col = resolve(w.column)
+          parts.push(`${col} IS NOT NULL`)
           break
         }
         case 'between': {
-          const col = this.resolveColumn(w.column)
+          const col = resolve(w.column)
           params.push(this.dehydrateValue(w.low))
           params.push(this.dehydrateValue(w.high))
-          whereParts.push(`${col} BETWEEN $${paramIdx++} AND $${paramIdx++}`)
+          parts.push(`${col} BETWEEN $${paramIdx.value++} AND $${paramIdx.value++}`)
           break
         }
         case 'raw': {
           let rawSql = w.sql
           for (const p of w.params) {
-            rawSql = rawSql.replace(`$${w.params.indexOf(p) + 1}`, `$${paramIdx++}`)
+            rawSql = rawSql.replace(`$${w.params.indexOf(p) + 1}`, `$${paramIdx.value++}`)
             params.push(this.dehydrateValue(p))
           }
-          whereParts.push(rawSql)
+          parts.push(rawSql)
+          break
+        }
+        case 'group': {
+          const { parts: groupParts, booleans: groupBooleans } = this.buildClauseParts(
+            w.clauses,
+            params,
+            paramIdx,
+            false,
+            rawColumns
+          )
+          if (groupParts.length > 0) {
+            parts.push(`(${this.joinWithBooleans(groupParts, groupBooleans)})`)
+          }
           break
         }
       }
     }
 
-    if (whereParts.length > 0) {
-      parts.push(`WHERE ${whereParts.join(' AND ')}`)
-    }
+    return { parts, booleans }
+  }
 
-    // GROUP BY
-    if (this.groupBys.length > 0) {
-      const cols = this.groupBys.map(c => this.resolveColumn(c))
-      parts.push(`GROUP BY ${cols.join(', ')}`)
+  private joinWithBooleans(parts: string[], booleans: WhereBoolean[]): string {
+    if (parts.length === 0) return ''
+    let result = parts[0]!
+    for (let i = 1; i < parts.length; i++) {
+      result += ` ${booleans[i]} ${parts[i]}`
     }
+    return result
+  }
 
-    // count mode skips ORDER BY, LIMIT, OFFSET
-    if (mode === 'select') {
-      // ORDER BY
-      if (this.orderBys.length > 0) {
-        const clauses = this.orderBys.map(o => `${this.resolveColumn(o.column)} ${o.direction}`)
-        parts.push(`ORDER BY ${clauses.join(', ')}`)
+  // ---------------------------------------------------------------------------
+  // Eager loading
+  // ---------------------------------------------------------------------------
+
+  private async eagerLoad(models: T[]): Promise<void> {
+    if (this.eagerLoads.length === 0 || models.length === 0) return
+
+    const ctor = this.modelClass as unknown as Function
+    const refMetas: ReferenceMetadata[] = getReferenceMeta(ctor)
+    const assocMetas: AssociateMetadata[] = getAssociates(ctor)
+
+    for (const relation of this.eagerLoads) {
+      const refMeta = refMetas.find(r => r.property === relation)
+      if (refMeta) {
+        await this.eagerLoadReference(models, refMeta)
+        continue
       }
 
-      // LIMIT
-      if (this.limitValue !== null) {
-        parts.push(`LIMIT ${this.limitValue}`)
+      const assocMeta = assocMetas.find(a => a.property === relation)
+      if (assocMeta) {
+        await this.eagerLoadAssociation(models, assocMeta)
+        continue
       }
 
-      // OFFSET
-      if (this.offsetValue !== null) {
-        parts.push(`OFFSET ${this.offsetValue}`)
+      throw new Error(`Unknown relation "${relation}" on ${this.modelClass.name}`)
+    }
+  }
+
+  private async eagerLoadReference(models: T[], meta: ReferenceMetadata): Promise<void> {
+    const db = this.modelClass.db
+    const fkValues = [
+      ...new Set(
+        models.map(m => (m as any)[meta.foreignKey]).filter(v => v !== null && v !== undefined)
+      ),
+    ]
+
+    if (fkValues.length === 0) {
+      for (const model of models) {
+        ;(model as any)[meta.property] = null
       }
+      return
     }
 
-    return { sql: parts.join(' '), params }
+    const targetTable = toSnakeCase(meta.model)
+    const targetPKCol = toSnakeCase(meta.targetPK)
+    const placeholders = fkValues.map((_, i) => `$${i + 1}`).join(', ')
+    const rows = await db.sql.unsafe(
+      `SELECT * FROM "${targetTable}" WHERE "${targetPKCol}" IN (${placeholders})`,
+      fkValues
+    )
+
+    const lookup = new Map<unknown, Record<string, unknown>>()
+    for (const row of rows) {
+      const r = row as Record<string, unknown>
+      lookup.set(r[targetPKCol], hydrateRow(r))
+    }
+
+    for (const model of models) {
+      const fkVal = (model as any)[meta.foreignKey]
+      ;(model as any)[meta.property] = fkVal != null ? (lookup.get(fkVal) ?? null) : null
+    }
+  }
+
+  private async eagerLoadAssociation(models: T[], meta: AssociateMetadata): Promise<void> {
+    const db = this.modelClass.db
+    const ctor = this.modelClass as typeof BaseModel
+    const pkProp = ctor.primaryKeyProperty
+
+    const pkValues = models.map(m => (m as any)[pkProp])
+    if (pkValues.length === 0) return
+
+    const targetTable = toSnakeCase(meta.model)
+    const targetPKCol = toSnakeCase(meta.targetPK)
+    const placeholders = pkValues.map((_, i) => `$${i + 1}`).join(', ')
+
+    const rows = await db.sql.unsafe(
+      `SELECT t.*, p."${meta.foreignKey}" AS "_pivot_fk" ` +
+        `FROM "${targetTable}" t ` +
+        `INNER JOIN "${meta.through}" p ON p."${meta.otherKey}" = t."${targetPKCol}" ` +
+        `WHERE p."${meta.foreignKey}" IN (${placeholders})`,
+      pkValues
+    )
+
+    const grouped = new Map<unknown, Record<string, unknown>[]>()
+    for (const row of rows) {
+      const r = row as Record<string, unknown>
+      const fk = r._pivot_fk
+      delete r._pivot_fk
+      if (!grouped.has(fk)) grouped.set(fk, [])
+      grouped.get(fk)!.push(hydrateRow(r))
+    }
+
+    for (const model of models) {
+      const pk = (model as any)[pkProp]
+      ;(model as any)[meta.property] = grouped.get(pk) ?? []
+    }
   }
 
   // ---------------------------------------------------------------------------