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

package/lib/cjs/Metadata/Class.js

@@ -21,9 +21,10 @@ const SchemaItem_1 = require("./SchemaItem");
 const Helper_1 = require("../Deserialization/Helper");
 /**
  * A common abstract class for all of the ECClass types.
- * @beta
+ * @public @preview
  */
 class ECClass extends SchemaItem_1.SchemaItem {
+    /** @internal */
     static get schemaItemType() { return ECObjects_1.AbstractSchemaItemType.Class; } // need this so getItem("name", ECClass) in schema works
     _modifier;
     _baseClass;
@@ -33,6 +34,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
     _mergedPropertyCache;
     get modifier() { return this._modifier; }
     get customAttributes() { return this._customAttributes; }
+    /** @internal */
     constructor(schema, name, modifier) {
         super(schema, name);
         if (modifier)
@@ -46,8 +48,16 @@ class ECClass extends SchemaItem_1.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;
@@ -70,6 +80,8 @@ class ECClass extends SchemaItem_1.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)
@@ -81,7 +93,7 @@ class ECClass extends SchemaItem_1.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) {
@@ -95,7 +107,7 @@ class ECClass extends SchemaItem_1.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) {
@@ -106,40 +118,37 @@ class ECClass extends SchemaItem_1.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);
@@ -151,7 +160,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
     async getInheritedProperty(name) {
         if (this.baseClass) {
             const baseClassObj = await this.baseClass;
-            return baseClassObj.getProperty(name, true);
+            return baseClassObj.getProperty(name);
         }
         return undefined;
     }
