@itwin/ecschema-metadata 5.0.0-dev.1 → 5.0.0-dev.100

package/lib/esm/Metadata/Class.js

@@ -8,10 +8,11 @@
 import { assert } from "@itwin/core-bentley";
 import { DelayedPromiseWithProps } from "../DelayedPromise";
 import { XmlSerializationUtils } from "../Deserialization/XmlSerializationUtils";
-import { classModifierToString, ECClassModifier, parseClassModifier, parsePrimitiveType, PrimitiveType, SchemaItemType } from "../ECObjects";
+import { AbstractSchemaItemType, classModifierToString, ECClassModifier, parseClassModifier, parsePrimitiveType, PrimitiveType, SchemaItemType } from "../ECObjects";
 import { ECObjectsError, ECObjectsStatus } from "../Exception";
 import { SchemaItemKey, SchemaKey } from "../SchemaKey";
 import { serializeCustomAttributes } from "./CustomAttribute";
+import { Enumeration } from "./Enumeration";
 import { EnumerationArrayProperty, EnumerationProperty, PrimitiveArrayProperty, PrimitiveProperty, StructArrayProperty, StructProperty, } from "./Property";
 import { SchemaItem } from "./SchemaItem";
 import { SchemaReadHelper } from "../Deserialization/Helper";
@@ -20,10 +21,14 @@ import { SchemaReadHelper } from "../Deserialization/Helper";
  * @beta
  */
 export class ECClass extends SchemaItem {
+    static get schemaItemType() { return AbstractSchemaItemType.Class; } // need this so getItem("name", ECClass) in schema works
+    _modifier;
+    _baseClass;
+    _derivedClasses;
+    _properties;
+    _customAttributes;
+    _mergedPropertyCache;
     get modifier() { return this._modifier; }
-    get baseClass() { return this._baseClass; }
-    set baseClass(baseClass) { this._baseClass = baseClass; }
-    get properties() { return this._properties?.values(); }
     get customAttributes() { return this._customAttributes; }
     constructor(schema, name, modifier) {
         super(schema, name);
@@ -32,6 +37,32 @@ export class ECClass extends SchemaItem {
         else
             this._modifier = ECClassModifier.None;
     }
+    /**
+     * Gets the base class if it exists, otherwise returns undefined.
+     */
+    get baseClass() {
+        return this._baseClass;
+    }
+    /**
+     * Sets the base class of the ECClass. Pass undefined to 'remove' the base class.
+     */
+    async setBaseClass(baseClass) {
+        const oldBaseClass = this._baseClass;
+        this._baseClass = baseClass;
+        if (baseClass)
+            this.addDerivedClass(await baseClass, this);
+        else if (oldBaseClass)
+            this.removeDerivedClass(await oldBaseClass, this);
+    }
+    /**
+     * Gets the derived classes belonging to this class.
+     * @returns An array of ECClasses or undefined if no derived classes exist.
+     */
+    async getDerivedClasses() {
+        if (!this._derivedClasses || this._derivedClasses.size === 0)
+            return undefined;
+        return Array.from(await Promise.all(this._derivedClasses.values()));
+    }
     /**
      * Convenience method for adding an already loaded ECProperty used by create*Property methods.
      * @param prop The property to add.
@@ -41,6 +72,7 @@ export class ECClass extends SchemaItem {
         if (!this._properties)
             this._properties = new Map();
         this._properties.set(prop.name.toUpperCase(), prop);
+        this.cleanCache();
         return prop;
     }
     /**
@@ -51,8 +83,10 @@ export class ECClass extends SchemaItem {
     async deleteProperty(name) {
         if (this._properties) {
             const property = await this.getProperty(name);
-            if (property)
+            if (property) {
                 this._properties.delete(name.toUpperCase());
+                this.cleanCache();
+            }
         }
     }
     /**
@@ -63,44 +97,49 @@ export class ECClass extends SchemaItem {
     deletePropertySync(name) {
         if (this._properties) {
             const property = this.getPropertySync(name);
-            if (property)
+            if (property) {
                 this._properties.delete(name.toUpperCase());
+                this.cleanCache();
+            }
         }
     }
     getBaseClassSync() {
         if (!this.baseClass) {
             return undefined;
         }
-        return this.schema.lookupItemSync(this.baseClass);
+        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);
@@ -112,7 +151,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;
     }
@@ -123,11 +162,11 @@ 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))
+        if (await this.getProperty(name, true))
             throw new ECObjectsError(ECObjectsStatus.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")
@@ -135,7 +174,7 @@ export class ECClass extends SchemaItem {
         return this.addProperty(new EnumerationProperty(this, name, new DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitivePropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new ECObjectsError(ECObjectsStatus.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")
@@ -143,7 +182,7 @@ export class ECClass extends SchemaItem {
         return this.addProperty(new EnumerationProperty(this, name, new DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     async createPrimitiveArrayProperty(name, primitiveType) {
-        if (await this.getProperty(name))
+        if (await this.getProperty(name, true))
             throw new ECObjectsError(ECObjectsStatus.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")
@@ -151,7 +190,7 @@ export class ECClass extends SchemaItem {
         return this.addProperty(new EnumerationArrayProperty(this, name, new DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitiveArrayPropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new ECObjectsError(ECObjectsStatus.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")
@@ -164,7 +203,7 @@ export class ECClass extends SchemaItem {
      * @param structType The struct type of property to create.
      */
     async createStructProperty(name, structType) {
-        if (await this.getProperty(name))
+        if (await this.getProperty(name, true))
             throw new ECObjectsError(ECObjectsStatus.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)));
     }
