@itwin/presentation-hierarchies 2.0.0-alpha.1 → 2.0.0-alpha.10

package/lib/esm/hierarchies/imodel/IModelHierarchyDefinition.d.ts

@@ -1,5 +1,5 @@
 import { GenericInstanceFilter } from "@itwin/core-common";
-import { ECSqlQueryDef } from "@itwin/presentation-shared";
+import { ECClassHierarchyInspector, ECSchemaProvider, ECSqlQueryDef } from "@itwin/presentation-shared";
 import { NonGroupingHierarchyNode } from "../HierarchyNode.js";
 import { ProcessedGenericHierarchyNode, ProcessedHierarchyNode, ProcessedInstanceHierarchyNode, SourceGenericHierarchyNode, SourceInstanceHierarchyNode } from "./IModelHierarchyNode.js";
 /**
@@ -46,9 +46,16 @@ export type HierarchyLevelDefinition = HierarchyNodesDefinition[];
  * A type for a function that parses a `SourceInstanceHierarchyNode` from provided ECSQL `row` object.
  * @public
  */
-export type NodeParser = (row: {
-    [columnName: string]: any;
-}, parentNode?: HierarchyDefinitionParentNode) => SourceInstanceHierarchyNode | Promise<SourceInstanceHierarchyNode>;
+export type NodeParser = (props: {
+    /** The ECSQL row object to parse. Keys & value types depend on the executed query. */
+    row: {
+        [columnName: string]: any;
+    };
+    /** The parent node whose child node is being parsed. */
+    parentNode?: HierarchyDefinitionParentNode;
+    /** The key of iModel which is used to run the query. */
+    imodelKey: string;
+}) => SourceInstanceHierarchyNode | Promise<SourceInstanceHierarchyNode>;
 /**
  * A type for a function that pre-processes given node. Unless the function decides not to make any modifications,
  * it should return a new - modified - node, rather than modifying the given one. Returning `undefined` omits the node
@@ -77,6 +84,10 @@ export type HierarchyDefinitionParentNode = Omit<NonGroupingHierarchyNode, "chil
  * @public
  */
 export interface DefineHierarchyLevelProps {
+    /** The iModel for which the hierarchy definition is being requested for. */
+    imodelAccess: ECSchemaProvider & ECClassHierarchyInspector & {
+        imodelKey: string;
+    };
     /** Parent node to get children for. Pass `undefined` to get root nodes. */
     parentNode: HierarchyDefinitionParentNode | undefined;
     /** Optional hierarchy level filter. */

package/lib/esm/hierarchies/imodel/IModelHierarchyDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IModelHierarchyDefinition.d.ts","sourceRoot":"","sources":["../../../../src/hierarchies/imodel/IModelHierarchyDefinition.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,oDAAoD;IACpD,IAAI,EAAE,0BAA0B,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,8BAA8B,GAAG,4BAA4B,CAAC;AACrG,cAAc;AAEd,yBAAiB,wBAAwB,CAAC;IACxC,SAAgB,aAAa,CAAC,GAAG,EAAE,wBAAwB,GAAG,GAAG,IAAI,8BAA8B,CAElG;IACD,SAAgB,oBAAoB,CAAC,GAAG,EAAE,wBAAwB,GAAG,GAAG,IAAI,4BAA4B,CAEvG;CACF;AAED;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,wBAAwB,EAAE,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,GAAG,EAAE;IAAE,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAClC,UAAU,CAAC,EAAE,6BAA6B,KACvC,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,SAAS,6BAA6B,GAAG,8BAA8B,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;AAEzJ;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,UAAU,EAAE,6BAA6B,GAAG,SAAS,CAAC;IAEtD,uCAAuC;IACvC,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC;IAEvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAElC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAC;IAEpC,+EAA+E;IAC/E,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC3F"}
+{"version":3,"file":"IModelHierarchyDefinition.d.ts","sourceRoot":"","sources":["../../../../src/hierarchies/imodel/IModelHierarchyDefinition.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACxG,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,oDAAoD;IACpD,IAAI,EAAE,0BAA0B,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,8BAA8B,GAAG,4BAA4B,CAAC;AACrG,cAAc;AAEd,yBAAiB,wBAAwB,CAAC;IACxC,SAAgB,aAAa,CAAC,GAAG,EAAE,wBAAwB,GAAG,GAAG,IAAI,8BAA8B,CAElG;IACD,SAAgB,oBAAoB,CAAC,GAAG,EAAE,wBAAwB,GAAG,GAAG,IAAI,4BAA4B,CAEvG;CACF;AAED;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,wBAAwB,EAAE,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE;IAC/B,sFAAsF;IACtF,GAAG,EAAE;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;IAEnC,wDAAwD;IACxD,UAAU,CAAC,EAAE,6BAA6B,CAAC;IAE3C,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB,KAAK,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,SAAS,6BAA6B,GAAG,8BAA8B,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;AAEzJ;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,YAAY,EAAE,gBAAgB,GAAG,yBAAyB,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAEnF,2EAA2E;IAC3E,UAAU,EAAE,6BAA6B,GAAG,SAAS,CAAC;IAEtD,uCAAuC;IACvC,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC;IAEvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAElC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAC;IAEpC,+EAA+E;IAC/E,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC3F"}

package/lib/esm/hierarchies/imodel/IModelHierarchyDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"IModelHierarchyDefinition.js","sourceRoot":"","sources":["../../../../src/hierarchies/imodel/IModelHierarchyDefinition.ts"],"names":[],"mappings":"AAAA;;;gGAGgG;AA6ChG,cAAc;AACd,2DAA2D;AAC3D,MAAM,KAAW,wBAAwB,CAOxC;AAPD,WAAiB,wBAAwB;IACvC,SAAgB,aAAa,CAAC,GAA6B;QACzD,OAAO,CAAC,CAAE,GAAsC,CAAC,IAAI,CAAC;IACxD,CAAC;IAFe,sCAAa,gBAE5B,CAAA;IACD,SAAgB,oBAAoB,CAAC,GAA6B;QAChE,OAAO,CAAC,CAAE,GAAoC,CAAC,KAAK,CAAC;IACvD,CAAC;IAFe,6CAAoB,uBAEnC,CAAA;AACH,CAAC,EAPgB,wBAAwB,KAAxB,wBAAwB,QAOxC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\nimport { GenericInstanceFilter } from \"@itwin/core-common\";\nimport { ECSqlQueryDef } from \"@itwin/presentation-shared\";\nimport { NonGroupingHierarchyNode } from \"../HierarchyNode.js\";\nimport {\n  ProcessedGenericHierarchyNode,\n  ProcessedHierarchyNode,\n  ProcessedInstanceHierarchyNode,\n  SourceGenericHierarchyNode,\n  SourceInstanceHierarchyNode,\n} from \"./IModelHierarchyNode.js\";\n\n/**\n * A nodes definition that returns a single generic node.\n * @public\n */\nexport interface GenericHierarchyNodeDefinition {\n  /** The node to be created in the hierarchy level */\n  node: SourceGenericHierarchyNode;\n}\n\n/**\n * A nodes definition that returns an ECSQL query for selecting nodes from an iModel.\n * @public\n */\nexport interface InstanceNodesQueryDefinition {\n  /**\n   * Full name of the class whose instances are going to be returned. It's okay if the attribute\n   * points to a base class of multiple different classes of instances returned by the query, however\n   * the more specific this class is, the more efficient hierarchy building process is.\n   */\n  fullClassName: string;\n  /**\n   * An ECSQL query that selects nodes from an iModel. `SELECT` clause of the query is expected\n   * to be built using `NodeSelectQueryFactory.createSelectClause`.\n   */\n  query: ECSqlQueryDef;\n}\n\n/**\n * A definition of nodes included in a hierarchy level.\n * @public\n */\nexport type HierarchyNodesDefinition = GenericHierarchyNodeDefinition | InstanceNodesQueryDefinition;\n/** @public */\n// eslint-disable-next-line @typescript-eslint/no-redeclare\nexport namespace HierarchyNodesDefinition {\n  export function isGenericNode(def: HierarchyNodesDefinition): def is GenericHierarchyNodeDefinition {\n    return !!(def as GenericHierarchyNodeDefinition).node;\n  }\n  export function isInstanceNodesQuery(def: HierarchyNodesDefinition): def is InstanceNodesQueryDefinition {\n    return !!(def as InstanceNodesQueryDefinition).query;\n  }\n}\n\n/**\n * A definition of a hierarchy level, which may consist of multiple node definitions.\n * @public\n */\nexport type HierarchyLevelDefinition = HierarchyNodesDefinition[];\n\n/**\n * A type for a function that parses a `SourceInstanceHierarchyNode` from provided ECSQL `row` object.\n * @public\n */\nexport type NodeParser = (\n  row: { [columnName: string]: any },\n  parentNode?: HierarchyDefinitionParentNode,\n) => SourceInstanceHierarchyNode | Promise<SourceInstanceHierarchyNode>;\n\n/**\n * A type for a function that pre-processes given node. Unless the function decides not to make any modifications,\n * it should return a new - modified - node, rather than modifying the given one. Returning `undefined` omits the node\n * from the hierarchy.\n *\n * @public\n */\nexport type NodePreProcessor = <TNode extends ProcessedGenericHierarchyNode | ProcessedInstanceHierarchyNode>(node: TNode) => Promise<TNode | undefined>;\n\n/**\n * A type for a function that post-processes given node. Unless the function decides not to make any modifications,\n * it should return a new - modified - node, rather than modifying the given one.\n *\n * @public\n */\nexport type NodePostProcessor = (node: ProcessedHierarchyNode) => Promise<ProcessedHierarchyNode>;\n\n/**\n * A type of node that can be passed to `HierarchyDefinition.defineHierarchyLevel`. This basically means\n * a `HierarchyNode` that:\n * - knows nothing about its children,\n * - is either an instances node (key is of `InstancesNodeKey` type) or a generic node (key is of `GenericNodeKey` type).\n * @public\n */\nexport type HierarchyDefinitionParentNode = Omit<NonGroupingHierarchyNode, \"children\">;\n\n/**\n * Props for `HierarchyDefinition.defineHierarchyLevel`.\n * @public\n */\nexport interface DefineHierarchyLevelProps {\n  /** Parent node to get children for. Pass `undefined` to get root nodes. */\n  parentNode: HierarchyDefinitionParentNode | undefined;\n\n  /** Optional hierarchy level filter. */\n  instanceFilter?: GenericInstanceFilter;\n}\n\n/**\n * An interface for a factory that knows how define a hierarchy based on a given parent node.\n * @public\n */\nexport interface HierarchyDefinition {\n  /**\n   * An optional function for parsing ECInstance node from ECSQL row.\n   *\n   * Should be used in situations when the `HierarchyDefinition` implementation\n   * introduces additional ECSQL columns into the select clause and wants to assign additional\n   * data to the nodes it produces.\n   *\n   * Defaults to a function that parses all `HierarchyNode` attributes from a query, whose SELECT\n   * clause is created using `NodeSelectQueryFactory.createSelectClause`.\n   */\n  parseNode?: NodeParser;\n\n  /**\n   * An optional function for pre-processing nodes.\n   *\n   * Pre-processing happens immediately after the nodes are loaded based on `HierarchyLevelDefinition`\n   * returned by this `HierarchyDefinition` and before their processing (hiding, grouping, sorting, etc.) starts.\n   * The step allows assigning nodes additional data or excluding them from the hierarchy based on some attributes.\n   */\n  preProcessNode?: NodePreProcessor;\n\n  /**\n   * An optional function for post-processing nodes.\n   *\n   * Post-processing happens after the loaded nodes go through all the merging, hiding and grouping\n   * steps, but before sorting them. This step allows `HierarchyDefinition` implementations to assign additional data\n   * to nodes after they're processed. This is especially true for grouping nodes as they're only created during\n   * processing.\n   */\n  postProcessNode?: NodePostProcessor;\n\n  /** A function to create a hierarchy level definition for given parent node. */\n  defineHierarchyLevel(props: DefineHierarchyLevelProps): Promise<HierarchyLevelDefinition>;\n}\n"]}
+{"version":3,"file":"IModelHierarchyDefinition.js","sourceRoot":"","sources":["../../../../src/hierarchies/imodel/IModelHierarchyDefinition.ts"],"names":[],"mappings":"AAAA;;;gGAGgG;AA6ChG,cAAc;AACd,2DAA2D;AAC3D,MAAM,KAAW,wBAAwB,CAOxC;AAPD,WAAiB,wBAAwB;IACvC,SAAgB,aAAa,CAAC,GAA6B;QACzD,OAAO,CAAC,CAAE,GAAsC,CAAC,IAAI,CAAC;IACxD,CAAC;IAFe,sCAAa,gBAE5B,CAAA;IACD,SAAgB,oBAAoB,CAAC,GAA6B;QAChE,OAAO,CAAC,CAAE,GAAoC,CAAC,KAAK,CAAC;IACvD,CAAC;IAFe,6CAAoB,uBAEnC,CAAA;AACH,CAAC,EAPgB,wBAAwB,KAAxB,wBAAwB,QAOxC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\nimport { GenericInstanceFilter } from \"@itwin/core-common\";\nimport { ECClassHierarchyInspector, ECSchemaProvider, ECSqlQueryDef } from \"@itwin/presentation-shared\";\nimport { NonGroupingHierarchyNode } from \"../HierarchyNode.js\";\nimport {\n  ProcessedGenericHierarchyNode,\n  ProcessedHierarchyNode,\n  ProcessedInstanceHierarchyNode,\n  SourceGenericHierarchyNode,\n  SourceInstanceHierarchyNode,\n} from \"./IModelHierarchyNode.js\";\n\n/**\n * A nodes definition that returns a single generic node.\n * @public\n */\nexport interface GenericHierarchyNodeDefinition {\n  /** The node to be created in the hierarchy level */\n  node: SourceGenericHierarchyNode;\n}\n\n/**\n * A nodes definition that returns an ECSQL query for selecting nodes from an iModel.\n * @public\n */\nexport interface InstanceNodesQueryDefinition {\n  /**\n   * Full name of the class whose instances are going to be returned. It's okay if the attribute\n   * points to a base class of multiple different classes of instances returned by the query, however\n   * the more specific this class is, the more efficient hierarchy building process is.\n   */\n  fullClassName: string;\n  /**\n   * An ECSQL query that selects nodes from an iModel. `SELECT` clause of the query is expected\n   * to be built using `NodeSelectQueryFactory.createSelectClause`.\n   */\n  query: ECSqlQueryDef;\n}\n\n/**\n * A definition of nodes included in a hierarchy level.\n * @public\n */\nexport type HierarchyNodesDefinition = GenericHierarchyNodeDefinition | InstanceNodesQueryDefinition;\n/** @public */\n// eslint-disable-next-line @typescript-eslint/no-redeclare\nexport namespace HierarchyNodesDefinition {\n  export function isGenericNode(def: HierarchyNodesDefinition): def is GenericHierarchyNodeDefinition {\n    return !!(def as GenericHierarchyNodeDefinition).node;\n  }\n  export function isInstanceNodesQuery(def: HierarchyNodesDefinition): def is InstanceNodesQueryDefinition {\n    return !!(def as InstanceNodesQueryDefinition).query;\n  }\n}\n\n/**\n * A definition of a hierarchy level, which may consist of multiple node definitions.\n * @public\n */\nexport type HierarchyLevelDefinition = HierarchyNodesDefinition[];\n\n/**\n * A type for a function that parses a `SourceInstanceHierarchyNode` from provided ECSQL `row` object.\n * @public\n */\nexport type NodeParser = (props: {\n  /** The ECSQL row object to parse. Keys & value types depend on the executed query. */\n  row: { [columnName: string]: any };\n\n  /** The parent node whose child node is being parsed. */\n  parentNode?: HierarchyDefinitionParentNode;\n\n  /** The key of iModel which is used to run the query. */\n  imodelKey: string;\n}) => SourceInstanceHierarchyNode | Promise<SourceInstanceHierarchyNode>;\n\n/**\n * A type for a function that pre-processes given node. Unless the function decides not to make any modifications,\n * it should return a new - modified - node, rather than modifying the given one. Returning `undefined` omits the node\n * from the hierarchy.\n *\n * @public\n */\nexport type NodePreProcessor = <TNode extends ProcessedGenericHierarchyNode | ProcessedInstanceHierarchyNode>(node: TNode) => Promise<TNode | undefined>;\n\n/**\n * A type for a function that post-processes given node. Unless the function decides not to make any modifications,\n * it should return a new - modified - node, rather than modifying the given one.\n *\n * @public\n */\nexport type NodePostProcessor = (node: ProcessedHierarchyNode) => Promise<ProcessedHierarchyNode>;\n\n/**\n * A type of node that can be passed to `HierarchyDefinition.defineHierarchyLevel`. This basically means\n * a `HierarchyNode` that:\n * - knows nothing about its children,\n * - is either an instances node (key is of `InstancesNodeKey` type) or a generic node (key is of `GenericNodeKey` type).\n * @public\n */\nexport type HierarchyDefinitionParentNode = Omit<NonGroupingHierarchyNode, \"children\">;\n\n/**\n * Props for `HierarchyDefinition.defineHierarchyLevel`.\n * @public\n */\nexport interface DefineHierarchyLevelProps {\n  /** The iModel for which the hierarchy definition is being requested for. */\n  imodelAccess: ECSchemaProvider & ECClassHierarchyInspector & { imodelKey: string };\n\n  /** Parent node to get children for. Pass `undefined` to get root nodes. */\n  parentNode: HierarchyDefinitionParentNode | undefined;\n\n  /** Optional hierarchy level filter. */\n  instanceFilter?: GenericInstanceFilter;\n}\n\n/**\n * An interface for a factory that knows how define a hierarchy based on a given parent node.\n * @public\n */\nexport interface HierarchyDefinition {\n  /**\n   * An optional function for parsing ECInstance node from ECSQL row.\n   *\n   * Should be used in situations when the `HierarchyDefinition` implementation\n   * introduces additional ECSQL columns into the select clause and wants to assign additional\n   * data to the nodes it produces.\n   *\n   * Defaults to a function that parses all `HierarchyNode` attributes from a query, whose SELECT\n   * clause is created using `NodeSelectQueryFactory.createSelectClause`.\n   */\n  parseNode?: NodeParser;\n\n  /**\n   * An optional function for pre-processing nodes.\n   *\n   * Pre-processing happens immediately after the nodes are loaded based on `HierarchyLevelDefinition`\n   * returned by this `HierarchyDefinition` and before their processing (hiding, grouping, sorting, etc.) starts.\n   * The step allows assigning nodes additional data or excluding them from the hierarchy based on some attributes.\n   */\n  preProcessNode?: NodePreProcessor;\n\n  /**\n   * An optional function for post-processing nodes.\n   *\n   * Post-processing happens after the loaded nodes go through all the merging, hiding and grouping\n   * steps, but before sorting them. This step allows `HierarchyDefinition` implementations to assign additional data\n   * to nodes after they're processed. This is especially true for grouping nodes as they're only created during\n   * processing.\n   */\n  postProcessNode?: NodePostProcessor;\n\n  /** A function to create a hierarchy level definition for given parent node. */\n  defineHierarchyLevel(props: DefineHierarchyLevelProps): Promise<HierarchyLevelDefinition>;\n}\n"]}

