@memberjunction/core 6.2.0-edge.0 → 6.2.0-edge.2

package/dist/generic/entityInfo.js

@@ -3,7 +3,7 @@ import { Metadata } from "./metadata.js";
 import { TypeScriptTypeFromSQLType, SQLFullType, SQLMaxLength, FormatValue, CodeNameFromString } from "./util.js";
 import { IsFixedWidthStringSQLType } from "@memberjunction/sql-dialect";
 import { LogError } from "./logging.js";
-import { WarningManager, SafeJSONParse, UUIDsEqual, ordinalCompare } from "@memberjunction/global";
+import { WarningManager, SafeJSONParse, UUIDsEqual, ordinalCompare, GeneratePluralName } from "@memberjunction/global";
 import { ReadRelationshipJoinFields, } from "./entityConfiguration.js";
 /**
  * Runtime domain for {@link EntityFieldInfo.ExtendedType}. This array is the single source of
@@ -101,6 +101,14 @@ export class EntityRelationshipInfo extends BaseInfo {
     get ConfigurationObject() {
         return this.Configuration;
     }
+    /**
+     * Parsed clone configuration for this relationship.
+     * Specifies the policy (Deep, Reference, Skip), locked status, field rules, etc.
+     * @see plans/record-cloning/README.md §4.2
+     */
+    get CloneConfig() {
+        return this.ConfigurationObject?.Clone ?? null;
+    }
     constructor(initData) {
         super();
         this.ID = null;
@@ -216,7 +224,7 @@ export class EntityOrganicKeyInfo extends BaseInfo {
         this.__mj_UpdatedAt = null;
         // virtual fields from the database view
         this.Entity = null;
-        this._RelatedEntities = [];
+        this._RelatedEntities = []; // case-violation-ok-legacy-back-compat: a class in the same hierarchy already declares the camelCase name — TypeScript rejects two declarations of one private property (TS2415)
         if (initData) {
             this.copyInitData(initData);
             this._RelatedEntities = [];
@@ -623,6 +631,7 @@ export class EntityFieldValueInfo extends BaseInfo {
         return {
             Value: this.Value,
             Code: this.Code,
+            Description: this.Description ?? undefined,
         };
     }
 }
@@ -674,6 +683,14 @@ export class EntityFieldInfo extends BaseInfo {
     get ConfigurationObject() {
         return this.Configuration;
     }
+    /**
+     * Parsed clone configuration for this field.
+     * Specifies copy/reset/remap/suffix policy, value transformations, JSON remaps, etc.
+     * @see plans/record-cloning/README.md §4.3
+     */
+    get CloneConfig() {
+        return this.ConfigurationObject?.Clone ?? null;
+    }
     /**
      * Returns true if this field is explicitly configured as an intentional recursive tree hierarchy.
      */
@@ -686,6 +703,38 @@ export class EntityFieldInfo extends BaseInfo {
     get HierarchyMaxDepth() {
         return this.ConfigurationObject?.Hierarchy?.MaxDepth ?? 100;
     }
+    /** @deprecated Use {@link RelatedEntityTableAlias}. */
+    get _RelatedEntityTableAlias() {
+        return this.RelatedEntityTableAlias;
+    }
+    /** @deprecated Use {@link RelatedEntityTableAlias}. */
+    set _RelatedEntityTableAlias(value) {
+        this.RelatedEntityTableAlias = value;
+    }
+    /** @deprecated Use {@link RelatedEntityNameFieldIsVirtual}. */
+    get _RelatedEntityNameFieldIsVirtual() {
+        return this.RelatedEntityNameFieldIsVirtual;
+    }
+    /** @deprecated Use {@link RelatedEntityNameFieldIsVirtual}. */
+    set _RelatedEntityNameFieldIsVirtual(value) {
+        this.RelatedEntityNameFieldIsVirtual = value;
+    }
+    /** @deprecated Use {@link RelatedEntityNameFieldIsComputed}. */
+    get _RelatedEntityNameFieldIsComputed() {
+        return this.RelatedEntityNameFieldIsComputed;
+    }
+    /** @deprecated Use {@link RelatedEntityNameFieldIsComputed}. */
+    set _RelatedEntityNameFieldIsComputed(value) {
+        this.RelatedEntityNameFieldIsComputed = value;
+    }
+    /** @deprecated Use {@link RelatedEntityJoinFieldMappings}. */
+    get _RelatedEntityJoinFieldMappings() {
+        return this.RelatedEntityJoinFieldMappings;
+    }
+    /** @deprecated Use {@link RelatedEntityJoinFieldMappings}. */
+    set _RelatedEntityJoinFieldMappings(value) {
+        this.RelatedEntityJoinFieldMappings = value;
+    }
     /**
      * JSON configuration for additional fields to join from the related entity.
      * Parsed from the RelatedEntityJoinFields column. Uses lazy initialization and caching
@@ -728,7 +777,7 @@ export class EntityFieldInfo extends BaseInfo {
      * Empty for the overwhelming majority of fields — see {@link HasFieldPermissions}.
      */
     get FieldPermissions() {
-        return this._FieldPermissions;
+        return this._fieldPermissions;
     }
     /**
      * True when at least one {@link EntityFieldPermissionInfo} record exists for this field.
@@ -739,7 +788,7 @@ export class EntityFieldInfo extends BaseInfo {
      * enabled entity a field with no records is denied, not open.
      */
     get HasFieldPermissions() {
-        return this._FieldPermissions.length > 0;
+        return this._fieldPermissions.length > 0;
     }
     /**
      * Entities whose fields can never be restricted by field-level security.
@@ -760,7 +809,7 @@ export class EntityFieldInfo extends BaseInfo {
      *
      * Stored lowercased; compare with a trimmed, lowercased entity name.
      */
-    static { this.UnrestrictableEntityNames = new Set([
+    static { this.unrestrictableEntityNames = new Set([
         'mj: entities',
         'mj: entity fields',
         'mj: entity permissions',
@@ -774,7 +823,7 @@ export class EntityFieldInfo extends BaseInfo {
      * See {@link EntityFieldInfo.UnrestrictableEntityNames} for the rationale.
      */
     get IsOnUnrestrictableEntity() {
-        return EntityFieldInfo.UnrestrictableEntityNames.has((this.Entity ?? '').trim().toLowerCase());
+        return EntityFieldInfo.unrestrictableEntityNames.has((this.Entity ?? '').trim().toLowerCase());
     }
     /**
      * True for fields that must remain readable regardless of any permission record:
@@ -859,7 +908,7 @@ export class EntityFieldInfo extends BaseInfo {
      * arithmetic.
      */
     aggregateUserFieldPermissions(user) {
-        return EntityFieldInfo.AggregateFieldRulesForUser(this._FieldPermissions, user);
+        return EntityFieldInfo.AggregateFieldRulesForUser(this._fieldPermissions, user);
     }
     /**
      * The same aggregation {@link GetUserFieldPermissions} performs, over a rule list the caller
@@ -958,8 +1007,9 @@ export class EntityFieldInfo extends BaseInfo {
      *   * **Stringifying is required.** `EntityFieldValue.Value` is always a string in metadata while
      *     the field's runtime value may be a number, so a strict `===` would reject every legal value
      *     on a numeric list. It is not lossless: `String(1.0)` is `'1'`, so a metadata value written
-     *     as `'1.0'` would fail closed. No numeric value lists exist today (CodeGen cannot produce
-     *     one — see the note in ValueIsPermittedByValueList), so this is recorded rather than solved.
+     *     as `'1.00'` would fail closed here — which is why a NUMERIC column's list is not compared
+     *     through this function at all but by value, in numericValueIsPermittedByValueList (MJ #3978).
+     *     This normalization is what a STRING column's list is compared with.
      *   * **Trimming is cheap insurance, NOT the load-bearing rule it was first documented as.** An
      *     earlier version of this comment claimed an untrimmed comparison would reject 9,301 existing
      *     rows in fixed-width `nchar` columns (`MJ: Action Params`.Type, `MJ: Record Changes`.Status
@@ -1002,10 +1052,10 @@ export class EntityFieldInfo extends BaseInfo {
      *   * Only string and number values are checked, and the gate fails OPEN — an unsupported type
      *     skips validation rather than manufacturing a failure. Nothing in the schema restricts
      *     which columns may carry a value list (`CK_EntityField_ValueListType_New` constrains the
-     *     mode, not the column type), but in practice every one is a string column: measured on a
-     *     current 6.x instance, 455 nvarchar + 7 nchar and nothing else, which follows from
-     *     CodeGen's constraint parser only ever extracting quoted literals. `number` is admitted
-     *     because the generated union type anticipates a non-quoted list via `NeedsQuotes`.
+     *     mode, not the column type). Every list WAS on a string column — measured on a 6.x
+     *     instance, 455 nvarchar + 7 nchar and nothing else — because CodeGen's constraint parser
+     *     only extracted quoted literals; since MJ #3978 it extracts the unquoted numeric form too,
+     *     so a numeric column's list is now a real case and is compared by value (below).
      *     Booleans and Dates are excluded deliberately: a bit column carrying a `'1'`/`'0'` list
      *     would see `String(true) === 'true'` and reject every legal value, and a Date has no sane
      *     string form to compare — so guessing there would break saves rather than guard them.
@@ -1059,17 +1109,72 @@ export class EntityFieldInfo extends BaseInfo {
         if (typeof value !== 'string' && typeof value !== 'number') {
             // The rule cannot be applied to this type at all, and that is a mismatch rather than a
             // state to absorb: either the field should not declare a value list (one on a bit column
-            // — which CodeGen never produces, since SQL Server renders `IN (0,1)` as unquoted
-            // `([B]=(1) OR [B]=(0))`, the same reason no NUMERIC list exists either; see MJ #3978)
-            // or a caller assigned the wrong type. Skipping it silently would
+            // — which CodeGen still never produces: it captures the unquoted numeric form as of MJ
+            // #3978, but excludes `bit` fields, since `IN (0,1)` is vacuous on a bit and `= 1` is a
+            // validator rather than a dropdown) or a caller assigned the wrong type. Skipping it silently would
             // leave the caller believing a guard is on when it is not, which is the exact failure
             // mode this rung was added to fix — so it is reported, once per field.
             this.reportUnsupportedValueListValue(`a ${typeof value} value (SQL type ${this.SQLFullType})`, 'value-list validation compares strings, numbers and dates only — comparing anything ' +
                 'else would reject legal values rather than guard them');
             return true;
         }
+        // A NUMERIC column's list is compared by VALUE, not by string form — see
+        // numericValueIsPermittedByValueList. Falls through to the string comparison when the list is
+        // not entirely numeric, which is the only case where there is nothing to compare against.
+        if (this.TSType === EntityFieldTSType.Number) {
+            const numericKeys = this.valueListNumericKeys();
+            if (numericKeys) {
+                return this.numericValueIsPermittedByValueList(value, numericKeys);
+            }
+        }
         return this._normalizedValueListValues.has(EntityFieldInfo.NormalizeValueListValue(value));
     }
+    /**
+     * Value-list membership for a NUMERIC column, compared on the numeric VALUE rather than the
+     * string form (MJ issue #3978).
+     *
+     * Necessary because the two sides are written by different hands: SQL Server stores
+     * `CHECK (Price IN (0.50, 1.00))` as the unquoted literals `([Price]=(1.00) OR [Price]=(0.50))`,
+     * CodeGen captures those literals verbatim, and the runtime value of that column is the number
+     * `1`. `String(1) === '1'` is not `'1.00'`, so a string comparison would refuse a value the
+     * database accepts — the exact failure mode this rung exists to avoid. Comparing as numbers makes
+     * the scale of the literal irrelevant.
+     *
+     * The comparison is gated on the column being numeric, NOT merely on the list looking numeric: on
+     * a string column `CHECK (Code IN ('1','2'))` really is a string list, and comparing `'01'`
+     * numerically would permit a value the database refuses.
+     *
+     * A value that is not a finite number falls back to the string comparison rather than being
+     * refused here, so a value list that happens to hold non-numeric text on a numeric column (which
+     * CodeGen cannot produce, but `applyValueListConfig` could) still behaves as it did before.
+     */
+    numericValueIsPermittedByValueList(value, numericKeys) {
+        const candidate = typeof value === 'number' ? value : Number(value.trim());
+        if (!Number.isFinite(candidate)) {
+            return this._normalizedValueListValues.has(EntityFieldInfo.NormalizeValueListValue(value));
+        }
+        return numericKeys.has(candidate);
+    }
+    /**
+     * The value list as a set of numbers, or null when any of its values is not a finite number (so
+     * there is nothing to compare numerically). Memoized alongside the normalized string set, and
+     * built from it — lower-casing and trimming cannot change how a numeric literal parses.
+     */
+    valueListNumericKeys() {
+        if (this._valueListNumericKeys === undefined) {
+            const keys = new Set();
+            for (const normalized of this._normalizedValueListValues ?? []) {
+                const parsed = Number(normalized);
+                if (normalized.length === 0 || !Number.isFinite(parsed)) {
+                    this._valueListNumericKeys = null;
+                    return null;
+                }
+                keys.add(parsed);
+            }
+            this._valueListNumericKeys = keys.size > 0 ? keys : null;
+        }
+        return this._valueListNumericKeys;
+    }
     /**
      * Value-list membership for a `Date` runtime value, compared on the CALENDAR DATE rather than
      * the instant.
@@ -1101,7 +1206,7 @@ export class EntityFieldInfo extends BaseInfo {
             return true; // an Invalid Date is not an out-of-list value; leave it to the date check
         }
         return this._valueListDateKeys.has(value.toISOString().slice(0, 10)) ||
-            this._valueListDateKeys.has(EntityFieldInfo.LocalCalendarDate(value));
+            this._valueListDateKeys.has(EntityFieldInfo.localCalendarDate(value));
     }
     /**
      * Builds the set of yyyy-mm-dd keys for a `date` field's value list, or null when the field is
@@ -1124,7 +1229,7 @@ export class EntityFieldInfo extends BaseInfo {
         return keys.size > 0 ? keys : null;
     }
     /** The Date's LOCAL calendar date as yyyy-mm-dd (its UTC one is `toISOString().slice(0, 10)`). */
-    static LocalCalendarDate(value) {
+    static localCalendarDate(value) {
         const pad = (n) => String(n).padStart(2, '0');
         return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
     }
@@ -1872,6 +1977,8 @@ export class EntityFieldInfo extends BaseInfo {
         this._loggedUnsupportedValueListType = false;
         /** Memoized yyyy-mm-dd keys for a `date` field's value list; null when it cannot be compared. */
         this._valueListDateKeys = undefined;
+        /** Memoized numeric form of a numeric field's value list; null when it is not entirely numeric. */
+        this._valueListNumericKeys = undefined;
         /**
          * Cached parsed RelatedEntityJoinFieldsConfig to avoid repeated JSON.parse calls.
          * Lazy-initialized on first access.
@@ -1881,7 +1988,7 @@ export class EntityFieldInfo extends BaseInfo {
          * Flag to track if RelatedEntityJoinFieldsConfig parsing failed to avoid repeated parse attempts on bad JSON.
          */
         this._relatedEntityJoinFieldsFailedParsing = false;
-        this._FieldPermissions = [];
+        this._fieldPermissions = [];
         /** Memoized {@link TSType} — `Type` is immutable after metadata load, so the classification never changes. */
         this._tsType = undefined;
         /**
@@ -1911,7 +2018,7 @@ export class EntityFieldInfo extends BaseInfo {
             // would cost more than the construction it avoids.
             const efp = initData.EntityFieldPermissions || initData._FieldPermissions || initData.FieldPermissions;
             if (efp && efp.length > 0) {
-                this._FieldPermissions = efp.map((p) => new EntityFieldPermissionInfo(p));
+                this._fieldPermissions = efp.map((p) => new EntityFieldPermissionInfo(p));
             }
         }
     }
@@ -2058,7 +2165,10 @@ export class EntityInfo extends BaseInfo {
                 try {
                     const parsed = JSON.parse(this.SubtypeSelector);
                     if (parsed && typeof parsed['Path'] === 'string' && parsed['Path'].trim().length > 0) {
-                        this._subtypeSelectorConfig = { Path: parsed['Path'].trim() };
+                        this._subtypeSelectorConfig = {
+                            Path: parsed['Path'].trim(),
+                            UseForLoadedRecords: this.parseSubtypeSelectorUseForLoadedRecords(parsed),
+                        };
                     }
                     else {
                         LogError(`EntityInfo '${this.Name}': SubtypeSelector JSON must contain a non-empty 'Path' string property. Found: ${this.SubtypeSelector}`);
@@ -2076,6 +2186,19 @@ export class EntityInfo extends BaseInfo {
         }
         return this._subtypeSelectorConfig;
     }
+    /**
+     * Reads the selector's optional `UseForLoadedRecords` flag. Only a JSON `true` turns load hints
+     * on; a value of any other type is logged and leaves them off, so a quoted `"true"` can't look
+     * like an opt-in that silently does nothing.
+     */
+    parseSubtypeSelectorUseForLoadedRecords(parsed) {
+        const value = parsed['UseForLoadedRecords'];
+        if (value === undefined || value === null || typeof value === 'boolean') {
+            return value === true;
+        }
+        LogError(`EntityInfo '${this.Name}': SubtypeSelector 'UseForLoadedRecords' must be true or false, but is ${JSON.stringify(value)}. Loads of this entity won't use the selector.`);
+        return false;
+    }
     /**
      * True when at least one field is a writable Geo* source (street and/or native lat/lng).
      * Person/Org PrimaryAddress* are virtual display fields and do **not** count.
@@ -2083,6 +2206,62 @@ export class EntityInfo extends BaseInfo {
     get HasWritableGeoSourceFields() {
         return (this.Fields ?? []).some(f => f.IsWritableGeoField);
     }
+    /** @deprecated Use {@link SpCreate}. */
+    get spCreate() {
+        return this.SpCreate;
+    }
+    /** @deprecated Use {@link SpCreate}. */
+    set spCreate(value) {
+        this.SpCreate = value;
+    }
+    /** @deprecated Use {@link SpUpdate}. */
+    get spUpdate() {
+        return this.SpUpdate;
+    }
+    /** @deprecated Use {@link SpUpdate}. */
+    set spUpdate(value) {
+        this.SpUpdate = value;
+    }
+    /** @deprecated Use {@link SpDelete}. */
+    get spDelete() {
+        return this.SpDelete;
+    }
+    /** @deprecated Use {@link SpDelete}. */
+    set spDelete(value) {
+        this.SpDelete = value;
+    }
+    /** @deprecated Use {@link SpCreateGenerated}. */
+    get spCreateGenerated() {
+        return this.SpCreateGenerated;
+    }
+    /** @deprecated Use {@link SpCreateGenerated}. */
+    set spCreateGenerated(value) {
+        this.SpCreateGenerated = value;
+    }
+    /** @deprecated Use {@link SpUpdateGenerated}. */
+    get spUpdateGenerated() {
+        return this.SpUpdateGenerated;
+    }
+    /** @deprecated Use {@link SpUpdateGenerated}. */
+    set spUpdateGenerated(value) {
+        this.SpUpdateGenerated = value;
+    }
+    /** @deprecated Use {@link SpDeleteGenerated}. */
+    get spDeleteGenerated() {
+        return this.SpDeleteGenerated;
+    }
+    /** @deprecated Use {@link SpDeleteGenerated}. */
+    set spDeleteGenerated(value) {
+        this.SpDeleteGenerated = value;
+    }
+    /** @deprecated Use {@link SpMatch}. */
+    get spMatch() {
+        return this.SpMatch;
+    }
+    /** @deprecated Use {@link SpMatch}. */
+    set spMatch(value) {
+        this.SpMatch = value;
+    }
     /**
      * Optional JSON configuration bag (shape = {@link IEntityConfiguration}).
      * Nested `UI.Form` holds generated-form chrome: layout, auto left-nav
@@ -2117,6 +2296,66 @@ export class EntityInfo extends BaseInfo {
     get ConfigurationObject() {
         return this.Configuration;
     }
+    /**
+     * Parsed clone configuration for this entity.
+     * Controls clone enablement, not-cloneable status, caps, naming, field rules, etc.
+     * @see plans/record-cloning/README.md §4.1
+     */
+    get CloneConfig() {
+        return this.ConfigurationObject?.Clone ?? null;
+    }
+    /**
+     * Returns true if cloning is explicitly enabled for this entity as a ROOT record.
+     */
+    get CloneEnabled() {
+        return this.CloneConfig?.Enabled === true;
+    }
+    /**
+     * Returns true if this entity is strictly not cloneable (neither as root nor child).
+     */
+    get NotCloneable() {
+        return this.CloneConfig?.NotCloneable === true;
+    }
+    /** @deprecated Use {@link HasIdField}. */
+    get _hasIdField() {
+        return this.HasIdField;
+    }
+    /** @deprecated Use {@link HasIdField}. */
+    set _hasIdField(value) {
+        this.HasIdField = value;
+    }
+    /** @deprecated Use {@link VirtualCount}. */
+    get _virtualCount() {
+        return this.VirtualCount;
+    }
+    /** @deprecated Use {@link VirtualCount}. */
+    set _virtualCount(value) {
+        this.VirtualCount = value;
+    }
+    /** @deprecated Use {@link ManyToManyCount}. */
+    get _manyToManyCount() {
+        return this.ManyToManyCount;
+    }
+    /** @deprecated Use {@link ManyToManyCount}. */
+    set _manyToManyCount(value) {
+        this.ManyToManyCount = value;
+    }
+    /** @deprecated Use {@link OneToManyCount}. */
+    get _oneToManyCount() {
+        return this.OneToManyCount;
+    }
+    /** @deprecated Use {@link OneToManyCount}. */
+    set _oneToManyCount(value) {
+        this.OneToManyCount = value;
+    }
+    /** @deprecated Use {@link FloatCount}. */
+    get _floatCount() {
+        return this.FloatCount;
+    }
+    /** @deprecated Use {@link FloatCount}. */
+    set _floatCount(value) {
+        this.FloatCount = value;
+    }
     /**
      * The set of field names this user may NOT READ on this entity — the per-request primitive
      * every field-security enforcement point is built on.
@@ -2243,7 +2482,7 @@ export class EntityInfo extends BaseInfo {
         if (!this.EnableFieldLevelSecurity) {
             return denied;
         }
-        for (const field of this._Fields) {
+        for (const field of this._fields) {
             if (isDenied(field.GetUserFieldPermissions(user, true))) {
                 denied.add(field.Name.trim().toLowerCase());
                 denied.add(field.CodeName.trim().toLowerCase());
@@ -2267,7 +2506,7 @@ export class EntityInfo extends BaseInfo {
             return undefined;
         if (this._fieldByNameMap === null) {
             const map = new Map();
-            for (const f of this._Fields) {
+            for (const f of this._fields) {
                 if (f.Name != null)
                     map.set(f.Name.trim().toLowerCase(), f);
             }
@@ -2348,7 +2587,7 @@ export class EntityInfo extends BaseInfo {
      * @returns {EntityFieldInfo[]} Array of all entity fields
      */
     get Fields() {
-        return this._Fields;
+        return this._fields;
     }
     /**
      * Returns true if ANY field on this entity is `Deprecated` or `Disabled` (i.e. not `Active`).
@@ -2363,7 +2602,7 @@ export class EntityInfo extends BaseInfo {
      */
     get HasInactiveFields() {
         if (this._hasInactiveFields === undefined) {
-            this._hasInactiveFields = this._Fields.some(f => f.Status === 'Deprecated' || f.Status === 'Disabled');
+            this._hasInactiveFields = this._fields.some(f => f.Status === 'Deprecated' || f.Status === 'Disabled');
         }
         return this._hasInactiveFields;
     }
@@ -2389,7 +2628,7 @@ export class EntityInfo extends BaseInfo {
      */
     get HasSearchFields() {
         if (this._hasSearchFields === undefined) {
-            this._hasSearchFields = this._Fields.some(f => f.IncludeInUserSearchAPI);
+            this._hasSearchFields = this._fields.some(f => f.IncludeInUserSearchAPI);
         }
         return this._hasSearchFields;
     }
@@ -2398,21 +2637,21 @@ export class EntityInfo extends BaseInfo {
      * @returns {EntityRelationshipInfo[]} Array of entity relationships
      */
     get RelatedEntities() {
-        return this._RelatedEntities;
+        return this._relatedEntities;
     }
     /**
      * Gets the security permissions for this entity by role.
      * @returns {EntityPermissionInfo[]} Array of permission settings
      */
     get Permissions() {
-        return this._Permissions;
+        return this._permissions;
     }
     /**
      * Gets custom configuration settings for this entity.
      * @returns {EntitySettingInfo[]} Array of entity-specific settings
      */
     get Settings() {
-        return this._Settings;
+        return this._settings;
     }
     /**
      * Gets the parsed FieldCategoryInfo map for this entity, keyed by category name.
@@ -2420,7 +2659,7 @@ export class EntityInfo extends BaseInfo {
      * during EntityInfo construction. Returns null if no category info is configured.
      */
     get FieldCategories() {
-        return this._FieldCategories;
+        return this._fieldCategories;
     }
     /**
      * Gets the organic keys defined on this entity. Organic keys enable cross-entity
@@ -2429,7 +2668,7 @@ export class EntityInfo extends BaseInfo {
      * @returns {EntityOrganicKeyInfo[]} Array of organic key definitions with their related entities
      */
     get OrganicKeys() {
-        return this._OrganicKeys;
+        return this._organicKeys;
     }
     static { this.__createdAtFieldName = '__mj_CreatedAt'; }
     static { this.__updatedAtFieldName = '__mj_UpdatedAt'; }
@@ -2486,6 +2725,38 @@ export class EntityInfo extends BaseInfo {
     get DisplayNameOrName() {
         return this.DisplayName ? this.DisplayName : this.Name;
     }
+    /**
+     * Returns a business-user-friendly PLURAL of the entity's display name, e.g. "Contacts", "Companies",
+     * "Addresses". Derived from `DisplayNameOrName` via `GeneratePluralName`, so a per-deployment
+     * `DisplayName` override flows through (rename the entity's DisplayName to "Member" and this returns
+     * "Members"). Handles irregular plurals and the common English rules (`-y` to `-ies`, `-s/ch/sh/x/z` to `-es`).
+     *
+     * This is the seam for surfacing the user's own domain nouns in place of the platform meta-noun
+     * "entity" on business-user surfaces (empty states, counts, headers). It is display-only: never use it
+     * as a lookup key. If the display name is already plural, `GeneratePluralName` returns it unchanged.
+     *
+     * Memoized per instance: templates read this on every change-detection pass, and the source name
+     * is fixed per metadata load (the same assumption `_nameFieldCache` relies on). The cache is keyed
+     * by the source name so it stays correct if `DisplayName` is ever mutated in place.
+     */
+    get DisplayNamePlural() {
+        const source = this.DisplayNameOrName;
+        if (this._displayNamePluralCache?.source !== source) {
+            this._displayNamePluralCache = { source, plural: EntityInfo.matchLeadingCase(source, GeneratePluralName(source)) };
+        }
+        return this._displayNamePluralCache.plural;
+    }
+    /**
+     * Gives `plural` the same leading-letter case as `source`. The irregular-plural table stores
+     * lowercase values ('person' → 'people'), so without this an empty state reads "No people to
+     * display". Only the first letter is touched: `capitalizeFirstLetterOnly` would also capitalize a
+     * name that deliberately starts lowercase ("iPhone" → "IPhones").
+     */
+    static matchLeadingCase(source, plural) {
+        const lead = source.charAt(0);
+        const startsUpper = lead !== lead.toLowerCase();
+        return startsUpper && plural.length > 0 ? plural.charAt(0).toUpperCase() + plural.slice(1) : plural;
+    }
     /**
      * Returns the EntityField object for the Field that has IsNameField set to true. If multiple fields have IsNameField on, the function will return the first field (by sequence) that matches.
      * If no fields match, if there is a field called "Name", that is returned. If there is no field called "Name", null is returned.
@@ -3089,10 +3360,10 @@ export class EntityInfo extends BaseInfo {
         const params = {};
         const matchFields = organicKey.MatchFieldNamesArray;
         if (organicKeyRelatedEntity.IsTransitiveMatch) {
-            params.ExtraFilter = EntityInfo.BuildTransitiveOrganicKeyFilter(record, organicKeyRelatedEntity, organicKey, matchFields);
+            params.ExtraFilter = EntityInfo.buildTransitiveOrganicKeyFilter(record, organicKeyRelatedEntity, organicKey, matchFields);
         }
         else {
-            params.ExtraFilter = EntityInfo.BuildDirectOrganicKeyFilter(record, organicKeyRelatedEntity, organicKey, matchFields);
+            params.ExtraFilter = EntityInfo.buildDirectOrganicKeyFilter(record, organicKeyRelatedEntity, organicKey, matchFields);
         }
         if (filter && filter.length > 0) {
             params.ExtraFilter = `(${params.ExtraFilter}) AND (${filter})`;
@@ -3112,12 +3383,12 @@ export class EntityInfo extends BaseInfo {
      * matching organic key (same Name) to find its expression. Falls back to the hub's
      * expression on both sides if the spoke doesn't carry its own.
      */
-    static BuildDirectOrganicKeyFilter(record, relatedEntity, organicKey, matchFields) {
+    static buildDirectOrganicKeyFilter(record, relatedEntity, organicKey, matchFields) {
         const relatedFields = relatedEntity.RelatedEntityFieldNamesArray;
         const conditions = [];
         // Resolve the spoke entity's own organic key (matching by Name) to pull its
         // per-column normalization. Falls back to the hub's expression if not found.
-        const spokeOrganicKey = EntityInfo.ResolveSpokeOrganicKey(relatedEntity, organicKey);
+        const spokeOrganicKey = EntityInfo.resolveSpokeOrganicKey(relatedEntity, organicKey);
         for (let i = 0; i < matchFields.length; i++) {
             const value = record.Get(matchFields[i]);
             if (value == null) {
@@ -3126,7 +3397,7 @@ export class EntityInfo extends BaseInfo {
             }
             const relatedField = relatedFields[i] || matchFields[i];
             const escapedValue = String(value).replace(/'/g, "''");
-            conditions.push(EntityInfo.WrapBothSidesWithNormalization(`[${relatedField}]`, spokeOrganicKey ?? organicKey, escapedValue, organicKey));
+            conditions.push(EntityInfo.wrapBothSidesWithNormalization(`[${relatedField}]`, spokeOrganicKey ?? organicKey, escapedValue, organicKey));
         }
         return conditions.join(' AND ');
     }
@@ -3135,7 +3406,7 @@ export class EntityInfo extends BaseInfo {
      * the spoke's own normalization function on the spoke side. Returns undefined if the
      * spoke entity doesn't have a parallel organic key — caller falls back to the hub's.
      */
-    static ResolveSpokeOrganicKey(relatedEntity, hubOrganicKey, provider) {
+    static resolveSpokeOrganicKey(relatedEntity, hubOrganicKey, provider) {
         const md = provider ?? Metadata.Provider;
         if (!md)
             return undefined;
@@ -3148,7 +3419,7 @@ export class EntityInfo extends BaseInfo {
     /**
      * Builds an ExtraFilter for transitive organic key matching (via SQL view/table subquery).
      */
-    static BuildTransitiveOrganicKeyFilter(record, relatedEntity, organicKey, matchFields) {
+    static buildTransitiveOrganicKeyFilter(record, relatedEntity, organicKey, matchFields) {
         const transitiveMatchFields = relatedEntity.TransitiveObjectMatchFieldNamesArray;
         const conditions = [];
         // Transitive bridge values are normalized using the HUB's expression on both sides —
@@ -3161,7 +3432,7 @@ export class EntityInfo extends BaseInfo {
             }
             const transitiveField = transitiveMatchFields[i] || matchFields[i];
             const escapedValue = String(value).replace(/'/g, "''");
-            conditions.push(EntityInfo.WrapWithNormalization(`[${transitiveField}]`, organicKey, escapedValue));
+            conditions.push(EntityInfo.wrapWithNormalization(`[${transitiveField}]`, organicKey, escapedValue));
         }
         // TransitiveObjectName is schema-qualified (e.g. "mailchimp.vwBridge") — bracket each part separately
         const transitiveObject = relatedEntity.TransitiveObjectName.split('.').map(p => `[${p}]`).join('.');
@@ -3172,7 +3443,7 @@ export class EntityInfo extends BaseInfo {
      * based on the organic key's NormalizationStrategy.
      * Returns a SQL comparison expression like: LOWER(LTRIM(RTRIM([Field]))) = LOWER(LTRIM(RTRIM('value')))
      */
-    static WrapWithNormalization(fieldExpression, organicKey, escapedValue) {
+    static wrapWithNormalization(fieldExpression, organicKey, escapedValue) {
         switch (organicKey.NormalizationStrategy) {
             case 'LowerCaseTrim':
                 return `LOWER(LTRIM(RTRIM(${fieldExpression}))) = LOWER(LTRIM(RTRIM('${escapedValue}')))`;
@@ -3204,13 +3475,13 @@ export class EntityInfo extends BaseInfo {
      * when the expressions agree; different transforms applied independently when they
      * don't (the per-column normalization case).
      */
-    static WrapBothSidesWithNormalization(fieldExpression, fieldOrganicKey, escapedValue, valueOrganicKey) {
-        const leftSide = EntityInfo.NormalizeFieldExpression(fieldExpression, fieldOrganicKey);
-        const rightSide = EntityInfo.NormalizeLiteralExpression(escapedValue, valueOrganicKey);
+    static wrapBothSidesWithNormalization(fieldExpression, fieldOrganicKey, escapedValue, valueOrganicKey) {
+        const leftSide = EntityInfo.normalizeFieldExpression(fieldExpression, fieldOrganicKey);
+        const rightSide = EntityInfo.normalizeLiteralExpression(escapedValue, valueOrganicKey);
         return `${leftSide} = ${rightSide}`;
     }
     /** Apply an organic key's normalization to a SQL field expression (left side of compare). */
-    static NormalizeFieldExpression(fieldExpression, organicKey) {
+    static normalizeFieldExpression(fieldExpression, organicKey) {
         switch (organicKey.NormalizationStrategy) {
             case 'LowerCaseTrim': return `LOWER(LTRIM(RTRIM(${fieldExpression})))`;
             case 'Trim': return `LTRIM(RTRIM(${fieldExpression}))`;
@@ -3226,7 +3497,7 @@ export class EntityInfo extends BaseInfo {
         }
     }
     /** Apply an organic key's normalization to a quoted literal value (right side of compare). */
-    static NormalizeLiteralExpression(escapedValue, organicKey) {
+    static normalizeLiteralExpression(escapedValue, organicKey) {
         switch (organicKey.NormalizationStrategy) {
             case 'LowerCaseTrim': return `LOWER(LTRIM(RTRIM('${escapedValue}')))`;
             case 'Trim': return `LTRIM(RTRIM('${escapedValue}'))`;
@@ -3522,27 +3793,27 @@ export class EntityInfo extends BaseInfo {
         /**
          * Name of the stored procedure for creating records
          */
-        this.spCreate = null;
+        this.SpCreate = null;
         /**
          * Name of the stored procedure for updating records
          */
-        this.spUpdate = null;
+        this.SpUpdate = null;
         /**
          * Name of the stored procedure for deleting records
          */
-        this.spDelete = null;
+        this.SpDelete = null;
         /**
          * Whether the create stored procedure is generated by CodeGen
          */
-        this.spCreateGenerated = null;
+        this.SpCreateGenerated = null;
         /**
          * Whether the update stored procedure is generated by CodeGen
          */
-        this.spUpdateGenerated = null;
+        this.SpUpdateGenerated = null;
         /**
          * Whether the delete stored procedure is generated by CodeGen
          */
-        this.spDeleteGenerated = null;
+        this.SpDeleteGenerated = null;
         /**
          * Whether to automatically delete related records when a parent is deleted
          */
@@ -3558,7 +3829,7 @@ export class EntityInfo extends BaseInfo {
         /**
          * Name of the stored procedure used for matching/duplicate detection
          */
-        this.spMatch = null;
+        this.SpMatch = null;
         /**
          * Default display type for relationships: Search (type-ahead) or Dropdown
          */
@@ -3683,13 +3954,13 @@ export class EntityInfo extends BaseInfo {
         this.ParentEntity = null;
         this.ParentBaseTable = null;
         this.ParentBaseView = null;
-        this._FieldCategories = null;
-        this._OrganicKeys = [];
-        this._hasIdField = false;
-        this._virtualCount = 0;
-        this._manyToManyCount = 0;
-        this._oneToManyCount = 0;
-        this._floatCount = 0;
+        this._fieldCategories = null;
+        this._organicKeys = [];
+        this.HasIdField = false;
+        this.VirtualCount = 0;
+        this.ManyToManyCount = 0;
+        this.OneToManyCount = 0;
+        this.FloatCount = 0;
         // --- Lazy caches for immutable field-derived collections ---------------------------------
         // `_Fields` is populated once in the constructor and never reassigned, so these caches never
         // need invalidation. They replace per-access `.filter()`/`.find()` scans on hot paths
@@ -3702,6 +3973,8 @@ export class EntityInfo extends BaseInfo {
         this._encryptedFieldsCache = null;
         this._datetimeFieldsCache = null;
         this._nameFieldCache = undefined;
+        /** Memoized computed plural, keyed by the display name it was derived from (see `DisplayNamePlural`). */
+        this._displayNamePluralCache = undefined;
         this._hasInactiveFields = undefined;
         this._hasSearchFields = undefined;
         // Cache for ParentChain to avoid repeated walks
@@ -3712,7 +3985,7 @@ export class EntityInfo extends BaseInfo {
             this.copyInitData(initData);
             // do some special handling to create class instances instead of just data objects
             // copy the Entity Fields (accept EntityFields, _Fields, or Fields as input names)
-            this._Fields = [];
+            this._fields = [];
             // Reset every lazy field-derived memo cache whenever _Fields is (re)assigned.
             // `entityInfo.cacheReset.test.ts` mirrors this list in `runProductionCacheReset`;
             // a cache added here needs adding there too, or its reset goes unexercised.
@@ -3739,27 +4012,27 @@ export class EntityInfo extends BaseInfo {
             const ef = initData.EntityFields || initData._Fields || initData.Fields;
             if (ef) {
                 for (let j = 0; j < ef.length; j++) {
-                    this._Fields.push(new EntityFieldInfo(ef[j]));
+                    this._fields.push(new EntityFieldInfo(ef[j]));
                 }
             }
             // copy the Entity Permissions
-            this._Permissions = [];
+            this._permissions = [];
             const ep = initData.EntityPermissions || initData._Permissions || initData.Permissions;
             if (ep) {
                 for (let j = 0; j < ep.length; j++) {
-                    this._Permissions.push(new EntityPermissionInfo(ep[j]));
+                    this._permissions.push(new EntityPermissionInfo(ep[j]));
                 }
             }
             // copy the Entity settings
-            this._Settings = [];
+            this._settings = [];
             const es = initData.EntitySettings || initData._Settings || initData.Settings;
             if (es) {
-                es.map((s) => this._Settings.push(new EntitySettingInfo(s)));
+                es.map((s) => this._settings.push(new EntitySettingInfo(s)));
             }
             // auto-populate FieldCategories from the FieldCategoryInfo setting
-            this._FieldCategories = this.parseFieldCategoriesFromSettings();
+            this._fieldCategories = this.parseFieldCategoriesFromSettings();
             // copy the Related Entities (accept EntityRelationships, _RelatedEntities, or RelatedEntities as input names)
-            this._RelatedEntities = [];
+            this._relatedEntities = [];
             const er = initData.EntityRelationships || initData._RelatedEntities || initData.RelatedEntities;
             if (er) {
                 // check to see if ANY of the records in the er array have a non-null or non-zero sequence value. The reason is 
@@ -3782,15 +4055,15 @@ export class EntityInfo extends BaseInfo {
                 }
                 // now that we have prepared the er array by sorting it, if needed, let's load up the related entities
                 for (let j = 0; j < er.length; j++) {
-                    this._RelatedEntities.push(new EntityRelationshipInfo(er[j]));
+                    this._relatedEntities.push(new EntityRelationshipInfo(er[j]));
                 }
             }
             // copy the Organic Keys (sorted by sequence inside EntityOrganicKeyInfo constructor)
-            this._OrganicKeys = [];
+            this._organicKeys = [];
             const ok = initData.EntityOrganicKeys || initData._OrganicKeys || initData.OrganicKeys;
             if (ok && Array.isArray(ok)) {
                 for (const item of ok) {
-                    this._OrganicKeys.push(new EntityOrganicKeyInfo(item));
+                    this._organicKeys.push(new EntityOrganicKeyInfo(item));
                 }
             }
             this.prepareSpecialFields();
@@ -3810,9 +4083,9 @@ export class EntityInfo extends BaseInfo {
                 virtualCount += f.IsVirtual ? 1 : 0;
                 floatCount += f.IsFloat ? 1 : 0;
             }
-            this._hasIdField = hasIdField;
-            this._floatCount = floatCount;
-            this._virtualCount = virtualCount;
+            this.HasIdField = hasIdField;
+            this.FloatCount = floatCount;
+            this.VirtualCount = virtualCount;
             // now see if there are any relationships and count the one to many and many to many
             for (let j = 0; j < this.RelatedEntities.length; ++j) {
                 const r = this.RelatedEntities[j];
@@ -3821,8 +4094,8 @@ export class EntityInfo extends BaseInfo {
                 else
                     manyToManyCount++;
             }
-            this._manyToManyCount = manyToManyCount;
-            this._oneToManyCount = oneToManyCount;
+            this.ManyToManyCount = manyToManyCount;
+            this.OneToManyCount = oneToManyCount;
         }
         catch (e) {
             LogError(e);
@@ -3833,11 +4106,11 @@ export class EntityInfo extends BaseInfo {
      * Called once during construction so the result is cached on _FieldCategories.
      */
     parseFieldCategoriesFromSettings() {
-        if (!this._Settings || this._Settings.length === 0) {
+        if (!this._settings || this._settings.length === 0) {
             return null;
         }
         // Try new format first
-        const infoSetting = this._Settings.find(s => s.Name === 'FieldCategoryInfo');
+        const infoSetting = this._settings.find(s => s.Name === 'FieldCategoryInfo');
         if (infoSetting?.Value) {
             const parsed = SafeJSONParse(infoSetting.Value, false);
             if (parsed) {
@@ -3845,7 +4118,7 @@ export class EntityInfo extends BaseInfo {
             }
         }
         // Fallback to legacy FieldCategoryIcons format (icon-only map)
-        const iconSetting = this._Settings.find(s => s.Name === 'FieldCategoryIcons');
+        const iconSetting = this._settings.find(s => s.Name === 'FieldCategoryIcons');
         if (iconSetting?.Value) {
             const icons = SafeJSONParse(iconSetting.Value, false);
             if (icons) {