@@ -162,36 +171,36 @@ class ECClass extends SchemaItem_1.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 Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.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 Property_1.PrimitiveProperty(this, name, propType));
         return this.addProperty(new Property_1.EnumerationProperty(this, name, new DelayedPromise_1.DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitivePropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.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 Property_1.PrimitiveProperty(this, name, propType));
         return this.addProperty(new Property_1.EnumerationProperty(this, name, new DelayedPromise_1.DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     async createPrimitiveArrayProperty(name, primitiveType) {
-        if (await this.getProperty(name))
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.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 Property_1.PrimitiveArrayProperty(this, name, propType));
         return this.addProperty(new Property_1.EnumerationArrayProperty(this, name, new DelayedPromise_1.DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitiveArrayPropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.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 Property_1.PrimitiveArrayProperty(this, name, propType));
@@ -201,42 +210,58 @@ class ECClass extends SchemaItem_1.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 Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new Property_1.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 Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new Property_1.StructProperty(this, name, this.loadStructTypeSync(structType, this.schema)));
     }
     /**
      *
      * @param name
      * @param type
+     *
+     * @internal
      */
     async createStructArrayProperty(name, structType) {
-        if (await this.getProperty(name))
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (await this.getProperty(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new Property_1.StructArrayProperty(this, name, await this.loadStructType(structType, this.schema)));
     }
     /**
      *
      * @param name
      * @param type
+     *
+     * @internal
      */
     createStructArrayPropertySync(name, structType) {
-        if (this.getPropertySync(name))
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
+        if (this.getPropertySync(name, true))
+            throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.DuplicateProperty, `An ECProperty with the name ${name} already exists in the class ${this.name}.`);
         return this.addProperty(new Property_1.StructArrayProperty(this, name, this.loadStructTypeSync(structType, this.schema)));
     }
+    /**
+     *
+     * @param structType
+     * @param schema
+     * @returns
+     *
+     * @internal
+     */
     async loadStructType(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
@@ -245,9 +270,17 @@ class ECClass extends SchemaItem_1.SchemaItem {
         else
             correctType = structType;
         if (!correctType)
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidType, `The provided Struct type, ${structType}, is not a valid StructClass.`);
+            throw new Exception_1.ECSchemaError(Exception_1.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") {
@@ -256,9 +289,17 @@ class ECClass extends SchemaItem_1.SchemaItem {
         else
             correctType = structType;
         if (!correctType)
-            throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidType, `The provided Struct type, ${structType}, is not a valid StructClass.`);
+            throw new Exception_1.ECSchemaError(Exception_1.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 ECObjects_1.PrimitiveType.Integer;
@@ -268,14 +309,22 @@ class ECClass extends SchemaItem_1.SchemaItem {
                 resolvedType = await schema.lookupItem(primitiveType, Enumeration_1.Enumeration);
             }
             if (resolvedType === undefined)
-                throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
+                throw new Exception_1.ECSchemaError(Exception_1.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 !== ECObjects_1.SchemaItemType.Enumeration)
-                throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
+                throw new Exception_1.ECSchemaError(Exception_1.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 ECObjects_1.PrimitiveType.Integer;
@@ -285,7 +334,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
                 resolvedType = schema.lookupItemSync(primitiveType, Enumeration_1.Enumeration);
             }
             if (resolvedType === undefined)
-                throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
+                throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.InvalidType, `The provided primitive type, ${primitiveType}, is not a valid PrimitiveType or Enumeration.`);
             return resolvedType;
         }
         return primitiveType;
@@ -346,7 +395,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
                 if (Helper_1.SchemaReadHelper.isECSpecVersionNewer({ readVersion: classProps.originalECSpecMajorVersion, writeVersion: classProps.originalECSpecMinorVersion }))
                     this._modifier = ECObjects_1.ECClassModifier.None;
                 else
-                    throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidModifier, `The string '${classProps.modifier}' is not a valid ECClassModifier.`);
+                    throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.InvalidModifier, `The string '${classProps.modifier}' is not a valid ECClassModifier.`);
             }
             else {
                 this._modifier = modifier;
@@ -355,14 +404,14 @@ class ECClass extends SchemaItem_1.SchemaItem {
         if (undefined !== classProps.baseClass) {
             const ecClassSchemaItemKey = this.schema.getSchemaItemKey(classProps.baseClass);
             if (!ecClassSchemaItemKey)
-                throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
+                throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
             const baseClass = this.schema.lookupItemSync(ecClassSchemaItemKey);
             let lazyBase;
             if (!baseClass) {
                 lazyBase = new DelayedPromise_1.DelayedPromiseWithProps(ecClassSchemaItemKey, async () => {
                     const baseItem = await this.schema.lookupItem(ecClassSchemaItemKey);
                     if (undefined === baseItem || !ECClass.isECClass(baseItem))
-                        throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
+                        throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
                     return baseItem;
                 });
             }
@@ -380,6 +429,12 @@ class ECClass extends SchemaItem_1.SchemaItem {
     async fromJSON(classProps) {
         this.fromJSONSync(classProps);
     }
+    /**
+     *
+     * @param customAttribute
+     *
+     * @internal
+     */
     addCustomAttribute(customAttribute) {
         if (!this._customAttributes)
             this._customAttributes = new Map();
@@ -426,6 +481,15 @@ class ECClass extends SchemaItem_1.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();
@@ -441,6 +505,14 @@ class ECClass extends SchemaItem_1.SchemaItem {
             }
         }
     }
+    /**
+     *
+     * @param result
+     * @param existingValues
+     * @returns
+     *
+     * @internal
+     */
     async buildPropertyCache(result, existingValues) {
         if (!existingValues) {
             existingValues = new Map();
@@ -455,6 +527,14 @@ class ECClass extends SchemaItem_1.SchemaItem {
             return;
         ECClass.mergeProperties(result, existingValues, [...this._properties.values()], true);
     }
+    /**
+     *
+     * @param result
+     * @param existingValues
+     * @returns
+     *
+     * @internal
+     */
     buildPropertyCacheSync(result, existingValues) {
         if (!existingValues) {
             existingValues = new Map();
@@ -597,9 +677,9 @@ class ECClass extends SchemaItem_1.SchemaItem {
             object.schemaItemType === ECObjects_1.SchemaItemType.StructClass || object.schemaItemType === ECObjects_1.SchemaItemType.CustomAttributeClass;
     }
     /**
-     * @alpha
      * A setter method for the ECClass modifier, used specifically for schema editing.
      * @param modifier
+     * @internal
      */
     setModifier(modifier) {
         this._modifier = modifier;
@@ -637,17 +717,16 @@ class ECClass extends SchemaItem_1.SchemaItem {
 exports.ECClass = ECClass;
 /**
  * A Typescript class representation of an ECStructClass.
- * @beta
+ * @public @preview
  */
 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 ECObjects_1.SchemaItemType.StructClass; }
     /**
@@ -664,10 +743,11 @@ 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 Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidSchemaItemType, `Expected '${ECObjects_1.SchemaItemType.StructClass}' (StructClass)`);
+            throw new Exception_1.ECSchemaError(Exception_1.ECSchemaStatus.InvalidSchemaItemType, `Expected '${ECObjects_1.SchemaItemType.StructClass}' (StructClass)`);
     }
 }
 exports.StructClass = StructClass;