@dereekb/util 12.1.0 → 12.1.1

package/src/lib/tree/tree.d.ts

@@ -1,13 +1,29 @@
 /**
- * Represends a traversable tree with values of type T.
+ * Represents a node in a traversable tree structure.
+ *
+ * @template T The type of the value stored within the node.
+ * @template N The specific type of the tree node itself, allowing for recursive type definitions
+ *             for `parent` and `children` properties. Defaults to `TreeNode<T, any>` if not specified,
+ *             which is suitable for basic trees but can be overridden for custom node types.
  */
 export interface TreeNode<T, N extends TreeNode<T, N> = TreeNode<T, any>> {
+    /** The depth of the node in the tree. The root node has a depth of 0. */
     depth: number;
+    /** The value associated with this tree node. */
     value: T;
+    /** A reference to the parent node, or undefined if this is the root node. */
     parent?: N;
+    /** An array of child nodes, or undefined if this node has no children. */
     children?: N[];
 }
 /**
- * A TreeNode with no children values available. Used when building a tree.
+ * A utility type representing a TreeNode before its children have been attached.
+ * This is often used during the tree construction process where a node is created
+ * and then its children are recursively generated and linked.
+ *
+ * It omits the 'children' property from the standard TreeNode interface.
+ *
+ * @template T The type of the value stored within the node.
+ * @template N The specific type of the tree node, as in TreeNode.
  */
 export type TreeNodeWithoutChildren<T, N extends TreeNode<T, N> = TreeNode<T, any>> = Omit<TreeNode<T, N>, 'children'>;

package/src/lib/tree/tree.expand.d.ts

@@ -1,40 +1,73 @@
 import { type TreeNode, type TreeNodeWithoutChildren } from './tree';
 import { type Maybe } from '../value/maybe.type';
 /**
- * ExpandTreeFunction configuration.
+ * Configuration for an ExpandTreeFunction, defining how to retrieve child values for a given value.
+ *
+ * @template T The type of the value being processed at each node in the tree.
  */
 export interface ExpandTree<T> {
     /**
-     * Returns child values from the value, if they exist.
-     * @param value
+     * Returns child values from the input value, if they exist.
+     * These child values will be recursively processed to form child nodes.
+     *
+     * @param value The current value of type T to retrieve children for.
+     * @returns An array of child values of type T, or undefined/null if no children exist.
      */
     getChildren(value: T): Maybe<T[]>;
 }
 /**
- * Extended ExpandTree configuration with custom node building.
+ * Extended ExpandTree configuration that includes a custom node builder.
+ * This allows for creating tree nodes of a specific type N, potentially with additional properties beyond the basic TreeNode structure.
+ *
+ * @template T The type of the value being processed at each node.
+ * @template N The specific type of TreeNode to be created. Must extend TreeNode<T, N>.
  */
 export interface ExpandTreeWithNodeBuilder<T, N extends TreeNode<T, N>> extends ExpandTree<T> {
     /**
-     * Creates a TreeNode of type N, minus the children values that are attached afterwards.
+     * Creates a tree node of type N (omitting the 'children' property, which is attached later).
+     * This function is called for each value being converted into a node in the tree.
+     *
+     * @param node A TreeNodeWithoutChildren<T, N> object containing the core properties (value, depth, parent).
+     * @returns An object of type Omit<N, 'children'>, representing the custom-built node without its children.
      */
     makeNode: (node: TreeNodeWithoutChildren<T, N>) => Omit<N, 'children'>;
 }
 /**
- * Expands the input value into a TreeNode.
+ * A function that expands an input value of type T into a TreeNode of type N.
+ *
+ * @template T The type of the input value to expand.
+ * @template N The type of the TreeNode to be created. Defaults to TreeNode<T, any>.
+ * @param value The input value of type T to expand into a tree node.
+ * @returns A tree node of type N representing the expanded value and its descendants.
  */
 export type ExpandTreeFunction<T, N extends TreeNode<T, N> = TreeNode<T, any>> = (value: T) => N;
 /**
- * Creates an ExpandTreeFunction from the input configuration.
+ * Creates an ExpandTreeFunction using a basic ExpandTree configuration.
+ * The resulting nodes will be of type TreeNode<T>.
  *
- * @param config
+ * @template T The type of the value being processed at each node.
+ * @param config An ExpandTree<T> configuration object.
+ * @returns An ExpandTreeFunction<T, TreeNode<T>>.
  */
 export declare function expandTreeFunction<T>(config: ExpandTree<T>): ExpandTreeFunction<T, TreeNode<T>>;
