@itwin/presentation-hierarchies 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @itwin/presentation-hierarchies
+
+## 0.1.0
+
+### Minor Changes
+
+- [#584](https://github.com/iTwin/presentation/pull/584): Initial release.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @itwin/presentation-shared@0.2.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright © 2017-2024 Bentley Systems, Incorporated. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# @itwin/presentation-hierarchies
+
+Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.
+
+The `@itwin/presentation-hierarchies` package provides APIs for creating hierarchical data structures based on data in an [iTwin.js iModel](https://www.itwinjs.org/learning/imodels/#imodel-overview).
+
+## Basic concepts
+
+A hierarchy is an arrangement of items, called hierarchy nodes, which are represented as being "above", "below", or "at the same level as" one another:
+
+![Sample hierarchy](./media/sample-hierarchy.png)
+
+Here are definitions of some basic hierarchy-related concepts based on the above example:
+
+- A hierarchy node is an item in the hierarchy, e.g. `Node 0`, `Node 1`, `Node 1-0` etc.
+- A hierarchy level is a group of hierarchy nodes that are at the same level in the hierarchy. In the above example the root level contains `Node 0`, `Node 1` and `Node 2`. Child level of `Node 2` contains `Node 2-0`, `Node 2-1`.
+- A hierarchy branch is a sub-hierarchy under specific parent node, including the parent itself. In the above example, the branch of `Node 2` contains `Node 2`, `Node 2-0`, `Node 2-1` and `Node 2-1-0`.
+
+In the context of `@itwin/presentation-hierarchies` package, a hierarchy is built by requesting hierarchy levels from a [hierarchy provider](#hierarchy-provider). The provider knows how to create hierarchy levels based on the data in an iModel and a [hierarchy definition](#hierarchy-definition).
+
+### Hierarchy nodes
+
+A `HierarchyNode` interface in the package represents a single node in a hierarchy. It contains information about what the node represents in the iModel (through it's `key` property), label and other properties. There are multiple types of nodes:
+
+- A custom node is not based on any iModel data and is created by the application. Its `key` is a string.
+- An instances node is based on one or more ECInstance(s) in the iModel. Its `key` is an `InstancesNodeKey` and contains identifiers of those ECInstances.
+- A grouping node groups one or more instances nodes. Its `key` is a `GroupingNodeKey` and contains the grouping criteria, which depends on the type of grouping:
+  - Label grouping node keys have a label.
+  - Class grouping nodes have a full class name.
+  - Property grouping nodes have a full class name containing the property and property name. Also, depending on whether the grouping is based on value or a range of values, that information is also included.
+
+`HierarchyNode` and `HierarchyNodeKey` namespaces contain type guards and utility functions for working with hierarchy nodes and their keys.
+
+A `HierarchyNode` goes through several stages throughout its lifetime:
+
+1. A node starts its life as a `ParsedHierarchyNode` when it's initially parsed from ECSQL query results or returned by a [hierarchy definition](#hierarchy-definition) as a custom node. This variation has no information about its ancestors (position in the hierarchy) and may have unformatted label. Parsed nodes may only be custom or instances nodes.
+
+2. A node becomes a `ProcessedHierarchyNode` as soon as it starts being processed by a [hierarchy provider](#hierarchy-provider). During the processing, provider assigns a formatted label, handles node hiding, grouping, sorting and other operations. A [hierarchy definition](#hierarchy-definition) gets a chance to step into the process as well. In case of grouping, new grouping nodes may be created.
+
+3. Finally, all the processing-related information is cleaned up from `ProcessedHierarchyNode` and it becomes a `HierarchyNode`, which is what consumers get from a [hierarchy provider](#hierarchy-provider).
+
+### Hierarchy definition
+
+A hierarchy definition is what describes the hierarchy by defining what child nodes to return for a given parent node. In this package that is achieved though the `HierarchyDefinition` interface, which has one required method - `defineHierarchyLevel`. The method's responsibility is to create a `HierarchyLevelDefinition` for a given parent node. A `HierarchyLevelDefinition` is actually just a set of `HierarchyNodesDefinition` objects, which either describe a single custom node, or an ECSQL query that returns a number of ECInstance nodes. When `HierarchyLevelDefinition` consists of more than 1 `HierarchyNodesDefinition`, the hierarchy level is combined from multiple sets of nodes.
+
+In case of ECSQL queries for creating the hierarchy level, the definition may want to select some extra information and assign it to the nodes. For that purpose, there's an optional `HierarchyDefinition.parseNode` method, which lets the definition parse the query results handle those extra columns.
+
+Finally, the library also allows hierarchy definitions to step into nodes processing chain through the optional `preProcessNode` and `postProcessNode` methods. These methods are called before and after the node is processed by a [hierarchy provider](#hierarchy-provider) respectively and allow hiding and customizing nodes.
+
+In iTwin.js, the most common way to create hierarchies is based on EC data (schemas, classes, relationships) in iModels. To make consumers' life easier, the package provides an utility called `createClassBasedHierarchyDefinition`, which lets consumers define hierarchy levels based on parent nodes' class.
+
+### Hierarchy provider
+
+`HierarchyProvider` the core concept of the library - it's responsibility is to glue everything together, including evaluating hierarchy definition, running the queries, processing nodes and, finally, returning them to consumers. The package delivers the `createHierarchyProvider` function to create an instance of `HierarchyProvider`.
+
+## Basic usage
+
+Here's a simple example of how to create a hierarchy provider and build a hierarchy of Models and their Elements, with the latter grouped by class:
+
+```ts
+import { IModelConnection } from "@itwin/core-frontend";
+import { SchemaContext } from "@itwin/ecschema-metadata";
+import { ECSchemaRpcLocater } from "@itwin/ecschema-rpcinterface-common";
+import { createECSchemaProvider, createECSqlQueryExecutor } from "@itwin/presentation-core-interop";
+import {
+  createClassBasedHierarchyDefinition,
+  createHierarchyProvider,
+  createLimitingECSqlQueryExecutor,
+  createNodesQueryClauseFactory,
+  DefineInstanceNodeChildHierarchyLevelProps,
+  HierarchyNode,
+  HierarchyProvider,
+} from "@itwin/presentation-hierarchies";
+import { createBisInstanceLabelSelectClauseFactory, createCachingECClassHierarchyInspector, ECSqlBinding } from "@itwin/presentation-shared";
+
+// Not really part of the package, but we need SchemaContext to create a hierarchy provider. It's
+// recommended to cache the schema context and reuse it across different application's components to
+// avoid loading and storing same schemas multiple times.
+const imodelSchemaContextsCache = new Map<string, SchemaContext>();
+function getIModelSchemaContext(imodel: IModelConnection) {
+  let context = imodelSchemaContextsCache.get(imodel.key);
+  if (!context) {
+    context = new SchemaContext();
+    context.addLocater(new ECSchemaRpcLocater(imodel.getRpcProps()));
+    imodelSchemaContextsCache.set(imodel.key, context);
+    imodel.onClose.addListener(() => imodelSchemaContextsCache.delete(imodel.key));
+  }
+  return context;
+}
+
+function createProvider(imodel: IModelConnection): HierarchyProvider {
+  // First, set up access to the iModel
+  const schemaProvider = createECSchemaProvider(getIModelSchemaContext(imodel));
+  const imodelAccess = {
+    ...schemaProvider,
+    // while caching for hierarchy inspector is not mandatory, it's recommended to use it to improve performance
+    ...createCachingECClassHierarchyInspector({ schemaProvider, cacheSize: 100 }),
+    // the second argument is the maximum number of rows the executor will return - this allows us to
+    // avoid creating hierarchy levels of insane size (expensive to us and useless to users)
+    ...createLimitingECSqlQueryExecutor(createECSqlQueryExecutor(imodel), 1000),
+  };
+
+  // Create a factory for building nodes SELECT query clauses in a format understood by the provider
+  const nodesQueryFactory = createNodesQueryClauseFactory({ imodelAccess });
+  // Create a factory for building labels SELECT query clauses according to BIS conventions
+  const labelsQueryFactory = createBisInstanceLabelSelectClauseFactory({ classHierarchyInspector: imodelAccess });
+
+  // Then, define the hierarchy
+  const hierarchyDefinition = createClassBasedHierarchyDefinition({
+    classHierarchyInspector: imodelAccess,
+    hierarchy: {
+      // for root nodes, select all root level bis.Model instances
+      rootNodes: async () => [
+        {
+          fullClassName: "BisCore.Model",
+          query: {
+            ecsql: `
+              SELECT
+                ${await nodesQueryFactory.createSelectClause({
+                  ecClassId: { selector: "this.ECClassId" },
+                  ecInstanceId: { selector: "this.ECInstanceId" },
+                  nodeLabel: {
+                    selector: await labelsQueryFactory.createSelectClause({ classAlias: "this", className: "BisCore.Model" }),
+                  },
+                })}
+              FROM BisCore.Model this
+              WHERE this.ParentModel IS NULL
+            `,
+          },
+        },
+      ],
+      childNodes: [
+        {
+          // for bis.Model parent nodes, select all bis.Element instances contained in corresponding model
+          parentNodeClassName: "BisCore.Model",
+          definitions: async ({ parentNodeInstanceIds }: DefineInstanceNodeChildHierarchyLevelProps) => [
+            {
+              fullClassName: "BisCore.Element",
+              query: {
+                ecsql: `
+                  SELECT
+                    ${await nodesQueryFactory.createSelectClause({
+                      ecClassId: { selector: "this.ECClassId" },
+                      ecInstanceId: { selector: "this.ECInstanceId" },
+                      nodeLabel: {
+                        selector: await labelsQueryFactory.createSelectClause({ classAlias: "this", className: "BisCore.Element" }),
+                      },
+                      grouping: {
+                        byClass: true,
+                      },
+                    })}
+                  FROM BisCore.Element this
+                  WHERE this.Model.Id IN (${parentNodeInstanceIds.map(() => "?").join(",")})
+                `,
+                bindings: [...parentNodeInstanceIds.map((id): ECSqlBinding => ({ type: "id", value: id }))],
+              },
+            },
+          ],
+        },
+      ],
+    },
+  });
+
+  // Finally, create the provider
+  return createHierarchyProvider({ imodelAccess, hierarchyDefinition });
+}
+
+async function main() {
+  const provider = createProvider(/* pass your IModelConnection here */);
+  async function loadBranch(parentNode: HierarchyNode | undefined, indent: number = 0) {
+    for await (const node of provider.getNodes({ parentNode })) {
+      console.log(`${new Array(indent + 1).join(" ")} ${node.label}`);
+      await loadBranch(node);
+    }
+  }
+  await loadBranch(undefined);
+}
+```

package/lib/cjs/hierarchies/HierarchyDefinition.d.ts

@@ -0,0 +1,228 @@
+import { Id64String } from "@itwin/core-bentley";
+import { GenericInstanceFilter } from "@itwin/core-common";
+import { ECClassHierarchyInspector, ECSqlQueryDef } from "@itwin/presentation-shared";
+import { NonGroupingHierarchyNode, ParsedCustomHierarchyNode, ParsedInstanceHierarchyNode, ProcessedCustomHierarchyNode, ProcessedHierarchyNode, ProcessedInstanceHierarchyNode } from "./HierarchyNode";
+import { InstancesNodeKey } from "./HierarchyNodeKey";
+/**
+ * A nodes definition that returns a single custom defined node.
+ * @internal
+ */
+export interface CustomHierarchyNodeDefinition {
+    /** The node to be created in the hierarchy level */
+    node: ParsedCustomHierarchyNode;
+}
+/**
+ * A nodes definition that returns an ECSQL query for selecting nodes from an iModel.
+ * @internal
+ */
+export interface InstanceNodesQueryDefinition {
+    /**
+     * Full name of the class whose instances are going to be returned. It's okay if the attribute
+     * points to a base class of multiple different classes of instances returned by the query, however
+     * the more specific this class is, the more efficient hierarchy building process is.
+     */
+    fullClassName: string;
+    /**
+     * An ECSQL query that selects nodes from an iModel. `SELECT` clause of the query is expected
+     * to be built using `NodeSelectQueryFactory.createSelectClause`.
+     */
+    query: ECSqlQueryDef;
+}
+/**
+ * A definition of nodes included in a hierarchy level.
+ * @beta
+ */
+export type HierarchyNodesDefinition = CustomHierarchyNodeDefinition | InstanceNodesQueryDefinition;
+/** @beta */
+export declare namespace HierarchyNodesDefinition {
+    function isCustomNode(def: HierarchyNodesDefinition): def is CustomHierarchyNodeDefinition;
+    function isInstanceNodesQuery(def: HierarchyNodesDefinition): def is InstanceNodesQueryDefinition;
+}
+/**
+ * A definition of a hierarchy level, which may consist of multiple node definitions.
+ * @beta
+ */
+export type HierarchyLevelDefinition = HierarchyNodesDefinition[];
+/**
+ * A type for a function that parses a `ParsedInstanceHierarchyNode` from provided ECSQL `row` object.
+ * @beta
+ */
+export type NodeParser = (row: {
+    [columnName: string]: any;
+}) => ParsedInstanceHierarchyNode;
+/**
+ * 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
+ * from the hierarchy.
+ *
+ * @beta
+ */
+export type NodePreProcessor = <TNode extends ProcessedCustomHierarchyNode | ProcessedInstanceHierarchyNode>(node: TNode) => Promise<TNode | undefined>;
+/**
+ * A type for a function that post-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.
+ *
+ * @beta
+ */
+export type NodePostProcessor = (node: ProcessedHierarchyNode) => Promise<ProcessedHierarchyNode>;
+/**
+ * A type of node that can be passed to `HierarchyDefinition.defineHierarchyLevel`. This basically means
+ * a `HierarchyNode` that:
+ * - knows nothing about its children,
+ * - is either an instances node (key is of `InstancesNodeKey` type) or a custom node (key is of `string` type).
+ */
+type HierarchyDefinitionParentNode = Omit<NonGroupingHierarchyNode, "children">;
+/**
+ * Props for `HierarchyDefinition.defineHierarchyLevel`.
+ * @beta
+ */
+export interface DefineHierarchyLevelProps {
+    /** Parent node to get children for. Pass `undefined` to get root nodes. */
+    parentNode: HierarchyDefinitionParentNode | undefined;
+    /** Optional hierarchy level filter. */
+    instanceFilter?: GenericInstanceFilter;
+}
+/**
+ * An interface for a factory that knows how define a hierarchy based on a given parent node.
+ * @beta
+ */
+export interface HierarchyDefinition {
+    /**
+     * An optional function for parsing ECInstance node from ECSQL row.
+     *
+     * Should be used in situations when the `HierarchyDefinition` implementation
+     * introduces additional ECSQL columns into the select clause and wants to assign additional
+     * data to the nodes it produces.
+     *
+     * Defaults to a function that parses all `HierarchyNode` attributes from a query, whose SELECT
+     * clause is created using `NodeSelectQueryFactory.createSelectClause`.
+     */
+    parseNode?: NodeParser;
+    /**
+     * An optional function for pre-processing nodes.
+     *
+     * Pre-processing happens immediately after the nodes are loaded based on `HierarchyLevelDefinition`
+     * returned by this `HierarchyDefinition` and before their processing (hiding, grouping, sorting, etc.) starts.
+     * The step allows assigning nodes additional data or excluding them from the hierarchy based on some attributes.
+     */
+    preProcessNode?: NodePreProcessor;
+    /**
+     * An optional function for post-processing nodes.
+     *
+     * Post-processing happens after the loaded nodes go through all the merging, hiding and grouping
+     * steps, but before sorting them. This step allows `HierarchyDefinition` implementations to assign additional data
+     * to nodes after they're processed. This is especially true for grouping nodes as they're only created during
+     * processing.
+     */
+    postProcessNode?: NodePostProcessor;
+    /** A function to create a hierarchy level definition for given parent node. */
+    defineHierarchyLevel(props: DefineHierarchyLevelProps): Promise<HierarchyLevelDefinition>;
+}
+/**
+ * Props for defining child hierarchy level for specific parent instance node.
+ * @see `createClassBasedHierarchyDefinition`
+ * @beta
+ */
+export type DefineInstanceNodeChildHierarchyLevelProps = Omit<DefineHierarchyLevelProps, "parentNode"> & {
+    /** The parent instance node. */
+    parentNode: Omit<HierarchyDefinitionParentNode, "key"> & {
+        key: InstancesNodeKey;
+    };
+    /**
+     * Full name of the parent instance node class.
+     *
+     * The `parentNode.key` also contains information about the instances the parent node is based on. However,
+     * an instance node may be based on instances of multiple classes. In case that happens, parent node's instance
+     * keys are grouped by class and a hierarchy level definition is requested for each combination of class and
+     * instance IDs (with the same `parentNode`).
+     */
+    parentNodeClassName: string;
+    /**
+     * ECInstanceIds of the parent instance node.
+     *
+     * The `parentNode.key` also contains information about the instances the parent node is based on. However,
+     * an instance node may be based on instances of multiple classes. In case that happens, parent node's instance
+     * keys are grouped by class and a hierarchy level definition is requested for each combination of class and
+     * instance IDs (with the same `parentNode`).
+     */
+    parentNodeInstanceIds: Id64String[];
+};
+/**
+ * A definition of a hierarchy level that should be used for specific class of parent instance nodes.
+ */
+interface InstancesNodeChildHierarchyLevelDefinition {
+    /**
+     * Full name of the parent instance node's class to match against when checking if this hierarchy
+     * level should be used for specific parent instance node.
+     *
+     * The check is polymorphic, so `BisCore.Element` class would match `BisCore.GeometricElement`, `BisCore.Category` and
+     * all other element classes.
+     */
+    parentNodeClassName: string;
+    /**
+     * Called to create a hierarchy level definition when the class check passes (see `parentNodeClassName`).
+     */
+    definitions: (requestProps: DefineInstanceNodeChildHierarchyLevelProps) => Promise<HierarchyLevelDefinition>;
+}
+/**
+ * Props for defining child hierarchy level for specific parent custom node.
+ * @see `createClassBasedHierarchyDefinition`
+ * @beta
+ */
+export type DefineCustomNodeChildHierarchyLevelProps = Omit<DefineHierarchyLevelProps, "parentNode"> & {
+    /** The parent custom node. */
+    parentNode: Omit<HierarchyDefinitionParentNode, "key"> & {
+        key: string;
+    };
+};
+/**
+ * A definition of a hierarchy level for that should be used for specific custom parent nodes.
+ */
+interface CustomNodeChildHierarchyLevelDefinition {
+    /**
+     * `HierarchyNode.key` of the custom node that this child hierarchy level definition should be used for.
+     */
+    customParentNodeKey: string;
+    /**
+     * Called to create a hierarchy level definition when the node key check passes (see `customParentNodeKey`).
+     */
+    definitions: (requestProps: DefineCustomNodeChildHierarchyLevelProps) => Promise<HierarchyLevelDefinition>;
+}
+/**
+ * A hierarchy level definition associated with either parent instance node's class or custom
+ * node's key.
+ */
+type ClassBasedHierarchyLevelDefinition = InstancesNodeChildHierarchyLevelDefinition | CustomNodeChildHierarchyLevelDefinition;
+/**
+ * Props for defining root hierarchy level.
+ * @see `createClassBasedHierarchyDefinition`
+ * @beta
+ */
+export type DefineRootHierarchyLevelProps = Omit<DefineHierarchyLevelProps, "parentNode">;
+/**
+ * Props for `createClassBasedHierarchyDefinition`.
+ */
+interface ClassBasedHierarchyDefinitionProps {
+    /** Access to ECClass hierarchy in the iModel */
+    classHierarchyInspector: ECClassHierarchyInspector;
+    /** Hierarchy level definitions based on parent instance node's class or custom node's key. */
+    hierarchy: {
+        /** Called to create the root hierarchy level definition. */
+        rootNodes: (props: DefineRootHierarchyLevelProps) => Promise<HierarchyLevelDefinition>;
+        /**
+         * Called to get child hierarchy level definitions based on parent instance node's class
+         * or custom node's key.
+         */
+        childNodes: ClassBasedHierarchyLevelDefinition[];
+    };
+}
+/**
+ * Creates an instance of `HierarchyDefinition` that uses a somewhat declarative approach to define the
+ * hierarchy - each hierarchy level is assigned either an instance node's class or custom node's
+ * key and they're used to assign hierarchy level definitions based on parent node.
+ *
+ * @beta
+ */
+export declare function createClassBasedHierarchyDefinition(props: ClassBasedHierarchyDefinitionProps): HierarchyDefinition;
+export {};
+//# sourceMappingURL=HierarchyDefinition.d.ts.map

package/lib/cjs/hierarchies/HierarchyDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyDefinition.d.ts","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyDefinition.ts"],"names":[],"mappings":"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"}

package/lib/cjs/hierarchies/HierarchyDefinition.js

@@ -0,0 +1,94 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClassBasedHierarchyDefinition = exports.HierarchyNodesDefinition = void 0;
+const HierarchyNode_1 = require("./HierarchyNode");
+/** @beta */
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+var HierarchyNodesDefinition;
+(function (HierarchyNodesDefinition) {
+    function isCustomNode(def) {
+        return !!def.node;
+    }
+    HierarchyNodesDefinition.isCustomNode = isCustomNode;
+    function isInstanceNodesQuery(def) {
+        return !!def.query;
+    }
+    HierarchyNodesDefinition.isInstanceNodesQuery = isInstanceNodesQuery;
+})(HierarchyNodesDefinition || (exports.HierarchyNodesDefinition = HierarchyNodesDefinition = {}));
+/**
+ * Creates an instance of `HierarchyDefinition` that uses a somewhat declarative approach to define the
+ * hierarchy - each hierarchy level is assigned either an instance node's class or custom node's
+ * key and they're used to assign hierarchy level definitions based on parent node.
+ *
+ * @beta
+ */
+function createClassBasedHierarchyDefinition(props) {
+    return new ClassBasedHierarchyDefinition(props);
+}
+exports.createClassBasedHierarchyDefinition = createClassBasedHierarchyDefinition;
+class ClassBasedHierarchyDefinition {
+    _props;
+    constructor(_props) {
+        this._props = _props;
+    }
+    /**
+     * Create hierarchy level definitions for specific hierarchy level.
+     * @param parentNode Parent node to create children definitions for.
+     */
+    async defineHierarchyLevel(props) {
+        const { parentNode } = props;
+        if (!parentNode) {
+            return this._props.hierarchy.rootNodes(props);
+        }
+        if (HierarchyNode_1.HierarchyNode.isCustom(parentNode)) {
+            const defs = this._props.hierarchy.childNodes
+                .filter(isCustomNodeChildHierarchyLevelDefinition)
+                .filter((def) => def.customParentNodeKey === parentNode.key);
+            return (await Promise.all(defs.map(async (def) => def.definitions({ ...props, parentNode })))).flat();
+        }
+        // istanbul ignore else
+        if (HierarchyNode_1.HierarchyNode.isInstancesNode(parentNode)) {
+            const instanceIdsByClass = groupInstanceIdsByClass(parentNode.key.instanceKeys);
+            const instancesParentNodeDefs = this._props.hierarchy.childNodes.filter(isInstancesNodeChildHierarchyLevelDefinition);
+            return (await Promise.all([...instanceIdsByClass.entries()].map(async ([parentNodeClassName, parentNodeInstanceIds]) => createHierarchyLevelDefinitions(this._props.classHierarchyInspector, instancesParentNodeDefs, {
+                ...props,
+                parentNodeClassName,
+                parentNodeInstanceIds,
+                parentNode,
+            })))).flat();
+        }
+        // istanbul ignore next
+        return [];
+    }
+}
+async function createHierarchyLevelDefinitions(classHierarchy, defs, requestProps) {
+    return (await Promise.all(defs.map(async (def) => {
+        if (await classHierarchy.classDerivesFrom(requestProps.parentNodeClassName, def.parentNodeClassName)) {
+            return def.definitions(requestProps);
+        }
+        return [];
+    }))).flat();
+}
+function groupInstanceIdsByClass(instanceKeys) {
+    const instanceIdsByClass = new Map();
+    instanceKeys.forEach((key) => {
+        let instanceIds = instanceIdsByClass.get(key.className);
+        if (!instanceIds) {
+            instanceIds = [];
+            instanceIdsByClass.set(key.className, instanceIds);
+        }
+        instanceIds.push(key.id);
+    });
+    return instanceIdsByClass;
+}
+function isCustomNodeChildHierarchyLevelDefinition(def) {
+    return !!def.customParentNodeKey;
+}
+function isInstancesNodeChildHierarchyLevelDefinition(def) {
+    return !!def.parentNodeClassName;
+}
+//# sourceMappingURL=HierarchyDefinition.js.map

package/lib/cjs/hierarchies/HierarchyDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyDefinition.js","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyDefinition.ts"],"names":[],"mappings":"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","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 { Id64String } from \"@itwin/core-bentley\";\nimport { GenericInstanceFilter } from \"@itwin/core-common\";\nimport { ECClassHierarchyInspector, ECSqlQueryDef, InstanceKey } from \"@itwin/presentation-shared\";\nimport {\n  HierarchyNode,\n  NonGroupingHierarchyNode,\n  ParsedCustomHierarchyNode,\n  ParsedInstanceHierarchyNode,\n  ProcessedCustomHierarchyNode,\n  ProcessedHierarchyNode,\n  ProcessedInstanceHierarchyNode,\n} from \"./HierarchyNode\";\nimport { InstancesNodeKey } from \"./HierarchyNodeKey\";\n\n/**\n * A nodes definition that returns a single custom defined node.\n * @internal\n */\nexport interface CustomHierarchyNodeDefinition {\n  /** The node to be created in the hierarchy level */\n  node: ParsedCustomHierarchyNode;\n}\n\n/**\n * A nodes definition that returns an ECSQL query for selecting nodes from an iModel.\n * @internal\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 * @beta\n */\nexport type HierarchyNodesDefinition = CustomHierarchyNodeDefinition | InstanceNodesQueryDefinition;\n/** @beta */\n// eslint-disable-next-line @typescript-eslint/no-redeclare\nexport namespace HierarchyNodesDefinition {\n  export function isCustomNode(def: HierarchyNodesDefinition): def is CustomHierarchyNodeDefinition {\n    return !!(def as CustomHierarchyNodeDefinition).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 * @beta\n */\nexport type HierarchyLevelDefinition = HierarchyNodesDefinition[];\n\n/**\n * A type for a function that parses a `ParsedInstanceHierarchyNode` from provided ECSQL `row` object.\n * @beta\n */\nexport type NodeParser = (row: { [columnName: string]: any }) => ParsedInstanceHierarchyNode;\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 * @beta\n */\nexport type NodePreProcessor = <TNode extends ProcessedCustomHierarchyNode | 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 * @beta\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 custom node (key is of `string` type).\n */\ntype HierarchyDefinitionParentNode = Omit<NonGroupingHierarchyNode, \"children\">;\n\n/**\n * Props for `HierarchyDefinition.defineHierarchyLevel`.\n * @beta\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 * @beta\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\n/**\n * Props for defining child hierarchy level for specific parent instance node.\n * @see `createClassBasedHierarchyDefinition`\n * @beta\n */\nexport type DefineInstanceNodeChildHierarchyLevelProps = Omit<DefineHierarchyLevelProps, \"parentNode\"> & {\n  /** The parent instance node. */\n  parentNode: Omit<HierarchyDefinitionParentNode, \"key\"> & { key: InstancesNodeKey };\n\n  /**\n   * Full name of the parent instance node class.\n   *\n   * The `parentNode.key` also contains information about the instances the parent node is based on. However,\n   * an instance node may be based on instances of multiple classes. In case that happens, parent node's instance\n   * keys are grouped by class and a hierarchy level definition is requested for each combination of class and\n   * instance IDs (with the same `parentNode`).\n   */\n  parentNodeClassName: string;\n\n  /**\n   * ECInstanceIds of the parent instance node.\n   *\n   * The `parentNode.key` also contains information about the instances the parent node is based on. However,\n   * an instance node may be based on instances of multiple classes. In case that happens, parent node's instance\n   * keys are grouped by class and a hierarchy level definition is requested for each combination of class and\n   * instance IDs (with the same `parentNode`).\n   */\n  parentNodeInstanceIds: Id64String[];\n};\n\n/**\n * A definition of a hierarchy level that should be used for specific class of parent instance nodes.\n */\ninterface InstancesNodeChildHierarchyLevelDefinition {\n  /**\n   * Full name of the parent instance node's class to match against when checking if this hierarchy\n   * level should be used for specific parent instance node.\n   *\n   * The check is polymorphic, so `BisCore.Element` class would match `BisCore.GeometricElement`, `BisCore.Category` and\n   * all other element classes.\n   */\n  parentNodeClassName: string;\n\n  /**\n   * Called to create a hierarchy level definition when the class check passes (see `parentNodeClassName`).\n   */\n  definitions: (requestProps: DefineInstanceNodeChildHierarchyLevelProps) => Promise<HierarchyLevelDefinition>;\n}\n\n/**\n * Props for defining child hierarchy level for specific parent custom node.\n * @see `createClassBasedHierarchyDefinition`\n * @beta\n */\nexport type DefineCustomNodeChildHierarchyLevelProps = Omit<DefineHierarchyLevelProps, \"parentNode\"> & {\n  /** The parent custom node. */\n  parentNode: Omit<HierarchyDefinitionParentNode, \"key\"> & { key: string };\n};\n\n/**\n * A definition of a hierarchy level for that should be used for specific custom parent nodes.\n */\ninterface CustomNodeChildHierarchyLevelDefinition {\n  /**\n   * `HierarchyNode.key` of the custom node that this child hierarchy level definition should be used for.\n   */\n  customParentNodeKey: string;\n\n  /**\n   * Called to create a hierarchy level definition when the node key check passes (see `customParentNodeKey`).\n   */\n  definitions: (requestProps: DefineCustomNodeChildHierarchyLevelProps) => Promise<HierarchyLevelDefinition>;\n}\n\n/**\n * A hierarchy level definition associated with either parent instance node's class or custom\n * node's key.\n */\ntype ClassBasedHierarchyLevelDefinition = InstancesNodeChildHierarchyLevelDefinition | CustomNodeChildHierarchyLevelDefinition;\n\n/**\n * Props for defining root hierarchy level.\n * @see `createClassBasedHierarchyDefinition`\n * @beta\n */\nexport type DefineRootHierarchyLevelProps = Omit<DefineHierarchyLevelProps, \"parentNode\">;\n\n/**\n * Props for `createClassBasedHierarchyDefinition`.\n */\ninterface ClassBasedHierarchyDefinitionProps {\n  /** Access to ECClass hierarchy in the iModel */\n  classHierarchyInspector: ECClassHierarchyInspector;\n\n  /** Hierarchy level definitions based on parent instance node's class or custom node's key. */\n  hierarchy: {\n    /** Called to create the root hierarchy level definition. */\n    rootNodes: (props: DefineRootHierarchyLevelProps) => Promise<HierarchyLevelDefinition>;\n\n    /**\n     * Called to get child hierarchy level definitions based on parent instance node's class\n     * or custom node's key.\n     */\n    childNodes: ClassBasedHierarchyLevelDefinition[];\n  };\n}\n\n/**\n * Creates an instance of `HierarchyDefinition` that uses a somewhat declarative approach to define the\n * hierarchy - each hierarchy level is assigned either an instance node's class or custom node's\n * key and they're used to assign hierarchy level definitions based on parent node.\n *\n * @beta\n */\nexport function createClassBasedHierarchyDefinition(props: ClassBasedHierarchyDefinitionProps): HierarchyDefinition {\n  return new ClassBasedHierarchyDefinition(props);\n}\n\nclass ClassBasedHierarchyDefinition implements HierarchyDefinition {\n  public constructor(private _props: ClassBasedHierarchyDefinitionProps) {}\n\n  /**\n   * Create hierarchy level definitions for specific hierarchy level.\n   * @param parentNode Parent node to create children definitions for.\n   */\n  public async defineHierarchyLevel(props: DefineHierarchyLevelProps): Promise<HierarchyLevelDefinition> {\n    const { parentNode } = props;\n    if (!parentNode) {\n      return this._props.hierarchy.rootNodes(props);\n    }\n\n    if (HierarchyNode.isCustom(parentNode)) {\n      const defs = this._props.hierarchy.childNodes\n        .filter(isCustomNodeChildHierarchyLevelDefinition)\n        .filter((def) => def.customParentNodeKey === parentNode.key);\n      return (await Promise.all(defs.map(async (def) => def.definitions({ ...props, parentNode })))).flat();\n    }\n\n    // istanbul ignore else\n    if (HierarchyNode.isInstancesNode(parentNode)) {\n      const instanceIdsByClass = groupInstanceIdsByClass(parentNode.key.instanceKeys);\n      const instancesParentNodeDefs = this._props.hierarchy.childNodes.filter(isInstancesNodeChildHierarchyLevelDefinition);\n      return (\n        await Promise.all(\n          [...instanceIdsByClass.entries()].map(async ([parentNodeClassName, parentNodeInstanceIds]) =>\n            createHierarchyLevelDefinitions(this._props.classHierarchyInspector, instancesParentNodeDefs, {\n              ...props,\n              parentNodeClassName,\n              parentNodeInstanceIds,\n              parentNode,\n            }),\n          ),\n        )\n      ).flat();\n    }\n\n    // istanbul ignore next\n    return [];\n  }\n}\n\nasync function createHierarchyLevelDefinitions(\n  classHierarchy: ECClassHierarchyInspector,\n  defs: InstancesNodeChildHierarchyLevelDefinition[],\n  requestProps: DefineInstanceNodeChildHierarchyLevelProps,\n) {\n  return (\n    await Promise.all(\n      defs.map(async (def) => {\n        if (await classHierarchy.classDerivesFrom(requestProps.parentNodeClassName, def.parentNodeClassName)) {\n          return def.definitions(requestProps);\n        }\n        return [];\n      }),\n    )\n  ).flat();\n}\n\nfunction groupInstanceIdsByClass(instanceKeys: InstanceKey[]) {\n  const instanceIdsByClass = new Map<string, Id64String[]>();\n  instanceKeys.forEach((key) => {\n    let instanceIds = instanceIdsByClass.get(key.className);\n    if (!instanceIds) {\n      instanceIds = [];\n      instanceIdsByClass.set(key.className, instanceIds);\n    }\n    instanceIds.push(key.id);\n  });\n  return instanceIdsByClass;\n}\n\nfunction isCustomNodeChildHierarchyLevelDefinition(def: ClassBasedHierarchyLevelDefinition): def is CustomNodeChildHierarchyLevelDefinition {\n  return !!(def as CustomNodeChildHierarchyLevelDefinition).customParentNodeKey;\n}\n\nfunction isInstancesNodeChildHierarchyLevelDefinition(def: ClassBasedHierarchyLevelDefinition): def is InstancesNodeChildHierarchyLevelDefinition {\n  return !!(def as InstancesNodeChildHierarchyLevelDefinition).parentNodeClassName;\n}\n"]}

package/lib/cjs/hierarchies/HierarchyErrors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error that is thrown when rows amount exceed hierarchy level limit.
+ * @beta
+ */
+export declare class RowsLimitExceededError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+//# sourceMappingURL=HierarchyErrors.d.ts.map

package/lib/cjs/hierarchies/HierarchyErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyErrors.d.ts","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyErrors.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aACZ,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAGjD"}

package/lib/cjs/hierarchies/HierarchyErrors.js

@@ -0,0 +1,20 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RowsLimitExceededError = void 0;
+/**
+ * Error that is thrown when rows amount exceed hierarchy level limit.
+ * @beta
+ */
+class RowsLimitExceededError extends Error {
+    limit;
+    constructor(limit) {
+        super(`Query rows limit of ${limit} exceeded`);
+        this.limit = limit;
+    }
+}
+exports.RowsLimitExceededError = RowsLimitExceededError;
+//# sourceMappingURL=HierarchyErrors.js.map

package/lib/cjs/hierarchies/HierarchyErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HierarchyErrors.js","sourceRoot":"","sources":["../../../src/hierarchies/HierarchyErrors.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAEhG;;;GAGG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IACZ;IAAnC,YAAmC,KAAa;QAC9C,KAAK,CAAC,uBAAuB,KAAK,WAAW,CAAC,CAAC;QADd,UAAK,GAAL,KAAK,CAAQ;IAEhD,CAAC;CACF;AAJD,wDAIC","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\n/**\n * Error that is thrown when rows amount exceed hierarchy level limit.\n * @beta\n */\nexport class RowsLimitExceededError extends Error {\n  public constructor(public readonly limit: number) {\n    super(`Query rows limit of ${limit} exceeded`);\n  }\n}\n"]}