mftsccs-node 0.0.57 → 0.0.59

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

@@ -1,14 +1,106 @@
+/**
+ * @fileoverview Text data structure for the CCS-JS system.
+ * @module DataStructures/TheTexts
+ */
+/**
+ * Represents a text entity in the system with comprehensive metadata and security tracking.
+ *
+ * @remarks
+ * TheTexts class encapsulates text data along with user ownership, security credentials,
+ * access control, session tracking, and timestamp information. This class is similar to
+ * TheCharacter but designed for longer text strings and includes an entry timestamp for
+ * temporal tracking. It provides complete audit trail capabilities through its multiple
+ * user context references.
+ *
+ * @example
+ * ```typescript
+ * const text = new TheTexts(
+ *   1001,                    // userId
+ *   "Hello World",           // data
+ *   5001,                    // securityId
+ *   1001,                    // securityUserId
+ *   6001,                    // accessId
+ *   1001,                    // accessUserId
+ *   7001,                    // sessionId
+ *   1001,                    // sessionUserId
+ *   "2025-10-30T12:00:00Z",  // entryTimestamp
+ *   true                     // isNew
+ * );
+ * ```
+ */
 export declare class TheTexts {
+    /**
+     * Unique identifier for the text entity.
+     * @defaultValue 0
+     */
     id: number;
+    /**
+     * ID of the user who owns this text.
+     */
     userId: number;
+    /**
+     * The actual text data content.
+     */
     data: string;
+    /**
+     * Security level or security context identifier for this text.
+     */
     securityId: number;
+    /**
+     * User ID associated with the security context.
+     */
     securityUserId: number;
+    /**
+     * Access control identifier for this text.
+     */
     accessId: number;
+    /**
+     * User ID associated with the access control.
+     */
     accessUserId: number;
+    /**
+     * Session identifier tracking when this text was accessed.
+     */
     sessionId: number;
+    /**
+     * User ID associated with the session.
+     */
     sessionUserId: number;
+    /**
+     * ISO 8601 timestamp indicating when this text entry was created or modified.
+     */
     entryTimestamp: string;
+    /**
+     * Flag indicating whether this is a newly created text entry.
+     */
     isNew: boolean;
+    /**
+     * Creates a new TheTexts instance.
+     *
+     * @param userId - The ID of the user who owns this text
+     * @param data - The text content
+     * @param securityId - Security level or context identifier
+     * @param securityUserId - User ID for the security context
+     * @param accessId - Access control identifier
+     * @param accessUserId - User ID for access control
+     * @param sessionId - Session tracking identifier
+     * @param sessionUserId - User ID for the session
+     * @param entryTimestamp - ISO 8601 timestamp when the text was created/entered
+     * @param isNew - Whether this is a newly created text entry
+     *
+     * @remarks
+     * Unlike TheCharacter, this constructor stores the entryTimestamp property,
+     * making it suitable for temporal tracking and audit trails.
+     *
+     * @example
+     * ```typescript
+     * const text = new TheTexts(
+     *   1, "Sample text", 100, 1, 200, 1, 300, 1,
+     *   new Date().toISOString(), true
+     * );
+     * console.log(text.data); // "Sample text"
+     * console.log(text.entryTimestamp); // "2025-10-30T12:00:00.000Z"
+     * ```
+     */
     constructor(userId: number, data: string, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionId: number, sessionUserId: number, entryTimestamp: string, isNew: boolean);
 }

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

@@ -1,30 +1,320 @@
+/**
+ * @fileoverview Defines the Transaction class for managing transactional operations.
+ * @module DataStructures/Transaction/Transaction
+ */
 import { Concept } from "../Concept";
 import { Connection } from "../Connection";
