@memberjunction/codegen-lib 6.1.0-edge.2 → 6.1.0-edge.4

package/dist/Misc/entity_subclasses_codegen.js

@@ -1,11 +1,12 @@
 import { BaseEntity, EntityFieldValueListType, Metadata, TypeScriptTypeFromSQLType } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
 import fs from 'fs';
 import path from 'path';
 import ts from 'typescript';
 import { makeDir, sortBySequenceAndCreatedAt } from '../Misc/util.js';
-import { logError, logStatus } from './status_logging.js';
+import { logError, logStatus, logWarning } from './status_logging.js';
 import { ManageMetadataBase } from '../Database/manage-metadata.js';
-import { mj_core_schema } from '../Config/config.js';
+import { mj_core_schema, resolveEntityImportPackage } from '../Config/config.js';
 import { SQLLogging } from './sql_logging.js';
 /**
  * Dynamically collects all own property names from BaseEntity's prototype chain
@@ -118,22 +119,31 @@ export class EntitySubClassGeneratorBase {
             // Only consider entities that actually emit a class: generateEntitySubClass skips PK-less entities
             // (returns ''), so hoisting their import would leave a dangling/unused import (a build error under
             // a downstream consumer's noUnusedLocals). Match that skip condition here.
-            const subclassImports = [...new Set(entities
-                    .filter((e) => e.PrimaryKeys.length > 0)
+            const entitiesWithPK = entities.filter((e) => e.PrimaryKeys.length > 0);
+            const localClassNames = new Set(entitiesWithPK.map((e) => `${e.ClassName}Entity`));
+            const baseClassImports = [...new Set(entitiesWithPK
                     .map((e) => this.resolveEntityBaseClass(e).importStatement)
                     .filter((s) => s.length > 0))].join('');
+            // Collect every embed + related-record-collection peer across the file, then emit
+            // one grouped `import { A, B } from 'pkg'` per npm package. Per-entity import
+            // lines would duplicate packages (Address on two owners → two import lines).
+            const peerImports = entitiesWithPK.flatMap((e) => EntitySubClassGeneratorBase.CollectPeerClassImports(e, localClassNames));
+            const peerImportStatements = EntitySubClassGeneratorBase.FormatPeerImportStatements(peerImports).join('');
+            const subclassImports = `${baseClassImports}${peerImportStatements}`;
             const allContent = `${this.generateEntitySubClassFileHeader()} \n ${subclassImports}${zodContent} \n ${sContent}`;
             makeDir(directory);
             fs.writeFileSync(path.join(directory, 'entity_subclasses.ts'), allContent);
             return true;
         }
         catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logError(message);
             console.error(err);
             return false;
         }
     }
     generateEntitySubClassFileHeader() {
-        return `import { BaseEntity, EntitySaveOptions, EntityDeleteOptions, CompositeKey, ValidationResult, ValidationErrorInfo, ValidationErrorType, Metadata, ProviderType, DatabaseProviderBase } from "@memberjunction/core";
+        return `import { BaseEntity, EntitySaveOptions, EntityDeleteOptions, CompositeKey, ValidationResult, ValidationErrorInfo, ValidationErrorType, Metadata, ProviderType, DatabaseProviderBase, RunView } from "@memberjunction/core";
 import { RegisterClass } from "@memberjunction/global";
 import { z } from "zod";
 
@@ -167,88 +177,87 @@ export const loadModule = () => {
             console.warn(`SKIPPING TYPESCRIPT GENERATION: Entity ${entity.Name} has no primary keys in metadata. If using soft primary keys, ensure metadata was refreshed after applySoftPKFKConfig().`);
             return '';
         }
-        else {
-            // Sort fields by Sequence, then by __mj_CreatedAt for consistent ordering
-            const sortedFields = sortBySequenceAndCreatedAt(entity.Fields);
-            const sClassName = `${entity.ClassName}Entity`;
-            const fields = sortedFields.map((e) => {
-                let values = '';
-                let valueList = '';
-                if (e.ValueListType && e.ValueListType.length > 0 && e.ValueListType.trim().toLowerCase() !== 'none') {
-                    // Sort by Sequence to ensure consistent ordering in comments
-                    const sortedValues = sortBySequenceAndCreatedAt([...e.EntityFieldValues]);
-                    values = sortedValues.map((v) => `\n    *   * ${v.Value}${v.Description && v.Description.length > 0 ? ' - ' + EntitySubClassGeneratorBase.SanitizeDescription(v.Description) : ''}`).join('');
-                    valueList = `\n    * * Value List Type: ${e.ValueListType}\n    * * Possible Values ` + values;
+        const sClassName = `${entity.ClassName}Entity`;
+        // Sort fields by Sequence, then by __mj_CreatedAt for consistent ordering
+        const sortedFields = sortBySequenceAndCreatedAt(entity.Fields);
+        const fields = sortedFields.map((e) => {
+            let values = '';
+            let valueList = '';
+            if (e.ValueListType && e.ValueListType.length > 0 && e.ValueListType.trim().toLowerCase() !== 'none') {
+                // Sort by Sequence to ensure consistent ordering in comments
+                const sortedValues = sortBySequenceAndCreatedAt([...e.EntityFieldValues]);
+                values = sortedValues.map((v) => `\n    *   * ${v.Value}${v.Description && v.Description.length > 0 ? ' - ' + EntitySubClassGeneratorBase.SanitizeDescription(v.Description) : ''}`).join('');
+                valueList = `\n    * * Value List Type: ${e.ValueListType}\n    * * Possible Values ` + values;
+            }
+            // JSONType: when a field has JSONType metadata, we emit the standard string getter/setter
+            // unchanged, plus an additional typed "Object" accessor (e.g., DefaultNavItemsObject) that
+            // handles JSON.parse/stringify with caching. Interface names are entity-prefixed for safety.
+            const hasJSONType = e.JSONType && e.JSONType.trim().length > 0;
+            let typeString = TypeScriptTypeFromSQLType(e.Type) + (e.AllowsNull ? ' | null' : '');
+            // Build the typed accessor info (used later for the Object suffix property)
+            let jsonTypeAccessorInfo = null;
+            if (hasJSONType) {
+                const originalTypeName = e.JSONType.trim();
+                const prefixedTypeName = `${sClassName}_${originalTypeName}`;
+                const isArray = e.JSONTypeIsArray === true;
+                const fullTypeString = isArray ? `Array<${prefixedTypeName}>` : prefixedTypeName;
+                jsonTypeAccessorInfo = { prefixedTypeName, fullTypeString: fullTypeString + (e.AllowsNull ? ' | null' : ''), isArray };
+                // typeString stays as the standard SQL-mapped type (string | null) for the base getter
+            }
+            if (!hasJSONType && e.ValueListTypeEnum !== EntityFieldValueListType.None && e.EntityFieldValues && e.EntityFieldValues.length > 0) {
+                // construct a typeString that is a union of the possible values
+                const quotes = e.NeedsQuotes ? "'" : '';
+                // Sort deterministically by Sequence, CreatedAt, then Value to prevent flip-flopping across runs
+                const sortedValues = sortBySequenceAndCreatedAt([...e.EntityFieldValues]);
+                typeString = sortedValues.map((v) => `${quotes}${v.Value}${quotes}`).join(' | ');
+                if (e.ValueListTypeEnum === EntityFieldValueListType.ListOrUserEntry) {
+                    // special case becuase a user can enter whatever they want
+                    typeString += ' | ' + TypeScriptTypeFromSQLType(e.Type);
                 }
-                // JSONType: when a field has JSONType metadata, we emit the standard string getter/setter
-                // unchanged, plus an additional typed "Object" accessor (e.g., DefaultNavItemsObject) that
-                // handles JSON.parse/stringify with caching. Interface names are entity-prefixed for safety.
-                const hasJSONType = e.JSONType && e.JSONType.trim().length > 0;
-                let typeString = TypeScriptTypeFromSQLType(e.Type) + (e.AllowsNull ? ' | null' : '');
-                // Build the typed accessor info (used later for the Object suffix property)
-                let jsonTypeAccessorInfo = null;
-                if (hasJSONType) {
-                    const originalTypeName = e.JSONType.trim();
-                    const prefixedTypeName = `${sClassName}_${originalTypeName}`;
-                    const isArray = e.JSONTypeIsArray === true;
-                    const fullTypeString = isArray ? `Array<${prefixedTypeName}>` : prefixedTypeName;
-                    jsonTypeAccessorInfo = { prefixedTypeName, fullTypeString: fullTypeString + (e.AllowsNull ? ' | null' : ''), isArray };
-                    // typeString stays as the standard SQL-mapped type (string | null) for the base getter
+                // finally, add the null type if it allows null
+                if (e.AllowsNull) {
+                    typeString += ' | null';
                 }
-                if (!hasJSONType && e.ValueListTypeEnum !== EntityFieldValueListType.None && e.EntityFieldValues && e.EntityFieldValues.length > 0) {
-                    // construct a typeString that is a union of the possible values
-                    const quotes = e.NeedsQuotes ? "'" : '';
-                    // Sort deterministically by Sequence, CreatedAt, then Value to prevent flip-flopping across runs
-                    const sortedValues = sortBySequenceAndCreatedAt([...e.EntityFieldValues]);
-                    typeString = sortedValues.map((v) => `${quotes}${v.Value}${quotes}`).join(' | ');
-                    if (e.ValueListTypeEnum === EntityFieldValueListType.ListOrUserEntry) {
-                        // special case becuase a user can enter whatever they want
-                        typeString += ' | ' + TypeScriptTypeFromSQLType(e.Type);
-                    }
-                    // finally, add the null type if it allows null
-                    if (e.AllowsNull) {
-                        typeString += ' | null';
-                    }
-                }
-                const fieldDeprecatedFlag = e.Status === 'Deprecated' || e.Status === 'Disabled' ?
-                    `\n    * * @deprecated This field is deprecated and will be removed in a future version. Using it will result in console warnings.` : '';
-                const fieldDisabledFlag = e.Status === 'Disabled' ?
-                    `\n    * * @disabled This field is disabled and will not be available in the application. Attempting to use it will result in exceptions being thrown` : '';
-                // IS-A parent field detection: virtual fields with AllowUpdateAPI on child entities
-                const isISAParentField = e.IsVirtual && e.AllowUpdateAPI && entity.IsChildType;
-                const isaSourceComment = isISAParentField
-                    ? `\n    * * IS-A Source: Inherited from ${this.getISAFieldSourceEntity(entity, e)}`
-                    : '';
-                const jsonTypeComment = hasJSONType && jsonTypeAccessorInfo
-                    ? `\n    * * JSON Type: ${jsonTypeAccessorInfo.isArray ? `Array<${jsonTypeAccessorInfo.prefixedTypeName}>` : jsonTypeAccessorInfo.prefixedTypeName}`
-                    : '';
-                const safeName = SafeCodeName(e);
-                const conflictNote = safeName !== e.CodeName
-                    ? `\n    * * NOTE: Property renamed to \`${safeName}\` to avoid conflict with BaseEntity.${e.CodeName}`
-                    : '';
-                // Standard getter/setter (always uses raw string, even for JSONType fields)
-                const getterBody = `return this.Get('${e.Name}');`;
-                const setterBody = `this.Set('${e.Name}', value);`;
-                let sRet = `    /**
+            }
+            const fieldDeprecatedFlag = e.Status === 'Deprecated' || e.Status === 'Disabled' ?
+                `\n    * * @deprecated This field is deprecated and will be removed in a future version. Using it will result in console warnings.` : '';
+            const fieldDisabledFlag = e.Status === 'Disabled' ?
+                `\n    * * @disabled This field is disabled and will not be available in the application. Attempting to use it will result in exceptions being thrown` : '';
+            // IS-A parent field detection: virtual fields with AllowUpdateAPI on child entities
+            const isISAParentField = e.IsVirtual && e.AllowUpdateAPI && entity.IsChildType;
+            const isaSourceComment = isISAParentField
+                ? `\n    * * IS-A Source: Inherited from ${this.getISAFieldSourceEntity(entity, e)}`
+                : '';
+            const jsonTypeComment = hasJSONType && jsonTypeAccessorInfo
+                ? `\n    * * JSON Type: ${jsonTypeAccessorInfo.isArray ? `Array<${jsonTypeAccessorInfo.prefixedTypeName}>` : jsonTypeAccessorInfo.prefixedTypeName}`
+                : '';
+            const safeName = SafeCodeName(e);
+            const conflictNote = safeName !== e.CodeName
+                ? `\n    * * NOTE: Property renamed to \`${safeName}\` to avoid conflict with BaseEntity.${e.CodeName}`
+                : '';
+            // Standard getter/setter (always uses raw string, even for JSONType fields)
+            const getterBody = `return this.Get('${e.Name}');`;
+            const setterBody = `this.Set('${e.Name}', value);`;
+            let sRet = `    /**
     * * Field Name: ${e.Name}${e.DisplayName && e.DisplayName.length > 0 ? '\n    * * Display Name: ' + e.DisplayName : ''}
     * * ${fieldDeprecatedFlag}${fieldDisabledFlag}SQL Data Type: ${e.SQLFullType}${e.RelatedEntity ? '\n    * * Related Entity/Foreign Key: ' + e.RelatedEntity + ' (' + e.RelatedEntityBaseView + '.' + e.RelatedEntityFieldName + ')' : ''}${e.DefaultValue && e.DefaultValue.length > 0 ? '\n    * * Default Value: ' + e.DefaultValue : ''}${valueList}${jsonTypeComment}${e.Description && e.Description.length > 0 ? '\n    * * Description: ' + EntitySubClassGeneratorBase.SanitizeDescription(e.Description) : ''}${isaSourceComment}${conflictNote}
     */
     get ${safeName}(): ${typeString} {
         ${getterBody}
     }`;
-                if (!e.ReadOnly || (e.IsPrimaryKey && !e.AutoIncrement) || isISAParentField) {
-                    sRet += `
+            if (!e.ReadOnly || (e.IsPrimaryKey && !e.AutoIncrement) || isISAParentField) {
+                sRet += `
     set ${safeName}(value: ${typeString}) {
         ${setterBody}
     }`;
-                }
-                // JSONType: emit additional typed "Object" accessor with caching
-                if (hasJSONType && jsonTypeAccessorInfo) {
-                    const objName = `${safeName}Object`;
-                    const cachedField = `_${objName}_cached`;
-                    const lastRawField = `_${objName}_lastRaw`;
-                    const ft = jsonTypeAccessorInfo.fullTypeString;
-                    sRet += `
+            }
+            // JSONType: emit additional typed "Object" accessor with caching
+            if (hasJSONType && jsonTypeAccessorInfo) {
+                const objName = `${safeName}Object`;
+                const cachedField = `_${objName}_cached`;
+                const lastRawField = `_${objName}_lastRaw`;
+                const ft = jsonTypeAccessorInfo.fullTypeString;
+                sRet += `
 
     private ${cachedField}: ${ft} | undefined = undefined;
     private ${lastRawField}: string | null = null;
@@ -270,29 +279,29 @@ export const loadModule = () => {
         this.${cachedField} = value;
         this.${lastRawField} = raw;
     }`;
-                }
-                return sRet;
-            }).join('\n\n');
-            // Base-class resolution, in precedence order:
-            //   1. An explicit custom subclass configured on the entity (EntityObjectSubclassName/Import).
-            //   2. ReadOnlyExternalBaseEntity for entities backed by an external data source — they
-            //      proxy a remote system live and must reject Save/Delete. (External entities only ever
-            //      appear in downstream generated packages, so the @memberjunction/core-entities import
-            //      is always a clean cross-package import, never a self-import.)
-            //   3. BaseEntity for everything else.
-            // Base class + its import come from resolveEntityBaseClass (pure) so the file assembler can hoist
-            // and de-duplicate the imports into the header. The per-entity inline import (below) is emitted
-            // ONLY in the standalone includeFileHeader path (single entity → no duplication); in the
-            // multi-entity file path the assembler owns the (deduped) imports.
-            const { baseClass: sBaseClass, importStatement: subClassImportStatement } = this.resolveEntityBaseClass(entity);
-            if (entity.ExternalDataSourceID && entity.EntityObjectSubclassName && entity.EntityObjectSubclassImport) {
-                // Custom subclass takes precedence over ReadOnlyExternalBaseEntity, so this external entity's
-                // read-only guarantee holds ONLY if that subclass itself extends ReadOnlyExternalBaseEntity.
-                // Warn so the author doesn't silently lose Save/Delete rejection.
-                logStatus(`   ⚠️  External entity '${entity.Name}' has a custom subclass ('${entity.EntityObjectSubclassName}') that overrides ReadOnlyExternalBaseEntity — Save/Delete will be rejected only if '${entity.EntityObjectSubclassName}' extends ReadOnlyExternalBaseEntity.`);
-            }
-            const loadFieldString = entity.PrimaryKeys.map((f) => `${f.CodeName}: ${f.TSType}`).join(', ');
-            const loadFunction = `    /**
+            }
+            return sRet;
+        }).join('\n\n');
+        // Base-class resolution, in precedence order:
+        //   1. An explicit custom subclass configured on the entity (EntityObjectSubclassName/Import).
+        //   2. ReadOnlyExternalBaseEntity for entities backed by an external data source — they
+        //      proxy a remote system live and must reject Save/Delete. (External entities only ever
+        //      appear in downstream generated packages, so the @memberjunction/core-entities import
+        //      is always a clean cross-package import, never a self-import.)
+        //   3. BaseEntity for everything else.
+        // Base class + its import come from resolveEntityBaseClass (pure) so the file assembler can hoist
+        // and de-duplicate the imports into the header. The per-entity inline import (below) is emitted
+        // ONLY in the standalone includeFileHeader path (single entity → no duplication); in the
+        // multi-entity file path the assembler owns the (deduped) imports.
+        const { baseClass: sBaseClass, importStatement: subClassImportStatement } = this.resolveEntityBaseClass(entity);
+        if (entity.ExternalDataSourceID && entity.EntityObjectSubclassName && entity.EntityObjectSubclassImport) {
+            // Custom subclass takes precedence over ReadOnlyExternalBaseEntity, so this external entity's
+            // read-only guarantee holds ONLY if that subclass itself extends ReadOnlyExternalBaseEntity.
+            // Warn so the author doesn't silently lose Save/Delete rejection.
+            logStatus(`   ⚠️  External entity '${entity.Name}' has a custom subclass ('${entity.EntityObjectSubclassName}') that overrides ReadOnlyExternalBaseEntity — Save/Delete will be rejected only if '${entity.EntityObjectSubclassName}' extends ReadOnlyExternalBaseEntity.`);
+        }
+        const loadFieldString = entity.PrimaryKeys.map((f) => `${f.CodeName}: ${f.TSType}`).join(', ');
+        const loadFunction = `    /**
     * Loads the ${entity.Name} record from the database
     ${entity.PrimaryKeys.map((f) => `* @param ${f.CodeName}: ${f.TSType} - primary key value to load the ${entity.Name} record.`).join('\n    ')}
     * @param EntityRelationshipsToLoad - (optional) the relationships to load
@@ -308,10 +317,10 @@ export const loadModule = () => {
         ${entity.PrimaryKeys.map((f) => `compositeKey.KeyValuePairs.push({ FieldName: '${f.Name}', Value: ${f.CodeName} });`).join('\n        ')}
         return await super.InnerLoad(compositeKey, EntityRelationshipsToLoad);
     }`;
-            let deleteFunction = '';
-            if (!entity.AllowDeleteAPI) {
-                // Entity doesn't allow delete at all
-                deleteFunction = `    /**
+        let deleteFunction = '';
+        if (!entity.AllowDeleteAPI) {
+            // Entity doesn't allow delete at all
+            deleteFunction = `    /**
     * ${entity.Name} - AllowDeleteAPI is set to 0 in the database.  Delete is not allowed, so this method is generated to override the base class method and throw an error. To enable delete for this entity, set AllowDeleteAPI to 1 in the database.
     * @public
     * @method
@@ -322,10 +331,10 @@ export const loadModule = () => {
     public override async Delete(): Promise<boolean> {
         throw new Error('Delete is not allowed for ${entity.Name}, to enable it set AllowDeleteAPI to 1 in the database.');
     }`;
-            }
-            else if (entity.CascadeDeletes) {
-                // Entity has cascading deletes, wrap in transaction
-                deleteFunction = `    /**
+        }
+        else if (entity.CascadeDeletes) {
+            // Entity has cascading deletes, wrap in transaction
+            deleteFunction = `    /**
     * ${entity.Name} - Delete method override to wrap in transaction since CascadeDeletes is true.
     * Wrapping in a transaction ensures that all cascade delete operations are handled atomically.
     * @public
@@ -359,10 +368,10 @@ export const loadModule = () => {
             return super.Delete(options);
         }
     }`;
-            }
-            const saveFunction = entity.AllowCreateAPI || entity.AllowUpdateAPI
-                ? ''
-                : `    /**
+        }
+        const saveFunction = entity.AllowCreateAPI || entity.AllowUpdateAPI
+            ? ''
+            : `    /**
     * ${entity.Name} - AllowCreateAPI and AllowUpdateAPI are both set to 0 in the database.  Save is not allowed, so this method is generated to override the base class method and throw an error. To enable save for this entity, set AllowCreateAPI and/or AllowUpdateAPI to 1 in the database.
     * @public
     * @method
@@ -373,52 +382,54 @@ export const loadModule = () => {
     public override async Save(options?: EntitySaveOptions) : Promise<boolean> {
         throw new Error('Save is not allowed for ${entity.Name}, to enable it set AllowCreateAPI and/or AllowUpdateAPI to 1 in the database.');
     }`;
-            const validateFunction = await this.LogAndGenerateValidateFunction(pool, entity, skipDBUpdate);
-            const status = entity.Status.trim().toLowerCase();
-            const deprecatedFlag = status === 'deprecated' || status === 'disabled' ?
-                `\n * @deprecated This entity is deprecated and will be removed in a future version. Using it will result in console warnings.` : '';
-            const disabledFlag = status === 'disabled' ?
-                `\n * @disabled This entity is disabled and will not be available in the application. Attempting to use it will result in exceptions being thrown` : '';
-            // Collect and deduplicate JSONTypeDefinitions for this entity.
-            // These are raw TypeScript interface/type definitions (from EntityField.JSONTypeDefinition)
-            // that get emitted above the entity class so the typed getters/setters can reference them.
-            // A Set is used because multiple fields may share the same definition (e.g., a shared config type).
-            // Each definition is validated via the TypeScript compiler API before inclusion.
-            const jsonTypeDefinitions = new Set();
-            for (const field of sortedFields) {
-                if (field.JSONTypeDefinition && field.JSONTypeDefinition.trim().length > 0) {
-                    const definition = field.JSONTypeDefinition.trim();
-                    if (field.JSONType && field.JSONType.trim().length > 0) {
-                        const validation = EntitySubClassGeneratorBase.ValidateJSONTypeDefinition(definition, field.JSONType.trim(), entity.Name, field.Name);
-                        if (!validation.valid) {
-                            for (const err of validation.errors) {
-                                logError(err);
-                            }
-                            logError(`[JSONType] Skipping JSONTypeDefinition for ${entity.Name}.${field.Name} due to validation errors. The field will use a plain string getter/setter instead.`);
-                            field.JSONType = null;
-                            continue;
+        const validateFunction = await this.LogAndGenerateValidateFunction(pool, entity, skipDBUpdate);
+        const status = entity.Status.trim().toLowerCase();
+        const deprecatedFlag = status === 'deprecated' || status === 'disabled' ?
+            `\n * @deprecated This entity is deprecated and will be removed in a future version. Using it will result in console warnings.` : '';
+        const disabledFlag = status === 'disabled' ?
+            `\n * @disabled This entity is disabled and will not be available in the application. Attempting to use it will result in exceptions being thrown` : '';
+        // Collect and deduplicate JSONTypeDefinitions for this entity.
+        // These are raw TypeScript interface/type definitions (from EntityField.JSONTypeDefinition)
+        // that get emitted above the entity class so the typed getters/setters can reference them.
+        // A Set is used because multiple fields may share the same definition (e.g., a shared config type).
+        // Each definition is validated via the TypeScript compiler API before inclusion.
+        const jsonTypeDefinitions = new Set();
+        for (const field of sortedFields) {
+            if (field.JSONTypeDefinition && field.JSONTypeDefinition.trim().length > 0) {
+                const definition = field.JSONTypeDefinition.trim();
+                if (field.JSONType && field.JSONType.trim().length > 0) {
+                    const validation = EntitySubClassGeneratorBase.ValidateJSONTypeDefinition(definition, field.JSONType.trim(), entity.Name, field.Name);
+                    if (!validation.valid) {
+                        for (const err of validation.errors) {
+                            logError(err);
                         }
+                        logError(`[JSONType] Skipping JSONTypeDefinition for ${entity.Name}.${field.Name} due to validation errors. The field will use a plain string getter/setter instead.`);
+                        field.JSONType = null;
+                        continue;
                     }
-                    // Prefix all type names defined in this definition block with the entity class name
-                    // to avoid naming conflicts across entities. Uses AST to find all defined type names.
-                    let rewrittenDef = definition;
-                    const sourceFile = ts.createSourceFile('temp.ts', definition, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-                    ts.forEachChild(sourceFile, (node) => {
-                        if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) ||
-                            ts.isEnumDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
-                            const originalName = node.name.text;
-                            const prefixedName = `${sClassName}_${originalName}`;
-                            rewrittenDef = rewrittenDef.replace(new RegExp('\\b' + originalName + '\\b', 'g'), prefixedName);
-                        }
-                    });
-                    jsonTypeDefinitions.add(rewrittenDef);
                 }
+                // Prefix all type names defined in this definition block with the entity class name
+                // to avoid naming conflicts across entities. Uses AST to find all defined type names.
+                let rewrittenDef = definition;
+                const sourceFile = ts.createSourceFile('temp.ts', definition, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+                ts.forEachChild(sourceFile, (node) => {
+                    if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) ||
+                        ts.isEnumDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
+                        const originalName = node.name.text;
+                        const prefixedName = `${sClassName}_${originalName}`;
+                        rewrittenDef = rewrittenDef.replace(new RegExp('\\b' + originalName + '\\b', 'g'), prefixedName);
+                    }
+                });
+                jsonTypeDefinitions.add(rewrittenDef);
             }
-            const jsonTypeBlock = jsonTypeDefinitions.size > 0
-                ? '\n' + Array.from(jsonTypeDefinitions).join('\n\n') + '\n'
-                : '';
-            const relatedRecordCollections = EntitySubClassGeneratorBase.GenerateRelatedRecordCollections(entity);
-            let sRet = `
+        }
+        const jsonTypeBlock = jsonTypeDefinitions.size > 0
+            ? '\n' + Array.from(jsonTypeDefinitions).join('\n\n') + '\n'
+            : '';
+        const relatedRecordCollections = EntitySubClassGeneratorBase.GenerateRelatedRecordCollections(entity);
+        const embeddedRecords = EntitySubClassGeneratorBase.GenerateEmbeddedRecords(entity);
+        const hierarchyMethods = EntitySubClassGeneratorBase.GenerateHierarchyMethods(entity, sClassName);
+        let sRet = `
 ${jsonTypeBlock}
 /**
  * ${entity.Name} - strongly typed entity sub-class
@@ -431,15 +442,14 @@ ${jsonTypeBlock}
  * @public${deprecatedFlag}
  */
 ${includeFileHeader ? subClassImportStatement : ''}@RegisterClass(BaseEntity, '${entity.Name}')
-export class ${sClassName} extends ${sBaseClass}<${sClassName}Type> {${relatedRecordCollections}${loadFunction ? '\n' + loadFunction : ''}${saveFunction ? '\n\n' + saveFunction : ''}${deleteFunction ? '\n\n' + deleteFunction : ''}${validateFunction ? '\n\n' + validateFunction : ''}
+export class ${sClassName} extends ${sBaseClass}<${sClassName}Type> {${relatedRecordCollections}${embeddedRecords}${hierarchyMethods}${loadFunction ? '\n' + loadFunction : ''}${saveFunction ? '\n\n' + saveFunction : ''}${deleteFunction ? '\n\n' + deleteFunction : ''}${validateFunction ? '\n\n' + validateFunction : ''}
 
 ${fields}
 }
 `;
-            if (includeFileHeader)
-                sRet = this.generateEntitySubClassFileHeader() + sRet;
-            return sRet;
-        }
+        if (includeFileHeader)
+            sRet = this.generateEntitySubClassFileHeader() + sRet;
+        return sRet;
     }
     /**
      * Emits `DeclareRelatedRecords(...)` declarations for every relationship on this entity whose
@@ -673,6 +683,275 @@ ${fields}
     static EscapeSingleQuotes(value) {
         return String(value ?? '').replace(/\\/g, '\\\\').replace(/'/g, "\\'");
     }
+    /**
+     * Emits `{Field}_Object` / `{Field}_EnsureObject()` for every FK field whose
+     * `EmbeddedRecord` column holds a config object.
+     *
+     * RelatedEntity and the FK field name come from the row (`RelatedEntityID`, `Name`),
+     * not the JSON. `AllowsNull` on the same row decides the getter's nullability.
+     *
+     * @param entity - The entity being generated.
+     * @returns The declarations block, or an empty string when none are declared.
+     */
+    static GenerateEmbeddedRecords(entity) {
+        const declared = (entity.Fields ?? []).filter(f => f.EmbeddedRecord && String(f.EmbeddedRecord).trim().length > 0);
+        if (declared.length === 0) {
+            return '';
+        }
+        const md = new Metadata(); // global-provider-ok: codegen runs offline against a single provider
+        const blocks = [];
+        const seen = new Set();
+        for (const field of declared) {
+            const config = EntitySubClassGeneratorBase.ParseEmbeddedRecordConfig(entity, field);
+            if (!config) {
+                continue;
+            }
+            const nameKey = `${field.Name}_Object`.toLowerCase();
+            if (seen.has(nameKey)) {
+                logError(`[EmbeddedRecord] ${entity.Name}.${field.Name}: duplicate generated name '${field.Name}_Object'; skipping.`);
+                continue;
+            }
+            seen.add(nameKey);
+            const related = field.RelatedEntityID ? md.EntityByID(field.RelatedEntityID) : undefined;
+            if (!related) {
+                logError(`[EmbeddedRecord] ${entity.Name}.${field.Name}: RelatedEntityID is missing or unknown; skipping.`);
+                continue;
+            }
+            blocks.push(EntitySubClassGeneratorBase.RenderEmbeddedRecord(entity, field, related, config));
+        }
+        return blocks.length > 0 ? '\n' + blocks.join('\n') : '';
+    }
+    /**
+     * Emits strongly-typed hierarchy traversal helper methods (`GetDescendants`, `GetAncestors`, `GetChildren`)
+     * for entities with recursive self-referencing foreign keys.
+     *
+     * @param entity - The entity being generated.
+     * @param sClassName - The generated subclass name.
+     * @returns The generated methods block, or an empty string when the entity has no recursive FKs.
+     */
+    static GenerateHierarchyMethods(entity, sClassName) {
+        const recursiveFKs = (entity.Fields ?? []).filter(f => f.RelatedEntityID != null && (UUIDsEqual(f.RelatedEntityID, entity.ID) || f.RelatedEntity === entity.Name) && !f.IsVirtual && f.IsHierarchy === true);
+        if (recursiveFKs.length === 0) {
+            return '';
+        }
+        if (entity.PrimaryKeys.length !== 1) {
+            logWarning(`[Hierarchy] Entity '${entity.Name}' has ${recursiveFKs.length} hierarchy foreign key(s) ` +
+                `(${recursiveFKs.map(f => f.Name).join(', ')}), but has ${entity.PrimaryKeys.length} primary key fields. ` +
+                `MemberJunction hierarchy traversal requires a single-column primary key; skipping subclass hierarchy methods.`);
+            return '';
+        }
+        const methods = [];
+        const pkName = entity.FirstPrimaryKey?.Name ?? 'ID';
+        for (const field of recursiveFKs) {
+            const fieldName = field.Name;
+            const rootField = `Root${fieldName}`;
+            const depthField = `${fieldName}Depth`;
+            const pathField = `${fieldName}Path`;
+            const isPrimaryHierarchy = recursiveFKs.length === 1 || fieldName === 'ParentID';
+            // For primary hierarchies (e.g. ParentID), BaseEntity already provides strongly-typed
+            // GetDescendants<T = this>(), GetAncestors<T = this>(), and GetChildren<T = this>().
+            // We only generate named helper methods for non-primary hierarchy fields (e.g. ManagerID).
+            if (isPrimaryHierarchy) {
+                continue;
+            }
+            methods.push(`
+  /**
+   * Retrieves all descendant records in the ${fieldName} hierarchy under this record using a single RunView query.
+   * @param maxDepth Optional maximum relative depth to retrieve.
+   * @returns Array of descendant entity instances ordered by hierarchy depth.
+   */
+  public async Get${fieldName}Descendants<T extends BaseEntity = this>(maxDepth?: number): Promise<T[]> {
+    return this.GetDescendants<T>({ parentFieldName: '${fieldName}', maxDepth });
+  }
+
+  /**
+   * Retrieves all ancestor records in the ${fieldName} hierarchy from the top-level root down to this record using a single RunView query.
+   * @returns Array of ancestor entity instances ordered from root down to parent.
+   */
+  public async Get${fieldName}Ancestors<T extends BaseEntity = this>(): Promise<T[]> {
+    return this.GetAncestors<T>('${fieldName}');
+  }
+
+  /**
+   * Retrieves all direct child records in the ${fieldName} hierarchy of this record using a single RunView query.
+   * @returns Array of direct child entity instances.
+   */
+  public async Get${fieldName}Children<T extends BaseEntity = this>(): Promise<T[]> {
+    return this.GetChildren<T>('${fieldName}');
+  }`);
+        }
+        return methods.length > 0 ? '\n' + methods.join('\n') : '';
+    }
+    /**
+     * One peer class that must be imported because it is referenced by an embed or
+     * related-record collection and is not being emitted in this file.
+     */
+    static CollectPeerClassImports(entity, localClassNames, config) {
+        const owningSchema = (entity.SchemaName ?? '').trim();
+        if (!owningSchema) {
+            throw new Error(`[CodeGen] entity import: entity '${entity.Name}' has no SchemaName; cannot resolve peer import packages.`);
+        }
+        const md = new Metadata(); // global-provider-ok: codegen runs offline against a single provider
+        const byClass = new Map();
+        const addPeer = (className, relatedSchema, context) => {
+            if (!className || className === 'BaseEntity') {
+                return;
+            }
+            if (localClassNames.has(className)) {
+                return;
+            }
+            const schema = (relatedSchema ?? '').trim();
+            if (!schema) {
+                throw new Error(`[CodeGen] entity import: ${context} refers to class '${className}' but the related entity has no SchemaName. ` +
+                    `CodeGen cannot pick an npm package to import it from.`);
+            }
+            const packageName = resolveEntityImportPackage(schema, owningSchema, config);
+            const existing = byClass.get(className);
+            if (existing && existing !== packageName) {
+                throw new Error(`[CodeGen] entity import: class '${className}' resolved to both '${existing}' and '${packageName}' on entity '${entity.Name}'.`);
+            }
+            byClass.set(className, packageName);
+        };
+        for (const field of (entity.Fields ?? []).filter((f) => f.EmbeddedRecord && String(f.EmbeddedRecord).trim().length > 0 && f.RelatedEntityID)) {
+            const related = md.EntityByID?.(field.RelatedEntityID);
+            if (!related) {
+                continue;
+            }
+            addPeer(`${related.ClassName}Entity`, related.SchemaName, `${entity.Name}.${field.Name} (embedded record)`);
+        }
+        for (const relationship of (entity.RelatedEntities ?? []).filter((r) => r.RelatedRecordCollection && r.RelatedRecordCollection.trim().length > 0)) {
+            const parsed = EntitySubClassGeneratorBase.ParseRelatedRecordCollectionConfig(entity, relationship);
+            if (!parsed) {
+                continue;
+            }
+            const relatedBase = relationship.RelatedEntityClassName?.trim();
+            if (!relatedBase) {
+                continue;
+            }
+            let related;
+            if (relationship.RelatedEntityID && typeof md.EntityByID === 'function') {
+                related = md.EntityByID(relationship.RelatedEntityID);
+            }
+            if (!related && relationship.RelatedEntity && typeof md.EntityByName === 'function') {
+                related = md.EntityByName(relationship.RelatedEntity);
+            }
+            addPeer(`${relatedBase}Entity`, related?.SchemaName, `${entity.Name} → ${relationship.RelatedEntity} (related-record collection)`);
+        }
+        return [...byClass.entries()].map(([className, packageName]) => ({ className, packageName }));
+    }
+    /**
+     * Groups peer imports into one `import { A, B } from 'pkg'` line per npm package.
+     * `@memberjunction/core-entities` is emitted first; remaining packages are alphabetical.
+     */
+    static FormatPeerImportStatements(imports) {
+        const byPackage = new Map();
+        for (const item of imports) {
+            if (!item.className || !item.packageName) {
+                continue;
+            }
+            let set = byPackage.get(item.packageName);
+            if (!set) {
+                set = new Set();
+                byPackage.set(item.packageName, set);
+            }
+            set.add(item.className);
+        }
+        const packages = [...byPackage.keys()].sort((a, b) => {
+            if (a === '@memberjunction/core-entities')
+                return -1;
+            if (b === '@memberjunction/core-entities')
+                return 1;
+            return a.localeCompare(b);
+        });
+        return packages.map((pkg) => {
+            const names = [...byPackage.get(pkg)].sort((a, b) => a.localeCompare(b));
+            return `import { ${names.join(', ')} } from '${pkg}';\n`;
+        });
+    }
+    /**
+     * @deprecated Use {@link CollectPeerClassImports} + {@link FormatPeerImportStatements}.
+     * Kept so existing call sites still compile; includes related-record collections as well as embeds.
+     */
+    static CollectEmbeddedImports(entity, localClassNames, config) {
+        return EntitySubClassGeneratorBase.FormatPeerImportStatements(EntitySubClassGeneratorBase.CollectPeerClassImports(entity, localClassNames, config));
+    }
+    /**
+     * Parses and validates one field's `EmbeddedRecord` JSON.
+     * Invalid metadata is skipped with a logged error rather than throwing.
+     */
+    static ParseEmbeddedRecordConfig(entity, field) {
+        const label = `${entity.Name}.${field.Name}`;
+        let parsed;
+        try {
+            parsed = JSON.parse(String(field.EmbeddedRecord));
+        }
+        catch (e) {
+            logError(`[EmbeddedRecord] ${label}: EmbeddedRecord is not valid JSON ` +
+                `(${e instanceof Error ? e.message : String(e)}); skipping.`);
+            return null;
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            logError(`[EmbeddedRecord] ${label}: expected a JSON object; skipping.`);
+            return null;
+        }
+        const config = parsed;
+        const clearModes = ['delete', 'orphan', 'refuse'];
+        if (config.OnClear && !clearModes.includes(config.OnClear)) {
+            logError(`[EmbeddedRecord] ${label}: invalid OnClear '${config.OnClear}'; skipping.`);
+            return null;
+        }
+        const nestedModes = ['inherit', 'related'];
+        if (config.LoadNested && !nestedModes.includes(config.LoadNested)) {
+            logError(`[EmbeddedRecord] ${label}: invalid LoadNested '${config.LoadNested}'; skipping.`);
+            return null;
+        }
+        const emittedName = field.CodeName ? SafeCodeName(field) : field.Name;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(emittedName)) {
+            logError(`[EmbeddedRecord] ${label}: emitted name '${emittedName}' is not a valid TypeScript identifier; skipping.`);
+            return null;
+        }
+        return config;
+    }
+    /**
+     * Renders the private companion plus the public `{Field}_Object` / `{Field}_EnsureObject` API.
+     */
+    static RenderEmbeddedRecord(entity, field, related, config) {
+        const relatedClass = `${related.ClassName}Entity`;
+        const getterType = field.AllowsNull ? `${relatedClass} | null` : relatedClass;
+        const code = field.CodeName ? SafeCodeName(field) : field.Name;
+        const lines = [
+            `ForeignKeyField: '${EntitySubClassGeneratorBase.EscapeSingleQuotes(field.Name)}'`,
+            `RelatedEntity: '${EntitySubClassGeneratorBase.EscapeSingleQuotes(related.Name)}'`,
+        ];
+        if (config.OnClear) {
+            lines.push(`OnClear: '${config.OnClear}'`);
+        }
+        if (config.LoadNested) {
+            lines.push(`LoadNested: '${config.LoadNested}'`);
+        }
+        const requiredNote = field.AllowsNull
+            ? ` Null until ${code}_EnsureObject() or Load() finds a value.`
+            : ` Always present after GetEntityObject / NewRecord.`;
+        return `
+  /**
+  * Embedded record: ${related.Name}
+  *
+  * 1:1 peer joined by this record's ${field.Name}. Loaded and saved with this
+  * ${entity.Name} record — see packages/MJCore/docs/embedded-records.md.
+  * Declared by EntityField.EmbeddedRecord on '${entity.Name}.${field.Name}'; edit that row, not this file.
+  *${requiredNote}
+  */
+  private readonly __emb_${code} = this.DeclareEmbeddedRecord<${relatedClass}>({
+      ${lines.join(',\n        ')},
+  });
+  public get ${code}_Object(): ${getterType} {
+      return this.__emb_${code}.Value${field.AllowsNull ? '' : '!'};
+  }
+  public ${code}_EnsureObject(): ${relatedClass} {
+      return this.__emb_${code}.Ensure();
+  }
+`;
+    }
     /**
      * Finds the source parent entity for an IS-A inherited field by walking the parent chain.
      * Returns the name of the parent entity that originally defines the field (as a non-virtual column).