uql-orm 0.55.0 → 0.57.0

package/dist/querier/abstractQuerier.js

@@ -1,7 +1,6 @@
-import { assertSoleId, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
-import { asSelectMap, childrenOf, clone, dataKeyed, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { assertSoleId, getMeta, idOf, namesKey, relationOf, soleIdOf } from '../entity/index.js';
+import { childrenOf, clone, entityName, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
-import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
  * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
  * `{ $where: { id } }`, and a key compared to `undefined` is *no filter*, so an unchecked one
@@ -78,13 +77,10 @@ export class AbstractQuerier {
     logger;
     constructor(extra) {
         this.extra = extra;
-        this.logger = new LoggerWrapper(extra?.logger, {
-            logValues: extra?.logValues,
-            slowQuery: extra?.slowQuery,
-        });
+        this.logger = queryLoggerFor(extra);
     }
     validateProjectionQuery(entity, q) {
-        this.validateProjectionQueryRecursive(entity, q, getMeta(entity).name ?? entity.name);
+        this.validateProjectionQueryRecursive(entity, q, entityName(getMeta(entity)));
     }
     validateProjectionQueryRecursive(entity, q, path) {
         const meta = getMeta(entity);
@@ -96,9 +92,7 @@ export class AbstractQuerier {
             }
         }
         forEachRequestedRelation(meta, q.$populate, (relKey, relValue) => {
-            const relOpts = meta.relations[relKey];
-            if (!relOpts)
-                return;
+            const relOpts = relationOf(meta, relKey);
             const relEntity = relOpts.entity();
             const parsed = parseRelationQueryValue(relValue);
             if (parsed.nested) {
@@ -135,9 +129,12 @@ export class AbstractQuerier {
     async findMany(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
         this.validateProjectionQuery(entity, q);
-        const founds = await this.internalFindMany(entity, withIdForCounts(entity, q), opts);
-        await fillRelationCounts(this, entity, founds, q.$count);
-        await this.emitHook(entity, 'afterLoad', founds);
+        const founds = await this.internalFindMany(entity, q, opts);
+        // Guarded here rather than only inside: awaiting a call that returns at once still costs every read
+        // a promise and a turn of the microtask queue, and most reads hook nothing.
+        if (this.listensForLoad(entity, q.$populate)) {
+            await this.emitLoaded(entity, founds, q.$populate);
+        }
         return founds;
     }
     findManyStream(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
@@ -148,9 +145,10 @@ export class AbstractQuerier {
     async findManyAndCount(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
         this.validateProjectionQuery(entity, q);
-        const [founds, count] = await this.internalFindManyAndCount(entity, withIdForCounts(entity, q), opts);
-        await fillRelationCounts(this, entity, founds, q.$count);
-        await this.emitHook(entity, 'afterLoad', founds);
+        const [founds, count] = await this.internalFindManyAndCount(entity, q, opts);
+        if (this.listensForLoad(entity, q.$populate)) {
+            await this.emitLoaded(entity, founds, q.$populate);
+        }
         return [founds, count];
     }
     /**
@@ -341,125 +339,6 @@ export class AbstractQuerier {
         await (toInsert.length && toUpsert.length ? this.transaction(write) : write());
         return ids;
     }
-    async fillToManyRelations(entity, payload, populate) {
-        if (!payload.length) {
-            return;
-        }
-        const meta = getMeta(entity);
-        const relKeys = getRelationRequestSummary(meta, populate).toManyKeys;
-        for (const relKey of relKeys) {
-            const relOpts = meta.relations[relKey];
-            if (!relOpts)
-                continue;
-            const relEntity = relOpts.entity();
-            const relationQuery = clone(parseRelationAtKey(relKey, populate).query);
-            if (relOpts.through) {
-                await this.fillToManyThroughRelation(payload, meta, relKey, relOpts, relationQuery);
-            }
-            else if (relOpts.cardinality === '1m') {
-                await this.fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity);
-            }
-        }
-    }
-    async fillToManyThroughRelation(payload, meta, relKey, relOpts, relationQuery) {
-        const joins = parentJoins(relOpts, meta.ids.length);
-        const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
-        const throughEntity = relOpts.through();
-        const throughMeta = getMeta(throughEntity);
-        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === targetColumn));
-        if (!targetRelKey) {
-            // Asserted rather than assumed: used as a key regardless, it spells the literal string
-            // `undefined`, and the statement asks the junction for a relation of that name.
-            throw new TypeError(`'${meta.name}.${relKey}' goes through '${throughMeta.name}', which declares no relation on its ` +
-                `'${targetColumn}' column. Give it one, so the target's rows can be read through it.`);
-        }
-        // A relation query names the target's columns, not the junction's, so its projection and filter
-        // belong on the populate below, resolved against the entity that has them. Spread onto the
-        // junction query instead they asked `ItemTag` for `Tag`'s columns and failed with "no such
-        // column".
-        //
-        // Ordering and paging split the other way: they describe the statement with one row per pairing,
-        // which is the junction's. Left on the populate they reached a to-one join, which rejects all
-        // four by name - so a many-to-many carrying any of them threw rather than paging.
-        //
-        // Those four are not a coincidence: they are exactly the clauses a joined relation rejects, for
-        // the same reason - each needs a statement with many rows per parent, which only the junction's
-        // is. The `satisfies` ties the two lists together, so a fifth clause added there fails to compile
-        // here rather than quietly staying on the populate and throwing again.
-        const { $sort, $limit, $skip, $distinct, ...targetQuery } = relationQuery;
-        const junctionClauses = {
-            $limit,
-            $skip,
-            $distinct,
-            // Qualified by the relation that reaches them, since the columns it names are the target's.
-            $sort: $sort && { [targetRelKey]: $sort },
-        };
-        const junctionQuery = {
-            $select: joinedColumns(joins),
-            ...junctionClauses,
-            $populate: {
-                [targetRelKey]: {
-                    ...targetQuery,
-                    $required: true,
-                },
-            },
-        };
-        const throughFounds = await this.findChildrenOf(throughEntity, junctionQuery, joins, payload, meta.fields);
-        // The junction's own columns carried onto the target's row, which is where `putChildrenInParents`
-        // reads them back from - a junction row holds the parent's key under `joined`, not under `parent`.
-        const founds = throughFounds.map((it) => ({
-            ...it[targetRelKey],
-            ...Object.fromEntries(joins.map(({ joined }) => [joined, it[joined]])),
-        }));
-        this.putChildrenInParents(payload, founds, joins, relKey);
-    }
-    async fillToManyOneToMany(payload, meta, relKey, relOpts, relationQuery, relEntity) {
-        const joins = parentJoins(relOpts, meta.ids.length);
-        // 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);
-        const exclude = relationQuery.$exclude;
-        for (const { joined } of joins) {
-            if (select && !select[joined]) {
-                select[joined] = true;
-            }
-            delete exclude?.[joined];
-        }
-        this.putChildrenInParents(payload, await this.findChildrenOf(relEntity, relationQuery, joins, payload, meta.fields), joins, relKey);
-    }
-    /**
-     * The children of a whole page of parents, however the relation asked for them: one bounded branch
-     * per parent when it wants a share of its own, otherwise a single flat statement over an `IN (...)`
-     * list, which is both correct and cheaper.
-     *
-     * The one place that decision is made - a one-to-many and the junction of a many-to-many differ in
-     * what they query, never in how the page is spread over its parents.
-     */
-    async findChildrenOf(entity, query, joins, parents, parentFields) {
-        const founds = isBoundedPerParent(query)
-            ? await this.internalFindManyPerParent(entity, query, { joins, parents, parentFields })
-            : await this.findMany(entity, queryChildrenOfAll(query, joins, parents));
-        // Read back as rows rather than as the entity they hydrate to: what follows regroups them by the
-        // join columns, which a projected entity type does not carry.
-        return founds;
-    }
-    putChildrenInParents(parents, children, joins, relKey) {
-        const childrenByParentId = dataKeyed();
-        // Every joined column, so two children agreeing on one column of a composite key are not
-        // gathered under the same parent. Both column lists are read once, not once per row.
-        const joinedKeys = keyColumns(joins, 'joined');
-        const parentKeys = keyColumns(joins, 'parent');
-        for (const child of children) {
-            (childrenByParentId[rowKey(child, joinedKeys)] ??= []).push(child);
-        }
-        for (const parent of parents) {
-            // `[]` rather than nothing for a parent with no children: a populated to-many is a list the
-            // caller asked for, so it maps and counts without a guard, and its type can say so. An
-            // unpopulated one stays absent, which is what tells the two apart.
-            parent[relKey] = (childrenByParentId[rowKey(parent, parentKeys)] ?? []);
-        }
-    }
     async insertRelations(entity, payload) {
         const meta = getMeta(entity);
         const entries = payload.reduce((acc, it) => {
@@ -498,9 +377,7 @@ export class AbstractQuerier {
         const relKeys = filterPersistableRelationKeys(meta, meta.relations, 'delete');
         // Cascade forwards `opts` (including `hardDelete`); each child soft-deletes only if it can.
         for (const relKey of relKeys) {
-            const relOpts = meta.relations[relKey];
-            if (!relOpts)
-                continue;
+            const relOpts = relationOf(meta, relKey);
             const relEntity = relOpts.entity();
             const target = relOpts.through ? relOpts.through() : relEntity;
             const where = childrenOf(parentJoins(relOpts, meta.ids.length), ids);
@@ -514,9 +391,7 @@ export class AbstractQuerier {
      */
     async saveRelation(entity, ids, relValue, relKey, isUpdate) {
         const meta = getMeta(entity);
-        const relOpts = meta.relations[relKey];
-        if (!relOpts)
-            return;
+        const relOpts = relationOf(meta, relKey);
         // Here rather than only in the callers below: writing the parent's key into a child is one column
         // per key, so a composite takes a statement per parent. `soleParentColumn` and the sole
         // `targetKeyColumns` under it read the *first* pair, which is a real column of a wrong pairing
@@ -630,6 +505,32 @@ export class AbstractQuerier {
     hasHook(entity, event) {
         return (this.extra?.listeners?.some((listener) => listener[event]) || (getMeta(entity).hooks?.[event]?.length ?? 0) > 0);
     }
+    /** Whether an `afterLoad` listens on the entity a read returns or on any relation it populated. */
+    listensForLoad(entity, populate) {
+        if (this.hasHook(entity, 'afterLoad')) {
+            return true;
+        }
+        const meta = getMeta(entity);
+        return getRelationRequestSummary(meta, populate).requestedKeys.some((relKey) => this.listensForLoad(relationOf(meta, relKey).entity(), parseRelationAtKey(relKey, populate).query.$populate));
+    }
+    /**
+     * `afterLoad` for every row a read loaded, a populated relation's before the rows holding them, so a
+     * parent's hook sees its children as their own hooks left them. Rows are walked only where a hook
+     * listens.
+     */
+    async emitLoaded(entity, rows, populate) {
+        const meta = getMeta(entity);
+        for (const relKey of getRelationRequestSummary(meta, populate).requestedKeys) {
+            const relEntity = relationOf(meta, relKey).entity();
+            const relPopulate = parseRelationAtKey(relKey, populate).query.$populate;
+            if (this.listensForLoad(relEntity, relPopulate)) {
+                // A to-many holds a list and a to-one a row, which `flatMap` takes alike; an absent one adds none.
+                const loaded = rows.flatMap((row) => row[relKey] ?? []);
+                await this.emitLoaded(relEntity, loaded, relPopulate);
+            }
+        }
+        await this.emitHook(entity, 'afterLoad', rows);
+    }
     /**
      * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
      * not report them in payload order. A row that no read row matches, or that two do, keeps
@@ -684,7 +585,7 @@ export class AbstractQuerier {
      * another one would wait for a task queued behind itself. Callers below keep their `serialize` calls
      * sequential rather than nested.
      */
-    async serialize(task) {
+    serialize(task) {
         const res = this.taskQueue.then(task);
         this.taskQueue = res.catch(() => { });
         return res;

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -31,7 +31,7 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
      * The connection outlives the call here: it is held until the iterator is drained or closed by a
      * `break`/`throw`. Abandoning the iterator instead leaks it until GC, so consume it in a `for await`.
      */
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncGenerator<QueryFindResult<E, S, V, X, P>>;
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncGenerator<QueryFindResult<E, S, V, X, P, C>>;
     findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P, C>[], number]>;
     count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: QueryOptions): Promise<number>;
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,6 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
-import { type ParentPartition } from '../util/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
@@ -58,19 +57,6 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     private applyVectorTuning;
     protected internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
-    /**
-     * One bounded subquery per parent, concatenated with `UNION ALL`, so each parent gets its own
-     * `$limit` rather than a share of one. Universal, and reads `parents x (skip + limit)` rows where a
-     * `ROW_NUMBER` window reads every matching child. [The design](../../../../architecture/populate-limits.md).
-     *
-     * Each branch is a wrapped derived table: SQLite rejects `ORDER BY`/`LIMIT` on a bare parenthesised
-     * compound branch, and the wrapper costs nothing elsewhere.
-     *
-     * Unlike {@link selectRows} this asserts no lock and tunes no vector search: `$lock` and
-     * `$candidates` describe the statement, and `parseRelationQueryValue` refuses both on a relation
-     * query, so neither can reach here.
-     */
-    protected internalFindManyPerParent<E extends object>(entity: Type<E>, q: Query<E>, partition: ParentPartition): Promise<E[]>;
     /**
      * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
      * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
@@ -100,14 +86,17 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     protected internalStream<T>(query: string, values?: unknown[]): AsyncIterable<T>;
     /**
-     * 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, and makes a node two paths reach
-     * decode once. Only a relation can lead the walk back somewhere it has been, so an entity that
-     * declares none skips the guard rather than allocating a set per row to hold a single object -
-     * which cost more than the decoding it guards, on a flat read.
+     * Turn what a driver returned back into the types the entity declares, for every row and everything
+     * populated under them. Which columns, and as what, is `hydratableFields`, resolved once for all the
+     * rows; the per-cell decode is `decodeColumn`. Both live with the dialect, because a `sparsevec` is
+     * only sparse on Postgres.
+     */
+    private hydrateAll;
+    /**
+     * One row of {@link hydrateAll}. A related row arrives as its parent's statement read it: a to-one
+     * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
+     * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
+     * Each is an object of its own, so the walk reaches none twice.
      */
     private hydrateFields;
     /**

package/dist/querier/abstractSqlQuerier.js

@@ -1,7 +1,8 @@
 import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta, idOf, namesKey } from '../entity/index.js';
-import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { COUNT_RESULT_KEY } from '../type/index.js';
+import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, idOnlyQuery, isAutoIncrement, isPagedQuery, isRecord, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
 /**
@@ -153,24 +154,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
     }
     async internalFindMany(entity, q, opts) {
-        return this.hydrateRows(entity, q, await this.selectRows(entity, q, opts));
-    }
-    /**
-     * One bounded subquery per parent, concatenated with `UNION ALL`, so each parent gets its own
-     * `$limit` rather than a share of one. Universal, and reads `parents x (skip + limit)` rows where a
-     * `ROW_NUMBER` window reads every matching child. [The design](../../../../architecture/populate-limits.md).
-     *
-     * Each branch is a wrapped derived table: SQLite rejects `ORDER BY`/`LIMIT` on a bare parenthesised
-     * compound branch, and the wrapper costs nothing elsewhere.
-     *
-     * Unlike {@link selectRows} this asserts no lock and tunes no vector search: `$lock` and
-     * `$candidates` describe the statement, and `parseRelationQueryValue` refuses both on a relation
-     * query, so neither can reach here.
-     */
-    async internalFindManyPerParent(entity, q, partition) {
-        const ctx = this.dialect.createContext();
-        this.dialect.findPerParent(ctx, entity, q, partition);
-        return this.hydrateRows(entity, q, await this.all(ctx.sql, ctx.values));
+        return this.hydrateRows(entity, await this.selectRows(entity, q, opts));
     }
     /**
      * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
@@ -208,7 +192,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         for (const row of rows) {
             delete row[TOTAL_ALIAS];
         }
-        return [await this.hydrateRows(entity, q, rows), total];
+        return [this.hydrateRows(entity, rows), total];
     }
     async selectRows(entity, q, opts, totalAlias) {
         this.assertLockable(entity, q);
@@ -222,9 +206,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         this.dialect.find(ctx, entity, q, opts, totalAlias);
         return this.all(ctx.sql, ctx.values);
     }
-    async hydrateRows(entity, q, rows) {
-        const founds = unflatObjects(rows).map((row) => this.hydrateFields(entity, row));
-        await this.fillToManyRelations(entity, founds, q.$populate);
+    hydrateRows(entity, rows) {
+        const founds = unflatObjects(rows);
+        this.hydrateAll(entity, founds);
         return founds;
     }
     async *internalFindManyStream(entity, q, opts) {
@@ -234,10 +218,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             await this.applyVectorTuning(entity, q);
         }
         const meta = getMeta(entity);
-        const { toManyKeys } = getRelationRequestSummary(meta, q.$populate);
-        if (toManyKeys.length) {
-            throw new TypeError(`findManyStream does not load to-many relations (${toManyKeys.join(', ')}). Use findMany so fillToManyRelations can run, or omit those keys from the stream query.`);
-        }
         // The one path that does not go through `all`/`run`, so it connects on its own: streaming first on
         // a freshly acquired querier used to reach `getConn()` with nothing acquired.
         await this.lazyConnect();
@@ -245,11 +225,14 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // context holds was normalized as it was bound.
         const ctx = this.dialect.createContext();
         this.dialect.find(ctx, entity, q, opts);
+        const fields = this.dialect.hydratableFields(entity);
         let attrsPaths;
         try {
             for await (const row of this.internalStream(ctx.sql, ctx.values)) {
                 attrsPaths ??= obtainAttrsPaths(row);
-                yield this.hydrateFields(entity, unflatObject(row, attrsPaths));
+                const found = unflatObject(row, attrsPaths);
+                this.hydrateFields(meta, fields, found);
+                yield found;
             }
         }
         catch (err) {
@@ -265,53 +248,66 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         yield* await this.internalAll(query, values);
     }
     /**
-     * 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, and makes a node two paths reach
-     * decode once. Only a relation can lead the walk back somewhere it has been, so an entity that
-     * declares none skips the guard rather than allocating a set per row to hold a single object -
-     * which cost more than the decoding it guards, on a flat read.
+     * Turn what a driver returned back into the types the entity declares, for every row and everything
+     * populated under them. Which columns, and as what, is `hydratableFields`, resolved once for all the
+     * rows; the per-cell decode is `decodeColumn`. Both live with the dialect, because a `sparsevec` is
+     * only sparse on Postgres.
      */
-    hydrateFields(entity, dto, visited) {
-        if (!dto || typeof dto !== 'object' || visited?.has(dto)) {
-            return dto;
-        }
+    hydrateAll(entity, dtos) {
         const meta = getMeta(entity);
+        const fields = this.dialect.hydratableFields(entity);
+        for (const dto of dtos) {
+            this.hydrateFields(meta, fields, dto);
+        }
+    }
+    /**
+     * One row of {@link hydrateAll}. A related row arrives as its parent's statement read it: a to-one
+     * joined and unflattened, there only when its key is, since an unmatched join still fills a computed
+     * column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
+     * Each is an object of its own, so the walk reaches none twice.
+     */
+    hydrateFields(meta, fields, dto) {
         const row = dto;
-        for (const [key, kind] of this.dialect.hydratableFields(entity)) {
+        for (const [key, kind] of fields) {
             const value = row[key];
             if (value != null) {
                 row[key] = decodeColumn(value, kind);
             }
         }
-        // Allocated only where the walk can continue: an entity declaring no relation cannot lead back
-        // to a node already decoded, and the loop below is a no-op for it anyway.
-        if (hasKeys(meta.relations)) {
-            visited ??= new WeakSet();
+        // A tally read inside the statement comes back as its driver reads a COUNT, which on some is text.
+        const counts = row[COUNT_RESULT_KEY];
+        if (isRecord(counts)) {
+            for (const relKey in counts) {
+                counts[relKey] = Number(counts[relKey]);
+            }
         }
-        visited?.add(dto);
         // The value is read before the relation's target is resolved: a query that populated nothing
         // still walks every relation the entity declares, and `rel.entity()` is a call per row per
         // relation that only the populated ones need.
         for (const key in meta.relations) {
             const value = row[key];
-            if (!value || typeof value !== 'object')
+            if (!value)
                 continue;
             const rel = meta.relations[key];
             if (!rel)
                 continue;
             const relEntity = rel.entity();
-            if (Array.isArray(value)) {
-                for (const it of value) {
-                    this.hydrateFields(relEntity, it, visited);
+            if (typeof value === 'string' || Array.isArray(value)) {
+                // A to-many's rows, as flat as a statement's own.
+                const rows = unflatObjects(typeof value === 'string' ? JSON.parse(value) : value);
+                row[key] = rows;
+                this.hydrateAll(relEntity, rows);
+            }
+            else if (isRecord(value)) {
+                const relMeta = getMeta(relEntity);
+                if (value[relMeta.ids[0]] == null) {
+                    delete row[key];
+                }
+                else {
+                    this.hydrateFields(relMeta, this.dialect.hydratableFields(relEntity), value);
                 }
-                continue;
             }
-            this.hydrateFields(relEntity, value, visited);
         }
-        return dto;
     }
     /**
      * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and

package/dist/schema/canonicalType.js

@@ -6,7 +6,7 @@
  * - Canonical types (dialect-agnostic)
  * - TypeScript types (for entity generation)
  */
-import { columnFamily } from '../util/field.util.js';
+import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export function isVectorCategory(category) {
     return category === 'vector' || category === 'halfvec' || category === 'sparsevec';
@@ -395,9 +395,9 @@ export function fieldOptionsToCanonical(options) {
         case 'numeric':
             // BIGINT for every `Number` without a scale, key or not: a 32-bit column is a migration waiting
             // to happen, and the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
-            return type === Number && (options.precision || options.scale)
-                ? { category: 'decimal', precision: options.precision, scale: options.scale }
-                : { category: 'integer', size: 'big' };
+            return isIntegerColumn(options)
+                ? { category: 'integer', size: 'big' }
+                : { category: 'decimal', precision: options.precision, scale: options.scale };
         case 'boolean':
             return { category: 'boolean' };
         case 'date':
@@ -492,7 +492,5 @@ export function canonicalToColumnType(type) {
             return 'halfvec';
         case 'sparsevec':
             return 'sparsevec';
-        default:
-            return 'varchar';
     }
 }

package/dist/schema/dependencyGraph.js

@@ -38,11 +38,9 @@ export function findCycles(nodes, dependenciesOf) {
     const visited = new Set();
     const onPath = new Set();
     const visit = (node, path) => {
+        // A node on the walk was handed down in `path` too, so the cycle closes where it first appears.
         if (onPath.has(node)) {
-            const start = path.indexOf(node);
-            if (start !== -1) {
-                cycles.push(path.slice(start));
-            }
+            cycles.push(path.slice(path.indexOf(node)));
             return;
         }
         if (visited.has(node)) {

package/dist/schema/indexDifferences.js

@@ -61,20 +61,20 @@ export function describeIndexDifferences(source, target, facets) {
     if (comparableEntries) {
         const [sourceColumns, targetColumns] = [source.entries, target.entries].map((entries) => entries.map((entry) => entrySignature(entry, facets)).join(', '));
         if (sourceColumns !== targetColumns) {
-            differences.push(`columns: (${targetColumns}) → (${sourceColumns})`);
+            differences.push(`columns: (${targetColumns}) -> (${sourceColumns})`);
         }
     }
-    if ((source.unique ?? false) !== (target.unique ?? false)) {
-        differences.push(`unique: ${target.unique ?? false} → ${source.unique ?? false}`);
+    if (source.unique !== target.unique) {
+        differences.push(`unique: ${target.unique} -> ${source.unique}`);
     }
     if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
-        differences.push(`type: ${target.type ?? 'btree'} → ${source.type ?? 'btree'}`);
+        differences.push(`type: ${target.type ?? 'btree'} -> ${source.type ?? 'btree'}`);
     }
     if (facets.has('include')) {
         // Order carries no meaning in an `INCLUDE` list, so it is compared as a set.
         const [sourceInclude, targetInclude] = [source.include ?? [], target.include ?? []].map((columns) => [...columns].sort().join(', '));
         if (sourceInclude !== targetInclude) {
-            differences.push(`include: (${targetInclude}) → (${sourceInclude})`);
+            differences.push(`include: (${targetInclude}) -> (${sourceInclude})`);
         }
     }
     return differences;