mftsccs-node 0.0.56 → 0.0.58

package/dist/types/DataStructures/Local/LocalConceptData.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Local Concepts Data management for the Concept Connection System.
+ * This module provides static methods for managing local concept data, including
+ * adding, retrieving, and querying concepts from local binary trees and memory.
+ * @module DataStructures/Local/LocalConceptData
+ */
+import { LConcept } from "./../Local/LConcept";
+/**
+ * Manages local concept data storage and retrieval.
+ * Provides static methods for managing concepts in memory and across multiple
+ * binary tree structures for efficient querying.
+ *
+ * @class LocalConceptsData
+ * @export
+ */
+export declare class LocalConceptsData {
+    /**
+     * Name identifier for this data structure.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Creates a new LocalConceptsData instance.
+     *
+     * @constructor
+     */
+    constructor();
+    /**
+     * Static array storing all local concepts in memory.
+     * @type {LConcept[]}
+     * @static
+     */
+    static localconceptsArray: LConcept[];
+    /**
+     * Adds a concept to the local storage system.
+     * Stores the concept in the database and adds it to all relevant binary trees.
+     *
+     * @static
+     * @method AddConcept
+     * @param {LConcept} concept - The concept to add
+     * @returns {void}
+     */
+    static AddConcept(concept: LConcept): void;
+    /**
+     * Adds a concept to memory only (without database storage).
+     * Updates all relevant binary trees for fast lookups.
+     *
+     * @static
+     * @method AddConceptToMemory
+     * @param {LConcept} concept - The concept to add to memory
+     * @returns {void}
+     */
+    static AddConceptToMemory(concept: LConcept): void;
+    /**
+     * Retrieves a concept by its ID from the local binary tree.
+     *
+     * @static
+     * @async
+     * @method GetConcept
+     * @param {number} id - The ID of the concept to retrieve
+     * @returns {Promise<LConcept>} The concept if found, otherwise a default concept
+     */
+    static GetConcept(id: number): Promise<LConcept>;
+    /**
+     * Retrieves a concept by its character value.
+     *
+     * @static
+     * @async
+     * @method GetConceptByCharacter
+     * @param {string} characterValue - The character value to search for
+     * @returns {Promise<LConcept>} The concept if found, otherwise a default concept
+     */
+    static GetConceptByCharacter(characterValue: string): Promise<LConcept>;
+    /**
+     * Retrieves a concept by both character value and type ID.
+     * Useful for finding specific concepts when multiple concepts share the same character value.
+     *
+     * @static
+     * @async
+     * @method GetConceptByCharacterAndTypeLocal
+     * @param {string} character_value - The character value to search for
+     * @param {number} typeId - The type ID to match
+     * @returns {Promise<LConcept>} The concept if found, otherwise a default concept
+     */
+    static GetConceptByCharacterAndTypeLocal(character_value: string, typeId: number): Promise<LConcept>;
+    /**
+     * Retrieves all concepts of a specific type.
+     *
+     * @static
+     * @method GetConceptsByTypeId
+     * @param {number} typeId - The type ID to filter by
+     * @returns {LConcept[]} Array of concepts with the specified type
+     */
+    static GetConceptsByTypeId(typeId: number): LConcept[];
+    /**
+     * Retrieves concepts filtered by both type ID and user ID.
+     * Useful for multi-user environments.
+     *
+     * @static
+     * @async
+     * @method GetConceptsByTypeIdAndUser
+     * @param {number} typeId - The type ID to filter by
+     * @param {number} userId - The user ID to filter by
+     * @returns {Promise<LConcept[]>} Array of concepts matching both criteria
+     */
+    static GetConceptsByTypeIdAndUser(typeId: number, userId: number): Promise<LConcept[]>;
+    /**
+     * Gets the name of this data structure.
+     *
+     * @method getName
+     * @returns {string} The name identifier
+     */
+    getName(): string;
+}

