@react-hive/honey-utils 3.21.0 → 3.23.0

package/dist/tree/flatten-tree.d.ts

@@ -0,0 +1,48 @@
+import type { KeysWithArrayValues, KeysWithNonArrayValues } from '~/types';
+import type { HoneyTreeFlatNode } from '~/tree';
+/**
+ * Flattens a hierarchical tree into a single preorder array.
+ *
+ * Each node in the returned list is stripped of its nested children property
+ * (`childrenKey`) and enriched with hierarchy metadata:
+ *
+ * - `parentId` — identifier of the parent node (`undefined` for roots)
+ * - `depthLevel` — nesting depth starting at `0`
+ * - `childCount` — number of direct child nodes
+ *
+ * The flattening order is **preorder**, meaning parents always appear before
+ * their descendants. This representation is especially useful for rendering
+ * tree-based UIs such as TreeSelect components, nested menus, and folder pickers.
+ *
+ * @template OriginItem - Original node shape of the hierarchical structure.
+ *
+ * @param items - Root-level nodes to flatten. If undefined, an empty array is returned.
+ * @param nodeIdKey - Key that uniquely identifies each node.
+ * @param childrenKey - Key containing the nested child node array.
+ *
+ * @param flatTree - Internal accumulator used during recursion.
+ * @param parentId - Parent identifier for the current recursion level.
+ * @param depthLevel - Current depth level, where `0` represents the root.
+ *
+ * @returns A flat preorder list of tree nodes with hierarchy metadata attached,
+ *          excluding the original children property.
+ *
+ * @example
+ * ```ts
+ * const tree = [
+ *   {
+ *     id: 1,
+ *     name: 'Root',
+ *     children: [{ id: 2, name: 'Child', children: [] }],
+ *   },
+ * ];
+ *
+ * const flatTree = flattenTree(tree, 'id', 'children');
+ *
+ * // [
+ * //   { id: 1, name: 'Root', parentId: undefined, depthLevel: 0, childCount: 1 },
+ * //   { id: 2, name: 'Child', parentId: 1, depthLevel: 1, childCount: 0 }
+ * // ]
+ * ```
+ */
+export declare const flattenTree: <OriginItem extends object>(items: OriginItem[] | undefined, nodeIdKey: KeysWithNonArrayValues<OriginItem>, childrenKey: KeysWithArrayValues<OriginItem>, flatTree?: HoneyTreeFlatNode<OriginItem, typeof childrenKey>[], parentId?: OriginItem[KeysWithNonArrayValues<OriginItem>] | undefined, depthLevel?: number) => HoneyTreeFlatNode<OriginItem, typeof childrenKey>[];

package/dist/tree/get-tree-children.d.ts

@@ -0,0 +1,41 @@
+import type { KeysWithNonArrayValues } from '~/types';
+import type { HoneyTreeFlatNode } from '~/tree';
+/**
+ * Returns the direct children of a given parent node from a flattened tree.
+ *
+ * This helper filters a flat tree representation (`HoneyTreeFlatNode`) and
+ * selects only nodes whose `parentId` matches the provided identifier.
+ *
+ * ⚠️ Only direct children are returned - descendants at deeper levels are not included.
+ *
+ * An optional predicate may be provided to further narrow the result set
+ * (e.g. filtering by depth, type, or custom node flags).
+ *
+ * @template OriginItem - Original node shape of the hierarchical structure.
+ * @template ChildrenKey - Key of the removed nested children property.
+ *
+ * @param flatTree - Flat preorder list of tree nodes containing hierarchy metadata.
+ * @param parentId - Identifier of the parent node whose direct children should be returned.
+ * @param predicate - Optional additional filter applied to each matched child node.
+ *
+ * @returns An array of nodes that are direct children of the specified parent.
+ *
+ * @example
+ * ```ts
+ * const children = getTreeChildren(flatTree, 1);
+ *
+ * // Returns all nodes where parentId === 1
+ * ```
+ *
+ * @example
+ * ```ts
+ * const shallowChildren = getTreeChildren(
+ *   flatTree,
+ *   1,
+ *   node => node.depthLevel <= 2,
+ * );
+ *
+ * // Returns only children of node 1 that satisfy the predicate.
+ * ```
+ */
+export declare const getTreeChildren: <OriginItem extends object, ChildrenKey extends string>(flatTree: HoneyTreeFlatNode<OriginItem, ChildrenKey>[], parentId: OriginItem[KeysWithNonArrayValues<OriginItem>], predicate?: (node: HoneyTreeFlatNode<OriginItem, ChildrenKey>) => boolean) => HoneyTreeFlatNode<OriginItem, ChildrenKey>[];

