mftsccs-node 0.0.56 → 0.0.58

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

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

@@ -0,0 +1,139 @@
+/**
+ * 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;
+    id: number;
+    ghostId: 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;
+    sessionInformationId: number;
+    sessionInformationUserId: number;
+    entryTimeStamp: Date | string;
+    updatedTimeStamp: Date | string;
+    referent: Concept | null | void;
+    type: Concept | null | void;
+    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;
+}

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

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