mftsccs-node 0.2.6 → 0.2.8

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

@@ -1,25 +1,317 @@
+/**
+ * @fileoverview ConceptsData module for managing concept storage and retrieval in CCS-JS.
+ * This module provides centralized management of concepts using multiple indexing strategies
+ * including binary trees, character-based trees, and type-based trees for efficient lookups.
+ * @module DataStructures/ConceptData
+ */
 import { Concept } from "./Concept";
+/**
+ * Central repository for managing all concepts in the CCS system.
+ * Provides multiple indexing strategies (ID-based, character-based, type-based) for efficient concept retrieval.
+ * Maintains both in-memory (tree structures) and persistent (IndexedDB) storage.
+ *
+ * @class ConceptsData
+ * @example
+ * ```typescript
+ * // Add a concept to the system
+ * ConceptsData.AddConcept(myConcept);
+ *
+ * // Retrieve a concept by ID
+ * const concept = await ConceptsData.GetConcept(123);
+ *
+ * // Get concepts by type
+ * const concepts = ConceptsData.GetConceptsByTypeId(10);
+ * ```
+ *
+ * @remarks
+ * This class uses static methods and properties, functioning as a singleton data store.
+ * It coordinates multiple indexing strategies for optimized query performance.
+ */
 export declare class ConceptsData {
+    /** Name identifier for this data structure */
     name: string;
+    /**
+     * Creates a new ConceptsData instance.
+     * @remarks This is rarely instantiated as the class primarily uses static methods.
+     */
     constructor();
+    /** Legacy array storage for concepts (deprecated in favor of tree structures) */
     static conceptsArray: Concept[];
+    /**
+     * NPC (Non-Persistent Concepts) cache for temporarily tracking accessed concept IDs.
+     * Limited to 10 entries for memory management.
+     */
     static NPC: number[];
+    /** Dictionary-style storage for quick concept lookups by ID */
     static conceptDictionary: Concept[];
+    /**
+     * Checks if a concept already exists in the concepts array.
+     *
+     * @param {Concept} concept - The concept to check for existence
+     * @returns {boolean} True if the concept exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const exists = ConceptsData.CheckContains(myConcept);
+     * if (!exists) {
+     *   // Add the concept
+     * }
+     * ```
+     */
     static CheckContains(concept: Concept): boolean;
+    /**
+     * Adds a concept ID to the Non-Persistent Concepts (NPC) cache.
+     * Used for tracking recently accessed concepts. Automatically clears when exceeding 10 entries.
+     *
+     * @param {number} id - The concept ID to add to NPC cache
+     *
+     * @example
+     * ```typescript
+     * ConceptsData.AddNpc(123);
+     * ```
+     */
     static AddNpc(id: number): void;
+    /**
+     * Checks if a concept ID exists in the NPC cache.
+     *
+     * @param {number} id - The concept ID to check
+     * @returns {boolean} True if the ID is in the NPC cache, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (ConceptsData.GetNpc(123)) {
+     *   console.log("Concept recently accessed");
+     * }
+     * ```
+     */
     static GetNpc(id: number): boolean;
+    /**
+     * Adds a concept to persistent storage (IndexedDB) only.
+     * Does not update in-memory tree structures.
+     *
+     * @param {Concept} concept - The concept to store persistently
+     *
+     * @example
+     * ```typescript
+     * ConceptsData.AddConceptToStorage(myConcept);
+     * ```
+     *
+     * @remarks Only stores concepts with valid IDs (id > 0)
+     */
     static AddConceptToStorage(concept: Concept): void;
+    /**
+     * Adds a concept to both persistent storage and all in-memory tree indexes.
+     * This is the primary method for adding concepts to the system.
+     *
+     * @param {Concept} concept - The concept to add
+     *
+     * @example
+     * ```typescript
+     * const newConcept = new Concept(...);
+     * ConceptsData.AddConcept(newConcept);
+     * ```
+     *
+     * @remarks
+     * Updates three tree structures:
+     * - BinaryTree (ID-based lookup)
+     * - BinaryTypeTree (type-based lookup)
+     * - BinaryCharacterTree (character value lookup)
+     * Only processes concepts with valid IDs (id > 0)
+     */
     static AddConcept(concept: Concept): void;
+    /**
+     * Adds a concept to in-memory tree structures only, without persisting to storage.
+     * Useful for temporary concepts or when storage is handled separately.
+     *
+     * @param {Concept} concept - The concept to add to memory
+     *
+     * @example
+     * ```typescript
+     * ConceptsData.AddConceptToMemory(temporaryConcept);
+     * ```
+     *
+     * @remarks
+     * Updates three tree structures without touching IndexedDB.
+     * Only processes concepts with valid IDs (id > 0)
+     */
     static AddConceptToMemory(concept: Concept): void;
+    /**
+     * Adds a concept to the legacy array storage temporarily.
+     * Removes existing duplicates before adding.
+     *
+     * @param {Concept} concept - The concept to add temporarily
+     *
+     * @example
+     * ```typescript
+     * ConceptsData.AddConceptTemporary(tempConcept);
+     * ```
+     *
+     * @remarks
+     * This method uses the legacy conceptsArray and conceptDictionary.
+     * Consider using AddConceptToMemory for new implementations.
+     */
     static AddConceptTemporary(concept: Concept): void;
+    /**
+     * Removes a concept from all storage locations (memory trees and persistent storage).
+     *
+     * @param {Concept} concept - The concept to remove
+     *
+     * @example
+     * ```typescript
+     * ConceptsData.RemoveConcept(obsoleteConcept);
+     * ```
+     *
+     * @remarks
+     * Removes from:
+     * - Legacy conceptsArray
+     * - BinaryTree (ID index)
+     * - IndexedDB persistent storage
+     */
     static RemoveConcept(concept: Concept): void;
+    /**
+     * Retrieves a concept by its ID from the binary tree index.
+     *
+     * @param {number} id - The concept ID to retrieve
+     * @returns {Promise<Concept>} The concept if found, or a default concept if not found
+     *
+     * @example
+     * ```typescript
+     * const concept = await ConceptsData.GetConcept(123);
+     * if (concept.id !== 0) {
+     *   console.log("Found:", concept.characterValue);
+     * }
+     * ```
+     *
+     * @remarks
+     * Returns a default concept (id = 0) if the concept is not found.
+     * Uses BinaryTree for O(log n) lookup performance.
+     */
     static GetConcept(id: number): Promise<Concept>;
+    /**
+     * Retrieves a concept by its character value from the character tree index.
+     *
+     * @param {string} characterValue - The character value to search for
+     * @returns {Promise<Concept>} The concept if found, or a default concept if not found
+     *
+     * @example
+     * ```typescript
+     * const concept = await ConceptsData.GetConceptByCharacter("Hello");
+     * ```
+     *
+     * @remarks
+     * Uses BinaryCharacterTree for efficient character-based lookups.
+     * Returns a default concept if not found.
+     */
     static GetConceptByCharacter(characterValue: string): Promise<Concept>;
+    /**
+    * Retrieves a concept by its character value (updated version).
+    * Currently identical to GetConceptByCharacter.
+    *
+    * @param {string} characterValue - The character value to search for
+    * @returns {Promise<Concept>} The concept if found, or a default concept if not found
+    *
+    * @example
+    * ```typescript
+    * const concept = await ConceptsData.GetConceptByCharacterUpdated("Hello");
+    * ```
+    *
+    * @remarks
+    * This method may be deprecated or merged with GetConceptByCharacter in future versions.
+    */
     static GetConceptByCharacterUpdated(characterValue: string): Promise<Concept>;
+    /**
+    * Retrieves a concept by both its character value and type ID from local storage.
+    * Provides more specific matching than character-only searches.
+    *
+    * @param {string} character_value - The character value to search for
+    * @param {number} typeId - The type ID to filter by
+    * @returns {Promise<Concept>} The concept matching both criteria, or a default concept if not found
+    *
+    * @example
+    * ```typescript
+    * const concept = await ConceptsData.GetConceptByCharacterAndTypeLocal("Apple", 5);
+    * ```
+    *
+    * @remarks
+    * Uses BinaryTypeTree for efficient combined character and type lookups.
+    * More specific than GetConceptByCharacter as it filters by type.
+    */
     static GetConceptByCharacterAndTypeLocal(character_value: string, typeId: number): Promise<Concept>;
+    /**
+    * Retrieves a concept by both its character value and category ID from local storage.
+    *
+    * @param {string} character_value - The character value to search for
+    * @param {number} categoryId - The category ID to filter by
+    * @returns {Promise<Concept>} The concept matching both criteria, or a default concept if not found
+    *
+    * @example
+    * ```typescript
+    * const concept = await ConceptsData.GetConceptByCharacterAndCategoryLocal("Fruit", 3);
+    * ```
+    *
+    * @remarks
+    * Uses BinaryCharacterTree with category filtering for specific lookups.
+    */
     static GetConceptByCharacterAndCategoryLocal(character_value: string, categoryId: number): Promise<Concept>;
+    /**
+    * Retrieves all concepts of a specific type ID from local storage.
+    *
+    * @param {number} typeId - The type ID to filter by
+    * @returns {Concept[]} Array of concepts with the specified type
+    *
+    * @example
+    * ```typescript
+    * const fruits = ConceptsData.GetConceptsByTypeId(5);
+    * console.log(`Found ${fruits.length} fruits`);
+    * ```
+    *
+    * @remarks
+    * Currently searches the legacy conceptsArray.
+    * Consider using GetConceptsByTypeIdAndUser for more specific queries.
+    */
     static GetConceptsByTypeId(typeId: number): Concept[];
+    /**
+    * Retrieves all concepts of a specific type ID and user ID from the type tree.
+    *
+    * @param {number} typeId - The type ID to filter by
+    * @param {number} userId - The user ID to filter by
+    * @returns {Promise<Concept[]>} Array of concepts matching both type and user
+    *
+    * @example
+    * ```typescript
+    * const userConcepts = await ConceptsData.GetConceptsByTypeIdAndUser(5, 1);
+    * ```
+    *
+    * @remarks
+    * Uses BinaryTypeTree for efficient filtered queries.
+    * Useful for multi-user systems to get user-specific concepts of a type.
+    */
     static GetConceptsByTypeIdAndUser(typeId: number, userId: number): Promise<Concept[]>;
+    /**
+    * Returns the root node of the binary character tree.
+    * Used for direct tree traversal or debugging.
+    *
+    * @returns {Node | null} The root node of the character tree
+    *
+    * @example
+    * ```typescript
+    * const tree = ConceptsData.GetBinaryCharacterTree();
+    * if (tree) {
+    *   console.log("Tree root:", tree.key);
+    * }
+    * ```
+    */
     static GetBinaryCharacterTree(): import("./Node").Node | null;
+    /**
+     * Returns the name identifier of this data structure instance.
+     *
+     * @returns {string} The name "conceptsArray"
+     *
+     * @example
+     * ```typescript
+     * const conceptData = new ConceptsData();
+     * console.log(conceptData.getName()); // "conceptsArray"
+     * ```
+     */
     getName(): string;
 }

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

