@memberjunction/record-cloning 0.0.0 → 6.2.0-edge.2

package/dist/CloneMaterializer.js

@@ -0,0 +1,267 @@
+/**
+ * @file CloneMaterializer.ts
+ * Builds the in-memory entity graph for record cloning.
+ * Orchestrates collection routing (declared vs dynamic via DeclareRelatedRecordsDynamic),
+ * builds each row from NewRecord() plus the plan's field values, re-stamps join fields,
+ * and handles polymorphic IS-A child additions.
+ * @see plans/record-cloning/README.md §6, §13.1
+ */
+import { LogError, Metadata, RelatedRecordCollection, } from '@memberjunction/core';
+import { SingleKeyField, ToCompositeKey, ToRecordKeyString } from './CloneKeys.js';
+/** Writes every column of a planned target key (single or composite) onto the new row. */
+function applyTargetKey(entity, targetKey) {
+    if (!targetKey)
+        return; // server-assigned key
+    const ck = ToCompositeKey(entity.EntityInfo, targetKey);
+    for (const pair of ck.KeyValuePairs) {
+        // An empty column points at a parent whose key the database assigns; the save fills it in.
+        if (pair.Value === null || pair.Value === undefined || pair.Value === '')
+            continue;
+        entity.Set(pair.FieldName, pair.Value);
+    }
+}
+export class CloneMaterializer {
+    constructor(provider) {
+        this._provider = provider;
+    }
+    get Provider() {
+        return this._provider ?? Metadata.Provider;
+    }
+    /**
+     * Materializes a ClonePlan into memory.
+     */
+    async Materialize(plan, contextUser) {
+        const md = this.Provider;
+        const stagedEntities = new Map();
+        const sidecarEntities = [];
+        const prerequisiteEntities = [];
+        // 1. Build and Initialize Root
+        const rootPlanNode = plan.Nodes.find((n) => n.Depth === 0);
+        if (!rootPlanNode) {
+            throw new Error(`Plan contains no root node (Depth === 0).`);
+        }
+        const rootEntity = await md.GetEntityObject(rootPlanNode.EntityName, contextUser);
+        if (!rootEntity) {
+            throw new Error(`Failed to instantiate entity object for root '${rootPlanNode.EntityName}'.`);
+        }
+        rootEntity.NewRecord();
+        // The plan's field values are the whole row: excluded and denied fields keep the column default.
+        this.applyFieldChanges(rootEntity, rootPlanNode);
+        // Assign the planned target key (minted UUID or derived composite; none when server-assigned)
+        applyTargetKey(rootEntity, rootPlanNode.TargetKey);
+        const rootNodeKey = rootPlanNode.NodeKey ?? rootPlanNode.Key;
+        stagedEntities.set(rootNodeKey, rootEntity);
+        // Rows that point at another new row through a column other than their join field (a step
+        // path's DestinationStepID, a step's SubAgentID) can't save inside the root's graph save,
+        // which saves each row's children before its next sibling: the row they point at may not
+        // exist yet. They become sidecars, saved after the graph in dependency order.
+        const deferred = CloneMaterializer.rowsToDefer(plan);
+        const sidecarKeys = new Map();
+        // 2. Build Children by Depth (Depth 1, 2, ...)
+        const maxDepth = Math.max(...plan.Nodes.map((n) => n.Depth));
+        for (let d = 1; d <= maxDepth; d++) {
+            const nodesAtDepth = plan.Nodes.filter((n) => n.Depth === d && n.Action === 'Create');
+            for (const childNode of nodesAtDepth) {
+                const childNodeKey = childNode.NodeKey ?? childNode.Key;
+                // Find discovering edge pointing to this child
+                const edge = plan.Edges.find((e) => e.ToKey === childNodeKey && e.Policy === 'Deep');
+                if (!edge) {
+                    continue;
+                }
+                const parentEntity = stagedEntities.get(edge.FromKey);
+                if (!parentEntity) {
+                    throw new Error(`Parent entity not found in staged graph for edge '${edge.FromKey}' -> '${childNodeKey}'.`);
+                }
+                // Determine or establish collection companion
+                let childEntity;
+                if (edge.Kind === 'ForwardFK') {
+                    // ForwardFK targets are prerequisite entities that must exist before the parent entity can reference them
+                    childEntity = await md.GetEntityObject(childNode.EntityName, contextUser);
+                    childEntity.NewRecord();
+                    prerequisiteEntities.push(childEntity);
+                }
+                else {
+                    const collection = deferred.has(childNodeKey)
+                        ? null
+                        : this.resolveOrCreateCollection(parentEntity, childNode.EntityName, edge.JoinField, edge.RelationshipID);
+                    if (collection) {
+                        childEntity = await collection.Create();
+                    }
+                    else {
+                        // Sidecar route: a deferred row, or one whose collection can't be declared
+                        childEntity = await md.GetEntityObject(childNode.EntityName, contextUser);
+                        childEntity.NewRecord();
+                        sidecarEntities.push(childEntity);
+                        sidecarKeys.set(childEntity, childNodeKey);
+                    }
+                }
+                // The plan's field values are the whole row: excluded and denied fields keep the column default.
+                this.applyFieldChanges(childEntity, childNode);
+                // Assign the planned target key (minted UUID or derived composite; none when server-assigned)
+                applyTargetKey(childEntity, childNode.TargetKey);
+                // CRITICAL RULE (§6.7): Re-set the join field after the planned values.
+                // Foreign keys reference a single-column key, so both sides of the join use that column.
+                if (edge.Kind === 'ForwardFK') {
+                    // In a ForwardFK, parentEntity owns the FK pointing to childEntity
+                    const childKeyField = SingleKeyField(childEntity.EntityInfo, 'Pointing a row at its cloned prerequisite');
+                    parentEntity.Set(edge.JoinField, childEntity.Get(childKeyField));
+                }
+                else if (edge.Kind === 'SoftLink') {
+                    // Polymorphic EntityID/RecordID rows store the parent's record-id string, which
+                    // works for a composite parent key too.
+                    childEntity.Set(edge.JoinField, ToRecordKeyString(parentEntity.PrimaryKey));
+                }
+                else {
+                    const parentKeyField = SingleKeyField(parentEntity.EntityInfo, 'Joining a cloned child to its parent');
+                    childEntity.Set(edge.JoinField, parentEntity.Get(parentKeyField));
+                }
+                stagedEntities.set(childNodeKey, childEntity);
+            }
+        }
+        return {
+            RootEntity: rootEntity,
+            StagedEntities: stagedEntities,
+            SidecarEntities: CloneMaterializer.orderSidecars(plan, sidecarEntities, sidecarKeys),
+            DeferredNodeKeys: deferred,
+            PrerequisiteEntities: prerequisiteEntities,
+        };
+    }
+    /**
+     * Create rows with a remapped column, other than the join field to their parent, whose new
+     * value is another new row's key: they must save after that row, not inside the graph save.
+     */
+    static rowsToDefer(plan) {
+        const newRowByKey = CloneMaterializer.newRowsByTargetKey(plan);
+        const deferred = new Set();
+        for (const node of plan.Nodes) {
+            if (node.Depth === 0 || node.Action !== 'Create')
+                continue;
+            const nodeKey = node.NodeKey ?? node.Key;
+            const edge = plan.Edges.find((e) => e.ToKey === nodeKey && e.Policy === 'Deep');
+            if (!edge || edge.Kind === 'ForwardFK')
+                continue;
+            const pointsAtNewRow = CloneMaterializer.remappedTargets(node, edge.JoinField, newRowByKey).some((target) => target !== nodeKey);
+            if (pointsAtNewRow)
+                deferred.add(nodeKey);
+        }
+        return deferred;
+    }
+    /** New rows by their planned key, lower-cased, for matching a remapped column's value. */
+    static newRowsByTargetKey(plan) {
+        const byKey = new Map();
+        for (const node of plan.Nodes) {
+            if (node.Action !== 'Create')
+                continue;
+            const key = ToRecordKeyString(node.TargetKey);
+            if (key)
+                byKey.set(key.toLowerCase(), node.NodeKey ?? node.Key);
+        }
+        return byKey;
+    }
+    /** Plan nodes a row points at through remapped columns other than `joinField`. */
+    static remappedTargets(node, joinField, newRowByKey) {
+        const targets = [];
+        for (const change of node.FieldChanges) {
+            if (change.Kind !== 'Remap' || change.Field.toLowerCase() === joinField.toLowerCase())
+                continue;
+            if (typeof change.NewValue !== 'string')
+                continue;
+            const target = newRowByKey.get(change.NewValue.toLowerCase());
+            if (target)
+                targets.push(target);
+        }
+        return targets;
+    }
+    /**
+     * Sidecars in an order where each saves after the sidecars it depends on: its parent, when
+     * the parent is a sidecar too, and the new rows its remapped columns point at. Rows saved in
+     * the graph save come first anyway. Stable: independent sidecars keep their planned order.
+     */
+    static orderSidecars(plan, sidecars, keys) {
+        if (sidecars.length < 2)
+            return sidecars;
+        const newRowByKey = CloneMaterializer.newRowsByTargetKey(plan);
+        const sidecarKeys = new Set(keys.values());
+        const dependsOn = new Map();
+        for (const [, nodeKey] of keys) {
+            const node = plan.Nodes.find((n) => (n.NodeKey ?? n.Key) === nodeKey);
+            const edge = plan.Edges.find((e) => e.ToKey === nodeKey && e.Policy === 'Deep');
+            if (!node || !edge)
+                continue;
+            const deps = [edge.FromKey, ...CloneMaterializer.remappedTargets(node, edge.JoinField, newRowByKey)]
+                .filter((k) => k !== nodeKey && sidecarKeys.has(k));
+            dependsOn.set(nodeKey, deps);
+        }
+        const ordered = [];
+        const done = new Set();
+        const visiting = new Set();
+        const byKey = new Map([...keys].map(([entity, key]) => [key, entity]));
+        const visit = (key) => {
+            if (done.has(key) || visiting.has(key))
+                return; // a cycle can't all be inserted anyway; keep the planned order
+            visiting.add(key);
+            for (const dep of dependsOn.get(key) ?? [])
+                visit(dep);
+            visiting.delete(key);
+            done.add(key);
+            const entity = byKey.get(key);
+            if (entity)
+                ordered.push(entity);
+        };
+        for (const entity of sidecars) {
+            const key = keys.get(entity);
+            if (key)
+                visit(key);
+        }
+        return ordered;
+    }
+    /**
+     * Resolves an existing writable collection or declares a dynamic one on the parent entity.
+     */
+    resolveOrCreateCollection(parent, childEntityName, joinField, relationshipId) {
+        // 1. Check if parent already has a declared writable collection for this child
+        if (parent.HasCompanions) {
+            for (const companion of parent.Companions) {
+                if (companion instanceof RelatedRecordCollection) {
+                    if (companion.RelatedEntityName.toLowerCase() === childEntityName.toLowerCase() &&
+                        companion.RelatedEntityJoinField.toLowerCase() === joinField.toLowerCase() &&
+                        !companion.IsReadOnly) {
+                        return companion;
+                    }
+                }
+            }
+        }
+        // 2. Use DeclareRelatedRecordsDynamic to declare runtime collection companion
+        const dynamicCollectionName = `_mj_clone_${childEntityName.replace(/[^a-zA-Z0-9_]/g, '_')}_${joinField}`;
+        try {
+            return parent.DeclareRelatedRecordsDynamic({
+                Name: dynamicCollectionName,
+                RelatedEntity: childEntityName,
+                RelatedEntityJoinField: joinField,
+                Source: 'database',
+                ReadOnly: false,
+            });
+        }
+        catch (err) {
+            // The row still saves, but after the parent's transaction step rather than inside its
+            // save (the sidecar route). Say so: it is the line between the two routes.
+            LogError(`[RecordCloning] Could not declare ${childEntityName} rows as a collection of ${parent.EntityInfo?.Name ?? 'the parent'}; saving them as sidecars: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Writes the plan's field values in pipeline order, so later stages (reset, rename, remap,
+     * prompt) win over the copied value. Fields the plan excludes are never set.
+     */
+    applyFieldChanges(entity, planNode) {
+        for (const change of planNode.FieldChanges) {
+            if (change.Kind === 'Excluded' || change.Kind === 'NotWritable' || change.Kind === 'DeniedRead' || change.Kind === 'DeniedCreate') {
+                continue;
+            }
+            if (change.NewValue !== undefined) {
+                entity.Set(change.Field, change.NewValue);
+            }
+        }
+    }
+}
+//# sourceMappingURL=CloneMaterializer.js.map

package/dist/CloneMaterializer.js.map

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

package/dist/ClonePlanHash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file ClonePlanHash.ts
+ * SHA-256 of a clone plan's canonical form. The hash detects a plan that changed between review
+ * and Execute (`PLAN_CHANGED`); only the server computes it, and the browser echoes it back.
+ */
+import { ClonePlanHashInput } from '@memberjunction/record-cloning-base';
+/** Hex SHA-256 of `text`, encoded as UTF-8. */
+export declare function Sha256Hex(text: string): string;
+/** The plan hash: SHA-256 over `CanonicalPlanPayload`, which ignores target keys and masks encrypted values. */
+export declare function ComputeClonePlanHash(plan: ClonePlanHashInput): string;
+//# sourceMappingURL=ClonePlanHash.d.ts.map

package/dist/ClonePlanHash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePlanHash.d.ts","sourceRoot":"","sources":["../src/ClonePlanHash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAwB,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAE/F,+CAA+C;AAC/C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,gHAAgH;AAChH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAErE"}

package/dist/ClonePlanHash.js

@@ -0,0 +1,16 @@
+/**
+ * @file ClonePlanHash.ts
+ * SHA-256 of a clone plan's canonical form. The hash detects a plan that changed between review
+ * and Execute (`PLAN_CHANGED`); only the server computes it, and the browser echoes it back.
+ */
+import { createHash } from 'node:crypto';
+import { CanonicalPlanPayload } from '@memberjunction/record-cloning-base';
+/** Hex SHA-256 of `text`, encoded as UTF-8. */
+export function Sha256Hex(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+/** The plan hash: SHA-256 over `CanonicalPlanPayload`, which ignores target keys and masks encrypted values. */
+export function ComputeClonePlanHash(plan) {
+    return Sha256Hex(CanonicalPlanPayload(plan));
+}
+//# sourceMappingURL=ClonePlanHash.js.map

package/dist/ClonePlanHash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePlanHash.js","sourceRoot":"","sources":["../src/ClonePlanHash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAsB,MAAM,qCAAqC,CAAC;AAE/F,+CAA+C;AAC/C,MAAM,UAAU,SAAS,CAAC,IAAY;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IACzD,OAAO,SAAS,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/ClonePlanner.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file ClonePlanner.ts
+ * Computes deterministic clone plans for entity records using graph traversal.
+ * Enforces caps, permissions, unique key classification, field transformations, and plan hashing.
+ * @see plans/record-cloning/README.md §5, §7, §13.1
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { ClonePlan, RecordCloneRequest } from '@memberjunction/record-cloning-base';
+export interface ClonePlannerOptions {
+    Provider?: IMetadataProvider;
+}
+export declare class ClonePlanner {
+    private _provider?;
+    constructor(options?: ClonePlannerOptions);
+    protected get Provider(): IMetadataProvider;
+    /**
+     * Generates a fully calculated ClonePlan for the requested record.
+     */
+    Plan(request: RecordCloneRequest, contextUser: UserInfo): Promise<ClonePlan>;
+    /**
+     * Values already taken in each field a clone renames, per entity, found with one prefix query
+     * per (entity, field). Without them the rename can't avoid "Sales (copy)" on the second clone.
+     */
+    private loadExistingNames;
+    /**
+     * Drops rows matching their relationship's `ExcludeRows`, with every row discovered beneath them.
+     * The rule is looked up in the same order as the edge's policy (`ResolveEdgePolicy`): the
+     * relationship's own bag, then the root's entry by relationship ID, `Child.JoinField`, then
+     * `Child`. One Info warning per relationship.
+     */
+    private dropExcludedRows;
+}
+//# sourceMappingURL=ClonePlanner.d.ts.map

package/dist/ClonePlanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePlanner.d.ts","sourceRoot":"","sources":["../src/ClonePlanner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAKH,iBAAiB,EAGjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAGH,SAAS,EAST,kBAAkB,EAerB,MAAM,qCAAqC,CAAC;AAM7C,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAChC;AA6BD,qBAAa,YAAY;IACrB,OAAO,CAAC,SAAS,CAAC,CAAoB;gBAEnB,OAAO,CAAC,EAAE,mBAAmB;IAIhD,SAAS,KAAK,QAAQ,IAAI,iBAAiB,CAE1C;IAED;;OAEG;IACU,IAAI,CACb,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,SAAS,CAAC;IAmxBrB;;;OAGG;YACW,iBAAiB;IA4C/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAuD3B"}