mftsccs-node 0.0.56 → 0.0.58

package/dist/types/Services/CreateTheConnection.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Connection Creation Service
+ *
+ * This module provides functionality for creating temporary connections between concepts
+ * in the Concept Connection System. It handles basic connection creation with default
+ * security and access settings.
+ *
+ * @module CreateTheConnection
+ */
+import { Connection } from "../DataStructures/Connection";
+/**
+ * Creates a temporary connection between two concepts with default settings.
+ *
+ * This function establishes a basic connection relationship between a source concept
+ * (ofTheConcept) and a target concept (toTheConcept). The created connection is marked
+ * as temporary (isTemp = true) and assigned a random ID. It automatically handles the
+ * special case where a concept connects to itself by setting predefined IDs.
+ *
+ * The function uses default values for security (0), access level (4), and order (1),
+ * making it suitable for quick connection creation during prototyping or when advanced
+ * configuration is not required.
+ *
+ * @param ofTheConceptId - The ID of the source concept from which the connection originates
+ * @param ofTheConceptUserId - The user ID who owns the source concept
+ * @param toTheConceptId - The ID of the target concept to which the connection points
+ * @param toTheConceptUserId - The user ID who owns the target concept
+ * @param typeId - The ID of the concept that defines the type/nature of this connection
+ * @param sessionInformationId - The ID of the session in which this connection is created
+ * @param sessionInformationUserId - The user ID associated with the session information
+ *
+ * @returns A new Connection object that has been added to SyncData for synchronization
+ *
+ * @example
+ * ```typescript
+ * // Create a simple "likes" connection between user's concepts
+ * const likesConcept = await GetConceptByCharacter("likes");
+ * const connection = createTheConnection(
+ *   userConcept.id,
+ *   userConcept.userId,
+ *   postConcept.id,
+ *   postConcept.userId,
+ *   likesConcept.id,
+ *   999,
+ *   999
+ * );
+ * console.log("Connection created:", connection.id);
+ * ```
+ *
+ * @remarks
+ * - The connection is marked as temporary (isTemp = true) and assigned a random ID
+ * - Self-referencing connections (where ofTheConceptId equals toTheConceptId) are handled
+ *   specially by setting ofTheConceptId to 0 and toTheConceptId to 1
+ * - Default security level is set to 0 and access level to 4
+ * - The connection is automatically added to SyncData for later synchronization
+ * - For production use with reserved IDs and more control, consider using CreateTheConnectionGeneral
+ *
+ * @see {@link CreateTheConnectionGeneral} for creating connections with more configuration options
+ * @see {@link Connection} for the connection data structure
+ * @see {@link SyncData.AddConnection} for how connections are queued for sync
+ */
+export declare function createTheConnection(ofTheConceptId: number, ofTheConceptUserId: number, toTheConceptId: number, toTheConceptUserId: number, typeId: number, sessionInformationId: number, sessionInformationUserId: number): Connection;

package/dist/types/Services/CreateTheConnectionGeneral.d.ts

