@itwin/ecschema-metadata 5.1.0-dev.9 → 5.2.0-dev.2

package/lib/esm/Deserialization/Helper.js

@@ -36,8 +36,11 @@ export class SchemaReadHelper {
      * calling getCachedSchema on the context.
      * @param schema The Schema to populate
      * @param rawSchema The serialized data to use to populate the Schema.
+     * @param addSchemaToCache Optional parameter that indicates if the schema should be added to the SchemaContext.
+     * The default is true. If false, the schema loading will not begin asynchronously in the background because the
+     * schema promise must be added to the context. In this case, only the SchemaInfo is returned.
      */
-    async readSchemaInfo(schema, rawSchema) {
+    async readSchemaInfo(schema, rawSchema, addSchemaToCache = true) {
         // Ensure context matches schema context
         if (schema.context) {
             if (this._context !== schema.context)
@@ -50,15 +53,15 @@ export class SchemaReadHelper {
         // Loads all of the properties on the Schema object
         await schema.fromJSON(this._parser.parseSchema());
         this._schema = schema;
-        const schemaInfoReferences = [];
-        const schemaInfo = { schemaKey: schema.schemaKey, alias: schema.alias, references: schemaInfoReferences };
+        const schemaReferences = [];
+        const schemaInfo = { schemaKey: schema.schemaKey, alias: schema.alias, references: schemaReferences };
         for (const reference of this._parser.getReferences()) {
             const refKey = new SchemaKey(reference.name, ECVersion.fromString(reference.version));
-            schemaInfoReferences.push({ schemaKey: refKey });
+            schemaReferences.push({ schemaKey: refKey });
         }
         this._schemaInfo = schemaInfo;
         // Need to add this schema to the context to be able to locate schemaItems within the context.
-        if (!this._context.schemaExists(schema.schemaKey)) {
+        if (addSchemaToCache && !this._context.schemaExists(schema.schemaKey)) {
             await this._context.addSchemaPromise(schemaInfo, schema, this.loadSchema(schemaInfo, schema));
         }
         return schemaInfo;
@@ -67,33 +70,53 @@ export class SchemaReadHelper {
      * Populates the given Schema from a serialized representation.
      * @param schema The Schema to populate
      * @param rawSchema The serialized data to use to populate the Schema.
+     * @param addSchemaToCache Optional parameter that indicates if the schema should be added to the SchemaContext.
+     * The default is true. If false, the schema will be loaded directly by this method and not from the context's schema cache.
      */
-    async readSchema(schema, rawSchema) {
+    async readSchema(schema, rawSchema, addSchemaToCache = true) {
         if (!this._schemaInfo) {
-            await this.readSchemaInfo(schema, rawSchema);
+            await this.readSchemaInfo(schema, rawSchema, addSchemaToCache);
+        }
+        // If not adding schema to cache (occurs in readSchemaInfo), we must load the schema here
+        if (!addSchemaToCache) {
+            const loadedSchema = await this.loadSchema(this._schemaInfo, schema);
+            if (undefined === loadedSchema)
+                throw new ECSchemaError(ECSchemaStatus.UnableToLoadSchema, `Could not load schema ${schema.schemaKey.toString()}`);
+            return loadedSchema;
         }
         const cachedSchema = await this._context.getCachedSchema(this._schemaInfo.schemaKey, SchemaMatchType.Latest);
         if (undefined === cachedSchema)
             throw new ECSchemaError(ECSchemaStatus.UnableToLoadSchema, `Could not load schema ${schema.schemaKey.toString()}`);
         return cachedSchema;
     }
+    /**
+     * Called when a SchemaItem has been successfully loaded by the Helper. The default implementation simply
+     * checks if the schema item is undefined. An implementation of the helper may choose to partially load
+     * a schema item in which case this method would indicate if the item has been fully loaded.
+     * @param schemaItem The SchemaItem to check.
+     * @returns True if the SchemaItem has been fully loaded, false otherwise.
+     */
+    isSchemaItemLoaded(schemaItem) {
+        return schemaItem !== undefined;
+    }
     /* Finish loading the rest of the schema */
     async loadSchema(schemaInfo, schema) {
         // Verify that there are no schema reference cycles, this will start schema loading by loading their headers
         (await SchemaGraph.generateGraph(schemaInfo, this._context)).throwIfCycles();
         for (const reference of schemaInfo.references) {
-            await this.loadSchemaReference(schemaInfo, reference.schemaKey);
+            await this.loadSchemaReference(schema, reference.schemaKey);
         }
         if (this._visitorHelper)
             await this._visitorHelper.visitSchema(schema, false);
         // Load all schema items
         for (const [itemName, itemType, rawItem] of this._parser.getItems()) {
-            // Make sure the item has not already been read. No need to check the SchemaContext because all SchemaItems are added to a Schema,
+            // Make sure the item has not already been loaded. No need to check the SchemaContext because all SchemaItems are added to a Schema,
             // which would be found when adding to the context.
-            if (await schema.getItem(itemName) !== undefined)
+            const schemaItem = await schema.getItem(itemName);
+            if (this.isSchemaItemLoaded(schemaItem))
                 continue;
             const loadedItem = await this.loadSchemaItem(schema, itemName, itemType, rawItem);
-            if (loadedItem && this._visitorHelper) {
+            if (this.isSchemaItemLoaded(loadedItem) && this._visitorHelper) {
                 await this._visitorHelper.visitSchemaPart(loadedItem);
             }
         }
@@ -124,12 +147,8 @@ export class SchemaReadHelper {
             this._visitorHelper.visitSchemaSync(schema, false);
         // Load all schema items
         for (const [itemName, itemType, rawItem] of this._parser.getItems()) {
-            // Make sure the item has not already been read. No need to check the SchemaContext because all SchemaItems are added to a Schema,
-            // which would be found when adding to the context.
-            if (schema.getItemSync(itemName) !== undefined)
-                continue;
             const loadedItem = this.loadSchemaItemSync(schema, itemName, itemType, rawItem);
-            if (loadedItem && this._visitorHelper) {
+            if (this.isSchemaItemLoaded(loadedItem) && this._visitorHelper) {
                 this._visitorHelper.visitSchemaPartSync(loadedItem);
             }
         }
@@ -142,12 +161,14 @@ export class SchemaReadHelper {
      * Ensures that the schema references can be located and adds them to the schema.
      * @param ref The object to read the SchemaReference's props from.
      */
-    async loadSchemaReference(schemaInfo, refKey) {
+    async loadSchemaReference(schema, refKey) {
         const refSchema = await this._context.getSchema(refKey, SchemaMatchType.LatestWriteCompatible);
         if (undefined === refSchema)
-            throw new ECSchemaError(ECSchemaStatus.UnableToLocateSchema, `Could not locate the referenced schema, ${refKey.name}.${refKey.version.toString()}, of ${schemaInfo.schemaKey.name}`);
-        await this._schema.addReference(refSchema);
-        const results = this.validateSchemaReferences(this._schema);
+            throw new ECSchemaError(ECSchemaStatus.UnableToLocateSchema, `Could not locate the referenced schema, ${refKey.name}.${refKey.version.toString()}, of ${schema.schemaKey.name}`);
+        if (schema.references.find((ref) => ref.schemaKey.matches(refSchema.schemaKey)))
+            return refSchema;
+        await schema.addReference(refSchema);
+        const results = this.validateSchemaReferences(schema);
         let errorMessage = "";
         for (const result of results) {
             errorMessage += `${result}\r\n`;
@@ -155,6 +176,7 @@ export class SchemaReadHelper {
         if (errorMessage) {
             throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `${errorMessage}`);
         }
+        return refSchema;
     }
     /**
      * Ensures that the schema references can be located and adds them to the schema.
@@ -204,73 +226,97 @@ export class SchemaReadHelper {
      * @param schemaItemObject The Object to populate the SchemaItem with.
      */
     async loadSchemaItem(schema, name, itemType, schemaItemObject) {
-        let schemaItem;
+        let schemaItem = await schema.getItem(name);
+        if (this.isSchemaItemLoaded(schemaItem)) {
+            return schemaItem;
+        }
         switch (parseSchemaItemType(itemType)) {
             case SchemaItemType.EntityClass:
-                schemaItem = await schema.createEntityClass(name);
-                await this.loadEntityClass(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createEntityClass(name);
+                schemaItemObject && await this.loadEntityClass(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.StructClass:
-                schemaItem = await schema.createStructClass(name);
-                const structProps = this._parser.parseStructClass(schemaItemObject);
-                await this.loadClass(schemaItem, structProps, schemaItemObject);
+                schemaItem = schemaItem || await schema.createStructClass(name);
+                const structProps = schemaItemObject && this._parser.parseStructClass(schemaItemObject);
+                structProps && await this.loadClass(schemaItem, structProps, schemaItemObject);
                 break;
             case SchemaItemType.Mixin:
-                schemaItem = await schema.createMixinClass(name);
-                await this.loadMixin(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createMixinClass(name);
+                schemaItemObject && await this.loadMixin(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.CustomAttributeClass:
-                schemaItem = await schema.createCustomAttributeClass(name);
-                const caClassProps = this._parser.parseCustomAttributeClass(schemaItemObject);
-                await this.loadClass(schemaItem, caClassProps, schemaItemObject);
+                schemaItem = schemaItem || await schema.createCustomAttributeClass(name);
+                const caClassProps = schemaItemObject && this._parser.parseCustomAttributeClass(schemaItemObject);
+                caClassProps && await this.loadClass(schemaItem, caClassProps, schemaItemObject);
                 break;
             case SchemaItemType.RelationshipClass:
-                schemaItem = await schema.createRelationshipClass(name);
-                await this.loadRelationshipClass(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createRelationshipClass(name);
+                schemaItemObject && await this.loadRelationshipClass(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.KindOfQuantity:
-                schemaItem = await schema.createKindOfQuantity(name);
-                await this.loadKindOfQuantity(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createKindOfQuantity(name);
+                schemaItemObject && await this.loadKindOfQuantity(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Unit:
-                schemaItem = await schema.createUnit(name);
-                await this.loadUnit(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createUnit(name);
+                schemaItemObject && await this.loadUnit(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Constant:
-                schemaItem = await schema.createConstant(name);
-                await this.loadConstant(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createConstant(name);
+                schemaItemObject && await this.loadConstant(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.InvertedUnit:
-                schemaItem = await schema.createInvertedUnit(name);
-                await this.loadInvertedUnit(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createInvertedUnit(name);
+                schemaItemObject && await this.loadInvertedUnit(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Format:
-                schemaItem = await schema.createFormat(name);
-                await this.loadFormat(schemaItem, schemaItemObject);
+                schemaItem = schemaItem || await schema.createFormat(name);
+                schemaItemObject && await this.loadFormat(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Phenomenon:
-                schemaItem = await schema.createPhenomenon(name);
-                const phenomenonProps = this._parser.parsePhenomenon(schemaItemObject);
-                await schemaItem.fromJSON(phenomenonProps);
+                schemaItem = schemaItem || await schema.createPhenomenon(name);
+                const phenomenonProps = schemaItemObject && this._parser.parsePhenomenon(schemaItemObject);
+                phenomenonProps && await schemaItem.fromJSON(phenomenonProps);
                 break;
             case SchemaItemType.UnitSystem:
-                schemaItem = await schema.createUnitSystem(name);
-                await schemaItem.fromJSON(this._parser.parseUnitSystem(schemaItemObject));
+                schemaItem = schemaItem || await schema.createUnitSystem(name);
+                schemaItemObject && await schemaItem.fromJSON(this._parser.parseUnitSystem(schemaItemObject));
                 break;
             case SchemaItemType.PropertyCategory:
-                schemaItem = await schema.createPropertyCategory(name);
-                const propertyCategoryProps = this._parser.parsePropertyCategory(schemaItemObject);
-                await schemaItem.fromJSON(propertyCategoryProps);
+                schemaItem = schemaItem || await schema.createPropertyCategory(name);
+                const propertyCategoryProps = schemaItemObject && this._parser.parsePropertyCategory(schemaItemObject);
+                propertyCategoryProps && schemaItemObject && await schemaItem.fromJSON(propertyCategoryProps);
                 break;
             case SchemaItemType.Enumeration:
-                schemaItem = await schema.createEnumeration(name);
-                const enumerationProps = this._parser.parseEnumeration(schemaItemObject);
-                await schemaItem.fromJSON(enumerationProps);
+                schemaItem = schemaItem || await schema.createEnumeration(name);
+                const enumerationProps = schemaItemObject && this._parser.parseEnumeration(schemaItemObject);
+                enumerationProps && await schemaItem.fromJSON(enumerationProps);
                 break;
             // NOTE: we are being permissive here and allowing unknown types to silently fail. Not sure if we want to hard fail or just do a basic deserialization
         }
         return schemaItem;
     }
+    /**
+     * Load the customAttribute class dependencies for a set of CustomAttribute objects and add
+     * them to a given custom attribute container.
+     * @param container The CustomAttributeContainer that each CustomAttribute will be added to.
+     * @param customAttributes An iterable set of parsed CustomAttribute objects.
+     */
+    async loadCustomAttributes(container, caProviders) {
+        for (const providerTuple of caProviders) {
+            // First tuple entry is the CA class name.
+            const caClass = await this.findSchemaItem(providerTuple[0]);
+            // If custom attribute exist within the context and is referenced, validate the reference is defined in the container's schema
+            if (caClass && caClass.key.schemaName !== container.schema.name &&
+                !container.schema.getReferenceSync(caClass.key.schemaName)) {
+                throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `Unable to load custom attribute ${caClass.fullName} from container ${container.fullName}, ${caClass.key.schemaName} reference not defined`);
+            }
+            // Second tuple entry ia a function that provides the CA instance.
+            const provider = providerTuple[1];
+            const customAttribute = provider(caClass);
+            container.addCustomAttribute(customAttribute);
+        }
+    }
     /**
      * Given the schema item object, the anticipated type and the name a schema item is created and loaded into the schema provided.
      * @param schema The Schema the SchemaItem to.
@@ -279,66 +325,69 @@ export class SchemaReadHelper {
      * @param schemaItemObject The Object to populate the SchemaItem with.
      */
     loadSchemaItemSync(schema, name, itemType, schemaItemObject) {
-        let schemaItem;
+        let schemaItem = schema.getItemSync(name);
+        if (this.isSchemaItemLoaded(schemaItem)) {
+            return schemaItem;
+        }
         switch (parseSchemaItemType(itemType)) {
             case SchemaItemType.EntityClass:
-                schemaItem = schema.createEntityClassSync(name);
+                schemaItem = schemaItem || schema.createEntityClassSync(name);
                 this.loadEntityClassSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.StructClass:
-                schemaItem = schema.createStructClassSync(name);
+                schemaItem = schemaItem || schema.createStructClassSync(name);
                 const structProps = this._parser.parseStructClass(schemaItemObject);
                 this.loadClassSync(schemaItem, structProps, schemaItemObject);
                 break;
             case SchemaItemType.Mixin:
-                schemaItem = schema.createMixinClassSync(name);
+                schemaItem = schemaItem || schema.createMixinClassSync(name);
                 this.loadMixinSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.CustomAttributeClass:
-                schemaItem = schema.createCustomAttributeClassSync(name);
+                schemaItem = schemaItem || schema.createCustomAttributeClassSync(name);
                 const caClassProps = this._parser.parseCustomAttributeClass(schemaItemObject);
                 this.loadClassSync(schemaItem, caClassProps, schemaItemObject);
                 break;
             case SchemaItemType.RelationshipClass:
-                schemaItem = schema.createRelationshipClassSync(name);
+                schemaItem = schemaItem || schema.createRelationshipClassSync(name);
                 this.loadRelationshipClassSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.KindOfQuantity:
-                schemaItem = schema.createKindOfQuantitySync(name);
+                schemaItem = schemaItem || schema.createKindOfQuantitySync(name);
                 this.loadKindOfQuantitySync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Unit:
-                schemaItem = schema.createUnitSync(name);
+                schemaItem = schemaItem || schema.createUnitSync(name);
                 this.loadUnitSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Constant:
-                schemaItem = schema.createConstantSync(name);
+                schemaItem = schemaItem || schema.createConstantSync(name);
                 this.loadConstantSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.InvertedUnit:
-                schemaItem = schema.createInvertedUnitSync(name);
+                schemaItem = schemaItem || schema.createInvertedUnitSync(name);
                 this.loadInvertedUnitSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Format:
-                schemaItem = schema.createFormatSync(name);
+                schemaItem = schemaItem || schema.createFormatSync(name);
                 this.loadFormatSync(schemaItem, schemaItemObject);
                 break;
             case SchemaItemType.Phenomenon:
-                schemaItem = schema.createPhenomenonSync(name);
+                schemaItem = schemaItem || schema.createPhenomenonSync(name);
                 const phenomenonProps = this._parser.parsePhenomenon(schemaItemObject);
                 schemaItem.fromJSONSync(phenomenonProps);
                 break;
             case SchemaItemType.UnitSystem:
-                schemaItem = schema.createUnitSystemSync(name);
+                schemaItem = schemaItem || schema.createUnitSystemSync(name);
                 schemaItem.fromJSONSync(this._parser.parseUnitSystem(schemaItemObject));
                 break;
             case SchemaItemType.PropertyCategory:
-                schemaItem = schema.createPropertyCategorySync(name);
+                schemaItem = schemaItem || schema.createPropertyCategorySync(name);
                 const propertyCategoryProps = this._parser.parsePropertyCategory(schemaItemObject);
                 schemaItem.fromJSONSync(propertyCategoryProps);
                 break;
             case SchemaItemType.Enumeration:
-                schemaItem = schema.createEnumerationSync(name);
+                schemaItem = schemaItem || schema.createEnumerationSync(name);
                 const enumerationProps = this._parser.parseEnumeration(schemaItemObject);
                 schemaItem.fromJSONSync(enumerationProps);
                 break;
@@ -386,7 +435,7 @@ export class SchemaReadHelper {
             const foundItem = this._parser.findItem(itemName);
             if (foundItem) {
                 schemaItem = await this.loadSchemaItem(this._schema, ...foundItem);
-                if (!skipVisitor && schemaItem && this._visitorHelper) {
+                if (!skipVisitor && this.isSchemaItemLoaded(schemaItem) && this._visitorHelper) {
                     await this._visitorHelper.visitSchemaPart(schemaItem);
                 }
                 if (loadCallBack && schemaItem)
@@ -419,7 +468,7 @@ export class SchemaReadHelper {
             const foundItem = this._parser.findItem(itemName);
             if (foundItem) {
                 schemaItem = this.loadSchemaItemSync(this._schema, ...foundItem);
-                if (!skipVisitor && schemaItem && this._visitorHelper) {
+                if (!skipVisitor && this.isSchemaItemLoaded(schemaItem) && this._visitorHelper) {
                     this._visitorHelper.visitSchemaPartSync(schemaItem);
                 }
                 if (loadCallBack && schemaItem)
@@ -569,7 +618,7 @@ export class SchemaReadHelper {
      */
     async loadClass(classObj, classProps, rawClass) {
         const baseClassLoaded = async (baseClass) => {
-            if (this._visitorHelper)
+            if (this._visitorHelper && this.isSchemaItemLoaded(baseClass))
                 await this._visitorHelper.visitSchemaPart(baseClass);
         };
         // Load base class first
@@ -592,7 +641,7 @@ export class SchemaReadHelper {
      */
     loadClassSync(classObj, classProps, rawClass) {
         const baseClassLoaded = async (baseClass) => {
-            if (this._visitorHelper)
+            if (this._visitorHelper && this.isSchemaItemLoaded(baseClass))
                 this._visitorHelper.visitSchemaPartSync(baseClass);
         };
         // Load base class first
@@ -643,7 +692,7 @@ export class SchemaReadHelper {
     async loadMixin(mixin, rawMixin) {
         const mixinProps = this._parser.parseMixin(rawMixin);
         const appliesToLoaded = async (appliesToClass) => {
-            if (this._visitorHelper)
+            if (this._visitorHelper && this.isSchemaItemLoaded(appliesToClass))
                 await this._visitorHelper.visitSchemaPart(appliesToClass);
         };
         await this.findSchemaItem(mixinProps.appliesTo, true, appliesToLoaded);
@@ -657,7 +706,7 @@ export class SchemaReadHelper {
     loadMixinSync(mixin, rawMixin) {
         const mixinProps = this._parser.parseMixin(rawMixin);
         const appliesToLoaded = async (appliesToClass) => {
-            if (this._visitorHelper)
+            if (this._visitorHelper && this.isSchemaItemLoaded(appliesToClass))
                 await this._visitorHelper.visitSchemaPart(appliesToClass);
         };
         this.findSchemaItemSync(mixinProps.appliesTo, true, appliesToLoaded);
@@ -853,27 +902,6 @@ export class SchemaReadHelper {
         propertyObj.fromJSONSync(props);
         this.loadCustomAttributesSync(propertyObj, this._parser.getPropertyCustomAttributeProviders(rawProperty));
     }
-    /**
-     * Load the customAttribute class dependencies for a set of CustomAttribute objects and add
-     * them to a given custom attribute container.
-     * @param container The CustomAttributeContainer that each CustomAttribute will be added to.
-     * @param customAttributes An iterable set of parsed CustomAttribute objects.
-     */
-    async loadCustomAttributes(container, caProviders) {
-        for (const providerTuple of caProviders) {
-            // First tuple entry is the CA class name.
-            const caClass = await this.findSchemaItem(providerTuple[0]);
-            // If custom attribute exist within the context and is referenced, validate the reference is defined in the container's schema
-            if (caClass && caClass.key.schemaName !== container.schema.name &&
-                !container.schema.getReferenceSync(caClass.key.schemaName)) {
-                throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `Unable to load custom attribute ${caClass.fullName} from container ${container.fullName}, ${caClass.key.schemaName} reference not defined`);
-            }
-            // Second tuple entry ia a function that provides the CA instance.
-            const provider = providerTuple[1];
-            const customAttribute = provider(caClass);
-            container.addCustomAttribute(customAttribute);
-        }
-    }
     /**
      * Load the customAttribute class dependencies for a set of CustomAttribute objects and add them to a given custom attribute container.
      * @param container The CustomAttributeContainer that each CustomAttribute will be added to.