package/dist/tree/index.d.ts

@@ -0,0 +1,4 @@
+export * from './tree.types';
+export * from './flatten-tree';
+export * from './get-tree-children';
+export * from './search-tree';

package/dist/tree/search-tree.d.ts

@@ -0,0 +1,54 @@
+import type { KeysWithNonArrayValues, KeysWithStringValues } from '~/types';
+import type { HoneyTreeFlatNode } from '~/tree';
+/**
+ * Performs a context-aware search over a flattened tree.
+ *
+ * Matching is applied to the provided string field (`nodeValueKey`) using
+ * **case-insensitive, word-prefix comparison**:
+ *
+ * - The query is split into words
+ * - Each query word must match the start of at least one word in the node value
+ *
+ * Unlike a simple filter, this function preserves hierarchical context:
+ *
+ * - When a nested node matches, all of its ancestor nodes are included, so the
+ *   result remains navigable.
+ * - When a root node matches, its full descendant subtree is included so the
+ *   hierarchy stays intact.
+ *
+ * This makes the utility ideal for searchable tree-based UIs such as
+ * TreeSelect components, folder pickers, nested menus, and grouped lists.
+ *
+ * @template OriginItem - Original node shape of the hierarchical structure.
+ * @template ChildrenKey - Key of the removed nested children property.
+ *
+ * @param flatTree - Flat preorder list of tree nodes containing hierarchy metadata.
+ * @param nodeIdKey - Key that uniquely identifies each node.
+ * @param nodeValueKey - Key containing the searchable string value (e.g. `"name"`).
+ * @param searchQuery - User input query. Split into words and matched by prefix.
+ *
+ * @returns A filtered flat list containing:
+ * - all matching nodes
+ * - their ancestor chain (for nested matches)
+ * - full descendant subtrees (for root-level matches)
+ *
+ * @example
+ * ```ts
+ * const results = searchTree(flatTree, 'id', 'label', 'kit che');
+ *
+ * // Matches nodes where words start with "kit" and "che"
+ * // (e.g. "Kitchen Chair"), including their parents.
+ * ```
+ *
+ * @example
+ * ```ts
+ * // If a deep child matches, ancestors are included:
+ * //
+ * // Root
+ * // └─ Category
+ * //    └─ Item ← matches
+ * //
+ * // Result includes: Root, Category, Item
+ * ```
+ */
+export declare const searchTree: <OriginItem extends object, ChildrenKey extends string>(flatTree: HoneyTreeFlatNode<OriginItem, ChildrenKey>[], nodeIdKey: KeysWithNonArrayValues<OriginItem>, nodeValueKey: KeysWithStringValues<OriginItem>, searchQuery: string) => HoneyTreeFlatNode<OriginItem, ChildrenKey>[];

package/dist/tree/tree.types.d.ts

