turbine-orm 0.27.0 → 0.28.0

package/dist/cjs/query/batched-loader.js

@@ -51,6 +51,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.includeKeysForBatching = includeKeysForBatching;
 exports.stripFields = stripFields;
 exports.neededParentKeyFields = neededParentKeyFields;
+exports.resolveCountRelations = resolveCountRelations;
 exports.loadRelationsBatched = loadRelationsBatched;
 const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
@@ -120,6 +121,14 @@ function neededParentKeyFields(parentMeta, withClause) {
     for (const [relName, spec] of Object.entries(withClause)) {
         if (!spec)
             continue;
+        // `_count` needs each counted relation's parent-side key to stitch counts.
+        if (relName === '_count') {
+            for (const rel of resolveCountRelations(parentMeta, spec)) {
+                for (const col of localKeyColumns(rel))
+                    fields.add(parentMeta.reverseColumnMap[col] ?? col);
+            }
+            continue;
+        }
         const rel = parentMeta.relations[relName];
         if (!rel)
             continue; // unknown relation — the join path throws; let the loader surface it
@@ -140,6 +149,37 @@ function localKeyColumns(rel) {
         return (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
     return (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
 }
+/**
+ * Resolve the set of to-many relations a `_count` spec selects. `true` counts
+ * every to-many relation (hasMany + manyToMany) of the table; the record form
+ * counts only the enabled names. Shared by the join builder and the batched
+ * loader so both count the exact same relations.
+ *
+ * Errors: E005 ({@link RelationError}) for an unknown relation name, E003
+ * ({@link ValidationError}) when a named relation is to-one.
+ */
+function resolveCountRelations(parentMeta, countSpec) {
+    const isToMany = (r) => r.type === 'hasMany' || r.type === 'manyToMany';
+    if (countSpec === true) {
+        return Object.values(parentMeta.relations).filter(isToMany);
+    }
+    const out = [];
+    for (const [relName, enabled] of Object.entries(countSpec)) {
+        if (!enabled)
+            continue;
+        const rel = parentMeta.relations[relName];
+        if (!rel) {
+            throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in _count on table "${parentMeta.name}". ` +
+                `Available: ${Object.keys(parentMeta.relations).join(', ')}`);
+        }
+        if (!isToMany(rel)) {
+            throw new errors_js_1.ValidationError(`[turbine] _count is only supported for to-many relations; "${relName}" on ` +
+                `"${parentMeta.name}" is a to-one relation.`);
+        }
+        out.push(rel);
+    }
+    return out;
+}
 /** Stringified stitch key — robust to number/uuid/bigint type drift across a join. */
 function keyOf(value) {
     return String(value);
@@ -161,6 +201,11 @@ async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0
     for (const [relName, spec] of Object.entries(withClause)) {
         if (!spec)
             continue;
+        // Reserved `_count` key — one grouped COUNT(*) follow-up per counted relation.
+        if (relName === '_count') {
+            loads.push(loadCounts(ctx, parents, spec));
+            continue;
+        }
         const rel = ctx.parentMeta.relations[relName];
         if (!rel) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
@@ -215,6 +260,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
             select: proj.select,
             omit: proj.omit,
             orderBy: options.orderBy,
+            skipGlobalFilters: ctx.skipGlobalFilters,
         });
         const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
         return deferred.transform(result);
@@ -313,6 +359,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
             select: proj.select,
             omit: proj.omit,
             orderBy: options.orderBy,
+            skipGlobalFilters: ctx.skipGlobalFilters,
         });
         const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
         return deferred.transform(result);
@@ -347,6 +394,107 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     }
     stripFields(targetsInOrder, proj.strip);
 }
+/**
+ * Load correlated `_count` values for the counted relations. One grouped
+ * follow-up per relation (`SELECT key, COUNT(*) … WHERE key = ANY($1) GROUP BY
+ * key`), attached onto each parent's `_count` object (0 when a parent has no
+ * matching rows) — byte-identical to the join strategy's `_count` output.
+ */
+async function loadCounts(ctx, parents, countSpec) {
+    const rels = resolveCountRelations(ctx.parentMeta, countSpec);
+    // Initialise every parent's `_count` up-front so the concurrent per-relation
+    // loads below (each writing its own key) never race on the object creation.
+    for (const parent of parents) {
+        if (parent._count === undefined)
+            parent._count = {};
+    }
+    await Promise.all(rels.map((rel) => loadOneCount(ctx, parents, rel)));
+}
+/** One grouped COUNT(*) follow-up for a single to-many relation. */
+async function loadOneCount(ctx, parents, rel) {
+    let parentKeyCol;
+    let childTable;
+    let childKeyCol;
+    if (rel.type === 'manyToMany') {
+        const through = rel.through;
+        if (!through) {
+            throw new errors_js_1.ValidationError(`[turbine] manyToMany relation "${rel.name}" is missing its junction (\`through\`).`);
+        }
+        const sourceRef = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+        const sourceJ = (0, schema_js_1.normalizeKeyColumns)(through.sourceKey);
+        if (sourceRef.length > 1 || sourceJ.length > 1) {
+            throw new errors_js_1.UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}" — use the default 'join' strategy for composite-key m2m _count`);
+        }
+        parentKeyCol = sourceRef[0];
+        childTable = through.table;
+        childKeyCol = sourceJ[0];
+    }
+    else {
+        // hasMany: child FK correlates to the parent reference key.
+        const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+        const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+        if (fk.length > 1 || rk.length > 1) {
+            throw new errors_js_1.UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}" — use the default 'join' strategy for composite-key _count`);
+        }
+        parentKeyCol = rk[0];
+        childTable = rel.to;
+        childKeyCol = fk[0];
+    }
+    const parentKeyField = ctx.parentMeta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
+    const keys = uniqueKeys(parents, parentKeyField);
+    const counts = new Map();
+    if (keys.length > 0) {
+        const qChild = ctx.quote(childTable);
+        const qKey = ctx.quote(childKeyCol);
+        const chunks = [];
+        for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
+            chunks.push(keys.slice(i, i + MAX_RELATION_KEYS));
+        // Global filter on the counted target, matching the join strategy so the
+        // two strategies return identical counts under a filter. hasMany filters
+        // the counted table directly; m2m counts junction rows but restricts them
+        // to junction rows whose TARGET survives the target table's filter via
+        // EXISTS — mirroring buildRelationCountExpr's EXISTS-on-target (which also
+        // skips the filter when the junction targetKey arity doesn't match the
+        // target PK). Rendered after the $1 key array.
+        let gf = null;
+        if (ctx.tableGlobalFilter) {
+            if (rel.type === 'manyToMany' && rel.through) {
+                const targetKeys = (0, schema_js_1.normalizeKeyColumns)(rel.through.targetKey);
+                const targetMeta = ctx.schema.tables[rel.to];
+                const pk = targetMeta?.primaryKey ?? [];
+                if (targetMeta && pk.length > 0 && pk.length === targetKeys.length) {
+                    const targetGf = ctx.tableGlobalFilter(rel.to, 't', 1);
+                    if (targetGf) {
+                        const join = targetKeys.map((jc, i) => `t.${ctx.quote(pk[i])} = ${qChild}.${ctx.quote(jc)}`).join(' AND ');
+                        gf = {
+                            clause: `EXISTS (SELECT 1 FROM ${ctx.quote(rel.to)} t WHERE ${join} AND ${targetGf.clause})`,
+                            params: targetGf.params,
+                        };
+                    }
+                }
+            }
+            else if (rel.type !== 'manyToMany') {
+                gf = ctx.tableGlobalFilter(childTable, qChild, 1);
+            }
+        }
+        const gfAnd = gf ? ` AND ${gf.clause}` : '';
+        const results = await Promise.all(chunks.map((chunk) => {
+            const params = [ctx.inClauseParam(chunk), ...(gf ? gf.params : [])];
+            const predicate = ctx.buildInClause(`${qChild}.${qKey}`, ctx.paramPlaceholder(1), false);
+            const sql = `SELECT ${qChild}.${qKey} AS "k", COUNT(*) AS "c" FROM ${qChild} ` +
+                `WHERE ${predicate}${gfAnd} GROUP BY ${qChild}.${qKey}`;
+            return ctx.exec(sql, params);
+        }));
+        for (const { rows } of results) {
+            for (const row of rows) {
+                counts.set(keyOf(row.k), Number(row.c));
+            }
+        }
+    }
+    for (const parent of parents) {
+        parent._count[rel.name] = counts.get(keyOf(parent[parentKeyField])) ?? 0;
+    }
+}
 // ---------------------------------------------------------------------------
 // Small helpers
 // ---------------------------------------------------------------------------