+/**
+ * Creates an ExpandTreeFunction using an ExpandTreeWithNodeBuilder configuration.
+ * This allows for the creation of custom tree nodes of type N.
+ *
+ * @template T The type of the value being processed at each node.
+ * @template N The specific type of TreeNode to be created.
+ * @param config An ExpandTreeWithNodeBuilder<T, N> configuration object.
+ * @returns An ExpandTreeFunction<T, N>.
+ */
 export declare function expandTreeFunction<T, N extends TreeNode<T, N>>(config: ExpandTreeWithNodeBuilder<T, N>): ExpandTreeFunction<T, N>;
 /**
- * Convenience function for expanding multiple values into trees then merging them together into a single array.
+ * Convenience function for expanding multiple root values into an array of trees.
+ * Each value in the input array is treated as a root for a new tree.
  *
- * @param values
- * @param expandFn
- * @returns
+ * @template T The type of the input values.
+ * @template N The type of the TreeNode in the resulting trees. Must extend TreeNode<T, N>.
+ * @param values An array of root values of type T to expand.
+ * @param expandFn An ExpandTreeFunction<T, N> used to expand each value into a tree.
+ * @returns An array of N, where each N is the root node of an expanded tree.
  */
 export declare function expandTrees<T, N extends TreeNode<T, N>>(values: T[], expandFn: ExpandTreeFunction<T, N>): N[];

package/src/lib/tree/tree.flatten.d.ts

@@ -1,6 +1,12 @@
 import { type TreeNode } from './tree';
 /**
- * Flattens the tree by pushing the values into the input array, or a new array and returns the value.
+ * A function that flattens a tree structure into an array of values.
+ *
+ * @template N The type of the tree node, extending TreeNode.
+ * @template V The type of values in the resulting flattened array.
+ * @param tree The root node of the tree to flatten.
+ * @param array Optional. An existing array to push the flattened values into. If not provided, a new array is created.
+ * @returns An array containing the flattened values from the tree.
  */
 export type FlattenTreeFunction<N extends TreeNode<unknown>, V> = (tree: N, array?: V[]) => V[];
 /**
@@ -15,7 +21,21 @@ export declare function flattenTree<N extends TreeNode<unknown> = TreeNode<unkno
  * @returns
  */
 export declare function flattenTreeToArray<N extends TreeNode<unknown> = TreeNode<unknown>>(tree: N, array: N[]): N[];
+/**
+ * Creates a FlattenTreeFunction that flattens tree nodes themselves into an array.
+ *
+ * @template N The type of the tree node.
+ * @returns A FlattenTreeFunction that collects nodes of type N.
+ */
 export declare function flattenTreeToArrayFunction<N extends TreeNode<unknown>>(): FlattenTreeFunction<N, N>;
+/**
+ * Creates a FlattenTreeFunction that flattens tree nodes into an array of mapped values.
+ *
+ * @template N The type of the tree node.
+ * @template V The type of the value to map each node to.
+ * @param mapNodeFn An optional function to transform each node N into a value V. If not provided, nodes are returned as is.
+ * @returns A FlattenTreeFunction that collects values of type V.
+ */
 export declare function flattenTreeToArrayFunction<N extends TreeNode<unknown, N>, V>(mapNodeFn?: (node: N) => V): FlattenTreeFunction<N, V>;
 /**
  * Convenience function for flattening multiple trees with a flatten function.

package/test/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [12.1.1](https://github.com/dereekb/dbx-components/compare/v12.1.0-dev...v12.1.1) (2025-05-12)
+
+
+
 # [12.1.0](https://github.com/dereekb/dbx-components/compare/v12.0.6-dev...v12.1.0) (2025-05-10)
 
 

package/test/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util/test",
-  "version": "12.1.0",
+  "version": "12.1.1",
   "type": "commonjs",
   "peerDependencies": {
     "@dereekb/util": "*"