package/lib/esm/hierarchies/imodel/IModelHierarchyProvider.d.ts

@@ -1,7 +1,7 @@
 import "../internal/DisposePolyfill.js";
 import { ECClassHierarchyInspector, ECSchemaProvider, Event, IPrimitiveValueFormatter } from "@itwin/presentation-shared";
-import { HierarchyFilteringPath } from "../HierarchyFiltering.js";
 import { HierarchyProvider } from "../HierarchyProvider.js";
+import { HierarchySearchPath } from "../HierarchySearch.js";
 import { HierarchyDefinition } from "./IModelHierarchyDefinition.js";
 import { LimitingECSqlQueryExecutor } from "./LimitingECSqlQueryExecutor.js";
 /**
@@ -37,7 +37,10 @@ interface IModelHierarchyProviderProps {
      * @see `ECClassHierarchyInspector`
      */
     imodelAccess: IModelAccess;
-    /** An event that is raised when iModel data, that may affect the hierarchy, changes. */
+    /**
+     * An event that is raised when iModel data, that may affect the hierarchy, changes. The created provider
+     * subscribes to the event to know that it needs to reload the data, and unsubscribes on disposal.
+     */
     imodelChanged?: Event<() => void>;
     /**
      * A function that returns a hierarchy definition, describing how the hierarchy that the provider should be create. The
@@ -59,22 +62,54 @@ interface IModelHierarchyProviderProps {
      * by calling `setFormatter` on the provider instance.
      */
     formatter?: IPrimitiveValueFormatter;
