@zintrust/core 3.5.1 → 3.6.0

package/src/orm/QueryBuilder.ts

@@ -1,2419 +0,0 @@
-/**
- * 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();
-  },
-});