@itwin/presentation-hierarchies 2.0.0-alpha.2 → 2.0.0-alpha.20

package/lib/hierarchies/imodel/IModelHierarchyProvider.js

@@ -0,0 +1,656 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import "../internal/DisposePolyfill.js";
+import { catchError, concat, defaultIfEmpty, EMPTY, filter, finalize, from, fromEventPattern, identity, map, merge, mergeAll, mergeMap, of, reduce, Subject, take, takeUntil, tap, } from "rxjs";
+import { assert, BeEvent, Guid, StopWatch } from "@itwin/core-bentley";
+import { createDefaultValueFormatter, createIModelInstanceLabelSelectClauseFactory, eachValueFrom, formatConcatenatedValue, InstanceKey, normalizeFullClassName, } from "@itwin/presentation-shared";
+import { RowsLimitExceededError } from "../HierarchyErrors.js";
+import { HierarchyNode } from "../HierarchyNode.js";
+import { HierarchyNodeKey } from "../HierarchyNodeKey.js";
+import { HierarchySearchTree } from "../HierarchySearch.js";
+import { LOGGING_NAMESPACE as BASE_LOGGING_NAMESPACE, LOGGING_NAMESPACE_INTERNAL as BASE_LOGGING_NAMESPACE_INTERNAL, LOGGING_NAMESPACE_PERFORMANCE as BASE_LOGGING_NAMESPACE_PERFORMANCE, createNodeIdentifierForLogging, hasChildren, } from "../internal/Common.js";
+import { doLog, log } from "../internal/LoggingUtils.js";
+import { partition } from "../internal/operators/Partition.js";
+import { reduceToMergeMapList } from "../internal/operators/ReduceToMergeMap.js";
+import { shareReplayWithErrors } from "../internal/operators/ShareReplayWithErrors.js";
+import { sortNodesByLabelOperator } from "../internal/operators/Sorting.js";
+import { getRxjsHierarchyDefinition } from "../internal/RxjsHierarchyDefinition.js";
+import { SubscriptionScheduler } from "../internal/SubscriptionScheduler.js";
+import { HierarchyCache } from "./HierarchyCache.js";
+import { HierarchyNodesDefinition } from "./IModelHierarchyDefinition.js";
+import { createNodesQueryClauseFactory, NodeSelectClauseColumnNames } from "./NodeSelectQueryFactory.js";
+import { createDetermineChildrenOperator } from "./operators/DetermineChildren.js";
+import { createGroupingOperator } from "./operators/Grouping.js";
+import { createHideIfNoChildrenOperator } from "./operators/HideIfNoChildren.js";
+import { createHideNodesInHierarchyOperator } from "./operators/HideNodesInHierarchy.js";
+import { SearchHierarchyDefinition } from "./SearchHierarchyDefinition.js";
+import { readNodes } from "./TreeNodesReader.js";
+import { ECSQL_PREFIX } from "./Utils.js";
+const LOGGING_NAMESPACE = `${BASE_LOGGING_NAMESPACE}.IModelHierarchyProvider`;
+const LOGGING_NAMESPACE_INTERNAL = `${BASE_LOGGING_NAMESPACE_INTERNAL}.IModelHierarchyProvider`;
+const LOGGING_NAMESPACE_PERFORMANCE = `${BASE_LOGGING_NAMESPACE_PERFORMANCE}.IModelHierarchyProvider`;
+const DEFAULT_QUERY_CONCURRENCY = 10;
+const DEFAULT_QUERY_CACHE_SIZE = 1;
+/**
+ * Creates an instance of `HierarchyProvider` that creates a hierarchy based on given the iModel and
+ * a hierarchy definition, which defines each hierarchy level through ECSQL queries.
+ *
+ * @public
+ */
+export function createIModelHierarchyProvider(props) {
+    const { imodelAccess, imodelChanged, instanceLabelSelectClauseFactory, ...restProps } = props;
+    return createMergedIModelHierarchyProvider({
+        ...restProps,
+        imodels: [{ imodelAccess, imodelChanged, instanceLabelSelectClauseFactory }],
+    });
+}
+/**
+ * Creates an instance of `HierarchyProvider` that creates a hierarchy based on multiple version of **the same** iModel
+ * and a hierarchy definition, which defines each hierarchy level through ECSQL queries.
+ *
+ * **Warning:** This is an experimental API that **should not be used in production**.
+ *
+ * @alpha
+ */
+export function createMergedIModelHierarchyProvider(props) {
+    return new IModelHierarchyProviderImpl(props);
+}
+class IModelHierarchyProviderImpl {
+    _imodelProps;
+    _imodels;
+    _hierarchyChanged;
+    _valuesFormatter;
+    _sourceHierarchyDefinition;
+    _activeHierarchyDefinition;
+    _localizedStrings;
+    _queryConcurrency;
+    _querySchedulers;
+    _nodesCache;
+    _unsubscribe;
+    _dispose = new Subject();
+    #componentId;
+    #componentName;
+    #sourceName;
+    constructor(props) {
+        if (props.imodels.length === 0) {
+            throw new Error(`Creating an iModel hierarchy provider requires at least one iModel.`);
+        }
+        this.#componentId = Guid.createValue();
+        this.#componentName = "IModelHierarchyProviderImpl";
+        this.#sourceName = props.sourceName ?? `${this.#componentName}:${this.#componentId}`;
+        this._imodelProps = props.imodels;
+        this._imodels = props.imodels.map((imodelProps) => this.#createIModelState(imodelProps));
+        this._hierarchyChanged = new BeEvent();
+        this._activeHierarchyDefinition = this._sourceHierarchyDefinition = getRxjsHierarchyDefinition(props.hierarchyDefinition);
+        this._valuesFormatter = props.formatter ?? createDefaultValueFormatter();
+        this._localizedStrings = { other: "Other", unspecified: "Not specified", ...props.localizedStrings };
+        this._queryConcurrency = props.queryConcurrency ?? DEFAULT_QUERY_CONCURRENCY;
+        this._querySchedulers = new Map();
+        this.setHierarchySearch(props.search);
+        const queryCacheSize = props.queryCacheSize ?? DEFAULT_QUERY_CACHE_SIZE;
+        if (queryCacheSize !== 0) {
+            this._nodesCache = new HierarchyCache({
+                // we divide the size by 2, because each variation also counts as a query that we cache
+                size: Math.ceil(queryCacheSize / 2),
+                variationsCount: 1,
+            });
+        }
+        const imodelChangeSubscription = from(this._imodels)
+            .pipe(mergeMap(({ imodelAccess, imodelChanged }, index) => imodelChanged
+            ? fromEventPattern((handler) => imodelChanged.addListener(handler), (handler) => imodelChanged.removeListener(handler), () => ({ imodelKey: imodelAccess.imodelKey, index }))
+            : EMPTY))
+            .subscribe(({ imodelKey, index }) => {
+            this.invalidateHierarchyCache(`Data source changed: "${imodelKey}"`);
+            this._dispose.next();
+            // The iModel's schemas may have changed, so re-create the query factories to drop their schema-derived caches.
+            this._imodels[index] = this.#createIModelState(this._imodelProps[index]);
+            this._hierarchyChanged.raiseEvent({});
+        });
+        this._unsubscribe = () => {
+            imodelChangeSubscription.unsubscribe();
+        };
+    }
+    #createIModelState(imodelProps) {
+        const { imodelAccess, imodelChanged } = imodelProps;
+        const instanceLabelSelectClauseFactory = imodelProps.instanceLabelSelectClauseFactory ?? createIModelInstanceLabelSelectClauseFactory({ imodelAccess });
+        const nodeSelectClauseFactory = createNodesQueryClauseFactory({ imodelAccess, instanceLabelSelectClauseFactory });
+        return { imodelAccess, imodelChanged, nodeSelectClauseFactory };
+    }
+    [Symbol.dispose]() {
+        this._dispose.next();
+        this._unsubscribe?.();
+    }
+    /* v8 ignore next -- @preserve */
+    dispose() {
+        this[Symbol.dispose]();
+    }
+    get hierarchyChanged() {
+        return this._hierarchyChanged;
+    }
+    getQueryScheduler(imodelKey) {
+        let scheduler = this._querySchedulers.get(imodelKey);
+        if (!scheduler) {
+            scheduler = new SubscriptionScheduler(this._queryConcurrency);
+            this._querySchedulers.set(imodelKey, scheduler);
+        }
+        return scheduler;
+    }
+    getPrimaryIModelAccess() {
+        return this._imodels[this._imodels.length - 1].imodelAccess;
+    }
+    invalidateHierarchyCache(reason) {
+        /* v8 ignore next -- @preserve */
+        doLog({
+            category: `${LOGGING_NAMESPACE}.Events`,
+            message: () => (reason ? `${reason}: clear hierarchy cache` : `Clear hierarchy cache`),
+        });
+        this._nodesCache?.clear();
+    }
+    /**
+     * Sets `HierarchyProvider` values formatter that formats nodes' labels. If provided `undefined`, then defaults to the
+     * result of `createDefaultValueFormatter` called with default parameters.
+     */
+    setFormatter(formatter) {
+        this._valuesFormatter = formatter ?? createDefaultValueFormatter();
+        this._hierarchyChanged.raiseEvent({ formatterChange: { newFormatter: this._valuesFormatter } });
+    }
+    setHierarchySearch(props) {
+        if (!props) {
+            if (this._sourceHierarchyDefinition !== this._activeHierarchyDefinition) {
+                this._activeHierarchyDefinition = this._sourceHierarchyDefinition;
+                this.invalidateHierarchyCache("Hierarchy search reset");
+            }
+            this._hierarchyChanged.raiseEvent({ searchChange: { newSearch: undefined } });
+            return;
+        }
+        this._activeHierarchyDefinition = new SearchHierarchyDefinition({
+            imodelAccess: this.getPrimaryIModelAccess(),
+            source: this._sourceHierarchyDefinition,
+            sourceName: this.#sourceName,
+            targetPaths: props.paths,
+        });
+        this.invalidateHierarchyCache("Hierarchy search set");
+        this._dispose.next();
+        this._hierarchyChanged.raiseEvent({ searchChange: { newSearch: props } });
+    }
+    onGroupingNodeCreated(groupingNode, props) {
+        this._nodesCache?.set({ ...props, parentNode: groupingNode }, { observable: from(groupingNode.children), processingStatus: "pre-processed" });
+    }
+    createHierarchyLevelDefinitionsObservable(props) {
+        const { requestContext, ...defineHierarchyLevelProps } = props;
+        /* v8 ignore next -- @preserve */
+        doLog({
+            category: LOGGING_NAMESPACE_PERFORMANCE,
+            message: () => `[${requestContext.requestId}] Requesting hierarchy level definitions for ${createNodeIdentifierForLogging(props.parentNode)}`,
+        });
+        return from(this._imodels).pipe(mergeMap(({ imodelAccess, nodeSelectClauseFactory }, imodelAccessIndex) => {
+            let parentNode = props.parentNode;
+            if (parentNode &&
+                HierarchyNode.isGeneric(parentNode) &&
+                parentNode.key.source &&
+                parentNode.key.source !== this.#sourceName) {
+                return EMPTY;
+            }
+            if (parentNode && HierarchyNode.isInstancesNode(parentNode)) {
+                parentNode = {
+                    ...parentNode,
+                    key: {
+                        ...parentNode.key,
+                        instanceKeys: parentNode.key.instanceKeys.filter((ik) => !ik.imodelKey || ik.imodelKey === imodelAccess.imodelKey),
+                    },
+                };
+                assert(HierarchyNodeKey.isInstances(parentNode.key));
+                if (parentNode.key.instanceKeys.length === 0) {
+                    return EMPTY;
+                }
+            }
+            return this._activeHierarchyDefinition
+                .defineHierarchyLevel({
+                ...defineHierarchyLevelProps,
+                createSelectClause: async (selectClauseProps) => nodeSelectClauseFactory.createSelectClause(selectClauseProps),
+                /* v8 ignore start */
+                createFilterClauses: async (filterClausesProps) => nodeSelectClauseFactory.createFilterClauses(filterClausesProps),
+                /* v8 ignore stop */
+                parentNode,
+                imodelAccess,
+            })
+                .pipe(mergeAll(), map(
+            /* Using `as` to work around TS not understanding that `{ x: A, y: B | C }` is the same as `{ x: A } & ({ y: B } | { y: C })` */
+            (hierarchyNodesDefinition) => ({ imodelAccess, imodelAccessIndex, hierarchyNodesDefinition })));
+        }), finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: LOGGING_NAMESPACE_PERFORMANCE,
+                message: () => `[${requestContext.requestId}] Received all hierarchy level definitions for ${createNodeIdentifierForLogging(props.parentNode)}`,
+            });
+        }));
+    }
+    createSourceNodesObservable(props) {
+        const createSourceNodesFromDefinition = (imodelAccess, def) => {
+            if (HierarchyNodesDefinition.isGenericNode(def)) {
+                return of({ ...def.node, key: { type: "generic", id: def.node.key, source: this.#sourceName } });
+            }
+            const query = createInstanceKeysFilteredQuery(def.query, props.targetInstanceKeys);
+            return this.getQueryScheduler(imodelAccess.imodelKey).scheduleSubscription(readNodes({
+                queryExecutor: imodelAccess,
+                query,
+                limit: props.hierarchyLevelSizeLimit,
+                parser: this._activeHierarchyDefinition.parseNode
+                    ? ({ row }) => this._activeHierarchyDefinition.parseNode({
+                        row,
+                        parentNode: props.parentNode,
+                        imodelKey: imodelAccess.imodelKey,
+                    })
+                    : undefined,
+            }).pipe(map((node) => ({
+                ...node,
+                key: {
+                    ...node.key,
+                    instanceKeys: node.key.instanceKeys.map((key) => ({ ...key, imodelKey: imodelAccess.imodelKey })),
+                },
+            }))));
+        };
+        const definitions = this.createHierarchyLevelDefinitionsObservable(props);
+        let sourceNodes;
+        if (this._imodels.length === 1) {
+            sourceNodes = definitions.pipe(mergeMap(({ imodelAccess, hierarchyNodesDefinition: def }) => createSourceNodesFromDefinition(imodelAccess, def)));
+        }
+        else {
+            sourceNodes = definitions.pipe(mergeMap(({ imodelAccess, imodelAccessIndex, hierarchyNodesDefinition: def }) => createSourceNodesFromDefinition(imodelAccess, def).pipe(map((node) => ({ imodelAccess, imodelAccessIndex, node })))), mergeNodes, map(({ node }) => node));
+        }
+        return sourceNodes.pipe(finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: LOGGING_NAMESPACE_PERFORMANCE,
+                message: () => `[${props.requestContext.requestId}] Read all child nodes ${createNodeIdentifierForLogging(props.parentNode)}`,
+            });
+        }), shareReplayWithErrors());
+    }
+    createPreProcessedNodesObservable(queryNodesObservable, props) {
+        return queryNodesObservable.pipe(
+        // we're going to be mutating the nodes, but don't want to mutate the original one, so just clone it here once
+        map((node) => ({ ...node })), 
+        // set parent node keys on the source node
+        map((node) => Object.assign(node, { parentKeys: createParentNodeKeysList(props.parentNode) })), 
+        // format `ConcatenatedValue` labels into string labels
+        mergeMap((node) => applyLabelsFormatting(node, this._valuesFormatter)), 
+        // we have `ProcessedHierarchyNode` from here
+        // let consumers step-in
+        preProcessNodes(this._activeHierarchyDefinition, props.parentNode), 
+        // process hiding
+        createHideIfNoChildrenOperator((n) => this.getChildNodesObservables({ parentNode: n, requestContext: props.requestContext }).hasNodes), createHideNodesInHierarchyOperator(
+        // note: for child nodes created because of hidden parent, we want to use parent's request props (instance filter, limit)
+        (n) => this.getChildNodesObservables({ ...props, parentNode: n }).processedNodes, false), finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: LOGGING_NAMESPACE_PERFORMANCE,
+                message: () => `[${props.requestContext.requestId}] Finished pre-processing child nodes for ${createNodeIdentifierForLogging(props.parentNode)}`,
+            });
+        }));
+    }
+    createProcessedNodesObservable(preprocessedNodesObservable, props) {
+        return preprocessedNodesObservable.pipe(createGroupingOperator(this.getPrimaryIModelAccess(), props.parentNode, this._valuesFormatter, this._localizedStrings, undefined, (gn) => this.onGroupingNodeCreated(gn, props)), finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: LOGGING_NAMESPACE_PERFORMANCE,
+                message: () => `[${props.requestContext.requestId}] Finished grouping child nodes for ${createNodeIdentifierForLogging(props.parentNode)}`,
+            });
+        }));
+    }
+    createFinalizedNodesObservable(processedNodesObservable, props) {
+        return processedNodesObservable.pipe(createDetermineChildrenOperator((n) => this.getChildNodesObservables({ parentNode: n, requestContext: props.requestContext }).hasNodes), postProcessNodes(this._activeHierarchyDefinition, props.parentNode), sortNodesByLabelOperator, map((n) => {
+            if ("processingParams" in n) {
+                delete n.processingParams;
+            }
+            return { ...n, children: hasChildren(n) };
+        }), takeUntil(this._dispose), finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: LOGGING_NAMESPACE_PERFORMANCE,
+                message: () => `[${props.requestContext.requestId}] Finished finalizing child nodes for ${createNodeIdentifierForLogging(props.parentNode)}`,
+            });
+        }));
+    }
+    createHasNodesObservable(preprocessedNodesObservable, possiblyKnownChildrenObservable, props) {
+        const loggingCategory = `${LOGGING_NAMESPACE_INTERNAL}.HasNodes`;
+        return concat((possiblyKnownChildrenObservable ?? EMPTY).pipe(filter((n) => hasChildren(n))), preprocessedNodesObservable).pipe(
+        /* v8 ignore next -- @preserve */
+        log({
+            category: loggingCategory,
+            message: (n) => `[${props.requestContext.requestId}] Node before mapping to 'true': ${createNodeIdentifierForLogging(n)}`,
+        }), take(1), map(() => true), defaultIfEmpty(false), catchError((e) => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: loggingCategory,
+                message: () => `[${props.requestContext.requestId}] Error while determining children: ${e.message}`,
+            });
+            if (e instanceof RowsLimitExceededError) {
+                return of(true);
+            }
+            throw e;
+        }), 
+        /* v8 ignore next -- @preserve */
+        log({ category: loggingCategory, message: (r) => `[${props.requestContext.requestId}] Result: ${r}` }));
+    }
+    getCachedObservableEntry(props) {
+        const loggingCategory = `${LOGGING_NAMESPACE}.QueryResultsCache`;
+        const { parentNode, ...restProps } = props;
+        const cached = props.ignoreCache || !this._nodesCache ? undefined : this._nodesCache.get(props);
+        if (cached) {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: loggingCategory,
+                message: () => `[${props.requestContext.requestId}] Found query nodes observable for ${createNodeIdentifierForLogging(parentNode)}`,
+            });
+            return cached;
+        }
+        // if we don't find an entry for a grouping node, we load its instances by getting a query and applying
+        // a search based on grouped instance keys
+        let targetInstanceKeys;
+        let parentNonGroupingNode;
+        if (parentNode) {
+            if (HierarchyNode.isGroupingNode(parentNode)) {
+                parentNonGroupingNode = parentNode.nonGroupingAncestor;
+                targetInstanceKeys = parentNode.groupedInstanceKeys;
+            }
+            else {
+                // not sure why type checker doesn't pick this up
+                assert(HierarchyNode.isGeneric(parentNode) || HierarchyNode.isInstancesNode(parentNode));
+                parentNonGroupingNode = parentNode;
+            }
+        }
+        const nonGroupingNodeChildrenRequestProps = {
+            ...restProps,
+            parentNode: parentNonGroupingNode,
+            ...(targetInstanceKeys ? { targetInstanceKeys } : undefined),
+        };
+        const value = {
+            observable: this.createSourceNodesObservable(nonGroupingNodeChildrenRequestProps),
+            processingStatus: "none",
+        };
+        this._nodesCache?.set(nonGroupingNodeChildrenRequestProps, value);
+        /* v8 ignore next -- @preserve */
+        doLog({
+            category: loggingCategory,
+            message: () => `[${props.requestContext.requestId}] Saved query nodes observable for ${createNodeIdentifierForLogging(parentNode)}`,
+        });
+        return value;
+    }
+    getChildNodesObservables(props) {
+        const entry = this.getCachedObservableEntry(props);
+        switch (entry.processingStatus) {
+            case "none": {
+                const pre = this.createPreProcessedNodesObservable(entry.observable, props);
+                const post = this.createProcessedNodesObservable(pre, props);
+                return {
+                    processedNodes: post,
+                    hasNodes: this.createHasNodesObservable(pre, entry.observable, props),
+                    finalizedNodes: this.createFinalizedNodesObservable(post, props),
+                };
+            }
+            case "pre-processed": {
+                const post = this.createProcessedNodesObservable(entry.observable, props);
+                return {
+                    processedNodes: post,
+                    hasNodes: this.createHasNodesObservable(entry.observable, undefined, props),
+                    finalizedNodes: this.createFinalizedNodesObservable(post, props),
+                };
+            }
+        }
+    }
+    /**
+     * Creates and runs a query based on provided props, then processes retrieved nodes and returns them.
+     */
+    getNodes(props) {
+        const requestContext = { requestId: Guid.createValue() };
+        const loggingCategory = `${LOGGING_NAMESPACE}.GetNodes`;
+        const timer = new StopWatch(undefined, true);
+        let error;
+        let nodesCount = 0;
+        /* v8 ignore next -- @preserve */
+        doLog({
+            category: loggingCategory,
+            message: () => `[${requestContext.requestId}] Requesting child nodes for ${createNodeIdentifierForLogging(props.parentNode)}`,
+        });
+        return eachValueFrom(this.getChildNodesObservables({ ...props, requestContext }).finalizedNodes.pipe(tap(() => ++nodesCount), catchError((e) => {
+            error = e;
+            throw e;
+        }), finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: loggingCategory,
+                message: () => error
+                    ? `[${requestContext.requestId}] Error creating child nodes for ${createNodeIdentifierForLogging(props.parentNode)}: ${error instanceof Error ? error.message : error.toString()}`
+                    : `[${requestContext.requestId}] Returned ${nodesCount} child nodes for ${createNodeIdentifierForLogging(props.parentNode)} in ${timer.currentSeconds.toFixed(2)} s.`,
+            });
+        })));
+    }
+    getNodeInstanceKeysObs(props) {
+        const { parentNode, instanceFilter, hierarchyLevelSizeLimit = "unbounded", requestContext } = props;
+        if (parentNode && HierarchyNode.isGroupingNode(parentNode)) {
+            return from(parentNode.groupedInstanceKeys);
+        }
+        assert(!parentNode || HierarchyNode.isGeneric(parentNode) || HierarchyNode.isInstancesNode(parentNode));
+        // split the definitions based on whether they're for generic nodes or for instance nodes
+        const hierarchyLevelDefinitions = this.createHierarchyLevelDefinitionsObservable({
+            parentNode,
+            instanceFilter,
+            requestContext,
+        });
+        const [instanceDefs, genericDefs] = partition(hierarchyLevelDefinitions, (x) => HierarchyNodesDefinition.isInstanceNodesQuery(x.hierarchyNodesDefinition));
+        // query instance keys and a flag whether they should be hidden
+        const instanceKeys = instanceDefs.pipe(mergeMap(({ imodelAccess, hierarchyNodesDefinition: def }) => this.getQueryScheduler(imodelAccess.imodelKey).scheduleSubscription(of(def.query).pipe(mergeMap(async (query) => {
+            const ecsql = `
+                SELECT
+                  ${NodeSelectClauseColumnNames.FullClassName},
+                  ${NodeSelectClauseColumnNames.ECInstanceId},
+                  ${NodeSelectClauseColumnNames.HideNodeInHierarchy}
+                FROM (
+                  ${query.ecsql}
+                )
+              `;
+            const reader = imodelAccess.createQueryReader({ ...query, ecsql }, {
+                rowFormat: "Indexes",
+                limit: hierarchyLevelSizeLimit,
+                restartToken: `${this.#componentName}/${this.#componentId}/node-instance-keys/${Guid.createValue()}`,
+            });
+            return from(reader).pipe(map((row) => ({
+                key: {
+                    className: normalizeFullClassName(row[0]),
+                    id: row[1],
+                    imodelKey: imodelAccess.imodelKey,
+                },
+                hide: !!row[2],
+            })));
+        }), mergeAll()))));
+        // split the instance keys observable based on whether they should be hidden or not
+        const [visibleNodeInstanceKeys, hiddenNodeInstanceKeys] = partition(instanceKeys, ({ hide }) => !hide);
+        // hidden items' handling:
+        // - if a generic node is hidden, we'll want to retrieve instance keys of its children, otherwise we don't care about it,
+        // - if an instance key is hidden, we want to create a merged node similar to what we do in `createHideNodesInHierarchyOperator`
+        const hiddenParentNodes = merge(genericDefs.pipe(filter(({ hierarchyNodesDefinition }) => !!hierarchyNodesDefinition.node.processingParams?.hideInHierarchy), map(({ hierarchyNodesDefinition }) => ({
+            type: "generic",
+            id: hierarchyNodesDefinition.node.key,
+            source: this.#sourceName,
+        }))), hiddenNodeInstanceKeys.pipe(
+        // first merge all keys by class
+        reduceToMergeMapList(({ key }) => key.className, ({ key }) => key), 
+        // then, for each class, create an instance key
+        mergeMap((mergedMap) => [...mergedMap.entries()].map(([className, keys]) => ({
+            type: "instances",
+            instanceKeys: keys.map(({ id, imodelKey }) => ({ className, id, imodelKey })),
+        }))))).pipe(map((key) => ({ key, parentKeys: [], label: "" })));
+        // merge visible instance keys from this level & the ones we get recursively requesting from deeper levels
+        return merge(visibleNodeInstanceKeys.pipe(map(({ key }) => key)), hiddenParentNodes.pipe(mergeMap((hiddenNode) => this.getNodeInstanceKeysObs({ parentNode: hiddenNode, requestContext })))).pipe(takeUntil(this._dispose));
+    }
+    /**
+     * Creates an iterator for all child hierarchy level instance keys, taking into account any hidden hierarchy levels
+     * that there may be under the given parent node.
+     */
+    getNodeInstanceKeys(props) {
+        const requestContext = { requestId: Guid.createValue() };
+        const loggingCategory = `${LOGGING_NAMESPACE}.GetNodeInstanceKeys`;
+        const timer = new StopWatch(undefined, true);
+        /* v8 ignore next -- @preserve */
+        doLog({
+            category: loggingCategory,
+            message: () => `[${requestContext.requestId}] Requesting keys for ${createNodeIdentifierForLogging(props.parentNode)}`,
+        });
+        let error;
+        let keysCount = 0;
+        return eachValueFrom(this.getNodeInstanceKeysObs({ ...props, requestContext }).pipe(tap(() => ++keysCount), catchError((e) => {
+            error = e;
+            throw e;
+        }), finalize(() => {
+            /* v8 ignore next -- @preserve */
+            doLog({
+                category: loggingCategory,
+                message: () => error
+                    ? `[${requestContext.requestId}] Error creating node instance keys for ${createNodeIdentifierForLogging(props.parentNode)}: ${error instanceof Error ? error.message : error.toString()}`
+                    : `[${requestContext.requestId}] Returned ${keysCount} instance keys for ${createNodeIdentifierForLogging(props.parentNode)} in ${timer.currentSeconds.toFixed(2)} s.`,
+            });
+        })));
+    }
+}
+function preProcessNodes(hierarchyFactory, parentNode) {
+    return hierarchyFactory.preProcessNode ? processNodes(hierarchyFactory.preProcessNode, parentNode) : identity;
+}
+function postProcessNodes(hierarchyFactory, parentNode) {
+    return hierarchyFactory.postProcessNode ? processNodes(hierarchyFactory.postProcessNode, parentNode) : identity;
+}
+function processNodes(processor, parentNode) {
+    return (nodes) => nodes.pipe(mergeMap((node) => processor({ node, parentNode })));
+}
+function applyLabelsFormatting(node, valueFormatter) {
+    return from(formatConcatenatedValue({ value: node.label, valueFormatter })).pipe(map((label) => ({ ...node, label })));
+}
+function createParentNodeKeysList(parentNode) {
+    if (!parentNode) {
+        return [];
+    }
+    return [...parentNode.parentKeys, parentNode.key];
+}
+function createInstanceKeysFilteredQuery(query, targetInstanceKeys) {
+    if (!targetInstanceKeys || !targetInstanceKeys.length) {
+        return query;
+    }
+    if (Array.isArray(query.bindings)) {
+        return {
+            ...query,
+            ecsql: `
+        SELECT *
+        FROM (${query.ecsql}) q
+        JOIN IdSet(?) targetInstanceKeys ON targetInstanceKeys.id = q.ECInstanceId
+        ECSQLOPTIONS ENABLE_EXPERIMENTAL_FEATURES
+      `,
+            bindings: [...query.bindings, { type: "idset", value: targetInstanceKeys.map((k) => k.id) }],
+        };
+    }
+    const ecsqlVarTargetInstanceKeys = `${ECSQL_PREFIX}targetInstanceKeys`;
+    return {
+        ...query,
+        ecsql: `
+      SELECT *
+      FROM (${query.ecsql}) q
+      JOIN IdSet(:${ecsqlVarTargetInstanceKeys}) targetInstanceKeys ON targetInstanceKeys.id = q.ECInstanceId
+      ECSQLOPTIONS ENABLE_EXPERIMENTAL_FEATURES
+    `,
+        bindings: {
+            ...query.bindings,
+            [ecsqlVarTargetInstanceKeys]: { type: "idset", value: targetInstanceKeys.map((k) => k.id) },
+        },
+    };
+}
+// TODO: MISSING_COVERAGE
+/* v8 ignore start */
+function mergeNodes(source) {
+    return from(source).pipe(reduce((acc, input) => {
+        for (let i = 0; i < acc.length; ++i) {
+            if (input.imodelAccess === acc[i].imodelAccess) {
+                // don't attempt to merge nodes if they come from the same provider
+                continue;
+            }
+            // the first argument for `tryMergeNodes` acts as the primary data source, so we have to make sure we pass
+            // the node with higher `imodelAccessIndex` first
+            const candidates = input.imodelAccessIndex > acc[i].imodelAccessIndex
+                ? {
+                    imodelAccess: input.imodelAccess,
+                    imodelAccessIndex: input.imodelAccessIndex,
+                    primary: input.node,
+                    secondary: acc[i].node,
+                }
+                : {
+                    imodelAccess: acc[i].imodelAccess,
+                    imodelAccessIndex: acc[i].imodelAccessIndex,
+                    primary: acc[i].node,
+                    secondary: input.node,
+                };
+            const merged = tryMergeNodes(candidates.primary, candidates.secondary);
+            if (merged) {
+                acc[i] = {
+                    node: merged,
+                    imodelAccess: candidates.imodelAccess,
+                    imodelAccessIndex: candidates.imodelAccessIndex,
+                };
+                return acc;
+            }
+        }
+        acc.push(input);
+        return acc;
+    }, new Array()), mergeAll());
+}
+function mergeSearchAttribute(primary, secondary) {
+    if (!primary) {
+        return secondary;
+    }
+    if (!secondary) {
+        return primary;
+    }
+    const hasSearchTargetAncestor = primary.hasSearchTargetAncestor || secondary.hasSearchTargetAncestor;
+    const isSearchTarget = primary.isSearchTarget || secondary.isSearchTarget;
+    const searchOptions = HierarchySearchTree.mergeOptions(primary.options, secondary.options);
+    const childrenTargetPathsBuilder = HierarchySearchTree.createBuilder();
+    primary.childrenTargetPaths?.forEach((tree) => childrenTargetPathsBuilder.accept({ tree }));
+    secondary.childrenTargetPaths?.forEach((tree) => childrenTargetPathsBuilder.accept({ tree }));
+    const childrenTargetPaths = childrenTargetPathsBuilder.getTree();
+    return {
+        ...(hasSearchTargetAncestor ? { hasSearchTargetAncestor } : undefined),
+        ...(childrenTargetPaths.length ? { childrenTargetPaths } : undefined),
+        ...(isSearchTarget ? { isSearchTarget } : undefined),
+        ...(searchOptions ? { options: searchOptions } : undefined),
+    };
+}
+function mergeBaseNodeAttributes(primary, secondary) {
+    const search = mergeSearchAttribute(primary.search, secondary.search);
+    return {
+        ...(primary.autoExpand || secondary.autoExpand ? { autoExpand: true } : undefined),
+        ...(primary.children && secondary.children ? { children: true } : undefined),
+        ...(primary.supportsFiltering || secondary.supportsFiltering ? { supportsFiltering: true } : undefined),
+        ...(search ? { search } : undefined),
+    };
+}
+function tryMergeInstanceNodes(primary, secondary) {
+    if (HierarchyNode.isInstancesNode(primary) &&
+        HierarchyNode.isInstancesNode(secondary) &&
+        primary.key.instanceKeys.some((lhsKey) => secondary.key.instanceKeys.some((rhsKey) => InstanceKey.equals(lhsKey, rhsKey)))) {
+        return {
+            ...primary,
+            key: { type: "instances", instanceKeys: primary.key.instanceKeys.concat(secondary.key.instanceKeys) },
+            ...mergeBaseNodeAttributes(primary, secondary),
+        };
+    }
+    return undefined;
+}
+function tryMergeGenericNodes(primary, secondary) {
+    if (HierarchyNode.isGeneric(primary) && HierarchyNode.isGeneric(secondary) && primary.key.id === secondary.key.id) {
+        return { ...primary, ...mergeBaseNodeAttributes(primary, secondary) };
+    }
+    return undefined;
+}
+function tryMergeNodes(primary, secondary) {
+    return tryMergeInstanceNodes(primary, secondary) ?? tryMergeGenericNodes(primary, secondary) ?? undefined;
+}
+/* v8 ignore stop */
+//# sourceMappingURL=IModelHierarchyProvider.js.map