mftsccs-node 0.2.6 → 0.2.8

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

@@ -1,8 +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

@@ -1,14 +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

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

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

@@ -1,21 +1,223 @@
+/**
+ * @fileoverview Node implementation for the CompositionBinaryTree.
+ * This module provides the CompositionNode class with AVL tree operations and automatic expiration.
+ * @module DataStructures/Composition/CompositionNode
+ */
 import { Composition } from './Composition';
+/**
+ * Represents a node in the composition binary tree with time-based expiration.
+ *
+ * @remarks
+ * CompositionNode implements an AVL tree node specifically for Composition objects.
+ * Each node has a 10-minute expiration time for automatic cache invalidation.
+ * The node supports all standard AVL tree operations including rotations and balancing.
+ *
+ * @example
+ * ```typescript
+ * const composition = new Composition();
+ * const node = new CompositionNode(123, composition, null, null);
+ * if (node.isValid()) {
+ *   console.log("Node is still valid");
+ * }
+ * ```
+ */
 export declare class CompositionNode {
+    /**
+     * The expiration timestamp for this node.
+     * Defaults to 10 minutes from creation time.
+     */
     expiryTime: Date;
+    /**
+     * The unique key used for tree ordering (composition ID).
+     */
     key: number;
+    /**
+     * The Composition object stored in this node.
+     */
     value: Composition;
+    /**
+     * Reference to the left child node.
+     * Null if no left child exists.
+     */
     leftNode: CompositionNode | null;
+    /**
+     * Reference to the right child node.
+     * Null if no right child exists.
+     */
     rightNode: CompositionNode | null;
+    /**
+     * The height of this node in the tree.
+     * Used for AVL tree balancing calculations.
+     */
     height: number;
+    /**
+     * Creates a new CompositionNode.
+     *
+     * @param key - The unique identifier for this node (composition ID)
+     * @param value - The Composition object to store
+     * @param leftNode - The left child node (or null)
+     * @param rightNode - The right child node (or null)
+     *
+     * @example
+     * ```typescript
+     * const node = new CompositionNode(123, composition, null, null);
+     * ```
+     */
     constructor(key: number, value: Composition, leftNode: CompositionNode | null, rightNode: CompositionNode | null);
+    /**
+     * Checks if this node is still valid (not expired).
+     *
+     * @returns True if the node is valid, false if expired
+     *
+     * @remarks
+     * If the node has expired, it automatically removes itself from the tree.
+     * This ensures automatic cache invalidation after 10 minutes.
+     *
+     * @example
+     * ```typescript
+     * if (node.isValid()) {
+     *   console.log("Node data is still fresh");
+     * } else {
+     *   console.log("Node has expired and been removed");
+     * }
+     * ```
+     */
     isValid(): boolean;
+    /**
+     * Saves data to the composition's cache.
+     *
+     * @param data - The data to be cached in the composition
+     *
+     * @remarks
+     * This is a convenience method to update the cached property of the stored composition.
+     *
+     * @example
+     * ```typescript
+     * node.saveToCache({ processed: true, data: [...] });
+     * ```
+     */
     saveToCache(data: any): void;
+    /**
+     * 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
+     * This method implements the AVL tree insertion algorithm with automatic balancing.
+     * Performs left and right rotations as needed to maintain O(log n) performance.
+     * Also validates nodes during insertion to remove expired entries.
+     *
+     * @example
+     * ```typescript
+     * const newNode = new CompositionNode(456, newComposition, null, null);
+     * node.addNode(newNode, node, node.height);
+     * ```
+     */
     addNode(passedNode: CompositionNode, node: CompositionNode | null, height: number): CompositionNode | null;
+    /**
+     * Performs a right rotation on the given node.
+     *
+     * @param y - The node to rotate right
+     * @returns The new root node after rotation
+     *
+     * @remarks
+     * Right rotation is an AVL tree operation used to rebalance the tree when
+     * the left subtree is too heavy. Updates heights after rotation.
+     */
     rightRotate(y: CompositionNode | null): CompositionNode | null;
+    /**
+     * Performs a left rotation on the given node.
+     *
+     * @param x - The node to rotate left
+     * @returns The new root node after rotation
+     *
+     * @remarks
+     * Left rotation is an AVL tree operation used to rebalance the tree when
+     * the right subtree is too heavy. Updates heights after rotation.
+     */
     leftRotate(x: CompositionNode | null): CompositionNode | 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
+     *
+     * @remarks
+     * Height is used for AVL tree balancing calculations.
+     */
     getHeight(node: CompositionNode | 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)
+     *
+     * @remarks
+     * Balance factor is used to determine if rotations are needed.
+     * Values > 1 or < -1 indicate an unbalanced tree.
+     */
     getBalanceFactor(N: CompositionNode | null): number;
+    /**
+     * Retrieves a node from the tree by its ID.
+     *
+     * @param id - The composition ID to search for
+     * @param node - The current node being evaluated
+     * @returns The matching CompositionNode if found and valid, null otherwise
+     *
+     * @remarks
+     * Performs a binary search through the tree. Validates nodes during retrieval.
+     *
+     * @example
+     * ```typescript
+     * const foundNode = node.getFromNode(123, rootNode);
+     * ```
+     */
     getFromNode(id: number, node: CompositionNode | null): CompositionNode | null;
+    /**
+     * Removes a node from the tree by its ID.
+     *
+     * @param passedNode - The current node being evaluated
+     * @param id - The composition ID to remove
+     * @returns The root node after removal
+     *
+     * @remarks
+     * Implements standard BST deletion with in-order successor replacement.
+     * Maintains tree structure by replacing removed nodes with their successors.
+     *
+     * @example
+     * ```typescript
+     * const newRoot = node.removeNode(rootNode, 123);
+     * ```
+     */
     removeNode(passedNode: CompositionNode | null, id: number): CompositionNode | null;
+    /**
+     * Counts all nodes below and including the given node.
+     *
+     * @param root - The root node to start counting from
+     * @returns The total number of nodes in the subtree
+     *
+     * @remarks
+     * Recursively traverses the entire subtree to count all nodes.
+     *
+     * @example
+     * ```typescript
+     * const count = node.countNodeBelow(rootNode);
+     * console.log(`Subtree contains ${count} nodes`);
+     * ```
+     */
     countNodeBelow(root: CompositionNode | null): number;
+    /**
+     * 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.
+     * Traverses left until finding a node with no left child.
+     */
     inOrderSuccessor(root: CompositionNode): CompositionNode;
 }

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

