@rvoh/dream 0.44.7 → 0.44.9

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

@@ -0,0 +1,1768 @@
+import { sql, } from 'kysely';
+import pluralize from 'pluralize-esm';
+import DreamCLI from '../../cli/index.js';
+import _db from '../../db/index.js';
+import associationToGetterSetterProp from '../../decorators/field/association/associationToGetterSetterProp.js';
+import DreamApp from '../../dream-app/index.js';
+import CannotAssociateThroughPolymorphic from '../../errors/associations/CannotAssociateThroughPolymorphic.js';
+import CannotJoinPolymorphicBelongsToError from '../../errors/associations/CannotJoinPolymorphicBelongsToError.js';
+import JoinAttemptedOnMissingAssociation from '../../errors/associations/JoinAttemptedOnMissingAssociation.js';
+import MissingRequiredAssociationAndClause from '../../errors/associations/MissingRequiredAssociationAndClause.js';
+import MissingRequiredPassthroughForAssociationAndClause from '../../errors/associations/MissingRequiredPassthroughForAssociationAndClause.js';
+import MissingThroughAssociation from '../../errors/associations/MissingThroughAssociation.js';
+import MissingThroughAssociationSource from '../../errors/associations/MissingThroughAssociationSource.js';
+import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
+import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
+import UnexpectedUndefined from '../../errors/UnexpectedUndefined.js';
+import CalendarDate from '../../helpers/CalendarDate.js';
+import camelize from '../../helpers/camelize.js';
+import generateMigration from '../../helpers/cli/generateMigration.js';
+import compact from '../../helpers/compact.js';
+import { DateTime } from '../../helpers/DateTime.js';
+import loadPgClient from '../../helpers/db/loadPgClient.js';
+import runMigration from '../../helpers/db/runMigration.js';
+import EnvInternal from '../../helpers/EnvInternal.js';
+import isEmpty from '../../helpers/isEmpty.js';
+import isObject from '../../helpers/isObject.js';
+import namespaceColumn from '../../helpers/namespaceColumn.js';
+import normalizeUnicode from '../../helpers/normalizeUnicode.js';
+import objectPathsToArrays from '../../helpers/objectPathsToArrays.js';
+import protectAgainstPollutingAssignment from '../../helpers/protectAgainstPollutingAssignment.js';
+import { Range } from '../../helpers/range.js';
+import snakeify from '../../helpers/snakeify.js';
+import sqlAttributes from '../../helpers/sqlAttributes.js';
+import uniq from '../../helpers/uniq.js';
+import CurriedOpsStatement from '../../ops/curried-ops-statement.js';
+import OpsStatement from '../../ops/ops-statement.js';
+import { DreamConst } from '../constants.js';
+import executeDatabaseQuery from '../internal/executeDatabaseQuery.js';
+import extractAssociationMetadataFromAssociationName from '../internal/extractAssociationMetadataFromAssociationName.js';
+import orderByDirection from '../internal/orderByDirection.js';
+import shouldBypassDefaultScope from '../internal/shouldBypassDefaultScope.js';
+import SimilarityBuilder from '../internal/similarity/SimilarityBuilder.js';
+import sqlResultToDreamInstance from '../internal/sqlResultToDreamInstance.js';
+import Query from '../Query.js';
+import QueryDriverBase from './Base.js';
+import writeSyncFile from '../../bin/helpers/sync.js';
+import SchemaBuilder from '../../helpers/cli/SchemaBuilder.js';
+import createDb from '../../helpers/db/createDb.js';
+import _dropDb from '../../helpers/db/dropDb.js';
+export default class KyselyQueryDriver extends QueryDriverBase {
+    // ATTENTION FRED
+    // stop trying to make this async. You never learn...
+    //
+    // if you are attempting to leverage a kysely-based connection using a different driver,
+    // you would want to extend this KyselyQueryDriver class, and then change this method
+    // to return a custom kysely instance, tailored to the specific database connection
+    // you are attempting to support. By default, dream is postgres-only, so our internal _db
+    // function will return a kysely instance, tightly coupled to a postgres-specific connection.
+    dbFor(sqlCommandType) {
+        if (this.dreamTransaction?.kyselyTransaction)
+            return this.dreamTransaction?.kyselyTransaction;
+        return _db(this.dbConnectionType(sqlCommandType));
+    }
+    /**
+     * migrate the database. Must respond to the NODE_ENV value.
+     */
+    static async migrate() {
+        const dreamApp = DreamApp.getOrFail();
+        const primaryDbConf = dreamApp.dbConnectionConfig('primary');
+        DreamCLI.logger.logStartProgress(`migrating ${primaryDbConf.name}...`);
+        await runMigration({ mode: 'migrate' });
+        DreamCLI.logger.logEndProgress();
+        await this.duplicateDatabase();
+    }
+    /**
+     * rollback the database. Must respond to the NODE_ENV value.
+     */
+    static async rollback(opts) {
+        const dreamApp = DreamApp.getOrFail();
+        const primaryDbConf = dreamApp.dbConnectionConfig('primary');
+        DreamCLI.logger.logStartProgress(`rolling back ${primaryDbConf.name}...`);
+        let step = opts.steps;
+        while (step > 0) {
+            await runMigration({ mode: 'rollback' });
+            step -= 1;
+        }
+        DreamCLI.logger.logEndProgress();
+        await this.duplicateDatabase();
+    }
+    static async generateMigration(migrationName, columnsWithTypes) {
+        await generateMigration({ migrationName, columnsWithTypes });
+    }
+    static async sync(onSync) {
+        DreamCLI.logger.logStartProgress('writing db schema...');
+        await writeSyncFile();
+        DreamCLI.logger.logEndProgress();
+        DreamCLI.logger.logStartProgress('building dream schema...');
+        await new SchemaBuilder().build();
+        DreamCLI.logger.logEndProgress();
+        // intentionally leaving logs off here, since it allows other
+        // onSync handlers to determine their own independent logging approach
+        await onSync();
+    }
+    /**
+     * create the database. Must respond to the NODE_ENV value.
+     */
+    static async dbCreate() {
+        const dreamApp = DreamApp.getOrFail();
+        const primaryDbConf = dreamApp.dbConnectionConfig('primary');
+        DreamCLI.logger.logStartProgress(`creating ${primaryDbConf.name}...`);
+        await createDb('primary');
+        DreamCLI.logger.logEndProgress();
+        // TODO: add support for creating replicas. Began doing it below, but it is very tricky,
+        // and we don't need it at the moment, so kicking off for future development when we have more time
+        // to flesh this out.
+        // if (connectionRetriever.hasReplicaConfig()) {
+        //   const replicaDbConf = connectionRetriever.getConnectionConf('replica')
+        //   console.log(`creating ${process.env[replicaDbConf.name]}`)
+        //   await createDb('replica')
+        // }
+    }
+    /**
+     * delete the database. Must respond to the NODE_ENV value.
+     */
+    static async dbDrop() {
+        const dreamApp = DreamApp.getOrFail();
+        const primaryDbConf = dreamApp.dbConnectionConfig('primary');
+        DreamCLI.logger.logStartProgress(`dropping ${primaryDbConf.name}...`);
+        await _dropDb('primary');
+        DreamCLI.logger.logEndProgress();
+        // TODO: add support for dropping replicas. Began doing it below, but it is very tricky,
+        // and we don't need it at the moment, so kicking off for future development when we have more time
+        // to flesh this out.
+        // if (connectionRetriever.hasReplicaConfig()) {
+        //   const replicaDbConf = connectionRetriever.getConnectionConf('replica')
+        //   console.log(`dropping ${process.env[replicaDbConf.name]}`)
+        //   await _dropDb('replica')
+        // }
+    }
+    /**
+     * Converts the given dream class into a Kysely query, enabling
+     * you to build custom queries using the Kysely API
+     *
+     * ```ts
+     * await User.query().toKysely('select').where('email', '=', 'how@yadoin').execute()
+     * ```
+     *
+     * @param type - the type of Kysely query builder instance you would like to obtain
+     * @returns A Kysely query. Depending on the type passed, it will return either a SelectQueryBuilder, DeleteQueryBuilder, or an UpdateQueryBuilder
+     */
+    toKysely(type) {
+        switch (type) {
+            case 'select':
+                return this.buildSelect();
+            case 'delete':
+                return this.buildDelete();
+            case 'update':
+                return this.buildUpdate({});
+            // TODO: in the future, we should support insert type, but don't yet, since inserts are done outside
+            // the query class for some reason.
+            default: {
+                // protection so that if a new QueryType is ever added, this will throw a type error at build time
+                const _never = type;
+                throw new Error(`Unhandled QueryType: ${_never}`);
+            }
+        }
+    }
+    /**
+     * @internal
+     *
+     * This method is used internally by a Query driver to
+     * take the result of a single row in a database, and
+     * turn that row into the provided dream instance.
+     *
+     * If needed, the return type can be overriden to
+     * explicitly define the resulting dream instance,
+     * in cases where a proper type for the dream class
+     * cannot be inferred, i.e.
+     *
+     * ```ts
+     * this.dbResultToDreamInstance<typeof Dream, DreamInstance>(result, this.dreamClass)
+     * ```
+     */
+    dbResultToDreamInstance(result, dreamClass) {
+        return sqlResultToDreamInstance(dreamClass, result);
+    }
+    /**
+     * @internal
+     *
+     * Used for applying first and last queries
+     *
+     * @returns A dream instance or null
+     */
+    async takeOne() {
+        if (this.query['joinLoadActivated']) {
+            let query;
+            if (this.query['whereStatements'].find(whereStatement => whereStatement[this.dreamClass.primaryKey] ||
+                whereStatement[this.query['namespacedPrimaryKey']])) {
+                // the query already includes a primary key where statement
+                query = this.query;
+            }
+            else {
+                // otherwise find the primary key and apply it to the query
+                const primaryKeyValue = (await this.query.limit(1).pluck(this.query['namespacedPrimaryKey']))[0];
+                if (primaryKeyValue === undefined)
+                    return null;
+                query = this.query.where({ [this.query['namespacedPrimaryKey']]: primaryKeyValue });
+            }
+            const driverClass = this.constructor;
+            return (await new driverClass(query)['executeJoinLoad']())[0] || null;
+        }
+        const kyselyQuery = new KyselyQueryDriver(this.query.limit(1)).buildSelect();
+        const results = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirst');
+        if (results) {
+            const theFirst = this.dbResultToDreamInstance(results, this.dreamClass);
+            if (theFirst)
+                await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], [theFirst]);
+            return theFirst;
+        }
+        else
+            return null;
+    }
+    /**
+     * Retrieves an array containing all records matching the Query.
+     * Be careful using this, since it will attempt to pull every
+     * record into memory at once. When querying might return a large
+     * number of records, consider using `.findEach`, which will pull
+     * the records in batches.
+     *
+     * ```ts
+     * await User.query().all()
+     * ```
+     *
+     * @returns an array of dreams
+     */
+    async takeAll(options = {}) {
+        if (this.query['joinLoadActivated'])
+            return await this.executeJoinLoad(options);
+        const kyselyQuery = this.buildSelect(options);
+        const results = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const theAll = results.map(r => this.dbResultToDreamInstance(r, this.dreamClass));
+        await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], theAll);
+        return theAll;
+    }
+    /**
+     * Retrieves the max value of the specified column
+     * for this Query
+     *
+     * ```ts
+     * await User.query().max('id')
+     * // 99
+     * ```
+     *
+     * @param columnName - a column name on the model
+     * @returns the max value of the specified column for this Query
+     *
+     */
+    async max(columnName) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { max } = this.dbFor('select').fn;
+        let kyselyQuery = new KyselyQueryDriver(this.query).buildSelect({
+            bypassSelectAll: true,
+            bypassOrder: true,
+        });
+        kyselyQuery = kyselyQuery.select(max(columnName));
+        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        return data.max;
+    }
+    /**
+     * Retrieves the min value of the specified column
+     * for this Query
+     *
+     * ```ts
+     * await User.query().min('id')
+     * // 1
+     * ```
+     *
+     * @param columnName - a column name on the model
+     * @returns the min value of the specified column for this Query
+     */
+    async min(columnName) {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { min } = this.dbFor('select').fn;
+        let kyselyQuery = new KyselyQueryDriver(this.query).buildSelect({
+            bypassSelectAll: true,
+            bypassOrder: true,
+        });
+        kyselyQuery = kyselyQuery.select(min(columnName));
+        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        return data.min;
+    }
+    /**
+     * Retrieves the number of records in the database
+     *
+     * ```ts
+     * await User.query().count()
+     * ```
+     *
+     * @returns The number of records in the database
+     */
+    async count() {
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const { count } = this.dbFor('select').fn;
+        const distinctColumn = this.query['distinctColumn'];
+        const query = this.query.clone({ distinctColumn: null });
+        let kyselyQuery = new KyselyQueryDriver(query).buildSelect({ bypassSelectAll: true, bypassOrder: true });
+        const countClause = distinctColumn
+            ? count(sql `DISTINCT ${distinctColumn}`)
+            : count(query['namespaceColumn'](query.dreamInstance.primaryKey));
+        kyselyQuery = kyselyQuery.select(countClause.as('tablecount'));
+        const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
+        return parseInt(data.tablecount.toString());
+    }
+    /**
+     * @internal
+     *
+     * Runs the query and extracts plucked values
+     *
+     * @returns An array of plucked values
+     */
+    async pluck(...fields) {
+        let kyselyQuery = new KyselyQueryDriver(this.query['removeAllDefaultScopesExceptOnAssociations']()).buildSelect({
+            bypassSelectAll: true,
+        });
+        const aliases = [];
+        fields.forEach((field) => {
+            // field will already be namespaced in a join situation, but when the field to pluck is on the
+            // base model, it will be underscored (to match the table name), but when the selected column
+            // comes back from Kysely camelCased
+            aliases.push(field.includes('_') ? camelize(field) : field);
+            //  namespace the selection so that when plucking the same column name from
+            // multpile tables, they don't get saved as the same name (e.g. select results with two `id` columns,
+            // which the pg package then returns in an object with a single `id` key)
+            kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(field)} as ${field}`);
+        });
+        return (await executeDatabaseQuery(kyselyQuery, 'execute')).map(singleResult => aliases.map(alias => singleResult[alias]));
+    }
+    /**
+     * Returns a new Kysely SelectQueryBuilder instance to be used
+     * in a sub Query
+     *
+     * ```ts
+     * const records = await User.where({
+     *   id: Post.query().nestedSelect('userId'),
+     * }).all()
+     * // [User{id: 1}, ...]
+     * ```
+     *
+     * @param selection - the column to use for your nested Query
+     * @returns A Kysely SelectQueryBuilder instance
+     */
+    nestedSelect(selection) {
+        const query = this.buildSelect({
+            bypassSelectAll: true,
+            bypassOrder: true,
+        });
+        return query.select(this.namespaceColumn(selection));
+    }
+    /**
+     * executes provided query instance as a deletion query.
+     * @returns the number of deleted rows
+     */
+    async delete() {
+        const deletionResult = await executeDatabaseQuery(this.buildDelete(), 'executeTakeFirst');
+        return Number(deletionResult?.numDeletedRows || 0);
+    }
+    /**
+     * executes provided query instance as an update query.
+     * @returns the number of updated rows
+     */
+    async update(attributes) {
+        const kyselyQuery = this.buildUpdate(attributes);
+        const res = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const resultData = Array.from(res.entries())?.[0]?.[1];
+        return Number(resultData?.numUpdatedRows || 0);
+    }
+    /**
+     * persists any unsaved changes to the database. If a transaction
+     * is provided as a second argument, it will use that transaction
+     * to encapsulate the persisting of the dream, as well as any
+     * subsequent model hooks that are fired.
+     */
+    static async saveDream(dream, txn = null) {
+        const db = txn?.kyselyTransaction ?? _db('primary');
+        const sqlifiedAttributes = sqlAttributes(dream);
+        if (dream.isPersisted) {
+            const query = db
+                .updateTable(dream.table)
+                .set(sqlifiedAttributes)
+                .where(namespaceColumn(dream.primaryKey, dream.table), '=', dream.primaryKeyValue);
+            return await executeDatabaseQuery(query.returning([...dream.columns()]), 'executeTakeFirstOrThrow');
+        }
+        else {
+            const query = db
+                .insertInto(dream.table)
+                .values(sqlifiedAttributes)
+                .returning([...dream.columns()]);
+            return await executeDatabaseQuery(query, 'executeTakeFirstOrThrow');
+        }
+    }
+    dbConnectionType(sqlCommandType) {
+        if (this.dreamTransaction)
+            return 'primary';
+        switch (sqlCommandType) {
+            case 'select':
+                return this.connectionOverride || (this.isReplicaSafe() ? 'replica' : 'primary');
+            default:
+                return 'primary';
+        }
+    }
+    isReplicaSafe() {
+        return this.innerJoinDreamClasses.reduce((accumulator, dreamClass) => accumulator && dreamClass['replicaSafe'], this.dreamClass['replicaSafe']);
+    }
+    /**
+     * Returns the sql that would be executed by this Query
+     *
+     * ```ts
+     * User.where({ email: 'how@yadoin' }).sql()
+     * // {
+     * //  query: {
+     * //    kind: 'SelectQueryNode',
+     * //    from: { kind: 'FromNode', froms: [Array] },
+     * //    selections: [ [Object] ],
+     * //    distinctOn: undefined,
+     * //    joins: undefined,
+     * //    groupBy: undefined,
+     * //    orderBy: undefined,
+     * //    where: { kind: 'WhereNode', where: [Object] },
+     * //    frontModifiers: undefined,
+     * //    endModifiers: undefined,
+     * //    limit: undefined,
+     * //    offset: undefined,
+     * //    with: undefined,
+     * //    having: undefined,
+     * //    explain: undefined,
+     * //    setOperations: undefined
+     * //  },
+     * //  sql: 'select "users".* from "users" where ("users"."email" = $1 and "users"."deleted_at" is null)',
+     * //  parameters: [ 'how@yadoin' ]
+     * //}
+     * ```
+     *
+     * @returns An object representing the underlying sql statement
+     *
+     */
+    sql() {
+        const kyselyQuery = this.buildSelect();
+        return kyselyQuery.compile();
+    }
+    buildDelete() {
+        const kyselyQuery = this.dbFor('delete').deleteFrom(this.query['baseSqlAlias']);
+        const results = this.attachLimitAndOrderStatementsToNonSelectQuery(kyselyQuery);
+        return new KyselyQueryDriver(results.clone).buildCommon(results.kyselyQuery);
+    }
+    buildSelect({ bypassSelectAll = false, bypassOrder = false, columns, } = {}) {
+        let kyselyQuery;
+        if (this.query['baseSelectQuery']) {
+            const connectionOverride = this.query['connectionOverride'];
+            const query = connectionOverride
+                ? this.query['baseSelectQuery'].connection(connectionOverride)
+                : this.query['baseSelectQuery'];
+            kyselyQuery = new KyselyQueryDriver(query).buildSelect({ bypassSelectAll: true });
+        }
+        else {
+            const from = this.query['baseSqlAlias'] === this.query['tableName']
+                ? this.query['tableName']
+                : `${this.query['tableName']} as ${this.query['baseSqlAlias']}`;
+            kyselyQuery = this.dbFor('select').selectFrom(from);
+        }
+        if (this.query['distinctColumn']) {
+            kyselyQuery = kyselyQuery.distinctOn(this.query['distinctColumn']);
+        }
+        kyselyQuery = this.buildCommon(kyselyQuery);
+        kyselyQuery = this.conditionallyAttachSimilarityColumnsToSelect(kyselyQuery, {
+            bypassOrder: bypassOrder || !!this.query['distinctColumn'],
+        });
+        if (this.query['orderStatements'].length && !bypassOrder) {
+            this.query['orderStatements'].forEach(orderStatement => {
+                kyselyQuery = kyselyQuery.orderBy(this.namespaceColumn(orderStatement.column), orderByDirection(orderStatement.direction));
+            });
+        }
+        if (this.query['limitStatement'])
+            kyselyQuery = kyselyQuery.limit(this.query['limitStatement']);
+        if (this.query['offsetStatement'])
+            kyselyQuery = kyselyQuery.offset(this.query['offsetStatement']);
+        if (columns) {
+            kyselyQuery = kyselyQuery.select(this.columnsWithRequiredLoadColumns(columns).map(column => this.namespaceColumn(column)));
+        }
+        else if (!bypassSelectAll) {
+            kyselyQuery = kyselyQuery.selectAll(this.query['baseSqlAlias']);
+        }
+        // even though we manually bypass explicit order statements above,
+        // associations can contain their own ordering systems. If we do not
+        // escape all orders, we can mistakenly allow an order clause to sneak in.
+        if (bypassOrder)
+            kyselyQuery = kyselyQuery.clearOrderBy();
+        return kyselyQuery;
+    }
+    buildUpdate(attributes) {
+        let kyselyQuery = this.dbFor('update')
+            .updateTable(this.query['tableName'])
+            .set(attributes);
+        kyselyQuery = this.conditionallyAttachSimilarityColumnsToUpdate(kyselyQuery);
+        const results = this.attachLimitAndOrderStatementsToNonSelectQuery(kyselyQuery);
+        return new KyselyQueryDriver(results.clone).buildCommon(results.kyselyQuery);
+    }
+    /**
+     * @internal
+     *
+     * Used to hydrate dreams with the provided associations
+     */
+    hydrateAssociation(dreams, association, preloadedDreamsAndWhatTheyPointTo) {
+        switch (association.type) {
+            case 'HasMany':
+                dreams.forEach((dream) => {
+                    dream[association.as] = [];
+                });
+                break;
+            default:
+                dreams.forEach((dream) => {
+                    dream[associationToGetterSetterProp(association)] = null;
+                });
+        }
+        // dreams is a Rating
+        // Rating belongs to: rateables (Posts / Compositions)
+        // loadedAssociations is an array of Posts and Compositions
+        // if rating.rateable_id === loadedAssociation.primaryKeyvalue
+        //  rating.rateable = loadedAssociation
+        preloadedDreamsAndWhatTheyPointTo.forEach(preloadedDreamAndWhatItPointsTo => {
+            dreams
+                .filter(dream => dream.primaryKeyValue === preloadedDreamAndWhatItPointsTo.pointsToPrimaryKey)
+                .forEach((dream) => {
+                if (association.type === 'HasMany') {
+                    dream[association.as].push(preloadedDreamAndWhatItPointsTo.dream);
+                }
+                else {
+                    // in a HasOne context, order clauses will be applied in advance,
+                    // prior to hydration. Considering, we only want to set the first
+                    // result and ignore other results, so we will use ||= to set.
+                    dream[association.as] ||= preloadedDreamAndWhatItPointsTo.dream;
+                }
+            });
+        });
+        if (association.type === 'HasMany') {
+            dreams.forEach((dream) => Object.freeze(dream[association.as]));
+        }
+    }
+    /**
+     * @internal
+     *
+     * Used by loadBuider
+     */
+    async hydratePreload(dream) {
+        await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], dream);
+    }
+    static async duplicateDatabase() {
+        const dreamApp = DreamApp.getOrFail();
+        const parallelTests = dreamApp.parallelTests;
+        if (!parallelTests)
+            return;
+        DreamCLI.logger.logStartProgress(`duplicating db for parallel tests...`);
+        const dbConf = dreamApp.dbConnectionConfig('primary');
+        const client = await loadPgClient({ useSystemDb: true });
+        if (EnvInternal.boolean('DREAM_CORE_DEVELOPMENT')) {
+            const replicaTestWorkerDatabaseName = `replica_test_${dbConf.name}`;
+            DreamCLI.logger.logContinueProgress(`creating fake replica test database ${replicaTestWorkerDatabaseName}...`, { logPrefix: '  ├ [db]', logPrefixColor: 'cyan' });
+            await client.query(`DROP DATABASE IF EXISTS ${replicaTestWorkerDatabaseName};`);
+            await client.query(`CREATE DATABASE ${replicaTestWorkerDatabaseName} TEMPLATE ${dbConf.name};`);
+        }
+        for (let i = 2; i <= parallelTests; i++) {
+            const workerDatabaseName = `${dbConf.name}_${i}`;
+            DreamCLI.logger.logContinueProgress(`creating duplicate test database ${workerDatabaseName} for concurrent tests...`, { logPrefix: '  ├ [db]', logPrefixColor: 'cyan' });
+            await client.query(`DROP DATABASE IF EXISTS ${workerDatabaseName};`);
+            await client.query(`CREATE DATABASE ${workerDatabaseName} TEMPLATE ${dbConf.name};`);
+        }
+        await client.end();
+        DreamCLI.logger.logEndProgress();
+    }
+    aliasWhereStatements(whereStatements, alias) {
+        return whereStatements.map(whereStatement => this.aliasWhereStatement(whereStatement, alias));
+    }
+    aliasWhereStatement(whereStatement, alias) {
+        return Object.keys(whereStatement).reduce((aliasedWhere, key) => {
+            aliasedWhere[this.namespaceColumn(key, alias)] = whereStatement[key];
+            return aliasedWhere;
+        }, {});
+    }
+    rawifiedSelfOnClause({ associationAlias, selfAlias, selfAndClause, }) {
+        const alphanumericUnderscoreRegexp = /[^a-zA-Z0-9_]/g;
+        selfAlias = selfAlias.replace(alphanumericUnderscoreRegexp, '');
+        return Object.keys(selfAndClause).reduce((acc, key) => {
+            const selfColumn = selfAndClause[key]?.replace(alphanumericUnderscoreRegexp, '');
+            if (!selfColumn)
+                return acc;
+            acc[this.namespaceColumn(key, associationAlias)] = sql.raw(`"${snakeify(selfAlias)}"."${snakeify(selfColumn)}"`);
+            return acc;
+        }, {});
+    }
+    attachLimitAndOrderStatementsToNonSelectQuery(kyselyQuery) {
+        if (this.query['limitStatement'] || this.query['orderStatements'].length) {
+            kyselyQuery = kyselyQuery.where((eb) => {
+                const subquery = this.query.nestedSelect(this.dreamInstance.primaryKey);
+                return eb(this.dreamInstance.primaryKey, 'in', subquery);
+            });
+            return {
+                kyselyQuery,
+                clone: this.query.clone({
+                    where: null,
+                    whereNot: null,
+                    order: null,
+                    limit: null,
+                }),
+            };
+        }
+        return { kyselyQuery, clone: this.query };
+    }
+    columnsWithRequiredLoadColumns(columns) {
+        return uniq(compact([this.dreamClass.primaryKey, this.dreamClass['isSTIBase'] ? 'type' : null, ...columns]));
+    }
+    /**
+     * @internal
+     *
+     */
+    async executeJoinLoad(options = {}) {
+        const query = this.query['limit'](null).offset(null);
+        let kyselyQuery = new KyselyQueryDriver(query).buildSelect({ bypassSelectAll: true });
+        const aliasToDreamClassesMap = {
+            [this.query['baseSqlAlias']]: this.dreamClass,
+            ...this.joinStatementsToDreamClassesMap(this.query['leftJoinStatements']),
+        };
+        const associationAliasToColumnAliasMap = {};
+        const aliasToAssociationsMap = this.joinStatementsToAssociationsMap(this.query['leftJoinStatements']);
+        const aliases = Object.keys(aliasToDreamClassesMap);
+        let nextColumnAliasCounter = 0;
+        aliases.forEach((aliasOrExpression) => {
+            const alias = extractAssociationMetadataFromAssociationName(aliasOrExpression).alias;
+            if (alias === undefined)
+                throw new UnexpectedUndefined();
+            associationAliasToColumnAliasMap[alias] ||= {};
+            const aliasedDreamClass = aliasToDreamClassesMap[alias];
+            if (aliasedDreamClass === undefined)
+                throw new UnexpectedUndefined();
+            const association = aliasToAssociationsMap[alias];
+            const columns = alias === this.query['baseSqlAlias']
+                ? options.columns
+                    ? this.columnsWithRequiredLoadColumns(options.columns)
+                    : this.dreamClass.columns()
+                : aliasedDreamClass.columns();
+            columns.forEach((column) => {
+                const columnAlias = `dr${nextColumnAliasCounter++}`;
+                kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(column, alias)} as ${columnAlias}`);
+                const columnAliasMap = associationAliasToColumnAliasMap[alias];
+                if (columnAliasMap === undefined)
+                    throw new UnexpectedUndefined();
+                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();
+                    columnAliasMap[dbColumnName] = columnAlias;
+                    kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(dbColumnName, association.through)} as ${columnAlias}`);
+                };
+                if (association.through && association.preloadThroughColumns) {
+                    if (isObject(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 executeDatabaseQuery(kyselyQuery, 'execute');
+        const aliasToDreamIdMap = queryResults.reduce((aliasToDreamIdMap, singleSqlResult) => {
+            this.fleshOutJoinLoadExecutionResults({
+                currentAlias: this.query['baseSqlAlias'],
+                singleSqlResult,
+                aliasToDreamIdMap,
+                associationAliasToColumnAliasMap,
+                aliasToAssociationsMap,
+                aliasToDreamClassesMap,
+                leftJoinStatements: this.query['leftJoinStatements'],
+            });
+            return aliasToDreamIdMap;
+        }, {});
+        const baseModelIdToDreamMap = aliasToDreamIdMap[this.query['baseSqlAlias']] || new Map();
+        return compact(Array.from(baseModelIdToDreamMap.values()));
+    }
+    fleshOutJoinLoadExecutionResults({ currentAlias, singleSqlResult, aliasToDreamIdMap, associationAliasToColumnAliasMap, aliasToAssociationsMap, aliasToDreamClassesMap, leftJoinStatements, }) {
+        const dreamClass = aliasToDreamClassesMap[currentAlias];
+        if (dreamClass === undefined)
+            throw new UnexpectedUndefined();
+        const columnToColumnAliasMap = associationAliasToColumnAliasMap[currentAlias];
+        if (columnToColumnAliasMap === undefined)
+            throw new UnexpectedUndefined();
+        const primaryKeyName = dreamClass.primaryKey;
+        if (primaryKeyName === undefined)
+            throw new UnexpectedUndefined();
+        const columnAlias = columnToColumnAliasMap[primaryKeyName];
+        if (columnAlias === undefined)
+            throw new UnexpectedUndefined();
+        const primaryKeyValue = singleSqlResult[columnAlias];
+        if (!primaryKeyValue)
+            return null;
+        aliasToDreamIdMap[currentAlias] ||= new Map();
+        if (!aliasToDreamIdMap[currentAlias].get(primaryKeyValue)) {
+            const columnValueMap = Object.keys(columnToColumnAliasMap).reduce((columnNameValueMap, columnName) => {
+                const columnAlias = columnToColumnAliasMap[columnName];
+                if (columnAlias === undefined)
+                    throw new UnexpectedUndefined();
+                columnNameValueMap[columnName] = singleSqlResult[columnAlias];
+                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();
+                this.hydratePreloadedThroughColumns({
+                    association,
+                    columnToColumnAliasMap: throughAssociationColumnToColumnAliasMap,
+                    dream,
+                    singleSqlResult,
+                });
+            }
+            aliasToDreamIdMap[protectAgainstPollutingAssignment(currentAlias)]?.set(primaryKeyValue, dream);
+        }
+        const dream = aliasToDreamIdMap[currentAlias].get(primaryKeyValue);
+        Object.keys(leftJoinStatements).forEach(nextAlias => {
+            const { name: associationName, alias } = extractAssociationMetadataFromAssociationName(nextAlias);
+            const association = dreamClass['getAssociationMetadata'](associationName);
+            if (association === undefined)
+                throw new UnexpectedUndefined();
+            const associatedDream = this.fleshOutJoinLoadExecutionResults({
+                currentAlias: alias,
+                singleSqlResult,
+                aliasToDreamIdMap,
+                associationAliasToColumnAliasMap,
+                aliasToAssociationsMap,
+                aliasToDreamClassesMap,
+                leftJoinStatements: leftJoinStatements[nextAlias],
+            });
+            const hasMany = association.type === 'HasMany';
+            // initialize by trying to access the association, which throws an exception if not yet initialized
+            try {
+                ;
+                dream[association.as];
+            }
+            catch {
+                if (hasMany)
+                    dream[association.as] = [];
+                else
+                    dream[associationToGetterSetterProp(association)] = null;
+            }
+            if (!associatedDream)
+                return;
+            if (hasMany) {
+                if (!dream[association.as].includes(associatedDream))
+                    dream[association.as].push(associatedDream);
+            }
+            else
+                dream[associationToGetterSetterProp(association)] = associatedDream;
+        });
+        return dream;
+    }
+    hydratePreloadedThroughColumns({ association, columnToColumnAliasMap, dream, singleSqlResult, }) {
+        if (!association.through)
+            return;
+        if (!dream.preloadedThroughColumns)
+            return;
+        let columnNames = [];
+        const columnNameToPreloadedThroughColumnNameMap = {};
+        if (isObject(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();
+            const columnAlias = columnToColumnAliasMap[columnName];
+            if (columnAlias === undefined) {
+                throw new UnexpectedUndefined();
+            }
+            ;
+            dream.preloadedThroughColumns[preloadedThroughColumnName] = singleSqlResult[columnAlias];
+        });
+    }
+    applyJoinAndStatement(join, joinAndStatement, rootTableOrAssociationAlias) {
+        if (!joinAndStatement)
+            return join;
+        join = this._applyJoinAndStatements(join, joinAndStatement.and, rootTableOrAssociationAlias);
+        join = this._applyJoinAndStatements(join, joinAndStatement.andNot, rootTableOrAssociationAlias, {
+            negate: true,
+        });
+        join = this._applyJoinAndAnyStatements(join, joinAndStatement.andAny, rootTableOrAssociationAlias);
+        return join;
+    }
+    _applyJoinAndStatements(join, joinAndStatement, rootTableOrAssociationAlias, { negate = false, } = {}) {
+        if (!joinAndStatement)
+            return join;
+        return join.on((eb) => this.joinAndStatementToExpressionWrapper(joinAndStatement, rootTableOrAssociationAlias, eb, {
+            negate,
+            disallowSimilarityOperator: negate,
+        }));
+    }
+    _applyJoinAndAnyStatements(join, joinAndAnyStatement, rootTableOrAssociationAlias) {
+        if (!joinAndAnyStatement)
+            return join;
+        if (!joinAndAnyStatement.length)
+            return join;
+        return join.on((eb) => {
+            return eb.or(joinAndAnyStatement.map(joinAndStatement => this.joinAndStatementToExpressionWrapper(joinAndStatement, rootTableOrAssociationAlias, eb)));
+        });
+    }
+    joinAndStatementToExpressionWrapper(joinAndStatement, rootTableOrAssociationAlias, eb, { negate = false, disallowSimilarityOperator = true, } = {}) {
+        return this.whereStatementToExpressionWrapper(eb, Object.keys(joinAndStatement).reduce((agg, key) => {
+            agg[this.namespaceColumn(key.toString(), rootTableOrAssociationAlias)] = joinAndStatement[key];
+            return agg;
+        }, {}), {
+            negate,
+            disallowSimilarityOperator,
+        });
+    }
+    buildCommon(kyselyQuery) {
+        this.checkForQueryViolations();
+        const query = this.conditionallyApplyDefaultScopes();
+        if (!isEmpty(query['innerJoinStatements'])) {
+            kyselyQuery = this.recursivelyJoin({
+                query: kyselyQuery,
+                joinStatement: query['innerJoinStatements'],
+                joinAndStatements: query['innerJoinAndStatements'],
+                dreamClass: query['dreamClass'],
+                previousAssociationTableOrAlias: this.query['baseSqlAlias'],
+                joinType: 'inner',
+            });
+        }
+        if (!isEmpty(query['leftJoinStatements'])) {
+            kyselyQuery = this.recursivelyJoin({
+                query: kyselyQuery,
+                joinStatement: query['leftJoinStatements'],
+                joinAndStatements: query['leftJoinAndStatements'],
+                dreamClass: query['dreamClass'],
+                previousAssociationTableOrAlias: this.query['baseSqlAlias'],
+                joinType: 'left',
+            });
+        }
+        if (query['whereStatements'].length ||
+            query['whereNotStatements'].length ||
+            query['whereAnyStatements'].length) {
+            kyselyQuery = kyselyQuery.where((eb) => eb.and([
+                ...this.aliasWhereStatements(query['whereStatements'], query['baseSqlAlias']).map(whereStatement => this.whereStatementToExpressionWrapper(eb, whereStatement, {
+                    disallowSimilarityOperator: false,
+                })),
+                ...this.aliasWhereStatements(query['whereNotStatements'], query['baseSqlAlias']).map(whereNotStatement => this.whereStatementToExpressionWrapper(eb, whereNotStatement, { negate: true })),
+                ...query['whereAnyStatements'].map(whereAnyStatements => eb.or(this.aliasWhereStatements(whereAnyStatements, query['baseSqlAlias']).map(whereAnyStatement => this.whereStatementToExpressionWrapper(eb, whereAnyStatement)))),
+            ]));
+        }
+        return kyselyQuery;
+    }
+    whereStatementToExpressionWrapper(eb, whereStatement, { negate = false, disallowSimilarityOperator = true, } = {}) {
+        const clauses = compact(Object.keys(whereStatement)
+            .filter(key => whereStatement[key] !== DreamConst.required)
+            .map(attr => {
+            const val = whereStatement[attr];
+            if (val?.isOpsStatement &&
+                val.shouldBypassWhereStatement) {
+                if (disallowSimilarityOperator)
+                    throw new Error('Similarity operator may not be used in whereAny');
+                // some ops statements are handled specifically in the select portion of the query,
+                // and should be ommited from the where clause directly
+                return;
+            }
+            const { a, b, c, a2, b2, c2 } = this.dreamWhereStatementToExpressionBuilderParts(attr, val);
+            // postgres is unable to handle WHERE IN statements with blank arrays, such as in
+            // "WHERE id IN ()", meaning that:
+            // 1. If we receive a blank array during an IN comparison,
+            //    then we need to simply regurgitate a where statement which
+            //    guarantees no records.
+            // 2. If we receive a blank array during a NOT IN comparison,
+            //    then it is the same as the where statement not being present at all,
+            //    resulting in a noop on our end
+            //
+            if (Array.isArray(c)) {
+                if ((b === 'in' && c.includes(null)) || (b === 'not in' && !c.includes(null))) {
+                    return this.inArrayWithNull_or_notInArrayWithoutNull_ExpressionBuilder(eb, a, b, c);
+                }
+                else if (negate && b === 'in' && !c.includes(null)) {
+                    return this.inArrayWithoutNullExpressionBuilder(eb, a, b, c);
+                }
+                else if (b === 'not in' && c.includes(null)) {
+                    return this.notInArrayWithNullExpressionBuilder(eb, a, b, c);
+                }
+                const compactedC = compact(c);
+                if (b === 'in' && compactedC.length === 0) {
+                    // in an empty array means match nothing
+                    return sql `FALSE`;
+                }
+                else if (b === 'not in' && compactedC.length === 0) {
+                    // not in an empty array means match everything
+                    return sql `TRUE`;
+                }
+                else {
+                    return eb(a, b, compactedC);
+                }
+                //
+            }
+            else if (b === '=' && c === null) {
+                return eb(a, 'is', null);
+                //
+            }
+            else if (b === '!=' && c === null) {
+                return eb(a, 'is not', null);
+                //
+            }
+            else if (b === '=' && negate) {
+                return eb.and([eb(a, '=', c), eb(a, 'is not', null)]);
+                //
+            }
+            else if (b === '!=' && c !== null) {
+                return eb.or([eb(a, '!=', c), eb(a, 'is', null)]);
+                //
+            }
+            else {
+                const expression = eb(a, b, c);
+                if (b2)
+                    return expression.and(eb(a2, b2, c2));
+                return expression;
+            }
+        }));
+        return negate ? eb.not(eb.parens(eb.and(clauses))) : eb.and(clauses);
+    }
+    inArrayWithNull_or_notInArrayWithoutNull_ExpressionBuilder(eb, a, b, c) {
+        const isNullStatement = eb(a, 'is', null);
+        const compactedC = compact(c);
+        if (compactedC.length)
+            return eb.or([eb(a, b, compactedC), isNullStatement]);
+        // not in an empty array means match everything
+        if (b === 'not in')
+            return sql `TRUE`;
+        return isNullStatement;
+    }
+    inArrayWithoutNullExpressionBuilder(eb, a, b, c) {
+        const isNotNullStatement = eb(a, 'is not', null);
+        const compactedC = compact(c);
+        if (compactedC.length)
+            return eb.and([eb(a, 'in', compactedC), isNotNullStatement]);
+        // in an empty array means match nothing
+        return sql `FALSE`;
+    }
+    notInArrayWithNullExpressionBuilder(eb, a, b, c) {
+        const isNullStatement = eb(a, 'is not', null);
+        const compactedC = compact(c);
+        if (compactedC.length)
+            return eb.and([eb(a, 'not in', compactedC), isNullStatement]);
+        return isNullStatement;
+    }
+    dreamWhereStatementToExpressionBuilderParts(attr, val) {
+        let a;
+        let b;
+        let c;
+        let a2 = null;
+        let b2 = null;
+        let c2 = null;
+        if (val instanceof Function && val !== DreamConst.passthrough) {
+            val = val();
+        }
+        else if (val === DreamConst.passthrough) {
+            const column = attr.split('.').at(-1);
+            if (this.query['passthroughOnStatement'][column] === undefined)
+                throw new MissingRequiredPassthroughForAssociationAndClause(column);
+            val = this.query['passthroughOnStatement'][column];
+        }
+        if (val === null) {
+            a = attr;
+            b = 'is';
+            c = val;
+        }
+        else if (['SelectQueryBuilder', 'SelectQueryBuilderImpl'].includes(val?.constructor?.name)) {
+            a = attr;
+            b = 'in';
+            c = val;
+        }
+        else if (Array.isArray(val)) {
+            a = attr;
+            b = 'in';
+            c = val.map(v => v instanceof DateTime || v instanceof CalendarDate
+                ? v.toSQL()
+                : typeof v === 'string'
+                    ? normalizeUnicode(v)
+                    : v);
+        }
+        else if (val instanceof CurriedOpsStatement) {
+            val = val.toOpsStatement(this.dreamClass, attr);
+            a = attr;
+            b = val.operator;
+            c = val.value;
+        }
+        else if (val instanceof OpsStatement) {
+            a = attr;
+            b = val.operator;
+            c = val.value;
+        }
+        else if (val instanceof Range) {
+            const rangeStart = val.begin;
+            const rangeEnd = val.end;
+            const excludeEnd = val.excludeEnd;
+            if (rangeStart && rangeEnd) {
+                a = attr;
+                b = '>=';
+                c = rangeStart;
+                a2 = attr;
+                b2 = excludeEnd ? '<' : '<=';
+                c2 = rangeEnd;
+            }
+            else if (rangeStart) {
+                a = attr;
+                b = '>=';
+                c = rangeStart;
+            }
+            else {
+                a = attr;
+                b = excludeEnd ? '<' : '<=';
+                c = rangeEnd;
+            }
+        }
+        else {
+            a = attr;
+            b = '=';
+            c = val;
+        }
+        if (c instanceof DateTime || c instanceof CalendarDate)
+            c = c.toSQL();
+        else if (typeof c === 'string')
+            c = normalizeUnicode(c);
+        if (c2 instanceof DateTime || c2 instanceof CalendarDate)
+            c2 = c2.toSQL();
+        else if (typeof c2 === 'string')
+            c2 = normalizeUnicode(c2);
+        if (a && c === undefined)
+            throw new CannotPassUndefinedAsAValueToAWhereClause(this.dreamClass, a);
+        if (a2 && c2 === undefined)
+            throw new CannotPassUndefinedAsAValueToAWhereClause(this.dreamClass, a2);
+        return { a, b, c, a2, b2, c2 };
+    }
+    recursivelyJoin({ query, joinStatement, joinAndStatements, dreamClass, previousAssociationTableOrAlias, joinType, }) {
+        for (const currentAssociationTableOrAlias of Object.keys(joinStatement)) {
+            const results = this.applyOneJoin({
+                query,
+                dreamClass,
+                previousAssociationTableOrAlias,
+                currentAssociationTableOrAlias,
+                joinAndStatements,
+                joinType,
+            });
+            query = results.query;
+            const association = results.association;
+            query = this.recursivelyJoin({
+                query,
+                joinStatement: joinStatement[currentAssociationTableOrAlias],
+                joinAndStatements: joinAndStatements[currentAssociationTableOrAlias],
+                dreamClass: association.modelCB(),
+                previousAssociationTableOrAlias: currentAssociationTableOrAlias,
+                joinType,
+            });
+        }
+        return query;
+    }
+    /**
+     * @internal
+     *
+     *
+     */
+    joinStatementsToDreamClassesMap(joinStatements) {
+        const associationsToDreamClassesMap = {};
+        objectPathsToArrays(joinStatements).forEach(associationChain => this.associationNamesToDreamClassesMap(associationChain, associationsToDreamClassesMap));
+        return associationsToDreamClassesMap;
+    }
+    /**
+     * @internal
+     *
+     *
+     */
+    joinStatementsToAssociationsMap(joinStatements) {
+        const associationsToAssociationsMap = {};
+        objectPathsToArrays(joinStatements).forEach(associationChain => this.associationNamesToAssociationsMap(associationChain, associationsToAssociationsMap));
+        return associationsToAssociationsMap;
+    }
+    /**
+     * @internal
+     *
+     *
+     */
+    associationNamesToDreamClassesMap(associationNames, associationsToDreamClassesMap = {}) {
+        const namesToAssociationsAndDreamClasses = this.associationNamesToAssociationDataAndDreamClassesMap(associationNames);
+        return Object.keys(namesToAssociationsAndDreamClasses).reduce((remap, associationName) => {
+            const associationAndDreamClass = namesToAssociationsAndDreamClasses[associationName];
+            if (associationAndDreamClass === undefined)
+                throw new UnexpectedUndefined();
+            remap[associationName] = associationAndDreamClass.dreamClass;
+            return remap;
+        }, associationsToDreamClassesMap);
+    }
+    /**
+     * @internal
+     *
+     *
+     */
+    associationNamesToAssociationsMap(associationNames, associationsToAssociations = {}) {
+        const namesToAssociationsAndDreamClasses = this.associationNamesToAssociationDataAndDreamClassesMap(associationNames);
+        return Object.keys(namesToAssociationsAndDreamClasses).reduce((remap, associationName) => {
+            const associationAndDreamClass = namesToAssociationsAndDreamClasses[associationName];
+            if (associationAndDreamClass === undefined)
+                throw new UnexpectedUndefined();
+            remap[associationName] = associationAndDreamClass.association;
+            return remap;
+        }, associationsToAssociations);
+    }
+    /**
+     * @internal
+     */
+    associationNamesToAssociationDataAndDreamClassesMap(associationNames) {
+        const associationsToDreamClassesMap = {};
+        associationNames.reduce((dreamClass, associationName) => {
+            const { name, alias } = extractAssociationMetadataFromAssociationName(associationName);
+            const association = dreamClass['getAssociationMetadata'](name);
+            if (association === undefined)
+                throw new UnexpectedUndefined();
+            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();
+            associationsToDreamClassesMap[alias] = { association, dreamClass: nextDreamClass };
+            return nextDreamClass;
+        }, this.dreamClass);
+        return associationsToDreamClassesMap;
+    }
+    /**
+     * @internal
+     */
+    throughAssociationDetails(dreamClass, through) {
+        const throughAssociation = dreamClass['getAssociationMetadata'](through);
+        if (throughAssociation === undefined)
+            throw new UnexpectedUndefined();
+        const throughAssociationDreamClass = throughAssociation.modelCB();
+        return { throughAssociation, throughAssociationDreamClass };
+    }
+    /**
+     * @internal
+     *
+     * Returns a namespaced column name
+     *
+     * @returns A string
+     */
+    namespaceColumn(column, alias = this.query['baseSqlAlias']) {
+        return namespaceColumn(column, alias);
+    }
+    checkForQueryViolations() {
+        const invalidWhereNotClauses = this.similarityStatementBuilder().whereNotStatementsWithSimilarityClauses();
+        if (invalidWhereNotClauses.length) {
+            const invalidWhereNotClause = invalidWhereNotClauses[0];
+            if (invalidWhereNotClause === undefined)
+                throw new UnexpectedUndefined();
+            const { tableName, columnName, opsStatement } = invalidWhereNotClause;
+            throw new CannotNegateSimilarityClause(tableName, columnName, opsStatement.value);
+        }
+    }
+    similarityStatementBuilder() {
+        return new SimilarityBuilder(this.dreamInstance, {
+            where: [...this.query['whereStatements']],
+            whereNot: [...this.query['whereNotStatements']],
+            joinAndStatements: this.query['innerJoinAndStatements'],
+            transaction: this.query['dreamTransaction'],
+            connection: this.query['connectionOverride'],
+        });
+    }
+    /**
+     * @internal
+     *
+     * Applies a preload statement
+     */
+    async applyPreload(preloadStatement, preloadOnStatements, dream) {
+        const keys = Object.keys(preloadStatement);
+        for (const key of keys) {
+            const nestedDreams = await this.applyOnePreload(key, dream, this.applyablePreloadOnStatements(preloadOnStatements[key]));
+            if (nestedDreams) {
+                await this.applyPreload(preloadStatement[key], preloadOnStatements[key], nestedDreams);
+            }
+        }
+    }
+    /**
+     * @internal
+     *
+     * retrieves on statements that can be applied to a preload
+     */
+    applyablePreloadOnStatements(preloadOnStatements) {
+        if (preloadOnStatements === undefined)
+            return undefined;
+        return Object.keys(preloadOnStatements).reduce((agg, key) => {
+            const value = preloadOnStatements[key];
+            if (value === undefined)
+                throw new UnexpectedUndefined();
+            // filter out plain objects, but not ops and not and/andNot/andAny statements
+            // because plain objects are just the next level of nested preload
+            if (key === 'and' ||
+                key === 'andNot' ||
+                key === 'andAny' ||
+                value === null ||
+                value.constructor !== Object) {
+                agg[key] = value;
+            }
+            return agg;
+        }, {});
+    }
+    conditionallyApplyDefaultScopes() {
+        if (this.query['bypassAllDefaultScopes'] || this.query['bypassAllDefaultScopesExceptOnAssociations'])
+            return this.query;
+        const thisScopes = this.dreamClass['scopes'].default;
+        let query = this.query;
+        for (const scope of thisScopes) {
+            if (!shouldBypassDefaultScope(scope.method, {
+                defaultScopesToBypass: [
+                    ...this.query['defaultScopesToBypass'],
+                    ...this.query['defaultScopesToBypassExceptOnAssociations'],
+                ],
+            })) {
+                query = this.dreamClass[scope.method](query);
+            }
+        }
+        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.
+     */
+    joinsBridgeThroughAssociations({ query, dreamClass, association, previousAssociationTableOrAlias, throughAssociations, joinType, }) {
+        if (association.type === 'BelongsTo' || !association.through) {
+            return {
+                query,
+                dreamClass,
+                association,
+                previousAssociationTableOrAlias,
+            };
+        }
+        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({
+                query,
+                dreamClass,
+                previousAssociationTableOrAlias,
+                currentAssociationTableOrAlias: association.through,
+                throughAssociations,
+                joinType,
+            });
+            // 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,
+                });
+            }
+            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({
+                dreamClass,
+                association,
+            });
+        const throughClass = throughAssociation.modelCB();
+        if (Array.isArray(throughClass))
+            throw new CannotAssociateThroughPolymorphic({
+                dreamClass,
+                association,
+            });
+        const newAssociation = getSourceAssociation(throughClass, association.source);
+        if (!newAssociation)
+            throw new MissingThroughAssociationSource({
+                dreamClass,
+                throughClass,
+                association,
+            });
+        return { throughAssociation, throughClass, newAssociation };
+    }
+    /**
+     * 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.
+     */
+    applyOneJoin({ query, dreamClass, previousAssociationTableOrAlias, currentAssociationTableOrAlias, joinAndStatements = {}, throughAssociations = [], joinType, }) {
+        const { name, alias } = extractAssociationMetadataFromAssociationName(currentAssociationTableOrAlias);
+        const joinAndStatement = joinAndStatements[currentAssociationTableOrAlias];
+        previousAssociationTableOrAlias = extractAssociationMetadataFromAssociationName(previousAssociationTableOrAlias).alias;
+        currentAssociationTableOrAlias = alias;
+        let association = dreamClass['getAssociationMetadata'](name);
+        if (!association) {
+            throw new JoinAttemptedOnMissingAssociation({
+                dreamClass,
+                associationName: currentAssociationTableOrAlias,
+            });
+        }
+        const results = this.joinsBridgeThroughAssociations({
+            query,
+            dreamClass,
+            association,
+            previousAssociationTableOrAlias,
+            throughAssociations,
+            joinType,
+        });
+        query = results.query;
+        dreamClass = results.dreamClass;
+        association = results.association;
+        const timeToApplyThroughAssociations = throughAssociations.length && throughAssociations[0]?.source === association.as;
+        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,
+                        });
+                    }
+                }
+            });
+        }
+        if (association.type === 'BelongsTo') {
+            if (Array.isArray(association.modelCB()))
+                throw new CannotJoinPolymorphicBelongsToError({
+                    dreamClass,
+                    association,
+                    innerJoinStatements: this.query['innerJoinStatements'],
+                    leftJoinStatements: this.query['leftJoinStatements'],
+                });
+            const to = association.modelCB().table;
+            const joinTableExpression = currentAssociationTableOrAlias === to
+                ? currentAssociationTableOrAlias
+                : `${to} as ${currentAssociationTableOrAlias}`;
+            query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
+                join = join.onRef(this.namespaceColumn(association.foreignKey(), previousAssociationTableOrAlias), '=', this.namespaceColumn(association.primaryKey(), currentAssociationTableOrAlias));
+                if (timeToApplyThroughAssociations) {
+                    throughAssociations.forEach((throughAssociation) => {
+                        join = this.applyAssociationAndStatementsToJoinStatement({
+                            join,
+                            association: throughAssociation,
+                            currentAssociationTableOrAlias,
+                            previousAssociationTableOrAlias: originalPreviousAssociationTableOrAlias,
+                            joinAndStatements,
+                        });
+                    });
+                }
+                join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
+                    join,
+                    tableNameOrAlias: currentAssociationTableOrAlias,
+                    association,
+                });
+                join = this.applyJoinAndStatement(join, joinAndStatement, currentAssociationTableOrAlias);
+                return join;
+            });
+        }
+        else {
+            const to = association.modelCB().table;
+            const joinTableExpression = currentAssociationTableOrAlias === to
+                ? currentAssociationTableOrAlias
+                : `${to} as ${currentAssociationTableOrAlias}`;
+            query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
+                join = join.onRef(this.namespaceColumn(association.primaryKey(), previousAssociationTableOrAlias), '=', this.namespaceColumn(association.foreignKey(), currentAssociationTableOrAlias));
+                if (association.polymorphic) {
+                    join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement({
+                        [association.foreignKeyTypeField()]: throughClass
+                            ? throughClass['stiBaseClassOrOwnClassName']
+                            : dreamClass['stiBaseClassOrOwnClassName'],
+                    }, currentAssociationTableOrAlias)));
+                }
+                if (timeToApplyThroughAssociations) {
+                    throughAssociations.forEach((throughAssociation) => {
+                        join = this.applyAssociationAndStatementsToJoinStatement({
+                            join,
+                            association: throughAssociation,
+                            currentAssociationTableOrAlias,
+                            previousAssociationTableOrAlias: originalPreviousAssociationTableOrAlias,
+                            joinAndStatements,
+                        });
+                    });
+                }
+                join = this.applyAssociationAndStatementsToJoinStatement({
+                    join,
+                    association,
+                    currentAssociationTableOrAlias,
+                    previousAssociationTableOrAlias,
+                    joinAndStatements,
+                });
+                join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
+                    join,
+                    tableNameOrAlias: currentAssociationTableOrAlias,
+                    association,
+                });
+                join = this.applyJoinAndStatement(join, joinAndStatement, currentAssociationTableOrAlias);
+                return join;
+            });
+            if (association.type === 'HasMany') {
+                if (association.order) {
+                    query = this.applyOrderStatementForAssociation({
+                        query,
+                        tableNameOrAlias: currentAssociationTableOrAlias,
+                        association,
+                    });
+                }
+                if (query.distinctOn && association.distinct) {
+                    query = query.distinctOn(this.distinctColumnNameForAssociation({
+                        association,
+                        tableNameOrAlias: currentAssociationTableOrAlias,
+                        foreignKey: association.foreignKey(),
+                    }));
+                }
+            }
+        }
+        return {
+            query,
+            association,
+            previousAssociationTableOrAlias,
+            currentAssociationTableOrAlias,
+        };
+    }
+    applyOrderStatementForAssociation({ query, tableNameOrAlias, association, }) {
+        if (!query.orderBy)
+            return query;
+        let selectQuery = query;
+        const orderStatement = association.order;
+        if (typeof orderStatement === 'string') {
+            selectQuery = selectQuery.orderBy(this.namespaceColumn(orderStatement, tableNameOrAlias), 'asc');
+        }
+        else {
+            Object.keys(orderStatement).forEach(column => {
+                const direction = orderStatement[column];
+                selectQuery = selectQuery.orderBy(this.namespaceColumn(column, tableNameOrAlias), direction);
+            });
+        }
+        return selectQuery;
+    }
+    distinctColumnNameForAssociation({ association, tableNameOrAlias, foreignKey, }) {
+        if (!association.distinct)
+            return null;
+        if (association.distinct === true)
+            return this.namespaceColumn(foreignKey, tableNameOrAlias);
+        return this.namespaceColumn(association.distinct, tableNameOrAlias);
+    }
+    applyAssociationAndStatementsToJoinStatement({ join, currentAssociationTableOrAlias, previousAssociationTableOrAlias, association, joinAndStatements, }) {
+        if (association.and) {
+            this.throwUnlessAllRequiredWhereClausesProvided(association, currentAssociationTableOrAlias, joinAndStatements);
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(association.and, currentAssociationTableOrAlias), { disallowSimilarityOperator: false }));
+        }
+        if (association.andNot) {
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(association.andNot, currentAssociationTableOrAlias), { negate: true }));
+        }
+        if (association.andAny) {
+            join = join.on((eb) => eb.or(association.andAny.map(whereAnyStatement => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(whereAnyStatement, currentAssociationTableOrAlias), { disallowSimilarityOperator: false }))));
+        }
+        if (association.selfAnd) {
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.rawifiedSelfOnClause({
+                associationAlias: association.as,
+                selfAlias: previousAssociationTableOrAlias,
+                selfAndClause: association.selfAnd,
+            })));
+        }
+        if (association.selfAndNot) {
+            join = join.on((eb) => this.whereStatementToExpressionWrapper(eb, this.rawifiedSelfOnClause({
+                associationAlias: association.as,
+                selfAlias: previousAssociationTableOrAlias,
+                selfAndClause: association.selfAndNot,
+            }), { negate: true }));
+        }
+        return join;
+    }
+    throwUnlessAllRequiredWhereClausesProvided(association, namespace, joinAndStatements) {
+        const andClause = association.and;
+        const columnsRequiringAndStatements = Object.keys(andClause).reduce((agg, column) => {
+            if (andClause[column] === DreamConst.required)
+                agg.push(column);
+            return agg;
+        }, []);
+        const missingRequiredWhereStatements = columnsRequiringAndStatements.filter(column => joinAndStatements[namespace]?.and?.[column] === undefined);
+        if (missingRequiredWhereStatements.length)
+            throw new MissingRequiredAssociationAndClause(association, missingRequiredWhereStatements[0]);
+    }
+    conditionallyApplyDefaultScopesDependentOnAssociation({ join, tableNameOrAlias, association, }) {
+        let scopesQuery = new Query(this.dreamInstance);
+        const associationClass = association.modelCB();
+        const associationScopes = associationClass['scopes'].default;
+        for (const scope of associationScopes) {
+            if (!shouldBypassDefaultScope(scope.method, {
+                bypassAllDefaultScopes: this.query['bypassAllDefaultScopes'],
+                defaultScopesToBypass: [
+                    ...this.query['defaultScopesToBypass'],
+                    ...(association.withoutDefaultScopes || []),
+                ],
+            })) {
+                const tempQuery = associationClass[scope.method](scopesQuery);
+                // The scope method on a Dream model should return a clone of the Query it receives
+                // (e.g. by returning `scope.where(...)`), but in case the function doesn't return,
+                // or returns the wrong thing, we check before overriding `scopesQuery` with what the
+                // method returned.
+                if (tempQuery && tempQuery.constructor === scopesQuery.constructor)
+                    scopesQuery = tempQuery;
+            }
+        }
+        if (scopesQuery['whereStatements'].length) {
+            join = join.on((eb) => eb.and(scopesQuery['whereStatements'].flatMap(whereStatement => this.whereStatementToExpressionWrapper(eb, this.aliasWhereStatement(whereStatement, tableNameOrAlias), { disallowSimilarityOperator: false }))));
+        }
+        return join;
+    }
+    /**
+     * @internal
+     *
+     * Polymorphic BelongsTo. Since polymorphic associations may point to multiple tables,
+     * preload by loading each target class separately.
+     *
+     * Used to preload polymorphic belongs to associations
+     */
+    async preloadPolymorphicBelongsTo(association, dreams) {
+        if (!association.polymorphic)
+            throw new Error(`Association ${association.as} points to an array of models but is not designated polymorphic`);
+        if (association.type !== 'BelongsTo')
+            throw new Error(`Polymorphic association ${association.as} points to an array of models but is ${association.type}. Only BelongsTo associations may point to an array of models.`);
+        const associatedDreams = [];
+        for (const associatedModel of association.modelCB()) {
+            await this.preloadPolymorphicAssociationModel(dreams, association, associatedModel, associatedDreams);
+        }
+        return associatedDreams;
+    }
+    async preloadPolymorphicAssociationModel(dreams, association, associatedDreamClass, associatedDreams) {
+        const relevantAssociatedModels = dreams.filter((dream) => {
+            const field = association.foreignKeyTypeField();
+            return dream[field] === associatedDreamClass['stiBaseClassOrOwnClassName'] || dream[field] === null;
+        });
+        if (relevantAssociatedModels.length) {
+            dreams.forEach((dream) => {
+                dream[associationToGetterSetterProp(association)] = null;
+            });
+            // Load all models of type associated that are associated with any of the already loaded Dream models
+            const loadedAssociations = await this.dreamClassQueryWithScopeBypasses(associatedDreamClass, {
+                // The association may remove specific default scopes that would otherwise preclude
+                // certain instances of the associated class from being found.
+                defaultScopesToBypassExceptOnAssociations: association.withoutDefaultScopes,
+            })
+                .where({
+                [associatedDreamClass.primaryKey]: relevantAssociatedModels.map((dream) => dream[association.foreignKey()]),
+            })
+                .all();
+            loadedAssociations.forEach((loadedAssociation) => associatedDreams.push(loadedAssociation));
+            //////////////////////////////////////////////////////////////////////////////////////////////
+            // Associate each loaded association with each dream based on primary key and foreign key type
+            //////////////////////////////////////////////////////////////////////////////////////////////
+            for (const loadedAssociation of loadedAssociations) {
+                dreams
+                    .filter((dream) => {
+                    return (dream[association.foreignKeyTypeField()] === loadedAssociation['stiBaseClassOrOwnClassName'] &&
+                        dream[association.foreignKey()] === association.primaryKeyValue(loadedAssociation));
+                })
+                    .forEach((dream) => {
+                    dream[association.as] = loadedAssociation;
+                });
+            }
+            ///////////////////////////////////////////////////////////////////////////////////////////////////
+            // end: Associate each loaded association with each dream based on primary key and foreign key type
+            ///////////////////////////////////////////////////////////////////////////////////////////////////
+        }
+    }
+    /**
+     * @internal
+     *
+     * Used for applying preload and load statements
+     *
+     * @returns An associated Query
+     */
+    dreamClassQueryWithScopeBypasses(dreamClass, { bypassAllDefaultScopesExceptOnAssociations = false, defaultScopesToBypassExceptOnAssociations = [], } = {}) {
+        const associationQuery = dreamClass.query().clone({
+            passthroughOnStatement: this.query['passthroughOnStatement'],
+            bypassAllDefaultScopes: this.query['bypassAllDefaultScopes'],
+            bypassAllDefaultScopesExceptOnAssociations,
+            defaultScopesToBypass: this.query['defaultScopesToBypass'],
+            defaultScopesToBypassExceptOnAssociations,
+        });
+        return (this.dreamTransaction ? associationQuery.txn(this.dreamTransaction) : associationQuery);
+    }
+    conditionallyAttachSimilarityColumnsToSelect(kyselyQuery, { bypassOrder = false } = {}) {
+        const similarityBuilder = this.similarityStatementBuilder();
+        if (similarityBuilder.hasSimilarityClauses) {
+            kyselyQuery = similarityBuilder.select(kyselyQuery, { bypassOrder });
+        }
+        return kyselyQuery;
+    }
+    conditionallyAttachSimilarityColumnsToUpdate(kyselyQuery) {
+        const similarityBuilder = this.similarityStatementBuilder();
+        if (similarityBuilder.hasSimilarityClauses) {
+            kyselyQuery = similarityBuilder.update(kyselyQuery);
+        }
+        return kyselyQuery;
+    }
+    /**
+     * @internal
+     *
+     * Applies a preload statement
+     */
+    async applyOnePreload(associationName, dreams, onStatement = {}) {
+        if (!Array.isArray(dreams))
+            dreams = [dreams];
+        const dream = dreams.find(dream => dream['getAssociationMetadata'](associationName));
+        if (!dream)
+            return;
+        const { name, alias } = extractAssociationMetadataFromAssociationName(associationName);
+        const association = dream['getAssociationMetadata'](name);
+        if (association === undefined)
+            throw new UnexpectedUndefined();
+        const dreamClass = dream.constructor;
+        const dreamClassToHydrate = association.modelCB();
+        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 (isObject(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']
+            : dreamClass;
+        const associationDataScope = this.dreamClassQueryWithScopeBypasses(baseClass, {
+            // In order to stay DRY, preloading leverages the association logic built into
+            // `joins` (by using `pluck`, which calls `joins`). However, baseClass may have
+            // default scopes that would preclude finding that instance. We remove all
+            // default scopes on baseClass, but not subsequent associations, so that the
+            // single query will be able to find each row corresponding to a Dream in `dreams`,
+            // regardless of default scopes on that Dream's class.
+            bypassAllDefaultScopesExceptOnAssociations: true,
+        }).where({
+            [dreamClass.primaryKey]: dreams.map(obj => obj.primaryKeyValue),
+        });
+        const hydrationData = await associationDataScope['_connection'](this.connectionOverride)
+            .innerJoin(associationName, (onStatement || {}))
+            .pluck(...columnsToPluck);
+        const preloadedDreamsAndWhatTheyPointTo = hydrationData.map(pluckedData => {
+            const attributes = {};
+            dreamClassToHydrateColumns.forEach((columnName, index) => (attributes[protectAgainstPollutingAssignment(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),
+            };
+        });
+        this.hydrateAssociation(dreams, association, preloadedDreamsAndWhatTheyPointTo);
+        return preloadedDreamsAndWhatTheyPointTo.map(obj => obj.dream);
+    }
+}
+function getSourceAssociation(dream, sourceName) {
+    if (!dream)
+        return;
+    if (!sourceName)
+        return;
+    return (dream['getAssociationMetadata'](sourceName) ||
+        dream['getAssociationMetadata'](pluralize.singular(sourceName)));
+}