@itwin/presentation-shared/lib/esm/shared/InstanceLabelSelectClauseFactory.d.ts

The package contains types and utilities used across different iTwin.js Presentation packages.

import { ConcatenatedValue } from "./ConcatenatedValue.js";
import { TypedValueSelectClauseProps } from "./ecsql-snippets/ECSqlValueSelectorSnippets.js";
import { ECClassHierarchyInspector } from "./Metadata.js";
/**
 * Props for `IInstanceLabelSelectClauseFactory.createSelectClause`.
 * @public
 */
interface CreateInstanceLabelSelectClauseProps {
    /**
     * Alias of an ECSQL class referring to the target instance whose label should be selected.
     *
     * Example:
     * ```ts
     * const selectClause = `
     *   SELECT ${await factory.createSelectClause({ classAlias: "x" })}
     *   FROM bis.GeometricElement3d AS x
     * `;
     * ```
     */
    classAlias: string;
    /**
     * An optional full name of the class whose instance label is to be selected.
     *
     * The attribute's purpose is purely for optimization and `IInstanceLabelSelectClauseFactory` should not
     * rely on this to be set to a leaf class or set at all. However, when this name is provided, some factory
     * implementations may be able to create a more efficient select clause (e.g. drop some pieces of clause
     * that don't apply for given class).
     */
    className?: string;
    /**
     * An optional function for concatenating multiple `TypedValueSelectClauseProps`. Selectors' concatenation
     * is used when a label consists of multiple pieces, e.g.:
     * - `[` - string,
     * - `this.PropertyX` - property value selector,
     * - `]` - string.
     *
     * It's concatenator's job to serialize those pieces into a single selector and, depending on the use case,
     * it may do that in multiple ways. For example:
     *
     * - `createConcatenatedValueJsonSelector` serializes parts into a JSON array selector. This allows the array to
     *   be parsed after the query is run, where each part can be handled individually without losing its metadata.
     *   This is the default value.
     *
     * - `createConcatenatedValueStringSelector` concatenates parts into a string using SQLite's `||` operator. While
     *   this way of concatenation looses metadata (thus disabling formatting of the values), it tries to produce the
     *   value to be as close as possible to the formatted one. This concatenator may be used to create a label for using
     *   in the query `WHERE` clause.
     *
     * @see `createConcatenatedValueJsonSelector`
     * @see `createConcatenatedValueStringSelector`
     */
    selectorsConcatenator?: (selectors: TypedValueSelectClauseProps[], checkSelector?: string) => string;
}
/**
 * An interface for a factory that knows how create instance label select clauses.
 * @see `createDefaultInstanceLabelSelectClauseFactory`
 * @see `createClassBasedInstanceLabelSelectClauseFactory`
 * @see `createBisInstanceLabelSelectClauseFactory`
 * @public
 */
export interface IInstanceLabelSelectClauseFactory {
    /** Creates a select clause for an instance label. */
    createSelectClause(props: CreateInstanceLabelSelectClauseProps): Promise<string>;
}
/**
 * Parses an instance label from query result into a string or a `ConcatenatedValue`. The latter type of result
 * is expected when label selector is created using `IInstanceLabelSelectClauseFactory.createSelectClause` with
 * `createConcatenatedValueJsonSelector`.
 *
 * @public
 */
export declare function parseInstanceLabel(value: string | undefined): ConcatenatedValue | string;
/**
 * Creates a label select clause in a format `Class label [base36(briefcase id)-base36(local id)]`, where
 * local and briefcase IDs are calculated based on ECInstance ID:
 * - `{briefcase id} = ECInstanceId >> 40`
 * - `{local id} = ECInstanceId & (1 << 40 - 1)`
 *
 * @see https://www.itwinjs.org/presentation/advanced/defaultbisrules/#label-overrides
 * @public
 */
export declare function createDefaultInstanceLabelSelectClauseFactory(): IInstanceLabelSelectClauseFactory;
/**
 * An association of a class and an instance label select clause factory method.
 * @public
 */
interface ClassBasedLabelSelectClause {
    /** Full class name */
    className: string;
    /** A factory method to create an instance label select clause */
    clause: (props: CreateInstanceLabelSelectClauseProps) => Promise<string>;
}
/**
 * Props for `createClassBasedInstanceLabelSelectClauseFactory`.
 * @public
 */
interface ClassBasedInstanceLabelSelectClauseFactoryProps {
    /** Access to ECClass hierarchy in the iModel. */
    classHierarchyInspector: ECClassHierarchyInspector;
    /**
     * A prioritized list of instance label selectors associated to classes they should be applied to.
     *
     * Because the list may contain clauses for classes in the same class hierarchy, and the factory
     * handles them in given order, the order of clauses should be from the most specific class to the
     * most general one.
     */
    clauses: ClassBasedLabelSelectClause[];
    /**
     * A fallback label clause factory for when class-based factory doesn't produce a label.
     * Defaults to the result of `createDefaultInstanceLabelSelectClauseFactory`.
     */
    defaultClauseFactory?: IInstanceLabelSelectClauseFactory;
}
/**
 * Creates an instance label select clause based on its class.
 * @public
 */
export declare function createClassBasedInstanceLabelSelectClauseFactory(props: ClassBasedInstanceLabelSelectClauseFactoryProps): IInstanceLabelSelectClauseFactory;
/**
 * Props for `createBisInstanceLabelSelectClauseFactory`.
 * @public
 */
interface BisInstanceLabelSelectClauseFactoryProps {
    classHierarchyInspector: ECClassHierarchyInspector;
}
/**
 * Creates a label select clause according to BIS instance label rules.
 * @see https://www.itwinjs.org/presentation/advanced/defaultbisrules/#label-overrides
 * @public
 */
export declare function createBisInstanceLabelSelectClauseFactory(props: BisInstanceLabelSelectClauseFactoryProps): IInstanceLabelSelectClauseFactory;
export {};
//# sourceMappingURL=InstanceLabelSelectClauseFactory.d.ts.map