@@ -1,3 +1,81 @@
+/**
+ * Core data structure representing a Concept in the Freeschema system.
+ * A Concept is the fundamental unit of knowledge/data with metadata for typing,
+ * categorization, security, and relationships. Concepts can reference other concepts
+ * through type, category, and referent relationships.
+ *
+ * @module DataStructures/Concept
+ * @see https://documentation.freeschema.com/#concept for concept documentation
+ */
+/**
+ * Represents a concept with all its metadata and relationships.
+ * A Concept is a typed, categorized piece of data with security controls,
+ * timestamps, and the ability to reference other concepts.
+ *
+ * @class Concept
+ *
+ * @property id - Unique identifier for this concept
+ * @property ghostId - Ghost identifier used for local/offline concepts before backend sync
+ * @property userId - The ID of the user who owns/created this concept
+ * @property typeId - The ID of the concept that defines this concept's type
+ * @property typeUserId - The user ID of the type concept owner
+ * @property categoryId - The ID of the concept that categorizes this concept
+ * @property categoryUserId - The user ID of the category concept owner
+ * @property referentId - The ID of the concept this concept refers to (0 if none)
+ * @property referentUserId - The user ID of the referent concept owner
+ * @property characterValue - The string/text content representing this concept's value
+ * @property securityId - The ID of the security concept controlling access rules
+ * @property securityUserId - The user ID of the security concept owner
+ * @property accessId - The ID of the access concept defining permissions
+ * @property accessUserId - The user ID of the access concept owner
+ * @property sessionInformationId - The ID of the session concept for tracking
+ * @property sessionInformationUserId - The user ID of the session concept owner
+ * @property entryTimeStamp - Timestamp when this concept was created
+ * @property updatedTimeStamp - Timestamp when this concept was last updated
+ * @property referent - Reference to the actual Concept object this concept refers to (lazy loaded)
+ * @property type - Reference to the actual Concept object defining this concept's type (lazy loaded)
+ * @property isNew - Flag indicating if this concept is newly created and needs backend sync
+ * @property updateRecursion - Flag enabling recursive updates through composition hierarchies
+ * @property isTemp - Flag indicating if this is a temporary concept (not persisted to backend)
+ * @property x - X coordinate for UI visualization/drawing
+ * @property y - Y coordinate for UI visualization/drawing
+ *
+ * @example
+ * ```typescript
+ * // Create a concept representing a person
+ * const person = new Concept(
+ *   1001,              // id
+ *   1,                 // userId
+ *   20, 1,             // typeId (Person type), typeUserId
+ *   10, 1,             // categoryId (People category), categoryUserId
+ *   0, 0,              // referentId (no referent), referentUserId
+ *   'John Doe',        // characterValue
+ *   30, 1,             // securityId, securityUserId
+ *   40, 1,             // accessId, accessUserId
+ *   50, 1,             // sessionInformationId, sessionInformationUserId
+ *   true,              // isNew
+ *   new Date(),        // entryTimeStamp
+ *   new Date()         // updatedTimeStamp
+ * );
+ *
+ * console.log(person.characterValue);  // 'John Doe'
+ * console.log(person.isNew);           // true
+ * person.getType();                    // Logs the typeId
+ * ```
+ *
+ * @remarks
+ * The Concept class implements a flexible, self-describing data model where:
+ * - Every concept has a type (which is itself a concept)
+ * - Every concept belongs to a category (which is itself a concept)
+ * - Concepts can refer to other concepts via the referent relationship
+ * - Security and access control are handled through concept references
+ * - All metadata is versioned with timestamps
+ * - Concepts support both backend-synced and local-only (temporary) modes
+ *
+ * @see ConceptsData for the global concept storage and management
+ * @see CreateTheConcept for creating new concepts
+ * @see https://documentation.freeschema.com/#concept for detailed concept documentation
+ */
 export declare class Concept {
     x: number;
     y: number;
@@ -24,6 +102,38 @@ export declare class Concept {
     isNew: boolean;
     updateRecursion: boolean;
     isTemp: boolean;
+    /**
+     * Creates a new Concept instance with all required metadata.
+     *
+     * @param id - Unique identifier for this concept
+     * @param userId - The ID of the user who owns this concept
+     * @param typeId - The ID of the type concept defining this concept's type
+     * @param typeUserId - The user ID of the type concept owner
+     * @param categoryId - The ID of the category concept this belongs to
+     * @param categoryUserId - The user ID of the category concept owner
+     * @param referentId - The ID of the referent concept (0 if none)
+     * @param referentUserId - The user ID of the referent concept owner
+     * @param characterValue - The string value representing this concept
+     * @param securityId - The ID of the security concept for access control
+     * @param securityUserId - The user ID of the security concept owner
+     * @param accessId - The ID of the access concept defining permissions
+     * @param accessUserId - The user ID of the access concept owner
+     * @param sessionId - The ID of the session concept for tracking
+     * @param sessionUserId - The user ID of the session concept owner
+     * @param isNew - Whether this is a newly created concept needing sync (default: false)
+     * @param entryTimeStamp - Creation timestamp
+     * @param updatedTimeStamp - Last update timestamp
+     */
     constructor(id: number, userId: number, typeId: number, typeUserId: number, categoryId: number, categoryUserId: number, referentId: number, referentUserId: number, characterValue: string, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionId: number, sessionUserId: number, isNew: boolean | undefined, entryTimeStamp: Date | string, updatedTimeStamp: Date | string);
+    /**
+     * Logs the typeId of this concept to the console.
+     * This is a utility method for debugging and inspecting the concept's type.
+     *
+     * @example
+     * ```typescript
+     * const concept = new Concept(...);
+     * concept.getType();  // Logs the typeId to console
+     * ```
+     */
     getType(): void;
 }