mftsccs-node 0.2.6 → 0.2.8

package/dist/types/DataStructures/BinaryCharacterTree.d.ts

@@ -1,16 +1,227 @@
+/**
+ * @fileoverview BinaryCharacterTree module providing self-balancing AVL tree for concept storage by character value.
+ * This module implements an AVL tree structure for efficient concept retrieval using string-based keys
+ * with support for variant nodes (multiple concepts with the same character value).
+ * @module DataStructures/BinaryCharacterTree
+ */
 import { Concept } from "../DataStructures/Concept";
 import { Node } from "./Node";
+/**
+ * Self-balancing AVL binary tree for storing and retrieving concepts by their character value.
+ * Supports multiple concepts with the same character value through variant nodes.
+ * Provides O(log n) time complexity for insertions, deletions, and lookups.
+ *
+ * @class BinaryCharacterTree
+ * @example
+ * ```typescript
+ * // Add a concept to the tree
+ * BinaryCharacterTree.addConceptToTree(myConcept);
+ *
+ * // Retrieve a concept by character value
+ * const node = BinaryCharacterTree.getNodeFromTree("Apple");
+ * if (node) {
+ *   console.log("Found:", node.value.id);
+ * }
+ *
+ * // Get concept by character and type
+ * const specificNode = await BinaryCharacterTree.getCharacterAndTypeFromTree("Apple", 5);
+ * ```
+ *
+ * @remarks
+ * This class uses static methods and maintains a single root node for the entire tree.
+ * When multiple concepts share the same character value, they are stored as variants.
+ */
 export declare class BinaryCharacterTree {
+    /** Root node of the character-based binary tree, null if tree is empty */
     static characterRoot: Node | null;
+    /**
+     * Waits for the character data loading flag to be set before proceeding.
+     * Used for synchronization when loading initial data.
+     *
+     * @returns {Promise<string>} Resolves with "done" when data is loaded, rejects with "not" after 25 seconds
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await BinaryCharacterTree.waitForDataToLoad();
+     *   console.log("Character data loaded");
+     * } catch (error) {
+     *   console.log("Character data load timeout");
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses IdentifierFlags.isCharacterLoaded to determine when data is ready.
+     * Times out after 25 seconds to prevent infinite waiting.
+     */
     static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Recursively checks if the character data loaded flag is set.
+     * Internal helper method for waitForDataToLoad.
+     *
+     * @param {any} resolve - Promise resolve function
+     *
+     * @remarks
+     * Checks IdentifierFlags.isCharacterLoaded every 1000ms until it's true.
+     * This is an internal method used by waitForDataToLoad.
+     */
     static checkFlag(resolve: any): any;
+    /**
+     * Adds a node to the character-based binary tree, maintaining AVL balance.
+     * Supports adding variant nodes for concepts with the same character value.
+     *
+     * @param {Node} node - The node to add to the tree
+     * @returns {Promise<Node>} The new root node after insertion and balancing
+     *
+     * @example
+     * ```typescript
+     * const node = new Node("Apple", myConcept, null, null);
+     * await BinaryCharacterTree.addNodeToTree(node);
+     * ```
+     *
+     * @remarks
+     * If the tree is empty, the node becomes the root.
+     * If a node with the same character value exists, the new concept is added as a variant.
+     */
     static addNodeToTree(node: Node): Promise<Node | null>;
+    /**
+     * Removes a specific concept from a character node by character value and concept ID.
+     *
+     * @param {string} character - The character value to search for
+     * @param {number} id - The concept ID to remove
+     *
+     * @example
+     * ```typescript
+     * await BinaryCharacterTree.removeNodeByCharacter("Apple", 123);
+     * ```
+     *
+     * @remarks
+     * If multiple concepts share the same character value, only the one with matching ID is removed.
+     * Does nothing if the tree is empty.
+     */
     static removeNodeByCharacter(character: string, id: number): Promise<void>;
+    /**
+     * Counts the total number of nodes in the character tree.
+     *
+     * @returns {number} The total count of nodes in the tree
+     *
+     * @example
+     * ```typescript
+     * const nodeCount = BinaryCharacterTree.countNumberOfNodes();
+     * console.log(`Tree contains ${nodeCount} character nodes`);
+     * ```
+     *
+     * @remarks
+     * Recursively traverses the entire tree to count nodes.
+     * Returns 0 if the tree is empty.
+     */
     static countNumberOfNodes(): number;
+    /**
+     * Convenience method to add a concept to the character tree.
+     *
+     * @param {Concept} concept - The concept to add to the tree
+     *
+     * @example
+     * ```typescript
+     * BinaryCharacterTree.addConceptToTree(myConcept);
+     * ```
+     *
+     * @remarks
+     * Only adds concepts with non-empty character values.
+     * Creates a node with the concept's character value as the key.
+     */
     static addConceptToTree(concept: Concept): void;
+    /**
+     * Retrieves a node from the tree by its character value.
+     *
+     * @param {string} value - The character value to search for
+     * @returns {Node | null} The node if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const node = BinaryCharacterTree.getNodeFromTree("Apple");
+     * if (node) {
+     *   const concept = node.value as Concept;
+     *   console.log(concept.id);
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses binary search for O(log n) time complexity.
+     * Returns the main node; access variants through node.variants property.
+     */
     static getNodeFromTree(value: string): Node | null;
+    /**
+     * Retrieves a node from the tree by its character value (updated version).
+     * Currently identical to getNodeFromTree.
+     *
+     * @param {string} value - The character value to search for
+     * @returns {Node | null} The node if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const node = BinaryCharacterTree.getNodeFromTreeUpdated("Apple");
+     * ```
+     *
+     * @remarks
+     * This method may be deprecated or merged with getNodeFromTree in future versions.
+     */
     static getNodeFromTreeUpdated(value: string): Node | null;
+    /**
+     * Retrieves a node matching both character value and type ID.
+     * Searches through variants to find the specific type match.
+     *
+     * @param {string} value - The character value to search for
+     * @param {number} typeId - The type ID to filter by
+     * @returns {Promise<Node | null>} The node matching both criteria, null if not found
+     *
+     * @example
+     * ```typescript
+     * const node = await BinaryCharacterTree.getCharacterAndTypeFromTree("Apple", 5);
+     * if (node) {
+     *   console.log("Found Apple of type 5");
+     * }
+     * ```
+     *
+     * @remarks
+     * First finds the character node, then searches through variants for matching type.
+     * Returns null if no match is found.
+     */
     static getCharacterAndTypeFromTree(value: string, typeId: number): Promise<Node | null>;
+    /**
+     * Retrieves a node matching both character value and category ID.
+     * Searches through variants to find the specific category match.
+     *
+     * @param {string} value - The character value to search for
+     * @param {number} categoryId - The category ID to filter by
+     * @returns {Promise<Node | null>} The node matching both criteria, null if not found
+     *
+     * @example
+     * ```typescript
+     * const node = await BinaryCharacterTree.getCharacterAndCategoryFromTree("Apple", 3);
+     * if (node) {
+     *   console.log("Found Apple in category 3");
+     * }
+     * ```
+     *
+     * @remarks
+     * First finds the character node, then searches through variants for matching category.
+     * Returns null if no match is found.
+     */
     static getCharacterAndCategoryFromTree(value: string, categoryId: number): Promise<Node | null>;
+    /**
+     * Removes a concept from the character tree by its ID.
+     *
+     * @param {number} id - The concept ID to remove
+     *
+     * @example
+     * ```typescript
+     * BinaryCharacterTree.removeConceptCharacter(123);
+     * ```
+     *
+     * @remarks
+     * After removal, the tree is automatically rebalanced to maintain AVL properties.
+     * Does nothing if the tree is empty.
+     */
     static removeConceptCharacter(id: number): void;
 }

