@rvoh/dream 1.0.5 → 1.1.0

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -9,14 +9,14 @@ const index_js_2 = require("../../db/index.js");
 const associationToGetterSetterProp_js_1 = require("../../decorators/field/association/associationToGetterSetterProp.js");
 const PackageManager_js_1 = require("../../dream-app/helpers/PackageManager.js");
 const index_js_3 = require("../../dream-app/index.js");
-const ArrayTargetsIncompatibleWithThroughAssociation_js_1 = require("../../errors/associations/ArrayTargetsIncompatibleWithThroughAssociation.js");
-const CannotAssociateThroughMultiplePolymorphics_js_1 = require("../../errors/associations/CannotAssociateThroughMultiplePolymorphics.js");
+const ArrayTargetIncompatibleWithThroughAssociation_js_1 = require("../../errors/associations/ArrayTargetIncompatibleWithThroughAssociation.js");
 const CannotJoinPolymorphicBelongsToError_js_1 = require("../../errors/associations/CannotJoinPolymorphicBelongsToError.js");
 const JoinAttemptedOnMissingAssociation_js_1 = require("../../errors/associations/JoinAttemptedOnMissingAssociation.js");
 const MissingRequiredAssociationAndClause_js_1 = require("../../errors/associations/MissingRequiredAssociationAndClause.js");
 const MissingRequiredPassthroughForAssociationAndClause_js_1 = require("../../errors/associations/MissingRequiredPassthroughForAssociationAndClause.js");
 const MissingThroughAssociation_js_1 = require("../../errors/associations/MissingThroughAssociation.js");
 const MissingThroughAssociationSource_js_1 = require("../../errors/associations/MissingThroughAssociationSource.js");
+const ThroughAssociationConditionsIncompatibleWithThroughAssociationSource_js_1 = require("../../errors/associations/ThroughAssociationConditionsIncompatibleWithThroughAssociationSource.js");
 const CannotNegateSimilarityClause_js_1 = require("../../errors/CannotNegateSimilarityClause.js");
 const CannotPassUndefinedAsAValueToAWhereClause_js_1 = require("../../errors/CannotPassUndefinedAsAValueToAWhereClause.js");
 const UnexpectedUndefined_js_1 = require("../../errors/UnexpectedUndefined.js");
@@ -32,7 +32,6 @@ const loadPgClient_js_1 = require("../../helpers/db/loadPgClient.js");
 const runMigration_js_1 = require("../../helpers/db/runMigration.js");
 const EnvInternal_js_1 = require("../../helpers/EnvInternal.js");
 const isEmpty_js_1 = require("../../helpers/isEmpty.js");
-const isObject_js_1 = require("../../helpers/isObject.js");
 const namespaceColumn_js_1 = require("../../helpers/namespaceColumn.js");
 const normalizeUnicode_js_1 = require("../../helpers/normalizeUnicode.js");
 const objectPathsToArrays_js_1 = require("../../helpers/objectPathsToArrays.js");
@@ -44,8 +43,9 @@ const uniq_js_1 = require("../../helpers/uniq.js");
 const curried_ops_statement_js_1 = require("../../ops/curried-ops-statement.js");
 const ops_statement_js_1 = require("../../ops/ops-statement.js");
 const constants_js_1 = require("../constants.js");
+const throughAssociationHasOptionsBesidesThroughAndSource_js_1 = require("../internal/associations/throughAssociationHasOptionsBesidesThroughAndSource.js");
+const associationStringToNameAndAlias_js_1 = require("../internal/associationStringToNameAndAlias.js");
 const executeDatabaseQuery_js_1 = require("../internal/executeDatabaseQuery.js");
-const extractAssociationMetadataFromAssociationName_js_1 = require("../internal/extractAssociationMetadataFromAssociationName.js");
 const orderByDirection_js_1 = require("../internal/orderByDirection.js");
 const shouldBypassDefaultScope_js_1 = require("../internal/shouldBypassDefaultScope.js");
 const SimilarityBuilder_js_1 = require("../internal/similarity/SimilarityBuilder.js");
