mftsccs-node 0.0.56 → 0.0.58

package/dist/types/DataStructures/Local/LNode.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Local Node data structure for binary tree operations.
+ * This module defines the LNode class which represents a node in an AVL
+ * (self-balancing) binary tree for storing and managing LConcept instances.
+ * @module DataStructures/Local/LNode
+ */
+import { LConcept } from "./LConcept";
+/**
+ * Represents a node in an AVL binary tree for local concepts.
+ * This class implements self-balancing tree operations including rotations,
+ * insertions, deletions, and lookups for efficient concept management.
+ *
+ * @class LNode
+ * @export
+ */
+export declare class LNode {
+    /**
+     * The key used for tree ordering (can be number or string).
+     * @type {any}
+     */
+    key: any;
+    /**
+     * The concept value stored in this node.
+     * @type {LConcept}
+     */
+    value: LConcept;
+    /**
+     * Reference to the left child node.
+     * @type {LNode | null}
+     */
+    leftNode: LNode | null;
+    /**
+     * Reference to the right child node.
+     * @type {LNode | null}
+     */
+    rightNode: LNode | null;
+    /**
+     * Reference to current node for linking nodes with same key.
+     * @type {LNode | null}
+     */
+    currentNode: LNode | null;
+    /**
+     * Array of variant nodes with same key but different properties.
+     * @type {LNode[]}
+     * @default []
+     */
+    variants: LNode[];
+    /**
+     * Height of the node in the tree for AVL balancing.
+     * @type {number}
+     * @default 1
+     */
+    height: number;
+    /**
+     * Creates a new LNode instance.
+     *
+     * @constructor
+     * @param {any} key - The key used for tree ordering
+     * @param {LConcept} value - The concept value to store
+     * @param {LNode | null} leftNode - Reference to left child
+     * @param {LNode | null} rightNode - Reference to right child
+     */
+    constructor(key: any, value: LConcept, leftNode: LNode | null, rightNode: LNode | null);
+    /**
+     * Adds a current node to the chain based on typeId.
+     * This method links nodes with different typeIds.
+     *
+     * @method addCurrentNode
+     * @param {LNode} passedNode - The node to add
+     * @param {LNode | null} node - The current node in the chain
+     * @returns {LNode | null} The updated node chain
+     */
+    addCurrentNode(passedNode: LNode, node: LNode | null): LNode;
+    /**
+     * Adds a node as a variant if it has the same key but different id.
+     * This method manages variants (nodes with same key but different properties).
+     *
+     * @method addCurrentNodeType
+     * @param {LNode} passedNode - The node to add as variant
+     * @param {LNode | null} node - The current node
+     * @returns {LNode | null} The updated node
+     */
+    addCurrentNodeType(passedNode: LNode, node: LNode | null): LNode;
+    /**
+     * Adds a node to the AVL tree with automatic balancing.
+     * This method performs standard AVL insertion with rotations.
+     *
+     * @method addNode
+     * @param {LNode} passedNode - The node to insert
+     * @param {LNode | null} node - The current node in traversal
+     * @param {number} height - Current height for balancing
+     * @returns {LNode | null} The root of the updated subtree
+     */
+    addNode(passedNode: LNode, node: LNode | null, height: number): LNode | null;
+    /**
+     * Adds a character node to the tree with variant management.
+     * Handles nodes with character keys and manages variants for duplicate keys.
+     *
+     * @method addCharacterNode
+     * @param {LNode} passedNode - The node to insert
+     * @param {LNode | null} node - The current node in traversal
+     * @param {number} height - Current height for balancing
+     * @returns {LNode | null} The root of the updated subtree
+     */
+    addCharacterNode(passedNode: LNode, node: LNode | null, height: number): LNode | null;
+    /**
+     * Adds a type node to the tree with variant management.
+     * Handles nodes with typeId keys and manages variants for duplicate typeIds.
+     *
+     * @method addTypeNode
+     * @param {LNode} passedNode - The node to insert
+     * @param {LNode | null} node - The current node in traversal
+     * @param {number} height - Current height for balancing
+     * @returns {LNode | null} The root of the updated subtree
+     */
+    addTypeNode(passedNode: LNode, node: LNode | null, height: number): LNode | null;
+    /**
+     * Performs a right rotation for AVL tree balancing.
+     *
+     * @method rightRotate
+     * @param {LNode | null} y - The node to rotate
+     * @returns {LNode | null} The new root of the rotated subtree
+     */
+    rightRotate(y: LNode | null): LNode | null;
+    /**
+     * Performs a left rotation for AVL tree balancing.
+     *
+     * @method leftRotate
+     * @param {LNode | null} x - The node to rotate
+     * @returns {LNode | null} The new root of the rotated subtree
+     */
+    leftRotate(x: LNode | null): LNode | null;
+    /**
+     * Gets the height of a node.
+     *
+     * @method getHeight
+     * @param {LNode | null} node - The node to get height from
+     * @returns {number} The height of the node, or 0 if null
+     */
+    getHeight(node: LNode | null): number;
+    /**
+     * Calculates the balance factor of a node.
+     * Balance factor = height(left subtree) - height(right subtree)
+     *
+     * @method getBalanceFactor
+     * @param {LNode | null} N - The node to calculate balance factor for
+     * @returns {number} The balance factor (-2, -1, 0, 1, or 2)
+     */
+    getBalanceFactor(N: LNode | null): number;
+    /**
+     * Searches for a node by numeric id.
+     *
+     * @method getFromNode
+     * @param {number} id - The id to search for
+     * @param {LNode | null} node - The current node in traversal
+     * @returns {LNode | null} The found node or null
+     */
+    getFromNode(id: number, node: LNode | null): LNode | null;
+    /**
+     * Searches for a node by character value.
+     *
+     * @method getCharacterFromNode
+     * @param {string} value - The character value to search for
+     * @param {LNode | null} node - The current node in traversal
+     * @returns {LNode | null} The found node or null
+     */
+    getCharacterFromNode(value: string, node: LNode | null): LNode | null;
+    /**
+     * Searches for a node by both character value and type id.
+     * This method also searches through variants to find exact matches.
+     *
+     * @method getFromNodeWithCharacterAndType
+     * @param {string} value - The character value to search for
+     * @param {number} typeId - The type identifier to match
+     * @param {LNode | null} node - The current node in traversal
+     * @returns {LNode | null} The found node or null
+     */
+    getFromNodeWithCharacterAndType(value: string, typeId: number, node: LNode | null): LNode | null;
+    /**
+     * Removes a node from the tree by id.
+     * Uses standard BST deletion with in-order successor replacement.
+     *
+     * @method removeNode
+     * @param {LNode | null} passedNode - The current node in traversal
+     * @param {number} id - The id of the node to remove
+     * @returns {LNode | null} The root of the updated subtree
+     */
+    removeNode(passedNode: LNode | null, id: number): LNode | null;
+    /**
+     * Removes a node with variant management.
+     * If the node has variants, replaces the removed node with first variant.
+     *
+     * @method removeNodeWithVariants
+     * @param {LNode | null} passedNode - The current node in traversal
+     * @param {any} typeIdentifier - The type identifier (key) to search for
+     * @param {number} conceptId - The concept id to remove
+     * @returns {LNode | null} The root of the updated subtree
+     */
+    removeNodeWithVariants(passedNode: LNode | null, typeIdentifier: any, conceptId: number): LNode | null;
+    /**
+     * Counts the total number of nodes in the subtree.
+     *
+     * @method countNodeBelow
+     * @param {LNode | null} root - The root of the subtree
+     * @returns {number} The total count of nodes
+     */
+    countNodeBelow(root: LNode | null): number;
+    /**
+     * Finds the in-order successor (leftmost node in right subtree).
+     * Used during node deletion.
+     *
+     * @method inOrderSuccessor
+     * @param {LNode} root - The root to find successor from
+     * @returns {LNode} The in-order successor node
+     */
+    inOrderSuccessor(root: LNode): LNode;
+}