-    /** Props for filtering the hierarchy. */
-    filtering?: {
+    /** Props for search the hierarchy. */
+    search?: {
         /** A list of node identifiers from root to target node. */
-        paths: HierarchyFilteringPath[];
+        paths: HierarchySearchPath[];
     };
 }
 /**
- * Creates an instance of `HierarchyProvider` that creates a hierarchy based on given iModel and
+ * 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 declare function createIModelHierarchyProvider(props: IModelHierarchyProviderProps): HierarchyProvider & {
-    /** @deprecated in 1.4. Use `[Symbol.dispose]` instead. */
-    dispose: () => void;
-    [Symbol.dispose]: () => void;
-};
+export declare function createIModelHierarchyProvider(props: IModelHierarchyProviderProps): HierarchyProvider & Disposable;
+/**
+ * Props for `createMergedIModelHierarchyProvider`.
+ * @alpha
+ */
+interface MergedIModelHierarchyProviderProps extends Omit<IModelHierarchyProviderProps, "imodelAccess" | "imodelChanged"> {
+    /**
+     * A list of iModels to create merged hierarchy for.
+     *
+     * **Warning:** These **must** all be different versions of the same iModel, ordered from the earliest to the
+     * latest version. Not obeying this rule may result in undefined behavior.
+     */
+    imodels: Array<{
+        /**
+         * An object that provides access to iModel's data and metadata.
+         *
+         * @see `ECSchemaProvider`
+         * @see `LimitingECSqlQueryExecutor`
+         * @see `ECClassHierarchyInspector`
+         */
+        imodelAccess: IModelAccess;
+        /**
+         * An event that is raised when iModel data, that may affect the hierarchy, changes. The created provider
+         * subscribes to the event to know that it needs to reload the data, and unsubscribes on disposal.
+         */
+        imodelChanged?: Event<() => void>;
+    }>;
+}
+/**
+ * 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 declare function createMergedIModelHierarchyProvider(props: MergedIModelHierarchyProviderProps): HierarchyProvider & Disposable;
 export {};
 //# sourceMappingURL=IModelHierarchyProvider.d.ts.map

package/lib/esm/hierarchies/imodel/IModelHierarchyProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IModelHierarchyProvider.d.ts","sourceRoot":"","sources":["../../../../src/hierarchies/imodel/IModelHierarchyProvider.ts"],"names":[],"mappings":"AAKA,OAAO,gCAAgC,CAAC;AAuBxC,OAAO,EAGL,yBAAyB,EACzB,gBAAgB,EAGhB,KAAK,EAIL,wBAAwB,EAEzB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAA0B,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAkBpF,OAAO,EAA6B,mBAAmB,EAA4B,MAAM,gCAAgC,CAAC;AAE1H,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAe7E;;;GAGG;AACH,UAAU,uCAAuC;IAC/C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,cAAc;AACd,KAAK,YAAY,GAAG,gBAAgB,GAAG,0BAA0B,GAAG,yBAAyB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH;;;GAGG;AACH,UAAU,4BAA4B;IACpC;;;;;;OAMG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B,wFAAwF;IACxF,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAElC;;;OAGG;IACH,mBAAmB,EAAE,mBAAmB,CAAC;IAEzC,qGAAqG;IACrG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC,uCAAuC,CAAC,CAAC;IAEpE;;;;OAIG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,yCAAyC;IACzC,SAAS,CAAC,EAAE;QACV,2DAA2D;QAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;KACjC,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,4BAA4B,GAAG,iBAAiB,GAAG;IACtG,0DAA0D;IAC1D,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CAC9B,CAEA"}
+{"version":3,"file":"IModelHierarchyProvider.d.ts","sourceRoot":"","sources":["../../../../src/hierarchies/imodel/IModelHierarchyProvider.ts"],"names":[],"mappings":"AAKA,OAAO,gCAAgC,CAAC;AA4BxC,OAAO,EAGL,yBAAyB,EACzB,gBAAgB,EAGhB,KAAK,EAIL,wBAAwB,EAEzB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAA0B,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAiB5D,OAAO,EAGL,mBAAmB,EAGpB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAgB7E;;;GAGG;AACH,UAAU,uCAAuC;IAC/C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,cAAc;AACd,KAAK,YAAY,GAAG,gBAAgB,GAAG,0BAA0B,GAAG,yBAAyB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH;;;GAGG;AACH,UAAU,4BAA4B;IACpC;;;;;;OAMG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAElC;;;OAGG;IACH,mBAAmB,EAAE,mBAAmB,CAAC;IAEzC,qGAAqG;IACrG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC,uCAAuC,CAAC,CAAC;IAEpE;;;;OAIG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IAErC,sCAAsC;IACtC,MAAM,CAAC,EAAE;QACP,2DAA2D;QAC3D,KAAK,EAAE,mBAAmB,EAAE,CAAC;KAC9B,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,4BAA4B,GAAG,iBAAiB,GAAG,UAAU,CAGjH;AAED;;;GAGG;AACH,UAAU,kCAAmC,SAAQ,IAAI,CAAC,4BAA4B,EAAE,cAAc,GAAG,eAAe,CAAC;IACvH;;;;;OAKG;IACH,OAAO,EAAE,KAAK,CAAC;QACb;;;;;;WAMG;QACH,YAAY,EAAE,YAAY,CAAC;QAE3B;;;WAGG;QACH,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;KACnC,CAAC,CAAC;CACJ;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,kCAAkC,GAAG,iBAAiB,GAAG,UAAU,CAE7H"}

package/lib/esm/hierarchies/imodel/IModelHierarchyProvider.js

@@ -3,12 +3,13 @@
  * 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, identity, map, merge, mergeAll, mergeMap, of, Subject, take, takeUntil, tap, } from "rxjs";
+import { catchError, concat, defaultIfEmpty, defer, 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, formatConcatenatedValue, normalizeFullClassName, } from "@itwin/presentation-shared";
+import { createDefaultValueFormatter, formatConcatenatedValue, InstanceKey, normalizeFullClassName, } from "@itwin/presentation-shared";
 import { RowsLimitExceededError } from "../HierarchyErrors.js";
 import { HierarchyNode } from "../HierarchyNode.js";
 import { HierarchyNodeKey } from "../HierarchyNodeKey.js";
+import { HierarchySearchPath } 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 { eachValueFrom } from "../internal/EachValueFrom.js";
 import { doLog, log } from "../internal/LoggingUtils.js";
@@ -18,14 +19,14 @@ import { shareReplayWithErrors } from "../internal/operators/ShareReplayWithErro
 import { sortNodesByLabelOperator } from "../internal/operators/Sorting.js";
 import { getRxjsHierarchyDefinition } from "../internal/RxjsHierarchyDefinition.js";
 import { SubscriptionScheduler } from "../internal/SubscriptionScheduler.js";
-import { FilteringHierarchyDefinition } from "./FilteringHierarchyDefinition.js";
 import { HierarchyCache } from "./HierarchyCache.js";
-import { HierarchyNodesDefinition } from "./IModelHierarchyDefinition.js";
+import { HierarchyNodesDefinition, } from "./IModelHierarchyDefinition.js";
 import { 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";
 const LOGGING_NAMESPACE = `${BASE_LOGGING_NAMESPACE}.IModelHierarchyProvider`;
 const LOGGING_NAMESPACE_INTERNAL = `${BASE_LOGGING_NAMESPACE_INTERNAL}.IModelHierarchyProvider`;
@@ -33,33 +34,57 @@ const LOGGING_NAMESPACE_PERFORMANCE = `${BASE_LOGGING_NAMESPACE_PERFORMANCE}.IMo
 const DEFAULT_QUERY_CONCURRENCY = 10;
 const DEFAULT_QUERY_CACHE_SIZE = 1;
 /**
- * Creates an instance of `HierarchyProvider` that creates a hierarchy based on given iModel and
+ * 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, ...restProps } = props;
+    return createMergedIModelHierarchyProvider({ ...restProps, imodels: [{ imodelAccess, imodelChanged }] });
+}
+/**
+ * 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 {
-    _imodelAccess;
+    _imodels;
     _hierarchyChanged;
     _valuesFormatter;
     _sourceHierarchyDefinition;
     _activeHierarchyDefinition;
     _localizedStrings;
-    _queryScheduler;
+    _queryConcurrency;
+    _querySchedulers;
     _nodesCache;
     _unsubscribe;
     _dispose = new Subject();
+    #componentId;
+    #componentName;
+    #sourceName;
     constructor(props) {
-        this._imodelAccess = props.imodelAccess;
+        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";
+        /* c8 ignore next */
+        this.#sourceName = props.sourceName ?? `${this.#componentName}:${this.#componentId}`;
+        this._imodels = props.imodels;
         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._queryScheduler = new SubscriptionScheduler(props.queryConcurrency ?? DEFAULT_QUERY_CONCURRENCY);