+/**
+ * Manages transactional operations for concepts and connections.
+ * This class provides ACID-like transaction capabilities for creating and managing
+ * concepts and connections. It supports rollback functionality and ensures data
+ * consistency by tracking all actions within a transaction context.
+ *
+ * @class Transaction
+ *
+ * @example
+ * ```typescript
+ * const transaction = new Transaction();
+ * await transaction.initialize();
+ *
+ * try {
+ *   const concept = await transaction.MakeTheInstanceConcept(
+ *     "User", "John Doe", false, 1, 4, 999, 0
+ *   );
+ *   await transaction.commitTransaction();
+ * } catch (error) {
+ *   await transaction.rollbackTransaction();
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Complex transaction with multiple operations
+ * const transaction = new Transaction();
+ * await transaction.initialize();
+ *
+ * try {
+ *   const user = await transaction.MakeTheInstanceConcept("User", "Alice", false, 1, 4);
+ *   const post = await transaction.MakeTheInstanceConcept("Post", "My First Post", false, 1, 4);
+ *   await transaction.CreateConnection(user, post, "authored");
+ *   await transaction.commitTransaction();
+ * } catch (error) {
+ *   console.error("Transaction failed:", error);
+ *   await transaction.rollbackTransaction();
+ * }
+ * ```
+ */
 export declare class Transaction {
+    /**
+     * Unique identifier for this transaction.
+     * Generated randomly to track transaction operations.
+     *
+     * @protected
+     * @type {string}
+     */
     protected transactionId: string;
+    /**
+     * Collection of all actions performed within this transaction.
+     * Tracks concepts and connections created or modified during the transaction.
+     *
+     * @type {InnerActions}
+     */
     actions: InnerActions;
+    /**
+     * Flag indicating whether the transaction is still valid.
+     * Set to false on failure or after rollback to prevent further operations.
+     *
+     * @protected
+     * @type {boolean}
+     * @default true
+     */
     protected success: boolean;
+    /**
+     * Creates a new Transaction instance.
+     * Generates a unique transaction ID for tracking purposes.
+     *
+     * @constructor
+     *
+     * @example
+     * ```typescript
+     * const transaction = new Transaction();
+     * await transaction.initialize();
+     * ```
+     */
     constructor();
+    /**
+     * Initializes the transaction in the data store.
+     * Must be called before performing any transactional operations.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If initialization fails
+     *
+     * @example
+     * ```typescript
+     * const transaction = new Transaction();
+     * await transaction.initialize();
+     * ```
+     */
     initialize(): Promise<void>;
     /**
-   * Method to move concepts and connection to transaction collection
-   * @param concept Concept
+   * Marks and persists the current transaction actions.
+   * Internal method to save concepts and connections to the transaction collection.
+   *
+   * @protected
+   * @async
+   * @returns {Promise<void>}
+   *
+   * @remarks
+   * This method is called internally after each concept or connection operation
+   * to ensure actions are tracked for potential rollback.
    */
     protected markAction(): Promise<void>;
     /**
-   * Method to rollback all the tranctions occured
+   * Rolls back all operations performed within this transaction.
+   * Reverts all changes made during the transaction and marks it as expired.
+   * After rollback, no further operations can be performed on this transaction.
+   *
+   * @async
+   * @returns {Promise<void>}
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const concept = await transaction.MakeTheInstanceConcept(...);
+   *   // ... operation that might fail
+   * } catch (error) {
+   *   await transaction.rollbackTransaction();
+   *   console.error("Transaction rolled back due to error:", error);
+   * }
+   * ```
    */
     rollbackTransaction(): Promise<void>;
+    /**
+     * Commits the transaction, making all changes permanent.
+     * Synchronizes all transaction data to the online/persistent store.
+     * After commit, the transaction is marked as expired and cannot be used further.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If the transaction has already expired or failed
+     *
+     * @example
+     * ```typescript
+     * const transaction = new Transaction();
+     * await transaction.initialize();
+     *
+     * try {
+     *   await transaction.MakeTheInstanceConcept("User", "Alice", false, 1, 4);
+     *   await transaction.commitTransaction();
+     *   console.log("Transaction committed successfully");
+     * } catch (error) {
+     *   await transaction.rollbackTransaction();
+     * }
+     * ```
+     */
     commitTransaction(): Promise<void>;
     /**
-   * Concepts
+   * Creates a new instance concept within the transaction.
+   * The concept represents a data instance of a specified type with associated metadata.
+   *
+   * @async
+   * @param {string} type - The type of the concept (e.g., "User", "Post")
+   * @param {string} referent - The value or name of the concept instance
+   * @param {boolean} [composition=false] - Whether this is a composition concept
+   * @param {number} userId - The ID of the user creating the concept
+   * @param {number} accessId - The access level ID for the concept
+   * @param {number} [sessionInformationId=999] - The session information ID
+   * @param {number} [referentId=0] - The referent ID for linking
+   * @returns {Promise<Concept>} The created concept
+   * @throws {Error} If the transaction has expired or creation fails
+   *
+   * @example
+   * ```typescript
+   * const transaction = new Transaction();
+   * await transaction.initialize();
+   *
+   * try {
+   *   const userConcept = await transaction.MakeTheInstanceConcept(
+   *     "User",
+   *     "John Doe",
+   *     false,
+   *     123,
+   *     4,
+   *     999,
+   *     0
+   *   );
+   *   await transaction.commitTransaction();
+   * } catch (error) {
+   *   await transaction.rollbackTransaction();
+   * }
+   * ```
    */
     MakeTheInstanceConcept(type: string, referent: string, composition: boolean | undefined, userId: number, accessId: number, sessionInformationId?: number, referentId?: number): Promise<Concept>;
+    /**
+   * Creates a connection between two concepts within the transaction.
+   * Establishes a typed relationship between source and target concepts.
+   *
+   * @async
+   * @param {Concept} ofTheConcept - The source concept (starting point of the connection)
+   * @param {Concept} toTheConcept - The target concept (endpoint of the connection)
+   * @param {string} typeConnection - The type of connection/relationship
+   * @returns {Promise<Connection>} The created connection
+   * @throws {Error} If the transaction has expired or creation fails
+   *
+   * @example
+   * ```typescript
+   * const transaction = new Transaction();
+   * await transaction.initialize();
+   *
+   * try {
+   *   const user = await transaction.MakeTheInstanceConcept("User", "Alice", false, 1, 4);
+   *   const post = await transaction.MakeTheInstanceConcept("Post", "My Post", false, 1, 4);
+   *   const connection = await transaction.CreateConnection(user, post, "authored");
+   *   await transaction.commitTransaction();
+   * } catch (error) {
+   *   await transaction.rollbackTransaction();
+   * }
+   * ```
+   */
     CreateConnection(ofTheConcept: Concept, toTheConcept: Concept, typeConnection: string): Promise<Connection>;
+    /**
+     * Creates a new type concept within the transaction.
+     * Type concepts define the schema or classification for instance concepts.
+     *
+     * @async
+     * @param {string} typeString - The name of the type to create
+     * @param {number} sessionId - The session ID
+     * @param {number} sessionUserId - The session user ID
+     * @param {number} userId - The ID of the user creating the type
+     * @returns {Promise<Concept>} The created type concept
+     * @throws {Error} If the transaction has expired or creation fails
+     *
+     * @example
+     * ```typescript
+     * const transaction = new Transaction();
+     * await transaction.initialize();
+     *
+     * try {
+     *   const typeConcept = await transaction.MakeTheTypeConcept(
+     *     "CustomType",
+     *     999,
+     *     1,
+     *     1
+     *   );
+     *   await transaction.commitTransaction();
+     * } catch (error) {
+     *   await transaction.rollbackTransaction();
+     * }
+     * ```
+     */
     MakeTheTypeConcept(typeString: string, sessionId: number, sessionUserId: number, userId: number): Promise<Concept>;
+    /**
+     * Creates a connection using concept IDs within the transaction.
+     * This is a more general method for creating connections when working directly with IDs
+     * rather than Concept objects. Provides fine-grained control over connection properties.
+     *
+     * @async
+     * @param {number} ofTheConceptId - The ID of the source concept
+     * @param {number} ofTheConceptUserId - The user ID of the source concept
+     * @param {number} toTheConceptId - The ID of the target concept
+     * @param {number} toTheConceptUserId - The user ID of the target concept
+     * @param {number} typeId - The connection type ID
+     * @param {number} sessionInformationId - The session information ID
+     * @param {number} sessionInformationUserId - The session information user ID
+     * @param {number} [orderId=1] - The order ID for sequencing connections
+     * @param {number} [accessId=4] - The access level ID
+     * @param {number} [passedUserId=999] - The passed user ID for permissions
+     * @returns {Promise<Connection>} The created connection
+     * @throws {Error} If the transaction has expired or creation fails
+     *
+     * @example
+     * ```typescript
+     * const transaction = new Transaction();
+     * await transaction.initialize();
+     *
+     * try {
+     *   const connection = await transaction.CreateTheConnectionGeneral(
+     *     123, 1,  // source concept
+     *     456, 1,  // target concept
+     *     789,     // type ID
+     *     999, 1,  // session info
+     *     1,       // order
+     *     4,       // access
+     *     999      // user
+     *   );
+     *   await transaction.commitTransaction();
+     * } catch (error) {
+     *   await transaction.rollbackTransaction();
+     * }
+     * ```
+     */
     CreateTheConnectionGeneral(ofTheConceptId: number, ofTheConceptUserId: number, toTheConceptId: number, toTheConceptUserId: number, typeId: number, sessionInformationId: number, sessionInformationUserId: number, orderId?: number, accessId?: number, passedUserId?: number): Promise<Connection>;
 }