package/dist/types/DataStructures/Local/LocalBinaryCharacterTree.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Local Binary Character Tree for managing concepts indexed by character value.
+ * This module provides a specialized binary tree implementation for efficient character-based lookups.
+ * @module DataStructures/Local/LocalBinaryCharacterTree
+ */
+import { LConcept } from "../../DataStructures/Local/LConcept";
+import { LNode } from "./../Local/LNode";
+/**
+ * Binary tree data structure for managing local concepts indexed by character values.
+ *
+ * @remarks
+ * This class implements an AVL tree specifically optimized for character-based lookups.
+ * Unlike LocalBinaryTree which uses numeric IDs, this tree uses character values as keys,
+ * enabling efficient string-based searches with O(log n) complexity.
+ *
+ * @example
+ * ```typescript
+ * const concept = new LConcept(123, "example", 1);
+ * LocalBinaryCharacterTree.addConceptToTree(concept);
+ * const node = LocalBinaryCharacterTree.getNodeFromTree("example");
+ * ```
+ */
+export declare class LocalBinaryCharacterTree {
+    /**
+     * The root node of the character-indexed binary tree.
+     * Null if the tree is empty.
+     */
+    static LocalCharacterRoot: LNode | null;
+    /**
+     * Waits for local character data to be loaded into the tree.
+     *
+     * @returns A promise that resolves with "done" when data is loaded, or rejects with "not" after 25 seconds
+     *
+     * @remarks
+     * This method polls the IdentifierFlags.isLocalCharacterLoaded flag every second.
+     * Useful for ensuring data is ready before performing operations on the tree.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await LocalBinaryCharacterTree.waitForDataToLoad();
+     *   console.log("Character data loaded");
+     * } catch (error) {
+     *   console.log("Loading timed out");
+     * }
+     * ```
+     */
+    static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Periodically checks if local character data has been loaded.
+     *
+     * @param resolve - The promise resolve function to call when data is loaded
+     *
+     * @remarks
+     * This method recursively checks the IdentifierFlags.isLocalCharacterLoaded flag every 1000ms.
+     */
+    static checkFlag(resolve: any): any;
+    /**
+     * Adds a node to the character-indexed binary tree.
+     *
+     * @param node - The LNode to be added to the tree (keyed by character value)
+     * @returns The root node after insertion
+     *
+     * @remarks
+     * If the tree is empty, the provided node becomes the root.
+     * Otherwise, uses the addCharacterNode method for character-based insertion.
+     *
+     * @example
+     * ```typescript
+     * const node = new LNode("example", concept, null, null);
+     * await LocalBinaryCharacterTree.addNodeToTree(node);
+     * ```
+     */
+    static addNodeToTree(node: LNode): Promise<LNode | null>;
+    /**
+     * Creates a node from a concept and adds it to the character tree.
+     *
+     * @param concept - The LConcept object to be added to the tree
+     *
+     * @remarks
+     * Only adds the concept if it has a non-empty characterValue.
+     * The node is keyed by the concept's character value.
+     *
+     * @example
+     * ```typescript
+     * const concept = new LConcept(123, "example", 1);
+     * LocalBinaryCharacterTree.addConceptToTree(concept);
+     * ```
+     */
+    static addConceptToTree(concept: LConcept): void;
+    /**
+     * Retrieves a node from the tree by its character value.
+     *
+     * @param value - The character string to search for
+     * @returns The LNode if found, the root node otherwise
+     *
+     * @remarks
+     * Performs a binary search through the tree using the character value as the key.
+     *
+     * @example
+     * ```typescript
+     * const node = LocalBinaryCharacterTree.getNodeFromTree("example");
+     * if (node) {
+     *   console.log("Found concept:", node.value);
+     * }
+     * ```
+     */
+    static getNodeFromTree(value: string): LNode | null;
+    /**
+     * Retrieves a node by matching both character value and type ID.
+     *
+     * @param value - The character value to search for
+     * @param typeId - The type ID to match
+     * @returns The matching LNode if found, the root node otherwise
+     *
+     * @remarks
+     * This method searches for a node that matches both the character value and type ID,
+     * useful for finding specific concept variants.
+     *
+     * @example
+     * ```typescript
+     * const node = await LocalBinaryCharacterTree.getCharacterAndTypeFromTree("example", 5);
+     * if (node) {
+     *   console.log("Found matching concept:", node.value);
+     * }
+     * ```
+     */
+    static getCharacterAndTypeFromTree(value: string, typeId: number): Promise<LNode | null>;
+    /**
+     * Removes a concept variant from the tree.
+     *
+     * @param character - The character value identifying the node
+     * @param id - The concept ID to remove
+     *
+     * @remarks
+     * This method removes a specific variant from a node while maintaining other variants.
+     * If the node has no remaining variants, the entire node is removed.
+     *
+     * @example
+     * ```typescript
+     * LocalBinaryCharacterTree.removeConceptType("example", 123);
+     * ```
+     */
+    static removeConceptType(character: string, id: number): void;
+}

