@zintrust/core 3.5.1 → 3.5.2

package/src/orm/QueryBuilder.js

@@ -0,0 +1,1711 @@
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Build queries without raw SQL
+ */
+import { createPaginator } from '../database/Paginator.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const getIdentifierQuote = (dialect) => {
+    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, dialect) => {
+    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, label) => {
+    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, label) => {
+    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) => typeof value === 'object' &&
+    value !== null &&
+    '__raw' in value &&
+    typeof value.__raw === 'string';
+const assertSafeRawExpression = (raw) => {
+    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) => {
+    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) => value === 'OR' ? 'OR' : 'AND';
+const normalizeTextOptions = (options) => ({
+    trim: options?.trim !== false,
+    lowercase: options?.lowercase !== false,
+});
+const normalizeTextComparisonValue = (value, options) => {
+    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, dialect, options) => {
+    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) => 'kind' in value && value.kind === 'group';
+const isWhereExistsClause = (value) => 'kind' in value && value.kind === 'exists';
+const isWhereColumnCompareClause = (value) => 'kind' in value && value.kind === 'column-compare';
+const normalizeOperator = (operator) => operator.trim().toUpperCase();
+const ALLOWED_COLUMN_COMPARE_OPERATORS = new Set(['=', '!=', '<>', '<', '<=', '>', '>=']);
+const assertSafeColumnCompareOperator = (operator) => {
+    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) => {
+    const d = (dialect ?? '').toLowerCase();
+    return d === 'sqlite' || d === 'd1' || d === 'd1-remote';
+};
+const assertSafeOperator = (operator) => {
+    const normalized = normalizeOperator(operator);
+    if (!ALLOWED_OPERATORS.has(normalized)) {
+        throw ErrorFactory.createDatabaseError('Unsafe SQL operator');
+    }
+    return normalized;
+};
+const assertMatchOperator = (operator, value, dialect) => {
+    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, label) => {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        throw ErrorFactory.createDatabaseError(`Unsafe ${label} value`);
+    }
+};
+const isNumericLiteral = (value) => {
+    // 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);
+};
+const ALLOWED_AGGREGATES = new Set(['MAX', 'MIN', 'COUNT', 'SUM', 'AVG']);
+const tryParseAggregateSelectExpr = (raw) => {
+    // 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();
+    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) => {
+    // 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) => {
+    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, dialect) => {
+    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, dialect) => {
+    const out = [];
+    for (const c of columns) {
+        const parsed = tryParseSelectExpr(String(c));
+        out.push(formatSelectExpr(parsed, dialect));
+    }
+    return out.join(', ');
+};
+const compileInWhereClause = (columnSql, operator, value) => {
+    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, operator, value) => {
+    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, operator, value) => {
+    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, operator, value, expression, normalization) => {
+    const finalValue = expression === 'normalized-text' ? normalizeTextComparisonValue(value, normalization) : value;
+    return { sql: `${columnSql} ${operator} ?`, parameters: [finalValue] };
+};
+const compileSingleWhereClause = (clause, dialect) => {
+    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, dialect) => {
+    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, dialect) => {
+    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, dialect) => {
+    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, dialect) => {
+    if (conditions.length === 0)
+        return { sql: '', parameters: [] };
+    const parameters = [];
+    const fragments = [];
+    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, dialect) => {
+    const compiled = compileWhereFragments(conditions, dialect);
+    return compiled.sql.length === 0
+        ? { sql: '', parameters: [] }
+        : { sql: ` WHERE ${compiled.sql}`, parameters: compiled.parameters };
+};
+const buildSoftDeleteWhereClause = (column, mode) => {
+    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) => {
+    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, randomOrder, dialect) => {
+    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, offset) => {
+    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*)*)$/;
+const parseJoinOnTerms = (on) => {
+    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) => {
+    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 = [];
+    const joinOnBuilder = Object.freeze({
+        on(left, operator, right) {
+            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, dialect) => {
+    const terms = parseJoinOnTerms(on);
+    return terms
+        .map((term) => `${escapeIdentifier(term.left, dialect)} ${term.op} ${escapeIdentifier(term.right, dialect)}`)
+        .join(' AND ');
+};
+const buildJoinClause = (joins, dialect) => joins
+    .map(({ table, on, type }) => {
+    assertSafeIdentifierPath(table, 'join table');
+    return ` ${type} JOIN ${escapeIdentifier(table, dialect)} ON ${buildJoinOnSql(on, dialect)}`;
+})
+    .join('');
+const buildGroupByClause = (columns, dialect) => {
+    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, dialect) => {
+    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, dialect) => {
+    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, columnsSql, options) => {
+    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) => {
+    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) => {
+    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, options) => {
+    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, column, operator, value, boolean = 'AND', extra = {}) => {
+    const col = String(column).trim();
+    assertSafeIdentifierPath(col, 'where column');
+    let op;
+    let val;
+    // 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) => ({
+    tableName: '',
+    whereConditions: [],
+    selectColumns: ['*'],
+    orderByClauses: [],
+    randomOrder: false,
+    joins: [],
+    groupByColumns: [],
+    eagerLoads: [],
+    eagerLoadConstraints: {},
+    eagerLoadCounts: [],
+    dialect,
+});
+const applyWhereColumnCompare = (state, left, operator, right, boolean = 'AND') => {
+    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, callback, not, boolean = 'AND') => {
+    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, table, on, type) => {
+    assertSafeIdentifierPath(table, 'join table');
+    const onSql = resolveJoinOnInput(on);
+    state.joins.push({ table: table.trim(), on: onSql, type });
+};
+const applyGroupBy = (state, columns) => {
+    for (const column of columns) {
+        const col = String(column).trim();
+        assertSafeIdentifierPath(col, 'group by column');
+        state.groupByColumns.push(col);
+    }
+};
+const applyLatestPer = (state, partitionBy, options) => {
+    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, callback, boolean) => {
+    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) => {
+    const flattened = [];
+    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, column, direction) => {
+    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, count) => {
+    assertSafeLimitOffset(count, 'LIMIT');
+    state.limitValue = count;
+};
+const applyOffset = (state, count) => {
+    assertSafeLimitOffset(count, 'OFFSET');
+    state.offsetValue = count;
+};
+/**
+ * Execute query and return first result
+ */
+async function executeFirst(builder, db) {
+    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()));
+    return results[0] ?? null;
+}
+async function executeFirstOrFail(builder, db, message) {
+    const result = await executeFirst(builder, db);
+    if (result === null)
+        throw ErrorFactory.createNotFoundError(message ?? 'Resource not found');
+    return result;
+}
+const compileInsert = (tableName, values, dialect) => {
+    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 = [];
+    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 compileInsertIfAbsent = (tableName, values, conflictColumns, dialect) => {
+    const compiled = compileInsert(tableName, values, dialect);
+    const dialectName = (dialect ?? '').toLowerCase();
+    if (dialectName === 'mysql') {
+        return { ...compiled, sql: compiled.sql.replace(/^INSERT INTO/i, 'INSERT IGNORE INTO') };
+    }
+    if (dialectName === 'sqlite' || dialectName === 'd1' || dialectName === 'd1-remote' || dialectName === 'postgresql') {
+        const columns = conflictColumns ?? [];
+        for (const column of columns)
+            assertSafeIdentifier(column, 'conflict column');
+        const target = columns.length === 0
+            ? ''
+            : ` (${columns.map((column) => escapeIdentifier(column, dialect)).join(', ')})`;
+        const returning = dialectName === 'postgresql' && compiled.sql.endsWith(' RETURNING id');
+        const insertSql = returning ? compiled.sql.slice(0, -' RETURNING id'.length) : compiled.sql;
+        const conflictSql = `${insertSql} ON CONFLICT${target} DO NOTHING`;
+        return {
+            ...compiled,
+            sql: returning ? `${conflictSql} RETURNING id` : conflictSql,
+        };
+    }
+    throw ErrorFactory.createDatabaseError(`insertIfAbsent is not supported for the ${dialectName || 'unknown'} database driver`);
+};
+const compileIncrement = (tableName, column, amount, conditions, dialect) => {
+    if (!Number.isFinite(amount)) {
+        throw ErrorFactory.createDatabaseError('Increment amount must be a finite number');
+    }
+    if (conditions.length === 0) {
+        throw ErrorFactory.createDatabaseError('UPDATE requires at least one WHERE clause');
+    }
+    assertSafeIdentifierPath(tableName, 'table name');
+    assertSafeIdentifierPath(column, 'increment column');
+    const columnSql = escapeIdentifier(column, dialect);
+    const where = compileWhere(conditions, dialect);
+    return {
+        sql: `UPDATE ${escapeIdentifier(tableName, dialect)} SET ${columnSql} = ${columnSql} + ?${where.sql}`,
+        parameters: [amount, ...where.parameters],
+    };
+};
+const compileUpdate = (tableName, values, conditions, dialect) => {
+    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 = [];
+    const setParams = [];
+    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, conditions, dialect) => {
+    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(builder, db) {
+    if (!db)
+        throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+    return (await db.query(builder.toSQL(), builder.getParameters(), builder.isReadOperation()));
+}
+const normalizePaginationValue = (value, label) => {
+    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(builder, state, db, page, perPage, options) {
+    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));
+    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(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, state) {
+    const clearDefaultStar = () => {
+        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, state) {
+    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, state) {
+    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, state) {
+    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, state) {
+    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.getEagerLoads = () => state.eagerLoads;
+    builder.getEagerLoadConstraints = () => state.eagerLoadConstraints;
+    builder.getEagerLoadCounts = () => state.eagerLoadCounts;
+}
+function attachReadExecutionMethods(builder, state, db) {
+    builder.first = async () => executeFirst(builder, db);
+    builder.firstOrFail = async (message) => executeFirstOrFail(builder, db, message);
+    builder.get = async () => executeGet(builder, db);
+    builder.paginate = async (page, perPage, options) => executePaginate(builder, state, db, page, perPage, options);
+    // raw just returns results without any hydration logic in callers
+    builder.raw = async () => executeGet(builder, db);
+}
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+const isKeyValue = (value) => typeof value === 'string' || typeof value === 'number';
+const getModelIds = (models, key) => models.map((model) => model.getAttribute(key)).filter((element) => isKeyValue(element));
+const normalizeCountValue = (value) => {
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'number')
+        return value;
+    return Number(value ?? 0);
+};
+const buildCountSql = (tableName, foreignKey, ids, dialect) => `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, sql, params) => {
+    const results = (await db.query(sql, params, true));
+    return new Map(results.map((row) => [row.key, normalizeCountValue(row.count)]));
+};
+const setRelationCounts = (models, relation, localKey, countMap) => {
+    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, constraint) => {
+    if (typeof constraint === 'function') {
+        return constraint(query) ?? query;
+    }
+    return query;
+};
+/**
+ * Load relationship counts for a collection of models
+ */
+async function loadCounts(models, relation, db) {
+    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;
+        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, relation) => {
+    const firstModel = models[0];
+    const relationFactory = firstModel?.[relation];
+    if (typeof relationFactory !== 'function')
+        return null;
+    const rel = relationFactory();
+    return rel ?? null;
+};
+const assignMorphToGroup = (modelsByType, type, model) => {
+    const existing = modelsByType.get(type);
+    if (existing) {
+        existing.push(model);
+    }
+    else {
+        modelsByType.set(type, [model]);
+    }
+};
+const getModelTable = (model) => {
+    const tableGetter = model.getTable;
+    if (typeof tableGetter !== 'function')
+        return null;
+    const table = tableGetter();
+    return isNonEmptyString(table) ? table : null;
+};
+const buildSingleMap = (results, key) => {
+    const map = new Map();
+    for (const result of results) {
+        const resultId = result.getAttribute(key);
+        if (isKeyValue(resultId)) {
+            map.set(resultId, result);
+        }
+    }
+    return map;
+};
+const buildBucketMap = (results, key) => {
+    const buckets = new Map();
+    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, relation, localKey, buckets, isMany) => {
+    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, relation, foreignKey, relatedMap) => {
+    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, throughForeignKey, secondLocalKey) => {
+    const parentToThroughIds = new Map();
+    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, relatedBuckets) => {
+    const aggregated = [];
+    for (const throughId of throughIds) {
+        const bucket = relatedBuckets.get(throughId);
+        if (bucket !== undefined) {
+            aggregated.push(...bucket);
+        }
+    }
+    return aggregated;
+};
+const setThroughRelations = (models, relation, localKey, parentToThroughIds, relatedBuckets, isMany) => {
+    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, morphType) => {
+    const modelsByType = new Map();
+    for (const model of models) {
+        const type = model.getAttribute(morphType);
+        if (isNonEmptyString(type)) {
+            assignMorphToGroup(modelsByType, type, model);
+        }
+    }
+    return modelsByType;
+};
+const setMorphToRelations = (models, relation, morphId, relatedMap) => {
+    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, morphId, modelsOfType, relatedModel, constraint) => {
+    const ids = getModelIds(modelsOfType, morphId);
+    if (ids.length === 0)
+        return;
+    const relatedQuery = applyConstraint(relatedModel.query(), constraint);
+    const relatedResults = await relatedQuery.whereIn('id', ids).get();
+    const relatedMap = buildSingleMap(relatedResults, 'id');
+    setMorphToRelations(modelsOfType, relation, morphId, relatedMap);
+};
+const loadMorphToRelation = async (models, relation, rel, constraint) => {
+    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];
+        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, rel, localKey, morphId, morphType) => {
+    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;
+    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, relation, rel, constraint) => {
+    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;
+    const tableName = prep.tableName;
+    const relatedQuery = applyConstraint(relatedModel.query(), constraint)
+        .where(morphType, '=', tableName)
+        .whereIn(morphId, ids);
+    const relatedResults = await relatedQuery.get();
+    const relatedBuckets = buildBucketMap(relatedResults, morphId);
+    const isMany = rel.type === 'morphMany';
+    setRelationsFromBuckets(models, relation, localKey, relatedBuckets, isMany);
+    return true;
+};
+const loadThroughRelation = async (models, relation, rel, constraint) => {
+    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;
+    const relatedModel = rel.related;
+    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();
+    const throughQuery = throughModel.query().whereIn(throughForeignKey, ids);
+    const throughResults = await throughQuery.get();
+    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, relation, rel, constraint) => {
+    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;
+    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();
+    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) => {
+    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, relation, rel, constraint) => {
+    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;
+    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();
+    const relatedBuckets = buildBucketMap(relatedResults, BELONGS_TO_MANY_PARENT_KEY_ALIAS);
+    setRelationsFromBuckets(models, relation, localKey, relatedBuckets, true);
+    return true;
+};
+const loadStandardRelation = async (models, relation, rel, constraint) => {
+    const related = rel.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;
+    if (typeof relatedModel.query !== 'function')
+        return false;
+    const relatedQuery = applyConstraint(relatedModel.query(), constraint);
+    const relatedResults = await relatedQuery.whereIn(foreignKey, ids).get();
+    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, relation, constraint) => {
+    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, state, db) {
+    builder.with = (relation) => {
+        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) => {
+        state.eagerLoadCounts.push(relation);
+        return builder;
+    };
+    builder.load = async (models, relation, constraint) => {
+        await loadRelation(models, relation, constraint);
+    };
+    builder.loadCount = async (models, relation) => {
+        await loadCounts(models, relation, db);
+    };
+}
+function attachWriteMethods(builder, state, db) {
+    const ensureDb = () => {
+        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 ??
+                (items.length === 1 ? (items[0]?.['id'] ?? null) : null),
+            affectedRows: result.rowCount,
+            insertedRecords: items,
+        };
+    };
+    builder.insertIfAbsent = async (values, conflictColumns) => {
+        const currentDb = ensureDb();
+        const tableName = state.tableName.trim();
+        if (tableName.length === 0)
+            throw ErrorFactory.createDatabaseError('INSERT requires a table name');
+        const compiled = compileInsertIfAbsent(tableName, values, conflictColumns, state.dialect);
+        const result = await currentDb.execute(compiled.sql, compiled.parameters, false);
+        const inserted = result.rowCount > 0;
+        return {
+            id: result.lastInsertId ?? (inserted ? values['id'] ?? null : null),
+            affectedRows: result.rowCount,
+            insertedRecords: inserted ? [values] : [],
+            inserted,
+        };
+    };
+    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);
+        const result = await currentDb.execute(compiled.sql, compiled.parameters, false);
+        return result.rowCount;
+    };
+    builder.increment = async (column, amount) => {
+        const currentDb = ensureDb();
+        const tableName = state.tableName.trim();
+        if (tableName.length === 0)
+            throw ErrorFactory.createDatabaseError('UPDATE requires a table name');
+        const compiled = compileIncrement(tableName, column, amount, state.whereConditions, state.dialect);
+        const result = await currentDb.execute(compiled.sql, compiled.parameters, false);
+        return result.rowCount;
+    };
+    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, db) {
+    const builder = {};
+    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, db, options = {}) {
+        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 = {
+            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) {
+        // Use the QueryBuilder itself to avoid embedding raw SQL at call sites.
+        await QueryBuilder.create('', db).select('1').get();
+    },
+});