Clean up EntityMetaData and fix incorrect release tags

common/api/core-backend.api.md

@@ -173,6 +173,7 @@ import { Polyface } from '@itwin/core-geometry';
 import { PolyfaceData } from '@itwin/core-geometry';
 import { PolyfaceVisitor } from '@itwin/core-geometry';
 import { PropertyCallback } from '@itwin/core-common';
+import { PropertyMetaDataCallback } from '@itwin/core-common';
 import { QueryBinder } from '@itwin/core-common';
 import { QueryOptions } from '@itwin/core-common';
 import { Range2d } from '@itwin/core-geometry';
@@ -2253,7 +2254,7 @@ export class Entity {
  protected collectReferenceConcreteIds: (_referenceIds: EntityReferenceSet) => void;
  // @beta
  protected collectReferenceIds(_referenceIds: EntityReferenceSet): void;
- forEachProperty(func: PropertyCallback, includeCustom?: boolean): void;
+ forEachProperty(func: PropertyCallback | PropertyMetaDataCallback, includeCustom?: boolean): void;
  // @internal @deprecated
  getReferenceConcreteIds: () => EntityReferenceSet;
  // @beta
@@ -3068,8 +3069,8 @@ export abstract class IModelDb extends IModel {
  get fontMap(): FontMap;
  // (undocumented)
  protected _fontMap?: FontMap;
- static forEachMetaData(iModel: IModelDb, classFullName: string, wantSuper: boolean, func: PropertyCallback, includeCustom?: boolean): void;
- forEachMetaData(classFullName: string, wantSuper: boolean, func: PropertyCallback, includeCustom?: boolean): void;
+ static forEachMetaData(iModel: IModelDb, classFullName: string, wantSuper: boolean, func: PropertyMetaDataCallback | PropertyCallback, includeCustom?: boolean): void;
+ forEachMetaData(classFullName: string, wantSuper: boolean, func: PropertyMetaDataCallback | PropertyCallback, includeCustom?: boolean): void;
  generateElementGraphics(request: ElementGraphicsRequestProps): Promise<Uint8Array | undefined>;
  getBriefcaseId(): BriefcaseId;
  getGeoCoordinatesFromIModelCoordinates(props: GeoCoordinatesRequestProps): Promise<GeoCoordinatesResponseProps>;

common/api/core-common.api.md

@@ -1815,7 +1815,7 @@ export enum CurrentImdlVersion {
  Minor = 0
 }
 
-// @beta
+// @public
 export interface CustomAttribute {
  ecclass: string;
  properties: {
@@ -2910,37 +2910,38 @@ export interface EntityIdAndClassId {
 // @public
 export type EntityIdAndClassIdIterable = Iterable<Readonly<EntityIdAndClassId>>;
 
-// @beta
-export class EntityMetaData implements EntityMetaDataProps {
+// @public
+export class EntityMetaData {
  constructor(jsonObj: EntityMetaDataProps);
  readonly baseClasses: string[];
  readonly classId: Id64String;
  readonly customAttributes?: CustomAttribute[];
- // (undocumented)
  readonly description?: string;
- // (undocumented)
  readonly displayLabel?: string;
  readonly ecclass: string;
- // (undocumented)
+ // @internal
+ getMutableProperties(): Iterable<PropertyMetaData & {
+ name: string;
+ }>;
+ getProperties(): Iterable<Readonly<PropertyMetaData & {
+ name: string;
+ }>>;
+ getProperty(name: string): Readonly<PropertyMetaData> | undefined;
  readonly modifier?: string;
- readonly properties: {
+ // @deprecated
+ get properties(): {
  [propName: string]: PropertyMetaData;
  };
 }
 
-// @beta (undocumented)
+// @public
 export interface EntityMetaDataProps {
  baseClasses: string[];
- // (undocumented)
  classId: Id64String;
  customAttributes?: CustomAttribute[];
- // (undocumented)
  description?: string;
- // (undocumented)
  displayLabel?: string;
- // (undocumented)
  ecclass: string;
- // (undocumented)
  modifier?: string;
  properties: {
  [propName: string]: PropertyMetaData;
@@ -6818,7 +6819,7 @@ export interface PrimaryTileTreeId {
  type: BatchType.Primary;
 }
 
-// @beta
+// @public
 export enum PrimitiveTypeCode {
  // (undocumented)
  Binary = 257,
@@ -6922,52 +6923,39 @@ export interface ProjectionProps {
  zoneNumber?: number;
 }
 
-// @beta
+// @public @deprecated
 export type PropertyCallback = (name: string, meta: PropertyMetaData) => void;
 
-// @beta
+// @public
 export class PropertyMetaData implements PropertyMetaDataProps {
  constructor(jsonObj: PropertyMetaDataProps);
+ // @deprecated
  createProperty(jsonObj: any): any;
- // (undocumented)
  customAttributes?: CustomAttribute[];
- // (undocumented)
  description?: string;
- // (undocumented)
  direction?: string;
- // (undocumented)
  displayLabel?: string;
- // (undocumented)
  extendedType?: string;
- // (undocumented)
  isCustomHandled?: boolean;
- // (undocumented)
+ // @deprecated (undocumented)
  isCustomHandledOrphan?: boolean;
  get isNavigation(): boolean;
- // (undocumented)
  kindOfQuantity?: string;
- // (undocumented)
  maximumLength?: number;
- // (undocumented)
  maximumValue?: any;
- // (undocumented)
  maxOccurs?: number;
- // (undocumented)
  minimumLength?: number;
- // (undocumented)
  minimumValue?: any;
- // (undocumented)
  minOccurs?: number;
- // (undocumented)
  primitiveType?: PrimitiveTypeCode;
- // (undocumented)
  readOnly?: boolean;
- // (undocumented)
  relationshipClass?: string;
- // (undocumented)
  structName?: string;
 }
 
+// @public
+export type PropertyMetaDataCallback = (name: string, meta: Readonly<PropertyMetaData>) => void;
+
 // @public (undocumented)
 export class PropertyMetaDataMap implements Iterable<QueryPropertyMetaData> {
  // (undocumented)
@@ -6985,43 +6973,26 @@ export class PropertyMetaDataMap implements Iterable<QueryPropertyMetaData> {
  readonly properties: QueryPropertyMetaData[];
 }
 
-// @beta (undocumented)
+// @public
 export interface PropertyMetaDataProps {
- // (undocumented)
  customAttributes?: CustomAttribute[];
- // (undocumented)
  description?: string;
- // (undocumented)
  direction?: string;
- // (undocumented)
  displayLabel?: string;
- // (undocumented)
  extendedType?: string;
- // (undocumented)
  isCustomHandled?: boolean;
- // (undocumented)
+ // @deprecated (undocumented)
  isCustomHandledOrphan?: boolean;
- // (undocumented)
  kindOfQuantity?: string;
- // (undocumented)
  maximumLength?: number;
- // (undocumented)
  maximumValue?: any;
- // (undocumented)
  maxOccurs?: number;
- // (undocumented)
  minimumLength?: number;
- // (undocumented)
  minimumValue?: any;
- // (undocumented)
  minOccurs?: number;
- // (undocumented)
  primitiveType?: number;
- // (undocumented)
  readOnly?: boolean;
- // (undocumented)
  relationshipClass?: string;
- // (undocumented)
  structName?: string;
 }
 

common/api/summary/core-common.exports.csv

@@ -156,7 +156,7 @@ internal;interface;CreateStandaloneIModelProps
 internal;const;CURRENT_INVOCATION
 internal;const;CURRENT_REQUEST
 internal;enum;CurrentImdlVersion
-beta;interface;CustomAttribute
+public;interface;CustomAttribute
 internal;interface;CustomViewState3dCreatorOptions
 internal;interface;CustomViewState3dProps
 public;class;CutStyle
@@ -242,8 +242,8 @@ public;interface;EmphasizeElementsProps
 public;class;EmptyLocalization
 public;interface;EntityIdAndClassId
 public;type;EntityIdAndClassIdIterable
-beta;class;EntityMetaData
-beta;interface;EntityMetaDataProps
+public;class;EntityMetaData
+public;interface;EntityMetaDataProps
 public;interface;EntityProps
 public;interface;EntityQueryParams
 alpha;type;EntityReference
@@ -591,16 +591,18 @@ public;enum;PolylineTypeFlags
 public;class;PositionalVectorTransform
 public;interface;PositionalVectorTransformProps
 internal;interface;PrimaryTileTreeId
-beta;enum;PrimitiveTypeCode
+public;enum;PrimitiveTypeCode
 public;interface;PriorityPlanarClipMaskArgs
 beta;enum;ProfileOptions
 public;class;Projection
 public;type;ProjectionMethod
 public;interface;ProjectionProps
-beta;type;PropertyCallback
-beta;class;PropertyMetaData
+public;type;PropertyCallback
+deprecated;type;PropertyCallback
+public;class;PropertyMetaData
+public;type;PropertyMetaDataCallback
 public;class;PropertyMetaDataMap
-beta;interface;PropertyMetaDataProps
+public;interface;PropertyMetaDataProps
 internal;interface;PullChangesOptions
 public;class;QParams2d
 alpha;interface;QParams2dProps

common/changes/@itwin/core-backend/pmc-entity-metadata_2024-08-02-12-40.json

@@ -0,0 +1,10 @@
+{
+ "changes": [
+ {
+ "packageName": "@itwin/core-backend",
+ "comment": "",
+ "type": "none"
+ }
+ ],
+ "packageName": "@itwin/core-backend"
+}

common/changes/@itwin/core-common/pmc-entity-metadata_2024-08-02-12-40.json

@@ -0,0 +1,10 @@
+{
+ "changes": [
+ {
+ "packageName": "@itwin/core-common",
+ "comment": "Clean up EntityMetaData APIs and promote to public.",
+ "type": "none"
+ }
+ ],
+ "packageName": "@itwin/core-common"
+}

core/backend/src/ClassRegistry.ts

@@ -95,12 +95,10 @@ export class ClassRegistry {
  * @param entityMetaData The Entity metadata that defines the class
  */
  private static generateClassForEntity(entityMetaData: EntityMetaData, iModel: IModelDb): typeof Entity {
- const name = entityMetaData.ecclass.split(":");
- const domainName = name[0];
- const className = name[1];
+ const [domainName, className] = entityMetaData.ecclass.split(":");
 
  if (0 === entityMetaData.baseClasses.length) // metadata must contain a superclass
- throw new IModelError(IModelStatus.BadArg, `class ${name} has no superclass`);
+ throw new IModelError(IModelStatus.BadArg, `class ${entityMetaData.ecclass} has no superclass`);
 
  // make sure schema exists
  let schema = Schemas.getRegisteredSchema(domainName);
@@ -109,7 +107,7 @@ export class ClassRegistry {
 
  const superclass = this._classMap.get(entityMetaData.baseClasses[0].toLowerCase());
  if (undefined === superclass)
- throw new IModelError(IModelStatus.NotFound, `cannot find superclass for class ${name}`);
+ throw new IModelError(IModelStatus.NotFound, `cannot find superclass for class ${entityMetaData.ecclass}`);
 
  // user defined class hierarchies may skip a class in the hierarchy, and therefore their JS base class cannot
  // be used to tell if there are any generated classes in the hierarchy
@@ -146,10 +144,10 @@ export class ClassRegistry {
  // - it is not in the `BisCore` schema
  // - there are no ancestors with manually registered JS implementations, (excluding BisCore base classes)
  if (!generatedClassHasNonGeneratedNonCoreAncestor) {
- const navigationProps = Object.entries(entityMetaData.properties)
- .filter(([_name, prop]) => prop.isNavigation)
+ const navigationProps = Array.from(entityMetaData.getProperties())
+ .filter((prop) => prop.isNavigation)
  // eslint-disable-next-line @typescript-eslint/no-shadow
- .map(([name, prop]) => {
+ .map((prop) => {
  assert(prop.relationshipClass);
  const maybeMetaData = iModel[_nativeDb].getSchemaItem(...prop.relationshipClass.split(":") as [string, string]);
  assert(maybeMetaData.result !== undefined, "The nav props relationship metadata was not found");
@@ -160,7 +158,7 @@ export class ClassRegistry {
  const normalizeClassName = (clsName: string) => clsName.replace(".", ":");
  const rootClass = ClassRegistry.findRegisteredClass(normalizeClassName(rootClassMetaData));
  assert(rootClass, `The root class for ${prop.relationshipClass} was not in BisCore.`);
- return { name, concreteEntityType: EntityReferences.typeFromClass(rootClass) };
+ return { name: prop.name, concreteEntityType: EntityReferences.typeFromClass(rootClass) };
  });
 
  Object.defineProperty(

core/backend/src/Entity.ts

@@ -7,7 +7,7 @@
  */
 
 import { Id64, Id64String } from "@itwin/core-bentley";
-import { EntityProps, EntityReferenceSet, PropertyCallback, PropertyMetaData } from "@itwin/core-common";
+import { EntityProps, EntityReferenceSet, PropertyCallback, PropertyMetaData, PropertyMetaDataCallback } from "@itwin/core-common";
 import type { IModelDb } from "./IModelDb";
 import { Schema } from "./Schema";
 
@@ -55,6 +55,7 @@ export class Entity {
  this.iModel = iModel;
  this.id = Id64.fromJSON(props.id);
  // copy all auto-handled properties from input to the object being constructed
+ // eslint-disable-next-line deprecation/deprecation
  this.forEachProperty((propName: string, meta: PropertyMetaData) => (this as any)[propName] = meta.createProperty((props as any)[propName]), false);
  }
 
@@ -82,7 +83,7 @@ export class Entity {
  * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
  * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
  */
- public forEachProperty(func: PropertyCallback, includeCustom: boolean = true) {
+ public forEachProperty(func: PropertyCallback | PropertyMetaDataCallback, includeCustom: boolean = true) { // eslint-disable-line deprecation/deprecation
  this.iModel.forEachMetaData(this.classFullName, true, func, includeCustom);
  }
 

core/backend/src/IModelDb.ts

@@ -22,7 +22,7 @@ import {
  GeoCoordinatesRequestProps, GeoCoordinatesResponseProps, GeometryContainmentRequestProps, GeometryContainmentResponseProps, IModel,
  IModelCoordinatesRequestProps, IModelCoordinatesResponseProps, IModelError, IModelNotFoundResponse, IModelTileTreeProps, LocalFileName,
  MassPropertiesRequestProps, MassPropertiesResponseProps, ModelExtentsProps, ModelLoadProps, ModelProps, ModelSelectorProps, OpenBriefcaseProps,
- OpenCheckpointArgs, OpenSqliteArgs, ProfileOptions, PropertyCallback, QueryBinder, QueryOptions, QueryOptionsBuilder, QueryRowFormat, SchemaState,
+ OpenCheckpointArgs, OpenSqliteArgs, ProfileOptions, PropertyCallback, PropertyMetaDataCallback, QueryBinder, QueryOptions, QueryOptionsBuilder, QueryRowFormat, SchemaState,
  SheetProps, SnapRequestProps, SnapResponseProps, SnapshotOpenOptions, SpatialViewDefinitionProps, SubCategoryResultRow, TextureData,
  TextureLoadProps, ThumbnailProps, UpgradeOptions, ViewDefinition2dProps, ViewDefinitionProps, ViewIdString, ViewQueryParams, ViewStateLoadProps,
  ViewStateProps, ViewStoreRpc,
@@ -1111,7 +1111,7 @@ export abstract class IModelDb extends IModel {
  * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
  * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
  */
- public static forEachMetaData(iModel: IModelDb, classFullName: string, wantSuper: boolean, func: PropertyCallback, includeCustom: boolean = true) {
+ public static forEachMetaData(iModel: IModelDb, classFullName: string, wantSuper: boolean, func: PropertyMetaDataCallback | PropertyCallback, includeCustom: boolean = true) { // eslint-disable-line deprecation/deprecation
  iModel.forEachMetaData(classFullName, wantSuper, func, includeCustom);
  }
 
@@ -1122,12 +1122,11 @@ export abstract class IModelDb extends IModel {
  * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
  * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
  */
- public forEachMetaData(classFullName: string, wantSuper: boolean, func: PropertyCallback, includeCustom: boolean = true) {
+ public forEachMetaData(classFullName: string, wantSuper: boolean, func: PropertyMetaDataCallback | PropertyCallback, includeCustom: boolean = true) { // eslint-disable-line deprecation/deprecation
  const meta = this.getMetaData(classFullName); // will load if necessary
- for (const propName in meta.properties) { // eslint-disable-line guard-for-in
- const propMeta = meta.properties[propName];
- if (includeCustom || !propMeta.isCustomHandled || propMeta.isCustomHandledOrphan)
- func(propName, propMeta);
+ for (const propMeta of meta.getMutableProperties()) {
+ if (includeCustom || !propMeta.isCustomHandled)
+ func(propMeta.name, propMeta);
  }
 
  if (wantSuper && meta.baseClasses && meta.baseClasses.length > 0)