package/dist/types/DataStructures/BinaryTree.d.ts

@@ -1,12 +1,151 @@
+/**
+ * @fileoverview BinaryTree module providing self-balancing AVL tree for concept storage by ID.
+ * This module implements an AVL (Adelson-Velsky and Landis) tree structure for efficient
+ * concept retrieval with O(log n) time complexity.
+ * @module DataStructures/BinaryTree
+ */
 import { Concept } from "../DataStructures/Concept";
 import { Node } from "./Node";
+/**
+ * Self-balancing AVL binary tree for storing and retrieving concepts by their numeric ID.
+ * Provides O(log n) time complexity for insertions, deletions, and lookups.
+ *
+ * @class BinaryTree
+ * @example
+ * ```typescript
+ * // Add a concept to the tree
+ * BinaryTree.addConceptToTree(myConcept);
+ *
+ * // Retrieve a concept by ID
+ * const node = await BinaryTree.getNodeFromTree(123);
+ * if (node) {
+ *   console.log("Found:", node.value.characterValue);
+ * }
+ *
+ * // Count all nodes
+ * const count = BinaryTree.countNumberOfNodes();
+ * ```
+ *
+ * @remarks
+ * This class uses static methods and maintains a single root node for the entire tree.
+ * The tree automatically balances itself using AVL rotations to maintain optimal search performance.
+ */
 export declare class BinaryTree {
+    /** Root node of the binary tree, null if tree is empty */
     static root: Node | null;
+    /**
+     * Adds a node to the binary tree, maintaining AVL balance.
+     *
+     * @param {Node} node - The node to add to the tree
+     * @returns {Node} The new root node after insertion and balancing
+     *
+     * @example
+     * ```typescript
+     * const node = new Node(123, myConcept, null, null);
+     * BinaryTree.addNodeToTree(node);
+     * ```
+     *
+     * @remarks
+     * If the tree is empty, the node becomes the root.
+     * Otherwise, the node is inserted and the tree is automatically balanced.
+     */
     static addNodeToTree(node: Node): Node | undefined;
+    /**
+     * Waits for the data loading flag to be set before proceeding.
+     * Used for synchronization when loading initial data.
+     *
+     * @returns {Promise<string>} Resolves with "done" when data is loaded, rejects with "not" after 25 seconds
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await BinaryTree.waitForDataToLoad();
+     *   console.log("Data loaded successfully");
+     * } catch (error) {
+     *   console.log("Data load timeout");
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses IdentifierFlags.isDataLoaded to determine when data is ready.
+     * Times out after 25 seconds to prevent infinite waiting.
+     */
     static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Recursively checks if the data loaded flag is set.
+     * Internal helper method for waitForDataToLoad.
+     *
+     * @param {any} resolve - Promise resolve function
+     *
+     * @remarks
+     * Checks IdentifierFlags.isDataLoaded every 1000ms until it's true.
+     * This is an internal method used by waitForDataToLoad.
+     */
     static checkFlag(resolve: any): any;
+    /**
+     * Convenience method to add a concept to both the ID tree and character tree.
+     *
+     * @param {Concept} concept - The concept to add to the tree
+     *
+     * @example
+     * ```typescript
+     * BinaryTree.addConceptToTree(myConcept);
+     * ```
+     *
+     * @remarks
+     * Creates a node with the concept's ID as the key and adds it to this tree.
+     * Also creates a node with the concept's character value and adds it to BinaryCharacterTree.
+     */
     static addConceptToTree(concept: Concept): void;
+    /**
+     * Retrieves a node from the tree by its ID.
+     *
+     * @param {number} id - The concept ID to search for
+     * @returns {Promise<Node | null>} The node if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const node = await BinaryTree.getNodeFromTree(123);
+     * if (node) {
+     *   const concept = node.value as Concept;
+     *   console.log(concept.characterValue);
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses binary search for O(log n) time complexity.
+     * Returns null if the tree is empty or the node is not found.
+     */
     static getNodeFromTree(id: number): Promise<Node | null>;
+    /**
+     * Removes a node from the tree by its ID.
+     *
+     * @param {number} id - The concept ID to remove
+     *
+     * @example
+     * ```typescript
+     * await BinaryTree.removeNodeFromTree(123);
+     * ```
+     *
+     * @remarks
+     * After removal, the tree is automatically rebalanced to maintain AVL properties.
+     * Does nothing if the tree is empty.
+     */
     static removeNodeFromTree(id: number): Promise<void>;
+    /**
+     * Counts the total number of nodes in the tree.
+     *
+     * @returns {number} The total count of nodes in the tree
+     *
+     * @example
+     * ```typescript
+     * const nodeCount = BinaryTree.countNumberOfNodes();
+     * console.log(`Tree contains ${nodeCount} concepts`);
+     * ```
+     *
+     * @remarks
+     * Recursively traverses the entire tree to count nodes.
+     * Returns 0 if the tree is empty.
+     */
     static countNumberOfNodes(): number;
 }