-        this.setHierarchyFilter(props.filtering);
+        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({
@@ -68,11 +93,18 @@ class IModelHierarchyProviderImpl {
                 variationsCount: 1,
             });
         }
-        this._unsubscribe = props.imodelChanged?.addListener(() => {
-            this.invalidateHierarchyCache("Data source changed");
+        const imodelChangeSubscription = from(this._imodels)
+            .pipe(mergeMap(({ imodelAccess, imodelChanged }) => imodelChanged
+            ? fromEventPattern((handler) => imodelChanged.addListener(handler), (handler) => imodelChanged.removeListener(handler), () => imodelAccess)
+            : EMPTY))
+            .subscribe(({ imodelKey }) => {
+            this.invalidateHierarchyCache(`Data source changed: "${imodelKey}"`);
             this._dispose.next();
             this._hierarchyChanged.raiseEvent();
         });
+        this._unsubscribe = () => {
+            imodelChangeSubscription.unsubscribe();
+        };
     }
     [Symbol.dispose]() {
         this._dispose.next();
@@ -85,6 +117,17 @@ class IModelHierarchyProviderImpl {
     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) {
         doLog({
             category: `${LOGGING_NAMESPACE}.Events`,
@@ -100,23 +143,24 @@ class IModelHierarchyProviderImpl {
         this._valuesFormatter = formatter ?? createDefaultValueFormatter();
         this._hierarchyChanged.raiseEvent({ formatterChange: { newFormatter: this._valuesFormatter } });
     }
-    setHierarchyFilter(props) {
+    setHierarchySearch(props) {
         if (!props) {
             if (this._sourceHierarchyDefinition !== this._activeHierarchyDefinition) {
                 this._activeHierarchyDefinition = this._sourceHierarchyDefinition;
-                this.invalidateHierarchyCache("Hierarchy filter reset");
+                this.invalidateHierarchyCache("Hierarchy search reset");
             }
-            this._hierarchyChanged.raiseEvent({ filterChange: { newFilter: undefined } });
+            this._hierarchyChanged.raiseEvent({ searchChange: { newSearch: undefined } });
             return;
         }
-        this._activeHierarchyDefinition = new FilteringHierarchyDefinition({
-            imodelAccess: this._imodelAccess,
+        this._activeHierarchyDefinition = new SearchHierarchyDefinition({
+            imodelAccess: this.getPrimaryIModelAccess(),
             source: this._sourceHierarchyDefinition,
-            nodeIdentifierPaths: props.paths,
+            sourceName: this.#sourceName,
+            targetPaths: props.paths,
         });
-        this.invalidateHierarchyCache("Hierarchy filter set");
+        this.invalidateHierarchyCache("Hierarchy search set");
         this._dispose.next();
-        this._hierarchyChanged.raiseEvent({ filterChange: { newFilter: props } });
+        this._hierarchyChanged.raiseEvent({ searchChange: { newSearch: props } });
     }
     onGroupingNodeCreated(groupingNode, props) {
         this._nodesCache?.set({ ...props, parentNode: groupingNode }, { observable: from(groupingNode.children), processingStatus: "pre-processed" });
@@ -127,44 +171,53 @@ class IModelHierarchyProviderImpl {
             category: LOGGING_NAMESPACE_PERFORMANCE,
             message: /* c8 ignore next */ () => `[${requestContext.requestId}] Requesting hierarchy level definitions for ${createNodeIdentifierForLogging(props.parentNode)}`,
         });
-        let parentNode = props.parentNode;
-        if (parentNode && HierarchyNode.isGeneric(parentNode) && parentNode.key.source && parentNode.key.source !== this._imodelAccess.imodelKey) {
-            return EMPTY;
-        }
-        if (parentNode && HierarchyNode.isInstancesNode(parentNode)) {
-            parentNode = {
-                ...parentNode,
-                key: {
-                    ...parentNode.key,
-                    instanceKeys: parentNode.key.instanceKeys.filter((ik) => !ik.imodelKey || ik.imodelKey === this._imodelAccess.imodelKey),
-                },
-            };
-            assert(HierarchyNodeKey.isInstances(parentNode.key));
-            if (parentNode.key.instanceKeys.length === 0) {
+        return from(this._imodels).pipe(mergeMap(({ imodelAccess }, imodelAccessIndex) => {
+            let parentNode = props.parentNode;
+            if (parentNode && HierarchyNode.isGeneric(parentNode) && parentNode.key.source && parentNode.key.source !== this.#sourceName) {
                 return EMPTY;
             }
-        }
-        return this._activeHierarchyDefinition.defineHierarchyLevel({ ...defineHierarchyLevelProps, parentNode }).pipe(mergeAll(), finalize(() => doLog({
+            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, 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(() => doLog({
             category: LOGGING_NAMESPACE_PERFORMANCE,
             message: /* c8 ignore next */ () => `[${requestContext.requestId}] Received all hierarchy level definitions for ${createNodeIdentifierForLogging(props.parentNode)}`,
         })));
     }
     createSourceNodesObservable(props) {
         // pipe definitions to nodes and put "share replay" on it
-        return this.createHierarchyLevelDefinitionsObservable(props).pipe(mergeMap((def) => {
+        return this.createHierarchyLevelDefinitionsObservable(props).pipe(mergeMap(({ imodelAccess, imodelAccessIndex, hierarchyNodesDefinition: def }) => defer(() => {
             if (HierarchyNodesDefinition.isGenericNode(def)) {
-                return of({ ...def.node, key: { type: "generic", id: def.node.key, source: this._imodelAccess.imodelKey } });
+                return of({
+                    ...def.node,
+                    key: { type: "generic", id: def.node.key, source: this.#sourceName },
+                });
             }
-            return this._queryScheduler.scheduleSubscription(of(def.query).pipe(map((query) => filterQueryByInstanceKeys(query, props.filteredInstanceKeys)), mergeMap((query) => readNodes({
-                queryExecutor: this._imodelAccess,
+            return this.getQueryScheduler(imodelAccess.imodelKey).scheduleSubscription(of(def.query).pipe(map((query) => createInstanceKeysFilteredQuery(query, props.targetInstanceKeys)), mergeMap((query) => readNodes({
+                queryExecutor: imodelAccess,
                 query,
                 limit: props.hierarchyLevelSizeLimit,
-                parser: this._activeHierarchyDefinition.parseNode ? (row) => this._activeHierarchyDefinition.parseNode(row, props.parentNode) : undefined,
+                parser: this._activeHierarchyDefinition.parseNode
+                    ? ({ row }) => this._activeHierarchyDefinition.parseNode({ row, parentNode: props.parentNode, imodelKey: imodelAccess.imodelKey })
+                    : undefined,
             })), map((node) => ({
                 ...node,
-                key: { ...node.key, instanceKeys: node.key.instanceKeys.map((key) => ({ ...key, imodelKey: this._imodelAccess.imodelKey })) },
+                key: { ...node.key, instanceKeys: node.key.instanceKeys.map((key) => ({ ...key, imodelKey: imodelAccess.imodelKey })) },
             }))));
-        }), finalize(() => doLog({
+        }).pipe(map((node) => ({ imodelAccess, imodelAccessIndex, node })))), mergeNodes, map(({ node }) => node), finalize(() => doLog({
             category: LOGGING_NAMESPACE_PERFORMANCE,
             message: /* c8 ignore next */ () => `[${props.requestContext.requestId}] Read all child nodes ${createNodeIdentifierForLogging(props.parentNode)}`,
         })), shareReplayWithErrors());
@@ -178,6 +231,7 @@ class IModelHierarchyProviderImpl {
         // format `ConcatenatedValue` labels into string labels
         mergeMap((node) => applyLabelsFormatting(node, this._valuesFormatter)), 
         // we have `ProcessedHierarchyNode` from here
+        // let consumers step-in
         preProcessNodes(this._activeHierarchyDefinition), 
         // process hiding
         createHideIfNoChildrenOperator((n) => this.getChildNodesObservables({ parentNode: n, requestContext: props.requestContext }).hasNodes), createHideNodesInHierarchyOperator(
@@ -188,7 +242,7 @@ class IModelHierarchyProviderImpl {
         })));
     }
     createProcessedNodesObservable(preprocessedNodesObservable, props) {
-        return preprocessedNodesObservable.pipe(createGroupingOperator(this._imodelAccess, props.parentNode, this._valuesFormatter, this._localizedStrings, undefined, (gn) => this.onGroupingNodeCreated(gn, props)), finalize(() => doLog({
+        return preprocessedNodesObservable.pipe(createGroupingOperator(this.getPrimaryIModelAccess(), props.parentNode, this._valuesFormatter, this._localizedStrings, undefined, (gn) => this.onGroupingNodeCreated(gn, props)), finalize(() => doLog({
             category: LOGGING_NAMESPACE_PERFORMANCE,
             message: /* c8 ignore next */ () => `[${props.requestContext.requestId}] Finished grouping child nodes for ${createNodeIdentifierForLogging(props.parentNode)}`,
         })));
@@ -198,9 +252,7 @@ class IModelHierarchyProviderImpl {
             if ("processingParams" in n) {
                 delete n.processingParams;
             }
-            return Object.assign(n, {
-                children: hasChildren(n),
-            });
+            return { ...n, children: hasChildren(n) };
         }), takeUntil(this._dispose), finalize(() => doLog({
             category: LOGGING_NAMESPACE_PERFORMANCE,
             message: /* c8 ignore next */ () => `[${props.requestContext.requestId}] Finished finalizing child nodes for ${createNodeIdentifierForLogging(props.parentNode)}`,
@@ -234,13 +286,13 @@ class IModelHierarchyProviderImpl {
             return cached;
         }
         // if we don't find an entry for a grouping node, we load its instances by getting a query and applying
-        // a filter based on grouped instance keys
-        let filteredInstanceKeys;
+        // a search based on grouped instance keys
+        let targetInstanceKeys;
         let parentNonGroupingNode;
         if (parentNode) {
             if (HierarchyNode.isGroupingNode(parentNode)) {
                 parentNonGroupingNode = parentNode.nonGroupingAncestor;
-                filteredInstanceKeys = parentNode.groupedInstanceKeys;
+                targetInstanceKeys = parentNode.groupedInstanceKeys;
             }
             else {
                 // not sure why type checker doesn't pick this up
@@ -251,7 +303,7 @@ class IModelHierarchyProviderImpl {
         const nonGroupingNodeChildrenRequestProps = {
             ...restProps,
             parentNode: parentNonGroupingNode,
-            ...(filteredInstanceKeys ? { filteredInstanceKeys } : undefined),
+            ...(targetInstanceKeys ? { targetInstanceKeys } : undefined),
         };
         const value = { observable: this.createSourceNodesObservable(nonGroupingNodeChildrenRequestProps), processingStatus: "none" };
         this._nodesCache?.set(nonGroupingNodeChildrenRequestProps, value);
@@ -315,11 +367,11 @@ class IModelHierarchyProviderImpl {
             return from(parentNode.groupedInstanceKeys);
         }
         assert(!parentNode || HierarchyNode.isGeneric(parentNode) || HierarchyNode.isInstancesNode(parentNode));
-        const hierarchyLevelDefinitions = this.createHierarchyLevelDefinitionsObservable({ parentNode, instanceFilter, requestContext });
         // split the definitions based on whether they're for generic nodes or for instance nodes
-        const [genericDefs, instanceDefs] = partition(hierarchyLevelDefinitions, HierarchyNodesDefinition.isGenericNode);
+        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((def) => this._queryScheduler.scheduleSubscription(of(def.query).pipe(mergeMap(async (query) => {
+        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},
@@ -329,12 +381,16 @@ class IModelHierarchyProviderImpl {
                   ${query.ecsql}
                 )
               `;
-            const reader = this._imodelAccess.createQueryReader({ ...query, ecsql }, { rowFormat: "Indexes", limit: hierarchyLevelSizeLimit });
+            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: this._imodelAccess.imodelKey,
+                    imodelKey: imodelAccess.imodelKey,
                 },
                 hide: !!row[2],
             })));
@@ -344,17 +400,17 @@ class IModelHierarchyProviderImpl {
         // 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((def) => !!def.node.processingParams?.hideInHierarchy), map((def) => ({
+        const hiddenParentNodes = merge(genericDefs.pipe(filter(({ hierarchyNodesDefinition }) => !!hierarchyNodesDefinition.node.processingParams?.hideInHierarchy), map(({ hierarchyNodesDefinition }) => ({
             type: "generic",
-            id: def.node.key,
-            source: this._imodelAccess.imodelKey,
+            id: hierarchyNodesDefinition.node.key,
+            source: this.#sourceName,
         }))), hiddenNodeInstanceKeys.pipe(
         // first merge all keys by class
-        reduceToMergeMapList(({ key }) => key.className, ({ key }) => key.id), 
+        reduceToMergeMapList(({ key }) => key.className, ({ key }) => key), 
         // then, for each class, create an instance key
-        mergeMap((mergedMap) => [...mergedMap.entries()].map(([className, ids]) => ({
+        mergeMap((mergedMap) => [...mergedMap.entries()].map(([className, keys]) => ({
             type: "instances",
-            instanceKeys: ids.map((id) => ({ className, id, imodelKey: this._imodelAccess.imodelKey })),
+            instanceKeys: keys.map(({ id, imodelKey }) => ({ className, id, imodelKey })),
         }))))).pipe(map((key) => ({
             key,
             parentKeys: [],
@@ -415,20 +471,20 @@ function createParentNodeKeysList(parentNode) {
     }
     return [...parentNode.parentKeys, parentNode.key];
 }
-function filterQueryByInstanceKeys(query, filteredInstanceKeys) {
-    if (!filteredInstanceKeys || !filteredInstanceKeys.length) {
+function createInstanceKeysFilteredQuery(query, targetInstanceKeys) {
+    if (!targetInstanceKeys || !targetInstanceKeys.length) {
         return query;
     }
     const MAX_ALLOWED_BINDINGS = 1000;
-    if (filteredInstanceKeys.length < MAX_ALLOWED_BINDINGS) {
+    if (targetInstanceKeys.length < MAX_ALLOWED_BINDINGS) {
         return {
             ...query,
             ecsql: `
         SELECT *
         FROM (${query.ecsql}) q
-        WHERE q.ECInstanceId IN (${filteredInstanceKeys.map(() => "?").join(",")})
+        WHERE q.ECInstanceId IN (${targetInstanceKeys.map(() => "?").join(",")})
       `,
-            bindings: [...(query.bindings ?? []), ...filteredInstanceKeys.map((k) => ({ type: "id", value: k.id }))],
+            bindings: [...(query.bindings ?? []), ...targetInstanceKeys.map((k) => ({ type: "id", value: k.id }))],
         };
     }
     /* c8 ignore start */
@@ -439,8 +495,78 @@ function filterQueryByInstanceKeys(query, filteredInstanceKeys) {
       FROM (${query.ecsql}) q
       WHERE InVirtualSet(?, q.ECInstanceId)
     `,
-        bindings: [...(query.bindings ?? []), { type: "idset", value: filteredInstanceKeys.map((k) => k.id) }],
+        bindings: [...(query.bindings ?? []), { type: "idset", value: targetInstanceKeys.map((k) => k.id) }],
     };
     /* c8 ignore end */
 }
+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 mergeSearchProps(primary, secondary) {
+    if (!primary || !secondary) {
+        return primary ?? secondary;
+    }
+    const hasSearchTargetAncestor = primary.hasSearchTargetAncestor || secondary.hasSearchTargetAncestor;
+    const childrenTargetPaths = [...(primary.childrenTargetPaths ?? []), ...(secondary.childrenTargetPaths ?? [])];
+    return {
+        ...(hasSearchTargetAncestor ? { hasSearchTargetAncestor } : undefined),
+        ...(childrenTargetPaths.length ? { childrenTargetPaths } : undefined),
+        ...(primary.isSearchTarget || secondary.isSearchTarget
+            ? {
+                isSearchTarget: true,
+                searchTargetOptions: HierarchySearchPath.mergeOptions(primary.isSearchTarget ? primary.searchTargetOptions : undefined, secondary.isSearchTarget ? secondary.searchTargetOptions : undefined),
+            }
+            : {
+                isSearchTarget: false,
+            }),
+    };
+}
+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)))) {
+        const searchProps = mergeSearchProps(primary.search, secondary.search);
+        return {
+            ...primary,
+            key: {
+                type: "instances",
+                instanceKeys: primary.key.instanceKeys.concat(secondary.key.instanceKeys),
+            },
+            ...(searchProps ? { search: searchProps } : undefined),
+        };
+    }
+    return undefined;
+}
+function tryMergeGenericNodes(primary, secondary) {
+    if (HierarchyNode.isGeneric(primary) && HierarchyNode.isGeneric(secondary) && primary.key.type === secondary.key.type) {
+        const searchProps = mergeSearchProps(primary.search, secondary.search);
+        return {
+            ...primary,
+            ...(searchProps ? { search: searchProps } : undefined),
+        };
+    }
+    return undefined;
+}
+function tryMergeNodes(primary, secondary) {
+    return tryMergeInstanceNodes(primary, secondary) ?? tryMergeGenericNodes(primary, secondary) ?? undefined;
+}
 //# sourceMappingURL=IModelHierarchyProvider.js.map