@memberjunction/core 6.1.0-edge.2 → 6.1.0-edge.3

package/dist/generic/embeddedRecord.js

@@ -0,0 +1,356 @@
+/**
+ * @fileoverview `EmbeddedRecord<T>` — a 1:1 peer `BaseEntity` that loads, validates
+ * and persists as one unit with its owner, joined by an **owner-held** foreign key.
+ *
+ * This is the third composition axis on `BaseEntity`, next to IS-A (shared PK) and
+ * related-record collections (FK on the related row). The FK lives on the owner
+ * (`Deal.OrderID`), so the save order inverts: the peer persists first, the owner
+ * stamps the FK, then the owner persists.
+ *
+ * Callers never hold this class. They see `owner.OrderID_Object` (the entity) and
+ * `owner.OrderID_EnsureObject()` (sync provision for a nullable FK).
+ *
+ * @module @memberjunction/core
+ */
+import { CompositeKey, KeyValuePair } from './compositeKey.js';
+import { EntityCompanion } from './entityCompanion.js';
+import { ValidationErrorInfo, ValidationErrorType } from './entityInfo.js';
+/**
+ * Internal companion for one owner-held 1:1 peer.
+ *
+ * @typeParam T - The embedded entity type.
+ */
+export class EmbeddedRecord extends EntityCompanion {
+    constructor(owner, options) {
+        super(owner);
+        this.instance = null;
+        this.exposed = false;
+        this.cleared = false;
+        this.constructing = false;
+        this.ForeignKeyField = options.ForeignKeyField;
+        this.RelatedEntityName = options.RelatedEntity;
+        const fieldInfo = owner.EntityInfo?.Fields.find(f => f.Name === options.ForeignKeyField);
+        this.Name = `${fieldInfo?.CodeName ?? options.ForeignKeyField}_Object`;
+        this.ClearMode = options.OnClear ?? 'orphan';
+        this.LoadNested = options.LoadNested ?? 'inherit';
+    }
+    /** The live peer, or `null` when a nullable FK is not yet provisioned. */
+    get Value() {
+        return this.exposed ? this.instance : null;
+    }
+    /** True when the getter will return an object. */
+    get IsProvisioned() {
+        return this.exposed && this.instance !== null;
+    }
+    /** True when the owner's FK column refuses null. */
+    get IsRequired() {
+        const field = this.Owner.GetFieldByName(this.ForeignKeyField);
+        return field?.EntityFieldInfo.AllowsNull === false;
+    }
+    /**
+     * Constructs the related entity instance without `NewRecord` / `Load`.
+     * Called from `BaseEntity.InitializeEmbeddedRecords` during `GetEntityObject`.
+     *
+     * @param visited - Entity names already being constructed, for cycle detection.
+     */
+    async InitializeInstance(visited) {
+        if (this.instance || this.constructing) {
+            return;
+        }
+        // Path-set, not a global set: a sibling targeting the same entity
+        // (BillTo + ShipTo) is not a cycle — InitializeEmbeddedRecords copies
+        // `visited` per sibling so they never see each other in-flight. A
+        // self-FK or A→B→A ancestor is on this path and must stop here, or
+        // ConstructUninitializedEntity's recurse would construct forever.
+        if (visited.has(this.RelatedEntityName)) {
+            return;
+        }
+        this.constructing = true;
+        visited.add(this.RelatedEntityName);
+        try {
+            this.instance = await this.Owner.ConstructUninitializedEntity(this.RelatedEntityName, visited);
+        }
+        finally {
+            visited.delete(this.RelatedEntityName);
+            this.constructing = false;
+        }
+    }
+    /**
+     * Sync provision. Idempotent. For a required FK this is a no-op after `NewRecord`.
+     */
+    Ensure() {
+        if (!this.instance) {
+            throw new Error(`EmbeddedRecord '${this.Name}' on ${this.Owner.EntityInfo?.Name}: the related ` +
+                `'${this.RelatedEntityName}' instance was not constructed. GetEntityObject must ` +
+                `run InitializeEmbeddedRecords before Ensure().`);
+        }
+        if (this.exposed) {
+            return this.instance;
+        }
+        // Always mint a new peer. After Clear()+Save() the leftover instance is
+        // the orphaned row (still IsSaved). Restamping its PK would silently
+        // re-attach it. Re-attachment is an explicit FK set, not Ensure's job.
+        this.instance.NewRecord();
+        this.stampOwnerKey();
+        this.exposed = true;
+        this.cleared = false;
+        return this.instance;
+    }
+    /**
+     * Marks the relationship for removal on the next save. Does not persist by itself.
+     */
+    Clear() {
+        if (this.ClearMode === 'refuse') {
+            throw new Error(`EmbeddedRecord '${this.Name}' on ${this.Owner.EntityInfo?.Name}: Clear() is refused ` +
+                `(OnClear: 'refuse'). Detaching this relationship is not allowed.`);
+        }
+        this.exposed = false;
+        this.cleared = true;
+        this.Owner.Set(this.ForeignKeyField, null);
+    }
+    /**
+     * Called from the owner's `NewRecord()`. Required FKs are provisioned here so
+     * `owner.OrderID_Object` is usable immediately after `GetEntityObject`.
+     */
+    OnOwnerNewRecord() {
+        this.cleared = false;
+        if (!this.instance) {
+            return;
+        }
+        if (this.IsRequired) {
+            const existingFk = this.Owner.Get(this.ForeignKeyField);
+            if (existingFk !== null && existingFk !== undefined && existingFk !== '') {
+                // Caller passed NewRecord({ [FK]: existingId }). Do not mint a
+                // new peer and overwrite that FK. The owner points at an existing
+                // row; Load() will hydrate it.
+                this.exposed = false;
+            }
+            else {
+                this.instance.NewRecord();
+                this.stampOwnerKey();
+                this.exposed = true;
+            }
+        }
+        else {
+            this.exposed = false;
+        }
+    }
+    /** @inheritdoc */
+    get Dirty() {
+        if (this.cleared) {
+            return true;
+        }
+        if (!this.exposed || !this.instance) {
+            return false;
+        }
+        return this.instance.Dirty;
+    }
+    /** @inheritdoc */
+    Validate(result) {
+        if (!this.exposed || !this.instance) {
+            return;
+        }
+        const inner = this.instance.Validate();
+        if (!inner.Success) {
+            result.Success = false;
+            for (const err of inner.Errors) {
+                result.Errors.push(this.prefixError(err));
+            }
+        }
+    }
+    /** @inheritdoc */
+    async ValidateAsync(result) {
+        if (!this.exposed || !this.instance) {
+            return;
+        }
+        const inner = await this.instance.ValidateAsync();
+        if (!inner.Success) {
+            result.Success = false;
+            for (const err of inner.Errors) {
+                result.Errors.push(this.prefixError(err));
+            }
+        }
+    }
+    /** @inheritdoc */
+    ContributeSaveWork(plan, options) {
+        if (this.cleared) {
+            this.contributeClearWork(plan);
+            return;
+        }
+        if (!this.exposed || !this.instance) {
+            return;
+        }
+        if (this.instance.IsSaved && !this.instance.Dirty && !options?.IgnoreDirtyState) {
+            return;
+        }
+        plan.AddSaveBeforeRoot(this.instance, this.Name);
+        plan.AddRootPrepare(() => this.stampOwnerKey());
+    }
+    /** @inheritdoc */
+    ContributePostDeleteWork(plan) {
+        if (this.ClearMode !== 'delete') {
+            return;
+        }
+        if (!this.instance || !this.instance.IsSaved) {
+            return;
+        }
+        plan.AddDelete(this.instance, `${this.Name}.OnOwnerDelete`);
+    }
+    /** @inheritdoc */
+    async LoadEager(visited = new Set()) {
+        if (!this.instance) {
+            return;
+        }
+        const fk = this.Owner.Get(this.ForeignKeyField);
+        if (fk === null || fk === undefined || fk === '') {
+            this.exposed = false;
+            this.cleared = false;
+            // A reused owner instance can still hold the previous record's
+            // saved peer. Reset it so Ensure() does not restamp that PK and
+            // OnClear:'delete' does not delete the previous peer.
+            if (this.instance.IsSaved) {
+                this.instance.NewRecord();
+            }
+            return;
+        }
+        const token = `${this.RelatedEntityName}:${String(fk)}`;
+        if (visited.has(token)) {
+            throw new Error(`EmbeddedRecord '${this.Name}' on ${this.Owner.EntityInfo?.Name}: load cycle at ` +
+                `${token}. A self-parented or mutually-referential embed cannot inherit forever.`);
+        }
+        const next = new Set(visited);
+        next.add(token);
+        // Nested embeds of a different entity were constructed with the owner.
+        // Self-FK / cycle peers stay unconstructed until this load walk; init
+        // them now so InnerLoad's loadEagerCompanions can inherit.
+        await this.instance.InitializeEmbeddedRecords();
+        this.instance.SetEmbeddedLoadVisited(next);
+        try {
+            const loaded = await this.instance.InnerLoad(this.keyFromForeignKey(fk));
+            if (!loaded) {
+                if (this.IsRequired) {
+                    throw new Error(`EmbeddedRecord '${this.Name}' on ${this.Owner.EntityInfo?.Name}: required ` +
+                        `FK ${this.ForeignKeyField}='${fk}' does not resolve to a ${this.RelatedEntityName} row.`);
+                }
+                this.exposed = false;
+                return;
+            }
+            this.exposed = true;
+            this.cleared = false;
+            if (this.LoadNested === 'related') {
+                await this.instance.LoadRelatedRecords();
+            }
+        }
+        finally {
+            this.instance.SetEmbeddedLoadVisited(undefined);
+        }
+    }
+    /** @inheritdoc */
+    AcceptChanges() {
+        this.cleared = false;
+    }
+    /** @inheritdoc */
+    async Serialize(mode = 'request') {
+        if (this.cleared) {
+            return { Fields: {}, IsNew: false, Cleared: true, Companions: null };
+        }
+        if (!this.exposed || !this.instance) {
+            return null;
+        }
+        // Request: omit a clean saved peer so a header-only edit does not ship it.
+        // Result: always ship an exposed peer so the client can mark it saved.
+        // Skipping result-serialize left the client IsSaved=false; the next Save
+        // re-sent IsNew:true and the server re-INSERTed the same UUID.
+        if (mode !== 'result' && this.instance.IsSaved && !this.instance.Dirty) {
+            return null;
+        }
+        const companions = await this.instance.SerializeCompanions(mode);
+        return {
+            EntityName: this.instance.EntityInfo?.Name ?? this.RelatedEntityName,
+            Fields: this.instance.GetAll(),
+            IsNew: !this.instance.IsSaved,
+            Cleared: false,
+            Companions: companions.length > 0 ? companions : null,
+        };
+    }
+    /** @inheritdoc */
+    async Deserialize(data, mode = 'request') {
+        if (!data) {
+            return;
+        }
+        if (data.Cleared) {
+            this.exposed = false;
+            this.cleared = true;
+            this.Owner.Set(this.ForeignKeyField, null);
+            return;
+        }
+        if (data.EntityName && data.EntityName !== this.RelatedEntityName && (!this.instance || this.instance.EntityInfo?.Name !== data.EntityName)) {
+            const provider = this.Owner.ProviderToUse;
+            if (provider) {
+                this.instance = (await provider.GetEntityObject(data.EntityName, this.Owner.ContextCurrentUser));
+            }
+        }
+        if (!this.instance) {
+            await this.InitializeInstance(new Set());
+        }
+        if (!this.instance) {
+            throw new Error(`EmbeddedRecord '${this.Name}': cannot deserialize — no instance of ${data.EntityName ?? this.RelatedEntityName}.`);
+        }
+        await this.applyWire(data, mode);
+        this.exposed = true;
+        this.cleared = false;
+    }
+    async applyWire(data, mode) {
+        const target = this.instance;
+        if (mode === 'result') {
+            await target.LoadFromData(data.Fields, true);
+            if (data.Companions && data.Companions.length > 0) {
+                await target.DeserializeCompanions(data.Companions, 'result');
+            }
+            return;
+        }
+        if (data.IsNew) {
+            target.NewRecord();
+            target.SetMany(data.Fields, true);
+        }
+        else {
+            await this.loadExistingThenApply(target, data.Fields);
+        }
+        if (data.Companions && data.Companions.length > 0) {
+            await target.DeserializeCompanions(data.Companions, mode);
+        }
+    }
+    async loadExistingThenApply(target, fields) {
+        const key = new CompositeKey(target.EntityInfo.PrimaryKeys.map(pk => new KeyValuePair(pk.Name, fields[pk.Name])));
+        const loaded = await target.InnerLoad(key);
+        if (!loaded) {
+            throw new Error(`EmbeddedRecord '${this.Name}': cannot load existing ${this.RelatedEntityName} ` +
+                `record ${key.ToString()} referenced by the incoming payload.`);
+        }
+        target.SetMany(fields, true);
+    }
+    contributeClearWork(plan) {
+        plan.AddRootPrepare(() => this.Owner.Set(this.ForeignKeyField, null));
+        if (this.ClearMode === 'delete' && this.instance?.IsSaved) {
+            plan.AddDelete(this.instance, `${this.Name}.Cleared`);
+        }
+    }
+    stampOwnerKey() {
+        const key = this.instance?.FirstPrimaryKey?.Value;
+        if (key === null || key === undefined || key === '') {
+            return;
+        }
+        this.Owner.Set(this.ForeignKeyField, key);
+    }
+    keyFromForeignKey(fk) {
+        const pks = this.instance.EntityInfo.PrimaryKeys;
+        if (pks.length === 1) {
+            return CompositeKey.FromID(fk);
+        }
+        return new CompositeKey(pks.map(pk => new KeyValuePair(pk.Name, fk)));
+    }
+    prefixError(err) {
+        return new ValidationErrorInfo(`${this.Name}.${err.Source ?? ''}`.replace(/\.$/, ''), err.Message, err.Value, err.Type ?? ValidationErrorType.Failure);
+    }
+}
+//# sourceMappingURL=embeddedRecord.js.map

