@relq/orm 0.1.3 → 0.1.5

package/dist/esm/mysql/helpers/select-joins.js

@@ -0,0 +1,455 @@
+import { createMysqlTableProxy, mysqlColumnRefToSQL, mysqlColumnRefToSQLUnqualified } from "../select/table-proxy.js";
+import { MysqlJoinConditionBuilder } from "../select/join-condition-builder.js";
+import { MysqlJoinManyBuilder } from "../select/join-builder.js";
+import { MYSQL_JOIN_INTERNAL } from "../select/join-internals.js";
+import { buildMysqlConditionsSQL } from "../condition/condition-collector.js";
+import { resolveMysqlForeignKey } from "../utils/fk-resolver.js";
+import { INTERNAL } from "../../core/helpers/methods.js";
+import { requireCapability } from "../../core/helpers/capability-guard.js";
+import { RelqBuilderError } from "../../shared/errors/relq-errors.js";
+import mysqlFormat from "../clients/shared/mysql-format.js";
+export function executeMysqlTypeSafeJoin(ctx, joinType, tableOrAlias, callback) {
+    const [rightTableKey, rightAlias] = Array.isArray(tableOrAlias)
+        ? tableOrAlias
+        : [tableOrAlias, tableOrAlias];
+    const internal = ctx.relq[INTERNAL];
+    const schema = internal.getSchema();
+    const leftTableDef = internal.getTableDef(ctx.schemaKey || ctx.tableName);
+    const rightTableDef = internal.getTableDef(rightTableKey);
+    const leftTableName = leftTableDef?.$name || ctx.tableName;
+    const rightTableName = rightTableDef?.$name || rightTableKey;
+    const leftAlias = ctx.builder.getTableIdentifier();
+    const leftProxy = createMysqlTableProxy(leftTableName, leftAlias, leftTableDef);
+    const rightProxy = createMysqlTableProxy(rightTableName, rightAlias, rightTableDef);
+    const conditionBuilder = new MysqlJoinConditionBuilder();
+    if (callback) {
+        if (joinType === 'RIGHT JOIN') {
+            callback(conditionBuilder, leftProxy, rightProxy);
+        }
+        else {
+            callback(conditionBuilder, rightProxy, leftProxy);
+        }
+    }
+    const conditionInternals = conditionBuilder[MYSQL_JOIN_INTERNAL];
+    if (!conditionInternals.hasConditions() && schema) {
+        const fkResolution = resolveMysqlForeignKey(schema, ctx.schemaKey || ctx.tableName, rightTableKey);
+        if (fkResolution) {
+            const leftCol = leftProxy[fkResolution.fromColumn];
+            const rightCol = rightProxy[fkResolution.toColumn];
+            conditionBuilder.equal(leftCol, rightCol);
+        }
+        else {
+            throw new RelqBuilderError(`Cannot auto-resolve FK relationship between "${ctx.schemaKey || ctx.tableName}" and "${rightTableKey}"`, { builder: 'join', hint: `Provide a callback with explicit join conditions, or define $foreignKeys on your table definition. Example: .join('${rightTableKey}', (on, ${rightTableKey}, source) => on.equal(${rightTableKey}.id, source.columnName))` });
+        }
+    }
+    const selectedProps = conditionInternals.getSelectedColumns();
+    let selectColumns;
+    const toSnake = (s) => s.replace(/[A-Z]/g, l => `_${l.toLowerCase()}`);
+    if (selectedProps && selectedProps.length > 0) {
+        const rightColumns = rightTableDef?.$columns || rightTableDef;
+        selectColumns = selectedProps.map(prop => {
+            const columnDef = rightColumns?.[prop];
+            const sqlName = columnDef?.$columnName || toSnake(prop);
+            return { property: prop, sqlName };
+        });
+    }
+    else if (rightTableDef) {
+        const rightColumns = rightTableDef.$columns || rightTableDef;
+        selectColumns = Object.entries(rightColumns)
+            .filter(([_, colDef]) => colDef && typeof colDef === 'object' && '$type' in colDef)
+            .map(([propName, colDef]) => ({
+            property: propName,
+            sqlName: colDef.$columnName || toSnake(propName),
+        }));
+    }
+    const joinClause = {
+        type: joinType,
+        table: rightTableName,
+        alias: rightAlias,
+        schemaKey: rightTableKey,
+        onClause: conditionInternals.toSQL() || undefined,
+        usingColumns: conditionInternals.getUsingColumns() || undefined,
+        selectColumns,
+    };
+    ctx.builder.addStructuredJoin(joinClause);
+}
+export function executeMysqlCorrelatedSubqueryJoin(ctx, tableOrAlias, callback) {
+    const [rightTableKey, rightAlias] = Array.isArray(tableOrAlias)
+        ? tableOrAlias
+        : [tableOrAlias, tableOrAlias];
+    const internal = ctx.relq[INTERNAL];
+    const leftTableDef = internal.getTableDef(ctx.schemaKey || ctx.tableName);
+    const rightTableDef = internal.getTableDef(rightTableKey);
+    const leftTableName = leftTableDef?.$name || ctx.tableName;
+    const rightTableName = rightTableDef?.$name || rightTableKey;
+    const leftAlias = ctx.builder.getTableIdentifier();
+    const leftProxy = createMysqlTableProxy(leftTableName, leftAlias, leftTableDef);
+    const rightProxy = createMysqlTableProxy(rightTableName, rightAlias, rightTableDef);
+    const builder = new MysqlJoinManyBuilder();
+    callback(builder, rightProxy, leftProxy);
+    if (builder.getSelectColumns().length === 0 && rightTableDef) {
+        const rightColumns = rightTableDef.$columns || rightTableDef;
+        const schemaColumns = Object.entries(rightColumns)
+            .filter(([_, colDef]) => colDef && typeof colDef === 'object' && '$type' in colDef)
+            .map(([propName, colDef]) => {
+            const sqlColumn = colDef.$columnName || propName.replace(/[A-Z]/g, (l) => `_${l.toLowerCase()}`);
+            return {
+                $table: rightTableName,
+                $alias: rightAlias,
+                $column: propName,
+                $sqlColumn: sqlColumn,
+                $type: undefined,
+            };
+        });
+        if (schemaColumns.length > 0) {
+            builder.selectRefs(schemaColumns);
+        }
+    }
+    const subquerySQL = builder.toCorrelatedSubquerySQL(rightTableName, rightAlias, leftAlias);
+    ctx.builder.addIncludeExpression(rightAlias, subquerySQL);
+}
+export function executeMysqlJoinManyThrough(ctx, targetTableOrAlias, junctionTableKey, callback) {
+    const [targetKey, targetAlias] = Array.isArray(targetTableOrAlias)
+        ? targetTableOrAlias
+        : [targetTableOrAlias, targetTableOrAlias];
+    const internal = ctx.relq[INTERNAL];
+    const schema = internal.getSchema();
+    if (!schema) {
+        throw new RelqBuilderError('Cannot use { through } without schema', { builder: 'joinMany', hint: 'Define $foreignKeys on your tables to use the { through } pattern, or use the callback form of joinMany instead' });
+    }
+    const junctionTableDef = internal.getTableDef(junctionTableKey);
+    const targetTableDef = internal.getTableDef(targetKey);
+    const junctionTableName = junctionTableDef?.$name || junctionTableKey;
+    const targetTableName = targetTableDef?.$name || targetKey;
+    const leftAlias = ctx.builder.getTableIdentifier();
+    const leftToJunction = resolveMysqlForeignKey(schema, ctx.schemaKey || ctx.tableName, junctionTableKey);
+    if (!leftToJunction) {
+        throw new RelqBuilderError(`Cannot resolve FK between "${ctx.schemaKey || ctx.tableName}" and junction table "${junctionTableKey}"`, { builder: 'joinMany', hint: 'Define $foreignKeys on your table definitions, or use the callback form of joinMany instead' });
+    }
+    const junctionToTarget = resolveMysqlForeignKey(schema, junctionTableKey, targetKey);
+    if (!junctionToTarget) {
+        throw new RelqBuilderError(`Cannot resolve FK between junction table "${junctionTableKey}" and target table "${targetKey}"`, { builder: 'joinMany', hint: 'Define $foreignKeys on your table definitions, or use the callback form of joinMany instead' });
+    }
+    const conditionBuilder = new MysqlJoinManyBuilder();
+    if (callback) {
+        callback(conditionBuilder);
+    }
+    const subquerySQL = buildThroughCorrelatedSubquery(junctionTableName, junctionTableKey, targetTableName, targetAlias, leftAlias, leftToJunction, junctionToTarget, conditionBuilder, targetTableDef);
+    ctx.builder.addIncludeExpression(targetAlias, subquerySQL);
+}
+function buildThroughCorrelatedSubquery(junctionTableName, _junctionAlias, targetTableName, targetAlias, leftAlias, leftToJunction, junctionToTarget, builder, targetTableDef) {
+    const toSnake = (s) => s.replace(/[A-Z]/g, (l) => `_${l.toLowerCase()}`);
+    let columnDefs = [];
+    const userSelectCols = builder.getSelectColumns();
+    if (userSelectCols.length > 0) {
+        columnDefs = userSelectCols.map(col => ({
+            property: col.$column,
+            sqlName: col.$sqlColumn,
+        }));
+    }
+    else if (targetTableDef) {
+        const targetColumns = targetTableDef.$columns || targetTableDef;
+        columnDefs = Object.entries(targetColumns)
+            .filter(([_, colDef]) => colDef && typeof colDef === 'object' && '$type' in colDef)
+            .map(([propName, colDef]) => ({
+            property: propName,
+            sqlName: colDef.$columnName || toSnake(propName),
+        }));
+    }
+    const parts = [];
+    parts.push('SELECT');
+    if (columnDefs.length > 0) {
+        const selectCols = columnDefs.map(col => `${mysqlFormat.ident(targetAlias)}.${mysqlFormat.ident(col.sqlName)} AS ${mysqlFormat.ident(col.property)}`).join(', ');
+        parts.push(selectCols);
+    }
+    else {
+        parts.push(`${mysqlFormat.ident(targetAlias)}.*`);
+    }
+    parts.push(`FROM ${mysqlFormat.ident(junctionTableName)}`);
+    parts.push(`JOIN ${mysqlFormat.ident(targetTableName)} AS ${mysqlFormat.ident(targetAlias)}` +
+        ` ON ${mysqlFormat.ident(junctionTableName)}.${mysqlFormat.ident(junctionToTarget.fromColumn)}` +
+        ` = ${mysqlFormat.ident(targetAlias)}.${mysqlFormat.ident(junctionToTarget.toColumn)}`);
+    let whereClause = `${mysqlFormat.ident(junctionTableName)}.${mysqlFormat.ident(leftToJunction.toColumn)}` +
+        ` = ${mysqlFormat.ident(leftAlias)}.${mysqlFormat.ident(leftToJunction.fromColumn)}`;
+    const conditionInternals = builder[MYSQL_JOIN_INTERNAL];
+    const userWhereSQL = conditionInternals.toSQL();
+    if (userWhereSQL) {
+        whereClause += ` AND ${userWhereSQL}`;
+    }
+    parts.push(`WHERE ${whereClause}`);
+    const orderSpecs = builder.getOrderBySpecs();
+    if (orderSpecs.length > 0) {
+        const orderSQL = orderSpecs.map(spec => `${mysqlFormat.ident(spec.column.$sqlColumn)} ${spec.direction}`).join(', ');
+        parts.push(`ORDER BY ${orderSQL}`);
+    }
+    const limit = builder.getLimit();
+    if (limit !== undefined) {
+        parts.push(`LIMIT ${limit}`);
+    }
+    const offset = builder.getOffset();
+    if (offset !== undefined) {
+        parts.push(`OFFSET ${offset}`);
+    }
+    const innerQuery = parts.join(' ');
+    let jsonObjectParts;
+    if (columnDefs.length > 0) {
+        jsonObjectParts = columnDefs
+            .map(col => `${mysqlFormat.literal(col.property)}, \`sub\`.${mysqlFormat.ident(col.property)}`)
+            .join(', ');
+    }
+    else {
+        jsonObjectParts = "'__all', `sub`.*";
+    }
+    const wrappedQuery = `SELECT COALESCE(JSON_ARRAYAGG(JSON_OBJECT(${jsonObjectParts})), CAST('[]' AS JSON))` +
+        ` AS ${mysqlFormat.ident(targetAlias)} FROM (${innerQuery}) AS \`sub\``;
+    return `(${wrappedQuery})`;
+}
+export function executeMysqlLateralJoin(ctx, joinType, tableOrAlias, callback) {
+    requireCapability(ctx.relq, 'lateral', 'LATERAL JOIN', 'Use the correlated subquery path (.joinMany) which works on all MySQL family dialects.');
+    const [rightTableKey, rightAlias] = Array.isArray(tableOrAlias)
+        ? tableOrAlias
+        : [tableOrAlias, tableOrAlias];
+    const internal = ctx.relq[INTERNAL];
+    const leftTableDef = internal.getTableDef(ctx.schemaKey || ctx.tableName);
+    const rightTableDef = internal.getTableDef(rightTableKey);
+    const leftTableName = leftTableDef?.$name || ctx.tableName;
+    const rightTableName = rightTableDef?.$name || rightTableKey;
+    const leftAlias = ctx.builder.getTableIdentifier();
+    const leftProxy = createMysqlTableProxy(leftTableName, leftAlias, leftTableDef);
+    const rightProxy = createMysqlTableProxy(rightTableName, rightAlias, rightTableDef);
+    const builder = new MysqlJoinManyBuilder();
+    callback(builder, rightProxy, leftProxy);
+    if (builder.getSelectColumns().length === 0 && rightTableDef) {
+        const rightColumns = rightTableDef.$columns || rightTableDef;
+        const schemaColumns = Object.entries(rightColumns)
+            .filter(([_, colDef]) => colDef && typeof colDef === 'object' && '$type' in colDef)
+            .map(([propName, colDef]) => {
+            const sqlColumn = colDef.$columnName || propName.replace(/[A-Z]/g, (l) => `_${l.toLowerCase()}`);
+            return {
+                $table: rightTableName,
+                $alias: rightAlias,
+                $column: propName,
+                $sqlColumn: sqlColumn,
+                $type: undefined,
+            };
+        });
+        if (schemaColumns.length > 0) {
+            builder.selectRefs(schemaColumns);
+        }
+    }
+    const lateralSQL = buildMysqlLateralSubquery(rightTableName, rightAlias, leftAlias, builder, rightTableDef);
+    const lateralJoinType = joinType === 'LEFT JOIN' ? 'LEFT JOIN LATERAL' : 'JOIN LATERAL';
+    const joinClause = {
+        type: lateralJoinType,
+        table: rightTableName,
+        alias: rightAlias,
+        schemaKey: rightTableKey,
+        lateralSubquery: lateralSQL,
+    };
+    ctx.builder.addStructuredJoin(joinClause);
+}
+function buildMysqlLateralSubquery(tableName, alias, _leftAlias, builder, tableDef) {
+    const toSnake = (s) => s.replace(/[A-Z]/g, (l) => `_${l.toLowerCase()}`);
+    let columnDefs = [];
+    const userSelectCols = builder.getSelectColumns();
+    if (userSelectCols.length > 0) {
+        columnDefs = userSelectCols.map(col => ({
+            property: col.$column,
+            sqlName: col.$sqlColumn,
+        }));
+    }
+    else if (tableDef) {
+        const tableColumns = tableDef.$columns || tableDef;
+        columnDefs = Object.entries(tableColumns)
+            .filter(([_, colDef]) => colDef && typeof colDef === 'object' && '$type' in colDef)
+            .map(([propName, colDef]) => ({
+            property: propName,
+            sqlName: colDef.$columnName || toSnake(propName),
+        }));
+    }
+    const parts = [];
+    parts.push('SELECT');
+    if (columnDefs.length > 0) {
+        const selectCols = columnDefs.map(col => `${mysqlFormat.ident(alias)}.${mysqlFormat.ident(col.sqlName)} AS ${mysqlFormat.ident(col.property)}`).join(', ');
+        parts.push(selectCols);
+    }
+    else {
+        parts.push(`${mysqlFormat.ident(alias)}.*`);
+    }
+    parts.push(`FROM ${mysqlFormat.ident(tableName)} AS ${mysqlFormat.ident(alias)}`);
+    const whereParts = [];
+    for (const cond of builder.conditions || []) {
+        if (cond.type === 'using' || cond.type === 'raw') {
+            if (cond.raw)
+                whereParts.push(cond.raw);
+            continue;
+        }
+        if (cond.type === 'ilike') {
+            const leftSQL = mysqlColumnRefToSQL(cond.left);
+            const rightSQL = formatJoinRightSide(cond.right);
+            whereParts.push(`LOWER(${leftSQL}) LIKE LOWER(${rightSQL})`);
+            continue;
+        }
+        const leftSQL = mysqlColumnRefToSQL(cond.left);
+        const rightSQL = formatJoinRightSide(cond.right);
+        whereParts.push(`${leftSQL} ${cond.operator} ${rightSQL}`);
+    }
+    if (whereParts.length > 0) {
+        parts.push(`WHERE ${whereParts.join(' AND ')}`);
+    }
+    const groupByColumns = builder.groupByColumns;
+    if (groupByColumns && groupByColumns.length > 0) {
+        const groupBySQL = groupByColumns
+            .map((col) => mysqlColumnRefToSQLUnqualified(col))
+            .join(', ');
+        parts.push(`GROUP BY ${groupBySQL}`);
+    }
+    const havingConditions = builder.havingConditions;
+    if (havingConditions && havingConditions.length > 0) {
+        const havingSQL = buildMysqlConditionsSQL(havingConditions);
+        if (havingSQL) {
+            parts.push(`HAVING ${havingSQL}`);
+        }
+    }
+    const orderSpecs = builder.getOrderBySpecs();
+    if (orderSpecs.length > 0) {
+        const orderSQL = orderSpecs.map(spec => `${mysqlColumnRefToSQLUnqualified(spec.column)} ${spec.direction}`).join(', ');
+        parts.push(`ORDER BY ${orderSQL}`);
+    }
+    const limit = builder.getLimit();
+    if (limit !== undefined) {
+        parts.push(`LIMIT ${limit}`);
+    }
+    const offset = builder.getOffset();
+    if (offset !== undefined) {
+        parts.push(`OFFSET ${offset}`);
+    }
+    const innerQuery = parts.join(' ');
+    let jsonObjectParts;
+    if (columnDefs.length > 0) {
+        jsonObjectParts = columnDefs
+            .map(col => `${mysqlFormat.literal(col.property)}, \`sub\`.${mysqlFormat.ident(col.property)}`)
+            .join(', ');
+    }
+    else {
+        jsonObjectParts = "'__all', `sub`.*";
+    }
+    const outerQuery = `(SELECT COALESCE(JSON_ARRAYAGG(JSON_OBJECT(${jsonObjectParts})), CAST('[]' AS JSON))` +
+        ` AS ${mysqlFormat.ident(alias)}` +
+        ` FROM (${innerQuery}) AS \`sub\`)` +
+        ` AS ${mysqlFormat.ident(`${alias}_lateral`)}`;
+    return outerQuery;
+}
+function formatJoinRightSide(right) {
+    if (right && typeof right === 'object' && '$table' in right) {
+        return mysqlColumnRefToSQL(right);
+    }
+    return mysqlFormat.literal(right);
+}
+export function executeMysqlLateralJoinThrough(ctx, joinType, targetTableOrAlias, junctionTableKey, callback) {
+    requireCapability(ctx.relq, 'lateral', 'LATERAL JOIN', 'Use the correlated subquery path (.joinMany with { through }) which works on all MySQL family dialects.');
+    const [targetKey, targetAlias] = Array.isArray(targetTableOrAlias)
+        ? targetTableOrAlias
+        : [targetTableOrAlias, targetTableOrAlias];
+    const internal = ctx.relq[INTERNAL];
+    const schema = internal.getSchema();
+    if (!schema) {
+        throw new RelqBuilderError('Cannot use { through } without schema', { builder: 'joinManyLateral', hint: 'Define $foreignKeys on your tables to use the { through } pattern, or use the callback form of joinMany instead' });
+    }
+    const junctionTableDef = internal.getTableDef(junctionTableKey);
+    const targetTableDef = internal.getTableDef(targetKey);
+    const junctionTableName = junctionTableDef?.$name || junctionTableKey;
+    const targetTableName = targetTableDef?.$name || targetKey;
+    const leftAlias = ctx.builder.getTableIdentifier();
+    const leftToJunction = resolveMysqlForeignKey(schema, ctx.schemaKey || ctx.tableName, junctionTableKey);
+    if (!leftToJunction) {
+        throw new RelqBuilderError(`Cannot resolve FK between "${ctx.schemaKey || ctx.tableName}" and junction table "${junctionTableKey}"`, { builder: 'joinManyLateral', hint: 'Define $foreignKeys on your table definitions, or use the callback form of joinMany instead' });
+    }
+    const junctionToTarget = resolveMysqlForeignKey(schema, junctionTableKey, targetKey);
+    if (!junctionToTarget) {
+        throw new RelqBuilderError(`Cannot resolve FK between junction table "${junctionTableKey}" and target table "${targetKey}"`, { builder: 'joinManyLateral', hint: 'Define $foreignKeys on your table definitions, or use the callback form of joinMany instead' });
+    }
+    const conditionBuilder = new MysqlJoinManyBuilder();
+    if (callback) {
+        callback(conditionBuilder);
+    }
+    const lateralSQL = buildMysqlThroughLateralSubquery(junctionTableName, junctionTableKey, targetTableName, targetAlias, leftAlias, leftToJunction, junctionToTarget, conditionBuilder, targetTableDef);
+    const lateralJoinType = joinType === 'LEFT JOIN' ? 'LEFT JOIN LATERAL' : 'JOIN LATERAL';
+    const joinClause = {
+        type: lateralJoinType,
+        table: targetTableName,
+        alias: targetAlias,
+        schemaKey: targetKey,
+        lateralSubquery: lateralSQL,
+    };
+    ctx.builder.addStructuredJoin(joinClause);
+}
+function buildMysqlThroughLateralSubquery(junctionTableName, _junctionAlias, targetTableName, targetAlias, leftAlias, leftToJunction, junctionToTarget, builder, targetTableDef) {
+    const toSnake = (s) => s.replace(/[A-Z]/g, (l) => `_${l.toLowerCase()}`);
+    let columnDefs = [];
+    const userSelectCols = builder.getSelectColumns();
+    if (userSelectCols.length > 0) {
+        columnDefs = userSelectCols.map(col => ({
+            property: col.$column,
+            sqlName: col.$sqlColumn,
+        }));
+    }
+    else if (targetTableDef) {
+        const targetColumns = targetTableDef.$columns || targetTableDef;
+        columnDefs = Object.entries(targetColumns)
+            .filter(([_, colDef]) => colDef && typeof colDef === 'object' && '$type' in colDef)
+            .map(([propName, colDef]) => ({
+            property: propName,
+            sqlName: colDef.$columnName || toSnake(propName),
+        }));
+    }
+    const parts = [];
+    parts.push('SELECT');
+    if (columnDefs.length > 0) {
+        const selectCols = columnDefs.map(col => `${mysqlFormat.ident(targetAlias)}.${mysqlFormat.ident(col.sqlName)} AS ${mysqlFormat.ident(col.property)}`).join(', ');
+        parts.push(selectCols);
+    }
+    else {
+        parts.push(`${mysqlFormat.ident(targetAlias)}.*`);
+    }
+    parts.push(`FROM ${mysqlFormat.ident(junctionTableName)}`);
+    parts.push(`JOIN ${mysqlFormat.ident(targetTableName)} AS ${mysqlFormat.ident(targetAlias)}` +
+        ` ON ${mysqlFormat.ident(junctionTableName)}.${mysqlFormat.ident(junctionToTarget.fromColumn)}` +
+        ` = ${mysqlFormat.ident(targetAlias)}.${mysqlFormat.ident(junctionToTarget.toColumn)}`);
+    let whereClause = `${mysqlFormat.ident(junctionTableName)}.${mysqlFormat.ident(leftToJunction.toColumn)}` +
+        ` = ${mysqlFormat.ident(leftAlias)}.${mysqlFormat.ident(leftToJunction.fromColumn)}`;
+    const conditionInternals = builder[MYSQL_JOIN_INTERNAL];
+    const userWhereSQL = conditionInternals.toSQL();
+    if (userWhereSQL) {
+        whereClause += ` AND ${userWhereSQL}`;
+    }
+    parts.push(`WHERE ${whereClause}`);
+    const orderSpecs = builder.getOrderBySpecs();
+    if (orderSpecs.length > 0) {
+        const orderSQL = orderSpecs.map(spec => `${mysqlFormat.ident(spec.column.$sqlColumn)} ${spec.direction}`).join(', ');
+        parts.push(`ORDER BY ${orderSQL}`);
+    }
+    const limit = builder.getLimit();
+    if (limit !== undefined) {
+        parts.push(`LIMIT ${limit}`);
+    }
+    const offset = builder.getOffset();
+    if (offset !== undefined) {
+        parts.push(`OFFSET ${offset}`);
+    }
+    const innerQuery = parts.join(' ');
+    let jsonObjectParts;
+    if (columnDefs.length > 0) {
+        jsonObjectParts = columnDefs
+            .map(col => `${mysqlFormat.literal(col.property)}, \`sub\`.${mysqlFormat.ident(col.property)}`)
+            .join(', ');
+    }
+    else {
+        jsonObjectParts = "'__all', `sub`.*";
+    }
+    const outerQuery = `(SELECT COALESCE(JSON_ARRAYAGG(JSON_OBJECT(${jsonObjectParts})), CAST('[]' AS JSON))` +
+        ` AS ${mysqlFormat.ident(targetAlias)}` +
+        ` FROM (${innerQuery}) AS \`sub\`)` +
+        ` AS ${mysqlFormat.ident(`${targetAlias}_lateral`)}`;
+    return outerQuery;
+}

