@relq/orm 0.1.3 → 0.1.5

package/dist/cjs/mysql/helpers/query-convenience.cjs

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeMysqlFindById = executeMysqlFindById;
+exports.executeMysqlFindOne = executeMysqlFindOne;
+exports.executeMysqlFindMany = executeMysqlFindMany;
+exports.executeMysqlExists = executeMysqlExists;
+exports.executeMysqlUpsert = executeMysqlUpsert;
+exports.executeMysqlSoftDelete = executeMysqlSoftDelete;
+exports.executeMysqlRestore = executeMysqlRestore;
+exports.executeMysqlCreateWith = executeMysqlCreateWith;
+exports.getMysqlPrimaryKeyColumn = getMysqlPrimaryKeyColumn;
+const count_builder_1 = require("../count/count-builder.cjs");
+const insert_builder_1 = require("../insert/insert-builder.cjs");
+const select_builder_1 = require("../select/select-builder.cjs");
+const update_builder_1 = require("../update/update-builder.cjs");
+const fk_resolver_1 = require("../utils/fk-resolver.cjs");
+const methods_1 = require("../../core/helpers/methods.cjs");
+const relq_errors_1 = require("../../shared/errors/relq-errors.cjs");
+async function executeMysqlFindById(ctx, id, getPrimaryKeyColumn) {
+    const pkColumn = getPrimaryKeyColumn();
+    const dbColumn = ctx.relq[methods_1.INTERNAL].transformToDbColumns(ctx.tableName, { [pkColumn]: id });
+    const dbColName = Object.keys(dbColumn)[0];
+    const builder = new select_builder_1.MysqlSelectBuilder(ctx.tableName, ['*']);
+    builder.where(q => q.equal(dbColName, id));
+    builder.limit(1);
+    const sql = builder.toString();
+    const result = await ctx.relq[methods_1.INTERNAL].executeSelectOne(sql, ctx.tableName);
+    return result.data;
+}
+async function executeMysqlFindOne(ctx, filter) {
+    const builder = new select_builder_1.MysqlSelectBuilder(ctx.tableName, ['*']);
+    const dbFilter = ctx.relq[methods_1.INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    builder.limit(1);
+    const sql = builder.toString();
+    const result = await ctx.relq[methods_1.INTERNAL].executeSelectOne(sql, ctx.tableName);
+    return result.data;
+}
+async function executeMysqlFindMany(ctx, filter) {
+    const builder = new select_builder_1.MysqlSelectBuilder(ctx.tableName, ['*']);
+    const dbFilter = ctx.relq[methods_1.INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[methods_1.INTERNAL].executeSelect(sql, ctx.tableName);
+    return result.data;
+}
+async function executeMysqlExists(ctx, filter) {
+    const builder = new count_builder_1.MysqlCountBuilder(ctx.tableName);
+    const dbFilter = ctx.relq[methods_1.INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[methods_1.INTERNAL].executeCount(sql);
+    return result.count > 0;
+}
+async function executeMysqlUpsert(ctx, options) {
+    const internal = ctx.relq[methods_1.INTERNAL];
+    const dbCreate = internal.transformToDbColumns(ctx.tableName, options.create);
+    const dbUpdate = internal.transformToDbColumns(ctx.tableName, options.update);
+    const dbWhere = internal.transformToDbColumns(ctx.tableName, options.where);
+    const builder = new insert_builder_1.MysqlInsertBuilder(ctx.tableName, dbCreate);
+    builder.onDuplicateKeyUpdate(dup => {
+        dup.doUpdate(dbUpdate);
+    });
+    const sql = builder.toString();
+    await internal.executeRun(sql);
+    const selectBuilder = new select_builder_1.MysqlSelectBuilder(ctx.tableName, ['*']);
+    selectBuilder.where(q => {
+        for (const [col, val] of Object.entries(dbWhere)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    selectBuilder.limit(1);
+    const selectResult = await internal.executeSelectOne(selectBuilder.toString(), ctx.tableName);
+    return selectResult.data;
+}
+async function executeMysqlSoftDelete(ctx, filter) {
+    const dbFilter = ctx.relq[methods_1.INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    const builder = new update_builder_1.MysqlUpdateBuilder(ctx.tableName);
+    builder.set({ deleted_at: new Date() });
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[methods_1.INTERNAL].executeRun(sql);
+    return result.metadata.rowCount ?? 0;
+}
+async function executeMysqlRestore(ctx, filter) {
+    const dbFilter = ctx.relq[methods_1.INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    const builder = new update_builder_1.MysqlUpdateBuilder(ctx.tableName);
+    builder.set({ deleted_at: null });
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[methods_1.INTERNAL].executeRun(sql);
+    return result.metadata.rowCount ?? 0;
+}
+async function executeMysqlCreateWith(ctx, parentData, related) {
+    const internal = ctx.relq[methods_1.INTERNAL];
+    const schema = internal.getSchema();
+    if (!schema) {
+        throw new relq_errors_1.RelqBuilderError('Cannot use createWith() without schema', { builder: 'createWith', hint: 'Pass schema to your Relq client, or use separate insert calls with a transaction instead' });
+    }
+    const parentSchemaKey = findSchemaKeyByTableName(schema, ctx.tableName) || ctx.tableName;
+    try {
+        await internal.executeRun('START TRANSACTION');
+        const dbParent = internal.transformToDbColumns(ctx.tableName, parentData);
+        const parentBuilder = new insert_builder_1.MysqlInsertBuilder(ctx.tableName, dbParent);
+        const parentSQL = parentBuilder.toString();
+        await internal.executeRun(parentSQL);
+        const pkColumn = getMysqlPrimaryKeyColumn(ctx.relq, parentSchemaKey);
+        const dbPkColumn = Object.keys(internal.transformToDbColumns(ctx.tableName, { [pkColumn]: true }))[0] || pkColumn;
+        const selectParentSQL = `SELECT * FROM \`${ctx.tableName}\` WHERE \`${dbPkColumn}\` = LAST_INSERT_ID() LIMIT 1`;
+        const parentResult = await internal.executeQuery(selectParentSQL);
+        if (!parentResult.result.rows || parentResult.result.rows.length === 0) {
+            throw new relq_errors_1.RelqBuilderError('Parent insert returned no rows via LAST_INSERT_ID()', { builder: 'createWith', hint: 'Ensure the table has an AUTO_INCREMENT primary key and the insert data is valid' });
+        }
+        const parentRow = parentResult.result.rows[0];
+        for (const [relationKey, childData] of Object.entries(related)) {
+            const childTableDef = schema[relationKey];
+            if (!childTableDef) {
+                throw new relq_errors_1.RelqBuilderError(`Unknown table "${relationKey}" in createWith()`, { builder: 'createWith', hint: 'Verify the relation key matches a table name defined in your schema' });
+            }
+            const childTableName = childTableDef.$name || relationKey;
+            const fk = (0, fk_resolver_1.resolveMysqlForeignKey)(schema, parentSchemaKey, relationKey);
+            if (!fk) {
+                throw new relq_errors_1.RelqBuilderError(`No FK relationship between "${parentSchemaKey}" and "${relationKey}"`, { builder: 'createWith', hint: 'Define $foreignKeys on your table definitions, or use separate insert calls with explicit FK values' });
+            }
+            let fkColumn;
+            let fkValue;
+            if (fk.direction === 'reverse') {
+                fkColumn = fk.toColumn;
+                fkValue = parentRow[fk.fromColumn];
+            }
+            else {
+                fkColumn = fk.fromColumn;
+                fkValue = parentRow[fk.toColumn];
+            }
+            const rows = Array.isArray(childData) ? childData : [childData];
+            if (rows.length === 0)
+                continue;
+            const firstChildRow = { ...rows[0], [fkColumn]: fkValue };
+            const dbFirstChild = internal.transformToDbColumns(childTableName, firstChildRow);
+            const childBuilder = new insert_builder_1.MysqlInsertBuilder(childTableName, dbFirstChild);
+            for (let i = 1; i < rows.length; i++) {
+                const childRow = { ...rows[i], [fkColumn]: fkValue };
+                const dbChild = internal.transformToDbColumns(childTableName, childRow);
+                childBuilder.addRow(dbChild);
+            }
+            const childSQL = childBuilder.toString();
+            await internal.executeRun(childSQL);
+        }
+        await internal.executeRun('COMMIT');
+        const transformed = internal.transformResultsFromDb(ctx.tableName, [parentRow]);
+        return transformed[0];
+    }
+    catch (error) {
+        try {
+            await internal.executeRun('ROLLBACK');
+        }
+        catch {
+        }
+        throw error;
+    }
+}
+function findSchemaKeyByTableName(schema, tableName) {
+    for (const [key, def] of Object.entries(schema)) {
+        if (def?.$name === tableName || key === tableName) {
+            return key;
+        }
+    }
+    return null;
+}
+function getMysqlPrimaryKeyColumn(relq, tableName) {
+    const schema = relq.schema;
+    if (schema && schema[tableName]) {
+        const tableSchema = schema[tableName];
+        const columns = tableSchema.$columns || tableSchema;
+        for (const [colName, colDef] of Object.entries(columns)) {
+            if (colDef && typeof colDef === 'object' &&
+                ('$primaryKey' in colDef ||
+                    colDef.config?.$primaryKey === true)) {
+                return colName;
+            }
+        }
+    }
+    return 'id';
+}

package/dist/cjs/mysql/helpers/select-joins.cjs

@@ -0,0 +1,465 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeMysqlTypeSafeJoin = executeMysqlTypeSafeJoin;
+exports.executeMysqlCorrelatedSubqueryJoin = executeMysqlCorrelatedSubqueryJoin;
+exports.executeMysqlJoinManyThrough = executeMysqlJoinManyThrough;
+exports.executeMysqlLateralJoin = executeMysqlLateralJoin;
+exports.executeMysqlLateralJoinThrough = executeMysqlLateralJoinThrough;
+const table_proxy_1 = require("../select/table-proxy.cjs");
+const join_condition_builder_1 = require("../select/join-condition-builder.cjs");
+const join_builder_1 = require("../select/join-builder.cjs");
+const join_internals_1 = require("../select/join-internals.cjs");
+const condition_collector_1 = require("../condition/condition-collector.cjs");
+const fk_resolver_1 = require("../utils/fk-resolver.cjs");
+const methods_1 = require("../../core/helpers/methods.cjs");
+const capability_guard_1 = require("../../core/helpers/capability-guard.cjs");
+const relq_errors_1 = require("../../shared/errors/relq-errors.cjs");
+const mysql_format_1 = __importDefault(require("../clients/shared/mysql-format.cjs"));
+function executeMysqlTypeSafeJoin(ctx, joinType, tableOrAlias, callback) {
+    const [rightTableKey, rightAlias] = Array.isArray(tableOrAlias)
+        ? tableOrAlias
+        : [tableOrAlias, tableOrAlias];
+    const internal = ctx.relq[methods_1.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 = (0, table_proxy_1.createMysqlTableProxy)(leftTableName, leftAlias, leftTableDef);
+    const rightProxy = (0, table_proxy_1.createMysqlTableProxy)(rightTableName, rightAlias, rightTableDef);
+    const conditionBuilder = new join_condition_builder_1.MysqlJoinConditionBuilder();
+    if (callback) {
+        if (joinType === 'RIGHT JOIN') {
+            callback(conditionBuilder, leftProxy, rightProxy);
+        }
+        else {
+            callback(conditionBuilder, rightProxy, leftProxy);
+        }
+    }
+    const conditionInternals = conditionBuilder[join_internals_1.MYSQL_JOIN_INTERNAL];
+    if (!conditionInternals.hasConditions() && schema) {
+        const fkResolution = (0, fk_resolver_1.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 relq_errors_1.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);
+}
+function executeMysqlCorrelatedSubqueryJoin(ctx, tableOrAlias, callback) {
+    const [rightTableKey, rightAlias] = Array.isArray(tableOrAlias)
+        ? tableOrAlias
+        : [tableOrAlias, tableOrAlias];
+    const internal = ctx.relq[methods_1.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 = (0, table_proxy_1.createMysqlTableProxy)(leftTableName, leftAlias, leftTableDef);
+    const rightProxy = (0, table_proxy_1.createMysqlTableProxy)(rightTableName, rightAlias, rightTableDef);
+    const builder = new join_builder_1.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);
+}
+function executeMysqlJoinManyThrough(ctx, targetTableOrAlias, junctionTableKey, callback) {
+    const [targetKey, targetAlias] = Array.isArray(targetTableOrAlias)
+        ? targetTableOrAlias
+        : [targetTableOrAlias, targetTableOrAlias];
+    const internal = ctx.relq[methods_1.INTERNAL];
+    const schema = internal.getSchema();
+    if (!schema) {
+        throw new relq_errors_1.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 = (0, fk_resolver_1.resolveMysqlForeignKey)(schema, ctx.schemaKey || ctx.tableName, junctionTableKey);
+    if (!leftToJunction) {
+        throw new relq_errors_1.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 = (0, fk_resolver_1.resolveMysqlForeignKey)(schema, junctionTableKey, targetKey);
+    if (!junctionToTarget) {
+        throw new relq_errors_1.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 join_builder_1.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 => `${mysql_format_1.default.ident(targetAlias)}.${mysql_format_1.default.ident(col.sqlName)} AS ${mysql_format_1.default.ident(col.property)}`).join(', ');
+        parts.push(selectCols);
+    }
+    else {
+        parts.push(`${mysql_format_1.default.ident(targetAlias)}.*`);
+    }
+    parts.push(`FROM ${mysql_format_1.default.ident(junctionTableName)}`);
+    parts.push(`JOIN ${mysql_format_1.default.ident(targetTableName)} AS ${mysql_format_1.default.ident(targetAlias)}` +
+        ` ON ${mysql_format_1.default.ident(junctionTableName)}.${mysql_format_1.default.ident(junctionToTarget.fromColumn)}` +
+        ` = ${mysql_format_1.default.ident(targetAlias)}.${mysql_format_1.default.ident(junctionToTarget.toColumn)}`);
+    let whereClause = `${mysql_format_1.default.ident(junctionTableName)}.${mysql_format_1.default.ident(leftToJunction.toColumn)}` +
+        ` = ${mysql_format_1.default.ident(leftAlias)}.${mysql_format_1.default.ident(leftToJunction.fromColumn)}`;
+    const conditionInternals = builder[join_internals_1.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 => `${mysql_format_1.default.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 => `${mysql_format_1.default.literal(col.property)}, \`sub\`.${mysql_format_1.default.ident(col.property)}`)
+            .join(', ');
+    }
+    else {
+        jsonObjectParts = "'__all', `sub`.*";
+    }
+    const wrappedQuery = `SELECT COALESCE(JSON_ARRAYAGG(JSON_OBJECT(${jsonObjectParts})), CAST('[]' AS JSON))` +
+        ` AS ${mysql_format_1.default.ident(targetAlias)} FROM (${innerQuery}) AS \`sub\``;
+    return `(${wrappedQuery})`;
+}
+function executeMysqlLateralJoin(ctx, joinType, tableOrAlias, callback) {
+    (0, capability_guard_1.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[methods_1.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 = (0, table_proxy_1.createMysqlTableProxy)(leftTableName, leftAlias, leftTableDef);
+    const rightProxy = (0, table_proxy_1.createMysqlTableProxy)(rightTableName, rightAlias, rightTableDef);
+    const builder = new join_builder_1.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 => `${mysql_format_1.default.ident(alias)}.${mysql_format_1.default.ident(col.sqlName)} AS ${mysql_format_1.default.ident(col.property)}`).join(', ');
+        parts.push(selectCols);
+    }
+    else {
+        parts.push(`${mysql_format_1.default.ident(alias)}.*`);
+    }
+    parts.push(`FROM ${mysql_format_1.default.ident(tableName)} AS ${mysql_format_1.default.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 = (0, table_proxy_1.mysqlColumnRefToSQL)(cond.left);
+            const rightSQL = formatJoinRightSide(cond.right);
+            whereParts.push(`LOWER(${leftSQL}) LIKE LOWER(${rightSQL})`);
+            continue;
+        }
+        const leftSQL = (0, table_proxy_1.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) => (0, table_proxy_1.mysqlColumnRefToSQLUnqualified)(col))
+            .join(', ');
+        parts.push(`GROUP BY ${groupBySQL}`);
+    }
+    const havingConditions = builder.havingConditions;
+    if (havingConditions && havingConditions.length > 0) {
+        const havingSQL = (0, condition_collector_1.buildMysqlConditionsSQL)(havingConditions);
+        if (havingSQL) {
+            parts.push(`HAVING ${havingSQL}`);
+        }
+    }
+    const orderSpecs = builder.getOrderBySpecs();
+    if (orderSpecs.length > 0) {
+        const orderSQL = orderSpecs.map(spec => `${(0, table_proxy_1.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 => `${mysql_format_1.default.literal(col.property)}, \`sub\`.${mysql_format_1.default.ident(col.property)}`)
+            .join(', ');
+    }
+    else {
+        jsonObjectParts = "'__all', `sub`.*";
+    }
+    const outerQuery = `(SELECT COALESCE(JSON_ARRAYAGG(JSON_OBJECT(${jsonObjectParts})), CAST('[]' AS JSON))` +
+        ` AS ${mysql_format_1.default.ident(alias)}` +
+        ` FROM (${innerQuery}) AS \`sub\`)` +
+        ` AS ${mysql_format_1.default.ident(`${alias}_lateral`)}`;
+    return outerQuery;
+}
+function formatJoinRightSide(right) {
+    if (right && typeof right === 'object' && '$table' in right) {
+        return (0, table_proxy_1.mysqlColumnRefToSQL)(right);
+    }
+    return mysql_format_1.default.literal(right);
+}
+function executeMysqlLateralJoinThrough(ctx, joinType, targetTableOrAlias, junctionTableKey, callback) {
+    (0, capability_guard_1.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[methods_1.INTERNAL];
+    const schema = internal.getSchema();
+    if (!schema) {
+        throw new relq_errors_1.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 = (0, fk_resolver_1.resolveMysqlForeignKey)(schema, ctx.schemaKey || ctx.tableName, junctionTableKey);
+    if (!leftToJunction) {
+        throw new relq_errors_1.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 = (0, fk_resolver_1.resolveMysqlForeignKey)(schema, junctionTableKey, targetKey);
+    if (!junctionToTarget) {
+        throw new relq_errors_1.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 join_builder_1.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 => `${mysql_format_1.default.ident(targetAlias)}.${mysql_format_1.default.ident(col.sqlName)} AS ${mysql_format_1.default.ident(col.property)}`).join(', ');
+        parts.push(selectCols);
+    }
+    else {
+        parts.push(`${mysql_format_1.default.ident(targetAlias)}.*`);
+    }
+    parts.push(`FROM ${mysql_format_1.default.ident(junctionTableName)}`);
+    parts.push(`JOIN ${mysql_format_1.default.ident(targetTableName)} AS ${mysql_format_1.default.ident(targetAlias)}` +
+        ` ON ${mysql_format_1.default.ident(junctionTableName)}.${mysql_format_1.default.ident(junctionToTarget.fromColumn)}` +
+        ` = ${mysql_format_1.default.ident(targetAlias)}.${mysql_format_1.default.ident(junctionToTarget.toColumn)}`);
+    let whereClause = `${mysql_format_1.default.ident(junctionTableName)}.${mysql_format_1.default.ident(leftToJunction.toColumn)}` +
+        ` = ${mysql_format_1.default.ident(leftAlias)}.${mysql_format_1.default.ident(leftToJunction.fromColumn)}`;
+    const conditionInternals = builder[join_internals_1.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 => `${mysql_format_1.default.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 => `${mysql_format_1.default.literal(col.property)}, \`sub\`.${mysql_format_1.default.ident(col.property)}`)
+            .join(', ');
+    }
+    else {
+        jsonObjectParts = "'__all', `sub`.*";
+    }
+    const outerQuery = `(SELECT COALESCE(JSON_ARRAYAGG(JSON_OBJECT(${jsonObjectParts})), CAST('[]' AS JSON))` +
+        ` AS ${mysql_format_1.default.ident(targetAlias)}` +
+        ` FROM (${innerQuery}) AS \`sub\`)` +
+        ` AS ${mysql_format_1.default.ident(`${targetAlias}_lateral`)}`;
+    return outerQuery;
+}