uql-orm 0.24.5 → 0.24.7

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -4,9 +4,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * Works with both MySQL and MariaDB as they share the same information_schema structure.
  */
 export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT TABLE_NAME as table_name
@@ -95,12 +92,6 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY ORDINAL_POSITION
     `;
     }
-    // ============================================================================
-    // Internal Types
-    // ============================================================================
-    mapTableNameRow(row) {
-        return row.table_name;
-    }
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,

package/dist/migrate/introspection/postgresIntrospector.d.ts

@@ -11,9 +11,6 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
     protected getIndexesQuery(_tableName: string): string;
     protected getForeignKeysQuery(_tableName: string): string;
     protected getPrimaryKeyQuery(_tableName: string): string;
-    protected mapTableNameRow(row: {
-        table_name: string;
-    }): string;
     protected mapColumnsResult(_read: TableRowReader, _tableName: string, results: PostgresColumnRow[]): Promise<ColumnSchema[]>;
     protected mapIndexesResult(_read: TableRowReader, _tableName: string, results: {
         index_name: string;

package/dist/migrate/introspection/postgresIntrospector.js

@@ -3,9 +3,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * PostgreSQL schema introspector
  */
 export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT table_name
@@ -128,12 +125,6 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY kcu.ordinal_position
     `;
     }
-    // ============================================================================
-    // Internal Types
-    // ============================================================================
-    mapTableNameRow(row) {
-        return row.table_name;
-    }
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,
@@ -166,9 +157,6 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));
     }