package/dist/types/DataStructures/Local/LocalBinaryTree.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Local Binary Tree data structure for managing local concepts.
+ * This module provides a binary tree implementation for storing and retrieving LConcept objects
+ * using an AVL tree structure for balanced performance.
+ * @module DataStructures/Local/LocalBinaryTree
+ */
+import { LConcept } from "../../DataStructures/Local/LConcept";
+import { LNode } from "./../Local/LNode";
+/**
+ * Binary tree data structure for managing local concepts with efficient lookup by ID.
+ *
+ * @remarks
+ * This class implements a self-balancing binary search tree (AVL tree) for storing local concepts.
+ * It provides O(log n) search, insertion, and deletion operations. The tree is keyed by concept ID
+ * and supports asynchronous data loading with timeout capabilities.
+ *
+ * @example
+ * ```typescript
+ * const concept = new LConcept(123, "example", 1);
+ * LocalBinaryTree.addConceptToTree(concept);
+ * const node = await LocalBinaryTree.getNodeFromTree(123);
+ * ```
+ */
+export declare class LocalBinaryTree {
+    /**
+     * The root node of the binary tree.
+     * Null if the tree is empty.
+     */
+    static root: LNode | null;
+    /**
+     * Adds a node to the binary tree.
+     *
+     * @param node - The LNode to be added to the tree
+     * @returns The root node after insertion
+     *
+     * @remarks
+     * If the tree is empty, the provided node becomes the root.
+     * Otherwise, the node is inserted at the appropriate position using the AVL tree algorithm.
+     *
+     * @example
+     * ```typescript
+     * const node = new LNode(123, concept, null, null);
+     * LocalBinaryTree.addNodeToTree(node);
+     * ```
+     */
+    static addNodeToTree(node: LNode): LNode | undefined;
+    /**
+     * Creates a node from a concept and adds it to the tree.
+     *
+     * @param concept - The LConcept object to be added to the tree
+     *
+     * @remarks
+     * This is a convenience method that creates an LNode from the concept and adds it to the tree.
+     * The node is keyed by the concept's ID.
+     *
+     * @example
+     * ```typescript
+     * const concept = new LConcept(123, "example", 1);
+     * LocalBinaryTree.addConceptToTree(concept);
+     * ```
+     */
+    static addConceptToTree(concept: LConcept): void;
+    /**
+     * Waits for local data to be loaded into the tree.
+     *
+     * @returns A promise that resolves with "done" when data is loaded, or rejects with "not" after 25 seconds
+     *
+     * @remarks
+     * This method polls the IdentifierFlags.isLocalDataLoaded flag every second until it's true.
+     * If data isn't loaded within 25 seconds, the promise is rejected.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await LocalBinaryTree.waitForDataToLoad();
+     *   console.log("Data loaded successfully");
+     * } catch (error) {
+     *   console.log("Data loading timed out");
+     * }
+     * ```
+     */
+    static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Periodically checks if local data has been loaded.
+     *
+     * @param resolve - The promise resolve function to call when data is loaded
+     *
+     * @remarks
+     * This method is called recursively every 1000ms until the data is loaded.
+     * It checks the IdentifierFlags.isLocalDataLoaded flag.
+     */
+    static checkFlag(resolve: any): any;
+    /**
+     * Retrieves a node from the tree by its ID.
+     *
+     * @param id - The numeric ID of the node to retrieve
+     * @returns The LNode if found, null otherwise
+     *
+     * @remarks
+     * This method performs a binary search through the tree using the concept ID as the key.
+     * The search has O(log n) time complexity in a balanced tree.
+     *
+     * @example
+     * ```typescript
+     * const node = await LocalBinaryTree.getNodeFromTree(123);
+     * if (node) {
+     *   console.log("Found concept:", node.value);
+     * }
+     * ```
+     */
+    static getNodeFromTree(id: number): Promise<LNode | null>;
+    /**
+     * Retrieves a node by matching both character value and type ID.
+     *
+     * @param value - The character value to search for
+     * @param typeId - The type ID to match
+     * @returns The matching LNode if found, the root node otherwise
+     *
+     * @remarks
+     * This method searches for a node that matches both the character value and type ID.
+     * It's useful for finding specific concept variants.
+     *
+     * @example
+     * ```typescript
+     * const node = LocalBinaryTree.getCharacterAndTypeFromTree("example", 5);
+     * if (node) {
+     *   console.log("Found matching concept:", node.value);
+     * }
+     * ```
+     */
+    static getCharacterAndTypeFromTree(value: string, typeId: number): LNode | null;
+    /**
+     * Removes a node from the tree by its ID.
+     *
+     * @param id - The numeric ID of the node to remove
+     *
+     * @remarks
+     * This method removes a node from the tree while maintaining the AVL tree balance.
+     * The tree is automatically rebalanced after removal.
+     *
+     * @example
+     * ```typescript
+     * await LocalBinaryTree.removeNodeFromTree(123);
+     * ```
+     */
+    static removeNodeFromTree(id: number): Promise<void>;
+}

