mftsccs-node 0.0.56 → 0.0.58

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

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

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

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

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Node implementation for the UserBinaryTree.
+ * This module provides the UserNode class for storing user-specific concepts and connections.
+ * @module DataStructures/User/UserNode
+ */
+import { LConcept } from "../Local/LConcept";
+import { LConnection } from "../Local/LConnection";
+/**
+ * Represents a node in the user binary tree that stores both concepts and connections.
+ *
+ * @remarks
+ * UserNode implements an AVL tree node that can store multiple concepts and connections
+ * for a given composite key (userId + sessionId + randomizer). This allows efficient
+ * storage and retrieval of all user data associated with a specific key combination.
+ *
+ * @example
+ * ```typescript
+ * const concept = new LConcept(123, "example", 5);
+ * const connection = new LConnection(456, 1, 2, 3, 4, 5);
+ * const node = new UserNode("compositeKey", concept, connection, null, null);
+ * ```
+ */
+export declare class UserNode {
+    /**
+     * The composite key used for tree ordering.
+     * Typically a hexadecimal string combining userId, sessionId, and randomizer.
+     */
+    key: any;
+    /**
+     * Array of connections stored in this node.
+     * Multiple connections can be associated with the same key.
+     */
+    connectionValue: LConnection[];
+    /**
+     * Array of concepts stored in this node.
+     * Multiple concepts can be associated with the same key.
+     */
+    value: LConcept[];
+    /**
+     * Reference to the left child node.
+     */
+    leftNode: UserNode | null;
+    /**
+     * Reference to the right child node.
+     */
+    rightNode: UserNode | null;
+    /**
+     * The height of this node in the tree.
+     * Used for AVL tree balancing calculations.
+     */
+    height: number;
+    /**
+     * Creates a new UserNode.
+     *
+     * @param key - The composite key for tree ordering
+     * @param value - The LConcept to store (added if ID > 0)
+     * @param connectionValue - The LConnection to store (added if ID > 0)
+     * @param leftNode - The left child node (or null)
+     * @param rightNode - The right child node (or null)
+     *
+     * @remarks
+     * Only adds concepts and connections with valid (> 0) IDs to their respective arrays.
+     *
+     * @example
+     * ```typescript
+     * const node = new UserNode("compositeKey", concept, connection, null, null);
+     * ```
+     */
+    constructor(key: any, value: LConcept, connectionValue: LConnection, leftNode: UserNode | null, rightNode: UserNode | null);
+    /**
+     * 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. When a node with the same key exists,
+     * the new node's concepts and connections are added to the existing node's arrays.
+     */
+    addNode(passedNode: UserNode, node: UserNode | null, height: number): UserNode | 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: UserNode | null): UserNode | 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: UserNode | null): UserNode | 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: UserNode | 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: UserNode | null): number;
+    /**
+     * Retrieves a node from the tree by its composite key.
+     *
+     * @param id - The composite key string to search for
+     * @param node - The current node being evaluated
+     * @returns The matching UserNode if found, null otherwise
+     */
+    getFromNode(id: string, node: UserNode | null): UserNode | null;
+    /**
+     * Removes a node from the tree by its composite key.
+     *
+     * @param passedNode - The current node being evaluated
+     * @param id - The composite key string to remove
+     * @returns The root node after removal
+     *
+     * @remarks
+     * Implements standard BST deletion with in-order successor replacement.
+     */
+    removeNode(passedNode: UserNode | null, id: string): UserNode | 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.
+     */
+    countNodeBelow(root: UserNode | 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.
+     */
+    inOrderSuccessor(root: UserNode): UserNode;
+}

package/dist/types/Database/GetConceptFromIndexDb.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Placeholder module for IndexedDB concept retrieval functionality.
+ *
+ * This module is reserved for future implementation of concept retrieval operations
+ * from IndexedDB storage in the Concept Connection System.
+ *
+ * @module Database/GetConceptFromIndexDb
+ * @see https://documentation.freeschema.com for reference
+ */