package/dist/types/DataStructures/BinaryTypeTree.d.ts

@@ -1,15 +1,211 @@
+/**
+ * @fileoverview BinaryTypeTree module providing self-balancing AVL tree for concept storage by type ID.
+ * This module implements an AVL tree structure for efficient concept retrieval by type
+ * with support for variant nodes (multiple concepts of the same type).
+ * @module DataStructures/BinaryTypeTree
+ */
 import { Concept } from "../DataStructures/Concept";
 import { Node } from "./Node";
+/**
+ * Self-balancing AVL binary tree for storing and retrieving concepts by their type ID.
+ * Supports multiple concepts with the same type through variant nodes.
+ * Provides O(log n) time complexity for insertions, deletions, and lookups.
+ *
+ * @class BinaryTypeTree
+ * @example
+ * ```typescript
+ * // Add a concept to the type tree
+ * BinaryTypeTree.addConceptToTree(myConcept);
+ *
+ * // Get all concepts of a specific type
+ * const concepts = BinaryTypeTree.getTypeVariantsFromTree(5);
+ * console.log(`Found ${concepts.length} concepts of type 5`);
+ *
+ * // Get concepts by type and user
+ * const userConcepts = await BinaryTypeTree.getTypeVariantsFromTreeWithUserId(5, 1);
+ * ```
+ *
+ * @remarks
+ * This class uses static methods and maintains a single root node for the entire tree.
+ * Multiple concepts with the same type ID are stored as variants for efficient batch retrieval.
+ */
 export declare class BinaryTypeTree {
+    /** Root node of the type-based binary tree, null if tree is empty */
     static typeRoot: Node | null;
+    /**
+     * Adds a node to the type-based binary tree, maintaining AVL balance.
+     * Supports adding variant nodes for concepts with the same type ID.
+     *
+     * @param {Node} node - The node to add to the tree
+     * @returns {Promise<Node>} The new root node after insertion and balancing
+     *
+     * @example
+     * ```typescript
+     * const node = new Node(5, myConcept, null, null);
+     * await BinaryTypeTree.addNodeToTree(node);
+     * ```
+     *
+     * @remarks
+     * If the tree is empty, the node becomes the root.
+     * If a node with the same type ID exists, the new concept is added as a variant.
+     */
     static addNodeToTree(node: Node): Promise<Node | null>;
+    /**
+     * Convenience method to add a concept to the type tree.
+     *
+     * @param {Concept} concept - The concept to add to the tree
+     *
+     * @example
+     * ```typescript
+     * BinaryTypeTree.addConceptToTree(myConcept);
+     * ```
+     *
+     * @remarks
+     * Only adds concepts with valid type IDs (typeId != 0).
+     * Creates a node with the concept's type ID as the key.
+     */
     static addConceptToTree(concept: Concept): void;
+    /**
+     * Removes a specific concept from a type node by type ID and concept ID.
+     *
+     * @param {number} typeId - The type ID to search for
+     * @param {number} id - The concept ID to remove
+     *
+     * @example
+     * ```typescript
+     * BinaryTypeTree.removeTypeConcept(5, 123);
+     * ```
+     *
+     * @remarks
+     * If multiple concepts share the same type ID, only the one with matching concept ID is removed.
+     * Does nothing if the tree is empty.
+     */
     static removeTypeConcept(typeId: number, id: number): void;
+    /**
+     * Retrieves a node from the tree by its type ID.
+     *
+     * @param {number} id - The type ID to search for
+     * @returns {Node | null} The node if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const node = BinaryTypeTree.getNodeFromTree(5);
+     * if (node) {
+     *   console.log("Found type node with", node.variants.length, "variants");
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses binary search for O(log n) time complexity.
+     * Returns the main node; access all concepts of this type through node.value and node.variants.
+     */
     static getNodeFromTree(id: number): Node | null;
+    /**
+     * Retrieves all concepts of a specific type ID as an array.
+     * Includes both the main concept and all variants.
+     *
+     * @param {number} typeId - The type ID to search for
+     * @returns {Concept[]} Array of all concepts with the specified type ID
+     *
+     * @example
+     * ```typescript
+     * const concepts = BinaryTypeTree.getTypeVariantsFromTree(5);
+     * concepts.forEach(concept => {
+     *   console.log(concept.characterValue);
+     * });
+     * ```
+     *
+     * @remarks
+     * Returns an empty array if no concepts of the type are found.
+     * Useful for batch operations on all concepts of a type.
+     */
     static getTypeVariantsFromTree(typeId: number): Concept[] | undefined;
+    /**
+     * Waits for the type data loading flag to be set before proceeding.
+     * Used for synchronization when loading initial data.
+     *
+     * @returns {Promise<string>} Resolves with "done" when data is loaded, rejects with "not" after 25 seconds
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await BinaryTypeTree.waitForDataToLoad();
+     *   console.log("Type data loaded");
+     * } catch (error) {
+     *   console.log("Type data load timeout");
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses IdentifierFlags.isTypeLoaded to determine when data is ready.
+     * Times out after 25 seconds to prevent infinite waiting.
+     */
     static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Recursively checks if the type data loaded flag is set.
+     * Internal helper method for waitForDataToLoad.
+     *
+     * @param {any} resolve - Promise resolve function
+     *
+     * @remarks
+     * Checks IdentifierFlags.isTypeLoaded every 1000ms until it's true.
+     * This is an internal method used by waitForDataToLoad.
+     */
     static checkFlag(resolve: any): any;
+    /**
+     * Retrieves all concepts of a specific type ID filtered by user ID.
+     * Includes both the main concept and all variants belonging to the specified user.
+     *
+     * @param {number} typeId - The type ID to search for
+     * @param {number} userId - The user ID to filter by
+     * @returns {Promise<Concept[]>} Array of concepts matching both type and user
+     *
+     * @example
+     * ```typescript
+     * const userConcepts = await BinaryTypeTree.getTypeVariantsFromTreeWithUserId(5, 1);
+     * console.log(`User 1 has ${userConcepts.length} concepts of type 5`);
+     * ```
+     *
+     * @remarks
+     * Returns an empty array if no matching concepts are found.
+     * Automatically deduplicates concepts with the same ID.
+     */
     static getTypeVariantsFromTreeWithUserId(typeId: number, userId: number): Promise<Concept[]>;
+    /**
+     * Retrieves a concept matching both type ID and character value.
+     * Searches through all concepts of the type for a matching character value.
+     *
+     * @param {string} characterValue - The character value to search for
+     * @param {number} typeId - The type ID to filter by
+     * @returns {Promise<Concept>} The concept matching both criteria, or a default concept if not found
+     *
+     * @example
+     * ```typescript
+     * const concept = await BinaryTypeTree.getTypeVariantsWithCharacterValue("Apple", 5);
+     * if (concept.id !== 0) {
+     *   console.log("Found Apple of type 5");
+     * }
+     * ```
+     *
+     * @remarks
+     * Returns a default concept (id = 0) if no match is found.
+     * More efficient than searching by character first when type is known.
+     */
     static getTypeVariantsWithCharacterValue(characterValue: string, typeId: number): Promise<Concept>;
+    /**
+     * Counts the total number of nodes in the type tree.
+     *
+     * @returns {number} The total count of nodes in the tree
+     *
+     * @example
+     * ```typescript
+     * const nodeCount = BinaryTypeTree.countNumberOfNodes();
+     * console.log(`Tree contains ${nodeCount} type nodes`);
+     * ```
+     *
+     * @remarks
+     * Recursively traverses the entire tree to count nodes.
+     * Returns 0 if the tree is empty.
+     */
     static countNumberOfNodes(): number;
 }