mftsccs-node 0.0.57 → 0.0.59

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

@@ -1,11 +1,126 @@
+/**
+ * @fileoverview Binary tree data structure for managing connections.
+ * This module provides an AVL tree implementation for efficient storage and retrieval of Connection objects.
+ * @module DataStructures/ConnectionBinaryTree/ConnectionBinaryTree
+ */
 import { Connection } from "../../DataStructures/Connection";
 import { ConnectionNode } from "./ConnectionNode";
+/**
+ * Binary tree data structure for managing connections with efficient ID-based lookup.
+ *
+ * @remarks
+ * This class implements a self-balancing AVL tree for storing Connection objects.
+ * It provides O(log n) search, insertion, and deletion operations. The tree supports
+ * asynchronous data loading with timeout capabilities and integrates with the
+ * IdentifierFlags system for data synchronization.
+ *
+ * @example
+ * ```typescript
+ * const connection = new Connection(123, ...);
+ * ConnectionBinaryTree.addConnectionToTree(connection);
+ * const node = await ConnectionBinaryTree.getNodeFromTree(123);
+ * ```
+ */
 export declare class ConnectionBinaryTree {
+    /**
+     * The root node of the connection binary tree.
+     * Null if the tree is empty.
+     */
     static connectionroot: ConnectionNode | null;
+    /**
+     * Adds a connection node to the binary tree.
+     *
+     * @param node - The ConnectionNode 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 using the AVL tree balancing algorithm.
+     *
+     * @example
+     * ```typescript
+     * const node = new ConnectionNode(123, connection, null, null);
+     * ConnectionBinaryTree.addNodeToTree(node);
+     * ```
+     */
     static addNodeToTree(node: ConnectionNode): ConnectionNode | undefined;
+    /**
+     * Creates a node from a connection and adds it to the tree.
+     *
+     * @param connection - The Connection object to be added to the tree
+     *
+     * @remarks
+     * This is a convenience method that wraps the connection in a ConnectionNode
+     * and adds it to the tree. The node is keyed by the connection's ID.
+     *
+     * @example
+     * ```typescript
+     * const connection = new Connection(123, 1, 2, 3, 4, 5);
+     * ConnectionBinaryTree.addConnectionToTree(connection);
+     * ```
+     */
     static addConnectionToTree(connection: Connection): void;
+    /**
+     * Waits for connection 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.isConnectionLoaded flag every second.
+     * Useful for ensuring data is ready before performing operations on the tree.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await ConnectionBinaryTree.waitForDataToLoad();
+     *   console.log("Connection data loaded");
+     * } catch (error) {
+     *   console.log("Loading timed out");
+     * }
+     * ```
+     */
     static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Periodically checks if connection data has been loaded.
+     *
+     * @param resolve - The promise resolve function to call when data is loaded
+     *
+     * @remarks
+     * This method recursively checks the IdentifierFlags.isConnectionLoaded flag every 1000ms.
+     */
     static checkFlag(resolve: any): any;
+    /**
+     * Removes a connection node from the tree by its ID.
+     *
+     * @param id - The numeric ID of the connection to remove
+     *
+     * @remarks
+     * This method removes a node from the tree while maintaining AVL balance.
+     * The tree is automatically rebalanced after removal.
+     *
+     * @example
+     * ```typescript
+     * await ConnectionBinaryTree.removeNodeFromTree(123);
+     * ```
+     */
     static removeNodeFromTree(id: number): Promise<void>;
+    /**
+     * Retrieves a connection node from the tree by its ID.
+     *
+     * @param id - The numeric ID of the connection to retrieve
+     * @returns The ConnectionNode if found, the root node otherwise
+     *
+     * @remarks
+     * This method performs a binary search through the tree using the connection ID as the key.
+     * The search has O(log n) time complexity in a balanced tree.
+     *
+     * @example
+     * ```typescript
+     * const node = await ConnectionBinaryTree.getNodeFromTree(123);
+     * if (node) {
+     *   console.log("Found connection:", node.value);
+     * }
+     * ```
+     */
     static getNodeFromTree(id: number): Promise<ConnectionNode | null>;
 }