package/dist/generic/embeddedRecord.js.map

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

package/dist/generic/entityCompanion.d.ts

@@ -127,9 +127,13 @@ export declare abstract class EntityCompanion<TWire = unknown> {
      * touches only header fields should not ship an empty children array and pay for it on every
      * request.
      *
+     * @param mode - `'request'` (default) is the caller's intent — omit a clean saved
+     *               companion so a header-only edit does not ship it. `'result'` is
+     *               post-save state the client must adopt so the next save does not
+     *               re-INSERT a peer the server already persisted.
      * @returns The wire payload, or `null` to omit this companion.
      */
-    abstract Serialize(): Promise<TWire | null>;
+    abstract Serialize(mode?: EntityCompanionDeserializeMode): Promise<TWire | null>;
     /**
      * Restores this companion's state from a wire payload produced by {@link Serialize} on the
      * other tier.
@@ -200,6 +204,16 @@ export declare abstract class EntityCompanion<TWire = unknown> {
      * @param _plan - The plan being assembled for this unit of work.
      */
     ContributeDeleteWork(_plan: EntitySavePlan): void;
+    /**
+     * Contributes work that must run **after** the owner's own delete node.
+     *
+     * Related-record collections delete first (they point at the owner). Embedded
+     * records delete last (the owner points at them — the FK dies with the owner
+     * row, then the peer can go). Default is a no-op.
+     *
+     * @param _plan - The plan being assembled; the owner's delete node already exists.
+     */
+    ContributePostDeleteWork(_plan: EntitySavePlan): void;
     /**
      * Populates this companion from the database, when it is configured to load eagerly.
      *
@@ -207,8 +221,12 @@ export declare abstract class EntityCompanion<TWire = unknown> {
      * from `LoadFromData()` — that is the row-materialization path for
      * `RunView(ResultType:'entity_object')`, so loading children there turns one view into an N+1
      * storm. Set-oriented eager loading is handled by `RunView`'s batched child loading instead.
+     *
+     * @param _visited - EntityName:PK tokens already on this load walk. Embedded
+     *                   records use it to fail a self-parented / cyclic inherit
+     *                   instead of recursing until the stack dies.
      */
-    LoadEager(): Promise<void>;
+    LoadEager(_visited?: Set<string>): Promise<void>;
     /**
      * Resets the companion to its post-save state — clearing pending removals, rebasing dirty
      * tracking, and so on. Called after the graph commits successfully.

package/dist/generic/entityCompanion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entityCompanion.d.ts","sourceRoot":"","sources":["../../src/generic/entityCompanion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,eAAe,CAAC,KAAK,GAAG,OAAO;IACjD;;OAEG;IACH,SAAgB,KAAK,EAAE,UAAU,CAAC;IAElC;;OAEG;gBACS,KAAK,EAAE,UAAU;IAI7B;;;;;;OAMG;IACH,kBAAyB,IAAI,EAAE,MAAM,CAAC;IAEtC;;;;;;;;;OASG;aACa,SAAS,IAAI,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAElD;;;;;;;;;;OAUG;aACa,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAE7F;;;;;;;;OAQG;IACH,IAAW,KAAK,IAAI,OAAO,CAE1B;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAIhD;;;;;;;;;;;OAWG;IACU,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAIpF;;;;;;;;OAQG;IACI,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIxD;;;;;;;OAOG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC;;;OAGG;IACI,aAAa,IAAI,IAAI;CAG/B"}
+{"version":3,"file":"entityCompanion.d.ts","sourceRoot":"","sources":["../../src/generic/entityCompanion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,eAAe,CAAC,KAAK,GAAG,OAAO;IACjD;;OAEG;IACH,SAAgB,KAAK,EAAE,UAAU,CAAC;IAElC;;OAEG;gBACS,KAAK,EAAE,UAAU;IAI7B;;;;;;OAMG;IACH,kBAAyB,IAAI,EAAE,MAAM,CAAC;IAEtC;;;;;;;;;;;;;OAaG;aACa,SAAS,CAAC,IAAI,CAAC,EAAE,8BAA8B,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAEvF;;;;;;;;;;OAUG;aACa,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAE7F;;;;;;;;OAQG;IACH,IAAW,KAAK,IAAI,OAAO,CAE1B;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAIhD;;;;;;;;;;;OAWG;IACU,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAIpF;;;;;;;;OAQG;IACI,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIxD;;;;;;;;OAQG;IACI,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAI5D;;;;;;;;;;;OAWG;IACU,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;OAGG;IACI,aAAa,IAAI,IAAI;CAG/B"}

package/dist/generic/entityCompanion.js

@@ -148,6 +148,18 @@ export class EntityCompanion {
     ContributeDeleteWork(_plan) {
         /* no-op by default */
     }
