@rvoh/dream 2.13.0 → 2.14.0-beta.1

package/dist/cjs/src/Dream.js

@@ -2020,10 +2020,10 @@ export default class Dream {
      * //       as: 'ratings',
      * //       polymorphic: true,
      * //       source: 'ratings',
-     * //       where: undefined,
-     * //       whereNot: undefined,
-     * //       selfWhere: undefined,
-     * //       selfWhereNot: undefined,
+     * //       and: undefined,
+     * //       andNot: undefined,
+     * //       selfAnd: undefined,
+     * //       selfAndNot: undefined,
      * //       primaryKeyOverride: null,
      * //       primaryKey: [Function: primaryKey],
      * //       primaryKeyValue: [Function: primaryKeyValue],

package/dist/cjs/src/db/DreamDbConnection.js

@@ -8,6 +8,7 @@
 // @ts-ignore
 import { CamelCasePlugin, Kysely } from 'kysely';
 import DreamApp from '../dream-app/index.js';
+import { claimedTestDatabaseIndexOrNull } from './testDatabasePool.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import { installDbConnectionLeakDiagnosticsIfEnabled, reportLeakedDbConnections, } from './dbConnectionLeakDiagnostics.js';
 let connections = {};
@@ -39,9 +40,14 @@ export default class DreamDbConnection {
         return dbConn;
     }
     static getConnectionTypeName(connectionType) {
-        return DreamApp.getOrFail().parallelDatabasesEnabled
-            ? `${connectionType}_${process.env.VITEST_POOL_ID}`
-            : connectionType;
+        // The connection cache is per Node process (per vitest worker), and a worker
+        // only ever uses its single claimed pool index, so suffixing the cache key by
+        // that index keeps connections cached per claimed database without colliding
+        // across the (now process-scoped) registry.
+        if (!DreamApp.getOrFail().testDatabaseClaimEnabled)
+            return connectionType;
+        const index = claimedTestDatabaseIndexOrNull();
+        return index === null ? connectionType : `${connectionType}_${index}`;
     }
 }
 export function dreamDbConnections() {

package/dist/cjs/src/db/dbConnectionLeakDiagnostics.js

@@ -41,21 +41,15 @@ function track(client, stack) {
     if (!client)
         return;
     checkedOutClients.set(client, { stack: stack ?? '(no stack captured)', since: Date.now() });
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const c = client;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     if (c.__dreamReleasePatched)
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     const originalRelease = c.release;
     if (typeof originalRelease !== 'function')
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     c.__dreamReleasePatched = true;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     c.release = function patchedRelease(...args) {
         checkedOutClients.delete(client);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
         return originalRelease.apply(this, args);
     };
 }
@@ -67,34 +61,26 @@ export function installDbConnectionLeakDiagnosticsIfEnabled() {
     if (!dreamDebugEnabled)
         return;
     enabled = true;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
     const Pool = pg.Pool;
     if (!Pool?.prototype)
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     if (Pool.prototype[INSTALLED])
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     Pool.prototype[INSTALLED] = true;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
     const originalConnect = Pool.prototype.connect;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     Pool.prototype.connect = function patchedConnect(cb) {
         const acquireStack = new Error('db connection acquired here').stack;
         if (typeof cb === 'function') {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
             return originalConnect.call(this, (err, client, release) => {
                 track(client, acquireStack);
                 // `track()` replaces `client.release` with an untracking wrapper.
                 // Callback-style users call the 3rd `release` arg, which pg captured
                 // *before* that swap — so hand them the wrapped one instead, or a
                 // correctly-released client would be reported as a false leak.
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
                 const wrappedRelease = client ? client.release : release;
                 cb(err, client, wrappedRelease);
             });
         }
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
         return originalConnect.call(this).then((client) => {
             track(client, acquireStack);
             return client;

package/dist/cjs/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -1,4 +1,5 @@
 import { sql } from 'kysely';
+import InternalEncrypt from '../../encrypt/InternalEncrypt.js';
 export default class DreamMigrationHelpers {
     /**
      * Rename a table and its associated primary key index and sequence.
@@ -195,6 +196,136 @@ export default class DreamMigrationHelpers {
             }
         }
     }
+    /**
+     * Convert an existing plaintext column into the encrypted-backed form expected by
+     * the `@Encrypted` decorator.
+     *
+     * This renames `column` to `encrypted_<column>`, widens it to `text`, and rewrites
+     * every non-null value with the AES-GCM ciphertext produced by the exact same code
+     * path the decorator's setter uses (`InternalEncrypt.encryptColumn`). After it runs,
+     * the column holds real ciphertext that the decorator's getter can decrypt — which is
+     * what a bare column rename does **not** do (renaming a plaintext column to
+     * `encrypted_<column>` and decorating the property leaves plaintext in the column, so
+     * the getter throws `DecryptionError`).
+     *
+     * The encryption key and algorithm come from the application's encryption config
+     * (`DreamApp` `encryption.columns.current`); if encryption is not configured this
+     * throws `MissingColumnEncryptionOpts`. Null values are left null.
+     *
+     * Intended for text/string columns (the common case is text -> encrypted text). The
+     * column is widened to `text` before reading, so values are encrypted as their text
+     * form; the inverse `decryptColumn` can restore a non-text type via its `columnType`
+     * option.
+     *
+     * ```ts
+     * // plaintext `phone` column -> encrypted `encrypted_phone` text column
+     * await DreamMigrationHelpers.encryptColumn(db, { table: 'users', column: 'phone' })
+     * ```
+     *
+     * **Rewrites rows one at a time** (each value needs a fresh random IV computed in Node,
+     * so the rewrite cannot be a single SQL `UPDATE`), reading them in keyset batches of
+     * `batchSize` to bound memory. It still holds the table for the migration's duration; on
+     * very large tables do not use this helper — write your own batched / online migration.
+     *
+     * **Drop any index on the column first.** Per-row updates pay index-maintenance cost on
+     * every write, and an index over ciphertext is useless anyway (encrypted values are not
+     * queryable). Remove the index before this migration and do not re-add it.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param options - Configuration options
+     * @param options.table - The name of the table
+     * @param options.column - The current (plaintext) column name
+     * @param options.encryptedColumnName - The target encrypted column name. Defaults to `encrypted_<column>`, matching the `@Encrypted` decorator's default; pass this when the decorator was given a custom encrypted column name.
+     * @param options.primaryKey - The primary key column used to keyset-paginate and target each row's update. Defaults to `id`.
+     * @param options.batchSize - How many rows to read per batch. Defaults to `1000`.
+     */
+    static async encryptColumn(db, { table, column, encryptedColumnName = `encrypted_${column}`, primaryKey = 'id', batchSize = 1000, }) {
+        await db.schema.alterTable(table).renameColumn(column, encryptedColumnName).execute();
+        await db.schema
+            .alterTable(table)
+            .alterColumn(encryptedColumnName, col => col.setDataType('text'))
+            .execute();
+        await this.transformColumnInBatches(db, { table, column: encryptedColumnName, primaryKey, batchSize }, value => InternalEncrypt.encryptColumn(value));
+    }
+    /**
+     * Inverse of {@link DreamMigrationHelpers.encryptColumn}: decrypt an
+     * `encrypted_<column>` column back to plaintext and rename it to `column`.
+     *
+     * Every non-null value is decrypted with the same path the decorator's getter uses
+     * (`InternalEncrypt.decryptColumn`, which honors both the `current` and `legacy`
+     * encryption keys), then the column is renamed back. Called with the same `table` and
+     * `column`, this exactly reverses `encryptColumn`.
+     *
+     * By default the column is left as `text`, because the original column type cannot be
+     * recovered from the encrypted state. Pass `columnType` to restore a specific type
+     * (e.g. `'integer'`); the conversion runs `ALTER COLUMN ... TYPE <columnType> USING
+     * <column>::<columnType>`.
+     *
+     * ```ts
+     * await DreamMigrationHelpers.decryptColumn(db, { table: 'users', column: 'phone' })
+     *
+     * // restore the original column type as part of the inverse
+     * await DreamMigrationHelpers.decryptColumn(db, { table: 'users', column: 'age', columnType: 'integer' })
+     * ```
+     *
+     * The same per-row, batched, table-locking caveat as `encryptColumn` applies.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param options - Configuration options
+     * @param options.table - The name of the table
+     * @param options.column - The target (plaintext) column name to rename back to
+     * @param options.encryptedColumnName - The current encrypted column name. Defaults to `encrypted_<column>`.
+     * @param options.primaryKey - The primary key column used to keyset-paginate and target each row's update. Defaults to `id`.
+     * @param options.batchSize - How many rows to read per batch. Defaults to `1000`.
+     * @param options.columnType - When provided, the restored column is converted to this type. When omitted, the column is left as `text`.
+     */
+    static async decryptColumn(db, { table, column, encryptedColumnName = `encrypted_${column}`, primaryKey = 'id', batchSize = 1000, columnType, }) {
+        await this.transformColumnInBatches(db, { table, column: encryptedColumnName, primaryKey, batchSize }, value => InternalEncrypt.decryptColumn(value));
+        await db.schema.alterTable(table).renameColumn(encryptedColumnName, column).execute();
+        if (columnType !== undefined) {
+            await sql `
+        ALTER TABLE ${sql.table(table)}
+        ALTER COLUMN ${sql.ref(column)}
+        TYPE ${sql.raw(columnType)}
+        USING ${sql.ref(column)}::${sql.raw(columnType)};
+      `.execute(db);
+        }
+    }
+    /**
+     * Walk every non-null value of `column` in keyset batches of `batchSize`, applying
+     * `transform` in Node and writing the result back one row at a time. Keyset pagination
+     * on `primaryKey` (`WHERE pk > last ORDER BY pk`) bounds memory to a single batch and
+     * guarantees forward progress, so a row is never read — or transformed — twice (which
+     * matters because the transform is not idempotent: re-encrypting ciphertext would
+     * double-encrypt, and re-decrypting plaintext would throw).
+     *
+     * Reads alias the selected columns to fixed keys via `sql.ref(...).as(...)` so a
+     * `CamelCasePlugin` on the connection cannot rename the result keys.
+     */
+    static async transformColumnInBatches(db, { table, column, primaryKey, batchSize, }, transform) {
+        let lastPrimaryKey;
+        for (;;) {
+            let query = db
+                .selectFrom(table)
+                .select([sql.ref(primaryKey).as('pk'), sql.ref(column).as('val')])
+                .where(column, 'is not', null)
+                .orderBy(primaryKey)
+                .limit(batchSize);
+            if (lastPrimaryKey !== undefined)
+                query = query.where(primaryKey, '>', lastPrimaryKey);
+            const rows = await query.execute();
+            if (rows.length === 0)
+                break;
+            for (const row of rows) {
+                await db
+                    .updateTable(table)
+                    .set({ [column]: transform(row.val) })
+                    .where(primaryKey, '=', row.pk)
+                    .execute();
+                lastPrimaryKey = row.pk;
+            }
+        }
+    }
 }
 async function getEnumValues(db, enumName) {
     const response = await sql `SELECT unnest(enum_range(NULL::${sql.raw(enumName)}))`.execute(db);

package/dist/cjs/src/db/testDatabasePool.js

@@ -0,0 +1,182 @@
+/**
+ * Per-live-worker test-database pool. Each worker claims a free database from a
+ * pre-created pool by holding a process-lifetime, auto-releasing lock; the
+ * adapter-specific lock primitive lives behind the query-driver seam
+ * ({@link TestDatabaseLockSession}), so this module stays driver-agnostic.
+ *
+ * ## Why this exists
+ *
+ * Under vitest (`pool: 'forks'`, `isolate: true`) `VITEST_POOL_ID` is a
+ * *reusable slot id* (1..maxWorkers) that vitest frees and reassigns across
+ * worker processes. vitest does not await `runner.stop()` before reusing a
+ * slot, so a retired-but-still-terminating worker overlaps the new worker that
+ * reused its slot. When the test database is keyed off that reusable slot
+ * (`<base>_<VITEST_POOL_ID>`), the two overlapping processes share one
+ * database, and the newcomer's `beforeEach(truncate)` wipes the other's
+ * in-flight rows -> records vanish mid-test -> intermittent failures.
+ *
+ * ## The fix
+ *
+ * Tie database ownership to *process liveness* instead of vitest's slot
+ * accounting. Each live worker claims a free database from a pre-created pool
+ * by taking a lock on a dedicated, long-lived connection (the
+ * {@link TestDatabaseLockSession}, supplied by the default connection's query
+ * driver). The lock auto-releases the instant the worker's connection drops on
+ * process exit, so a reused vitest slot can never collide: the new worker
+ * probes for and claims a *different* free database, and only ever reuses an
+ * index whose previous owner has genuinely exited.
+ *
+ * The pool is `<base>` (index 1, unsuffixed) plus `<base>_2 .. <base>_K`,
+ * pre-created at `db:migrate` / `db:reset` time as `TEMPLATE <base>` clones.
+ * Pool size `K = 2 * max(1, parallelTests) + margin` covers N active workers
+ * plus up to N still-terminating workers, with margin for transient overlap.
+ *
+ * The lock primitive itself — and its key derivation — is the driver's
+ * concern: Postgres maps `(namespace, index)` to a two-`int4` advisory lock,
+ * MySQL to a `GET_LOCK` name. This orchestrator only ever speaks the neutral
+ * `(namespace, index)` contract.
+ */
+// Extra databases beyond `2 * max(1, parallelTests)` to absorb transient
+// overlap (e.g. several workers terminating at once on a slow machine).
+const POOL_MARGIN = 2;
+// How long to keep re-probing for a free database when every pool index is
+// momentarily claimed, before failing loud. A lingering worker's lock frees
+// within milliseconds of its process exiting, so this only ever waits out a
+// brief handoff window.
+const WAIT_FOR_FREE_TIMEOUT_MS = 5_000;
+const WAIT_FOR_FREE_POLL_INTERVAL_MS = 50;
+// Module-level singleton: one per Node process === one per vitest worker. A
+// fresh worker process starts with a clean slate and claims its own index.
+const state = {
+    index: null,
+    claimPromise: null,
+    lockSession: null,
+};
+/**
+ * The number of databases in the pre-created pool (including the unsuffixed
+ * base at index 1). Shared by the CLI pool-creation / drop loops and the claim
+ * probe so they always agree on the index range.
+ */
+export function testDatabasePoolSize(parallelTests) {
+    const n = typeof parallelTests === 'number' && Number.isFinite(parallelTests) && parallelTests > 0
+        ? Math.floor(parallelTests)
+        : 1;
+    return 2 * Math.max(1, n) + POOL_MARGIN;
+}
+/**
+ * The database name for a pool index given the un-suffixed base name. Index 1
+ * is the base itself (no suffix); higher indexes are `<base>_<index>`. This is
+ * the single naming rule, used by both the claim path and the CLI loops.
+ */
+export function testDatabaseNameForIndex(baseName, index) {
+    return index <= 1 ? baseName : `${baseName}_${index}`;
+}
+/**
+ * Sync read of the already-claimed pool index, or null if no claim has
+ * completed yet in this process. `DreamApp.dbName()` (synchronous, called when
+ * Kysely builds a pool) relies on the claim having been awaited earlier in the
+ * worker — `DreamApp.init()` awaits {@link claimTestDatabase} before the first
+ * connection is built, and `truncate` awaits it too — so by the time any
+ * connection resolves its database name the index is populated.
+ */
+export function claimedTestDatabaseIndexOrNull() {
+    return state.index;
+}
+function delay(ms) {
+    return new Promise(resolve => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+/**
+ * Claim a free pool database for this worker (idempotent). On first call it
+ * opens the default driver's dedicated lock session, probes
+ * {@link TestDatabaseLockSession.tryAcquire} across the pool indexes until one
+ * succeeds, and caches the claimed index for the rest of the process.
+ * Subsequent calls (and concurrent callers) return the same index.
+ *
+ * Throws a loud, actionable error if the pool is genuinely exhausted after the
+ * wait-for-free window — telling the reader to recreate the pool with
+ * `<packageManager> psy db:reset`.
+ */
+export async function claimTestDatabase(dreamApp) {
+    if (state.index !== null)
+        return state.index;
+    if (state.claimPromise)
+        return state.claimPromise;
+    state.claimPromise = performClaim(dreamApp);
+    try {
+        state.index = await state.claimPromise;
+        return state.index;
+    }
+    finally {
+        state.claimPromise = null;
+    }
+}
+async function performClaim(dreamApp) {
+    const creds = dreamApp.dbCredentialsFor('default')?.primary ?? dreamApp.dbCredentialsFor('default')?.replica;
+    if (!creds?.name)
+        throw new Error('[dream] cannot claim a test database: the "default" connection has no resolvable primary db name');
+    // The base db name doubles as the lock namespace: the driver hashes it into
+    // its own lock key so two apps sharing one server reserve disjoint indexes.
+    const baseName = creds.name;
+    const poolSize = testDatabasePoolSize(dreamApp.parallelTests);
+    const driver = dreamApp.dbConnectionQueryDriverClass('default');
+    const session = await driver.openTestDatabaseLockSession('default');
+    state.lockSession = session;
+    const deadline = nowMs() + WAIT_FOR_FREE_TIMEOUT_MS;
+    for (;;) {
+        for (let index = 1; index <= poolSize; index++) {
+            if (await session.tryAcquire(baseName, index))
+                return index;
+        }
+        if (nowMs() >= deadline)
+            break;
+        await delay(WAIT_FOR_FREE_POLL_INTERVAL_MS);
+    }
+    // Genuine exhaustion: every pool index is held and none freed within the
+    // wait window. Fail loud with concrete remediation rather than hanging or
+    // silently sharing a database.
+    await session.release().catch(() => undefined);
+    state.lockSession = null;
+    throw new Error(`[dream] test-database pool exhausted: all ${poolSize} databases in the "${baseName}" ` +
+        `pool are claimed by live workers and none freed within ${WAIT_FOR_FREE_TIMEOUT_MS}ms. ` +
+        `This usually means the pool is undersized for the current parallelism, or stale locks are ` +
+        `lingering. Recreate the pool with:\n\n    ${dbResetCommand(dreamApp)}\n\n` +
+        `If it recurs under heavy parallelism, raise DREAM_PARALLEL_TESTS (which widens the pool).`);
+}
+function dbResetCommand(dreamApp) {
+    switch (dreamApp.packageManager) {
+        case 'npm':
+            return 'npm run psy db:reset';
+        case 'yarn':
+            return 'yarn psy db:reset';
+        case 'bun':
+            return 'bun run psy db:reset';
+        case 'deno':
+            return 'deno task psy db:reset';
+        case 'pnpm':
+        default:
+            return 'pnpm psy db:reset';
+    }
+}
+function nowMs() {
+    // Date.now() rather than performance.now(); we only need coarse wall-clock
+    // for the wait-for-free deadline.
+    return Date.now();
+}
+/**
+ * Test-only escape hatch for dream's own spec suite: release the claim and
+ * close the lock session so a test can exercise the claim machinery in
+ * isolation. Not part of the public API.
+ *
+ * @internal
+ */
+export async function __resetTestDatabaseClaimForSpec() {
+    const session = state.lockSession;
+    state.index = null;
+    state.claimPromise = null;
+    state.lockSession = null;
+    if (session)
+        await session.release().catch(() => undefined);
+}

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

@@ -164,6 +164,35 @@ export default class QueryDriverBase {
     static async setDatabaseTypeParsers(connectionName) { }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     static async duplicateDatabase(connectionName) { }
+    /**
+     * @internal
+     *
+     * Whether this driver implements the per-worker test-database claim seam
+     * ({@link openTestDatabaseLockSession}). Adapters that can hold a
+     * process-lifetime, auto-releasing lock to reserve one database from the
+     * test pool override this to `true`. It defaults to `false` so that a new
+     * adapter fails loud under vitest rather than silently sharing a single
+     * database across overlapping workers — see `src/db/testDatabasePool.ts`.
+     */
+    static supportsParallelTestDatabases = false;
+    /**
+     * @internal
+     *
+     * Open a dedicated, process-lifetime lock session used to claim one database
+     * from the per-worker test pool. Only ever called when
+     * {@link supportsParallelTestDatabases} is `true`; the base default throws.
+     *
+     * The returned session wraps a single dedicated connection: the orchestrator
+     * (`src/db/testDatabasePool.ts`) probes many pool indexes on the one session
+     * via `tryAcquire` and keeps whichever it acquires, holding it for the
+     * worker's lifetime.
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async openTestDatabaseLockSession(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    connectionName) {
+        throw new Error('override openTestDatabaseLockSession in child class');
+    }
     // eslint-disable-next-line @typescript-eslint/require-await
     static async getColumnData(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars

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

@@ -1007,7 +1007,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatements: query['innerJoinAndStatements'],
                 dreamClass: query['dreamClass'],
                 // 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')`),
+                // the developer has included 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.
@@ -1022,7 +1022,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatements: query['leftJoinAndStatements'],
                 dreamClass: query['dreamClass'],
                 // 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')`),
+                // the developer has included 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.
@@ -1367,6 +1367,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     namespaceColumn(column, alias = this.query['baseSqlAlias']) {
         return namespaceColumn(column, alias);
     }
+    /**
+     * @internal
+     *
+     * Builds the table expression passed to Kysely's `innerJoin`/`leftJoin` for an
+     * association. When the alias already snakeifies to the table name, Kysely's
+     * CamelCasePlugin emits the correct identifier from the alias alone, so no
+     * explicit `as` clause is needed; otherwise we join the table aliased as `alias`.
+     *
+     * @returns A table expression string, e.g. `"beautiful_balloons as balloon"`
+     */
+    aliasedJoinTableExpression(tableName, alias) {
+        return snakeify(alias) === tableName ? alias : `${tableName} as ${alias}`;
+    }
     checkForQueryViolations() {
         const invalidWhereNotClauses = this.similarityStatementBuilder().whereNotStatementsWithSimilarityClauses();
         if (invalidWhereNotClauses.length) {
@@ -1502,12 +1515,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      */
     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
+     * The table alias to use for the association being joined.
+     *
+     * When the join statement includes an explicit alias, e.g.
+     * `leftJoinPreload('hello as ho', 'world as wd')`, explicitAlias is that
+     * alias ('ho' for `hello`, 'wd' for `world`).
+     *
+     * When no explicit alias is given (e.g. `leftJoinPreload('hello', 'world')`),
+     * `recursivelyJoin` passes the association name itself ('hello', 'world') as
+     * the alias, so explicitAlias is still defined.
+     *
+     * explicitAlias is only `undefined` for the intermediate join tables that
+     * `joinsBridgeThroughAssociations` synthesizes while bridging a `through`
+     * association — those tables are never aliased by the developer.
      */
     explicitAlias, 
     /**
@@ -1628,12 +1648,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     }
     applyOneJoin({ 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
+     * The table alias to use for the association being joined.
+     *
+     * When the join statement includes an explicit alias, e.g.
+     * `leftJoinPreload('hello as ho', 'world as wd')`, explicitAlias is that
+     * alias ('ho' for `hello`, 'wd' for `world`).
+     *
+     * When no explicit alias is given (e.g. `leftJoinPreload('hello', 'world')`),
+     * `recursivelyJoin` passes the association name itself ('hello', 'world') as
+     * the alias, so explicitAlias is still defined.
+     *
+     * explicitAlias is only `undefined` for the intermediate join tables that
+     * `joinsBridgeThroughAssociations` synthesizes while bridging a `through`
+     * association — those tables are never aliased by the developer.
      */
     explicitAlias, 
     /**
@@ -1672,12 +1699,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     }
     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
+     * The table alias to use for the association being joined.
+     *
+     * When the join statement includes an explicit alias, e.g.
+     * `leftJoinPreload('hello as ho', 'world as wd')`, explicitAlias is that
+     * alias ('ho' for `hello`, 'wd' for `world`).
+     *
+     * When no explicit alias is given (e.g. `leftJoinPreload('hello', 'world')`),
+     * `recursivelyJoin` passes the association name itself ('hello', 'world') as
+     * the alias, so explicitAlias is still defined.
+     *
+     * explicitAlias is only `undefined` for the intermediate join tables that
+     * `joinsBridgeThroughAssociations` synthesizes while bridging a `through`
+     * association — those tables are never aliased by the developer.
      */
     explicitAlias, 
     /**
@@ -1714,7 +1748,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     leftJoinStatements: this.query['leftJoinStatements'],
                 });
             const to = (dreamClassThroughAssociationWantsToHydrate ?? association.modelCB()).table;
-            const joinTableExpression = snakeify(currentTableAlias) === to ? currentTableAlias : `${to} as ${currentTableAlias}`;
+            const joinTableExpression = this.aliasedJoinTableExpression(to, currentTableAlias);
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
                 join = join.onRef(this.namespaceColumn(association.foreignKey(), previousTableAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
                     associatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
@@ -1747,7 +1781,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         }
         else {
             const to = association.modelCB().table;
-            const joinTableExpression = snakeify(currentTableAlias) === to ? currentTableAlias : `${to} as ${currentTableAlias}`;
+            const joinTableExpression = this.aliasedJoinTableExpression(to, currentTableAlias);
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
                 join = join.onRef(this.namespaceColumn(association.primaryKey(), previousTableAlias), '=', this.namespaceColumn(association.foreignKey(), currentTableAlias));
                 if (association.polymorphic) {