package/dist/types/DataStructures/Local/LocalConnectionData.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Local Connection Data management for the Concept Connection System.
+ * This module provides static methods for managing local connection data, including
+ * adding, removing, and retrieving connections from memory and database storage.
+ * @module DataStructures/Local/LocalConnectionData
+ */
+import { LConnection } from "./LConnection";
+/**
+ * Manages local connection data storage and retrieval.
+ * Provides static methods for managing connections in memory and database,
+ * with support for querying connections by composition and waiting for data loads.
+ *
+ * @class LocalConnectionData
+ * @export
+ */
+export declare class LocalConnectionData {
+    /**
+     * Name identifier for this data structure.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Creates a new LocalConnectionData instance.
+     *
+     * @constructor
+     */
+    constructor();
+    /**
+     * Static array storing all local connections in memory.
+     * @type {LConnection[]}
+     * @static
+     */
+    static connectionArray: LConnection[];
+    /**
+     * Static dictionary/map for fast connection lookups by ID.
+     * @type {LConnection[]}
+     * @static
+     */
+    static connectionDictionary: LConnection[];
+    /**
+     * Checks if a connection already exists in the array.
+     *
+     * @static
+     * @method CheckContains
+     * @param {LConnection} connection - The connection to check
+     * @returns {boolean} True if the connection exists, false otherwise
+     */
+    static CheckContains(connection: LConnection): boolean;
+    /**
+     * Adds a connection to the local storage system.
+     * If the connection already exists, it is removed and re-added.
+     * Stores non-temporary connections with valid IDs to the database.
+     *
+     * @static
+     * @method AddConnection
+     * @param {LConnection} connection - The connection to add
+     * @returns {void}
+     */
+    static AddConnection(connection: LConnection): void;
+    /**
+     * Adds a connection to the fast lookup dictionary.
+     *
+     * @static
+     * @method AddToDictionary
+     * @param {LConnection} connection - The connection to add to dictionary
+     * @returns {void}
+     */
+    static AddToDictionary(connection: LConnection): void;
+    /**
+     * Removes a connection from the local storage system.
+     * Removes from both the array and the database (if it has a valid ID).
+     *
+     * @static
+     * @method RemoveConnection
+     * @param {LConnection} connection - The connection to remove
+     * @returns {void}
+     */
+    static RemoveConnection(connection: LConnection): void;
+    /**
+     * Retrieves a connection by its ID.
+     *
+     * @static
+     * @method GetConnection
+     * @param {number} id - The ID of the connection to retrieve
+     * @returns {LConnection | null} The connection if found, null otherwise
+     */
+    static GetConnection(id: number): LConnection | null;
+    /**
+     * Waits for the local connection data to finish loading.
+     * Uses a polling mechanism to check the loading flag.
+     *
+     * @static
+     * @async
+     * @method waitForDataToLoad
+     * @returns {Promise<string>} Resolves with "done" when loaded, rejects after 25 seconds
+     */
+    static waitForDataToLoad(): Promise<unknown>;
+    /**
+     * Polling function that checks if connection data has finished loading.
+     *
+     * @static
+     * @method checkFlag
+     * @param {Function} resolve - The promise resolve function
+     * @returns {*} Resolves immediately if loaded, otherwise schedules next check
+     */
+    static checkFlag(resolve: any): any;
+    /**
+     * Retrieves all connections of a specific composition (by type ID).
+     * Waits for data to load if necessary.
+     *
+     * @static
+     * @async
+     * @method GetConnectionsOfCompositionLocal
+     * @param {number} id - The composition type ID to filter by
+     * @returns {Promise<LConnection[]>} Array of connections with the specified type
+     */
+    static GetConnectionsOfCompositionLocal(id: number): Promise<LConnection[]>;
+    /**
+     * Gets the name of this data structure.
+     *
+     * @method getName
+     * @returns {string} The name identifier
+     */
+    getName(): string;
+}