package/dist/esm/mysql/helpers/select-pagination.js

@@ -0,0 +1,186 @@
+import { randomLimit, } from "../../types/pagination-types.js";
+import { INTERNAL } from "../../core/helpers/methods.js";
+import { RelqBuilderError } from "../../shared/errors/relq-errors.js";
+export async function executeMysqlCursorEach(ctx, callback, options = {}) {
+    const batchSize = options.batchSize ?? 100;
+    const baseSql = ctx.builder.toString();
+    const cleanSql = baseSql
+        .replace(/\s+LIMIT\s+\d+/gi, '')
+        .replace(/\s+OFFSET\s+\d+/gi, '');
+    let offset = 0;
+    let index = 0;
+    let shouldContinue = true;
+    while (shouldContinue) {
+        const batchSql = `${cleanSql} LIMIT ${batchSize} OFFSET ${offset}`;
+        const result = await ctx.relq[INTERNAL].executeSelect(batchSql, ctx.tableName);
+        if (result.data.length === 0) {
+            break;
+        }
+        for (const row of result.data) {
+            const callbackResult = await callback(row, index++);
+            if (callbackResult === false) {
+                shouldContinue = false;
+                break;
+            }
+        }
+        if (result.data.length < batchSize) {
+            break;
+        }
+        offset += batchSize;
+    }
+}
+export async function executeMysqlPagination(ctx, options, recurse) {
+    if (!options.mode || !['paging', 'offset'].includes(options.mode)) {
+        throw new RelqBuilderError('pagination() requires "mode" to be one of: \'paging\', \'offset\'', { builder: 'paginate', hint: 'Use .paging({ page, perPage }) for page-based or .offset({ position, limit }) for offset-based pagination' });
+    }
+    const orderByArr = options.orderBy
+        ? (Array.isArray(options.orderBy[0]) ? options.orderBy : [options.orderBy])
+        : [];
+    for (const [column, direction] of orderByArr) {
+        const dbColumn = ctx.relq[INTERNAL].hasColumnMapping()
+            ? Object.keys(ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, { [column]: true }))[0]
+            : column;
+        ctx.builder.orderBy(dbColumn, direction);
+    }
+    const isPaging = options.mode === 'paging';
+    const shouldCount = options.count ?? isPaging;
+    let total = 0;
+    if (shouldCount) {
+        const countSql = ctx.builder.toCountSQL();
+        const countResult = await ctx.relq[INTERNAL].executeCount(countSql);
+        total = countResult.count;
+    }
+    if (isPaging) {
+        return executePagingMode(ctx, options, total, recurse);
+    }
+    if (options.mode === 'offset') {
+        return executeOffsetMode(ctx, options, total, shouldCount, recurse);
+    }
+    throw new RelqBuilderError('Invalid pagination mode', { builder: 'paginate', hint: 'Use .paging({ page, perPage }) or .offset({ position, limit })' });
+}
+async function executePagingMode(ctx, options, total, recurse) {
+    const { page, perPage } = options;
+    if (typeof page !== 'number' || isNaN(page) || page < 1) {
+        throw new RelqBuilderError('pagination() paging mode requires "page" as a positive number (1-indexed)', { builder: 'paginate', hint: 'Page numbers are 1-indexed, starting from 1' });
+    }
+    if (typeof perPage !== 'number' || isNaN(perPage) || perPage < 1) {
+        throw new RelqBuilderError('pagination() paging mode requires "perPage" as a positive number', { builder: 'paginate', hint: 'Set perPage to the number of items you want per page (e.g. 20)' });
+    }
+    const offset = (page - 1) * perPage;
+    ctx.builder.limit(perPage);
+    ctx.builder.offset(offset);
+    const sql = ctx.builder.toString();
+    const result = await ctx.relq[INTERNAL].executeSelect(sql, ctx.tableName);
+    const totalPages = Math.ceil(total / perPage);
+    const hasNext = page < totalPages;
+    const hasPrev = page > 1;
+    const pagination = {
+        page,
+        perPage,
+        total,
+        totalPages,
+    };
+    if (hasNext) {
+        pagination.hasNext = true;
+        pagination.nextPage = page + 1;
+        Object.defineProperty(pagination, 'loadNext', {
+            value: () => recurse({ ...options, page: page + 1 }),
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    else {
+        pagination.hasNext = false;
+    }
+    if (hasPrev) {
+        pagination.hasPrev = true;
+        pagination.prevPage = page - 1;
+        Object.defineProperty(pagination, 'loadPrev', {
+            value: () => recurse({ ...options, page: page - 1 }),
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    else {
+        pagination.hasPrev = false;
+    }
+    addInspectProperties(pagination, () => {
+        const visible = { page, perPage, total, totalPages, hasNext };
+        if (hasNext)
+            visible.nextPage = page + 1;
+        visible.hasPrev = hasPrev;
+        if (hasPrev)
+            visible.prevPage = page - 1;
+        return visible;
+    });
+    return { data: result.data, pagination };
+}
+async function executeOffsetMode(ctx, options, total, shouldCount, recurse) {
+    const { position, limit: limitOpt } = options;
+    if (typeof position !== 'number' || isNaN(position)) {
+        throw new RelqBuilderError('pagination() offset mode requires "position" as a number', { builder: 'paginate', hint: 'Set position to the starting row offset (0-indexed)' });
+    }
+    if (limitOpt === undefined || (typeof limitOpt !== 'number' && !Array.isArray(limitOpt))) {
+        throw new RelqBuilderError('pagination() offset mode requires "limit" as a number or [min, max] array', { builder: 'paginate', hint: 'Pass limit as a number (e.g. 50) or a [min, max] tuple for random limit' });
+    }
+    const limit = Array.isArray(limitOpt) ? randomLimit(limitOpt) : limitOpt;
+    ctx.builder.limit(limit + 1);
+    ctx.builder.offset(position);
+    const sql = ctx.builder.toString();
+    const result = await ctx.relq[INTERNAL].executeSelect(sql, ctx.tableName);
+    const hasMore = result.data.length > limit;
+    const hasPrev = position > 0;
+    const data = hasMore ? result.data.slice(0, limit) : result.data;
+    const pagination = {
+        position,
+        limit,
+        ...(shouldCount && { total }),
+    };
+    if (hasMore) {
+        pagination.hasMore = true;
+        pagination.nextPos = position + limit;
+        Object.defineProperty(pagination, 'loadNext', {
+            value: () => recurse({ ...options, position: position + limit }),
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    else {
+        pagination.hasMore = false;
+    }
+    if (hasPrev) {
+        pagination.hasPrev = true;
+        pagination.prevPos = Math.max(0, position - limit);
+        Object.defineProperty(pagination, 'loadPrev', {
+            value: () => recurse({ ...options, position: Math.max(0, position - limit) }),
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    else {
+        pagination.hasPrev = false;
+    }
+    addInspectProperties(pagination, () => {
+        const visible = { position, limit };
+        if (shouldCount)
+            visible.total = total;
+        visible.hasMore = hasMore;
+        if (hasMore)
+            visible.nextPos = position + limit;
+        visible.hasPrev = hasPrev;
+        if (hasPrev)
+            visible.prevPos = Math.max(0, position - limit);
+        return visible;
+    });
+    return { data, pagination };
+}
+function addInspectProperties(obj, getVisibleProps) {
+    Object.defineProperty(obj, Symbol.for('nodejs.util.inspect.custom'), {
+        value: () => getVisibleProps(),
+        enumerable: false,
+    });
+    Object.defineProperty(obj, 'toJSON', {
+        value: () => getVisibleProps(),
+        enumerable: false,
+    });
+}