@itwin/ecschema-metadata/lib/esm/Context.d.ts

ECObjects core concepts in typescript

import { SchemaMatchType } from "./ECObjects";
import { SchemaInfo } from "./Interfaces";
import { Schema } from "./Metadata/Schema";
import { SchemaItem } from "./Metadata/SchemaItem";
import { SchemaItemKey, SchemaKey } from "./SchemaKey";
import { ECClassHierarchy } from "./utils/ECClassHierarchy";
/**
 * The interface defines what is needed to be an `ISchemaLocater`.
 * A Schema Locater loads the requested schema if it can or returns undefined.
 * Schema Locaters should always load the schema on each request and should not hold a cache of schemas.
 * Schema locaters should never be used directly to load a schema, they should be added to a `SchemaContext`
 * and the context should be used to load schemas.  The `SchemaContext` caches schemas and manages schema life time.
 * @public @preview
 */
export interface ISchemaLocater {
    /**
     * Attempts to get a schema from the locater. Yields undefined if no matching schema is found.
     * For schemas that may have references, construct and call through a SchemaContext instead.
     * @param schemaKey key to look up
     * @param matchType how to match key against candidate schemas
     * @param context context for loading schema references
     */
    getSchema(schemaKey: SchemaKey, matchType: SchemaMatchType, context: SchemaContext): Promise<Schema | undefined>;
    /**
    * Gets the schema info which matches the provided SchemaKey.  The schema info may be returned before the schema is fully loaded.
    * May return the entire Schema so long as it is completely loaded as it satisfies the SchemaInfo interface.
    * @param schemaKey The SchemaKey describing the schema to get from the cache.
    * @param matchType The match type to use when locating the schema
    */
    getSchemaInfo(schemaKey: SchemaKey, matchType: SchemaMatchType, context: SchemaContext): Promise<SchemaInfo | undefined>;
    /**
     * Attempts to get a schema from the locater. Yields undefined if no matching schema is found.
     * For schemas that may have references, construct and call through a SchemaContext instead.
     * @param schemaKey key to look up
     * @param matchType how to match key against candidate schemas
     * @param context context for loading schema references
     */
    getSchemaSync(schemaKey: SchemaKey, matchType: SchemaMatchType, context: SchemaContext): Schema | undefined;
}
/**
 * @internal
 */
export declare class SchemaCache implements ISchemaLocater {
    private _schema;
    constructor();
    get count(): number;
    private loadedSchemaExists;
    private schemaPromiseExists;
    private findEntry;
    private removeSchemaPromise;
    private removeEntry;
    /**
     * Returns true if the schema exists in either the schema cache or the promise cache.  SchemaMatchType.Latest used.
     * @param schemaKey The key to search for.
     */
    schemaExists(schemaKey: SchemaKey): boolean;
    /**
     * Adds a promise to load the schema to the cache. Does not allow for duplicate schemas in the cache of schemas or cache of promises, checks using SchemaMatchType.Latest.
     * When the promise completes the schema will be added to the schema cache and the promise will be removed from the promise cache
     * @param schemaInfo An object with the schema key for the schema being loaded and it's references
     * @param schema The partially loaded schema that the promise will fulfill
     * @param schemaPromise The schema promise to add to the cache.
     */
    addSchemaPromise(schemaInfo: SchemaInfo, schema: Schema, schemaPromise: Promise<Schema>): Promise<void>;
    /**
     * Adds a schema to the cache. Does not allow for duplicate schemas, checks using SchemaMatchType.Latest.
     * @param schema The schema to add to the cache.
     */
    addSchema(schema: Schema): Promise<void>;
    /**
     * Adds a schema to the cache. Does not allow for duplicate schemas, checks using SchemaMatchType.Latest.
     * @param schema The schema to add to the cache.
     */
    addSchemaSync(schema: Schema): void;
    /**
     * Gets the schema which matches the provided SchemaKey.
     * @param schemaKey The SchemaKey describing the schema to get from the cache.
     * @param matchType The match type to use when locating the schema
     */
    getSchema(schemaKey: SchemaKey, matchType?: SchemaMatchType): Promise<Schema | undefined>;
    /**
      * Gets the schema info which matches the provided SchemaKey.  The schema info may be returned before the schema is fully loaded.
      * @param schemaKey The SchemaKey describing the schema to get from the cache.
      * @param matchType The match type to use when locating the schema
      */
    getSchemaInfo(schemaKey: SchemaKey, matchType?: SchemaMatchType): Promise<SchemaInfo | undefined>;
    /**
     * Gets the schema which matches the provided SchemaKey.  If the schema is partially loaded an exception will be thrown.
     * @param schemaKey The SchemaKey describing the schema to get from the cache.
     * @param matchType The match type to use when locating the schema
     */
    getSchemaSync(schemaKey: SchemaKey, matchType?: SchemaMatchType): Schema | undefined;
    /**
     * Generator function that can iterate through each schema in _schema SchemaMap and items for each Schema.
     * Does not include schema items from schemas that are not completely loaded yet.
     */
    getSchemaItems(): Iterable<SchemaItem>;
    /**
     * Gets all the schemas from the schema cache.
     * Does not include schemas from schemas that are not completely loaded yet.
     * @returns An array of Schema objects.
     */
    getAllSchemas(): Iterable<Schema>;
}
/**
 * The SchemaContext, context object is used to facilitate schema and schema item location.
 *
 * The context controls the lifetime of each schema that it knows about. It has to be explicitly removed from the context to delete a schema object.
 *
 * The context is made up of a group of Schema Locators.
 * @public @preview
 */