+    /**
+     * Contributes work that must run **after** the owner's own delete node.
+     *
+     * Related-record collections delete first (they point at the owner). Embedded
+     * records delete last (the owner points at them — the FK dies with the owner
+     * row, then the peer can go). Default is a no-op.
+     *
+     * @param _plan - The plan being assembled; the owner's delete node already exists.
+     */
+    ContributePostDeleteWork(_plan) {
+        /* no-op by default */
+    }
     /**
      * Populates this companion from the database, when it is configured to load eagerly.
      *
@@ -155,8 +167,12 @@ export class EntityCompanion {
      * from `LoadFromData()` — that is the row-materialization path for
      * `RunView(ResultType:'entity_object')`, so loading children there turns one view into an N+1
      * storm. Set-oriented eager loading is handled by `RunView`'s batched child loading instead.
+     *
+     * @param _visited - EntityName:PK tokens already on this load walk. Embedded
+     *                   records use it to fail a self-parented / cyclic inherit
+     *                   instead of recursing until the stack dies.
      */
-    async LoadEager() {
+    async LoadEager(_visited) {
         /* no-op by default */
     }
     /**

package/dist/generic/entityCompanion.js.map

@@ -1 +1 @@
-{"version":3,"file":"entityCompanion.js","sourceRoot":"","sources":["../../src/generic/entityCompanion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAoBH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAgBrD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAgB,eAAe;IAMjC;;OAEG;IACH,YAAY,KAAiB;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAoCD;;;;;;;;OAQG;IACH,IAAW,KAAK;QACZ,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,OAAyB;QACrC,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,aAAa,CAAC,OAAyB;QAChD,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAqB,EAAE,QAA4B;QACzE,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACI,oBAAoB,CAAC,KAAqB;QAC7C,sBAAsB;IAC1B,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,SAAS;QAClB,sBAAsB;IAC1B,CAAC;IAED;;;OAGG;IACI,aAAa;QAChB,sBAAsB;IAC1B,CAAC;CACJ"}
+{"version":3,"file":"entityCompanion.js","sourceRoot":"","sources":["../../src/generic/entityCompanion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAoBH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAgBrD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAgB,eAAe;IAMjC;;OAEG;IACH,YAAY,KAAiB;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAwCD;;;;;;;;OAQG;IACH,IAAW,KAAK;QACZ,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,OAAyB;QACrC,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,aAAa,CAAC,OAAyB;QAChD,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAqB,EAAE,QAA4B;QACzE,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACI,oBAAoB,CAAC,KAAqB;QAC7C,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACI,wBAAwB,CAAC,KAAqB;QACjD,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,SAAS,CAAC,QAAsB;QACzC,sBAAsB;IAC1B,CAAC;IAED;;;OAGG;IACI,aAAa;QAChB,sBAAsB;IAC1B,CAAC;CACJ"}

package/dist/generic/entityConfiguration.d.ts

@@ -0,0 +1,131 @@
+export declare const DEFAULT_AUTO_LEFT_NAV_AT = 8;
+export declare const DEFAULT_PRIMARY_RELATED_BUDGET = 6;
+export declare const RELATED_ROLE_SCORE: {
+    readonly RelatedRecordCollection: 200;
+    readonly CustomDisplayComponent: 150;
+    readonly SameSchema: 100;
+    readonly OneToMany: 50;
+    readonly BeforeFieldTabs: 40;
+    /**
+     * Cap for the inbound-relationship hub boost. A related entity that many
+     * other entities point at (Order Headers) outranks a satellite with two
+     * incoming keys (Task Activities). Applied as `min(cap, 20 * log2(count))`.
+     */
+    readonly InboundHubCap: 120;
+    readonly CreatedByJoin: -90;
+    readonly SatelliteName: -70;
+    readonly PlatformSchema: -80;
+};
+export declare const PLATFORM_SCHEMA_NAME = "__mj";
+export type FormLayout = 'accordion' | 'left-nav' | 'auto';
+export type RelatedRolePolicy = 'keep-all-primary' | 'smart';
+export type FormRole = 'Primary' | 'Detail';
+/** L1 membership on a parent form. None never reaches the ranker. */
+export type FormInclusion = 'Primary' | 'More' | 'None';
+import { IEntityConfiguration, IEntityFormConfiguration } from './JSONType-interfaces/IEntityConfiguration.js';
+import { IEntityFieldConfiguration } from './JSONType-interfaces/IEntityFieldConfiguration.js';
+import { IEntityRelationshipConfiguration } from './JSONType-interfaces/IEntityRelationshipConfiguration.js';
+export * from './JSONType-interfaces/IEntityConfiguration.js';
+export * from './JSONType-interfaces/IEntityFieldConfiguration.js';
+export * from './JSONType-interfaces/IEntityRelationshipConfiguration.js';
+export interface IEntityRelationshipJoin {
+    mode: 'any';
+    fields: string[];
+}
+export type RelatedFormRoleReason = 'explicit-primary' | 'explicit-detail' | 'explicit-none' | 'join-sibling-none' | 'ranked-primary' | 'ranked-detail' | 'keep-all-primary' | 'under-budget' | 'install-primary' | 'install-more' | 'install-none';
+export type FormChromeRuleTargetKind = 'Relationship' | 'Contribution';
+/**
+ * One install-overlay (L3) pin. Loaded from `MJ: Form Chrome Rules`.
+ * Keyed by (parent entity, related entity) or (parent entity, contributionKey).
+ */
+export interface FormChromeRule {
+    EntityID: string;
+    TargetKind: FormChromeRuleTargetKind;
+    RelatedEntityID?: string | null;
+    ContributionKey?: string | null;
+    Inclusion: FormInclusion;
+    JoinFields?: string[] | null;
+    Sequence?: number | null;
+    /**
+     * Admin display title. Null / blank keeps the L1 DisplayName or
+     * humanized entity name. Keyed with the rule, not the previous label,
+     * so an OpenApp upgrade that renames the related entity does not
+     * overwrite a site-specific title.
+     */
+    Title?: string | null;
+}
+export interface RelatedFormRoleCandidate {
+    ID: string;
+    RelatedEntity: string;
+    RelatedEntityID: string;
+    RelatedEntityJoinField: string;
+    RelatedEntitySchemaName: string;
+    DisplayInForm: boolean;
+    DisplayLocation?: 'After Field Tabs' | 'Before Field Tabs' | null;
+    DisplayComponentID?: string | null;
+    RelatedRecordCollection?: string | null;
+    JoinView?: string | null;
+    Type?: string | null;
+    Sequence?: number | null;
+    /**
+     * The relationship's configuration bag, either raw JSON or already parsed.
+     * `EntityRelationshipInfo.Configuration` parses lazily and hands back
+     * {@link IEntityRelationshipConfiguration}, while callers reading straight
+     * from a row still supply the raw string — so both are accepted, matching
+     * what {@link ReadRelationshipInclusion}, {@link ReadRelationshipSortKey}
+     * and {@link ReadRelationshipJoinFields} already take.
+     */
+    Configuration?: string | IEntityRelationshipConfiguration | null;
+    /**
+     * How many EntityRelationships across metadata point at this related
+     * entity. Runtime-only — the ranker uses it as graph in-degree.
+     */
+    InboundRelationshipCount?: number | null;
+}
+export interface RelatedFormRoleAssignment {
+    RelationshipID: string;
+    RelatedEntity: string;
+    RelatedEntityID: string;
+    RelatedEntityJoinField: string;
+    Role: FormRole;
+    Inclusion: FormInclusion;
+    Score: number;
+    Reason: RelatedFormRoleReason;
+    ExplicitFormRole: FormRole | null;
+    ExplicitInclusion: FormInclusion | null;
+    JoinFields: string[] | null;
+}
+export interface RelatedFormRoleResolution {
+    Policy: RelatedRolePolicy;
+    Budget: number;
+    Assignments: RelatedFormRoleAssignment[];
+}
+export declare function ParseEntityConfiguration(raw: string | IEntityConfiguration | null | undefined): IEntityConfiguration | null;
+export declare function ParseEntityRelationshipConfiguration(raw: string | IEntityRelationshipConfiguration | null | undefined): IEntityRelationshipConfiguration | null;
+export declare function ResolveFormLayout(formConfig: IEntityFormConfiguration | null | undefined, firstClassSectionCount: number): Exclude<FormLayout, 'auto'>;
+/**
+ * Read L1 inclusion from a relationship Configuration bag.
+ * `inclusion` wins. `FormRole: 'Detail'` maps to More. `FormRole: 'Primary'` maps to Primary.
+ */
+export declare function ReadRelationshipInclusion(raw: string | IEntityRelationshipConfiguration | null | undefined): FormInclusion | null;
+/** Higher = earlier among first-class related rail items. Omit / invalid = null. */
+export declare function ReadRelationshipSortKey(raw: string | IEntityRelationshipConfiguration | null | undefined): number | null;
+export declare function ReadRelationshipJoinFields(raw: string | IEntityRelationshipConfiguration | null | undefined): string[] | null;
+/**
+ * Score a DisplayInForm relationship for the smart ranker. Explicit inclusion
+ * is not applied here — callers separate the L1 pool first.
+ */
+export declare function ScoreRelatedFormRole(candidate: RelatedFormRoleCandidate, parentSchemaName: string): number;
+export declare function ResolveRelatedFormRoles(parentSchemaName: string, formConfig: IEntityFormConfiguration | null | undefined, candidates: readonly RelatedFormRoleCandidate[]): RelatedFormRoleResolution;
+/**
+ * L3 install overlay. Pins Inclusion / JoinFields on matching relationship
+ * assignments. Later Sequence wins. Contribution rules are applied by the
+ * chrome resolver (they are not ranker assignments).
+ */
+export declare function ApplyFormChromeRules(parentEntityId: string, assignments: readonly RelatedFormRoleAssignment[], rules: readonly FormChromeRule[]): RelatedFormRoleAssignment[];
+export declare function ContributionInclusionFromRules(parentEntityId: string, contributionKey: string, rules: readonly FormChromeRule[]): FormInclusion | null;
+/**
+ * Safely parses an `EntityField.Configuration` JSON string or returns the object.
+ */
+export declare function ParseEntityFieldConfiguration(raw: string | IEntityFieldConfiguration | null | undefined): IEntityFieldConfiguration | null;
+//# sourceMappingURL=entityConfiguration.d.ts.map

package/dist/generic/entityConfiguration.d.ts.map

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