@c-rex/utils 0.1.20 → 0.1.22

package/dist/directoryNodes.d.ts

@@ -1,8 +1,199 @@
 import { ObjectRefModel, TreeOfContent, DirectoryNodeModel } from '@c-rex/interfaces';
 
+/**
+ * DIRECTORY NODES MODULE
+ *
+ * OVERVIEW:
+ * This module manages the hierarchical structure of directory/documentation nodes,
+ * transforming API data into a navigable tree structure.
+ *
+ * KEY CONCEPTS:
+ *
+ * 1. NODE STRUCTURE:
+ *    - Each node (DirectoryNode) can have parents (nodes above) and children (nodes below)
+ *    - Each node has labels (title) and informationUnits (content/links)
+ *    - The structure forms a bidirectional tree: children point to parents and vice-versa
+ *
+ * 2. "ACTIVE" CONCEPT:
+ *    - A node is "active: true" when it is part of the current/selected path
+ *    - Only ONE path is active at a time (from selected item to root)
+ *    - Other nodes at the same level are "active: false" (unselected siblings)
+ *    - Used to highlight current navigation in the UI
+ *
+ * 3. NAVIGATION:
+ *    - We start with a specific node (user entry point)
+ *    - We traverse upward (parents) until we find the root (node without parents)
+ *    - We capture all siblings at each level to display as navigation options
+ *    - We build a tree with the active path highlighted
+ *
+ * 4. VALIDATION:
+ *    - Each node MUST have: labels[0] (title) and informationUnits[0] (link/content)
+ *    - If either is missing, the node is ignored or marks end of tree (root)
+ *    - ShortId is always required to identify nodes
+ *
+ * 5. ERROR HANDLING:
+ *    - If API fails to fetch a node, we continue with nodes we have
+ *    - Errors are logged but do not interrupt the flow
+ *    - We return the maximum information possible
+ */
+
+/**
+ * FUNCTION: generateTreeOfContent
+ *
+ * PURPOSE:
+ * Generates a complete navigation tree starting from an initial node,
+ * including parents, siblings, and marking the active path.
+ *
+ * EXECUTION FLOW:
+ * 1. Validates input (non-empty array with shortId)
+ * 2. Fetches the initial node from API
+ * 3. Loads children (siblings) of the initial node
+ * 4. Creates active item with children
+ * 5. Enters loop: for each parent found...
+ *    a. Fetches the parent node
+ *    b. Loads its children (which include the previous node)
+ *    c. Replaces the inactive version of previous node with active version
+ *    d. Creates new active item with the parent
+ * 6. Loop terminates when:
+ *    - No more parents (reached root), OR
+ *    - Node is missing labels/informationUnits (incomplete data)
+ * 7. Returns array with root as single item containing entire tree
+ *
+ * EXAMPLE OUTPUT STRUCTURE:
+ * Input: node "article-123" inside "category-xyz" inside "root"
+ * Output: [
+ *   {
+ *     id: 'root',
+ *     label: 'Root',
+ *     active: true,
+ *     children: [
+ *       {
+ *         id: 'category-xyz',
+ *         label: 'Category XYZ',
+ *         active: true,
+ *         children: [
+ *           { id: 'article-123', label: 'Article', active: true, children: [] }
+ *         ]
+ *       },
+ *       { id: 'other-category', label: 'Other', active: false, children: [] }
+ *     ]
+ *   }
+ * ]
+ *
+ * @param directoryNodes - Array with the initial node
+ * @returns Array with single item (root) containing entire structure
+ */
 declare const generateTreeOfContent: (directoryNodes: ObjectRefModel[]) => Promise<TreeOfContent[]>;