+/**
+ * Represents the collection of actions within a transaction.
+ * This interface tracks all concepts and connections created or modified
+ * during a transaction for rollback and commit purposes.
+ *
+ * @interface InnerActions
+ *
+ * @example
+ * ```typescript
+ * const actions: InnerActions = {
+ *   concepts: [concept1, concept2],
+ *   connections: [connection1, connection2]
+ * };
+ * ```
+ */
 export interface InnerActions {
+    /**
+     * Array of concepts created or modified in the transaction.
+     * @type {Concept[]}
+     */
     concepts: Concept[];
+    /**
+     * Array of connections created or modified in the transaction.
+     * @type {Connection[]}
+     */
     connections: Connection[];
 }

package/dist/types/DataStructures/User/UserBinaryTree.d.ts

@@ -1,15 +1,132 @@
+/**
+ * @fileoverview Binary tree for managing user-specific concepts and connections.
+ * This module provides a composite-key based tree for efficient user and session-based data storage.
+ * @module DataStructures/User/UserBinaryTree
+ */
 import { LConcept } from "../../DataStructures/Local/LConcept";
 import { UserNode } from "./UserNode";
 import { LConnection } from "../Local/LConnection";
+/**
+ * Binary tree data structure for managing user-specific data with composite keys.
+ *
+ * @remarks
+ * This class implements an AVL tree that uses composite keys (userId + sessionId + randomizer)
+ * to organize user-specific concepts and connections. The composite key enables efficient
+ * organization and retrieval of data by user, session, and application context.
+ *
+ * @example
+ * ```typescript
+ * const concept = new LConcept(123, "example", 5);
+ * UserBinaryTree.addConceptToTree(concept, 42, 999);
+ * const node = await UserBinaryTree.getNodeFromTree(42, 999, 123);
+ * ```
+ */
 export declare class UserBinaryTree {
+    /**
+     * The root node of the user data binary tree.
+     * Null if the tree is empty.
+     */
     static root: UserNode | null;
+    /**
+     * Creates a composite key from user ID, session ID, and randomizer.
+     *
+     * @param userId - The user ID
+     * @param sessionId - The session ID
+     * @param randomizer - Additional identifier (defaults to 999)
+     * @returns A 12-character hexadecimal composite key
+     *
+     * @remarks
+     * The composite key is formed by concatenating three 4-digit hexadecimal values:
+     * userHex (4 chars) + sessionHex (4 chars) + randomizerHex (4 chars) = 12 chars total.
+     * This enables unique identification of data across users, sessions, and applications.
+     *
+     * @example
+     * ```typescript
+     * const key = UserBinaryTree.compositeKey(42, 999, 123);
+     * // Returns something like "002A03E7007B"
+     * ```
+     */
     static compositeKey(userId: number, sessionId: number, randomizer?: number): string;
+    /**
+     * Adds a user node to the binary tree.
+     *
+     * @param node - The UserNode to be added to the tree
+     *
+     * @remarks
+     * If the tree is empty, the provided node becomes the root.
+     * Otherwise, the node is inserted using the AVL tree balancing algorithm.
+     */
     static addNodeToTree(node: UserNode): UserNode | undefined;
+    /**
+     * Waits for user 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
+     */
     static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Periodically checks if user 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 concept and adds it to the user tree.
+     *
+     * @param concept - The LConcept object to be added
+     * @param userId - The user ID
+     * @param sessionId - The session ID (defaults to 999)
+     *
+     * @remarks
+     * Uses the concept's applicationId as the randomizer in the composite key.
+     */
     static addConceptToTree(concept: LConcept, userId: number, sessionId?: number): void;
+    /**
+     * Creates a node from a connection and adds it to the user tree.
+     *
+     * @param connection - The LConnection object to be added
+     * @param userId - The user ID
+     * @param sessionId - The session ID (defaults to 999)
+     *
+     * @remarks
+     * Uses the connection's applicationId as the randomizer in the composite key.
+     */
     static addConnectionToTree(connection: LConnection, userId: number, sessionId?: number): void;
+    /**
+     * Retrieves a node from the tree using composite key components.
+     *
+     * @param userId - The user ID
+     * @param sessionId - The session ID
+     * @param randomizer - Additional identifier (defaults to 999)
+     * @returns The UserNode if found, null otherwise
+     *
+     * @remarks
+     * Constructs a composite key from the parameters and performs a binary search.
+     */
     static getNodeFromTree(userId: number, sessionId: number, randomizer?: number): Promise<UserNode | null>;
+    /**
+     * Removes a node from the tree using composite key components.
+     *
+     * @param userId - The user ID
+     * @param sessionId - The session ID (defaults to 999)
+     * @param randomizer - Additional identifier (defaults to 999)
+     *
+     * @remarks
+     * Constructs a composite key and removes the matching node while maintaining AVL balance.
+     */
     static removeNodeFromTree(userId: number, sessionId?: number, randomizer?: number): Promise<void>;
+    /**
+     * Counts the total number of nodes in the tree.
+     *
+     * @returns The total number of user nodes in the tree
+     *
+     * @remarks
+     * Recursively traverses the entire tree to count all nodes. Returns 0 if the tree is empty.
+     *
+     * @example
+     * ```typescript
+     * const count = UserBinaryTree.countNumberOfNodes();
+     * console.log(`Tree contains ${count} user data nodes`);
+     * ```
+     */
     static countNumberOfNodes(): number;
 }