@@ -665,14 +665,12 @@ class KyselyQueryDriver extends Base_js_1.default {
         const aliases = Object.keys(aliasToDreamClassesMap);
         let nextColumnAliasCounter = 0;
         aliases.forEach((aliasOrExpression) => {
-            const alias = (0, extractAssociationMetadataFromAssociationName_js_1.default)(aliasOrExpression).alias;
-            if (alias === undefined)
-                throw new UnexpectedUndefined_js_1.default();
+            const { name, alias: _alias } = (0, associationStringToNameAndAlias_js_1.default)(aliasOrExpression);
+            const alias = _alias || name;
             associationAliasToColumnAliasMap[alias] ||= {};
             const aliasedDreamClass = aliasToDreamClassesMap[alias];
             if (aliasedDreamClass === undefined)
                 throw new UnexpectedUndefined_js_1.default();
-            const association = aliasToAssociationsMap[alias];
             const columns = alias === this.query['baseSqlAlias']
                 ? options.columns
                     ? this.columnsWithRequiredLoadColumns(options.columns)
@@ -686,26 +684,6 @@ class KyselyQueryDriver extends Base_js_1.default {
                     throw new UnexpectedUndefined_js_1.default();
                 columnAliasMap[column] = columnAlias;
             });
-            if (association?.type === 'HasOne' || association?.type === 'HasMany') {
-                const setupPreloadData = (dbColumnName) => {
-                    const columnAlias = `dr${nextColumnAliasCounter++}`;
-                    const columnAliasMap = associationAliasToColumnAliasMap[association.through];
-                    if (columnAliasMap === undefined)
-                        throw new UnexpectedUndefined_js_1.default();
-                    columnAliasMap[dbColumnName] = columnAlias;
-                    kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(dbColumnName, association.through)} as ${columnAlias}`);
-                };
-                if (association.through && association.preloadThroughColumns) {
-                    if ((0, isObject_js_1.default)(association.preloadThroughColumns)) {
-                        const preloadMap = association.preloadThroughColumns;
-                        Object.keys(preloadMap).forEach(columnName => setupPreloadData(columnName));
-                    }
-                    else {
-                        const preloadArray = association.preloadThroughColumns;
-                        preloadArray.forEach(columnName => setupPreloadData(columnName));
-                    }
-                }
-            }
         });
         const queryResults = await (0, executeDatabaseQuery_js_1.default)(kyselyQuery, 'execute');
         const aliasToDreamIdMap = queryResults.reduce((aliasToDreamIdMap, singleSqlResult) => {
@@ -749,23 +727,12 @@ class KyselyQueryDriver extends Base_js_1.default {
                 return columnNameValueMap;
             }, {});
             const dream = this.dbResultToDreamInstance(columnValueMap, dreamClass);
-            const association = aliasToAssociationsMap[currentAlias];
-            if (association && association.through && association.preloadThroughColumns) {
-                const throughAssociationColumnToColumnAliasMap = associationAliasToColumnAliasMap[association.through];
-                if (throughAssociationColumnToColumnAliasMap === undefined)
-                    throw new UnexpectedUndefined_js_1.default();
-                this.hydratePreloadedThroughColumns({
-                    association,
-                    columnToColumnAliasMap: throughAssociationColumnToColumnAliasMap,
-                    dream,
-                    singleSqlResult,
-                });
-            }
             aliasToDreamIdMap[(0, protectAgainstPollutingAssignment_js_1.default)(currentAlias)]?.set(primaryKeyValue, dream);
         }
         const dream = aliasToDreamIdMap[currentAlias].get(primaryKeyValue);
         Object.keys(leftJoinStatements).forEach(nextAlias => {
-            const { name: associationName, alias } = (0, extractAssociationMetadataFromAssociationName_js_1.default)(nextAlias);
+            const { name: associationName, alias: _alias } = (0, associationStringToNameAndAlias_js_1.default)(nextAlias);
+            const alias = _alias || associationName;
             const association = dreamClass['getAssociationMetadata'](associationName);
             if (association === undefined)
                 throw new UnexpectedUndefined_js_1.default();
@@ -801,38 +768,6 @@ class KyselyQueryDriver extends Base_js_1.default {
         });
         return dream;
     }
-    hydratePreloadedThroughColumns({ association, columnToColumnAliasMap, dream, singleSqlResult, }) {
-        if (!association.through)
-            return;
-        if (!dream.preloadedThroughColumns)
-            return;
-        let columnNames = [];
-        const columnNameToPreloadedThroughColumnNameMap = {};
-        if ((0, isObject_js_1.default)(association.preloadThroughColumns)) {
-            const preloadMap = association.preloadThroughColumns;
-            columnNames = Object.keys(preloadMap).map(columnName => {
-                columnNameToPreloadedThroughColumnNameMap[columnName] = preloadMap[columnName];
-                return columnName;
-            });
-        }
-        else if (Array.isArray(association.preloadThroughColumns)) {
-            columnNames = association.preloadThroughColumns.map(columnName => {
-                columnNameToPreloadedThroughColumnNameMap[columnName] = columnName;
-                return columnName;
-            });
-        }
-        columnNames.forEach(columnName => {
-            const preloadedThroughColumnName = columnNameToPreloadedThroughColumnNameMap[columnName];
-            if (preloadedThroughColumnName === undefined)
-                throw new UnexpectedUndefined_js_1.default();
-            const columnAlias = columnToColumnAliasMap[columnName];
-            if (columnAlias === undefined) {
-                throw new UnexpectedUndefined_js_1.default();
-            }
-            ;
-            dream.preloadedThroughColumns[preloadedThroughColumnName] = singleSqlResult[columnAlias];
-        });
-    }
     applyJoinAndStatement(join, joinAndStatement, rootTableOrAssociationAlias) {
         if (!joinAndStatement)
             return join;
@@ -878,7 +813,12 @@ class KyselyQueryDriver extends Base_js_1.default {
                 joinStatement: query['innerJoinStatements'],
                 joinAndStatements: query['innerJoinAndStatements'],
                 dreamClass: query['dreamClass'],
-                previousAssociationTableOrAlias: this.query['baseSqlAlias'],
+                // As recursivelyJoin progresses through the chain of associations that
+                // the developer has inclued in a join statement (e.g. `leftJoinPreload('hello as ho', 'world as wd')`),
+                // previousTableAlias will be modified so that the join statement can properly reference
+                // what we are joining on. When an `associationQuery` is the start of a join, then `baseSqlAlias` is set,
+                // this is passed into the very beginning of recursivelyJoin.
+                previousTableAlias: this.query['baseSqlAlias'],
                 joinType: 'inner',
             });
         }
@@ -888,7 +828,12 @@ class KyselyQueryDriver extends Base_js_1.default {
                 joinStatement: query['leftJoinStatements'],
                 joinAndStatements: query['leftJoinAndStatements'],
                 dreamClass: query['dreamClass'],
-                previousAssociationTableOrAlias: this.query['baseSqlAlias'],
+                // As recursivelyJoin progresses through the chain of associations that
+                // the developer has inclued in a join statement (e.g. `leftJoinPreload('hello as ho', 'world as wd')`),
+                // previousTableAlias will be modified so that the join statement can properly reference
+                // what we are joining on. When an `associationQuery` is the start of a join, then `baseSqlAlias` is set,
+                // this is passed into the very beginning of recursivelyJoin.
+                previousTableAlias: this.query['baseSqlAlias'],
                 joinType: 'left',
             });
         }
@@ -1090,26 +1035,41 @@ class KyselyQueryDriver extends Base_js_1.default {
             throw new CannotPassUndefinedAsAValueToAWhereClause_js_1.default(this.dreamClass, a2);
         return { a, b, c, a2, b2, c2 };
     }
-    recursivelyJoin({ query, joinStatement, joinAndStatements, dreamClass, previousAssociationTableOrAlias, joinType, }) {
-        for (const currentAssociationTableOrAlias of Object.keys(joinStatement)) {
+    recursivelyJoin({ query, joinStatement, joinAndStatements, dreamClass, previousTableAlias, joinType, }) {
+        for (const associationString of Object.keys(joinStatement)) {
+            const joinAndStatement = joinAndStatements[associationString];
+            const { association, alias } = associationStringToAssociationAndMaybeAlias({
+                dreamClass,
+                associationString,
+            });
             const results = this.applyOneJoin({
                 query,
                 dreamClass,
-                previousAssociationTableOrAlias,
-                currentAssociationTableOrAlias,
-                joinAndStatements,
+                association,
+                previousTableAlias,
+                explicitAlias: alias,
+                joinAndStatement,
                 joinType,
-                baseThroughAssociation: undefined,
-                polymorphicCount: { count: 0 },
+                previousThroughAssociation: undefined,
+                dreamClassThroughAssociationWantsToHydrate: undefined,
             });
             query = results.query;
-            const association = results.association;
+            /**
+             * If the returned association links to multiple models, then it is a polymorphic BelongsTo association,
+             * and we can only join through a polymorphic BelongsTo association when the association included in
+             * the join statement is a `through` association that clamps the types on the other side of the polymorphic
+             * BelongsTo down to a single Dream model. So if an array, use the associated type of the association
+             * included in the join statement.
+             */
+            const nextDreamClass = Array.isArray(results.association.modelCB())
+                ? association.modelCB()
+                : results.association.modelCB();
             query = this.recursivelyJoin({
                 query,
-                joinStatement: joinStatement[currentAssociationTableOrAlias],
-                joinAndStatements: joinAndStatements[currentAssociationTableOrAlias],
-                dreamClass: association.modelCB(),
-                previousAssociationTableOrAlias: currentAssociationTableOrAlias,
+                joinStatement: joinStatement[associationString],
+                joinAndStatements: joinAndStatement,
+                dreamClass: nextDreamClass,
+                previousTableAlias: alias || association.as,
                 joinType,
             });
         }
@@ -1171,21 +1131,12 @@ class KyselyQueryDriver extends Base_js_1.default {
     associationNamesToAssociationDataAndDreamClassesMap(associationNames) {
         const associationsToDreamClassesMap = {};
         associationNames.reduce((dreamClass, associationName) => {
-            const { name, alias } = (0, extractAssociationMetadataFromAssociationName_js_1.default)(associationName);
+            const { name, alias: _alias } = (0, associationStringToNameAndAlias_js_1.default)(associationName);
+            const alias = _alias || name;
             const association = dreamClass['getAssociationMetadata'](name);
             if (association === undefined)
                 throw new UnexpectedUndefined_js_1.default();
-            const through = association.through;
-            if (through) {
-                const { throughAssociation, throughAssociationDreamClass } = this.throughAssociationDetails(dreamClass, through);
-                associationsToDreamClassesMap[through] = {
-                    association: throughAssociation,
-                    dreamClass: throughAssociationDreamClass,
-                };
-            }
             const nextDreamClass = association.modelCB();
-            if (alias === undefined)
-                throw new UnexpectedUndefined_js_1.default();
             associationsToDreamClassesMap[alias] = { association, dreamClass: nextDreamClass };
             return nextDreamClass;
         }, this.dreamClass);
@@ -1286,291 +1237,349 @@ class KyselyQueryDriver extends Base_js_1.default {
         return query;
     }
     /**
-     * Each association in the chain is pushed onto `throughAssociations`
-     * and `applyOneJoin` is recursively called. The trick is that the
-     * through associations don't get written into the SQL; they
-     * locate the next association we need to build into the SQL,
-     * which is only run by the association that started the `through`
-     * chain. The final association at the end of the `through` chain _is_
-     * written into the SQL as a full association, but the modifications from
-     * the `through` association are only added when the recursion returns
-     * back to the association that kicked off the through associations.
+     * Recursively traverse the through association chain until we reach a non-through association.
+     * The non-through association is the association that joins the model with the through
+     * association's intended source (the model that it wants to pull into scope). The non-through
+     * association is added to the query, and then the process continues with the source on the other
+     * side of that association, which may itself be a through association, resulting in another
+     * recursive call to joinsBridgeThroughAssociations.
+     *
+     * A chain of through associations on a single Dream model class may be used to join through
+     * several other models. For example, given the following:
+     *
+     * ```
+     * model MyModel
+     *   @deco.HasOne('OtherModel')
+     *   public otherModel
+     *
+     *   @deco.HasOne('A', { through: 'otherModel', source: 'a' })
+     *   public myA
+     *
+     *   @deco.HasOne('B', { through: 'myA', source: 'b' })
+     *   public myB
+     *
+     * model OtherModel
+     *   @deco.HasOne('AToOtherModelJoinModel')
+     *   public aToOtherModelJoinModel
+     *
+     *   @deco.HasOne('A', { through: 'aToOtherModelJoinModel' })
+     *   public a
+     *
+     * model AToOtherModelJoinModel
+     *   @deco.BelongsTo('A')
+     *   public a
+     *
+     *   @deco.BelongsTo('OtherModel
+     *   public otherModel
+     *
+     * model A
+     *   @deco.HasOne('B')
+     *   public b
+     * ```
+     *
+     * Then `MyModel.leftJoinPreload('myB')` is processed as follows:
+     * - `applyOneJoin` is called with the `myB` association
+     *   - `joinsBridgeThroughAssociations` is called with the `myB` association
+     *     - `joinsBridgeThroughAssociations` is called with the `myA` association
+     *       - `addAssociationJoinStatementToQuery` is called with the `otherModel` association
+     *       - `applyOneJoin` is called with the `a` association from OtherModel
+     *         - `joinsBridgeThroughAssociations` is called with the `a` association from OtherModel
+     *           // throw ThroughAssociationConditionsIncompatibleWithThroughAssociationSource if
+     *           // myA in MyModel defines conditions, distinct, or order
+     *           - `addAssociationJoinStatementToQuery` is called with the `aToOtherModelJoinModel` association
+     *           - `applyOneJoin` is called with the `a` association from AToOtherModelJoinModel with conditions (if present) on `a` defined on OtherModel
+     *             - `addAssociationJoinStatementToQuery` is called with the `myA` association
+     *     - `applyOneJoin` is called with the `b` association from A with conditions (if present) from `myB` defined on MyModel
+     *       - `addAssociationJoinStatementToQuery` is called with the `myB` association
      */
-    joinsBridgeThroughAssociations({ query, dreamClass, association, previousAssociationTableOrAlias, throughAssociations, joinType, baseThroughAssociation, polymorphicCount, }) {
-        if (association.type === 'BelongsTo' || !association.through) {
-            return {
+    joinsBridgeThroughAssociations({ query, dreamClassTheAssociationIsDefinedOn, throughAssociation, 
+    /**
+     * If the join statement includes an explicit alias, e.g.,
+     * `leftJoinPreload('hello as ho', 'world as wd')`
+     * then explicitAlias is set (e.g., to 'ho' the first time that `recursivelyJoin`
+     * calls this method and to 'ho' the second time `recursivelyJoin` is called)
+     * If only implicit aliasing happens (based on association name)
+     * (e.g. `leftJoinPreload('hello', 'world')`), then explicitAlias is null
+     */
+    explicitAlias, 
+    /**
+     * previousTableAlias is always set
+     */
+    previousTableAlias, joinAndStatement, joinType, }) {
+        /**
+         * `through` associations always point to other associations on the same model
+         * they are defined on. So when we want to find an association referenced by a
+         * through association, we look on the same model as the through association
+         */
+        const associationReferencedByThroughAssociation = dreamClassTheAssociationIsDefinedOn['getAssociationMetadata'](throughAssociation.through);
+        if (!associationReferencedByThroughAssociation) {
+            // Type protection on association declarations should protect against this ever actually being reached
+            throw new MissingThroughAssociation_js_1.default({
+                dreamClass: dreamClassTheAssociationIsDefinedOn,
+                association: throughAssociation,
+            });
+        }
+        let recursiveResult;
+        const addingNestedThroughAssociation = associationReferencedByThroughAssociation.type !== 'BelongsTo' &&
+            associationReferencedByThroughAssociation.through;
+        if (addingNestedThroughAssociation) {
+            /**
+             * This new association is itself a through association, so we recursively
+             * call joinsBridgeThroughAssociations.
+             */
+            recursiveResult = this.joinsBridgeThroughAssociations({
                 query,
-                dreamClass,
-                association,
-                previousAssociationTableOrAlias,
-            };
+                /**
+                 * `through` associations always point to other associations on the same model
+                 * they are defined on. So when this association is a through association,
+                 * we can simply pass the dreamClassAssociationDefinedIn we already have
+                 */
+                dreamClassTheAssociationIsDefinedOn,
+                throughAssociation: associationReferencedByThroughAssociation,
+                explicitAlias: undefined,
+                previousTableAlias,
+                joinAndStatement: {},
+                joinType,
+            });
+            //
         }
         else {
-            throughAssociations.push(association);
-            // We have entered joinsBridgeThroughAssociations with the
-            // CompositionAssetAudits HasOne User association, which
-            // is through compositionAsset
-            // We now apply the compositionAsset association (a BelongsTo)
-            // to the query
-            const { query: queryWithThroughAssociationApplied } = this.applyOneJoin({
+            /**
+             * We have reached the association at the end of the through chain, the final
+             * association that we pass _through_ to reach the model class on which the
+             * _source_ association of the through association is found. That source
+             * association will be added to the query as the next step at the end of this
+             * method.
+             */
+            recursiveResult = this.addAssociationJoinStatementToQuery({
                 query,
-                dreamClass,
-                previousAssociationTableOrAlias,
-                currentAssociationTableOrAlias: association.through,
-                throughAssociations,
+                dreamClass: dreamClassTheAssociationIsDefinedOn,
+                association: associationReferencedByThroughAssociation,
+                /**
+                 * The explicit alias is reserved for the final association, not intermediary join tables
+                 */
+                explicitAlias: undefined,
+                previousTableAlias,
+                selfTableAlias: previousTableAlias,
+                /**
+                 * The joinAndStatement is reserved for the final association, not intermediary join tables
+                 */
+                joinAndStatement: {},
+                previousThroughAssociation: undefined,
                 joinType,
-                baseThroughAssociation,
-                polymorphicCount,
+                dreamClassThroughAssociationWantsToHydrate: undefined,
             });
-            // The through association has both a `through` and a `source`. The `source`
-            // is the association on the model that has now been joined. In our example,
-            // the `source` is the `user` association on the CompositionAsset model
-            const { newAssociation, throughAssociation, throughClass } = this.followThroughAssociation(dreamClass, association);
-            if (newAssociation.through) {
-                // This new association is itself a through association, so we recursively
-                // call joinsBridgeThroughAssociations
-                return this.joinsBridgeThroughAssociations({
-                    query: queryWithThroughAssociationApplied,
-                    dreamClass: throughClass,
-                    association: newAssociation,
-                    previousAssociationTableOrAlias: throughAssociation.as,
-                    throughAssociations,
-                    joinType,
-                    baseThroughAssociation,
-                    polymorphicCount,
-                });
-            }
-            else {
-                // This new association is not a through association, so
-                // this is the target association we were looking for
-                return {
-                    query: queryWithThroughAssociationApplied,
-                    dreamClass: association.modelCB(),
-                    association: newAssociation,
-                    throughClass,
-                    previousAssociationTableOrAlias: association.through,
-                };
-            }
         }
-    }
-    /**
-     * @internal
-     *
-     * Used to bridge through associations
-     */
-    followThroughAssociation(dreamClass, association) {
-        const throughAssociation = association.through && dreamClass['getAssociationMetadata'](association.through);
-        if (!throughAssociation)
-            throw new MissingThroughAssociation_js_1.default({
-                dreamClass,
-                association,
+        const dreamClassWithSourceAssociation = associationReferencedByThroughAssociation.modelCB();
+        if (Array.isArray(dreamClassWithSourceAssociation))
+            throw new ArrayTargetIncompatibleWithThroughAssociation_js_1.default({
+                dreamClass: dreamClassTheAssociationIsDefinedOn,
+                association: throughAssociation,
             });
-        const throughClass = throughAssociation.modelCB();
-        if (Array.isArray(throughClass))
-            throw new ArrayTargetsIncompatibleWithThroughAssociation_js_1.default({
-                dreamClass,
-                association,
-            });
-        const newAssociation = getSourceAssociation(throughClass, association.source);
-        if (!newAssociation)
+        const sourceAssociation = getSourceAssociation(dreamClassWithSourceAssociation, throughAssociation.source);
+        if (!sourceAssociation)
             throw new MissingThroughAssociationSource_js_1.default({
-                dreamClass,
-                throughClass,
-                association,
+                dreamClass: dreamClassTheAssociationIsDefinedOn,
+                association: throughAssociation,
+                throughClass: dreamClassWithSourceAssociation,
             });
-        return { throughAssociation, throughClass, newAssociation };
+        /**
+         * When the source is a polymorphic BelongsTo association, use the target of the through
+         * association to determine which class to target.
+         */
+        const dreamClassThroughAssociationWantsToHydrate = Array.isArray(sourceAssociation.modelCB())
+            ? throughAssociation.modelCB()
+            : undefined;
+        /**
+         * Add the source that `sourceAssociation` points to. Note that since joinsBridgeThroughAssociations
+         * is recursive, it may have added other through associations to the query in between when this
+         * particular method call started and now.
+         */
+        return this.applyOneJoin({
+            query: recursiveResult.query,
+            dreamClass: dreamClassWithSourceAssociation,
+            association: sourceAssociation,
+            // since joinsBridgeThroughAssociations passes undefined to explicitAlias recursively, we know this is only set on the
+            // first call to joinsBridgeThroughAssociations, which corresponds to the outermoset through association and therefore
+            // the last source association to be added to the statement (because joinsBridgeThroughAssociations was called
+            // recursively and therefore may have added other through associations and their sources prior to reaching this point)
+            explicitAlias,
+            previousTableAlias: recursiveResult.association.as,
+            selfTableAlias: (throughAssociation.selfAnd ?? throughAssociation.selfAndNot)
+                ? previousTableAlias
+                : recursiveResult.association.as,
+            // since joinsBridgeThroughAssociations passes {} to joinAndStatement recursively, we know this is only set on the
+            // first call to joinsBridgeThroughAssociations, which corresponds to the outermoset through association and therefore
+            // the last source association to be added to the statement (because joinsBridgeThroughAssociations was called
+            // recursively and therefore may have added other through associations and their sources prior to reaching this point)
+            joinAndStatement,
+            previousThroughAssociation: throughAssociation,
+            joinType,
+            dreamClassThroughAssociationWantsToHydrate,
+        });
     }
+    applyOneJoin({ query, dreamClass, association, 
     /**
-     * Each association in the chain is pushed onto `throughAssociations`
-     * and `applyOneJoin` is recursively called. The trick is that the
-     * through associations don't get written into the SQL; they
-     * locate the next association we need to build into the SQL,
-     * which is only run by the association that started the `through`
-     * chain. The final association at the end of the `through` chain _is_
-     * written into the SQL as a full association, but the modifications from
-     * the `through` association are only added when the recursion returns
-     * back to the association that kicked off the through associations.
+     * If the join statement includes an explicit alias, e.g.,
+     * `leftJoinPreload('hello as ho', 'world as wd')`
+     * then explicitAlias is set (e.g., to 'ho' the first time that `recursivelyJoin`
+     * calls this method and to 'ho' the second time `recursivelyJoin` is called)
+     * If only implicit aliasing happens (based on association name)
+     * (e.g. `leftJoinPreload('hello', 'world')`), then explicitAlias is null
      */
-    applyOneJoin({ query, dreamClass, previousAssociationTableOrAlias, currentAssociationTableOrAlias, joinAndStatements = {}, throughAssociations = [], joinType, baseThroughAssociation, polymorphicCount, }) {
-        const { name, alias } = (0, extractAssociationMetadataFromAssociationName_js_1.default)(currentAssociationTableOrAlias);
-        const joinAndStatement = joinAndStatements[currentAssociationTableOrAlias];
-        previousAssociationTableOrAlias = (0, extractAssociationMetadataFromAssociationName_js_1.default)(previousAssociationTableOrAlias).alias;
-        currentAssociationTableOrAlias = alias;
-        let association = dreamClass['getAssociationMetadata'](name);
-        if (association?.polymorphic)
-            polymorphicCount.count++;
-        if (!association) {
-            throw new JoinAttemptedOnMissingAssociation_js_1.default({
-                dreamClass,
-                associationName: currentAssociationTableOrAlias,
+    explicitAlias, 
+    /**
+     * previousTableAlias is always set
+     */
+    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociation, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+        if (association.type !== 'BelongsTo' && association.through) {
+            if ((0, throughAssociationHasOptionsBesidesThroughAndSource_js_1.default)(previousThroughAssociation)) {
+                throw new ThroughAssociationConditionsIncompatibleWithThroughAssociationSource_js_1.default({
+                    dreamClass,
+                    association,
+                });
+            }
+            return this.joinsBridgeThroughAssociations({
+                query,
+                dreamClassTheAssociationIsDefinedOn: dreamClass,
+                throughAssociation: association,
+                explicitAlias,
+                previousTableAlias,
+                joinAndStatement,
+                joinType,
             });
         }
-        baseThroughAssociation ??= association.through
-            ? association
-            : undefined;
-        const results = this.joinsBridgeThroughAssociations({
+        return this.addAssociationJoinStatementToQuery({
             query,
             dreamClass,
             association,
-            previousAssociationTableOrAlias,
-            throughAssociations,
+            explicitAlias,
+            previousTableAlias,
+            selfTableAlias,
+            joinAndStatement,
+            previousThroughAssociation,
             joinType,
-            baseThroughAssociation,
-            polymorphicCount,
+            dreamClassThroughAssociationWantsToHydrate,
         });
-        query = results.query;
-        dreamClass = results.dreamClass;
-        association = results.association;
-        if (association?.polymorphic)
-            polymorphicCount.count++;
-        const timeToApplyThroughAssociations = throughAssociations.length && throughAssociations[0]?.source === association.as;
-        const baseThroughAssociationToApply = association.polymorphic ? baseThroughAssociation : undefined;
-        if (baseThroughAssociationToApply && polymorphicCount.count > 1)
-            throw new CannotAssociateThroughMultiplePolymorphics_js_1.default({
-                dreamClass,
-                association,
-                innerJoinStatements: this.query['innerJoinStatements'],
-                leftJoinStatements: this.query['leftJoinStatements'],
-            });
-        const originalPreviousAssociationTableOrAlias = previousAssociationTableOrAlias;
-        previousAssociationTableOrAlias = results.previousAssociationTableOrAlias;
-        const throughClass = results.throughClass;
-        if (timeToApplyThroughAssociations) {
-            /**
-             * Each association in the chain is pushed onto `throughAssociations`
-             * and `applyOneJoin` is recursively called. The trick is that the
-             * through associations don't get written into the SQL; they
-             * locate the next association we need to build into the SQL,
-             * which is only run by the association that started the `through`
-             * chain (thus the
-             * `throughAssociations.length && throughAssociations[0].source === association.as`
-             * above). The final association at the end of the `through` chain _is_
-             * written into the SQL as a full association, but the modifications from
-             * the `through` association are only added when the recursion returns
-             * back to the association that kicked off the through associations.
-             */
-            throughAssociations.forEach((throughAssociation) => {
-                if (throughAssociation.type === 'HasMany') {
-                    if (query?.distinctOn && throughAssociation.distinct) {
-                        query = query.distinctOn(this.distinctColumnNameForAssociation({
-                            association: throughAssociation,
-                            tableNameOrAlias: currentAssociationTableOrAlias,
-                            foreignKey: throughAssociation.primaryKey(),
-                        }));
-                    }
-                    if (throughAssociation.order) {
-                        query = this.applyOrderStatementForAssociation({
-                            query,
-                            association: throughAssociation,
-                            tableNameOrAlias: currentAssociationTableOrAlias,
-                        });
-                    }
-                }
-            });
+    }
+    addAssociationJoinStatementToQuery({ query, dreamClass, association, 
+    /**
+     * If the join statement includes an explicit alias, e.g.,
+     * `leftJoinPreload('hello as ho', 'world as wd')`
+     * then explicitAlias is set (e.g., to 'ho' the first time that `recursivelyJoin`
+     * calls this method and to 'ho' the second time `recursivelyJoin` is called)
+     * If only implicit aliasing happens (based on association name)
+     * (e.g. `leftJoinPreload('hello', 'world')`), then explicitAlias is null
+     */
+    explicitAlias, 
+    /**
+     * previousTableAlias is always set
+     */
+    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociation, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+        const currentTableAlias = explicitAlias ?? association.as;
+        if (previousThroughAssociation?.type === 'HasMany') {
+            if (query?.distinctOn && previousThroughAssociation.distinct) {
+                query = query.distinctOn(this.distinctColumnNameForAssociation({
+                    association: previousThroughAssociation,
+                    tableNameOrAlias: currentTableAlias,
+                    foreignKey: previousThroughAssociation.primaryKey(),
+                }));
+            }
+            if (previousThroughAssociation?.order) {
+                query = this.applyOrderStatementForAssociation({
+                    query,
+                    association: previousThroughAssociation,
+                    tableNameOrAlias: currentTableAlias,
+                });
+            }
         }
         if (association.type === 'BelongsTo') {
-            if (!baseThroughAssociationToApply && Array.isArray(association.modelCB()))
+            if (!dreamClassThroughAssociationWantsToHydrate && Array.isArray(association.modelCB()))
                 throw new CannotJoinPolymorphicBelongsToError_js_1.default({
                     dreamClass,
                     association,
                     innerJoinStatements: this.query['innerJoinStatements'],
                     leftJoinStatements: this.query['leftJoinStatements'],
                 });
-            const to = (baseThroughAssociationToApply ?? association).modelCB().table;
-            const joinTableExpression = currentAssociationTableOrAlias === to
-                ? currentAssociationTableOrAlias
-                : `${to} as ${currentAssociationTableOrAlias}`;
+            const to = (dreamClassThroughAssociationWantsToHydrate ?? association.modelCB()).table;
+            const joinTableExpression = (0, snakeify_js_1.default)(currentTableAlias) === to ? currentTableAlias : `${to} as ${currentTableAlias}`;
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
-                join = join.onRef(this.namespaceColumn(association.foreignKey(), previousAssociationTableOrAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
-                    associatedClassOverride: baseThroughAssociationToApply?.modelCB(),
-                }), currentAssociationTableOrAlias));
-                if (baseThroughAssociationToApply) {
-                    /**
-                     * At this point, all `through` associations have been bridged and a
-                     * real association has been reached that is a polymorphic BelongsTo (it
-                     * is polymorphic and has an array of target models). Join with that
-                     * table conditionally based on the polymorphic foreign key type,
-                     * namespaced to the name of that association (which we know from the
-                     * target of the final `through` association)
-                     */
-                    join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement({
-                        [association.foreignKeyTypeField()]: baseThroughAssociationToApply.modelCB().sanitizedName,
-                    }, throughAssociations.at(-1).through)));
-                }
-                if (timeToApplyThroughAssociations) {
-                    throughAssociations.forEach((throughAssociation) => {
-                        join = this.applyAssociationAndStatementsToJoinStatement({
-                            join,
-                            association: throughAssociation,
-                            currentAssociationTableOrAlias,
-                            previousAssociationTableOrAlias: originalPreviousAssociationTableOrAlias,
-                            joinAndStatements,
-                        });
+                join = join.onRef(this.namespaceColumn(association.foreignKey(), previousTableAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
+                    associatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                }), currentTableAlias));
+                if (previousThroughAssociation) {
+                    if (dreamClassThroughAssociationWantsToHydrate) {
+                        join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement({
+                            [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate.sanitizedName,
+                        }, previousThroughAssociation.through)));
+                    }
+                    join = this.applyAssociationAndStatementsToJoinStatement({
+                        join,
+                        association: previousThroughAssociation,
+                        currentTableAlias,
+                        selfTableAlias,
+                        joinAndStatement,
                     });
                 }
                 join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
                     join,
-                    tableNameOrAlias: currentAssociationTableOrAlias,
+                    tableNameOrAlias: currentTableAlias,
                     association,
-                    throughAssociatedClassOverride: baseThroughAssociationToApply?.modelCB(),
+                    throughAssociatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
                 });
-                join = this.applyJoinAndStatement(join, joinAndStatement, currentAssociationTableOrAlias);
+                join = this.applyJoinAndStatement(join, joinAndStatement, currentTableAlias);
                 return join;
             });
         }
         else {
             const to = association.modelCB().table;
-            const joinTableExpression = currentAssociationTableOrAlias === to
-                ? currentAssociationTableOrAlias
-                : `${to} as ${currentAssociationTableOrAlias}`;
+            const joinTableExpression = (0, snakeify_js_1.default)(currentTableAlias) === to ? currentTableAlias : `${to} as ${currentTableAlias}`;
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
-                join = join.onRef(this.namespaceColumn(association.primaryKey(), previousAssociationTableOrAlias), '=', this.namespaceColumn(association.foreignKey(), currentAssociationTableOrAlias));
+                join = join.onRef(this.namespaceColumn(association.primaryKey(), previousTableAlias), '=', this.namespaceColumn(association.foreignKey(), currentTableAlias));
                 if (association.polymorphic) {
                     join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement({
-                        [association.foreignKeyTypeField()]: throughClass
-                            ? throughClass['stiBaseClassOrOwnClassName']
+                        [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate
+                            ? dreamClassThroughAssociationWantsToHydrate['stiBaseClassOrOwnClassName']
                             : dreamClass['stiBaseClassOrOwnClassName'],
-                    }, currentAssociationTableOrAlias)));
+                    }, currentTableAlias)));
                 }
-                if (timeToApplyThroughAssociations) {
-                    throughAssociations.forEach((throughAssociation) => {
-                        join = this.applyAssociationAndStatementsToJoinStatement({
-                            join,
-                            association: throughAssociation,
-                            currentAssociationTableOrAlias,
-                            previousAssociationTableOrAlias: originalPreviousAssociationTableOrAlias,
-                            joinAndStatements,
-                        });
+                if (previousThroughAssociation) {
+                    join = this.applyAssociationAndStatementsToJoinStatement({
+                        join,
+                        association: previousThroughAssociation,
+                        currentTableAlias,
+                        selfTableAlias,
+                        joinAndStatement,
                     });
                 }
                 join = this.applyAssociationAndStatementsToJoinStatement({
                     join,
                     association,
-                    currentAssociationTableOrAlias,
-                    previousAssociationTableOrAlias,
-                    joinAndStatements,
+                    currentTableAlias,
+                    selfTableAlias,
+                    joinAndStatement,
                 });
                 join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
                     join,
-                    tableNameOrAlias: currentAssociationTableOrAlias,
+                    tableNameOrAlias: currentTableAlias,
                     association,
-                    throughAssociatedClassOverride: baseThroughAssociationToApply?.modelCB(),
+                    throughAssociatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
                 });
-                join = this.applyJoinAndStatement(join, joinAndStatement, currentAssociationTableOrAlias);
+                join = this.applyJoinAndStatement(join, joinAndStatement, currentTableAlias);
                 return join;
             });
             if (association.type === 'HasMany') {
                 if (association.order) {
                     query = this.applyOrderStatementForAssociation({
                         query,
-                        tableNameOrAlias: currentAssociationTableOrAlias,
+                        tableNameOrAlias: currentTableAlias,
                         association,
                     });
                 }
                 if (query.distinctOn && association.distinct) {
                     query = query.distinctOn(this.distinctColumnNameForAssociation({
                         association,
-                        tableNameOrAlias: currentAssociationTableOrAlias,
+                        tableNameOrAlias: currentTableAlias,
                         foreignKey: association.foreignKey(),
                     }));
                 }
@@ -1579,8 +1588,6 @@ class KyselyQueryDriver extends Base_js_1.default {
         return {
             query,
             association,
-            previousAssociationTableOrAlias,
-            currentAssociationTableOrAlias,
         };
     }
     applyOrderStatementForAssociation({ query, tableNameOrAlias, association, }) {
@@ -1606,28 +1613,28 @@ class KyselyQueryDriver extends Base_js_1.default {
             return this.namespaceColumn(foreignKey, tableNameOrAlias);
         return this.namespaceColumn(association.distinct, tableNameOrAlias);
     }
-    applyAssociationAndStatementsToJoinStatement({ join, currentAssociationTableOrAlias, previousAssociationTableOrAlias, association, joinAndStatements, }) {
+    applyAssociationAndStatementsToJoinStatement({ join, currentTableAlias, selfTableAlias, association, joinAndStatement, }) {
         if (association.and) {
-            this.throwUnlessAllRequiredWhereClausesProvided(association, currentAssociationTableOrAlias, joinAndStatements);
-            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(association.and, currentAssociationTableOrAlias), { disallowSimilarityOperator: false }));
+            this.throwUnlessAllRequiredWhereClausesProvided(association, currentTableAlias, joinAndStatement);
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(association.and, currentTableAlias), { disallowSimilarityOperator: false }));
         }
         if (association.andNot) {
-            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(association.andNot, currentAssociationTableOrAlias), { negate: true }));
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(association.andNot, currentTableAlias), { negate: true }));
         }
         if (association.andAny) {
-            join = join.on((eb) => eb.or(association.andAny.map(whereAnyStatement => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(whereAnyStatement, currentAssociationTableOrAlias), { disallowSimilarityOperator: false }))));
+            join = join.on((eb) => eb.or(association.andAny.map(whereAnyStatement => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(whereAnyStatement, currentTableAlias), { disallowSimilarityOperator: false }))));
         }
         if (association.selfAnd) {
             join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.rawifiedSelfOnClause({
                 associationAlias: association.as,
-                selfAlias: previousAssociationTableOrAlias,
+                selfAlias: selfTableAlias,
                 selfAndClause: association.selfAnd,
             })));
         }
         if (association.selfAndNot) {
             join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.rawifiedSelfOnClause({
                 associationAlias: association.as,
-                selfAlias: previousAssociationTableOrAlias,
+                selfAlias: selfTableAlias,
                 selfAndClause: association.selfAndNot,
             }), { negate: true }));
         }
@@ -1640,7 +1647,7 @@ class KyselyQueryDriver extends Base_js_1.default {
                 agg.push(column);
             return agg;
         }, []);
-        const missingRequiredWhereStatements = columnsRequiringAndStatements.filter(column => joinAndStatements[namespace]?.and?.[column] === undefined);
+        const missingRequiredWhereStatements = columnsRequiringAndStatements.filter(column => joinAndStatements?.and?.[column] === undefined);
         if (missingRequiredWhereStatements.length)
             throw new MissingRequiredAssociationAndClause_js_1.default(association, missingRequiredWhereStatements[0]);
     }
@@ -1767,7 +1774,8 @@ class KyselyQueryDriver extends Base_js_1.default {
         const dream = dreams.find(dream => dream['getAssociationMetadata'](associationName));
         if (!dream)
             return;
-        const { name, alias } = (0, extractAssociationMetadataFromAssociationName_js_1.default)(associationName);
+        const { name, alias: _alias } = (0, associationStringToNameAndAlias_js_1.default)(associationName);
+        const alias = _alias || name;
         const association = dream['getAssociationMetadata'](name);
         if (association === undefined)
             throw new UnexpectedUndefined_js_1.default();
@@ -1776,25 +1784,7 @@ class KyselyQueryDriver extends Base_js_1.default {
         if ((association.polymorphic && association.type === 'BelongsTo') || Array.isArray(dreamClassToHydrate))
             return this.preloadPolymorphicBelongsTo(association, dreams);
         const dreamClassToHydrateColumns = [...dreamClassToHydrate.columns()];
-        const throughColumnsToHydrate = [];
         const columnsToPluck = dreamClassToHydrateColumns.map(column => this.namespaceColumn(column.toString(), alias));
-        const asHasAssociation = association;
-        if (asHasAssociation.through && asHasAssociation.preloadThroughColumns) {
-            if ((0, isObject_js_1.default)(asHasAssociation.preloadThroughColumns)) {
-                const preloadMap = asHasAssociation.preloadThroughColumns;
-                Object.keys(preloadMap).forEach(preloadThroughColumn => {
-                    throughColumnsToHydrate.push(preloadMap[preloadThroughColumn]);
-                    columnsToPluck.push(this.namespaceColumn(preloadThroughColumn, asHasAssociation.through));
-                });
-            }
-            else {
-                const preloadArray = asHasAssociation.preloadThroughColumns;
-                preloadArray.forEach(preloadThroughColumn => {
-                    throughColumnsToHydrate.push(preloadThroughColumn);
-                    columnsToPluck.push(this.namespaceColumn(preloadThroughColumn, asHasAssociation.through));
-                });
-            }
-        }
         columnsToPluck.push(this.namespaceColumn(dreamClass.primaryKey, dreamClass.table));
         const baseClass = dreamClass['stiBaseClassOrOwnClass']['getAssociationMetadata'](associationName)
             ? dreamClass['stiBaseClassOrOwnClass']
@@ -1817,8 +1807,6 @@ class KyselyQueryDriver extends Base_js_1.default {
             const attributes = {};
             dreamClassToHydrateColumns.forEach((columnName, index) => (attributes[(0, protectAgainstPollutingAssignment_js_1.default)(columnName)] = pluckedData[index]));
             const hydratedDream = this.dbResultToDreamInstance(attributes, dreamClassToHydrate);
-            throughColumnsToHydrate.forEach((throughAssociationColumn, index) => (hydratedDream.preloadedThroughColumns[throughAssociationColumn] =
-                pluckedData[dreamClassToHydrateColumns.length + index]));
             return {
                 dream: hydratedDream,
                 pointsToPrimaryKey: pluckedData.at(-1),
@@ -1837,3 +1825,18 @@ function getSourceAssociation(dream, sourceName) {
     return (dream['getAssociationMetadata'](sourceName) ||
         dream['getAssociationMetadata'](pluralize_esm_1.default.singular(sourceName)));
 }
+const associationStringToAssociationAndMaybeAlias = function ({ dreamClass, associationString, }) {
+    const { name, alias: _alias } = (0, associationStringToNameAndAlias_js_1.default)(associationString);
+    const alias = _alias || name;
+    const association = dreamClass['getAssociationMetadata'](name);
+    if (!association) {
+        throw new JoinAttemptedOnMissingAssociation_js_1.default({
+            dreamClass,
+            associationName: associationString,
+        });
+    }
+    return {
+        association,
+        alias,
+    };
+};