package/dist/types/DataStructures/Local/LocalBinaryTypeTree.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Local Binary Type Tree for managing concepts indexed by type ID.
+ * This module provides a specialized binary tree for efficient type-based concept lookups and variant retrieval.
+ * @module DataStructures/Local/LocalBinaryTypeTree
+ */
+import { LConcept } from "../../DataStructures/Local/LConcept";
+import { LNode } from "./LNode";
+/**
+ * Binary tree data structure for managing local concepts indexed by type ID.
+ *
+ * @remarks
+ * This class implements an AVL tree optimized for type-based lookups, enabling efficient
+ * retrieval of all concepts of a specific type. It supports variant management, allowing
+ * multiple concepts to share the same type while being stored efficiently.
+ *
+ * @example
+ * ```typescript
+ * const concept = new LConcept(123, "example", 5);
+ * LocalBinaryTypeTree.addConceptToTree(concept);
+ * const variants = LocalBinaryTypeTree.getTypeVariantsFromTree(5);
+ * ```
+ */
+export declare class LocalBinaryTypeTree {
+    /**
+     * The root node of the type-indexed binary tree.
+     * Null if the tree is empty.
+     */
+    static LocalTypeRoot: LNode | null;
+    /**
+     * Adds a node to the type-indexed binary tree.
+     *
+     * @param node - The LNode to be added to the tree (keyed by type ID)
+     * @returns The root node after insertion
+     *
+     * @remarks
+     * If the tree is empty, the provided node becomes the root.
+     * Otherwise, uses the addTypeNode method for type-based insertion with variant support.
+     *
+     * @example
+     * ```typescript
+     * const node = new LNode(5, concept, null, null);
+     * await LocalBinaryTypeTree.addNodeToTree(node);
+     * ```
+     */
+    static addNodeToTree(node: LNode): Promise<LNode | null>;
+    /**
+     * Creates a node from a concept and adds it to the type tree.
+     *
+     * @param concept - The LConcept object to be added to the tree
+     *
+     * @remarks
+     * Only adds the concept if it has a non-zero typeId.
+     * The node is keyed by the concept's type ID.
+     *
+     * @example
+     * ```typescript
+     * const concept = new LConcept(123, "example", 5);
+     * LocalBinaryTypeTree.addConceptToTree(concept);
+     * ```
+     */
+    static addConceptToTree(concept: LConcept): void;
+    /**
+     * Removes a specific concept variant from the tree.
+     *
+     * @param typeId - The type ID identifying the node
+     * @param id - The concept ID to remove
+     *
+     * @remarks
+     * This method removes a specific variant from a node while maintaining other variants.
+     * If the node has no remaining variants, the entire node is removed.
+     *
+     * @example
+     * ```typescript
+     * LocalBinaryTypeTree.removeConceptType(5, 123);
+     * ```
+     */
+    static removeConceptType(typeId: number, id: number): void;
+    /**
+     * Retrieves a node from the tree by its type ID.
+     *
+     * @param id - The numeric type ID to search for
+     * @returns The LNode if found, the root node otherwise
+     *
+     * @remarks
+     * Performs a binary search through the tree using the type ID as the key.
+     *
+     * @example
+     * ```typescript
+     * const node = LocalBinaryTypeTree.getNodeFromTree(5);
+     * if (node) {
+     *   console.log("Found type node with variants:", node.variants.length);
+     * }
+     * ```
+     */
+    static getNodeFromTree(id: number): LNode | null;
+    /**
+     * Retrieves all concept variants for a specific type ID.
+     *
+     * @param typeId - The type ID to search for
+     * @returns An array of LConcept objects of the specified type
+     *
+     * @remarks
+     * This method retrieves the primary concept and all its variants that share the same type ID.
+     * Useful for getting all concepts of a particular type in one operation.
+     *
+     * @example
+     * ```typescript
+     * const concepts = LocalBinaryTypeTree.getTypeVariantsFromTree(5);
+     * console.log(`Found ${concepts.length} concepts of type 5`);
+     * ```
+     */
+    static getTypeVariantsFromTree(typeId: number): LConcept[] | undefined;
+    /**
+     * Waits for local type data to be loaded into the tree.
+     *
+     * @returns A promise that resolves with "done" when data is loaded, or rejects with "not" after 25 seconds
+     *
+     * @remarks
+     * This method polls the IdentifierFlags.isLocalTypeLoaded flag every second.
+     * Ensures type data is ready before performing operations.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await LocalBinaryTypeTree.waitForDataToLoad();
+     *   console.log("Type data loaded");
+     * } catch (error) {
+     *   console.log("Loading timed out");
+     * }
+     * ```
+     */
+    static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Periodically checks if local type data has been loaded.
+     *
+     * @param resolve - The promise resolve function to call when data is loaded
+     *
+     * @remarks
+     * This method recursively checks the IdentifierFlags.isLocalTypeLoaded flag every 1000ms.
+     */
+    static checkFlag(resolve: any): any;
+    /**
+     * Retrieves all concept variants for a specific type ID filtered by user ID.
+     *
+     * @param typeId - The type ID to search for
+     * @param userId - The user ID to filter by
+     * @returns An array of LConcept objects of the specified type belonging to the specified user
+     *
+     * @remarks
+     * This method retrieves all concepts of a given type that belong to a specific user.
+     * Useful for user-specific concept management and filtering.
+     *
+     * @example
+     * ```typescript
+     * const userConcepts = await LocalBinaryTypeTree.getTypeVariantsFromTreeWithUserId(5, 42);
+     * console.log(`Found ${userConcepts.length} concepts of type 5 for user 42`);
+     * ```
+     */
+    static getTypeVariantsFromTreeWithUserId(typeId: number, userId: number): Promise<LConcept[]>;
+}