@@ -0,0 +1,40 @@
+import type { KeysWithNonArrayValues } from '~/types';
+/**
+ * A flattened representation of a node from a hierarchical tree structure.
+ *
+ * This type is produced when converting nested data (e.g. folders, categories,
+ * grouped lists) into a flat array while preserving hierarchy metadata.
+ *
+ * The original nested children property (`ChildrenKey`) is removed, and each node is augmented with:
+ *  - `parentId` — reference to the parent node (undefined for root nodes).
+ *  - `depthLevel` — nesting depth, starting at `0`.
+ *  - `childCount` — number of direct child nodes.
+ *
+ * This structure is ideal for rendering tree-based UIs (TreeSelect, menus, expandable lists)
+ * and for performing operations such as searching, filtering, or reconstructing parent-child relationships.
+ *
+ * @template OriginItem - The original node shape from the hierarchical structure.
+ * @template ChildrenKey - Key of the property that contains nested child nodes.
+ */
+export type HoneyTreeFlatNode<OriginItem extends object, ChildrenKey extends string> = Omit<OriginItem, ChildrenKey> & {
+    /**
+     * Identifier of the parent node in the flattened structure.
+     *
+     * Root-level nodes have `parentId` set to `undefined`.
+     */
+    parentId: OriginItem[KeysWithNonArrayValues<OriginItem>] | undefined;
+    /**
+     * Depth of the node within the hierarchy.
+     *
+     * - `0` → root level
+     * - `1` → direct child
+     * - `2+` → deeper descendants
+     */
+    depthLevel: number;
+    /**
+     * Number of direct nested child nodes contained within this node.
+     *
+     * This value is `0` for leaf nodes.
+     */
+    childCount: number;
+};

package/dist/types.d.ts

@@ -1,2 +1,69 @@
 export type Nullable<T> = T | null;
 export type TimeoutId = ReturnType<typeof setTimeout>;
+/**
+ * Extracts the keys from a given type `T` whose values match the specified `Condition`.
+ *
+ * @template T - The object type from which to extract keys.
+ * @template Condition - The condition that the type of the values must satisfy to be included.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string; b: number; c: boolean };
+ * type StringKeys = ExtractKeys<Example, string>; // "a"
+ * ```
+ */
+type ExtractKeys<T, Condition> = {
+    [K in keyof T]: T[K] extends Condition ? K : never;
+}[keyof T];
+/**
+ * Excludes the keys from a given type `T` whose values match the specified `Condition`.
+ *
+ * @template T - The object type from which to exclude keys.
+ * @template Condition - The condition that the type of the values must satisfy to be excluded.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string; b: number; c: boolean };
+ * type NonNumberKeys = ExcludeKeys<Example, number>; // "a" | "c"
+ * ```
+ */
+type ExcludeKeys<T, Condition> = {
+    [K in keyof T]: T[K] extends Condition ? never : K;
+}[keyof T];
+/**
+ * Extracts the keys from a given type `T` where the values are `string`, `null`, or `undefined`.
+ *
+ * @template T - The object type from which to extract string-related keys.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string; b: number; c: string | null };
+ * type StringKeys = KeysWithStringValues<Example>; // "a" | "c"
+ * ```
+ */
+export type KeysWithStringValues<T> = Extract<ExtractKeys<T, string | null | undefined>, string>;
+/**
+ * Extracts the keys from a given type `T` where the values are arrays (`unknown[]`), `null`, or `undefined`.
+ *
+ * @template T - The object type from which to extract array-related keys.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string[]; b: number; c: number[] | null };
+ * type ArrayKeys = KeysWithArrayValues<Example>; // "a" | "c"
+ * ```
+ */
+export type KeysWithArrayValues<T> = Extract<ExtractKeys<T, unknown[] | null | undefined>, string>;
+/**
+ * Extracts the keys from a given type `T` where the values are **not** arrays (`unknown[]`), `null`, or `undefined`.
+ *
+ * @template T - The object type from which to extract non-array keys.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string; b: number; c: string[]; d: null };
+ * type NonArrayKeys = KeysWithNonArrayValues<Example>; // "a" | "b"
+ * ```
+ */
+export type KeysWithNonArrayValues<T> = Extract<ExcludeKeys<T, unknown[] | null | undefined>, string>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-hive/honey-utils",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "description": "A lightweight TypeScript utility library providing a collection of helper functions for common programming tasks",
   "keywords": [
     "utils",
@@ -22,7 +22,7 @@
     "type": "git",
     "url": "git+ssh://git@github.com/React-Hive/honey-utils.git"
   },
-  "author": "Mykhailo Aliinyk <m.aliynik@gmail.com>",
+  "author": "Mike Aliinyk <m.aliynik@gmail.com>",
   "license": "MIT",
   "scripts": {
     "build": "webpack --config webpack.config.mjs",