package/dist/types/DataStructures/Local/LocalSyncData.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Local Synchronization Data management for the Concept Connection System.
+ * This module manages temporary storage of concepts and connections that need to be
+ * synchronized with the local database periodically.
+ * @module DataStructures/Local/LocalSyncData
+ */
+import { LConcept } from "./LConcept";
+import { LConnection } from "./LConnection";
+/**
+ * Manages synchronization data for local concepts and connections.
+ * Provides static methods for staging data before batch synchronization to the local database.
+ *
+ * @class LocalSyncData
+ * @export
+ */
+export declare class LocalSyncData {
+    /**
+     * Static array storing concepts pending synchronization.
+     * @type {LConcept[]}
+     * @static
+     */
+    static conceptsSyncArray: LConcept[];
+    /**
+     * Static array storing connections pending synchronization.
+     * @type {LConnection[]}
+     * @static
+     */
+    static connectionSyncArray: LConnection[];
+    /**
+     * Checks if a concept already exists in the sync array.
+     *
+     * @static
+     * @method CheckContains
+     * @param {LConcept} concept - The concept to check
+     * @returns {boolean} True if the concept exists, false otherwise
+     */
+    static CheckContains(concept: LConcept): boolean;
+    /**
+     * Removes related concepts and connections from sync arrays when a concept is deleted.
+     * Removes the concept itself and any connections that reference it.
+     *
+     * @static
+     * @method SyncDataDelete
+     * @param {number} id - The ID of the concept being deleted
+     * @returns {void}
+     */
+    static SyncDataDelete(id: number): void;
+    /**
+     * Checks if a connection already exists in the sync array.
+     *
+     * @static
+     * @method CheckContainsConnection
+     * @param {LConnection} connection - The connection to check
+     * @returns {boolean} True if the connection exists, false otherwise
+     */
+    static CheckContainsConnection(connection: LConnection): boolean;
+    /**
+     * Adds a concept to the sync array for later batch synchronization.
+     *
+     * @static
+     * @method AddConcept
+     * @param {LConcept} concept - The concept to add
+     * @returns {void}
+     */
+    static AddConcept(concept: LConcept): void;
+    /**
+     * Removes a concept from the sync array.
+     *
+     * @static
+     * @method RemoveConcept
+     * @param {LConcept} concept - The concept to remove
+     * @returns {void}
+     */
+    static RemoveConcept(concept: LConcept): void;
+    /**
+     * Adds a connection to the sync array for later batch synchronization.
+     *
+     * @static
+     * @method AddConnection
+     * @param {LConnection} connection - The connection to add
+     * @returns {void}
+     */
+    static AddConnection(connection: LConnection): void;
+    /**
+     * Removes a connection from the sync array.
+     *
+     * @static
+     * @method RemoveConnection
+     * @param {LConnection} connection - The connection to remove
+     * @returns {void}
+     */
+    static RemoveConnection(connection: LConnection): void;
+    /**
+     * Synchronizes all pending concepts and connections to the local database.
+     * Clears the sync arrays after successful synchronization.
+     *
+     * @static
+     * @async
+     * @method syncDataLocalDb
+     * @returns {Promise<string>} Returns "done" when synchronization is complete
+     */
+    static syncDataLocalDb(): Promise<string>;
+}

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

