@barchart/common-js/types/collections/Tree.d.ts

Library of common JavaScript utilities

/**
 * A tree data structure. Each instance represents a node, holding
 * an item, a reference to the parent node, and a reference to
 * children nodes. Children are stored in insertion order.
 *
 * @public
 */
export default class Tree {
    /**
     * @param {*} value - The value of the node.
     * @param {Tree=} parent - The parent node. If not supplied, this will be the root node.
     */
    constructor(value: any, parent?: Tree | undefined);
    _value: any;
    _parent: Tree;
    _children: any[];
    /**
     * Gets the root node.
     *
     * @public
     * @returns {Tree}
     */
    public getRoot(): Tree;
    /**
     * Returns the parent node. If this is the root node, a null value is returned.
     *
     * @public
     * @returns {Tree|null}
     */
    public getParent(): Tree | null;
    /**
     * Returns the collection of children nodes.
     *
     * @public
     * @returns {Array<Tree>}
     */
    public getChildren(): Array<Tree>;
    /**
     * Returns the value associated with the current node.
     *
     * @public
     * @returns {*}
     */
    public getValue(): any;
    /**
     * Returns true if this node has no children; otherwise false.
     *
     * @public
     * @returns {boolean}
     */
    public getIsLeaf(): boolean;
    /**
     * Returns true if this node has children; otherwise false.
     *
     * @public
     * @returns {boolean}
     */
    public getIsInner(): boolean;
    /**
     * Returns true if this node has no parent; otherwise false.
     *
     * @public
     * @returns {boolean}
     */
    public getIsRoot(): boolean;
    /**
     * Adds a child node to the current node and returns a reference
     * to the child node.
     *
     * @public
     * @param {*} value - The value of the child.
     * @returns {Tree}
     */
    public addChild(value: any): Tree;
    /**
     * Removes a child node.
     *
     * @public
     * @param {Tree} node - The child to remove.
     */
    public removeChild(node: Tree): void;
    /**
     * Removes the current node from the parent tree. Use on a root node
     * has no effect.
     *
     * @public
     */
    public sever(): void;
    /**
     * Searches the children nodes for the first child node that matches the
     * predicate.
     *
     * @public
     * @param {nodePredicate} predicate - A predicate that tests each child node. The predicate takes two arguments -- the node's value, and the node itself.
     * @returns {Tree|null}
     */
    public findChild(predicate: nodePredicate): Tree | null;
    /**
     * Searches the tree recursively, starting with the current node.
     *
     * @public
     * @param {nodePredicate} predicate - A predicate that tests each child node. The predicate takes two arguments -- the node's value, and the node itself.
     * @param {boolean=} parentFirst - If true, the tree will be searched from parent-to-child (breadth first). Otherwise, child-to-parent (depth first).
     * @param {boolean=} includeCurrentNode - True, if the current node should be checked against the predicate.
     * @returns {Tree|null}
     */
    public search(predicate: nodePredicate, parentFirst?: boolean | undefined, includeCurrentNode?: boolean | undefined): Tree | null;
    /**
     * Walks the children of the current node, running an action on each node.
     *
     * @public
     * @param {nodeAction} walkAction - A action to apply to each node. The action takes two arguments -- the node's value, and the node itself.
     * @param {boolean=} parentFirst - If true, the tree will be searched from parent-to-child (breadth first). Otherwise, child-to-parent (depth first).
     * @param {boolean=} includeCurrentNode - True if the current node should be applied to the action.
     */
    public walk(walkAction: nodeAction, parentFirst?: boolean | undefined, includeCurrentNode?: boolean | undefined): void;
    /**
     * Returns the count of all descendant nodes by walking the tree. Consequently, this
     * function is not efficient.
     *
     * @public
     * @returns {number}
     */
    public count(): number;
    /**
     * Climbs the parents of the current node -- current node up to the root node, running an action on each node.
     *
     * @public
     * @param {nodeAction} climbAction - A action to apply to each node. The action takes two arguments -- the node's value, and the node itself.
     * @param {boolean=} includeCurrentNode - True if the current node should be applied to the action.
     */
    public climb(climbAction: nodeAction, includeCurrentNode?: boolean | undefined): void;
    /**
     * Climbs the tree, evaluating each parent until a predicate is matched. Once matched,
     * the {@link Tree} node is returned. Otherwise, if the predicate cannot be matched,
     * a null value is returned.
     *
     * @public
     * @param {nodePredicate} predicate - A predicate that tests each child node. The predicate takes two arguments -- the node's value, and the node itself.
     * @param {boolean=} includeCurrentNode - If true, the predicate will be applied to the current node.
     * @returns {Tree|null}
     */
    public findParent(predicate: nodePredicate, includeCurrentNode?: boolean | undefined): Tree | null;
    /**
     * Creates a representation of the tree using JavaScript objects and arrays.
     *
     * @public
     * @param {Function=} valueConverter - An optional function for converting the value of each node.
     * @param {boolean=} omitEmptyChildren - If true, empty children arrays will be excluded from output.
     * @returns {object}
     */
    public toJSObj(valueConverter?: Function | undefined, omitEmptyChildren?: boolean | undefined): object;
    /**
     * Returns a string representation.
     *
     * @public
     * @returns {string}
     */
    public toString(): string;
}
/**
 * A predicate that is used to check a node (i.e. {@link Tree}).
 */
export type nodePredicate = (item: any, node: Tree) => boolean;
/**
 * An action that is run on a node (i.e. {@link Tree}).
 */
export type nodeAction = (item: any, node: Tree) => any;