@itwin/ecschema-metadata 5.0.0-dev.99 → 5.1.0-dev.1

package/lib/esm/Metadata/Class.js

@@ -9,7 +9,7 @@ import { assert } from "@itwin/core-bentley";
 import { DelayedPromiseWithProps } from "../DelayedPromise";
 import { XmlSerializationUtils } from "../Deserialization/XmlSerializationUtils";
 import { AbstractSchemaItemType, classModifierToString, ECClassModifier, parseClassModifier, parsePrimitiveType, PrimitiveType, SchemaItemType } from "../ECObjects";
-import { ECObjectsError, ECObjectsStatus } from "../Exception";
+import { ECSchemaError, ECSchemaStatus } from "../Exception";
 import { SchemaItemKey, SchemaKey } from "../SchemaKey";
 import { serializeCustomAttributes } from "./CustomAttribute";
 import { Enumeration } from "./Enumeration";
@@ -18,9 +18,10 @@ import { SchemaItem } from "./SchemaItem";
 import { SchemaReadHelper } from "../Deserialization/Helper";
 /**
  * A common abstract class for all of the ECClass types.
- * @beta
+ * @public @preview
  */
 export class ECClass extends SchemaItem {
+    /** @internal */
     static get schemaItemType() { return AbstractSchemaItemType.Class; } // need this so getItem("name", ECClass) in schema works
     _modifier;
     _baseClass;
@@ -30,6 +31,7 @@ export class ECClass extends SchemaItem {
     _mergedPropertyCache;
     get modifier() { return this._modifier; }
     get customAttributes() { return this._customAttributes; }
+    /** @internal */
     constructor(schema, name, modifier) {
         super(schema, name);
         if (modifier)
@@ -43,8 +45,16 @@ export class ECClass extends SchemaItem {
     get baseClass() {
         return this._baseClass;
     }
+    getBaseClassSync() {
+        if (!this.baseClass) {
+            return undefined;
+        }
+        return this.schema.lookupItemSync(this.baseClass, ECClass);
+    }
     /**
      * Sets the base class of the ECClass. Pass undefined to 'remove' the base class.
+     *
+     * @internal
      */
     async setBaseClass(baseClass) {
         const oldBaseClass = this._baseClass;
@@ -67,6 +77,8 @@ export class ECClass extends SchemaItem {
      * Convenience method for adding an already loaded ECProperty used by create*Property methods.
      * @param prop The property to add.
      * @return The property that was added.
+     *
+     * @internal
      */
     addProperty(prop) {
         if (!this._properties)
@@ -78,7 +90,7 @@ export class ECClass extends SchemaItem {
     /**
      * Deletes a property from within this class.
      * @param name The property name to delete, lookup is case-insensitive
-     * @alpha
+     * @internal
      */
     async deleteProperty(name) {
         if (this._properties) {
@@ -92,7 +104,7 @@ export class ECClass extends SchemaItem {
     /**
      * Deletes a property from within this class.
      * @param name The property name to delete, lookup is case-insensitive
-     * @alpha
+     * @internal
      */
     deletePropertySync(name) {
         if (this._properties) {
@@ -103,40 +115,37 @@ export class ECClass extends SchemaItem {
             }
         }
     }
-    getBaseClassSync() {
-        if (!this.baseClass) {
-            return undefined;
-        }
-        return this.schema.lookupItemSync(this.baseClass, ECClass);
-    }
     /**
-     * Searches, case-insensitive, for a local ECProperty with the name provided.
-     * @param name
+     * Searches, case-insensitive, for an ECProperty with given the name on this class and, by default, on
+     * all base classes. Set excludeInherited to 'true' to only search the local class.
+     * @param name The name of the property to retrieve.
+     * @param excludeInherited If true, excludes inherited properties from the results. Defaults to false.
      */
-    async getProperty(name, includeInherited = false) {
+    async getProperty(name, excludeInherited = false) {
         if (this._properties) {
             const upperKey = name.toUpperCase();
             const property = this._properties.get(upperKey);
             if (property)
                 return property;
         }
-        if (!includeInherited) {
+        if (excludeInherited) {
             return undefined;
         }
         return this.getInheritedProperty(name);
     }
     /**
      * Searches, case-insensitive, for a local ECProperty with the name provided.
-     * @param name
+     * @param name The name of the property to retrieve.
+     * @param excludeInherited If true, excludes inherited properties from the results. Defaults to false.
      */
-    getPropertySync(name, includeInherited = false) {
+    getPropertySync(name, excludeInherited = false) {
         if (this._properties) {
             const upperKey = name.toUpperCase();
             const property = this._properties.get(upperKey);
             if (property)
                 return property;
         }
-        if (!includeInherited) {
+        if (excludeInherited) {
             return undefined;
         }
         return this.getInheritedPropertySync(name);
@@ -148,7 +157,7 @@ export class ECClass extends SchemaItem {
     async getInheritedProperty(name) {
         if (this.baseClass) {
             const baseClassObj = await this.baseClass;
-            return baseClassObj.getProperty(name, true);
+            return baseClassObj.getProperty(name);
         }
         return undefined;
     }
@@ -159,36 +168,36 @@ export class ECClass extends SchemaItem {
     getInheritedPropertySync(name) {
         const baseClassObj = this.getBaseClassSync();
         if (baseClassObj)
-            return baseClassObj.getPropertySync(name, true);
+            return baseClassObj.getPropertySync(name);
         return undefined;
     }
     async createPrimitiveProperty(name, primitiveType) {
-        if (await this.getProperty(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         const propType = await this.loadPrimitiveType(primitiveType, this.schema);
         if (typeof (propType) === "number")
             return this.addProperty(new PrimitiveProperty(this, name, propType));
         return this.addProperty(new EnumerationProperty(this, name, new DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitivePropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         const propType = this.loadPrimitiveTypeSync(primitiveType, this.schema);
         if (typeof (propType) === "number")
             return this.addProperty(new PrimitiveProperty(this, name, propType));
         return this.addProperty(new EnumerationProperty(this, name, new DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     async createPrimitiveArrayProperty(name, primitiveType) {
-        if (await this.getProperty(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         const propType = await this.loadPrimitiveType(primitiveType, this.schema);
         if (typeof (propType) === "number")
             return this.addProperty(new PrimitiveArrayProperty(this, name, propType));
         return this.addProperty(new EnumerationArrayProperty(this, name, new DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitiveArrayPropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         const propType = this.loadPrimitiveTypeSync(primitiveType, this.schema);
         if (typeof (propType) === "number")
             return this.addProperty(new PrimitiveArrayProperty(this, name, propType));
@@ -198,42 +207,58 @@ export class ECClass extends SchemaItem {
      *
      * @param name The name of property to create.
      * @param structType The struct type of property to create.
+     *
+     * @internal
      */
     async createStructProperty(name, structType) {
-        if (await this.getProperty(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new StructProperty(this, name, await this.loadStructType(structType, this.schema)));
     }
     /**
      *
      * @param name The name of property to create.
      * @param structType The struct type of property to create.
+     *
+     * @internal
      */
     createStructPropertySync(name, structType) {
-        if (this.getPropertySync(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new StructProperty(this, name, this.loadStructTypeSync(structType, this.schema)));
     }
     /**
      *
      * @param name
      * @param type
+     *
+     * @internal
      */
     async createStructArrayProperty(name, structType) {
-        if (await this.getProperty(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new StructArrayProperty(this, name, await this.loadStructType(structType, this.schema)));
     }
     /**
      *
      * @param name
      * @param type
+     *
+     * @internal
      */
     createStructArrayPropertySync(name, structType) {
-        if (this.getPropertySync(name))
-            throw new ECObjectsError(ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new ECSchemaError(ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new StructArrayProperty(this, name, this.loadStructTypeSync(structType, this.schema)));
     }
+    /**
+     *
+     * @param structType
+     * @param schema
+     * @returns
+     *
+     * @internal
+     */
     async loadStructType(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
@@ -242,9 +267,17 @@ export class ECClass extends SchemaItem {
         else
             correctType = structType;
         if (!correctType)
-            throw new ECObjectsError(ECObjectsStatus.InvalidType, `The provided Struct type, ${structType}, is not a valid StructClass.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidType, `The provided Struct type, ${structType}, is not a valid StructClass.`);
         return correctType;
     }
+    /**
+     *
+     * @param structType
+     * @param schema
+     * @returns
+     *
+     * @internal
+     */
     loadStructTypeSync(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
@@ -253,9 +286,17 @@ export class ECClass extends SchemaItem {
         else
             correctType = structType;
         if (!correctType)
-            throw new ECObjectsError(ECObjectsStatus.InvalidType, `The provided Struct type, ${structType}, is not a valid StructClass.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidType, `The provided Struct type, ${structType}, is not a valid StructClass.`);
         return correctType;
     }
+    /**
+     *
+     * @param primitiveType
+     * @param schema
+     * @returns
+     *
+     * @internal
+     */
     async loadPrimitiveType(primitiveType, schema) {
         if (primitiveType === undefined)
             return PrimitiveType.Integer;
@@ -265,14 +306,22 @@ export class ECClass extends SchemaItem {
                 resolvedType = await schema.lookupItem(primitiveType, Enumeration);
             }
             if (resolvedType === undefined)
-                throw new ECObjectsError(ECObjectsStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
+                throw new ECSchemaError(ECSchemaStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
             // If resolvedType is a SchemaItem, make sure it is an Enumeration- if not, throw an error
             if (typeof (resolvedType) !== "number" && resolvedType.schemaItemType !== SchemaItemType.Enumeration)
-                throw new ECObjectsError(ECObjectsStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
+                throw new ECSchemaError(ECSchemaStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
             return resolvedType;
         }
         return primitiveType;
     }
+    /**
+     *
+     * @param primitiveType
+     * @param schema
+     * @returns
+     *
+     * @internal
+     */
     loadPrimitiveTypeSync(primitiveType, schema) {
         if (primitiveType === undefined)
             return PrimitiveType.Integer;
@@ -282,7 +331,7 @@ export class ECClass extends SchemaItem {
                 resolvedType = schema.lookupItemSync(primitiveType, Enumeration);
             }
             if (resolvedType === undefined)
-                throw new ECObjectsError(ECObjectsStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
+                throw new ECSchemaError(ECSchemaStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
             return resolvedType;
         }
         return primitiveType;
@@ -343,7 +392,7 @@ export class ECClass extends SchemaItem {
                 if (SchemaReadHelper.isECSpecVersionNewer({ readVersion: classProps.originalECSpecMajorVersion, writeVersion: classProps.originalECSpecMinorVersion }))
                     this._modifier = ECClassModifier.None;
                 else
-                    throw new ECObjectsError(ECObjectsStatus.InvalidModifier, `The string '${classProps.modifier}' is not a valid ECClassModifier.`);
+                    throw new ECSchemaError(ECSchemaStatus.InvalidModifier, `The string '${classProps.modifier}' is not a valid ECClassModifier.`);
             }
             else {
                 this._modifier = modifier;
@@ -352,14 +401,14 @@ export class ECClass extends SchemaItem {
         if (undefined !== classProps.baseClass) {
             const ecClassSchemaItemKey = this.schema.getSchemaItemKey(classProps.baseClass);
             if (!ecClassSchemaItemKey)
-                throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
+                throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
             const baseClass = this.schema.lookupItemSync(ecClassSchemaItemKey);
             let lazyBase;
             if (!baseClass) {
                 lazyBase = new DelayedPromiseWithProps(ecClassSchemaItemKey, async () => {
                     const baseItem = await this.schema.lookupItem(ecClassSchemaItemKey);
                     if (undefined === baseItem || !ECClass.isECClass(baseItem))
-                        throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
+                        throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
                     return baseItem;
                 });
             }
@@ -377,6 +426,12 @@ export class ECClass extends SchemaItem {
     async fromJSON(classProps) {
         this.fromJSONSync(classProps);
     }
+    /**
+     *
+     * @param customAttribute
+     *
+     * @internal
+     */
     addCustomAttribute(customAttribute) {
         if (!this._customAttributes)
             this._customAttributes = new Map();
@@ -423,6 +478,15 @@ export class ECClass extends SchemaItem {
                 yield baseClass;
         }
     }
+    /**
+     *
+     * @param target
+     * @param existingValues
+     * @param propertiesToMerge
+     * @param overwriteExisting
+     *
+     * @internal
+     */
     static mergeProperties(target, existingValues, propertiesToMerge, overwriteExisting) {
         for (const property of propertiesToMerge) {
             const upperCaseName = property.name.toUpperCase();
@@ -438,6 +502,14 @@ export class ECClass extends SchemaItem {
             }
         }
     }
+    /**
+     *
+     * @param result
+     * @param existingValues
+     * @returns
+     *
+     * @internal
+     */
     async buildPropertyCache(result, existingValues) {
         if (!existingValues) {
             existingValues = new Map();
@@ -452,6 +524,14 @@ export class ECClass extends SchemaItem {
             return;
         ECClass.mergeProperties(result, existingValues, [...this._properties.values()], true);
     }
+    /**
+     *
+     * @param result
+     * @param existingValues
+     * @returns
+     *
+     * @internal
+     */
     buildPropertyCacheSync(result, existingValues) {
         if (!existingValues) {
             existingValues = new Map();
@@ -594,9 +674,9 @@ export class ECClass extends SchemaItem {
             object.schemaItemType === SchemaItemType.StructClass || object.schemaItemType === SchemaItemType.CustomAttributeClass;
     }
     /**
-     * @alpha
      * A setter method for the ECClass modifier, used specifically for schema editing.
      * @param modifier
+     * @internal
      */
     setModifier(modifier) {
         this._modifier = modifier;
@@ -633,17 +713,16 @@ export class ECClass extends SchemaItem {
 }
 /**
  * A Typescript class representation of an ECStructClass.
- * @beta
+ * @public @preview
  */
 export class StructClass extends ECClass {
     /**
      * Get the type of item represented by this instance
-     * @beta
      */
     schemaItemType = StructClass.schemaItemType;
     /**
      * Get the type of item represented by this class
-     * @beta
+     * @internal
      */
     static get schemaItemType() { return SchemaItemType.StructClass; }
     /**
@@ -660,10 +739,11 @@ export class StructClass extends ECClass {
      * Type assertion to check if the SchemaItem is of type StructClass.
      * @param item The SchemaItem to check.
      * @returns The item cast to StructClass if it is a StructClass, undefined otherwise.
+     * @internal
      */
     static assertIsStructClass(item) {
         if (!this.isStructClass(item))
-            throw new ECObjectsError(ECObjectsStatus.InvalidSchemaItemType, `Expected '${SchemaItemType.StructClass}' (StructClass)`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidSchemaItemType, `Expected '${SchemaItemType.StructClass}' (StructClass)`);
     }
 }
 /**