@@ -174,7 +213,7 @@ export class ECClass extends SchemaItem {
      * @param structType The struct type of property to create.
      */
     createStructPropertySync(name, structType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new ECObjectsError(ECObjectsStatus.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)));
     }
@@ -184,7 +223,7 @@ export class ECClass extends SchemaItem {
      * @param type
      */
     async createStructArrayProperty(name, structType) {
-        if (await this.getProperty(name))
+        if (await this.getProperty(name, true))
             throw new ECObjectsError(ECObjectsStatus.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)));
     }
@@ -194,14 +233,14 @@ export class ECClass extends SchemaItem {
      * @param type
      */
     createStructArrayPropertySync(name, structType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new ECObjectsError(ECObjectsStatus.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)));
     }
     async loadStructType(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
-            correctType = await schema.lookupItem(structType);
+            correctType = await schema.lookupItem(structType, StructClass);
         }
         else
             correctType = structType;
@@ -212,7 +251,7 @@ export class ECClass extends SchemaItem {
     loadStructTypeSync(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
-            correctType = schema.lookupItemSync(structType);
+            correctType = schema.lookupItemSync(structType, StructClass);
         }
         else
             correctType = structType;
@@ -226,7 +265,7 @@ export class ECClass extends SchemaItem {
         if (typeof (primitiveType) === "string") {
             let resolvedType = parsePrimitiveType(primitiveType);
             if (!resolvedType) {
-                resolvedType = await schema.lookupItem(primitiveType);
+                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.`);
@@ -243,7 +282,7 @@ export class ECClass extends SchemaItem {
         if (typeof (primitiveType) === "string") {
             let resolvedType = parsePrimitiveType(primitiveType);
             if (!resolvedType) {
-                resolvedType = schema.lookupItemSync(primitiveType);
+                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.`);
@@ -265,7 +304,7 @@ export class ECClass extends SchemaItem {
         if (this.baseClass !== undefined)
             schemaJson.baseClass = this.baseClass.fullName;
         if (this._properties !== undefined && this._properties.size > 0)
-            schemaJson.properties = [...this.properties].map((prop) => prop.toJSON());
+            schemaJson.properties = [...this._properties.values()].map((prop) => prop.toJSON());
         const customAttributes = serializeCustomAttributes(this.customAttributes);
         if (customAttributes !== undefined)
             schemaJson.customAttributes = customAttributes;
@@ -283,8 +322,8 @@ export class ECClass extends SchemaItem {
             baseClassElement.textContent = baseClassName;
             itemElement.appendChild(baseClassElement);
         }
-        if (undefined !== this.properties) {
-            for (const prop of this.properties) {
+        if (undefined !== this._properties) {
+            for (const prop of this._properties.values()) {
                 const propXml = await prop.toXml(schemaXml);
                 itemElement.appendChild(propXml);
             }
@@ -317,12 +356,25 @@ export class ECClass extends SchemaItem {
             const ecClassSchemaItemKey = this.schema.getSchemaItemKey(classProps.baseClass);
             if (!ecClassSchemaItemKey)
                 throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
-            this._baseClass = new DelayedPromiseWithProps(ecClassSchemaItemKey, async () => {
-                const baseClass = await this.schema.lookupItem(ecClassSchemaItemKey);
-                if (undefined === baseClass)
-                    throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
-                return 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}.`);
+                    return baseItem;
+                });
+            }
+            else {
+                lazyBase = new DelayedPromiseWithProps(ecClassSchemaItemKey, async () => {
+                    return baseClass;
+                });
+            }
+            this._baseClass = lazyBase;
+            if (!baseClass)
+                return;
+            this.addDerivedClass(baseClass, this);
         }
     }
     async fromJSON(classProps) {
@@ -341,8 +393,8 @@ export class ECClass extends SchemaItem {
         const baseClasses = [this];
         const addBaseClasses = async (ecClass) => {
             if (SchemaItemType.EntityClass === ecClass.schemaItemType) {
-                for (let i = (ecClass).mixins.length - 1; i >= 0; i--) {
-                    baseClasses.push(await (ecClass).mixins[i]);
+                for (let i = ecClass.mixins.length - 1; i >= 0; i--) {
+                    baseClasses.push(await ecClass.mixins[i]);
                 }
             }
             if (ecClass.baseClass)
@@ -358,7 +410,7 @@ export class ECClass extends SchemaItem {
     *getAllBaseClassesSync() {
         const baseClasses = [this];
         const addBaseClasses = (ecClass) => {
-            if (SchemaItemType.EntityClass === ecClass.schemaItemType) {
+            if (ecClass.schemaItemType === SchemaItemType.EntityClass) { // cannot use EntityClass typeguard because of circular reference
                 for (const m of Array.from(ecClass.getMixinsSync()).reverse()) {
                     baseClasses.push(m);
                 }
@@ -389,52 +441,71 @@ export class ECClass extends SchemaItem {
             }
         }
     }
-    async buildPropertyCache(result, existingValues, resetBaseCaches = false) {
+    async buildPropertyCache(result, existingValues) {
         if (!existingValues) {
             existingValues = new Map();
         }
         if (this.baseClass) {
-            ECClass.mergeProperties(result, existingValues, await (await this.baseClass).getProperties(resetBaseCaches), false);
+            const baseClass = await this.baseClass;
+            if (baseClass) {
+                ECClass.mergeProperties(result, existingValues, await baseClass.getProperties(), false);
+            }
         }
-        if (!this.properties)
+        if (!this._properties)
             return;
-        ECClass.mergeProperties(result, existingValues, [...this.properties], true);
+        ECClass.mergeProperties(result, existingValues, [...this._properties.values()], true);
     }
-    buildPropertyCacheSync(result, existingValues, resetBaseCaches = false) {
+    buildPropertyCacheSync(result, existingValues) {
         if (!existingValues) {
             existingValues = new Map();
         }
         const baseClass = this.getBaseClassSync();
         if (baseClass) {
-            ECClass.mergeProperties(result, existingValues, baseClass.getPropertiesSync(resetBaseCaches), false);
+            ECClass.mergeProperties(result, existingValues, baseClass.getPropertiesSync(), false);
         }
-        if (!this.properties)
+        if (!this._properties)
             return;
-        ECClass.mergeProperties(result, existingValues, [...this.properties], true);
+        ECClass.mergeProperties(result, existingValues, [...this._properties.values()], true);
     }
     /**
-     * Iterates all properties, including the ones merged from base classes and mixins. To obtain only local properties, use the 'properties' field.
+     * Clears all caches on this object. This is called implicitly for this class,
+     * but needs to be called if derived classes have changed.
+     * @internal
+     */
+    cleanCache() {
+        this._mergedPropertyCache = undefined;
+    }
+    /**
+     * Returns the properties on this class and its base classes.
      * Since this is an expensive operation, results will be cached after first call.
-     * @param resetCache if true, any previously cached results will be dropped and cache will be rebuilt
+     * @param excludeInherited If true, only properties defined directly on this class will be returned. Defaults to false.
+     * @returns An array of properties, empty array if none exist.
      */
-    getPropertiesSync(resetCache = false) {
-        if (!this._mergedPropertyCache || resetCache) {
+    getPropertiesSync(excludeInherited) {
+        if (excludeInherited) {
+            return this._properties && this._properties.size > 0 ? this._properties.values() : [];
+        }
+        if (!this._mergedPropertyCache) {
             this._mergedPropertyCache = [];
-            this.buildPropertyCacheSync(this._mergedPropertyCache, undefined, resetCache);
+            this.buildPropertyCacheSync(this._mergedPropertyCache, undefined);
         }
         return this._mergedPropertyCache;
     }
     /**
-     * Iterates all properties, including the ones merged from base classes and mixins. To obtain only local properties, use the 'properties' field.
+     * Quick way to check whether this class has any local properties without having to use the iterable
+     */
+    get hasLocalProperties() {
+        return this._properties !== undefined && this._properties.size > 0;
+    }
+    /**
+     * Returns the properties on this class and its base classes.
      * Since this is an expensive operation, results will be cached after first call.
-     * @param resetCache if true, any previously cached results will be dropped and cache will be rebuilt
+     * @param excludeInherited If true, only properties defined directly on this class will be returned.
+     * @returns An array of properties, empty array if none exist.
      */
-    async getProperties(resetCache = false) {
-        if (!this._mergedPropertyCache || resetCache) {
-            this._mergedPropertyCache = [];
-            await this.buildPropertyCache(this._mergedPropertyCache, undefined, resetCache);
-        }
-        return this._mergedPropertyCache;
+    async getProperties(excludeInherited) {
+        // At the moment we do not lazy load properties, so this is the same as getPropertiesSync
+        return this.getPropertiesSync(excludeInherited);
     }
     /**
      * Retrieve all custom attributes in the current class and its bases
@@ -533,15 +604,69 @@ export class ECClass extends SchemaItem {
     setModifier(modifier) {
         this._modifier = modifier;
     }
+    /**
+     * Adds an ECClass to the derived class collection. This method is only intended to update the local
+     * cache of derived classes. For adding a class to the hierarchy, use the baseClass setter method.
+     * @param prop The property to add.
+     * @return The property that was added.
+     */
+    addDerivedClass(baseClass, derivedClass) {
+        if (!baseClass._derivedClasses)
+            baseClass._derivedClasses = new Map();
+        if (baseClass._derivedClasses.has(derivedClass.fullName))
+            return;
+        if (derivedClass.isSync(baseClass)) {
+            const promise = new DelayedPromiseWithProps(derivedClass.key, async () => derivedClass);
+            baseClass._derivedClasses.set(derivedClass.fullName, promise);
+        }
+    }
+    /**
+     * Removes an ECClass from the derived class collection. This method is only intended to update the local
+     * cache of derived classes. For updating the class hierarchy, use the baseClass setter method.
+     * @param prop The property to add.
+     * @return The property that was added.
+     */
+    removeDerivedClass(baseClass, derivedClass) {
+        if (!baseClass._derivedClasses)
+            return;
+        if (!baseClass._derivedClasses.has(derivedClass.fullName))
+            return;
+        baseClass._derivedClasses.delete(derivedClass.fullName);
+    }
 }
 /**
  * A Typescript class representation of an ECStructClass.
  * @beta
  */
 export class StructClass extends ECClass {
-    constructor(schema, name, modifier) {
-        super(schema, name, modifier);
-        this.schemaItemType = SchemaItemType.StructClass;
+    /**
+     * Get the type of item represented by this instance
+     * @beta
+     */
+    schemaItemType = StructClass.schemaItemType;
+    /**
+     * Get the type of item represented by this class
+     * @beta
+     */
+    static get schemaItemType() { return SchemaItemType.StructClass; }
+    /**
+     * Type guard to check if the SchemaItem is of type StructClass.
+     * @param item The SchemaItem to check.
+     * @returns True if the item is a StructClass, false otherwise.
+     */
+    static isStructClass(item) {
+        if (item && item.schemaItemType === SchemaItemType.StructClass)
+            return true;
+        return false;
+    }
+    /**
+     * 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.
+     */
+    static assertIsStructClass(item) {
+        if (!this.isStructClass(item))
+            throw new ECObjectsError(ECObjectsStatus.InvalidSchemaItemType, `Expected '${SchemaItemType.StructClass}' (StructClass)`);
     }
 }
 /**