@@ -0,0 +1,29 @@
+import { Concept } from "./Concept";
+export declare class Node {
+    key: any;
+    value: Concept;
+    leftNode: Node | null;
+    rightNode: Node | null;
+    currentNode: Node | null;
+    variants: Node[];
+    height: number;
+    constructor(key: any, value: Concept, leftNode: Node | null, rightNode: Node | null);
+    addCurrentNode(passedNode: Node, node: Node | null): Node;
+    addCurrentNodeType(passedNode: Node, node: Node | null): Node;
+    addNode(passedNode: Node, node: Node | null, height: number): Node | null;
+    addCharacterNode(passedNode: Node, node: Node | null, height: number): Node | null;
+    addTypeNode(passedNode: Node, node: Node | null, height: number): Node | null;
+    rightRotate(y: Node | null): Node | null;
+    leftRotate(x: Node | null): Node | null;
+    getHeight(node: Node | null): number;
+    getBalanceFactor(N: Node | null): number;
+    getFromNode(id: number, node: Node | null): Node | null;
+    getCharacterFromNode(value: string, node: Node | null): Node | null;
+    getCharacterFromNodeUpdated(value: string, node: Node | null): Node | null;
+    getFromNodeWithCharacterAndType(value: string, typeId: number, node: Node | null): Node | null;
+    getFromNodeWithCharacterAndCategory(value: string, categoryId: number, node: Node | null): Node | null;
+    removeNode(passedNode: Node | null, id: number): Node | null;
+    removeNodeWithVariants(passedNode: Node | null, typeIdentifier: any, conceptId: number): Node | null;
+    countNodeBelow(root: Node | null): number;
+    inOrderSuccessor(root: Node): Node;
+}

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

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Defines the PatcherStructure class for patching/updating compositions.
+ * @module DataStructures/PatcherStructure
+ */
+/**
+ * Represents a structure for patching or updating composition data.
+ * This class encapsulates all necessary information for performing partial updates
+ * on compositions, including identification, permissions, and the actual patch data.
+ *
+ * @class PatcherStructure
+ *
+ * @example
+ * ```typescript
+ * const patcher = new PatcherStructure();
+ * patcher.compositionId = 123;
+ * patcher.userId = 1;
+ * patcher.sessionId = 456;
+ * patcher.accessId = 4;
+ * patcher.ofTheCompositionId = 789;
+ * patcher.patchObject = { name: "Updated Name", description: "New description" };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Patching a user profile composition
+ * const profilePatcher = new PatcherStructure();
+ * profilePatcher.compositionId = 100;
+ * profilePatcher.userId = 25;
+ * profilePatcher.patchObject = {
+ *   email: "newemail@example.com",
+ *   bio: "Updated bio"
+ * };
+ * ```
+ */
+export declare class PatcherStructure {
+    /**
+     * The ID of the composition to be patched.
+     * Identifies which composition will receive the update.
+     *
+     * @type {number}
+     * @default 0
+     */
+    compositionId: number;
+    /**
+     * The ID of the user performing the patch operation.
+     * Used for access control and audit purposes.
+     *
+     * @type {number}
+     * @default 999
+     */
+    userId: number;
+    /**
+     * The session ID associated with the patch operation.
+     * Links the patch to a specific user session for tracking.
+     *
+     * @type {number}
+     * @default 999
+     */
+    sessionId: number;
+    /**
+     * The access level ID for the patch operation.
+     * Determines what level of access is required to perform this patch.
+     *
+     * @type {number}
+     * @default 4
+     */
+    accessId: number;
+    /**
+     * The ID of the parent or related composition.
+     * Used when patching within a composition hierarchy or relationship.
+     *
+     * @type {number}
+     * @default 0
+     */
+    ofTheCompositionId: number;
+    /**
+     * The object containing the patch data.
+     * Contains key-value pairs representing the fields to update and their new values.
+     * Can be any structure depending on the composition being patched.
+     *
+     * @type {any}
+     * @default {}
+     *
+     * @example
+     * ```typescript
+     * patchObject = {
+     *   name: "New Name",
+     *   age: 30,
+     *   tags: ["tag1", "tag2"]
+     * }
+     * ```
+     */
+    patchObject: any;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Referent information data structure for the CCS-JS system.
+ * @module DataStructures/ReferentInfo
+ */
+/**
+ * Represents referent information that links concept data with character data.
+ *
+ * @remarks
+ * ReferentInfo serves as a bridge between concept entities and character entities in the
+ * system. It maintains both the data IDs and the associated user IDs for each entity,
+ * enabling cross-referencing and ownership tracking across different data types. This is
+ * particularly useful for establishing semantic relationships between abstract concepts
+ * and their concrete character representations.
+ *
+ * @example
+ * ```typescript
+ * const referentInfo = new ReferentInfo(
+ *   1001,  // conceptDataId
+ *   2001,  // conceptDataUserId
+ *   3001,  // characterDataId
+ *   2001   // characterDataUserId
+ * );
+ *
+ * // Use for linking concept to character
+ * console.log(`Concept ${referentInfo.conceptDataId} ` +
+ *             `maps to Character ${referentInfo.characterDataId}`);
+ * ```
+ */
+export declare class ReferentInfo {
+    /**
+     * Unique identifier for the concept data.
+     */
+    conceptDataId: number;
+    /**
+     * User ID associated with the concept data.
+     *
+     * @remarks
+     * Tracks ownership of the concept entity.
+     */
+    conceptDataUserId: number;
+    /**
+     * Unique identifier for the character data.
+     */
+    characterDataId: number;
+    /**
+     * User ID associated with the character data.
+     *
+     * @remarks
+     * Tracks ownership of the character entity. May differ from conceptDataUserId
+     * when characters are shared across users.
+     */
+    characterDataUserId: number;
+    /**
+     * Creates a new ReferentInfo instance.
+     *
+     * @param conceptDataId - The ID of the concept data
+     * @param conceptDataUserId - The user ID who owns the concept data
+     * @param characterDataId - The ID of the character data
+     * @param characterDataUserId - The user ID who owns the character data
+     *
+     * @remarks
+     * Both concept and character entities maintain their own user ownership,
+     * allowing for flexible sharing and access control scenarios.
+     *
+     * @example
+     * ```typescript
+     * // Create a referent linking concept 100 to character 200
+     * const ref = new ReferentInfo(100, 1, 200, 1);
+     *
+     * // Verify the mapping
+     * console.log(`Concept: ${ref.conceptDataId} -> Character: ${ref.characterDataId}`);
+     * ```
+     */
+    constructor(conceptDataId: number, conceptDataUserId: number, characterDataId: number, characterDataUserId: number);
+}

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

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview ReservedIds module for managing pre-allocated concept and connection IDs.
+ * This module provides a pool of reserved IDs to avoid database round-trips during bulk operations.
+ * @module DataStructures/ReservedIds
+ */
+/**
+ * Manages a pool of pre-allocated concept IDs from the backend.
+ * Automatically refills the pool when it gets low to ensure smooth operation.
+ *
+ * @class ReservedIds
+ * @example
+ * ```typescript
+ * // Get a reserved ID for a new concept
+ * const newId = await ReservedIds.getId();
+ *
+ * // Add an ID to the pool
+ * ReservedIds.AddId(123);
+ * ```
+ *
+ * @remarks
+ * Maintains a pool of at least 10 IDs. When the pool has fewer than 10 IDs,
+ * it automatically requests more from the backend.
+ */
+export declare class ReservedIds {
+    /** Pool of reserved concept IDs */
+    static ids: number[];
+    /**
+    * Gets the next available reserved ID from the pool.
+    * Automatically refills the pool if it has fewer than 10 IDs.
+    *
+    * @returns {Promise<number>} A unique reserved concept ID
+    *
+    * @example
+    * ```typescript
+    * const id = await ReservedIds.getId();
+    * const concept = new Concept(id, ...);
+    * ```
+    *
+    * @remarks
+    * Uses FIFO (first in, first out) to retrieve IDs.
+    * Triggers a backend call to GetReservedIds when pool is low.
+    */
+    static getId(): Promise<number>;
+    /**
+     * Adds an ID to the reserved IDs pool.
+     *
+     * @param {number} id - The ID to add to the pool
+     *
+     * @example
+     * ```typescript
+     * ReservedIds.AddId(123);
+     * ```
+     *
+     * @remarks
+     * Prevents duplicate IDs from being added to the pool.
+     */
+    static AddId(id: number): void;
+}
+/**
+ * Manages a pool of pre-allocated connection IDs from the backend.
+ * Automatically refills the pool when it gets low to ensure smooth operation.
+ *
+ * @class ReservedConnectionIds
+ * @example
+ * ```typescript
+ * // Get a reserved ID for a new connection
+ * const newId = await ReservedConnectionIds.getId();
+ *
+ * // Add an ID to the pool
+ * ReservedConnectionIds.AddId(456);
+ * ```
+ *
+ * @remarks
+ * Maintains a pool of at least 10 IDs. When the pool has fewer than 10 IDs,
+ * it automatically requests more from the backend.
+ */
+export declare class ReservedConnectionIds {
+    /** Pool of reserved connection IDs */
+    static connectionIds: number[];
+    /**
+     * Gets the next available reserved connection ID from the pool.
+     * Automatically refills the pool if it has fewer than 10 IDs.
+     *
+     * @returns {Promise<number>} A unique reserved connection ID
+     *
+     * @example
+     * ```typescript
+     * const id = await ReservedConnectionIds.getId();
+     * const connection = new Connection(id, ...);
+     * ```
+     *
+     * @remarks
+     * Uses FIFO (first in, first out) to retrieve IDs.
+     * Triggers a backend call to GetReservedConnectionIds when pool is low.
+     */
+    static getId(): Promise<number>;
+    /**
+     * Adds an ID to the reserved connection IDs pool.
+     *
+     * @param {number} id - The ID to add to the pool
+     *
+     * @example
+     * ```typescript
+     * ReservedConnectionIds.AddId(456);
+     * ```
+     *
+     * @remarks
+     * Prevents duplicate IDs from being added to the pool.
+     */
+    static AddId(id: number): void;
+}