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

package/lib/cjs/Metadata/Class.js

@@ -15,6 +15,7 @@ const ECObjects_1 = require("../ECObjects");
 const Exception_1 = require("../Exception");
 const SchemaKey_1 = require("../SchemaKey");
 const CustomAttribute_1 = require("./CustomAttribute");
+const Enumeration_1 = require("./Enumeration");
 const Property_1 = require("./Property");
 const SchemaItem_1 = require("./SchemaItem");
 const Helper_1 = require("../Deserialization/Helper");
@@ -23,10 +24,14 @@ const Helper_1 = require("../Deserialization/Helper");
  * @beta
  */
 class ECClass extends SchemaItem_1.SchemaItem {
+    static get schemaItemType() { return ECObjects_1.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);
@@ -35,6 +40,32 @@ class ECClass extends SchemaItem_1.SchemaItem {
         else
             this._modifier = ECObjects_1.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.
@@ -44,6 +75,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
         if (!this._properties)
             this._properties = new Map();
         this._properties.set(prop.name.toUpperCase(), prop);
+        this.cleanCache();
         return prop;
     }
     /**
@@ -54,8 +86,10 @@ class ECClass extends SchemaItem_1.SchemaItem {
     async deleteProperty(name) {
         if (this._properties) {
             const property = await this.getProperty(name);
-            if (property)
+            if (property) {
                 this._properties.delete(name.toUpperCase());
+                this.cleanCache();
+            }
         }
     }
     /**
@@ -66,44 +100,49 @@ class ECClass extends SchemaItem_1.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);
@@ -115,7 +154,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;
     }
@@ -126,11 +165,11 @@ 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))
+        if (await this.getProperty(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.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")
@@ -138,7 +177,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
         return this.addProperty(new Property_1.EnumerationProperty(this, name, new DelayedPromise_1.DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitivePropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.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")
@@ -146,7 +185,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
         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))
+        if (await this.getProperty(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.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")
@@ -154,7 +193,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
         return this.addProperty(new Property_1.EnumerationArrayProperty(this, name, new DelayedPromise_1.DelayedPromiseWithProps(propType.key, async () => propType)));
     }
     createPrimitiveArrayPropertySync(name, primitiveType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.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")
@@ -167,7 +206,7 @@ class ECClass extends SchemaItem_1.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 Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.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)));
     }
@@ -177,7 +216,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
      * @param structType The struct type of property to create.
      */
     createStructPropertySync(name, structType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.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)));
     }
@@ -187,7 +226,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
      * @param type
      */
     async createStructArrayProperty(name, structType) {
-        if (await this.getProperty(name))
+        if (await this.getProperty(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.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)));
     }
@@ -197,14 +236,14 @@ class ECClass extends SchemaItem_1.SchemaItem {
      * @param type
      */
     createStructArrayPropertySync(name, structType) {
-        if (this.getPropertySync(name))
+        if (this.getPropertySync(name, true))
             throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.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)));
     }
     async loadStructType(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
-            correctType = await schema.lookupItem(structType);
+            correctType = await schema.lookupItem(structType, StructClass);
         }
         else
             correctType = structType;
@@ -215,7 +254,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
     loadStructTypeSync(structType, schema) {
         let correctType;
         if (typeof (structType) === "string") {
-            correctType = schema.lookupItemSync(structType);
+            correctType = schema.lookupItemSync(structType, StructClass);
         }
         else
             correctType = structType;
@@ -229,7 +268,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
         if (typeof (primitiveType) === "string") {
             let resolvedType = (0, ECObjects_1.parsePrimitiveType)(primitiveType);
             if (!resolvedType) {
-                resolvedType = await schema.lookupItem(primitiveType);
+                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.`);
@@ -246,7 +285,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
         if (typeof (primitiveType) === "string") {
             let resolvedType = (0, ECObjects_1.parsePrimitiveType)(primitiveType);
             if (!resolvedType) {
-                resolvedType = schema.lookupItemSync(primitiveType);
+                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.`);
@@ -268,7 +307,7 @@ class ECClass extends SchemaItem_1.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 = (0, CustomAttribute_1.serializeCustomAttributes)(this.customAttributes);
         if (customAttributes !== undefined)
             schemaJson.customAttributes = customAttributes;
@@ -286,8 +325,8 @@ class ECClass extends SchemaItem_1.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);
             }
@@ -320,12 +359,25 @@ class ECClass extends SchemaItem_1.SchemaItem {
             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}.`);
-            this._baseClass = new DelayedPromise_1.DelayedPromiseWithProps(ecClassSchemaItemKey, async () => {
-                const baseClass = await this.schema.lookupItem(ecClassSchemaItemKey);
-                if (undefined === baseClass)
-                    throw new Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidECJson, `Unable to locate the baseClass ${classProps.baseClass}.`);
-                return 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}.`);
+                    return baseItem;
+                });
+            }
+            else {
+                lazyBase = new DelayedPromise_1.DelayedPromiseWithProps(ecClassSchemaItemKey, async () => {
+                    return baseClass;
+                });
+            }
+            this._baseClass = lazyBase;
+            if (!baseClass)
+                return;
+            this.addDerivedClass(baseClass, this);
         }
     }
     async fromJSON(classProps) {
@@ -344,8 +396,8 @@ class ECClass extends SchemaItem_1.SchemaItem {
         const baseClasses = [this];
         const addBaseClasses = async (ecClass) => {
             if (ECObjects_1.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)
@@ -361,7 +413,7 @@ class ECClass extends SchemaItem_1.SchemaItem {
     *getAllBaseClassesSync() {
         const baseClasses = [this];
         const addBaseClasses = (ecClass) => {
-            if (ECObjects_1.SchemaItemType.EntityClass === ecClass.schemaItemType) {
+            if (ecClass.schemaItemType === ECObjects_1.SchemaItemType.EntityClass) { // cannot use EntityClass typeguard because of circular reference
                 for (const m of Array.from(ecClass.getMixinsSync()).reverse()) {
                     baseClasses.push(m);
                 }
@@ -392,52 +444,71 @@ class ECClass extends SchemaItem_1.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
@@ -536,6 +607,35 @@ class ECClass extends SchemaItem_1.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 DelayedPromise_1.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);
+    }
 }
 exports.ECClass = ECClass;
 /**
@@ -543,9 +643,34 @@ exports.ECClass = ECClass;
  * @beta
  */
 class StructClass extends ECClass {
-    constructor(schema, name, modifier) {
-        super(schema, name, modifier);
-        this.schemaItemType = ECObjects_1.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 ECObjects_1.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 === ECObjects_1.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 Exception_1.ECObjectsError(Exception_1.ECObjectsStatus.InvalidSchemaItemType, `Expected '${ECObjects_1.SchemaItemType.StructClass}' (StructClass)`);
     }
 }
 exports.StructClass = StructClass;