@zintrust/core 3.4.0 → 3.5.1

package/src/orm/QueryBuilder.ts

@@ -0,0 +1,2419 @@
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Build queries without raw SQL
+ */
+
+import type { PaginationQuery, Paginator } from '@database/Paginator';
+import { createPaginator } from '@database/Paginator';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { IDatabase, RawValue } from '@orm/Database';
+import type { IModel } from '@orm/Model';
+import type { IRelationship } from '@orm/Relationships';
+
+export interface WhereClause {
+  column: string;
+  operator: string;
+  value: unknown;
+  boolean?: 'AND' | 'OR';
+  expression?: 'normalized-text';
+  normalization?: NormalizedTextOptions;
+}
+
+export interface NormalizedTextOptions {
+  trim?: boolean;
+  lowercase?: boolean;
+}
+
+interface WhereGroupClause {
+  kind: 'group';
+  boolean: 'AND' | 'OR';
+  conditions: WherePredicate[];
+}
+
+interface WhereExistsClause {
+  kind: 'exists';
+  not: boolean;
+  boolean: 'AND' | 'OR';
+  table: string;
+  conditions: WherePredicate[];
+}
+
+interface WhereColumnCompareClause {
+  kind: 'column-compare';
+  boolean: 'AND' | 'OR';
+  left: string;
+  operator: string;
+  right: string;
+}
+
+type WherePredicate =
+  | WhereClause
+  | WhereGroupClause
+  | WhereExistsClause
+  | WhereColumnCompareClause;
+
+export interface IJoinOnBuilder {
+  on(left: string, operator: string, right: string): IJoinOnBuilder;
+}
+
+export type LatestPerOptions = {
+  orderBy: Array<[string, 'ASC' | 'DESC']>;
+  alias?: string;
+};
+
+export type JoinOnInput = string | ((on: IJoinOnBuilder) => unknown);
+
+/**
+ * Result returned from INSERT operations
+ * Provides access to the created record ID, affected rows count, and the full record if available
+ */
+export interface InsertResult {
+  id: string | number | bigint | null;
+  affectedRows: number;
+  insertedRecords?: Record<string, unknown>[];
+}
+
+export type SoftDeleteMode = 'exclude' | 'include' | 'only';
+
+export interface QueryBuilderOptions {
+  softDeleteColumn?: string;
+  softDeleteMode?: SoftDeleteMode;
+}
+
+export interface PaginationOptions {
+  baseUrl?: string;
+  query?: PaginationQuery;
+  /**
+   * When joins are present, paginate totals use COUNT(DISTINCT …).
+   * Defaults to `<table>.id`. Pass an explicit safe identifier path when the primary key differs.
+   */
+  countDistinct?: string;
+}
+
+export type EagerLoadConstraint = (builder: IQueryBuilder) => IQueryBuilder;
+export type EagerLoadConstraints = Record<string, EagerLoadConstraint>;
+
+export interface IQueryBuilder {
+  select(...columns: string[]): IQueryBuilder;
+  selectAs(column: string, alias: string): IQueryBuilder;
+  max(column: string, alias?: string): IQueryBuilder;
+  where(column: string, operator: string | number | boolean | null, value?: unknown): IQueryBuilder;
+  andWhere(column: string, operator: string, value?: unknown): IQueryBuilder;
+  orWhere(column: string, operator: string, value?: unknown): IQueryBuilder;
+  whereGroup(callback: (builder: IQueryBuilder) => unknown): IQueryBuilder;
+  orWhereGroup(callback: (builder: IQueryBuilder) => unknown): IQueryBuilder;
+  whereNormalized(column: string, value: unknown, options?: NormalizedTextOptions): IQueryBuilder;
+  orWhereNormalized(column: string, value: unknown, options?: NormalizedTextOptions): IQueryBuilder;
+  whereNull(column: string): IQueryBuilder;
+  whereNotNull(column: string): IQueryBuilder;
+  whereIn(column: string, values: unknown[]): IQueryBuilder;
+  whereNotIn(column: string, values: unknown[]): IQueryBuilder;
+  whereMatch(column: string, query: string): IQueryBuilder;
+  whereNotMatch(column: string, query: string): IQueryBuilder;
+  whereColumn(left: string, operator: string, right: string): IQueryBuilder;
+  whereExists(callback: (builder: IQueryBuilder) => unknown): IQueryBuilder;
+  whereNotExists(callback: (builder: IQueryBuilder) => unknown): IQueryBuilder;
+  from(table: string): IQueryBuilder;
+  withTrashed(): IQueryBuilder;
+  onlyTrashed(): IQueryBuilder;
+  withoutTrashed(): IQueryBuilder;
+  join(table: string, on: JoinOnInput): IQueryBuilder;
+  leftJoin(table: string, on: JoinOnInput): IQueryBuilder;
+  groupBy(...columns: string[]): IQueryBuilder;
+  latestPer(partitionBy: string | string[], options: LatestPerOptions): IQueryBuilder;
+  orderBy(column: string, direction?: 'ASC' | 'DESC'): IQueryBuilder;
+  inRandomOrder(): IQueryBuilder;
+  limit(count: number): IQueryBuilder;
+  offset(count: number): IQueryBuilder;
+  getWhereClauses(): WhereClause[];
+  getSelectColumns(): string[];
+  getTable(): string;
+  getLimit(): number | undefined;
+  getOffset(): number | undefined;
+  getOrderBy(): { column: string; direction: 'ASC' | 'DESC' } | undefined;
+  getJoins(): Array<{ table: string; on: string; type: 'INNER' | 'LEFT' }>;
+  isReadOperation(): boolean;
+  toSQL(): string;
+  getParameters(): unknown[];
+  first<T>(): Promise<T | null>;
+  firstOrFail<T>(message?: string): Promise<T>;
+  get<T>(): Promise<T[]>;
+  raw<T>(): Promise<T[]>;
+  paginate<T>(page: number, perPage: number, options?: PaginationOptions): Promise<Paginator<T>>;
+
+  with(relation: string | EagerLoadConstraints): IQueryBuilder;
+  withCount(relation: string): IQueryBuilder;
+  load(models: IModel[], relation: string, constraint?: EagerLoadConstraint): Promise<void>;
+  loadCount(models: IModel[], relation: string): Promise<void>;
+
+  insert(values: Record<string, unknown> | Array<Record<string, unknown>>): Promise<InsertResult>;
+  update(values: Record<string, unknown>): Promise<void>;
+  delete(): Promise<void>;
+}
+
+interface QueryState {
+  tableName: string;
+  whereConditions: WherePredicate[];
+  selectColumns: string[];
+  limitValue?: number;
+  offsetValue?: number;
+  orderByClauses: Array<{ column: string; direction: 'ASC' | 'DESC' }>;
+  randomOrder: boolean;
+  joins: Array<{ table: string; on: string; type: 'INNER' | 'LEFT' }>;
+  groupByColumns: string[];
+  latestPer?: {
+    partitionBy: string[];
+    orderBy: Array<{ column: string; direction: 'ASC' | 'DESC' }>;
+    alias: string;
+  };
+  softDelete?: { column: string; mode: SoftDeleteMode };
+  eagerLoads: string[];
+  eagerLoadConstraints: EagerLoadConstraints;
+  eagerLoadCounts: string[];
+  dialect?: string;
+}
+
+/**
+ * Escape SQL identifier
+ */
+type IdentifierQuote = {
+  open: string;
+  close: string;
+  escape: (raw: string) => string;
+};
+
+const getIdentifierQuote = (dialect?: string): IdentifierQuote => {
+  const d = (dialect ?? '').toLowerCase();
+
+  if (d === 'mysql') {
+    return {
+      open: '`',
+      close: '`',
+      escape: (raw) => raw.replaceAll('`', '``'),
+    };
+  }
+
+  if (d === 'sqlserver') {
+    return {
+      open: '[',
+      close: ']',
+      escape: (raw) => raw.replaceAll(']', ']]'),
+    };
+  }
+
+  // sqlite/postgresql/d1/d1-remote: standard SQL double-quote identifiers.
+  return {
+    open: '"',
+    close: '"',
+    escape: (raw) => raw.replaceAll('"', '""'),
+  };
+};
+
+const escapeIdentifier = (id: string, dialect?: string): string => {
+  const q = getIdentifierQuote(dialect);
+  return id
+    .split('.')
+    .map((part) => `${q.open}${q.escape(part)}${q.close}`)
+    .join('.');
+};
+
+const SAFE_IDENTIFIER_PATH = /^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$/;
+const SAFE_IDENTIFIER = /^[A-Za-z_]\w*$/;
+const SAFE_FUNCTION_CALL = /^[A-Za-z_]\w*\(\)$/;
+
+const assertSafeIdentifierPath = (id: string, label: string): void => {
+  const trimmed = id.trim();
+  if (trimmed.length === 0) {
+    throw ErrorFactory.createDatabaseError(`Empty SQL identifier for ${label}`);
+  }
+  if (!SAFE_IDENTIFIER_PATH.test(trimmed)) {
+    throw ErrorFactory.createDatabaseError(`Unsafe SQL identifier for ${label}`);
+  }
+};
+
+const assertSafeIdentifier = (id: string, label: string): void => {
+  const trimmed = id.trim();
+  if (trimmed.length === 0) {
+    throw ErrorFactory.createDatabaseError(`Empty SQL identifier for ${label}`);
+  }
+  if (!SAFE_IDENTIFIER.test(trimmed)) {
+    throw ErrorFactory.createDatabaseError(`Unsafe SQL identifier for ${label}`);
+  }
+};
+
+const isRawValue = (value: unknown): value is RawValue =>
+  typeof value === 'object' &&
+  value !== null &&
+  '__raw' in value &&
+  typeof (value as RawValue).__raw === 'string';
+
+const assertSafeRawExpression = (raw: string): string => {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw ErrorFactory.createDatabaseError('Empty raw SQL expression');
+  }
+  if (SAFE_IDENTIFIER_PATH.test(trimmed) || SAFE_FUNCTION_CALL.test(trimmed)) {
+    return trimmed;
+  }
+  throw ErrorFactory.createDatabaseError('Unsafe raw SQL expression');
+};
+
+const normalizeOrderDirection = (direction?: string): 'ASC' | 'DESC' => {
+  if (direction === undefined || direction === null) return 'ASC';
+  const trimmed = String(direction).trim();
+  if (trimmed.length === 0) return 'ASC';
+  const normalized = trimmed.toUpperCase();
+  if (normalized === 'ASC' || normalized === 'DESC') return normalized;
+  throw ErrorFactory.createDatabaseError('Unsafe ORDER BY direction');
+};
+
+const normalizeClauseBoolean = (value?: 'AND' | 'OR'): 'AND' | 'OR' =>
+  value === 'OR' ? 'OR' : 'AND';
+
+const normalizeTextOptions = (
+  options?: NormalizedTextOptions
+): Required<NormalizedTextOptions> => ({
+  trim: options?.trim !== false,
+  lowercase: options?.lowercase !== false,
+});
+
+const normalizeTextComparisonValue = (value: unknown, options?: NormalizedTextOptions): unknown => {
+  if (value === null || value === undefined) return value;
+
+  const normalizedOptions = normalizeTextOptions(options);
+  let normalized = String(value);
+
+  if (normalizedOptions.trim) {
+    normalized = normalized.trim();
+  }
+
+  if (normalizedOptions.lowercase) {
+    normalized = normalized.toLowerCase();
+  }
+
+  return normalized;
+};
+
+const buildNormalizedColumnSql = (
+  column: string,
+  dialect?: string,
+  options?: NormalizedTextOptions
+): string => {
+  const normalizedOptions = normalizeTextOptions(options);
+  let sql = escapeIdentifier(column, dialect);
+
+  if (normalizedOptions.trim) {
+    sql = `TRIM(${sql})`;
+  }
+
+  if (normalizedOptions.lowercase) {
+    sql = `LOWER(${sql})`;
+  }
+
+  return sql;
+};
+
+const isWhereGroupClause = (value: WherePredicate): value is WhereGroupClause =>
+  'kind' in value && value.kind === 'group';
+
+const isWhereExistsClause = (value: WherePredicate): value is WhereExistsClause =>
+  'kind' in value && value.kind === 'exists';
+
+const isWhereColumnCompareClause = (value: WherePredicate): value is WhereColumnCompareClause =>
+  'kind' in value && value.kind === 'column-compare';
+
+const normalizeOperator = (operator: string): string => operator.trim().toUpperCase();
+
+const ALLOWED_COLUMN_COMPARE_OPERATORS = new Set(['=', '!=', '<>', '<', '<=', '>', '>=']);
+
+const assertSafeColumnCompareOperator = (operator: string): string => {
+  const normalized = operator.trim();
+  if (!ALLOWED_COLUMN_COMPARE_OPERATORS.has(normalized)) {
+    throw ErrorFactory.createDatabaseError('Unsafe SQL column comparison operator');
+  }
+  return normalized;
+};
+
+const ALLOWED_OPERATORS = new Set([
+  '=',
+  '==',
+  '!=',
+  '<>',
+  '<',
+  '<=',
+  '>',
+  '>=',
+  'LIKE',
+  'NOT LIKE',
+  'ILIKE',
+  'NOT ILIKE',
+  'IN',
+  'NOT IN',
+  'BETWEEN',
+  'NOT BETWEEN',
+  'IS',
+  'IS NOT',
+  'NOT',
+  'MATCH',
+  'NOT MATCH',
+]);
+
+const MATCH_OPERATORS = new Set(['MATCH', 'NOT MATCH']);
+
+const isSqliteFamilyDialect = (dialect?: string): boolean => {
+  const d = (dialect ?? '').toLowerCase();
+  return d === 'sqlite' || d === 'd1' || d === 'd1-remote';
+};
+
+const assertSafeOperator = (operator: string): string => {
+  const normalized = normalizeOperator(operator);
+  if (!ALLOWED_OPERATORS.has(normalized)) {
+    throw ErrorFactory.createDatabaseError('Unsafe SQL operator');
+  }
+  return normalized;
+};
+
+const assertMatchOperator = (operator: string, value: unknown, dialect?: string): void => {
+  if (!MATCH_OPERATORS.has(operator)) {
+    return;
+  }
+
+  const dialectName = typeof dialect === 'string' ? dialect.trim() : '';
+  if (dialectName.length > 0 && !isSqliteFamilyDialect(dialectName)) {
+    throw ErrorFactory.createDatabaseError(
+      `MATCH is only supported on sqlite, d1, and d1-remote (got ${dialectName})`
+    );
+  }
+
+  if (typeof value !== 'string') {
+    throw ErrorFactory.createDatabaseError('MATCH operator requires a string value');
+  }
+};
+
+const assertSafeLimitOffset = (value: number, label: string): void => {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw ErrorFactory.createDatabaseError(`Unsafe ${label} value`);
+  }
+};
+
+const isNumericLiteral = (value: string): boolean => {
+  // Strict, injection-resistant numeric literal allow-list.
+  // Allows: 0, 1, 1.5, 0001
+  // Disallows: 1e3, 1;DROP, 1 as ok
+  return /^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value);
+};
+
+type SupportedAggregateFn = 'MAX' | 'MIN' | 'COUNT' | 'SUM' | 'AVG';
+
+const ALLOWED_AGGREGATES = new Set<SupportedAggregateFn>(['MAX', 'MIN', 'COUNT', 'SUM', 'AVG']);
+
+const tryParseAggregateSelectExpr = (
+  raw: string
+): { kind: 'aggregate'; fn: SupportedAggregateFn; arg: string; alias?: string } | null => {
+  // Aggregate functions: MAX(col) [AS alias]
+  // Capture content greedily to avoid ReDoS from overlapping whitespace patterns (S5852)
+  const agg = /^(MAX|MIN|COUNT|SUM|AVG)\(([^)]+)\)(?: AS (\S+))?$/i.exec(raw);
+  if (agg === null) return null;
+
+  const fn = agg[1]?.toUpperCase() as SupportedAggregateFn;
+  const arg = (agg[2] ?? '').trim();
+  const alias = (agg[3] ?? '').trim();
+
+  if (!ALLOWED_AGGREGATES.has(fn)) return null;
+  if (arg !== '*') {
+    assertSafeIdentifierPath(arg, 'aggregate argument');
+  }
+  if (alias.length > 0) {
+    assertSafeIdentifier(alias, 'aggregate alias');
+  }
+
+  return { kind: 'aggregate', fn, arg, alias: alias.length > 0 ? alias : undefined };
+};
+
+const tryParseColumnAliasSelectExpr = (
+  raw: string
+): { kind: 'column'; column: string; alias: string } | null => {
+  // Column alias: col [AS alias]
+  // Avoid catastrophic backtracking by using a linear-time separator scan.
+  const upperRaw = raw.toUpperCase();
+  const asIndex = upperRaw.indexOf(' AS ');
+  if (asIndex === -1) return null;
+
+  const asSeparator = { index: asIndex, 0: raw.slice(asIndex, asIndex + 4) };
+  const col = raw.slice(0, asSeparator.index).trim();
+  const alias = raw.slice(asSeparator.index + asSeparator[0].length).trim();
+
+  // Alias must be a single token (no whitespace).
+  if (col.length === 0 || alias.length === 0 || /\s/.test(alias)) return null;
+
+  assertSafeIdentifierPath(col, 'select column');
+  assertSafeIdentifier(alias, 'select alias');
+  return { kind: 'column', column: col, alias };
+};
+
+const tryParseSelectExpr = (
+  expr: string
+):
+  | { kind: 'all' }
+  | { kind: 'literal'; value: string }
+  | { kind: 'column'; column: string; alias?: string }
+  | { kind: 'aggregate'; fn: SupportedAggregateFn; arg: string; alias?: string } => {
+  const raw = expr.trim();
+  if (raw.length === 0) {
+    throw ErrorFactory.createDatabaseError('Empty SQL identifier for select column');
+  }
+  if (raw === '*') return { kind: 'all' };
+  if (isNumericLiteral(raw)) return { kind: 'literal', value: raw };
+
+  const aggregate = tryParseAggregateSelectExpr(raw);
+  if (aggregate !== null) return aggregate;
+
+  const aliased = tryParseColumnAliasSelectExpr(raw);
+  if (aliased !== null) return aliased;
+
+  // Plain identifier path
+  assertSafeIdentifierPath(raw, 'select column');
+  return { kind: 'column', column: raw };
+};
+
+/**
+ * Build SELECT clause
+ */
+const formatSelectExpr = (
+  parsed:
+    | { kind: 'all' }
+    | { kind: 'literal'; value: string }
+    | { kind: 'column'; column: string; alias?: string }
+    | { kind: 'aggregate'; fn: SupportedAggregateFn; arg: string; alias?: string },
+  dialect?: string
+): string => {
+  if (parsed.kind === 'all') return '*';
+  if (parsed.kind === 'literal') return parsed.value;
+
+  if (parsed.kind === 'aggregate') {
+    const argSql = parsed.arg === '*' ? '*' : escapeIdentifier(parsed.arg, dialect);
+    const base = `${parsed.fn}(${argSql})`;
+    const alias = typeof parsed.alias === 'string' && parsed.alias.length > 0 ? parsed.alias : null;
+    return alias === null ? base : `${base} AS ${escapeIdentifier(alias, dialect)}`;
+  }
+
+  const base = escapeIdentifier(parsed.column, dialect);
+  const alias = typeof parsed.alias === 'string' && parsed.alias.length > 0 ? parsed.alias : null;
+  return alias === null ? base : `${base} AS ${escapeIdentifier(alias, dialect)}`;
+};
+
+const buildSelectClause = (columns: string[], dialect?: string): string => {
+  const out: string[] = [];
+  for (const c of columns) {
+    const parsed = tryParseSelectExpr(String(c));
+    out.push(formatSelectExpr(parsed, dialect));
+  }
+
+  return out.join(', ');
+};
+
+const compileInWhereClause = (
+  columnSql: string,
+  operator: string,
+  value: unknown
+): { sql: string; parameters: unknown[] } | null => {
+  if (operator !== 'IN' && operator !== 'NOT IN') return null;
+
+  if (!Array.isArray(value) || value.length === 0) {
+    throw ErrorFactory.createDatabaseError('IN operator requires a non-empty array');
+  }
+
+  return {
+    sql: `${columnSql} ${operator} (${value.map(() => '?').join(', ')})`,
+    parameters: value,
+  };
+};
+
+const compileBetweenWhereClause = (
+  columnSql: string,
+  operator: string,
+  value: unknown
+): { sql: string; parameters: unknown[] } | null => {
+  if (operator !== 'BETWEEN' && operator !== 'NOT BETWEEN') return null;
+
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw ErrorFactory.createDatabaseError('BETWEEN operator requires a 2-item array');
+  }
+
+  return {
+    sql: `${columnSql} ${operator} ? AND ?`,
+    parameters: value,
+  };
+};
+
+const compileNullWhereClause = (
+  columnSql: string,
+  operator: string,
+  value: unknown
+): { sql: string; parameters: unknown[] } | null => {
+  if (value !== null && value !== undefined) return null;
+
+  if (operator === '=' || operator === '==') {
+    return { sql: `${columnSql} IS NULL`, parameters: [] };
+  }
+
+  if (operator === '!=' || operator === '<>' || operator === 'NOT') {
+    return { sql: `${columnSql} IS NOT NULL`, parameters: [] };
+  }
+
+  if (operator === 'IS' || operator === 'IS NOT') {
+    return { sql: `${columnSql} ${operator} NULL`, parameters: [] };
+  }
+
+  return null;
+};
+
+const compileComparisonWhereClause = (
+  columnSql: string,
+  operator: string,
+  value: unknown,
+  expression?: WhereClause['expression'],
+  normalization?: NormalizedTextOptions
+): { sql: string; parameters: unknown[] } => {
+  const finalValue =
+    expression === 'normalized-text' ? normalizeTextComparisonValue(value, normalization) : value;
+
+  return { sql: `${columnSql} ${operator} ?`, parameters: [finalValue] };
+};
+
+const compileSingleWhereClause = (
+  clause: WhereClause,
+  dialect?: string
+): {
+  sql: string;
+  parameters: unknown[];
+} => {
+  assertSafeIdentifierPath(clause.column, 'where column');
+  const operator = assertSafeOperator(clause.operator);
+  assertMatchOperator(operator, clause.value, dialect);
+  const columnSql =
+    clause.expression === 'normalized-text'
+      ? buildNormalizedColumnSql(clause.column, dialect, clause.normalization)
+      : escapeIdentifier(clause.column, dialect);
+
+  const inClause = compileInWhereClause(columnSql, operator, clause.value);
+  if (inClause !== null) return inClause;
+
+  const betweenClause = compileBetweenWhereClause(columnSql, operator, clause.value);
+  if (betweenClause !== null) return betweenClause;
+
+  const nullClause = compileNullWhereClause(columnSql, operator, clause.value);
+  if (nullClause !== null) return nullClause;
+
+  return compileComparisonWhereClause(
+    columnSql,
+    operator,
+    clause.value,
+    clause.expression,
+    clause.normalization
+  );
+};
+
+const compileColumnCompareClause = (
+  clause: WhereColumnCompareClause,
+  dialect?: string
+): { sql: string; parameters: unknown[] } => {
+  assertSafeIdentifierPath(clause.left, 'where column left');
+  assertSafeIdentifierPath(clause.right, 'where column right');
+  const operator = assertSafeColumnCompareOperator(clause.operator);
+  return {
+    sql: `${escapeIdentifier(clause.left, dialect)} ${operator} ${escapeIdentifier(
+      clause.right,
+      dialect
+    )}`,
+    parameters: [],
+  };
+};
+
+const compileExistsClause = (
+  clause: WhereExistsClause,
+  dialect?: string
+): { sql: string; parameters: unknown[] } => {
+  assertSafeIdentifierPath(clause.table, 'exists table');
+  const inner = compileWhereFragments(clause.conditions, dialect);
+  const whereSql = inner.sql.length > 0 ? ` WHERE ${inner.sql}` : '';
+  const keyword = clause.not ? 'NOT EXISTS' : 'EXISTS';
+  return {
+    sql: `${keyword} (SELECT 1 FROM ${escapeIdentifier(clause.table, dialect)}${whereSql})`,
+    parameters: inner.parameters,
+  };
+};
+
+const compileWherePredicate = (
+  condition: WherePredicate,
+  dialect?: string
+): { sql: string; parameters: unknown[]; grouped: boolean } => {
+  if (isWhereGroupClause(condition)) {
+    const compiled = compileWhereFragments(condition.conditions, dialect);
+    return { ...compiled, grouped: true };
+  }
+  if (isWhereExistsClause(condition)) {
+    return { ...compileExistsClause(condition, dialect), grouped: false };
+  }
+  if (isWhereColumnCompareClause(condition)) {
+    return { ...compileColumnCompareClause(condition, dialect), grouped: false };
+  }
+  return { ...compileSingleWhereClause(condition, dialect), grouped: false };
+};
+
+const compileWhereFragments = (
+  conditions: WherePredicate[],
+  dialect?: string
+): {
+  sql: string;
+  parameters: unknown[];
+} => {
+  if (conditions.length === 0) return { sql: '', parameters: [] };
+
+  const parameters: unknown[] = [];
+  const fragments: string[] = [];
+
+  for (const condition of conditions) {
+    const compiled = compileWherePredicate(condition, dialect);
+
+    if (compiled.sql.length === 0) continue;
+
+    parameters.push(...compiled.parameters);
+
+    const fragment = compiled.grouped ? `(${compiled.sql})` : compiled.sql;
+    const boolean = normalizeClauseBoolean(condition.boolean);
+    fragments.push(fragments.length === 0 ? fragment : `${boolean} ${fragment}`);
+  }
+
+  return { sql: fragments.join(' '), parameters };
+};
+
+const compileWhere = (
+  conditions: WherePredicate[],
+  dialect?: string
+): {
+  sql: string;
+  parameters: unknown[];
+} => {
+  const compiled = compileWhereFragments(conditions, dialect);
+  return compiled.sql.length === 0
+    ? { sql: '', parameters: [] }
+    : { sql: ` WHERE ${compiled.sql}`, parameters: compiled.parameters };
+};
+
+const buildSoftDeleteWhereClause = (column: string, mode: SoftDeleteMode): WhereClause | null => {
+  const col = column.trim();
+  if (col.length === 0) return null;
+  assertSafeIdentifierPath(col, 'soft delete column');
+
+  if (mode === 'include') return null;
+  if (mode === 'only') return { column: col, operator: 'IS NOT', value: null };
+  return { column: col, operator: 'IS', value: null };
+};
+
+const getEffectiveWhereConditions = (state: QueryState): WherePredicate[] => {
+  if (state.softDelete === undefined) return state.whereConditions;
+
+  const clause = buildSoftDeleteWhereClause(state.softDelete.column, state.softDelete.mode);
+  if (clause === null) return state.whereConditions;
+
+  return [...state.whereConditions, clause];
+};
+
+/**
+ * Build ORDER BY clause
+ */
+const buildOrderByClause = (
+  orderByClauses: Array<{ column: string; direction: 'ASC' | 'DESC' }>,
+  randomOrder: boolean,
+  dialect?: string
+): string => {
+  if (randomOrder) {
+    // Database-specific random ordering
+    switch (dialect) {
+      case 'mysql':
+      case 'mariadb':
+        return ' ORDER BY RAND()';
+      case 'postgres':
+        return ' ORDER BY RANDOM()';
+      case 'sqlite':
+        return ' ORDER BY RANDOM()';
+      case 'mssql':
+        return ' ORDER BY NEWID()';
+      default:
+        // Fallback for other databases
+        return ' ORDER BY RANDOM()';
+    }
+  }
+
+  if (orderByClauses.length === 0) return '';
+
+  const parts = orderByClauses.map((orderBy) => {
+    const col = orderBy.column.trim();
+    let columnSql = col;
+
+    if (!isNumericLiteral(col)) {
+      assertSafeIdentifierPath(col, 'order by column');
+      columnSql = escapeIdentifier(col, dialect);
+    }
+
+    const dir = normalizeOrderDirection(orderBy.direction);
+    return `${columnSql} ${dir}`;
+  });
+
+  return ` ORDER BY ${parts.join(', ')}`;
+};
+
+/**
+ * Build LIMIT and OFFSET clause
+ */
+const buildLimitOffsetClause = (limit?: number, offset?: number): string => {
+  let sql = '';
+  if (limit !== undefined && limit !== null) {
+    assertSafeLimitOffset(limit, 'LIMIT');
+    sql += ` LIMIT ${limit}`;
+  }
+  if (offset !== undefined && offset !== null) {
+    assertSafeLimitOffset(offset, 'OFFSET');
+    sql += ` OFFSET ${offset}`;
+  }
+  return sql;
+};
+
+// Matches `left OP right` where both sides are identifier paths (e.g.
+// `users.id = profiles.user_id`). Operator alternation lists the two-char
+// operators before their single-char prefixes so `<=`/`>=`/`<>` win the match.
+const JOIN_CONDITION =
+  /^([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)\s*(=|!=|<>|<=|>=|<|>)\s*([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)$/;
+
+type JoinOnTerm = { left: string; op: string; right: string };
+
+const parseJoinOnTerms = (on: string): JoinOnTerm[] => {
+  const parts = on
+    .split(/\s+AND\s+/i)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+
+  if (parts.length === 0) {
+    throw ErrorFactory.createDatabaseError('Unsafe SQL join condition');
+  }
+
+  return parts.map((part) => {
+    const match = JOIN_CONDITION.exec(part);
+    if (!match) {
+      throw ErrorFactory.createDatabaseError('Unsafe SQL join condition');
+    }
+    const [, left, op, right] = match;
+    return { left: left ?? '', op: op ?? '=', right: right ?? '' };
+  });
+};
+
+const resolveJoinOnInput = (on: JoinOnInput): string => {
+  if (typeof on === 'string') {
+    // Validate early so bad ON strings fail at builder time, not only at compile.
+    const terms = parseJoinOnTerms(on);
+    return terms.map((term) => `${term.left} ${term.op} ${term.right}`).join(' AND ');
+  }
+
+  const terms: JoinOnTerm[] = [];
+  const joinOnBuilder: IJoinOnBuilder = Object.freeze({
+    on(left: string, operator: string, right: string): IJoinOnBuilder {
+      assertSafeIdentifierPath(left, 'join on left');
+      assertSafeIdentifierPath(right, 'join on right');
+      const op = assertSafeColumnCompareOperator(operator);
+      terms.push({ left: left.trim(), op, right: right.trim() });
+      return joinOnBuilder;
+    },
+  });
+
+  on(joinOnBuilder);
+
+  if (terms.length === 0) {
+    throw ErrorFactory.createDatabaseError('Join ON builder requires at least one on() term');
+  }
+
+  return terms.map((term) => `${term.left} ${term.op} ${term.right}`).join(' AND ');
+};
+
+const buildJoinOnSql = (on: string, dialect?: string): string => {
+  const terms = parseJoinOnTerms(on);
+  return terms
+    .map(
+      (term) =>
+        `${escapeIdentifier(term.left, dialect)} ${term.op} ${escapeIdentifier(term.right, dialect)}`
+    )
+    .join(' AND ');
+};
+
+const buildJoinClause = (joins: QueryState['joins'], dialect?: string): string =>
+  joins
+    .map(({ table, on, type }) => {
+      assertSafeIdentifierPath(table, 'join table');
+      return ` ${type} JOIN ${escapeIdentifier(table, dialect)} ON ${buildJoinOnSql(on, dialect)}`;
+    })
+    .join('');
+
+const buildGroupByClause = (columns: string[], dialect?: string): string => {
+  if (columns.length === 0) return '';
+
+  const parts = columns.map((column) => {
+    const col = column.trim();
+    assertSafeIdentifierPath(col, 'group by column');
+    return escapeIdentifier(col, dialect);
+  });
+
+  return ` GROUP BY ${parts.join(', ')}`;
+};
+
+const buildWindowOrderBySql = (
+  orderBy: Array<{ column: string; direction: 'ASC' | 'DESC' }>,
+  dialect?: string
+): string => {
+  if (orderBy.length === 0) {
+    throw ErrorFactory.createDatabaseError('latestPer requires at least one orderBy column');
+  }
+
+  return orderBy
+    .map((clause) => {
+      assertSafeIdentifierPath(clause.column, 'window order by column');
+      return `${escapeIdentifier(clause.column, dialect)} ${clause.direction}`;
+    })
+    .join(', ');
+};
+
+const buildWindowPartitionSql = (partitionBy: string[], dialect?: string): string => {
+  if (partitionBy.length === 0) {
+    throw ErrorFactory.createDatabaseError('latestPer requires at least one partition column');
+  }
+
+  return partitionBy
+    .map((column) => {
+      assertSafeIdentifierPath(column, 'window partition column');
+      return escapeIdentifier(column, dialect);
+    })
+    .join(', ');
+};
+
+const buildBaseSelectBody = (
+  state: QueryState,
+  columnsSql: string,
+  options: { includeOrderLimit: boolean; includeGroupBy: boolean }
+): { sql: string; parameters: unknown[] } => {
+  if (state.tableName.length > 0) {
+    assertSafeIdentifierPath(state.tableName, 'table name');
+  }
+
+  const fromClause =
+    state.tableName.length > 0 ? ` FROM ${escapeIdentifier(state.tableName, state.dialect)}` : '';
+  const joinClause = buildJoinClause(state.joins, state.dialect);
+  const where = compileWhere(getEffectiveWhereConditions(state), state.dialect);
+  const groupByClause = options.includeGroupBy
+    ? buildGroupByClause(state.groupByColumns, state.dialect)
+    : '';
+  const orderLimit = options.includeOrderLimit
+    ? `${buildOrderByClause(state.orderByClauses, state.randomOrder, state.dialect)}${buildLimitOffsetClause(
+        state.limitValue,
+        state.offsetValue
+      )}`
+    : '';
+
+  const sql = `SELECT ${columnsSql}${fromClause}${joinClause}${where.sql}${groupByClause}${orderLimit}`;
+  return { sql, parameters: where.parameters };
+};
+
+const buildLatestPerQuery = (state: QueryState): { sql: string; parameters: unknown[] } => {
+  const latest = state.latestPer;
+  if (latest === undefined) {
+    throw ErrorFactory.createDatabaseError('latestPer state is missing');
+  }
+
+  const baseColumns = buildSelectClause(state.selectColumns, state.dialect);
+  const partitionSql = buildWindowPartitionSql(latest.partitionBy, state.dialect);
+  const orderSql = buildWindowOrderBySql(latest.orderBy, state.dialect);
+  const aliasSql = escapeIdentifier(latest.alias, state.dialect);
+  const windowSql = `ROW_NUMBER() OVER (PARTITION BY ${partitionSql} ORDER BY ${orderSql}) AS ${aliasSql}`;
+  const innerColumns =
+    baseColumns === '*' || baseColumns.trim().length === 0
+      ? `*, ${windowSql}`
+      : `${baseColumns}, ${windowSql}`;
+
+  // Window wrap owns outer ORDER/LIMIT; inner keeps filters/joins only.
+  const inner = buildBaseSelectBody(state, innerColumns, {
+    includeOrderLimit: false,
+    includeGroupBy: false,
+  });
+
+  const outerOrderLimit = `${buildOrderByClause(
+    state.orderByClauses,
+    state.randomOrder,
+    state.dialect
+  )}${buildLimitOffsetClause(state.limitValue, state.offsetValue)}`;
+
+  const sql = `SELECT * FROM (${inner.sql}) AS ${escapeIdentifier(
+    '_zt_window',
+    state.dialect
+  )} WHERE ${aliasSql} = 1${outerOrderLimit}`;
+
+  return { sql, parameters: inner.parameters };
+};
+
+const buildSelectQuery = (state: QueryState): { sql: string; parameters: unknown[] } => {
+  if (state.latestPer !== undefined) {
+    return buildLatestPerQuery(state);
+  }
+
+  const columns = buildSelectClause(state.selectColumns, state.dialect);
+  return buildBaseSelectBody(state, columns, {
+    includeOrderLimit: true,
+    includeGroupBy: true,
+  });
+};
+
+const buildCountQuery = (
+  state: QueryState,
+  options?: Pick<PaginationOptions, 'countDistinct'>
+): { sql: string; parameters: unknown[] } => {
+  if (state.tableName.length > 0) {
+    assertSafeIdentifierPath(state.tableName, 'table name');
+  }
+
+  // GROUP BY / window queries: count rows of the unconstrained result set via subquery.
+  if (state.groupByColumns.length > 0 || state.latestPer !== undefined) {
+    const prevLimit = state.limitValue;
+    const prevOffset = state.offsetValue;
+    const prevOrder = state.orderByClauses;
+    const prevRandom = state.randomOrder;
+
+    state.limitValue = undefined;
+    state.offsetValue = undefined;
+    state.orderByClauses = [];
+    state.randomOrder = false;
+
+    const inner = buildSelectQuery(state);
+
+    state.limitValue = prevLimit;
+    state.offsetValue = prevOffset;
+    state.orderByClauses = prevOrder;
+    state.randomOrder = prevRandom;
+
+    const sql = `SELECT COUNT(*) AS total FROM (${inner.sql}) AS ${escapeIdentifier(
+      '_zt_count',
+      state.dialect
+    )}`;
+    return { sql, parameters: inner.parameters };
+  }
+
+  const fromClause =
+    state.tableName.length > 0 ? ` FROM ${escapeIdentifier(state.tableName, state.dialect)}` : '';
+  const joinClause = buildJoinClause(state.joins, state.dialect);
+  const where = compileWhere(getEffectiveWhereConditions(state), state.dialect);
+
+  let countExpr = 'COUNT(*)';
+  if (state.joins.length > 0) {
+    const distinctCol =
+      typeof options?.countDistinct === 'string' && options.countDistinct.trim().length > 0
+        ? options.countDistinct.trim()
+        : `${state.tableName}.id`;
+    assertSafeIdentifierPath(distinctCol, 'count distinct column');
+    countExpr = `COUNT(DISTINCT ${escapeIdentifier(distinctCol, state.dialect)})`;
+  }
+
+  const sql = `SELECT ${countExpr} AS total${fromClause}${joinClause}${where.sql}`;
+  return { sql, parameters: where.parameters };
+};
+
+const applyWhereCondition = (
+  state: QueryState,
+  column: string,
+  operator: string | number | boolean | null,
+  value?: unknown,
+  boolean: 'AND' | 'OR' = 'AND',
+  extra: Partial<Pick<WhereClause, 'expression' | 'normalization'>> = {}
+): void => {
+  const col = String(column).trim();
+  assertSafeIdentifierPath(col, 'where column');
+
+  let op: string;
+  let val: unknown;
+
+  // Shorthand: where('id', 123)
+  if (value === undefined) {
+    op = '=';
+    val = operator;
+  } else {
+    if (typeof operator !== 'string') {
+      throw ErrorFactory.createDatabaseError('Unsafe SQL operator');
+    }
+    op = assertSafeOperator(operator);
+    val = value;
+    assertMatchOperator(op, val, state.dialect);
+  }
+
+  state.whereConditions.push({
+    column: col,
+    operator: op,
+    value: val,
+    boolean,
+    ...extra,
+  });
+};
+
+const createPredicateState = (dialect?: string): QueryState => ({
+  tableName: '',
+  whereConditions: [],
+  selectColumns: ['*'],
+  orderByClauses: [],
+  randomOrder: false,
+  joins: [],
+  groupByColumns: [],
+  eagerLoads: [],
+  eagerLoadConstraints: {},
+  eagerLoadCounts: [],
+  dialect,
+});
+
+const applyWhereColumnCompare = (
+  state: QueryState,
+  left: string,
+  operator: string,
+  right: string,
+  boolean: 'AND' | 'OR' = 'AND'
+): void => {
+  assertSafeIdentifierPath(left, 'where column left');
+  assertSafeIdentifierPath(right, 'where column right');
+  const op = assertSafeColumnCompareOperator(operator);
+
+  state.whereConditions.push({
+    kind: 'column-compare',
+    boolean,
+    left: left.trim(),
+    operator: op,
+    right: right.trim(),
+  });
+};
+
+const applyWhereExists = (
+  state: QueryState,
+  callback: (builder: IQueryBuilder) => unknown,
+  not: boolean,
+  boolean: 'AND' | 'OR' = 'AND'
+): void => {
+  const subState = createPredicateState(state.dialect);
+  const subBuilder = createBuilder(subState);
+  callback(subBuilder);
+
+  const table = subState.tableName.trim();
+  if (table.length === 0) {
+    throw ErrorFactory.createDatabaseError('EXISTS subquery requires from(table)');
+  }
+  assertSafeIdentifierPath(table, 'exists table');
+
+  state.whereConditions.push({
+    kind: 'exists',
+    not,
+    boolean,
+    table,
+    conditions: subState.whereConditions,
+  });
+};
+
+const applyJoin = (
+  state: QueryState,
+  table: string,
+  on: JoinOnInput,
+  type: 'INNER' | 'LEFT'
+): void => {
+  assertSafeIdentifierPath(table, 'join table');
+  const onSql = resolveJoinOnInput(on);
+  state.joins.push({ table: table.trim(), on: onSql, type });
+};
+
+const applyGroupBy = (state: QueryState, columns: string[]): void => {
+  for (const column of columns) {
+    const col = String(column).trim();
+    assertSafeIdentifierPath(col, 'group by column');
+    state.groupByColumns.push(col);
+  }
+};
+
+const applyLatestPer = (
+  state: QueryState,
+  partitionBy: string | string[],
+  options: LatestPerOptions
+): void => {
+  const partitions = (Array.isArray(partitionBy) ? partitionBy : [partitionBy])
+    .map((column) => String(column).trim())
+    .filter((column) => column.length > 0);
+
+  if (partitions.length === 0) {
+    throw ErrorFactory.createDatabaseError('latestPer requires at least one partition column');
+  }
+  for (const column of partitions) {
+    assertSafeIdentifierPath(column, 'window partition column');
+  }
+
+  if (!Array.isArray(options.orderBy) || options.orderBy.length === 0) {
+    throw ErrorFactory.createDatabaseError('latestPer requires at least one orderBy column');
+  }
+
+  const orderBy = options.orderBy.map(([column, direction]) => {
+    const col = String(column).trim();
+    assertSafeIdentifierPath(col, 'window order by column');
+    return { column: col, direction: normalizeOrderDirection(direction) };
+  });
+
+  const aliasRaw =
+    typeof options.alias === 'string' && options.alias.trim().length > 0
+      ? options.alias.trim()
+      : 'rn';
+  assertSafeIdentifier(aliasRaw, 'window alias');
+
+  state.latestPer = {
+    partitionBy: partitions,
+    orderBy,
+    alias: aliasRaw,
+  };
+};
+
+const applyWhereGroup = (
+  state: QueryState,
+  callback: (builder: IQueryBuilder) => unknown,
+  boolean: 'AND' | 'OR'
+): void => {
+  const groupState = createPredicateState(state.dialect);
+  const groupBuilder = createBuilder(groupState);
+  callback(groupBuilder);
+
+  if (groupState.whereConditions.length === 0) {
+    return;
+  }
+
+  state.whereConditions.push({
+    kind: 'group',
+    boolean,
+    conditions: groupState.whereConditions,
+  });
+};
+
+const flattenWherePredicates = (conditions: WherePredicate[]): WhereClause[] => {
+  const flattened: WhereClause[] = [];
+
+  for (const condition of conditions) {
+    if (isWhereGroupClause(condition)) {
+      flattened.push(...flattenWherePredicates(condition.conditions));
+      continue;
+    }
+    // Exists / column-compare predicates are not simple column clauses.
+    if (isWhereExistsClause(condition) || isWhereColumnCompareClause(condition)) {
+      continue;
+    }
+    flattened.push(condition);
+  }
+
+  return flattened;
+};
+
+const applyOrderByClause = (state: QueryState, column: string, direction?: string): void => {
+  const col = String(column).trim();
+  if (!isNumericLiteral(col)) {
+    assertSafeIdentifierPath(col, 'order by column');
+  }
+  const dir = normalizeOrderDirection(direction);
+  state.orderByClauses.push({ column: col, direction: dir });
+};
+
+const applyLimit = (state: QueryState, count: number): void => {
+  assertSafeLimitOffset(count, 'LIMIT');
+  state.limitValue = count;
+};
+
+const applyOffset = (state: QueryState, count: number): void => {
+  assertSafeLimitOffset(count, 'OFFSET');
+  state.offsetValue = count;
+};
+
+/**
+ * Execute query and return first result
+ */
+async function executeFirst<T>(builder: IQueryBuilder, db?: IDatabase): Promise<T | null> {
+  if (!db) throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+  builder.limit(1);
+  const results = (await db.query(
+    builder.toSQL(),
+    builder.getParameters(),
+    builder.isReadOperation()
+  )) as T[];
+  return results[0] ?? null;
+}
+
+async function executeFirstOrFail<T>(
+  builder: IQueryBuilder,
+  db: IDatabase | undefined,
+  message?: string
+): Promise<T> {
+  const result = await executeFirst<T>(builder, db);
+  if (result === null) throw ErrorFactory.createNotFoundError(message ?? 'Resource not found');
+  return result;
+}
+
+const compileInsert = (
+  tableName: string,
+  values: Record<string, unknown> | Array<Record<string, unknown>>,
+  dialect?: string
+): { sql: string; parameters: unknown[] } => {
+  const items = Array.isArray(values) ? values : [values];
+  if (items.length === 0) {
+    throw ErrorFactory.createDatabaseError('INSERT requires at least one column');
+  }
+
+  // Use keys from the first item
+  const keys = Object.keys(items[0] ?? {});
+  if (keys.length === 0) {
+    throw ErrorFactory.createDatabaseError('INSERT requires at least one column');
+  }
+
+  assertSafeIdentifierPath(tableName, 'table name');
+  for (const key of keys) assertSafeIdentifier(key, 'insert column');
+
+  const colsSql = keys.map((k) => escapeIdentifier(k, dialect)).join(', ');
+
+  // Single row or multi-row placeholders
+  const rowPlaceholders = `(${keys.map(() => '?').join(', ')})`;
+  const placeholders = items.map(() => rowPlaceholders).join(', ');
+
+  const parameters: unknown[] = [];
+  for (const item of items) {
+    for (const key of keys) {
+      parameters.push(item[key]);
+    }
+  }
+
+  const baseSql = `INSERT INTO ${escapeIdentifier(
+    tableName,
+    dialect
+  )} (${colsSql}) VALUES ${placeholders}`;
+  const wantsReturning = dialect === 'postgresql' && items.length === 1;
+  const sql = wantsReturning ? `${baseSql} RETURNING id` : baseSql;
+  return { sql, parameters };
+};
+
+const compileUpdate = (
+  tableName: string,
+  values: Record<string, unknown>,
+  conditions: WherePredicate[],
+  dialect?: string
+): { sql: string; parameters: unknown[] } => {
+  const keys = Object.keys(values);
+  if (keys.length === 0) {
+    throw ErrorFactory.createDatabaseError('UPDATE requires at least one column');
+  }
+  if (conditions.length === 0) {
+    throw ErrorFactory.createDatabaseError('UPDATE requires at least one WHERE clause');
+  }
+
+  assertSafeIdentifierPath(tableName, 'table name');
+  for (const key of keys) assertSafeIdentifier(key, 'update column');
+
+  const setParts: string[] = [];
+  const setParams: unknown[] = [];
+  for (const key of keys) {
+    const value = values[key];
+    if (isRawValue(value)) {
+      const rawSql = assertSafeRawExpression(value.__raw);
+      setParts.push(`${escapeIdentifier(key, dialect)} = ${rawSql}`);
+    } else {
+      setParts.push(`${escapeIdentifier(key, dialect)} = ?`);
+      setParams.push(value);
+    }
+  }
+  const setSql = setParts.join(', ');
+  const where = compileWhere(conditions, dialect);
+  const sql = `UPDATE ${escapeIdentifier(tableName, dialect)} SET ${setSql}${where.sql}`;
+  return { sql, parameters: [...setParams, ...where.parameters] };
+};
+
+const compileDelete = (
+  tableName: string,
+  conditions: WherePredicate[],
+  dialect?: string
+): { sql: string; parameters: unknown[] } => {
+  if (conditions.length === 0) {
+    throw ErrorFactory.createDatabaseError('DELETE requires at least one WHERE clause');
+  }
+  assertSafeIdentifierPath(tableName, 'table name');
+  const where = compileWhere(conditions, dialect);
+  const sql = `DELETE FROM ${escapeIdentifier(tableName, dialect)}${where.sql}`;
+  return { sql, parameters: where.parameters };
+};
+
+/**
+ * Execute query and return all results
+ */
+async function executeGet<T>(builder: IQueryBuilder, db?: IDatabase): Promise<T[]> {
+  if (!db) throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+  return (await db.query(
+    builder.toSQL(),
+    builder.getParameters(),
+    builder.isReadOperation()
+  )) as T[];
+}
+
+const normalizePaginationValue = (value: number, label: string): number => {
+  const n = Math.trunc(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw ErrorFactory.createValidationError(`${label} must be a positive integer`);
+  }
+  return n;
+};
+
+async function executePaginate<T>(
+  builder: IQueryBuilder,
+  state: QueryState,
+  db: IDatabase | undefined,
+  page: number,
+  perPage: number,
+  options?: PaginationOptions
+): Promise<Paginator<T>> {
+  if (!db) throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+
+  const safePage = normalizePaginationValue(page, 'page');
+  const safePerPage = normalizePaginationValue(perPage, 'perPage');
+
+  const countQuery = buildCountQuery(state, {
+    countDistinct: options?.countDistinct,
+  });
+  const countRows = (await db.query(countQuery.sql, countQuery.parameters, true)) as Array<
+    Record<string, unknown>
+  >;
+
+  const rawTotal = countRows.at(0)?.['total'];
+  const total = typeof rawTotal === 'bigint' ? Number(rawTotal) : Number(rawTotal ?? 0);
+  const sanitizedTotal = Number.isFinite(total) && total > 0 ? total : 0;
+
+  const offset = (safePage - 1) * safePerPage;
+  const prevLimit = state.limitValue;
+  const prevOffset = state.offsetValue;
+  state.limitValue = safePerPage;
+  state.offsetValue = offset;
+
+  const items = await executeGet<T>(builder, db);
+
+  state.limitValue = prevLimit;
+  state.offsetValue = prevOffset;
+
+  return createPaginator({
+    items,
+    total: sanitizedTotal,
+    perPage: safePerPage,
+    currentPage: safePage,
+    baseUrl: options?.baseUrl,
+    query: options?.query,
+  });
+}
+
+/**
+ * Create the builder object
+ */
+function attachSelectMethods(builder: IQueryBuilder, state: QueryState): void {
+  const clearDefaultStar = (): void => {
+    if (state.selectColumns.length === 1 && state.selectColumns[0] === '*')
+      state.selectColumns = [];
+  };
+
+  builder.select = (...columns) => {
+    state.selectColumns = columns.length > 0 ? columns : ['*'];
+    return builder;
+  };
+  builder.selectAs = (column, alias) => {
+    const col = String(column).trim();
+    const a = String(alias).trim();
+    assertSafeIdentifierPath(col, 'select column');
+    assertSafeIdentifier(a, 'select alias');
+    clearDefaultStar();
+    state.selectColumns.push(`${col} AS ${a}`);
+    return builder;
+  };
+  builder.max = (column, alias = 'max') => {
+    const col = String(column).trim();
+    const a = String(alias).trim();
+    assertSafeIdentifierPath(col, 'aggregate argument');
+    assertSafeIdentifier(a, 'aggregate alias');
+    clearDefaultStar();
+    state.selectColumns.push(`MAX(${col}) AS ${a}`);
+    return builder;
+  };
+}
+
+function attachWhereMethods(builder: IQueryBuilder, state: QueryState): void {
+  builder.where = (column, operator, value) => {
+    applyWhereCondition(state, column, operator, value, 'AND');
+    return builder;
+  };
+  builder.andWhere = (column, operator, value) => builder.where(column, operator, value);
+  builder.orWhere = (column, operator, value) => {
+    applyWhereCondition(state, column, operator, value, 'OR');
+    return builder;
+  };
+  builder.whereGroup = (callback) => {
+    applyWhereGroup(state, callback, 'AND');
+    return builder;
+  };
+  builder.orWhereGroup = (callback) => {
+    applyWhereGroup(state, callback, 'OR');
+    return builder;
+  };
+  builder.whereNormalized = (column, value, options) => {
+    applyWhereCondition(state, column, '=', value, 'AND', {
+      expression: 'normalized-text',
+      normalization: options,
+    });
+    return builder;
+  };
+  builder.orWhereNormalized = (column, value, options) => {
+    applyWhereCondition(state, column, '=', value, 'OR', {
+      expression: 'normalized-text',
+      normalization: options,
+    });
+    return builder;
+  };
+  builder.whereNull = (column) => builder.where(column, 'IS', null);
+  builder.whereNotNull = (column) => builder.where(column, 'IS NOT', null);
+  builder.whereIn = (column, values) => {
+    builder.where(column, 'IN', values);
+    return builder;
+  };
+  builder.whereNotIn = (column, values) => {
+    builder.where(column, 'NOT IN', values);
+    return builder;
+  };
+  builder.whereMatch = (column, query) => {
+    builder.where(column, 'MATCH', query);
+    return builder;
+  };
+  builder.whereNotMatch = (column, query) => {
+    builder.where(column, 'NOT MATCH', query);
+    return builder;
+  };
+  builder.whereColumn = (left, operator, right) => {
+    applyWhereColumnCompare(state, left, operator, right, 'AND');
+    return builder;
+  };
+  builder.whereExists = (callback) => {
+    applyWhereExists(state, callback, false, 'AND');
+    return builder;
+  };
+  builder.whereNotExists = (callback) => {
+    applyWhereExists(state, callback, true, 'AND');
+    return builder;
+  };
+  builder.from = (table) => {
+    const name = String(table).trim();
+    assertSafeIdentifierPath(name, 'table name');
+    state.tableName = name;
+    return builder;
+  };
+}
+
+function attachSoftDeleteMethods(builder: IQueryBuilder, state: QueryState): void {
+  builder.withTrashed = () => {
+    if (state.softDelete === undefined) {
+      state.softDelete = { column: 'deleted_at', mode: 'include' };
+    } else {
+      state.softDelete.mode = 'include';
+    }
+    return builder;
+  };
+  builder.onlyTrashed = () => {
+    if (state.softDelete === undefined) {
+      state.softDelete = { column: 'deleted_at', mode: 'only' };
+    } else {
+      state.softDelete.mode = 'only';
+    }
+    return builder;
+  };
+  builder.withoutTrashed = () => {
+    if (state.softDelete === undefined) {
+      state.softDelete = { column: 'deleted_at', mode: 'exclude' };
+    } else {
+      state.softDelete.mode = 'exclude';
+    }
+    return builder;
+  };
+}
+
+function attachJoinOrderPagingMethods(builder: IQueryBuilder, state: QueryState): void {
+  builder.join = (tableJoin, on) => {
+    applyJoin(state, tableJoin, on, 'INNER');
+    return builder;
+  };
+  builder.leftJoin = (tableJoin, on) => {
+    applyJoin(state, tableJoin, on, 'LEFT');
+    return builder;
+  };
+  builder.groupBy = (...columns) => {
+    applyGroupBy(state, columns);
+    return builder;
+  };
+  builder.latestPer = (partitionBy, options) => {
+    applyLatestPer(state, partitionBy, options);
+    return builder;
+  };
+  builder.orderBy = (column, direction = 'ASC') => {
+    applyOrderByClause(state, column, direction);
+    return builder;
+  };
+  builder.inRandomOrder = () => {
+    state.randomOrder = true;
+    return builder;
+  };
+  builder.limit = (count) => {
+    applyLimit(state, count);
+    return builder;
+  };
+  builder.offset = (count) => {
+    applyOffset(state, count);
+    return builder;
+  };
+}
+
+function attachIntrospectionMethods(builder: IQueryBuilder, state: QueryState): void {
+  builder.getWhereClauses = () => flattenWherePredicates(state.whereConditions);
+  builder.getSelectColumns = () => state.selectColumns;
+  builder.getTable = () => state.tableName;
+  builder.getLimit = () => state.limitValue;
+  builder.getOffset = () => state.offsetValue;
+  builder.getOrderBy = () => state.orderByClauses.at(-1);
+  builder.getJoins = () => state.joins;
+  builder.isReadOperation = () => true;
+  builder.toSQL = () => buildSelectQuery(state).sql;
+  builder.getParameters = () => buildSelectQuery(state).parameters;
+  // Internal method for eager loading distribution
+  (builder as unknown as { getEagerLoads: () => string[] }).getEagerLoads = () => state.eagerLoads;
+  (
+    builder as unknown as { getEagerLoadConstraints: () => EagerLoadConstraints }
+  ).getEagerLoadConstraints = () => state.eagerLoadConstraints;
+  (builder as unknown as { getEagerLoadCounts: () => string[] }).getEagerLoadCounts = () =>
+    state.eagerLoadCounts;
+}
+
+function attachReadExecutionMethods(
+  builder: IQueryBuilder,
+  state: QueryState,
+  db?: IDatabase
+): void {
+  builder.first = async <T>() => executeFirst<T>(builder, db);
+  builder.firstOrFail = async <T>(message?: string) => executeFirstOrFail<T>(builder, db, message);
+  builder.get = async <T>() => executeGet<T>(builder, db);
+  builder.paginate = async <T>(
+    page: number,
+    perPage: number,
+    options: PaginationOptions | undefined
+  ) => executePaginate<T>(builder, state, db, page, perPage, options);
+  // raw just returns results without any hydration logic in callers
+  builder.raw = async <T>() => executeGet<T>(builder, db);
+}
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+const isKeyValue = (value: unknown): value is string | number =>
+  typeof value === 'string' || typeof value === 'number';
+
+const getModelIds = (models: IModel[], key: string): Array<string | number> =>
+  models.map((model) => model.getAttribute(key)).filter((element) => isKeyValue(element));
+
+const normalizeCountValue = (value: number | bigint | null | undefined): number => {
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'number') return value;
+  return Number(value ?? 0);
+};
+
+const buildCountSql = (
+  tableName: string,
+  foreignKey: string,
+  ids: Array<string | number>,
+  dialect: ReturnType<IDatabase['getType']> | undefined
+): string =>
+  `SELECT ${escapeIdentifier(foreignKey, dialect)} as key, COUNT(*) as count FROM ${escapeIdentifier(
+    tableName,
+    dialect
+  )} WHERE ${escapeIdentifier(foreignKey, dialect)} IN (${ids
+    .map(() => '?')
+    .join(',')}) GROUP BY ${escapeIdentifier(foreignKey, dialect)}`;
+
+const queryCountMap = async (
+  db: IDatabase,
+  sql: string,
+  params: unknown[]
+): Promise<Map<string | number, number>> => {
+  const results = (await db.query(sql, params, true)) as Array<{
+    key: string | number;
+    count: number | bigint | null | undefined;
+  }>;
+
+  return new Map<string | number, number>(
+    results.map((row) => [row.key, normalizeCountValue(row.count)])
+  );
+};
+
+const setRelationCounts = (
+  models: IModel[],
+  relation: string,
+  localKey: string,
+  countMap: Map<string | number, number>
+): void => {
+  for (const model of models) {
+    const modelId = model.getAttribute(localKey);
+    const count = isKeyValue(modelId) ? (countMap.get(modelId) ?? 0) : 0;
+    model.setAttribute(`${relation}_count`, count);
+  }
+};
+
+const applyConstraint = (query: IQueryBuilder, constraint?: EagerLoadConstraint): IQueryBuilder => {
+  if (typeof constraint === 'function') {
+    return constraint(query) ?? query;
+  }
+  return query;
+};
+
+/**
+ * Load relationship counts for a collection of models
+ */
+async function loadCounts(models: IModel[], relation: string, db?: IDatabase): Promise<void> {
+  if (models.length === 0 || !db) return;
+
+  const rel = getRelationFromModels(models, relation);
+  if (rel === null || rel === undefined) return;
+
+  const relType = rel.type;
+
+  // Only hasMany and belongsToMany support counts
+  if (relType !== 'hasMany' && relType !== 'belongsToMany') {
+    return;
+  }
+
+  const foreignKey = rel.foreignKey;
+  const localKey = rel.localKey;
+
+  const ids = getModelIds(models, localKey);
+
+  if (ids.length === 0) return;
+
+  const dialect = typeof db.getType === 'function' ? db.getType() : undefined;
+
+  if (relType === 'hasMany') {
+    const relatedModel = rel.related as unknown as { query(): IQueryBuilder };
+    if (typeof relatedModel?.query !== 'function') return;
+
+    const tempQuery = relatedModel.query();
+    const relatedTable = tempQuery.getTable();
+
+    const countMap = await queryCountMap(
+      db,
+      buildCountSql(relatedTable, foreignKey, ids, dialect),
+      ids
+    );
+    setRelationCounts(models, relation, localKey, countMap);
+    return;
+  }
+
+  // belongsToMany
+  const throughTable = rel.throughTable;
+  const relatedKey = rel.relatedKey;
+  if (!isNonEmptyString(throughTable) || !isNonEmptyString(relatedKey)) return;
+
+  const countMap = await queryCountMap(
+    db,
+    buildCountSql(throughTable, foreignKey, ids, dialect),
+    ids
+  );
+  setRelationCounts(models, relation, localKey, countMap);
+}
+
+const getRelationFromModels = (models: IModel[], relation: string): IRelationship | null => {
+  const firstModel = models[0] as unknown as Record<string, () => IRelationship>;
+  const relationFactory = firstModel?.[relation];
+  if (typeof relationFactory !== 'function') return null;
+  const rel = relationFactory();
+  return rel ?? null;
+};
+
+const assignMorphToGroup = (
+  modelsByType: Map<string, IModel[]>,
+  type: string,
+  model: IModel
+): void => {
+  const existing = modelsByType.get(type);
+  if (existing) {
+    existing.push(model);
+  } else {
+    modelsByType.set(type, [model]);
+  }
+};
+
+const getModelTable = (model: IModel): string | null => {
+  const tableGetter = (model as unknown as { getTable?: () => string }).getTable;
+  if (typeof tableGetter !== 'function') return null;
+  const table = tableGetter();
+  return isNonEmptyString(table) ? table : null;
+};
+
+const buildSingleMap = (results: IModel[], key: string): Map<string | number, IModel> => {
+  const map = new Map<string | number, IModel>();
+  for (const result of results) {
+    const resultId = result.getAttribute(key);
+    if (isKeyValue(resultId)) {
+      map.set(resultId, result);
+    }
+  }
+  return map;
+};
+
+const buildBucketMap = (results: IModel[], key: string): Map<string | number, IModel[]> => {
+  const buckets = new Map<string | number, IModel[]>();
+  for (const result of results) {
+    const resultId = result.getAttribute(key);
+    if (isKeyValue(resultId)) {
+      const existing = buckets.get(resultId) ?? [];
+      existing.push(result);
+      buckets.set(resultId, existing);
+    }
+  }
+  return buckets;
+};
+
+const setRelationsFromBuckets = (
+  models: IModel[],
+  relation: string,
+  localKey: string,
+  buckets: Map<string | number, IModel[]>,
+  isMany: boolean
+): void => {
+  for (const model of models) {
+    const modelId = model.getAttribute(localKey);
+    if (!isKeyValue(modelId)) {
+      model.setRelation(relation, isMany ? [] : null);
+      continue;
+    }
+
+    const bucket = buckets.get(modelId) ?? [];
+    if (isMany) {
+      model.setRelation(relation, bucket);
+    } else {
+      model.setRelation(relation, bucket[0] ?? null);
+    }
+  }
+};
+
+const setBelongsToRelations = (
+  models: IModel[],
+  relation: string,
+  foreignKey: string,
+  relatedMap: Map<string | number, IModel>
+): void => {
+  for (const model of models) {
+    const relatedId = model.getAttribute(foreignKey);
+    if (!isKeyValue(relatedId)) {
+      model.setRelation(relation, null);
+      continue;
+    }
+
+    model.setRelation(relation, relatedMap.get(relatedId) ?? null);
+  }
+};
+
+const buildParentToThroughIds = (
+  throughResults: IModel[],
+  throughForeignKey: string,
+  secondLocalKey: string
+): Map<string | number, Array<string | number>> => {
+  const parentToThroughIds = new Map<string | number, Array<string | number>>();
+  for (const throughItem of throughResults) {
+    const parentId = throughItem.getAttribute(throughForeignKey);
+    const throughId = throughItem.getAttribute(secondLocalKey);
+    if (isKeyValue(parentId) && isKeyValue(throughId)) {
+      const existing = parentToThroughIds.get(parentId) ?? [];
+      existing.push(throughId);
+      parentToThroughIds.set(parentId, existing);
+    }
+  }
+  return parentToThroughIds;
+};
+
+const collectThroughRelated = (
+  throughIds: Array<string | number>,
+  relatedBuckets: Map<string | number, IModel[]>
+): IModel[] => {
+  const aggregated: IModel[] = [];
+  for (const throughId of throughIds) {
+    const bucket = relatedBuckets.get(throughId);
+    if (bucket !== undefined) {
+      aggregated.push(...bucket);
+    }
+  }
+  return aggregated;
+};
+
+const setThroughRelations = (
+  models: IModel[],
+  relation: string,
+  localKey: string,
+  parentToThroughIds: Map<string | number, Array<string | number>>,
+  relatedBuckets: Map<string | number, IModel[]>,
+  isMany: boolean
+): void => {
+  for (const model of models) {
+    const modelId = model.getAttribute(localKey);
+    if (!isKeyValue(modelId)) {
+      model.setRelation(relation, isMany ? [] : null);
+      continue;
+    }
+
+    const throughIds = parentToThroughIds.get(modelId) ?? [];
+    if (throughIds.length === 0) {
+      model.setRelation(relation, isMany ? [] : null);
+      continue;
+    }
+
+    const aggregated = collectThroughRelated(throughIds, relatedBuckets);
+    if (isMany) {
+      model.setRelation(relation, aggregated);
+    } else {
+      model.setRelation(relation, aggregated[0] ?? null);
+    }
+  }
+};
+
+const buildMorphToGroups = (models: IModel[], morphType: string): Map<string, IModel[]> => {
+  const modelsByType = new Map<string, IModel[]>();
+  for (const model of models) {
+    const type = model.getAttribute(morphType);
+    if (isNonEmptyString(type)) {
+      assignMorphToGroup(modelsByType, type, model);
+    }
+  }
+  return modelsByType;
+};
+
+const setMorphToRelations = (
+  models: IModel[],
+  relation: string,
+  morphId: string,
+  relatedMap: Map<string | number, IModel>
+): void => {
+  for (const model of models) {
+    const modelId = model.getAttribute(morphId);
+    if (isKeyValue(modelId)) {
+      model.setRelation(relation, relatedMap.get(modelId) ?? null);
+    } else {
+      model.setRelation(relation, null);
+    }
+  }
+};
+
+const loadMorphToGroup = async (
+  relation: string,
+  morphId: string,
+  modelsOfType: IModel[],
+  relatedModel: { query: () => IQueryBuilder },
+  constraint?: EagerLoadConstraint
+): Promise<void> => {
+  const ids = getModelIds(modelsOfType, morphId);
+  if (ids.length === 0) return;
+
+  const relatedQuery = applyConstraint(relatedModel.query(), constraint);
+
+  const relatedResults = await relatedQuery.whereIn('id', ids).get<IModel>();
+  const relatedMap = buildSingleMap(relatedResults, 'id');
+  setMorphToRelations(modelsOfType, relation, morphId, relatedMap);
+};
+
+const loadMorphToRelation = async (
+  models: IModel[],
+  relation: string,
+  rel: IRelationship,
+  constraint?: EagerLoadConstraint
+): Promise<boolean> => {
+  if (rel.type !== 'morphTo') return false;
+
+  const morphType = rel.morphType;
+  const morphId = rel.morphId;
+  const morphMap = rel.morphMap;
+
+  if (
+    !isNonEmptyString(morphType) ||
+    !isNonEmptyString(morphId) ||
+    morphMap === null ||
+    morphMap === undefined
+  ) {
+    return true;
+  }
+
+  const modelsByType = buildMorphToGroups(models, morphType);
+
+  const tasks = [...modelsByType.entries()].map(async ([type, modelsOfType]) => {
+    const relatedModel = morphMap[type] as unknown as { query(): IQueryBuilder } | undefined;
+    if (relatedModel === undefined || typeof relatedModel.query !== 'function') {
+      return Promise.resolve(); //NOSONAR
+    }
+
+    return loadMorphToGroup(relation, morphId, modelsOfType, relatedModel, constraint);
+  });
+
+  await Promise.all(tasks);
+
+  return true;
+};
+
+const prepareMorphOneMany = (
+  models: IModel[],
+  rel: IRelationship,
+  localKey: string | undefined,
+  morphId: string | undefined,
+  morphType: string | undefined
+): {
+  proceed: boolean;
+  ids?: Array<string | number>;
+  relatedModel?: { query?: () => IQueryBuilder };
+  tableName?: string;
+} => {
+  if (!isNonEmptyString(morphType) || !isNonEmptyString(morphId) || !isNonEmptyString(localKey)) {
+    return { proceed: false };
+  }
+
+  const ids = getModelIds(models, localKey);
+  if (ids.length === 0) return { proceed: false };
+
+  const relatedModel = rel.related as unknown as { query?: () => IQueryBuilder };
+  if (typeof relatedModel.query !== 'function') return { proceed: false };
+
+  const tableName = getModelTable(models[0]);
+  if (tableName === null) return { proceed: false };
+
+  return { proceed: true, ids, relatedModel, tableName };
+};
+
+const loadMorphOneManyRelation = async (
+  models: IModel[],
+  relation: string,
+  rel: IRelationship,
+  constraint?: EagerLoadConstraint
+): Promise<boolean> => {
+  if (rel.type !== 'morphOne' && rel.type !== 'morphMany') return false;
+
+  const morphType = rel.morphType;
+  const morphId = rel.morphId;
+  const localKey = rel.localKey;
+
+  const prep = prepareMorphOneMany(models, rel, localKey, morphId, morphType);
+  if (
+    !prep.proceed ||
+    prep.ids === undefined ||
+    prep.relatedModel === undefined ||
+    prep.tableName === undefined ||
+    !isNonEmptyString(morphType) ||
+    !isNonEmptyString(morphId) ||
+    !isNonEmptyString(localKey)
+  ) {
+    return true;
+  }
+
+  const ids = prep.ids;
+  const relatedModel = prep.relatedModel as { query(): IQueryBuilder };
+  const tableName = prep.tableName;
+
+  const relatedQuery = applyConstraint(relatedModel.query(), constraint)
+    .where(morphType, '=', tableName)
+    .whereIn(morphId, ids);
+
+  const relatedResults = await relatedQuery.get<IModel>();
+  const relatedBuckets = buildBucketMap(relatedResults, morphId);
+  const isMany = rel.type === 'morphMany';
+  setRelationsFromBuckets(models, relation, localKey, relatedBuckets, isMany);
+
+  return true;
+};
+
+const loadThroughRelation = async (
+  models: IModel[],
+  relation: string,
+  rel: IRelationship,
+  constraint?: EagerLoadConstraint
+): Promise<boolean> => {
+  if (rel.type !== 'hasOneThrough' && rel.type !== 'hasManyThrough') return false;
+
+  const through = rel.through;
+  const throughForeignKey = rel.throughForeignKey;
+  const secondLocalKey = rel.secondLocalKey;
+  const foreignKey = rel.foreignKey;
+  const localKey = rel.localKey;
+
+  if (
+    through === undefined ||
+    through === null ||
+    !isNonEmptyString(throughForeignKey) ||
+    !isNonEmptyString(secondLocalKey) ||
+    !isNonEmptyString(foreignKey) ||
+    !isNonEmptyString(localKey)
+  ) {
+    return true;
+  }
+
+  const ids = getModelIds(models, localKey);
+  if (ids.length === 0) return true;
+
+  const throughModel = through as unknown as {
+    query(): IQueryBuilder;
+    getTable?: () => string;
+  };
+  const relatedModel = rel.related as unknown as {
+    query(): IQueryBuilder;
+    getTable?: () => string;
+  };
+
+  if (
+    typeof throughModel.getTable !== 'function' ||
+    typeof relatedModel.query !== 'function' ||
+    typeof relatedModel.getTable !== 'function'
+  ) {
+    return true;
+  }
+
+  const throughTable = throughModel.getTable();
+  const relatedTable = relatedModel.getTable();
+  if (!isNonEmptyString(throughTable) || !isNonEmptyString(relatedTable)) return true;
+
+  let relatedQuery = relatedModel.query();
+  relatedQuery = applyConstraint(relatedQuery, constraint);
+
+  relatedQuery = relatedQuery
+    .join(throughTable, `${relatedTable}.${foreignKey} = ${throughTable}.${secondLocalKey}`)
+    .whereIn(`${throughTable}.${throughForeignKey}`, ids);
+
+  const relatedResults = await relatedQuery.get<IModel>();
+
+  const throughQuery = throughModel.query().whereIn(throughForeignKey, ids);
+  const throughResults = await throughQuery.get<IModel>();
+
+  const parentToThroughIds = buildParentToThroughIds(
+    throughResults,
+    throughForeignKey,
+    secondLocalKey
+  );
+
+  const relatedBuckets = buildBucketMap(relatedResults, foreignKey);
+
+  const isMany = rel.type === 'hasManyThrough';
+  setThroughRelations(models, relation, localKey, parentToThroughIds, relatedBuckets, isMany);
+
+  return true;
+};
+
+const loadBelongsToRelation = async (
+  models: IModel[],
+  relation: string,
+  rel: IRelationship,
+  constraint?: EagerLoadConstraint
+): Promise<boolean> => {
+  if (rel.type !== 'belongsTo') return false;
+
+  const foreignKey = rel.foreignKey;
+  const ownerKey = rel.localKey;
+  if (!isNonEmptyString(foreignKey) || !isNonEmptyString(ownerKey)) return true;
+
+  const relatedModel = rel.related as unknown as { query(): IQueryBuilder };
+  if (typeof relatedModel.query !== 'function') return true;
+
+  const ids = getModelIds(models, foreignKey);
+  if (ids.length === 0) {
+    setBelongsToRelations(models, relation, foreignKey, new Map());
+    return true;
+  }
+
+  const relatedQuery = applyConstraint(relatedModel.query(), constraint);
+  const relatedResults = await relatedQuery.whereIn(ownerKey, ids).get<IModel>();
+  const relatedMap = buildSingleMap(relatedResults, ownerKey);
+  setBelongsToRelations(models, relation, foreignKey, relatedMap);
+
+  return true;
+};
+
+const BELONGS_TO_MANY_PARENT_KEY_ALIAS = '__zin_belongs_to_many_parent_key';
+
+const resolveRelatedTableName = (relatedModel: {
+  query?: () => IQueryBuilder;
+  getTable?: () => string;
+}): string | null => {
+  if (typeof relatedModel.getTable === 'function') {
+    const tableName = relatedModel.getTable();
+    return isNonEmptyString(tableName) ? tableName : null;
+  }
+
+  if (typeof relatedModel.query !== 'function') return null;
+  const query = relatedModel.query();
+  const tableName = query.getTable();
+  return isNonEmptyString(tableName) ? tableName : null;
+};
+
+const loadBelongsToManyRelation = async (
+  models: IModel[],
+  relation: string,
+  rel: IRelationship,
+  constraint?: EagerLoadConstraint
+): Promise<boolean> => {
+  if (rel.type !== 'belongsToMany') return false;
+
+  const throughTable = rel.throughTable;
+  const foreignKey = rel.foreignKey;
+  const relatedKey = rel.relatedKey;
+  const localKey = rel.localKey;
+  if (
+    !isNonEmptyString(throughTable) ||
+    !isNonEmptyString(foreignKey) ||
+    !isNonEmptyString(relatedKey) ||
+    !isNonEmptyString(localKey)
+  ) {
+    return true;
+  }
+
+  const relatedModel = rel.related as unknown as {
+    query(): IQueryBuilder;
+    getTable?: () => string;
+  };
+  if (typeof relatedModel.query !== 'function') return true;
+
+  const ids = getModelIds(models, localKey);
+  if (ids.length === 0) {
+    setRelationsFromBuckets(models, relation, localKey, new Map(), true);
+    return true;
+  }
+
+  const relatedTable = resolveRelatedTableName(relatedModel);
+  if (!isNonEmptyString(relatedTable)) return true;
+
+  const relatedQuery = applyConstraint(relatedModel.query(), constraint)
+    .join(throughTable, `${relatedTable}.id = ${throughTable}.${relatedKey}`)
+    .selectAs(`${throughTable}.${foreignKey}`, BELONGS_TO_MANY_PARENT_KEY_ALIAS)
+    .whereIn(`${throughTable}.${foreignKey}`, ids);
+
+  const relatedResults = await relatedQuery.get<IModel>();
+  const relatedBuckets = buildBucketMap(relatedResults, BELONGS_TO_MANY_PARENT_KEY_ALIAS);
+  setRelationsFromBuckets(models, relation, localKey, relatedBuckets, true);
+
+  return true;
+};
+
+const loadStandardRelation = async (
+  models: IModel[],
+  relation: string,
+  rel: IRelationship,
+  constraint?: EagerLoadConstraint
+): Promise<boolean> => {
+  const related = (rel as unknown as { related?: unknown }).related;
+  if (related === null || related === undefined) return false;
+
+  const foreignKey = rel.foreignKey;
+  const localKey = rel.localKey;
+  if (!isNonEmptyString(foreignKey) || !isNonEmptyString(localKey)) return false;
+
+  const ids = getModelIds(models, localKey);
+  if (ids.length === 0) return true;
+
+  const relatedModel = rel.related as unknown as { query(): IQueryBuilder };
+  if (typeof relatedModel.query !== 'function') return false;
+
+  const relatedQuery = applyConstraint(relatedModel.query(), constraint);
+  const relatedResults = await relatedQuery.whereIn(foreignKey, ids).get<IModel>();
+  const relatedBuckets = buildBucketMap(relatedResults, foreignKey);
+  const isMany = rel.type === 'hasMany' || rel.type === 'belongsToMany';
+  setRelationsFromBuckets(models, relation, localKey, relatedBuckets, isMany);
+
+  return true;
+};
+
+const loadRelation = async (
+  models: IModel[],
+  relation: string,
+  constraint?: EagerLoadConstraint
+): Promise<void> => {
+  if (models.length === 0) return;
+  const rel = getRelationFromModels(models, relation);
+  if (!rel) return;
+
+  const type = rel.type;
+  if (type === 'morphTo') {
+    await loadMorphToRelation(models, relation, rel, constraint);
+    return;
+  }
+  if (type === 'morphOne' || type === 'morphMany') {
+    await loadMorphOneManyRelation(models, relation, rel, constraint);
+    return;
+  }
+  if (type === 'hasOneThrough' || type === 'hasManyThrough') {
+    await loadThroughRelation(models, relation, rel, constraint);
+    return;
+  }
+  if (type === 'belongsTo') {
+    await loadBelongsToRelation(models, relation, rel, constraint);
+    return;
+  }
+  if (type === 'belongsToMany') {
+    await loadBelongsToManyRelation(models, relation, rel, constraint);
+    return;
+  }
+  await loadStandardRelation(models, relation, rel, constraint);
+};
+
+function attachRelationshipMethods(
+  builder: IQueryBuilder,
+  state: QueryState,
+  db?: IDatabase
+): void {
+  builder.with = (relation: string | EagerLoadConstraints) => {
+    if (typeof relation === 'string') {
+      state.eagerLoads.push(relation);
+      return builder;
+    }
+
+    for (const [name, constraint] of Object.entries(relation)) {
+      if (state.eagerLoads.includes(name) === false) {
+        state.eagerLoads.push(name);
+      }
+      state.eagerLoadConstraints[name] = constraint;
+    }
+
+    return builder;
+  };
+
+  builder.withCount = (relation: string) => {
+    state.eagerLoadCounts.push(relation);
+    return builder;
+  };
+
+  builder.load = async (models: IModel[], relation: string, constraint?: EagerLoadConstraint) => {
+    await loadRelation(models, relation, constraint);
+  };
+
+  builder.loadCount = async (models: IModel[], relation: string) => {
+    await loadCounts(models, relation, db);
+  };
+}
+
+function attachWriteMethods(builder: IQueryBuilder, state: QueryState, db?: IDatabase): void {
+  const ensureDb = (): IDatabase => {
+    if (!db)
+      throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+    return db;
+  };
+
+  builder.insert = async (values) => {
+    const currentDb = ensureDb();
+    const tableName = state.tableName.trim();
+    if (tableName.length === 0)
+      throw ErrorFactory.createDatabaseError('INSERT requires a table name');
+    const compiled = compileInsert(tableName, values, state.dialect);
+    const items = Array.isArray(values) ? values : [values];
+
+    const result = await currentDb.execute(compiled.sql, compiled.parameters, false);
+
+    // Return InsertResult with metadata
+    // Note: lastInsertId typically only available for single-row inserts in most databases
+    // For multi-row inserts, use the insertedRecords array
+    return {
+      id:
+        (result.lastInsertId as string | number | bigint) ??
+        (items.length === 1 ? ((items[0]?.['id'] as string | number | null) ?? null) : null),
+      affectedRows: result.rowCount,
+      insertedRecords: items,
+    };
+  };
+  builder.update = async (values) => {
+    const currentDb = ensureDb();
+    const tableName = state.tableName.trim();
+    if (tableName.length === 0)
+      throw ErrorFactory.createDatabaseError('UPDATE requires a table name');
+    const compiled = compileUpdate(tableName, values, state.whereConditions, state.dialect);
+    await currentDb.query(compiled.sql, compiled.parameters, false);
+  };
+  builder.delete = async () => {
+    const currentDb = ensureDb();
+    const tableName = state.tableName.trim();
+    if (tableName.length === 0)
+      throw ErrorFactory.createDatabaseError('DELETE requires a table name');
+    const compiled = compileDelete(tableName, state.whereConditions, state.dialect);
+    await currentDb.query(compiled.sql, compiled.parameters, false);
+  };
+}
+
+function createBuilder(state: QueryState, db?: IDatabase): IQueryBuilder {
+  const builder = {} as IQueryBuilder;
+
+  attachSelectMethods(builder, state);
+  attachWhereMethods(builder, state);
+  attachSoftDeleteMethods(builder, state);
+  attachJoinOrderPagingMethods(builder, state);
+  attachIntrospectionMethods(builder, state);
+  attachReadExecutionMethods(builder, state, db);
+  attachRelationshipMethods(builder, state, db);
+  attachWriteMethods(builder, state, db);
+
+  return builder;
+}
+
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Sealed namespace object following Pattern 2
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export const QueryBuilder = Object.freeze({
+  /**
+   * Create a new query builder instance
+   */
+  create(
+    tableOrDb: string | IDatabase,
+    db?: IDatabase,
+    options: QueryBuilderOptions = {}
+  ): IQueryBuilder {
+    const hasTable = typeof tableOrDb === 'string';
+    const tableName = hasTable ? String(tableOrDb).trim() : '';
+    const database = hasTable ? db : tableOrDb;
+
+    if (tableName.length > 0) {
+      assertSafeIdentifierPath(tableName, 'table name');
+    }
+    const state: QueryState = {
+      tableName,
+      whereConditions: [],
+      selectColumns: ['*'],
+      orderByClauses: [],
+      randomOrder: false,
+      joins: [],
+      groupByColumns: [],
+      eagerLoads: [],
+      eagerLoadConstraints: {},
+      eagerLoadCounts: [],
+      dialect: typeof database?.getType === 'function' ? database.getType() : undefined,
+    };
+
+    if (options.softDeleteColumn !== undefined && options.softDeleteColumn.trim().length > 0) {
+      state.softDelete = {
+        column: options.softDeleteColumn.trim(),
+        mode: options.softDeleteMode ?? 'exclude',
+      };
+    }
+
+    return createBuilder(state, database);
+  },
+
+  /**
+   * Ping the database connection.
+   *
+   * This is intentionally a tiny, dependency-free check that can be reused by
+   * health/readiness endpoints without embedding SQL in route handlers.
+   */
+  async ping(db: IDatabase): Promise<void> {
+    // Use the QueryBuilder itself to avoid embedding raw SQL at call sites.
+    await QueryBuilder.create('', db).select('1').get();
+  },
+});