export declare class SchemaContext {
    private _locaters;
    private _knownSchemas;
    private _fallbackLocaterDefined;
    private _classHierarchy;
    constructor();
    get locaters(): ReadonlyArray<ISchemaLocater>;
    /** @internal */
    get classHierarchy(): ECClassHierarchy;
    /**
     * Adds a locater to the context.
     *
     * If no locaters are defined or a fallback locater is not defined, the new locater is added at the end of the locaters array.
     * If a fallback locater is already defined, the new locater is inserted before the fallback locater.
     *
     * @param locater - The locater to be added.
     */
    addLocater(locater: ISchemaLocater): void;
    /**
     * Adds a fallback locater to the context.
     *
     * If a fallback locater is already defined, it replaces the existing one.
     * Otherwise, it adds the new locater to the end of the locaters array and marks the fallback locater as defined.
     *
     * @param locater - The locater to be added as a fallback.
     */
    addFallbackLocater(locater: ISchemaLocater): void;
    /**
     * Adds the schema to this context.  Use addSchemaPromise instead when asynchronously loading schemas.
     * @param schema The schema to add to this context
     */
    addSchema(schema: Schema): Promise<void>;
    /**
     * Adds the schema to this context
     * @param schema The schema to add to this context
     */
    addSchemaSync(schema: Schema): void;
    /**
     * Adds the given SchemaItem to the the SchemaContext by locating the schema, with the best match of SchemaMatchType.Exact, and
     * @param schemaItem The SchemaItem to add
     * @deprecated in 4.0 - will not be removed until after 2026-06-13. Use ecschema-editing package
     */
    addSchemaItem(schemaItem: SchemaItem): Promise<void>;
    /**
     * Returns true if the schema is already in the context.  SchemaMatchType.Latest is used to find a match.
     * @param schemaKey
     */
    schemaExists(schemaKey: SchemaKey): boolean;
    /**
     * Adds a promise to load the schema to the cache. Does not allow for duplicate schemas in the cache of schemas or cache of promises, checks using SchemaMatchType.Latest.
     * When the promise completes the schema will be added to the schema cache and the promise will be removed from the promise cache.
     * Use this method over addSchema when asynchronously loading schemas
     * @param schemaInfo An object with the schema key for the schema being loaded and it's references
     * @param schema The partially loaded schema that the promise will fulfill
     * @param schemaPromise The schema promise to add to the cache.
     */
    addSchemaPromise(schemaInfo: SchemaInfo, schema: Schema, schemaPromise: Promise<Schema>): Promise<void>;
    /** Attempts to obtain a schema from this context that matches the specified criteria.
     * @param schemaKey Identifies the schema to obtain.
     * @param matchType Criteria by which to identify potentially matching schemas.
     * @returns the schema matching the input criteria, or `undefined` if no such schema could be located.
     */
    getSchema(schemaKey: SchemaKey, matchType?: SchemaMatchType): Promise<Schema | undefined>;
    /**
     * Gets the schema info which matches the provided SchemaKey.  The schema info may be returned before the schema is fully loaded.
     * The fully loaded schema can be gotten later from the context using [[getSchema]].
     * @param schemaKey The SchemaKey describing the schema to get from the cache.
     * @param matchType The match type to use when locating the schema
     */
    getSchemaInfo(schemaKey: SchemaKey, matchType: SchemaMatchType): Promise<SchemaInfo | undefined>;
    /** Attempts to obtain a schema from this context that matches the specified criteria.
     * Will return undefined if the schema is partially loaded.  Use [[getSchema]] to await until the schema is completely loaded.
     * @param schemaKey Identifies the schema to obtain.
     * @param matchType Criteria by which to identify potentially matching schemas.
     * @returns the schema matching the input criteria, or `undefined` if no such schema could be located.
     */
    getSchemaSync(schemaKey: SchemaKey, matchType?: SchemaMatchType): Schema | undefined;
    /**
     * Attempts to get a Schema from the context's cache.
     * Will await a partially loaded schema then return when it is completely loaded.
     * @param schemaKey The SchemaKey to identify the Schema.
     * @param matchType The SchemaMatch type to use. Default is SchemaMatchType.Latest.
     * @internal
     */
    getCachedSchema(schemaKey: SchemaKey, matchType?: SchemaMatchType): Promise<Schema | undefined>;
    /**
     * Attempts to get a Schema from the context's cache.
     * Will return undefined if the cached schema is partially loaded.  Use [[getCachedSchema]] to await until the schema is completely loaded.
     * @param schemaKey The SchemaKey to identify the Schema.
     * @param matchType The SchemaMatch type to use. Default is SchemaMatchType.Latest.
     * @internal
     */
    getCachedSchemaSync(schemaKey: SchemaKey, matchType?: SchemaMatchType): Schema | undefined;
    /**
     * Gets the schema item from the specified schema if it exists in this [[SchemaContext]].
     * Will await a partially loaded schema then look in it for the requested item.
     *
     * @param schemaNameOrKey - The SchemaItemKey identifying the item to return or the name of the schema or the schema item full name.
     * @param itemNameOrCtor - The name of the item to return or the constructor of the item to return.
     * @param itemConstructor - The constructor of the item to return.
     * @returns The requested schema item, or `undefined` if the item could not be found.
     *
     * @examples
     * ```typescript
     * const schemaItem = await schemaContext.getSchemaItem(new SchemaItemKey("TestElement", new SchemaKey("TestSchema")));
     * const schemaItemWithCtor = await schemaContext.getSchemaItem(new SchemaItemKey("TestElement", new SchemaKey("TestSchema")), EntityClass);
     * const schemaItemByName = await schemaContext.getSchemaItem("TestSchema", "TestElement");
     * const schemaItemByNameWithCtor = await schemaContext.getSchemaItem("TestSchema", "TestElement", EntityClass);
     * const schemaItemFullName = await schemaContext.getSchemaItem("TestSchema:TestElement", EntityClass);
     * const schemaItemFullNameWithCtor = await schemaContext.getSchemaItem("TestSchema:TestElement", EntityClass);
     * const schemaItemFullNameSep = await schemaContext.getSchemaItem("TestSchema.TestElement", EntityClass);
     * const schemaItemFullNameSepWithCtor = await schemaContext.getSchemaItem("TestSchema.TestElement", EntityClass);
     * ```
     */
    getSchemaItem<T extends typeof SchemaItem>(schemaNameOrKey: SchemaItemKey | string, itemNameOrCtor?: T): Promise<InstanceType<T> | undefined>;
    getSchemaItem<T extends typeof SchemaItem>(schemaNameOrKey: SchemaItemKey | string, itemNameOrCtor?: T): Promise<SchemaItem | undefined>;
    getSchemaItem<T extends typeof SchemaItem>(schemaNameOrKey: string, itemNameOrCtor: string, itemConstructor?: T): Promise<InstanceType<T> | undefined>;
    getSchemaItem<T extends typeof SchemaItem>(schemaNameOrKey: string, itemNameOrCtor: string, itemConstructor?: T): Promise<SchemaItem | undefined>;
    /**
     * Gets the schema item from the specified schema if it exists in this [[SchemaContext]].
     * Will return undefined if the cached schema is partially loaded. Use [[getSchemaItem]] to await until the schema is completely loaded.
     *
     * @param nameOrKey - The SchemaItemKey identifying the item to return or the name of the schema or the schema item full name.
     * @param nameOrCtor - The name of the item to return or the constructor of the item to return.
     * @param ctor - The constructor of the item to return.
     * @returns The requested schema item, or `undefined` if the item could not be found.
     *
     * @example
     * ```typescript
     * const schemaItem = schemaContext.getSchemaItemSync(new SchemaItemKey("TestElement", new SchemaKey("TestSchema")));
     * const schemaItemWithCtor = schemaContext.getSchemaItemSync(new SchemaItemKey("TestElement", new SchemaKey("TestSchema")), EntityClass);
     * const schemaItemByName = schemaContext.getSchemaItemSync("TestSchema", "TestElement");
     * const schemaItemByNameWithCtor = schemaContext.getSchemaItemSync("TestSchema", "TestElement", EntityClass);
     * const schemaItemFullName = schemaContext.getSchemaItemSync("TestSchema:TestElement", EntityClass);
     * const schemaItemFullNameWithCtor = schemaContext.getSchemaItemSync("TestSchema:TestElement", EntityClass);
     * const schemaItemFullNameSep = schemaContext.getSchemaItemSync("TestSchema.TestElement", EntityClass);
     * const schemaItemFullNameSepWithCtor = schemaContext.getSchemaItemSync("TestSchema.TestElement", EntityClass);
     * ```
     */
    getSchemaItemSync<T extends typeof SchemaItem>(schemaNameOrKey: SchemaItemKey | string, itemNameOrCtor?: T): InstanceType<T> | undefined;
    getSchemaItemSync<T extends typeof SchemaItem>(schemaNameOrKey: SchemaItemKey | string, itemNameOrCtor?: T): SchemaItem | undefined;
    getSchemaItemSync<T extends typeof SchemaItem>(schemaNameOrKey: string, itemNameOrCtor: string, itemConstructor?: T): InstanceType<T> | undefined;
    getSchemaItemSync<T extends typeof SchemaItem>(schemaNameOrKey: string, itemNameOrCtor: string, itemConstructor?: T): SchemaItem | undefined;
    /**
     * Iterates through the items of each schema known to the context.  This includes schemas added to the
     * context using [[SchemaContext.addSchema]]. This does not include schemas that
     * can be located by an ISchemaLocater instance added to the context.
     * Does not include schema items from schemas that are not completely loaded yet.
     */
    getSchemaItems(): Iterable<SchemaItem>;
    /**
     * Gets all the Schemas known by the context. This includes schemas added to the
     * context using [[SchemaContext.addSchema]]. This does not include schemas that
     * can be located by an ISchemaLocater instance added to the context.  Does not
     * include schemas that are partially loaded.
     * @returns An array of Schema objects.
     */
    getKnownSchemas(): Iterable<Schema>;
}
//# sourceMappingURL=Context.d.ts.map