-    // ============================================================================
-    // PostgreSQL-specific helpers
-    // ============================================================================
     normalizeType(dataType, udtName) {
         // Handle user-defined types and arrays
         if (dataType === 'USER-DEFINED') {

package/dist/migrate/introspection/sqliteIntrospector.d.ts

@@ -15,6 +15,7 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
     protected getIndexesParams(_tableName: string): unknown[];
     protected getForeignKeysParams(_tableName: string): unknown[];
     protected getPrimaryKeyParams(_tableName: string): unknown[];
+    /** `sqlite_master`, not `information_schema`, so the column is `name`. */
     protected mapTableNameRow(row: {
         name: string;
     }): string;

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -3,9 +3,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * SQLite schema introspector
  */
 export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT name
@@ -55,9 +52,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     getPrimaryKeyParams(_tableName) {
         return [];
     }
-    // ============================================================================
-    // Row Mapping (dialect-specific)
-    // ============================================================================
+    /** `sqlite_master`, not `information_schema`, so the column is `name`. */
     mapTableNameRow(row) {
         return row.name;
     }
@@ -128,9 +123,6 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return pkColumns.map((r) => r.name);
     }
-    // ============================================================================
-    // SQLite-specific helpers
-    // ============================================================================
     async getUniqueColumns(read, tableName) {
         const indexes = await read(this.getIndexesQuery(tableName));
         const uniqueColumns = new Set();

package/dist/migrate/migrator.d.ts

@@ -53,6 +53,14 @@ export declare class Migrator {
         to?: string;
         step?: number;
     }): Promise<MigrationResult[]>;
+    /**
+     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
+     *
+     * Both directions do exactly this and differ only in the list they start from: `up` takes the
+     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
+     * makes `--to` and `--step` mean the same thing whichever way you are going.
+     */
+    private runInOrder;
     /**
      * Run a single migration within a transaction
      */

package/dist/migrate/migrator.js

@@ -130,27 +130,7 @@ export class Migrator {
      * Run all pending migrations
      */
     async up(options = {}) {
-        const pendingMigrations = await this.pending();
-        const results = [];
-        let migrationsToRun = pendingMigrations;
-        if (options.to) {
-            const toIndex = migrationsToRun.findIndex((m) => m.name === options.to);
-            if (toIndex === -1) {
-                throw new Error(`Migration '${options.to}' not found`);
-            }
-            migrationsToRun = migrationsToRun.slice(0, toIndex + 1);
-        }
-        if (options.step !== undefined) {
-            migrationsToRun = migrationsToRun.slice(0, options.step);
-        }
-        for (const migration of migrationsToRun) {
-            const result = await this.runMigration(migration, 'up');
-            results.push(result);
-            if (!result.success) {
-                break; // Stop on first failure
-            }
-        }
-        return results;
+        return this.runInOrder(await this.pending(), 'up', options);
     }
     /**
      * Rollback migrations
@@ -159,23 +139,33 @@ export class Migrator {
         const [migrations, executed] = await Promise.all([this.getMigrations(), this.storage.executed()]);
         const executedSet = new Set(executed);
         const executedMigrations = migrations.filter((m) => executedSet.has(m.name)).reverse(); // Rollback in reverse order
-        const results = [];
-        let migrationsToRun = executedMigrations;
+        return this.runInOrder(executedMigrations, 'down', options);
+    }
+    /**
+     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
+     *
+     * Both directions do exactly this and differ only in the list they start from: `up` takes the
+     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
+     * makes `--to` and `--step` mean the same thing whichever way you are going.
+     */
+    async runInOrder(migrations, direction, options) {
+        let selected = migrations;
         if (options.to) {
-            const toIndex = migrationsToRun.findIndex((m) => m.name === options.to);
+            const toIndex = selected.findIndex((m) => m.name === options.to);
             if (toIndex === -1) {
                 throw new Error(`Migration '${options.to}' not found`);
             }
-            migrationsToRun = migrationsToRun.slice(0, toIndex + 1);
+            selected = selected.slice(0, toIndex + 1);
         }
         if (options.step !== undefined) {
-            migrationsToRun = migrationsToRun.slice(0, options.step);
+            selected = selected.slice(0, options.step);
         }
-        for (const migration of migrationsToRun) {
-            const result = await this.runMigration(migration, 'down');
+        const results = [];
+        for (const migration of selected) {
+            const result = await this.runMigration(migration, direction);
             results.push(result);
             if (!result.success) {
-                break; // Stop on first failure
+                break;
             }
         }
         return results;

package/dist/migrate/schemaGenerator.js

@@ -40,9 +40,6 @@ export class SqlSchemaGenerator {
     get serialPrimaryKeyType() {
         return this.dialect.serialPrimaryKey;
     }
-    // ============================================================================
-    // CanonicalType Integration (Unified Type System)
-    // ============================================================================
     /**
      * Convert FieldOptions to CanonicalType using the unified type system.
      */
@@ -52,9 +49,6 @@ export class SqlSchemaGenerator {
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
-    // ============================================================================
-    // SchemaGenerator Implementation
-    // ============================================================================
     generateCreateTable(entity, options = {}) {
         const builder = new SchemaASTBuilder(this.dialect.namingStrategy);
         const ast = builder.fromEntities([entity]);
@@ -390,9 +384,6 @@ export class SqlSchemaGenerator {
         };
         return normalize(current) === normalize(desired);
     }
-    // ============================================================================
-    // SchemaAST Support Methods
-    // ============================================================================
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
@@ -468,9 +459,6 @@ export class SqlSchemaGenerator {
     generateCreateIndexFromNode(index, options = { ifNotExists: false }) {
         return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
     }
-    // ============================================================================
-    // Phase 3: Builder Operation Methods (Moved forward for unification)
-    // ============================================================================
     generateCreateTableFromDefinition(table, options = {}) {
         const tableNode = this.tableDefinitionToNode(table);
         return this.generateCreateTableFromNode(tableNode, options);

package/dist/mongo/mongoDialect.d.ts

@@ -103,6 +103,13 @@ export declare class MongoDialect extends AbstractDialect {
      */
     private pathOf;
     aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, relationSummary?: RelationRequestSummary<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
+    /**
+     * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
+     * the joined documents, and the `_id` a to-many fill groups children by. It goes last, after the
+     * lookups have read the join keys - projecting any earlier is what used to leave `$populate`
+     * empty, and is why the pipeline emitted no projection at all and returned every column.
+     */
+    pipelineProjection<E extends Document>(entity: Type<E>, q: Query<E>, relationSummary?: RelationRequestSummary<E>): Record<string, 0 | 1> | undefined;
     /**
      * `$lookup`/`$unwind` stages for the joinable relations a query populates. Shared by the plain
      * aggregation pipeline and the `$vectorSearch` one, so relations load the same way in both.

package/dist/mongo/mongoDialect.js

@@ -414,8 +414,33 @@ export class MongoDialect extends AbstractDialect {
         // does after an INNER JOIN. Otherwise paging first is equivalent and spares the lookups.
         const dropsParents = relStages.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
         pipeline.push(...(dropsParents ? [...relStages, ...pager] : [...pager, ...relStages]));
+        const projection = this.pipelineProjection(entity, q, relationSummary);
+        if (projection) {
+            pipeline.push({ $project: projection });
+        }
         return pipeline;
     }
+    /**
+     * The scalar projection a narrowing query asks for, widened by what the pipeline itself produced:
+     * the joined documents, and the `_id` a to-many fill groups children by. It goes last, after the
+     * lookups have read the join keys - projecting any earlier is what used to leave `$populate`
+     * empty, and is why the pipeline emitted no projection at all and returned every column.
+     */
+    pipelineProjection(entity, q, relationSummary) {
+        if (!q.$select && !q.$exclude) {
+            return undefined;
+        }
+        const projection = this.select(entity, q.$select, q.$exclude);
+        const summary = relationSummary ?? getRelationRequestSummary(getMeta(entity), q.$populate);
+        for (const relKey of summary.joinableKeys) {
+            projection[relKey] = 1;
+        }
+        // Only ever undoes an exclusion: a relation cannot be filled onto a parent with no key.
+        if (summary.requestedKeys.length && projection[MongoDialect.ID_KEY] === 0) {
+            delete projection[MongoDialect.ID_KEY];
+        }
+        return projection;
+    }
     /**
      * `$lookup`/`$unwind` stages for the joinable relations a query populates. Shared by the plain
      * aggregation pipeline and the `$vectorSearch` one, so relations load the same way in both.
@@ -439,11 +464,22 @@ export class MongoDialect extends AbstractDialect {
             // filters (in particular `security: true` ones) must apply even to a bare
             // `$populate: { rel: true }`, exactly like the SQL dialects' JOIN ON-clause filters.
             const relationFilter = this.where(relEntity, relQuery.$where ?? {}, opts);
+            // The relation's own projection runs inside the lookup, where its keys resolve against the
+            // related entity. Left out, `$populate: { rel: { $select } }` returned all of `rel`'s columns.
+            const relationProjection = this.pipelineProjection(relEntity, relQuery);
+            // MongoDB returns `_id` unless a projection subtracts it, so dropping the key from the map is
+            // how a joined document keeps its own id - as it does on the SQL dialects, and as a nested
+            // to-many fill needs.
+            delete relationProjection?.[MongoDialect.ID_KEY];
+            const lookupPipeline = [
+                ...(hasKeys(relationFilter) ? [{ $match: relationFilter }] : []),
+                ...(relationProjection ? [{ $project: relationProjection }] : []),
+            ];
             pipeline.push({
                 $lookup: {
                     from: this.resolveTableName(relEntity, relMeta),
                     ...this.joinKeys(meta, relMeta, relOpts),
-                    ...(hasKeys(relationFilter) ? { pipeline: [{ $match: relationFilter }] } : {}),
+                    ...(lookupPipeline.length ? { pipeline: lookupPipeline } : {}),
                     as: relKey,
                 },
             });

package/dist/mongo/mongodbQuerier.js

@@ -109,14 +109,19 @@ export class MongodbQuerier extends AbstractQuerier {
         const meta = getMeta(entity);
         const relationSummary = getRelationRequestSummary(meta, q.$populate);
         const scoreAlias = vectorSort.vectorSearch.$project;
-        // With relations, the score is captured with `$addFields` before the lookups and no scalar
-        // `$project` is emitted: projecting here would drop both the join keys and the joined documents,
-        // which is why `$populate` used to come back empty under a vector sort.
+        // With relations the score is captured with `$addFields` before the lookups, and the scalar
+        // projection waits until after them: projecting any earlier drops the join keys and the joined
+        // documents, which is why `$populate` used to come back empty under a vector sort.
         if (relationSummary.requestedKeys.length) {
             if (scoreAlias) {
                 pipeline.push({ $addFields: { [scoreAlias]: { $meta: 'vectorSearchScore' } } });
             }
             pipeline.push(...this.dialect.relationStages(entity, q, relationSummary));
+            const projection = this.dialect.pipelineProjection(entity, q, relationSummary);
+            if (projection) {
+                // `$addFields` already made the score a real field, so it projects like any other.
+                pipeline.push({ $project: scoreAlias ? { ...projection, [scoreAlias]: 1 } : projection });
+            }
         }
         else if (scoreAlias) {
             const select = q.$select || q.$exclude ? this.buildScalarProjection(entity, q) : {};

package/dist/neon/neonQuerierPool.d.ts

@@ -6,5 +6,5 @@ import { NeonQuerier } from './neonQuerier.js';
 export declare class NeonQuerierPool extends AbstractPgQuerierPool<PoolClient, NeonQuerier, NeonDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<NeonQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): NeonQuerier;
 }

package/dist/neon/neonQuerierPool.js

@@ -1,12 +1,14 @@
-import { Pool } from '@neondatabase/serverless';
+import { Pool, types } from '@neondatabase/serverless';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
+import { numericTypes } from '../postgres/pgNumericTypes.js';
 import { NeonDialect } from './neonDialect.js';
 import { NeonQuerier } from './neonQuerier.js';
 export class NeonQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
-        super(new NeonDialect({ namingStrategy: extra?.namingStrategy }), new Pool(opts), extra);
+        // Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
+        super(new NeonDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new NeonQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new NeonQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/postgres/abstractPgQuerierPool.d.ts

@@ -17,5 +17,11 @@ export interface PgAnyPool<C extends PgAnyClient> extends ErrorEmittingPool {
 export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, Q extends AbstractPgQuerier<C, D>, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<Q, D> {
     readonly pool: PgAnyPool<C>;
     constructor(dialect: D, pool: PgAnyPool<C>, extra?: ExtraOptions);
+    /**
+     * Every pg-compatible pool acquires a client the same way, so only the querier class varies.
+     * Subclasses name that instead of restating the lazy `connect` the querier expects.
+     */
+    protected abstract buildQuerier(connect: () => Promise<C>): Q;
+    getQuerier(): Promise<Q>;
     end(): Promise<void>;
 }

package/dist/postgres/abstractPgQuerierPool.js

@@ -14,6 +14,9 @@ export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
         this.pool = pool;
         attachPoolErrorHandler(pool, 'Idle Postgres pool client encountered an error');
     }
+    async getQuerier() {
+        return this.buildQuerier(() => this.pool.connect());
+    }
     async end() {
         await this.pool.end();
     }

package/dist/postgres/pgNumericTypes.d.ts

@@ -0,0 +1,41 @@
+import type { CustomTypesConfig } from 'pg';
+/**
+ * The shape every pg-family driver exposes as `types`: `pg`'s own, and `@neondatabase/serverless`'s
+ * reimplementation of it. Taken as a parameter rather than imported, because `uql-orm/neon` must not
+ * pull `pg` into an edge bundle that has no such peer installed - the same reason
+ * `abstractPgQuerierPool.ts` keeps its `pg` imports type-only.
+ */
+type PgTypes = {
+    readonly builtins: Readonly<Record<string, number>>;
+    getTypeParser(oid: number, format?: 'text' | 'binary'): (value: string) => unknown;
+};
+/**
+ * Decode `INT8` and `FLOAT8` as JS numbers, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
+ * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
+ * JS number is, so decoding it loses nothing at all.
+ *
+ * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
+ * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
+ * types belong here and which need the entity's declaration is settled in `hydratableFields`.
+ *
+ * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
+ * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
+ * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
+ *
+ * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
+ * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
+ * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
+ * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
+ * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
+ * behaviour the library never shipped. Do not reintroduce one.
+ *
+ * Exact to 2^53, which covers any auto-increment id. A caller who needs more passes their own
+ * `types` in the pool options: it is spread after this one and therefore wins. For a decimal, the
+ * lighter escape hatch is the declaration itself: `@Field({ type: String, columnType: 'decimal' })`
+ * keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ */
+export declare function numericTypes(types: PgTypes): CustomTypesConfig;
+export {};

package/dist/postgres/pgNumericTypes.js

@@ -0,0 +1,35 @@
+/**
+ * Decode `INT8` and `FLOAT8` as JS numbers, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
+ * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
+ * JS number is, so decoding it loses nothing at all.
+ *
+ * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
+ * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
+ * types belong here and which need the entity's declaration is settled in `hydratableFields`.
+ *
+ * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
+ * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
+ * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
+ *
+ * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
+ * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
+ * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
+ * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
+ * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
+ * behaviour the library never shipped. Do not reintroduce one.
+ *
+ * Exact to 2^53, which covers any auto-increment id. A caller who needs more passes their own
+ * `types` in the pool options: it is spread after this one and therefore wins. For a decimal, the
+ * lighter escape hatch is the declaration itself: `@Field({ type: String, columnType: 'decimal' })`
+ * keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ */
+export function numericTypes(types) {
+    // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
+    const textNumeric = new Set([types.builtins['INT8'], types.builtins['FLOAT8']]);
+    return {
+        getTypeParser: (oid, format) => format === 'text' && textNumeric.has(oid) ? Number : types.getTypeParser(oid, format),
+    };
+}

package/dist/postgres/pgQuerierPool.d.ts

@@ -6,5 +6,5 @@ import { PgQuerier } from './pgQuerier.js';
 export declare class PgQuerierPool extends AbstractPgQuerierPool<PoolClient, PgQuerier, PgDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<PgQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): PgQuerier;
 }

package/dist/postgres/pgQuerierPool.js

@@ -1,14 +1,15 @@
-import { Pool } from 'pg';
+import { Pool, types } from 'pg';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
 import { PgDialect } from './pgDialect.js';
+import { numericTypes } from './pgNumericTypes.js';
 import { PgQuerier } from './pgQuerier.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PgDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, ...opts }), extra);
+        super(new PgDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new PgQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new PgQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/querier/abstractQuerier.d.ts

@@ -6,9 +6,6 @@ import { LoggerWrapper } from '../util/index.js';
  */
 export declare abstract class AbstractQuerier implements Querier {
     readonly extra?: ExtraOptions | undefined;
-    private static readonly emittedWarnings;
-    /** Clears process-wide warning deduplication. For tests only. */
-    static clearEmittedWarningsForTests(): void;
     /**
      * Internal promise used to queue database operations.
      * This ensures that each operation is executed serially, preventing race conditions

package/dist/querier/abstractQuerier.js

@@ -7,11 +7,6 @@ import { enrichError } from './queryError.js';
  */
 export class AbstractQuerier {
     extra;
-    static emittedWarnings = new Set();
-    /** Clears process-wide warning deduplication. For tests only. */
-    static clearEmittedWarningsForTests() {
-        AbstractQuerier.emittedWarnings.clear();
-    }
     /**
      * Internal promise used to queue database operations.
      * This ensures that each operation is executed serially, preventing race conditions
@@ -207,8 +202,13 @@ export class AbstractQuerier {
         const throughMeta = getMeta(throughEntity);
         const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === relOpts.references[1].local));
         const ids = payload.map((it) => it[meta.id]);
+        // A relation query names the target's columns, not the join table's, so the projection and the
+        // filter belong on the populate below - resolved there against the entity that has them. Spread
+        // onto the through query they asked `ItemTag` for `Tag`'s columns: `$where`/`$sort` failed with
+        // "no such column", and `$exclude` collided with the `$select` this builds.
+        const { $select: _select, $exclude: _exclude, $where: _where, ...throughQuery } = relationQuery;
         const throughFounds = await this.findMany(throughEntity, {
-            ...relationQuery,
+            ...throughQuery,
             $select: {
                 [localField]: true,
             },
@@ -219,7 +219,6 @@ export class AbstractQuerier {
                 },
             },
             $where: {
-                ...relationQuery.$where,
                 [localField]: ids,
             },
         });
@@ -231,12 +230,14 @@ export class AbstractQuerier {
     }
     async fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity) {
         const foreignField = relOpts.references[0].foreign;
-        // Ensure the FK column is selected so putChildrenInParents can group by it; skips the raw-array
-        // `$select` form (nothing to augment). Mutates the same object asSelectMap returns.
+        // The FK is what putChildrenInParents groups on, so it outlives the relation's projection
+        // either way: added to a whitelisting `$select` (the raw-array form has nothing to augment),
+        // dropped from a subtractive `$exclude`. `relationQuery` is already a clone.
         const select = asSelectMap(relationQuery.$select);
         if (select && !select[foreignField]) {
             select[foreignField] = true;
         }
+        delete relationQuery.$exclude?.[foreignField];
         const ids = payload.map((it) => it[meta.id]);
         relationQuery.$where = { ...relationQuery.$where, [foreignField]: ids };
         const founds = await this.findMany(relEntity, relationQuery);

package/dist/querier/abstractSqlQuerier.d.ts

@@ -41,8 +41,15 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * Drivers with native cursor/streaming APIs (SQLite, Pg) should override this.
      */
     protected internalStream<T>(query: string, values?: unknown[]): AsyncIterable<T>;
-    private hydrateJsonFields;
-    private hydrateJsonFieldsRecursive;
+    /**
+     * Turn what a driver returned back into the types the entity declares, for the row and everything
+     * populated under it. Which columns, and as what, is `hydratableFields`; the per-cell decode is
+     * `decodeColumn`. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
+     *
+     * `visited` guards a populated graph that points back at itself; it defaults rather than living in
+     * a separate entry-point wrapper, because the wrapper's whole body was seeding it.
+     */
+    private hydrateFields;
     protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;