mftsccs-node 0.0.56 → 0.0.58

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

@@ -0,0 +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;
+}

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

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Static repository for managing character data in the CCS-JS system.
+ * @module DataStructures/CharacterRepository
+ */
+import { TheCharacter } from "./TheCharacter";
+/**
+ * Manages a static collection of character entities with indexed storage and retrieval.
+ *
+ * @remarks
+ * CharacterRepository provides a centralized, static repository for storing and retrieving
+ * TheCharacter instances. Characters are stored in an array indexed by their ID for fast
+ * access. The class also provides lookup functionality to find characters by their data value.
+ *
+ * This repository uses static methods and properties, meaning the character collection is
+ * shared across all instances of the class. The instance method `name` is provided for
+ * identification purposes only.
+ *
+ * @example
+ * ```typescript
+ * // Add a character to the repository
+ * const char = new TheCharacter(1, "A", 100, 1, 200, 1, 300, 1, "2025-10-30", false);
+ * CharacterRepository.AddCharacter(char);
+ *
+ * // Retrieve character by data value
+ * const found = CharacterRepository.GetCharacter("A");
+ * if (found.id !== 0) {
+ *   console.log('Found character:', found.data);
+ * }
+ * ```
+ */
+export declare class CharacterRepository {
+    /**
+     * Descriptive name for this character repository.
+     * @defaultValue "character Repository"
+     */
+    name: string;
+    /**
+     * Creates a new CharacterRepository instance.
+     *
+     * @remarks
+     * While the class can be instantiated, the primary functionality is accessed
+     * through static methods. Instances are mainly useful for accessing the descriptive
+     * name property.
+     *
+     * @example
+     * ```typescript
+     * const repo = new CharacterRepository();
+     * console.log(repo.name); // "character Repository"
+     * ```
+     */
+    constructor();
+    /**
+     * Static array holding all character data indexed by character ID.
+     *
+     * @remarks
+     * Characters are stored at index positions corresponding to their ID values.
+     * This provides O(1) access time when retrieving characters by ID, but may
+     * result in sparse arrays if character IDs are not sequential.
+     *
+     * This array should be managed through the static methods provided by the class.
+     */
+    static characterData: TheCharacter[];
+    /**
+     * Adds a character to the repository, indexed by its ID.
+     *
+     * @param character - The character to add to the repository
+     *
+     * @remarks
+     * The character is stored at the array index matching its ID value. If a character
+     * with the same ID already exists, it will be overwritten. This indexed approach
+     * allows for fast retrieval by ID but may create sparse arrays.
+     *
+     * @example
+     * ```typescript
+     * const char1 = new TheCharacter(1, "A", 100, 1, 200, 1, 300, 1, "2025-10-30", false);
+     * const char2 = new TheCharacter(5, "B", 100, 1, 200, 1, 300, 1, "2025-10-30", false);
+     *
+     * CharacterRepository.AddCharacter(char1);
+     * CharacterRepository.AddCharacter(char2);
+     *
+     * // char1 is at index 1, char2 is at index 5
+     * console.log(CharacterRepository.characterData[1].data); // "A"
+     * ```
+     */
+    static AddCharacter(character: TheCharacter): void;
+    /**
+     * Retrieves a character from the repository by matching its data value.
+     *
+     * @param value - The data string to search for
+     * @returns The matching TheCharacter instance, or a default empty character if not found
+     *
+     * @remarks
+     * Performs a linear search through the entire characterData array to find a character
+     * whose `data` property matches the provided value. If no match is found, returns a
+     * default TheCharacter instance with ID 0 and data "0".
+     *
+     * Note: The default character returned has all numeric fields set to 0, data set to "0",
+     * and isNew set to false. Callers should check the ID to determine if a valid character
+     * was found (a valid character should have a non-zero ID).
+     *
+     * @example
+     * ```typescript
+     * const char = new TheCharacter(1, "A", 100, 1, 200, 1, 300, 1, "2025-10-30", false);
+     * CharacterRepository.AddCharacter(char);
+     *
+     * // Find existing character
+     * const found = CharacterRepository.GetCharacter("A");
+     * console.log(found.id); // 1
+     *
+     * // Search for non-existent character
+     * const notFound = CharacterRepository.GetCharacter("Z");
+     * console.log(notFound.id); // 0 (default)
+     * console.log(notFound.data); // "0" (default)
+     * ```
+     */
+    static GetCharacter(value: string): TheCharacter;
+}

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

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Composition data structure for managing complex concept relationships.
+ * This module provides the core Composition class for building and managing hierarchical
+ * concept structures with caching and distributed system synchronization.
+ * @module DataStructures/Composition/Composition
+ */
+import { Connection } from '../../DataStructures/Connection';
+import { Concept } from '../../DataStructures/Concept';
+/**
+ * Represents a composition of concepts and their relationships.
+ *
+ * @remarks
+ * A Composition is a hierarchical structure that combines multiple concepts through connections.
+ * It supports caching for performance optimization and can synchronize updates across distributed systems
+ * via MQTT messaging. Compositions can contain subcompositions for complex nested structures.
+ *
+ * @example
+ * ```typescript
+ * const composition = new Composition();
+ * composition.id = 123;
+ * composition.mainConcept = myConcept;
+ * await composition.updateCache();
+ * const data = composition.GetDataCache();
+ * ```
+ */
+export declare class Composition {
+    /**
+     * Unique identifier for this composition.
+     */
+    id: number;
+    /**
+     * The primary concept at the root of this composition.
+     * Defaults to a default concept if not set.
+     */
+    mainConcept: Concept;
+    /**
+     * Array of connections between concepts in this composition.
+     */
+    connections: Connection[];
+    /**
+     * Array of all concepts included in this composition.
+     */
+    concepts: Concept[];
+    /**
+     * Array of IDs referencing nested subcompositions.
+     */
+    subcompositions: number[];
+    /**
+     * Cached composition data for performance optimization.
+     * Stores the processed composition structure.
+     */
+    cached: any;
+    /**
+     * Updates the composition cache by recursively fetching related data.
+     *
+     * @returns A promise that resolves when the cache is updated
+     *
+     * @remarks
+     * This method performs the following operations:
+     * 1. Sets the mainConcept if not already set (by matching ID with concepts array)
+     * 2. Recursively fetches all related concepts, connections, and subcompositions
+     * 3. Stores the result in the cached property for fast retrieval
+     *
+     * @example
+     * ```typescript
+     * await composition.updateCache();
+     * console.log("Cache updated:", composition.cached);
+     * ```
+     */
+    updateCache(): Promise<void>;
+    /**
+     * Publishes a composition update message to the distributed system.
+     *
+     * @remarks
+     * This method broadcasts an update notification via MQTT to inform other
+     * system components that this composition has been modified. Only publishes
+     * if the composition has a valid (non-zero) ID.
+     *
+     * @example
+     * ```typescript
+     * composition.UpdateAcrossDistributedSystem();
+     * // Other system nodes will receive the update notification
+     * ```
+     */
+    UpdateAcrossDistributedSystem(): void;
+    /**
+     * Triggers a distributed system update notification.
+     *
+     * @remarks
+     * This is a convenience method that calls UpdateAcrossDistributedSystem.
+     * Indicates that the composition is being updated and needs to notify other system nodes.
+     *
+     * @example
+     * ```typescript
+     * composition.isUpdating();
+     * ```
+     */
+    isUpdating(): void;
+    /**
+     * Retrieves the cached composition data in a structured format.
+     *
+     * @returns An object containing the formatted cache data with the composition ID
+     *
+     * @remarks
+     * The returned object has the following structure:
+     * - `data`: An object keyed by the main concept's type characterValue
+     * - `id`: The composition's ID
+     *
+     * @example
+     * ```typescript
+     * const cacheData = composition.GetDataCache();
+     * console.log("Composition ID:", cacheData.id);
+     * console.log("Cached data:", cacheData.data);
+     * ```
+     */
+    GetDataCache(): any;
+}