@@ -1,11 +1,179 @@
+/**
+ * @fileoverview Static repository for managing concepts to be drawn/rendered in the CCS-JS system.
+ * @module DataStructures/ConceptsToDraw
+ */
 import { Concept } from "./Concept";
+/**
+ * Manages a static collection of concepts that need to be drawn or rendered.
+ *
+ * @remarks
+ * ConceptsToDraw acts as a singleton-like repository using static methods and properties
+ * to manage a collection of Concept instances. It provides functionality to add, remove,
+ * check existence, and retrieve concepts by ID. This is typically used for maintaining
+ * a render queue or active concept list in visualization components.
+ *
+ * The class uses static methods for all operations, meaning the concept array is shared
+ * across all instances of the class. The instance method `getName()` is provided for
+ * identification purposes.
+ *
+ * @example
+ * ```typescript
+ * // Add concepts to the collection
+ * const concept1 = new Concept(...);
+ * ConceptsToDraw.AddConcept(concept1);
+ *
+ * // Check if a concept exists
+ * if (ConceptsToDraw.CheckContains(concept1)) {
+ *   console.log('Concept is in the draw queue');
+ * }
+ *
+ * // Retrieve a concept by ID
+ * const retrieved = ConceptsToDraw.GetConcept(concept1.id);
+ *
+ * // Remove when done
+ * ConceptsToDraw.RemoveConcept(concept1);
+ * ```
+ */
 export declare class ConceptsToDraw {
+    /**
+     * Descriptive name for this concepts collection.
+     * @defaultValue "concepts To Draw"
+     */
     name: string;
+    /**
+     * Creates a new ConceptsToDraw instance.
+     *
+     * @remarks
+     * While the class can be instantiated, the primary functionality is accessed
+     * through static methods. Instances are mainly useful for accessing the `name`
+     * property via the `getName()` method.
+     *
+     * @example
+     * ```typescript
+     * const conceptsToDraw = new ConceptsToDraw();
+     * console.log(conceptsToDraw.getName()); // "concepts To Draw"
+     * ```
+     */
     constructor();
+    /**
+     * Static array holding all concepts that are queued to be drawn.
+     *
+     * @remarks
+     * This array is shared across all instances and should be managed through
+     * the static methods provided by the class. Direct manipulation is not recommended.
+     */
     static conceptsArray: Concept[];
+    /**
+     * Checks whether a concept already exists in the collection.
+     *
+     * @param concept - The concept to check for existence
+     * @returns `true` if the concept exists (matched by ID), `false` otherwise
+     *
+     * @remarks
+     * Performs a linear search through the conceptsArray comparing concept IDs.
+     * This method is used internally by `AddConcept` to prevent duplicates.
+     *
+     * @example
+     * ```typescript
+     * const concept = new Concept(...);
+     * ConceptsToDraw.AddConcept(concept);
+     *
+     * if (ConceptsToDraw.CheckContains(concept)) {
+     *   console.log('Concept already exists');
+     * }
+     * ```
+     */
     static CheckContains(concept: Concept): boolean;
+    /**
+     * Adds a concept to the collection if it doesn't already exist.
+     *
+     * @param concept - The concept to add to the collection
+     *
+     * @remarks
+     * This method ensures no duplicate concepts are added by first checking
+     * existence via `CheckContains`. Only concepts with unique IDs will be added.
+     * If a concept with the same ID already exists, the method silently returns
+     * without adding the duplicate.
+     *
+     * @example
+     * ```typescript
+     * const concept1 = new Concept(...);
+     * const concept2 = new Concept(...);
+     *
+     * ConceptsToDraw.AddConcept(concept1);
+     * ConceptsToDraw.AddConcept(concept2);
+     * ConceptsToDraw.AddConcept(concept1); // Won't add duplicate
+     *
+     * console.log(ConceptsToDraw.conceptsArray.length); // 2
+     * ```
+     */
     static AddConcept(concept: Concept): void;
+    /**
+     * Removes a concept from the collection by matching its ID.
+     *
+     * @param concept - The concept to remove from the collection
+     *
+     * @remarks
+     * Performs a linear search to find and remove the concept with a matching ID.
+     * Uses `Array.splice()` to remove the element. If multiple concepts with the
+     * same ID exist (which shouldn't happen with proper usage of AddConcept), only
+     * the first match is removed.
+     *
+     * If the concept doesn't exist in the array, the method completes without error.
+     *
+     * @example
+     * ```typescript
+     * const concept = new Concept(...);
+     * ConceptsToDraw.AddConcept(concept);
+     *
+     * // Later, when no longer needed
+     * ConceptsToDraw.RemoveConcept(concept);
+     *
+     * // Verify removal
+     * console.log(ConceptsToDraw.CheckContains(concept)); // false
+     * ```
+     */
     static RemoveConcept(concept: Concept): void;
+    /**
+     * Retrieves a concept from the collection by its ID.
+     *
+     * @param id - The unique identifier of the concept to retrieve
+     * @returns The Concept object if found, or `null` if no matching concept exists
+     *
+     * @remarks
+     * Performs a linear search through the conceptsArray to find a concept with
+     * the matching ID. Returns the first match found. If no concept with the
+     * specified ID exists, returns `null`.
+     *
+     * @example
+     * ```typescript
+     * const concept = new Concept(...);
+     * ConceptsToDraw.AddConcept(concept);
+     *
+     * // Retrieve by ID
+     * const retrieved = ConceptsToDraw.GetConcept(concept.id);
+     * if (retrieved) {
+     *   console.log('Found concept:', retrieved.id);
+     * } else {
+     *   console.log('Concept not found');
+     * }
+     * ```
+     */
     static GetConcept(id: number): Concept | null;
+    /**
+     * Gets the descriptive name of this concepts collection.
+     *
+     * @returns The name string "concepts To Draw"
+     *
+     * @remarks
+     * This is an instance method (unlike the other methods which are static),
+     * so it requires an instance of ConceptsToDraw to call.
+     *
+     * @example
+     * ```typescript
+     * const conceptsToDraw = new ConceptsToDraw();
+     * console.log(conceptsToDraw.getName()); // "concepts To Draw"
+     * ```
+     */
     getName(): string;
 }

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