@@ -0,0 +1,132 @@
+/**
+ * General Connection Creation Service
+ *
+ * This module provides advanced functionality for creating permanent connections between
+ * concepts with reserved IDs and configurable settings. It supports transaction tracking
+ * and is designed for production use where connections need to be persisted and updated.
+ *
+ * @module CreateTheConnectionGeneral
+ */
+import { Concept } from "../app";
+import { Connection } from "../DataStructures/Connection";
+import { InnerActions } from "../DataStructures/Transaction/Transaction";
+/**
+ * Creates a permanent connection between two concepts with reserved ID and full configuration.
+ *
+ * This is the production-ready version of connection creation that uses reserved IDs from
+ * the system's ID reservation pool. Unlike the basic createTheConnection, this function
+ * marks connections as non-temporary (isTemp = false) and sets them to update mode
+ * (toUpdate = true), ensuring they persist properly in the database.
+ *
+ * The function provides extensive configurability including custom order, access levels,
+ * and user assignment. It also supports transaction tracking by accepting an actions
+ * object where created connections are logged.
+ *
+ * @param ofTheConceptId - The ID of the source concept from which the connection originates
+ * @param ofTheConceptUserId - The user ID who owns the source concept
+ * @param toTheConceptId - The ID of the target concept to which the connection points
+ * @param toTheConceptUserId - The user ID who owns the target concept
+ * @param typeId - The ID of the concept that defines the type/nature of this connection
+ * @param sessionInformationId - The ID of the session in which this connection is created
+ * @param sessionInformationUserId - The user ID associated with the session information
+ * @param orderId - Optional ordering value for the connection (default: 1)
+ * @param accessId - Optional access level for the connection (default: 4)
+ * @param passedUserId - Optional specific user ID to assign to the connection (default: 999, uses ofTheConceptUserId if not provided)
+ * @param actions - Optional transaction tracking object to log created connections (default: empty actions)
+ *
+ * @returns A promise that resolves to the created Connection object with a reserved ID
+ *
+ * @example
+ * ```typescript
+ * // Create a production connection with transaction tracking
+ * const actions: InnerActions = { concepts: [], connections: [] };
+ * const connection = await CreateTheConnectionGeneral(
+ *   authorConcept.id,
+ *   authorConcept.userId,
+ *   bookConcept.id,
+ *   bookConcept.userId,
+ *   wroteTypeConcept.id,
+ *   999,
+ *   999,
+ *   1,
+ *   4,
+ *   authorConcept.userId,
+ *   actions
+ * );
+ * console.log("Connection ID:", connection.id);
+ * console.log("Tracked connections:", actions.connections.length);
+ * ```
+ *
+ * @remarks
+ * - Uses reserved IDs from ReservedConnectionIds for guaranteed uniqueness
+ * - Connection is marked as non-temporary (isTemp = false) for persistence
+ * - Sets toUpdate = true to ensure database synchronization
+ * - Self-referencing connections are handled by setting ofTheConceptId to 0 and toTheConceptId to 1
+ * - The connection is added to both SyncData and the provided actions object
+ * - If passedUserId is 999, the function defaults to using ofTheConceptUserId
+ *
+ * @see {@link createTheConnection} for creating temporary connections
+ * @see {@link CreateConnection} for a simplified high-level connection API
+ * @see {@link ReservedConnectionIds.getId} for ID reservation mechanism
+ */
+export declare function CreateTheConnectionGeneral(ofTheConceptId: number, ofTheConceptUserId: number, toTheConceptId: number, toTheConceptUserId: number, typeId: number, sessionInformationId: number, sessionInformationUserId: number, orderId?: number, accessId?: number, passedUserId?: number, actions?: InnerActions): Promise<Connection>;
+/**
+ * Creates a connection between two concepts using a type string identifier.
+ *
+ * This is a high-level convenience function that simplifies connection creation by
+ * accepting concept objects directly and a string for the connection type. It automatically
+ * handles the creation or retrieval of the connection type concept and delegates to
+ * CreateTheConnectionGeneral for the actual connection creation.
+ *
+ * This function is ideal for application-level code where you want to create connections
+ * using semantic type names (like "contains", "authored", "belongs_to") rather than
+ * managing type concept IDs manually.
+ *
+ * @param ofTheConcept - The source Concept object from which the connection originates
+ * @param toTheConcept - The target Concept object to which the connection points
+ * @param connectionTypeString - A string describing the connection type (e.g., "contains", "references")
+ * @param actions - Optional transaction tracking object to log created connections (default: empty actions)
+ *
+ * @returns A promise that resolves to the created Connection object
+ *
+ * @example
+ * ```typescript
+ * // Create a "contains" connection between a folder and a file
+ * const folderConcept = await GetTheConcept(123);
+ * const fileConcept = await GetTheConcept(456);
+ * const actions: InnerActions = { concepts: [], connections: [] };
+ *
+ * const connection = await CreateConnection(
+ *   folderConcept,
+ *   fileConcept,
+ *   "contains",
+ *   actions
+ * );
+ *
+ * console.log(`Created ${connectionTypeString} connection:`, connection.id);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create an "authored" connection between author and book
+ * const authorConcept = await GetTheConcept(789);
+ * const bookConcept = await GetTheConcept(101);
+ *
+ * const connection = await CreateConnection(
+ *   authorConcept,
+ *   bookConcept,
+ *   "authored"
+ * );
+ * ```
+ *
+ * @remarks
+ * - Automatically creates or retrieves a type concept for the connectionTypeString
+ * - Uses default session information ID (999) and order (1000)
+ * - Access level is set to 4 (standard access)
+ * - The userId from ofTheConcept is used for the connection
+ * - The connection is tracked in the provided actions object for transaction management
+ *
+ * @see {@link CreateTheConnectionGeneral} for the underlying connection creation logic
+ * @see {@link MakeTheTypeConceptApi} for how type concepts are created/retrieved
+ */
+export declare function CreateConnection(ofTheConcept: Concept, toTheConcept: Concept, connectionTypeString: string, actions?: InnerActions): Promise<Connection>;