package/dist/types/DataStructures/ConnectionBinaryTree/ConnectionNode.d.ts

@@ -1,24 +1,193 @@
+/**
+ * @fileoverview Node implementation for the ConnectionBinaryTree.
+ * This module provides the ConnectionNode class with AVL tree operations and variant management.
+ * @module DataStructures/ConnectionBinaryTree/ConnectionNode
+ */
 import { Connection } from "./../Connection";
+/**
+ * Represents a node in the connection binary tree with support for variants.
+ *
+ * @remarks
+ * ConnectionNode implements an AVL tree node for Connection objects with special
+ * support for managing connection variants (multiple connections with the same key).
+ * Each node can store multiple connection variants in the variants array, allowing
+ * efficient grouping of related connections by type or other criteria.
+ *
+ * @example
+ * ```typescript
+ * const connection = new Connection(123, 1, 2, 3, 4, 5);
+ * const node = new ConnectionNode(123, connection, null, null);
+ * ```
+ */
 export declare class ConnectionNode {
+    /**
+     * The key used for tree ordering (typically connection ID or type ID).
+     */
     key: any;
+    /**
+     * The Connection object stored in this node.
+     */
     value: Connection;
+    /**
+     * Reference to the left child node.
+     */
     leftNode: ConnectionNode | null;
+    /**
+     * Reference to the right child node.
+     */
     rightNode: ConnectionNode | null;
+    /**
+     * Reference to current node for variant chaining.
+     */
     currentNode: ConnectionNode | null;
+    /**
+     * Array of variant nodes that share the same key.
+     * Used for storing multiple connections with the same type or identifier.
+     */
     variants: ConnectionNode[];
+    /**
+     * The height of this node in the tree.
+     * Used for AVL tree balancing calculations.
+     */
     height: number;
+    /**
+     * Creates a new ConnectionNode.
+     *
+     * @param key - The key for tree ordering
+     * @param value - The Connection object to store
+     * @param leftNode - The left child node (or null)
+     * @param rightNode - The right child node (or null)
+     *
+     * @example
+     * ```typescript
+     * const node = new ConnectionNode(123, connection, null, null);
+     * ```
+     */
     constructor(key: any, value: Connection, leftNode: ConnectionNode | null, rightNode: ConnectionNode | null);
+    /**
+     * Adds a node to the current node chain by type ID.
+     *
+     * @param passedNode - The node to add
+     * @param node - The current node in the chain
+     * @returns The updated node chain
+     *
+     * @remarks
+     * Used internally for managing connection variants with different type IDs.
+     */
     addCurrentNode(passedNode: ConnectionNode, node: ConnectionNode | null): ConnectionNode;
+    /**
+     * Adds a connection variant to this node's variants array.
+     *
+     * @param passedNode - The variant node to add
+     * @param node - The current node
+     * @returns The updated node with the new variant
+     *
+     * @remarks
+     * This method ensures no duplicate connections are added by checking IDs.
+     * Variants are stored in the variants array for efficient retrieval.
+     */
     addCurrentNodeType(passedNode: ConnectionNode, node: ConnectionNode | null): ConnectionNode;
+    /**
+     * Adds a new node to the tree with AVL balancing.
+     *
+     * @param passedNode - The node to be added
+     * @param node - The current node being evaluated
+     * @param height - The height of the current node
+     * @returns The root node after insertion and balancing
+     *
+     * @remarks
+     * Implements AVL tree insertion with automatic balancing through rotations.
+     */
     addNode(passedNode: ConnectionNode, node: ConnectionNode | null, height: number): ConnectionNode | null;
+    /**
+     * Adds a node to the tree indexed by type ID with variant support.
+     *
+     * @param passedNode - The node to be added
+     * @param node - The current node being evaluated
+     * @param height - The height of the current node
+     * @returns The root node after insertion and balancing
+     *
+     * @remarks
+     * This method is similar to addNode but specifically handles type-based indexing
+     * and manages connection variants that share the same type ID.
+     */
     addTypeNode(passedNode: ConnectionNode, node: ConnectionNode | null, height: number): ConnectionNode | null;
+    /**
+     * Performs a right rotation on the given node for AVL balancing.
+     *
+     * @param y - The node to rotate right
+     * @returns The new root node after rotation
+     */
     rightRotate(y: ConnectionNode | null): ConnectionNode | null;
+    /**
+     * Performs a left rotation on the given node for AVL balancing.
+     *
+     * @param x - The node to rotate left
+     * @returns The new root node after rotation
+     */
     leftRotate(x: ConnectionNode | null): ConnectionNode | null;
+    /**
+     * Gets the height of a node.
+     *
+     * @param node - The node to get the height from
+     * @returns The height of the node, or 0 if null
+     */
     getHeight(node: ConnectionNode | null): number;
+    /**
+     * Calculates the balance factor of a node.
+     *
+     * @param N - The node to calculate the balance factor for
+     * @returns The balance factor (difference between left and right heights)
+     */
     getBalanceFactor(N: ConnectionNode | null): number;
+    /**
+     * Retrieves a node from the tree by its numeric ID.
+     *
+     * @param id - The connection ID to search for
+     * @param node - The current node being evaluated
+     * @returns The matching ConnectionNode if found, null otherwise
+     */
     getFromNode(id: number, node: ConnectionNode | null): ConnectionNode | null;
+    /**
+     * Retrieves a node from the tree by its character/string value.
+     *
+     * @param value - The character value to search for
+     * @param node - The current node being evaluated
+     * @returns The matching ConnectionNode if found, null otherwise
+     */
     getCharacterFromNode(value: string, node: ConnectionNode | null): ConnectionNode | null;
+    /**
+     * Removes a node from the tree by its ID.
+     *
+     * @param passedNode - The current node being evaluated
+     * @param id - The connection ID to remove
+     * @returns The root node after removal
+     *
+     * @remarks
+     * Implements standard BST deletion with in-order successor replacement.
+     */
     removeNode(passedNode: ConnectionNode | null, id: number): ConnectionNode | null;
+    /**
+     * Removes a specific variant from a node or the entire node if no variants remain.
+     *
+     * @param passedNode - The current node being evaluated
+     * @param typeIdentifier - The type identifier of the node
+     * @param conceptId - The specific connection ID to remove
+     * @returns The root node after removal
+     *
+     * @remarks
+     * This method handles removal of connection variants. If the main value matches,
+     * it's replaced by the first variant. If a variant matches, only that variant is removed.
+     */
     removeNodeWithVariants(passedNode: ConnectionNode | null, typeIdentifier: any, conceptId: number): ConnectionNode | null;
+    /**
+     * Finds the in-order successor of a node.
+     *
+     * @param root - The node to find the successor from
+     * @returns The in-order successor node (leftmost node in right subtree)
+     *
+     * @remarks
+     * Used during node deletion to find the replacement node.
+     */
     inOrderSuccessor(root: ConnectionNode): ConnectionNode;
 }