@@ -1,27 +1,103 @@
+/**
+ * @fileoverview Connection module for the Concept Connection System (CCS-JS).
+ * This module defines the Connection class which represents relationships between concepts.
+ * @module DataStructures/Connection
+ */
 import { Concept } from "./Concept";
+/**
+ * Represents a connection (relationship) between two concepts in the CCS system.
+ * Connections link concepts together and define semantic relationships with type, order, security, and access control.
+ *
+ * @class Connection
+ * @example
+ * ```typescript
+ * const connection = new Connection(
+ *   0, // id
+ *   123, // ofTheConceptId
+ *   456, // toTheConceptId
+ *   1, 1, // userIds
+ *   1, // userId
+ *   10, 1, // type
+ *   0, 0, // order
+ *   0, 0, // security
+ *   0, 0, // access
+ *   0, 0  // sessionInfo
+ * );
+ * ```
+ */
 export declare class Connection {
+    /** Unique identifier for this connection */
     id: number;
+    /** User ID of the connection owner */
     userId: number;
+    /** Ghost ID for tracking temporary connections before persistence */
     ghostId: number;
+    /** ID of the source concept in this connection */
     ofTheConceptId: number;
+    /** ID of the target concept in this connection */
     toTheConceptId: number;
+    /** User ID of the source concept owner */
     ofTheConceptUserId: number;
+    /** User ID of the target concept owner */
     toTheConceptUserId: number;
+    /** Timestamp when the connection was created */
     entryTimeStamp: Date | string;
+    /** Termination date for the connection (if applicable) */
     terminationDateTime: Date;
+    /** Type ID defining the semantic meaning of this connection */
     typeId: number;
+    /** User ID of the type concept owner */
     typeUserId: number;
+    /** Order ID for sorting connections */
     orderId: number;
+    /** User ID of the order concept owner */
     orderUserId: number;
+    /** Security concept ID controlling access permissions */
     securityId: number;
+    /** User ID of the security concept owner */
     securityUserId: number;
+    /** Access control concept ID */
     accessId: number;
+    /** User ID of the access concept owner */
     accessUserId: number;
+    /** Session information concept ID for tracking connection context */
     sessionInformationId: number;
+    /** User ID of the session information concept owner */
     sessionInformationUserId: number;
+    /** Local synchronization timestamp for offline support */
     localSyncTime: Date;
+    /** Flag indicating if this is a temporary connection not yet persisted */
     isTemp: boolean;
+    /** Flag indicating if this connection needs to be updated */
     toUpdate: boolean;
+    /** The type concept object providing semantic meaning to this connection */
     type: Concept;
+    /**
+     * Creates a new Connection instance.
+     *
+     * @param {number} [id=0] - Unique identifier for the connection
+     * @param {number} ofTheConceptId - Source concept ID
+     * @param {number} toTheConceptId - Target concept ID
+     * @param {number} ofTheConceptUserId - User ID of source concept owner
+     * @param {number} toTheConceptUserId - User ID of target concept owner
+     * @param {number} userId - User ID of connection creator
+     * @param {number} typeId - Connection type ID
+     * @param {number} typeUserId - User ID of type concept owner
+     * @param {number} orderId - Order concept ID for sorting
+     * @param {number} orderUserId - User ID of order concept owner
+     * @param {number} securityId - Security concept ID
+     * @param {number} securityUserId - User ID of security concept owner
+     * @param {number} accessId - Access control concept ID
+     * @param {number} accessUserId - User ID of access concept owner
+     * @param {number} sessionInformationId - Session information concept ID
+     * @param {number} sessionInformationUserId - User ID of session information concept owner
+     *
+     * @example
+     * ```typescript
+     * const connection = new Connection(
+     *   1, 100, 200, 1, 1, 1, 5, 1, 0, 0, 0, 0, 0, 0, 0, 0
+     * );
+     * ```
+     */
     constructor(id: number | undefined, ofTheConceptId: number, toTheConceptId: number, ofTheConceptUserId: number, toTheConceptUserId: number, userId: number, typeId: number, typeUserId: number, orderId: number, orderUserId: number, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionInformationId: number, sessionInformationUserId: number);
 }