package/dist/types/Services/CreateTypeTreeFromData.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type-Based Binary Tree Data Loading Service
+ *
+ * This module provides functionality for creating and populating a type-based binary tree
+ * data structure from persisted concept data. The tree is organized by type identifiers,
+ * enabling efficient type-based categorization, filtering, and retrieval of concepts.
+ *
+ * @module CreateTypeTreeFromData
+ */
+/**
+ * Creates and populates a type-based binary tree from concept data stored in the database.
+ *
+ * This function retrieves all concept records from IndexedDB and constructs a binary tree
+ * where nodes are organized by their type identifiers (typeId). This organization enables
+ * efficient grouping and retrieval of concepts by their type classification.
+ *
+ * The BinaryTypeTree structure is essential for type-based queries and operations, allowing
+ * the system to quickly find all concepts of a particular type without scanning the entire
+ * dataset. Performance metrics are tracked to monitor loading times.
+ *
+ * @returns A promise that resolves when the type binary tree has been fully populated
+ *
+ * @example
+ * ```typescript
+ * // Build the type-based binary tree from database
+ * await CreateTypeTreeFromData();
+ *
+ * // The tree can now be used for type-based queries
+ * const conceptsOfType = BinaryTypeTree.getByType(42);
+ * console.log('All concepts of type 42:', conceptsOfType);
+ * ```
+ *
+ * @remarks
+ * - Tracks execution time for performance monitoring (startTime, endTime, time variables)
+ * - Each concept is wrapped in a Node using its typeId property as the organizational key
+ * - The tree is built sequentially by iterating through all retrieved concepts
+ * - Type identifiers determine node placement in the binary tree structure
+ * - Time measurements are calculated but not currently returned or logged
+ *
+ * @see {@link BinaryTypeTree.addNodeToTree} for how nodes are inserted into the tree
+ * @see {@link Node} for the node data structure used in the tree
+ * @see {@link getFromDatabaseWithTypeOld} for database retrieval implementation
+ */
+export declare function CreateTypeTreeFromData(): Promise<void>;

package/dist/types/Services/Delete/DeleteConnectionByType.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module DeleteConnectionByType
+ * @description Provides functions to delete and retrieve connections by their type
+ */
+/**
+ * Deletes all connections of specified types from a concept.
+ * Finds connections matching the given linker types and deletes them.
+ *
+ * @async
+ * @param {number} id - The concept ID whose connections should be deleted
+ * @param {string[]} linkers - Array of connection type names to delete
+ * @returns {Promise<boolean>} A promise that resolves to true if all deletions successful, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const conceptId = 123;
+ * const linkersToDelete = ["follows", "likes", "shares"];
+ * const success = await DeleteConnectionByTypeBulk(conceptId, linkersToDelete);
+ * if (success) {
+ *   console.log("All connections deleted successfully");
+ * }
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Fetches all linker connections from the concept
+ * - Gets concept objects for the specified linker type names
+ * - Matches connections by typeId with linker concept IDs
+ * - Deletes each matching connection
+ * - Returns false if any deletion fails
+ * - Uses bulk operations for efficiency
+ */
+export declare function DeleteConnectionByTypeBulk(id: number, linkers: string[]): Promise<boolean>;
+/**
+ * Retrieves all connection IDs of specified types from a concept without deleting them.
+ * Useful for querying which connections exist before performing operations.
+ *
+ * @async
+ * @param {number} id - The concept ID whose connections should be retrieved
+ * @param {string[]} linkers - Array of connection type names to find
+ * @returns {Promise<number[]>} A promise that resolves to array of matching connection IDs
+ *
+ * @example
+ * ```typescript
+ * const conceptId = 123;
+ * const linkersToFind = ["follows", "likes"];
+ * const connectionIds = await GetConnectionByTypeBulk(conceptId, linkersToFind);
+ * // connectionIds = [101, 102, 103, 104]
+ * console.log(`Found ${connectionIds.length} connections`);
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Similar to DeleteConnectionByTypeBulk but only retrieves IDs
+ * - Does not modify any data
+ * - Returns empty array if no matching connections found
+ * - Useful for counting or inspecting connections before deletion
+ * - Can be used to check connection existence
+ */
+export declare function GetConnectionByTypeBulk(id: number, linkers: string[]): Promise<number[]>;