package/dist/types/DataStructures/Composition/CompositionBinaryTree.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Binary tree data structure for managing compositions.
+ * This module provides an efficient AVL tree implementation for storing and retrieving compositions.
+ * @module DataStructures/Composition/CompositionBinaryTree
+ */
+import { Composition } from './Composition';
+import { CompositionNode } from './CompositionNode';
+/**
+ * Binary tree data structure for managing compositions with automatic expiration.
+ *
+ * @remarks
+ * This class implements an AVL tree specifically designed for storing Composition objects.
+ * Each node in the tree has an expiration time, allowing automatic cache invalidation.
+ * The tree provides O(log n) operations for insert, search, and delete.
+ *
+ * @example
+ * ```typescript
+ * const composition = new Composition();
+ * composition.id = 123;
+ * CompositionBinaryTree.addCompositionToTree(composition);
+ * const node = await CompositionBinaryTree.getNodeFromTree(123);
+ * ```
+ */
+export declare class CompositionBinaryTree {
+    /**
+     * The root node of the composition binary tree.
+     * Null if the tree is empty.
+     */
+    static root: CompositionNode | null;
+    /**
+     * Adds a composition node to the binary tree.
+     *
+     * @param node - The CompositionNode 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 AVL tree balancing algorithm.
+     *
+     * @example
+     * ```typescript
+     * const node = new CompositionNode(123, composition, null, null);
+     * CompositionBinaryTree.addNodeToTree(node);
+     * ```
+     */
+    static addNodeToTree(node: CompositionNode): CompositionNode | undefined;
+    /**
+     * Creates a node from a composition and adds it to the tree.
+     *
+     * @param composition - The Composition object to be added to the tree
+     *
+     * @remarks
+     * This is a convenience method that wraps the composition in a CompositionNode
+     * and adds it to the tree. The node is keyed by the composition's ID.
+     *
+     * @example
+     * ```typescript
+     * const composition = new Composition();
+     * composition.id = 123;
+     * CompositionBinaryTree.addCompositionToTree(composition);
+     * ```
+     */
+    static addCompositionToTree(composition: Composition): void;
+    /**
+     * Retrieves a composition node from the tree by its ID.
+     *
+     * @param id - The numeric ID of the composition to retrieve
+     * @returns The CompositionNode if found and valid, null otherwise
+     *
+     * @remarks
+     * This method performs a binary search through the tree.
+     * The node's validity is checked during retrieval (expiration check).
+     *
+     * @example
+     * ```typescript
+     * const node = await CompositionBinaryTree.getNodeFromTree(123);
+     * if (node) {
+     *   console.log("Found composition:", node.value);
+     * }
+     * ```
+     */
+    static getNodeFromTree(id: number): Promise<CompositionNode | null>;
+    /**
+     * Removes a composition node from the tree by its ID.
+     *
+     * @param id - The numeric ID of the composition 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 CompositionBinaryTree.removeNodeFromTree(123);
+     * ```
+     */
+    static removeNodeFromTree(id: number): Promise<void>;
+    /**
+     * Counts the total number of nodes in the tree.
+     *
+     * @returns The total number of composition nodes in the tree
+     *
+     * @remarks
+     * This method recursively traverses the entire tree to count all nodes.
+     * Returns 0 if the tree is empty.
+     *
+     * @example
+     * ```typescript
+     * const count = CompositionBinaryTree.countNumberOfNodes();
+     * console.log(`Tree contains ${count} compositions`);
+     * ```
+     */
+    static countNumberOfNodes(): number;
+}