+type GenerateTreeOfContentOptions = {
+    includeLinkIds?: boolean;
+};
+declare const generateTreeOfContentWithOptions: (directoryNodes: ObjectRefModel[], options?: GenerateTreeOfContentOptions) => Promise<TreeOfContent[]>;
+/**
+ * FUNCTION: getChildrenInfo
+ *
+ * PURPOSE:
+ * Fetches detailed information for multiple child nodes in parallel,
+ * converting them to TreeOfContent structure.
+ *
+ * FLOW:
+ * 1. Validates if children exist
+ * 2. Makes parallel requests for ALL children (Promise.all)
+ *    - If one fails, continues with others (silent catch)
+ *    - Logs error but does not interrupt
+ * 3. Filters valid results:
+ *    a. Removes undefined responses (failed requests)
+ *    b. Removes nodes without labels (incomplete data)
+ * 4. For each valid node:
+ *    a. Extracts label (title) from first label
+ *    b. Extracts linkId (content reference) from first informationUnit
+ *    c. Creates TreeOfContent with active=false (unselected siblings)
+ *    d. Initializes children as empty array (will be filled in next call)
+ * 5. Returns array of formatted nodes
+ *
+ * IMPORTANT:
+ * - ALL returned children have active=false
+ * - The active node will be marked LATER by generateTreeOfContent
+ * - Parallel requests = better performance than sequential
+ *
+ * @param childNodes - Array of references to child nodes
+ * @returns Array of TreeOfContent with active=false for all
+ */
 declare const getChildrenInfo: (childNodes: ObjectRefModel[]) => Promise<TreeOfContent[]>;
+/**
+ * FUNCTION: getRootNode
+ *
+ * PURPOSE:
+ * Finds the root node of the hierarchy from any node,
+ * climbing up the ancestor chain to reach the top.
+ *
+ * FLOW:
+ * 1. Validates input (non-empty array with valid shortId)
+ * 2. Fetches the initial node
+ * 3. Checks if it is already root:
+ *    - If it has no ancestors, returns this node as root
+ * 4. Validates node data:
+ *    - MUST have informationUnits[0]
+ *    - MUST have labels[0]
+ *    - Returns null if missing
+ * 5. Navigates through ancestors:
+ *    a. Ancestors is an array of arrays (path history?)
+ *    b. Gets first element [0] (main path)
+ *    c. Gets last element of this path [-1] (top)
+ *    d. This is the root node
+ * 6. Fetches and returns the root node
+ *
+ * MULTIPLE VALIDATIONS:
+ * - Each access is validated to avoid TypeError
+ * - Returns null if any access fails
+ * - Ensures returned node has complete data
+ *
+ * @param directoryNodes - Array with the starting node
+ * @returns Root node with complete data, or null if invalid
+ */
 declare const getRootNode: (directoryNodes: ObjectRefModel[]) => Promise<DirectoryNodeModel | null>;
+/**
+ * FUNCTION: getLastLabel
+ *
+ * PURPOSE:
+ * Recursively extracts the title (label) of the deepest node in the active path.
+ * Useful for displaying "you are at: [final breadcrumb]" in navigation UI.
+ *
+ * ALGORITHM (Recursive):
+ * 1. Filters the tree to find the node with active=true
+ * 2. If not found, returns empty string
+ * 3. If found:
+ *    a. Stores its label
+ *    b. Checks if it has children with any active node
+ *    c. If yes, recursively searches at the next level
+ *    d. Returns the deepest label found in the active path
+ *
+ * EXAMPLE EXECUTION:
+ * Input tree:
+ * [
+ *   {
+ *     label: 'Home',
+ *     active: true,
+ *     children: [
+ *       {
+ *         label: 'Documentation',
+ *         active: true,
+ *         children: [
+ *           { label: 'API Reference', active: true, children: [] }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * ]
+ * Output: 'API Reference' (the deepest node in active path)
+ *
+ * EDGE CASES:
+ * - Empty tree: returns ""
+ * - No active nodes: returns ""
+ * - Only root is active: returns root label
+ *
+ * @param tree - Complete content tree structure
+ * @returns String containing the label of the deepest active node
+ */
 declare const getLastLabel: (tree: TreeOfContent[]) => string;
 
-export { generateTreeOfContent, getChildrenInfo, getLastLabel, getRootNode };
+export { generateTreeOfContent, generateTreeOfContentWithOptions, getChildrenInfo, getLastLabel, getRootNode };