package/dist/types/Services/Delete/GetAllConnectionByType.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module GetAllConnectionByType
+ * @description Provides functions to retrieve connections filtered by type and direction
+ */
+import { Connection } from "../../app";
+/**
+ * Retrieves all connections of a specific type from or to a concept.
+ * Supports both forward (from concept) and reverse (to concept) direction.
+ *
+ * @async
+ * @param {number} id - The concept ID to query connections for
+ * @param {string} linker - The connection type name to filter by
+ * @param {boolean} [reverse=false] - If true, returns connections TO the concept; if false, returns connections FROM the concept
+ * @returns {Promise<Connection[]>} A promise that resolves to array of matching Connection objects
+ *
+ * @example
+ * ```typescript
+ * // Get all "follows" connections FROM concept 123
+ * const followsFrom = await GetAllTheConnectionsByTypeAndOfTheConcept(123, "follows", false);
+ *
+ * // Get all "follows" connections TO concept 123 (reverse)
+ * const followsTo = await GetAllTheConnectionsByTypeAndOfTheConcept(123, "follows", true);
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Forward direction (reverse=false): Returns connections where concept is ofTheConceptId
+ * - Reverse direction (reverse=true): Returns connections where concept is toTheConceptId
+ * - Creates or retrieves the linker concept by type name
+ * - Filters connections by matching typeId
+ * - Caches forward connections in ConnectionData
+ * - Returns empty array if no matching connections found
+ */
+export declare function GetAllTheConnectionsByTypeAndOfTheConcept(id: number, linker: string, reverse?: boolean): Promise<Connection[]>;
+/**
+ * Retrieves specific connections between two concepts with a given linker type.
+ * Filters connections to match both the source, destination, and type.
+ *
+ * @async
+ * @param {number} ofTheConceptId - The source concept ID
+ * @param {number} toTheConceptId - The destination concept ID
+ * @param {string} linker - The connection type name
+ * @param {boolean} [reverse=false] - If true, swaps the direction (queries from toTheConceptId)
+ * @returns {Promise<Connection[]>} A promise that resolves to array of matching connections
+ *
+ * @example
+ * ```typescript
+ * // Find all "follows" connections from concept 123 to concept 456
+ * const connections = await GiveConnection(123, 456, "follows", false);
+ *
+ * // Find all "follows" connections from 456 to 123 (reverse direction)
+ * const reverseConnections = await GiveConnection(123, 456, "follows", true);
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - First uses GetAllTheConnectionsByTypeAndOfTheConcept to get typed connections
+ * - Then filters by the destination concept ID
+ * - Forward (reverse=false): Returns connections from ofTheConceptId to toTheConceptId
+ * - Reverse (reverse=true): Returns connections from toTheConceptId to ofTheConceptId
+ * - Useful for finding specific connection instances between two concepts
+ * - Returns empty array if no matching connections exist
+ */
+export declare function GiveConnection(ofTheConceptId: number, toTheConceptId: number, linker: string, reverse?: boolean): Promise<Connection[]>;

