ecschema-metadata integration in backend

[rschili]

First step of cleaning up ClassRegistry, removing redundancy and make ecschema-metadata available in backend.

Story: https://github.com/iTwin/itwinjs-backlog/issues/1156

This is the first of several PRs, it only adds the dependency and adds some ways to access the data, it does not replace any existing logic yet.

[ColinKerr]

Is it possible to take in just typeof SchemaItem and have it just behave the same?

[rschili]

Mmh it doesn't quite work like that. I tried so many variations now....

public getItemSync<T extends SchemaItem>(name: string, itemConstructor?: typeof SchemaItem): T | undefined {

I think this is what you had in mind. The problem with that is, that itemConstructor is not connected to T in this case. So you could call getItemSync<EntityClass>("name", Unit); which does not make any sense.

What DOES work is this:

  public getItemSync<T extends typeof SchemaItem>(name: string, itemConstructor?: T): InstanceType<T> | undefined {
    const value = this._items.get(name.toUpperCase());
    if (value === undefined)
      return value;

    if (itemConstructor !== undefined && (value.schemaItemType !== itemConstructor.schemaItemType))
      throw new ECObjectsError(ECObjectsStatus.InvalidSchemaItemType, `The item ${name} is not of the expected type.`);

    return value as InstanceType<T>;
  }

But that is a break, because now the generic parameter has to be typeof EntityClass so everybody calling the method with getItemSync<EntityClass> has to adjust it to getItemSync<typeof EntityClass>. I guess we could do that, but I'm hesitant...

[rschili]

I reworked it a bit. Strangely, when I put SchemaItemConstructor into SchemaItem.ts and import it, the compiler would complain it cannot find the schemaItemType static property on the constructor. But IntelliSense didn't complain.
When I moved the type into the Schema.ts file, everything suddenly worked fine...

[ColinKerr]

This is cleaner but I'm concerned that this method could be suprising to callers. If called without the constructor it will return undefined if no item is found, the item found cast to the template type regardless of the actual type. If called with the constructor it will return undefined if no item is found, the item if found and of the right type or throw if an item of the wrong type is found.

I propose that we provide two options:

1. Explicit typesafe options that return the typed item if found and of the right type or undefined if not found or not of the right type
2. Explicitly generic option that returns a SchemaItem if found and leaves it up to the user to do the type checking

I suggest this because those two methods seem to cleanly fit the usecases we've seen over the years. e.g. If I need to use a unit called smoot any other item called smoot won't do. If I want to insert a unit called smoot I want to know if any other item exists regardless of type.

What do you think?

[rschili]

Yeah agreed. I agree this mix of throwing and returnung undefined is unclean.
I'd like to hear opinions on how the API for that would look like.
In my opinion, a clean version of this would be:

public async getItem(name: string): Promise<SchemaItem | undefined> { }
public async getTypedItem<T extends typeof SchemaItem>(name: string, itemConstructor: T): Promise<InstanceType<T> | undefined> {

And you call it like this

this.getTypedItem(name, UnitSystem);

I'm just not sure about removing the generic type parameter from the non-typed method. That's a break and many many callers are using that currently. However, I think we can find and adjust those spots easily. So maybe now is the time to do it. What do you think @ColinKerr @RohitPtnkr1996 ?

[ColinKerr]

lets tag everything we're adding as @beta during development so we can go through and review everything one last time before we make 5.0 final

[rschili]

Done

[ColinKerr]

If this Schema object represents the version of the schema the domain handlers are written against you could make an argument that the version does matter.

I think what you have done is fine for now but our thinking here should be critical of the purpose of the Schema objects. That may guide us to change this later.

[rschili]

I was really thinking of not going with SchemaKey/SchemaItemKey because backend as it stands does NOT care about version. And version may differ based on imodel. So if anything, we may hold a "minimum supported version" somewhere...
I have the impression people just want to identify their schemas by name and their items by fullname, which is fine in the context of a single imodel. So if we moved away from static stuff, we may want to rework this. I'd like to hear opinions on this from consumers.

[ColinKerr]

Maybe it would be better to call this 'NoVersion' and document that a version with all zeros is an invalid version for a schema but using it in a key means no version has been specified. As it stands this could mean anything and the docs don't help you figure what it should mean

[rschili]

done. Do we want to prevent schemas to be constructed with a NO_VERSION version? I don't think we have validation on that end now...
I'll keep the comment open to remind me to add something to the docs

[ColinKerr]

We need to keep track of the breaking changes we are making. For example removing generics from ISchemaLocater.

This list should exist outside the scope of this PR so we can write up a nice doc for the 5 release.