@memberjunction/core 5.51.0 → 6.1.0-edge.1

package/dist/generic/relatedRecordBatchLoader.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Batched child-collection loading for result sets.
+ *
+ * Populates a named {@link RelatedRecordCollection} across every row of a `RunView` result using **one**
+ * query per collection, rather than one per row.
+ *
+ * ## The N+1 this exists to prevent
+ *
+ * The intuitive way to make children load automatically is to do it in `BaseEntity.LoadFromData()`.
+ * That method is also how every row of `RunView(ResultType:'entity_object')` is materialised, so the
+ * intuitive implementation silently multiplies a single view into one child query per row. This is
+ * not theoretical: `JournalEntryEntityServer.LoadFromData()` overrides the method to call
+ * `LoadLines()`, so listing 500 journal entries issues 500 line queries — plus another 500 for line
+ * dimensions.
+ *
+ * Companion eager loading is therefore excluded from `LoadFromData()` by design, and set-oriented
+ * loading goes through here: gather every parent key, issue one `WHERE fk IN (...)`, bucket the rows
+ * by parent, and hand each parent its own slice.
+ *
+ * @module @memberjunction/core
+ */
+import { RelatedRecordCollection } from './relatedRecordCollection.js';
+import { LogError } from './logging.js';
+/**
+ * Populates the named child collections across a set of already-materialised parent entities.
+ *
+ * Unknown collection names are logged and skipped rather than thrown, so a caller asking for a
+ * collection that a particular subclass does not declare degrades to "no children loaded" instead of
+ * failing the whole view.
+ *
+ * @param parents - The entity objects returned by the view. Entities that do not declare a named
+ *                  collection are left untouched.
+ * @param collectionNames - The companion names to populate.
+ * @param provider - The provider used to issue the batched queries.
+ * @param contextUser - The acting user, required server-side.
+ */
+export async function LoadRelatedRecordsBatched(parents, collectionNames, provider, contextUser) {
+    if (!parents?.length || !collectionNames?.length) {
+        return;
+    }
+    for (const name of collectionNames) {
+        await loadOneCollectionBatched(parents, name, provider, contextUser);
+    }
+}
+/**
+ * Populates a single named collection across all parents with one query.
+ *
+ * @param parents - The parent entities.
+ * @param collectionName - The companion name to populate.
+ * @param provider - The provider used to issue the query.
+ * @param contextUser - The acting user.
+ */
+async function loadOneCollectionBatched(parents, collectionName, provider, contextUser) {
+    // Use the first parent that actually declares the collection to read its configuration. Parents
+    // in one result set are the same entity, but a mixed set (or a subclass that conditionally
+    // declares) should not take the whole load down.
+    const template = parents
+        .map(p => p.GetCompanion(collectionName))
+        .find((c) => c instanceof RelatedRecordCollection);
+    if (!template) {
+        LogError(`RunView.IncludeRelatedRecords: no RelatedRecordCollection named '${collectionName}' is declared on ` +
+            `${parents[0]?.EntityInfo?.Name ?? 'the returned entity'}; skipping.`);
+        return;
+    }
+    const foreignKey = template.RelatedEntityJoinField;
+    const parentKeys = collectParentKeys(parents);
+    if (parentKeys.length === 0) {
+        return;
+    }
+    const result = await provider.RunView({
+        EntityName: template.RelatedEntityName,
+        ExtraFilter: `${foreignKey} IN (${parentKeys.map(k => `'${escapeSQLLiteral(k)}'`).join(',')})`,
+        OrderBy: template.OrderByClause,
+        ResultType: 'entity_object',
+    }, contextUser);
+    if (!result.Success) {
+        // Loud: quietly handing back empty collections would make populated parents look childless,
+        // and anything derived from that — a total, a reversal, a validation decision — is then
+        // wrong in a way nothing downstream can detect.
+        throw new Error(`RunView.IncludeRelatedRecords: failed to batch-load '${collectionName}' ` +
+            `(${template.RelatedEntityName}): ${result.ErrorMessage ?? 'unknown error'}`);
+    }
+    distributeChildren(parents, collectionName, foreignKey, result.Results ?? []);
+}
+/**
+ * Buckets loaded children by their foreign key and hands each parent its own slice.
+ *
+ * Every parent that declares the collection is assigned a slice — including an empty one. Assigning
+ * empty matters: it marks the collection as loaded, so a later `Items` read is known-empty rather
+ * than not-yet-loaded.
+ *
+ * @param parents - The parent entities.
+ * @param collectionName - The companion name being populated.
+ * @param foreignKey - The child field pointing back at the parent.
+ * @param children - All loaded children across every parent.
+ */
+function distributeChildren(parents, collectionName, foreignKey, children) {
+    const byParent = new Map();
+    for (const child of children) {
+        // Case-insensitive keying: MJ primary keys are UUIDs, and their casing is not guaranteed to
+        // survive a round trip identically on every platform.
+        const key = normalizeKey(child.Get(foreignKey));
+        const bucket = byParent.get(key);
+        if (bucket) {
+            bucket.push(child);
+        }
+        else {
+            byParent.set(key, [child]);
+        }
+    }
+    for (const parent of parents) {
+        const collection = parent.GetCompanion(collectionName);
+        if (!(collection instanceof RelatedRecordCollection)) {
+            continue;
+        }
+        const key = normalizeKey(parent.FirstPrimaryKey?.Value);
+        collection.SetLoadedItems(byParent.get(key) ?? []);
+    }
+}
+/**
+ * Collects the distinct primary-key values of the parents, skipping unsaved ones.
+ *
+ * @param parents - The parent entities.
+ * @returns Distinct key values as strings.
+ */
+function collectParentKeys(parents) {
+    const keys = new Set();
+    for (const parent of parents) {
+        const value = parent.FirstPrimaryKey?.Value;
+        if (value !== null && value !== undefined && value !== '') {
+            keys.add(String(value));
+        }
+    }
+    return Array.from(keys);
+}
+/**
+ * Normalises a key value for map lookups — string form, lower-cased, trimmed.
+ *
+ * @param value - The raw key value.
+ * @returns The normalised key.
+ */
+function normalizeKey(value) {
+    return String(value ?? '').trim().toLowerCase();
+}
+/**
+ * Escapes a value for safe inclusion in a single-quoted SQL literal.
+ *
+ * @param value - The raw value.
+ * @returns The escaped value.
+ */
+function escapeSQLLiteral(value) {
+    return value.replace(/'/g, "''");
+}
+//# sourceMappingURL=relatedRecordBatchLoader.js.map

package/dist/generic/relatedRecordBatchLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relatedRecordBatchLoader.js","sourceRoot":"","sources":["../../src/generic/relatedRecordBatchLoader.ts"],"names":[],"mappings":"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"}