package/dist/types/DataStructures/ConnectionBinaryTree/ConnectionTypeTree.d.ts

@@ -1,13 +1,95 @@
+/**
+ * @fileoverview Binary tree for managing connections indexed by type ID.
+ * This module provides a specialized tree for efficient type-based connection lookups and variant retrieval.
+ * @module DataStructures/ConnectionBinaryTree/ConnectionTypeTree
+ */
 import { Connection } from "../../DataStructures/Connection";
 import { ConnectionNode } from "./ConnectionNode";
+/**
+ * Binary tree data structure for managing connections indexed by type ID.
+ *
+ * @remarks
+ * This class implements an AVL tree optimized for type-based connection lookups.
+ * It enables efficient retrieval of all connections of a specific type and supports
+ * variant management for grouping related connections.
+ *
+ * @example
+ * ```typescript
+ * const connection = new Connection(123, 1, 2, 3, 4, 5);
+ * ConnectionTypeTree.addConnectionToTree(connection);
+ * const variants = await ConnectionTypeTree.getTypeVariantsFromTree(5);
+ * ```
+ */
 export declare class ConnectionTypeTree {
+    /**
+     * The root node of the type-indexed connection tree.
+     * Null if the tree is empty.
+     */
     static connectionTypeRoot: ConnectionNode | null;
+    /**
+     * Adds a connection node to the type-indexed tree.
+     *
+     * @param node - The ConnectionNode to be added
+     * @returns The root node after insertion
+     *
+     * @remarks
+     * Uses the addTypeNode method for type-based insertion with variant support.
+     */
     static addNodeToTree(node: ConnectionNode): Promise<ConnectionNode | null>;
+    /**
+     * Waits for connection type data to be loaded.
+     *
+     * @returns A promise that resolves when data is loaded, or rejects after 25 seconds
+     */
     static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Periodically checks if connection type data has been loaded.
+     *
+     * @param resolve - The promise resolve function to call when data is loaded
+     */
     static checkFlag(resolve: any): any;
+    /**
+     * Creates a node from a connection and adds it to the type tree.
+     *
+     * @param connection - The Connection object to be added
+     *
+     * @remarks
+     * Only adds the connection if it has a non-zero typeId.
+     */
     static addConnectionToTree(connection: Connection): void;
+    /**
+     * Removes a specific connection variant from the tree.
+     *
+     * @param typeId - The type ID identifying the node
+     * @param id - The connection ID to remove
+     */
     static removeTypeConcept(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 ConnectionNode if found, the root node otherwise
+     */
     static getNodeFromTree(id: number): ConnectionNode | null;
+    /**
+     * Retrieves all connection variants for a specific type ID.
+     *
+     * @param typeId - The type ID to search for
+     * @returns An array of Connection objects of the specified type
+     *
+     * @remarks
+     * Returns the primary connection and all its variants that share the same type ID.
+     */
     static getTypeVariantsFromTree(typeId: number): Promise<Connection[] | undefined>;
+    /**
+     * Retrieves all connection 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 Connection objects of the specified type belonging to the specified user
+     *
+     * @remarks
+     * Useful for user-specific connection management and filtering.
+     */
     static getTypeVariantsFromTreeWithUserId(typeId: number, userId: number): Promise<Connection[]>;
 }

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

@@ -1,18 +1,209 @@
+/**
+ * @fileoverview ConnectionData module for managing connection storage and retrieval in CCS-JS.
+ * This module provides centralized management of connections using binary tree indexing
+ * for efficient ID-based and type-based lookups.
+ * @module DataStructures/ConnectionData
+ */
 import { Connection } from "./Connection";
+/**
+ * Central repository for managing all connections in the CCS system.
+ * Provides binary tree indexing for efficient connection retrieval by ID and type.
+ * Maintains both in-memory (tree structures) and persistent (IndexedDB) storage.
+ *
+ * @class ConnectionData
+ * @example
+ * ```typescript
+ * // Add a connection to the system
+ * ConnectionData.AddConnection(myConnection);
+ *
+ * // Retrieve a connection by ID
+ * const connection = await ConnectionData.GetConnection(123);
+ *
+ * // Get connections of a composition type
+ * const connections = await ConnectionData.GetConnectionsOfCompositionLocal(10);
+ * ```
+ *
+ * @remarks
+ * This class uses static methods and properties, functioning as a singleton data store.
+ * It coordinates ID-based and type-based indexing for optimized query performance.
+ */
 export declare class ConnectionData {
+    /** Name identifier for this data structure */
     name: string;
+    /**
+     * Creates a new ConnectionData instance.
+     * @remarks This is rarely instantiated as the class primarily uses static methods.
+     */
     constructor();
+    /** Legacy array storage for connections (deprecated in favor of tree structures) */
     static connectionArray: Connection[];
+    /** Dictionary-style storage for quick connection lookups by ID */
     static connectionDictionary: Connection[];
+    /**
+     * Checks if a connection already exists in the connections array.
+     *
+     * @param {Connection} connection - The connection to check for existence
+     * @returns {boolean} True if the connection exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const exists = ConnectionData.CheckContains(myConnection);
+     * if (!exists) {
+     *   // Add the connection
+     * }
+     * ```
+     */
     static CheckContains(connection: Connection): boolean;
+    /**
+     * Adds a connection to persistent storage (IndexedDB) only.
+     * Does not update in-memory tree structures.
+     *
+     * @param {Connection} connection - The connection to store persistently
+     *
+     * @example
+     * ```typescript
+     * ConnectionData.AddConnectionToStorage(myConnection);
+     * ```
+     */
     static AddConnectionToStorage(connection: Connection): void;
+    /**
+     * Adds a connection to both persistent storage and all in-memory tree indexes.
+     * This is the primary method for adding connections to the system.
+     *
+     * @param {Connection} connection - The connection to add
+     *
+     * @example
+     * ```typescript
+     * const newConnection = new Connection(...);
+     * ConnectionData.AddConnection(newConnection);
+     * ```
+     *
+     * @remarks
+     * Updates two tree structures:
+     * - ConnectionBinaryTree (ID-based lookup)
+     * - ConnectionTypeTree (type-based lookup)
+     * Skips temporary connections (isTemp = true)
+     */
     static AddConnection(connection: Connection): void;
+    /**
+     * Adds a connection to in-memory tree structures only, without persisting to storage.
+     * Useful for temporary connections or when storage is handled separately.
+     *
+     * @param {Connection} connection - The connection to add to memory
+     *
+     * @example
+     * ```typescript
+     * ConnectionData.AddConnectionToMemory(temporaryConnection);
+     * ```
+     *
+     * @remarks
+     * Updates tree structures without touching IndexedDB.
+     * Skips temporary connections (isTemp = true)
+     */
     static AddConnectionToMemory(connection: Connection): void;
+    /**
+     * Adds a connection to the dictionary for quick ID-based lookups.
+     *
+     * @param {Connection} connection - The connection to add to dictionary
+     *
+     * @example
+     * ```typescript
+     * ConnectionData.AddToDictionary(myConnection);
+     * ```
+     */
     static AddToDictionary(connection: Connection): void;
+    /**
+     * Removes a connection from all storage locations (memory trees and persistent storage).
+     *
+     * @param {Connection} connection - The connection to remove
+     *
+     * @example
+     * ```typescript
+     * ConnectionData.RemoveConnection(obsoleteConnection);
+     * ```
+     *
+     * @remarks
+     * Removes from:
+     * - IndexedDB persistent storage
+     * - ConnectionBinaryTree (ID index)
+     * - ConnectionTypeTree (type index)
+     * Only processes connections with valid IDs (id != 0)
+     */
     static RemoveConnection(connection: Connection): void;
+    /**
+     * Returns the root node of the connection binary tree.
+     * Used for direct tree traversal or debugging.
+     *
+     * @returns {Node | null} The root node of the connection tree
+     *
+     * @example
+     * ```typescript
+     * const tree = ConnectionData.GetConnectionTree();
+     * if (tree) {
+     *   console.log("Tree root:", tree.key);
+     * }
+     * ```
+     */
     static GetConnectionTree(): import("./ConnectionBinaryTree/ConnectionNode").ConnectionNode | null;
+    /**
+     * Returns the root node of the connection type tree.
+     * Used for direct tree traversal or debugging.
+     *
+     * @returns {Node | null} The root node of the connection type tree
+     *
+     * @example
+     * ```typescript
+     * const tree = ConnectionData.GetConnectionTypeTree();
+     * ```
+     */
     static GetConnectionTypeTree(): import("./ConnectionBinaryTree/ConnectionNode").ConnectionNode | null;
+    /**
+     * Retrieves a connection by its ID from the binary tree index.
+     *
+     * @param {number} id - The connection ID to retrieve
+     * @returns {Promise<Connection>} The connection if found, or a default connection if not found
+     *
+     * @example
+     * ```typescript
+     * const connection = await ConnectionData.GetConnection(123);
+     * if (connection.id !== 0) {
+     *   console.log("Found connection:", connection.ofTheConceptId, "->", connection.toTheConceptId);
+     * }
+     * ```
+     *
+     * @remarks
+     * Returns a default connection (id = 0) if the connection is not found.
+     * Uses ConnectionBinaryTree for O(log n) lookup performance.
+     */
     static GetConnection(id: number): Promise<Connection>;
+    /**
+     * Retrieves all connections of a specific composition type ID from the type tree.
+     * Includes the main connection and all its variants.
+     *
+     * @param {number} id - The type ID to filter by
+     * @returns {Promise<Connection[]>} Array of connections with the specified type
+     *
+     * @example
+     * ```typescript
+     * const connections = await ConnectionData.GetConnectionsOfCompositionLocal(10);
+     * console.log(`Found ${connections.length} connections of type 10`);
+     * ```
+     *
+     * @remarks
+     * Uses ConnectionTypeTree to retrieve the main connection and all variant connections.
+     * Returns an empty array if no connections are found for the type.
+     */
     static GetConnectionsOfCompositionLocal(id: number): Promise<Connection[]>;
+    /**
+     * Returns the name identifier of this data structure instance.
+     *
+     * @returns {string} The name "Connection Array"
+     *
+     * @example
+     * ```typescript
+     * const connectionData = new ConnectionData();
+     * console.log(connectionData.getName()); // "Connection Array"
+     * ```
+     */
     getName(): string;
 }

package/dist/types/DataStructures/Count/CountInfo.d.ts

@@ -1,6 +1,79 @@
+/**
+ * @fileoverview Defines the CountInfo class for storing connection count information.
+ * @module DataStructures/Count/CountInfo
+ */
+/**
+ * Represents information about connection counts for a concept.
+ * This class stores the count of connections of a specific type
+ * associated with a particular concept, useful for analytics and statistics.
+ *
+ * @class CountInfo
+ *
+ * @example
+ * ```typescript
+ * const countInfo = new CountInfo();
+ * countInfo.conceptId = 123;
+ * countInfo.connectionTypeId = 456;
+ * countInfo.connectionType = "likes";
+ * countInfo.count = 42;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Tracking follower counts
+ * const followerCount = new CountInfo();
+ * followerCount.conceptId = 100; // User ID
+ * followerCount.connectionType = "followers";
+ * followerCount.count = 1523;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple connection counts for a post
+ * const likesCount = new CountInfo();
+ * likesCount.conceptId = 200; // Post ID
+ * likesCount.connectionType = "likes";
+ * likesCount.count = 350;
+ *
+ * const commentsCount = new CountInfo();
+ * commentsCount.conceptId = 200; // Same Post ID
+ * commentsCount.connectionType = "comments";
+ * commentsCount.count = 45;
+ * ```
+ */
 export declare class CountInfo {
+    /**
+     * The ID of the concept for which connections are being counted.
+     * Identifies the entity whose connections are being tracked.
+     *
+     * @type {number}
+     * @default 0
+     */
     conceptId: number;
+    /**
+     * The ID of the connection type being counted.
+     * Identifies which type of connection this count represents.
+     *
+     * @type {number}
+     * @default 0
+     */
     connectionTypeId: number;
+    /**
+     * The string name/description of the connection type.
+     * Human-readable identifier for the type of connection being counted.
+     *
+     * @type {string}
+     * @default ""
+     *
+     * @example "likes", "follows", "comments", "shares"
+     */
     connectionType: string;
+    /**
+     * The number of connections of this type.
+     * The actual count value representing how many connections exist.
+     *
+     * @type {number}
+     * @default 0
+     */
     count: number;
 }