package/dist/types/Services/DeleteConcept.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Concept deletion service for the CCS-JS system.
+ * This module provides comprehensive functionality for deleting concepts from the system,
+ * including removal from all cache structures (binary trees, type trees, character trees),
+ * local database cleanup, and backend synchronization.
+ * @module Services/DeleteConcept
+ */
+/**
+ * Deletes a concept from the entire CCS-JS system, including all caches and the backend.
+ *
+ * This function performs a comprehensive deletion of a concept by removing it from multiple
+ * data structures and storage layers:
+ * 1. Retrieves the concept to get its metadata (typeId, characterValue)
+ * 2. Removes the concept from the main BinaryTree index
+ * 3. Removes it from the BinaryTypeTree (type-based indexing)
+ * 4. Removes it from the BinaryCharacterTree (character-based indexing)
+ * 5. Removes it from the local IndexedDB database
+ * 6. Deletes it from the backend server
+ *
+ * This ensures complete cleanup across all layers of the application, maintaining data
+ * consistency and preventing orphaned references. The deletion is performed in a specific
+ * order to ensure safe removal from all dependent structures.
+ *
+ * @param id - The unique identifier of the concept to delete
+ * @param token - Optional authentication token for backend deletion. If not provided,
+ *                the function will attempt deletion without authentication
+ * @returns A promise that resolves to a boolean indicating whether the backend deletion was successful
+ *
+ * @example
+ * ```typescript
+ * // Delete a concept with authentication
+ * import { DeleteConceptById } from './DeleteConcept';
+ *
+ * const conceptId = 12345;
+ * const authToken = "user-auth-token-xyz";
+ *
+ * const isDeleted = await DeleteConceptById(conceptId, authToken);
+ * if (isDeleted) {
+ *   console.log("Concept successfully deleted from all systems");
+ * } else {
+ *   console.log("Backend deletion failed, but local caches cleared");
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete a concept without authentication token
+ * const conceptId = 67890;
+ * const result = await DeleteConceptById(conceptId);
+ * console.log(`Deletion status: ${result}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete multiple concepts in sequence
+ * const conceptIds = [123, 456, 789];
+ * const authToken = "user-token";
+ *
+ * for (const id of conceptIds) {
+ *   const deleted = await DeleteConceptById(id, authToken);
+ *   if (!deleted) {
+ *     console.error(`Failed to delete concept ${id}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete concept with error handling
+ * try {
+ *   const conceptId = 999;
+ *   const isDeleted = await DeleteConceptById(conceptId, "auth-token");
+ *
+ *   if (isDeleted) {
+ *     // Update UI to reflect deletion
+ *     updateConceptList();
+ *   }
+ * } catch (error) {
+ *   console.error("Error during concept deletion:", error);
+ * }
+ * ```
+ *
+ * @remarks
+ * Important implementation details and considerations:
+ *
+ * **Deletion Order:**
+ * The function follows a specific deletion sequence:
+ * 1. First retrieves concept data (needed for type and character indices)
+ * 2. Removes from main binary tree (ID-based index)
+ * 3. Removes from type tree (type-based index)
+ * 4. Removes from character tree (character-based index)
+ * 5. Removes from local database (IndexedDB)
+ * 6. Finally deletes from backend server
+ *
+ * **Cache Consistency:**
+ * - Removes the concept from all three binary tree structures
+ * - BinaryTree: Main ID-based concept index
+ * - BinaryTypeTree: Type-categorized concept index
+ * - BinaryCharacterTree: Character/name-based concept index
+ * - This ensures no dangling references remain in any cache
+ *
+ * **Local Database:**
+ * - Uses removeFromDatabase to clear from IndexedDB
+ * - This is synchronous local storage cleanup
+ * - Ensures offline-first capability remains consistent
+ *
+ * **Backend Synchronization:**
+ * - Calls DeleteTheConcept API to remove from server
+ * - Uses optional authentication token
+ * - Returns backend deletion status
+ * - Local cleanup happens regardless of backend success
+ *
+ * **Error Handling:**
+ * - If GetTheConcept fails, the function will throw
+ * - Tree removal operations are awaited but may not throw
+ * - Backend deletion status is returned but doesn't affect local cleanup
+ * - Consider wrapping in try-catch for production use
+ *
+ * **Side Effects:**
+ * - Permanently removes concept from all storage layers
+ * - Cannot be undone without re-creating the concept
+ * - May orphan connections that reference this concept
+ * - Consider deleting associated connections first
+ *
+ * **Performance:**
+ * - Multiple async operations performed sequentially
+ * - May take longer for concepts with complex relationships
+ * - Consider using connection cleanup functions before deletion
+ *
+ * @see {@link DeleteTheConcept} for backend deletion API
+ * @see {@link GetTheConcept} for concept retrieval
+ * @see {@link BinaryTree} for main concept indexing
+ * @see {@link BinaryTypeTree} for type-based indexing
+ * @see {@link BinaryCharacterTree} for character-based indexing
+ * @see {@link DeleteConnectionById} for deleting associated connections
+ */
+export declare function DeleteConceptById(id: number, token?: string): Promise<boolean>;