mftsccs-node 0.0.56 → 0.0.58

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

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Connection deletion service for the CCS-JS system.
+ * This module provides functionality for deleting connections between concepts, supporting both
+ * individual and bulk deletion operations. It handles removal from cache structures, local
+ * database, and backend synchronization to maintain system consistency.
+ * @module Services/DeleteConnection
+ */
+/**
+ * Deletes a single connection from the entire CCS-JS system.
+ *
+ * This function performs comprehensive deletion of a connection by removing it from:
+ * 1. The backend server via API call
+ * 2. The local IndexedDB database
+ * 3. The ConnectionBinaryTree (main ID-based index)
+ * 4. The ConnectionTypeTree (type-based index)
+ *
+ * The function first retrieves the connection to obtain its metadata (particularly the typeId),
+ * then performs deletion across all storage and indexing layers to maintain consistency.
+ *
+ * @param id - The unique identifier of the connection to delete
+ * @param token - Optional authentication token for backend deletion. If empty, will attempt
+ *                deletion without authentication
+ * @returns A promise that resolves to a boolean indicating whether the backend deletion was successful
+ *
+ * @example
+ * ```typescript
+ * // Delete a connection with authentication
+ * import { DeleteConnectionById } from './DeleteConnection';
+ *
+ * const connectionId = 12345;
+ * const authToken = "user-auth-token-xyz";
+ *
+ * const isDeleted = await DeleteConnectionById(connectionId, authToken);
+ * if (isDeleted) {
+ *   console.log("Connection deleted successfully");
+ * } else {
+ *   console.log("Backend deletion failed, but local cleanup completed");
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete connection without authentication token
+ * const result = await DeleteConnectionById(54321);
+ * console.log(`Deletion status: ${result}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete connection as part of composition update
+ * const oldConnections = [123, 456, 789];
+ *
+ * for (const connId of oldConnections) {
+ *   await DeleteConnectionById(connId, userToken);
+ * }
+ * ```
+ *
+ * @remarks
+ * **Deletion Process:**
+ * - Retrieves connection first to access typeId for tree removal
+ * - Backend deletion is performed before local cleanup
+ * - Local cleanup occurs regardless of backend deletion success
+ * - Returns backend deletion status
+ *
+ * **Cache Consistency:**
+ * - Removes from ConnectionBinaryTree (main index)
+ * - Removes from ConnectionTypeTree (type-based index)
+ * - Ensures no dangling references in memory
+ *
+ * **Data Persistence:**
+ * - Removes from IndexedDB for offline consistency
+ * - Backend deletion provides server-side cleanup
+ *
+ * @see {@link DeleteTheConnection} for backend deletion API
+ * @see {@link GetConnectionById} for connection retrieval
+ * @see {@link DeleteConnectionByIdBulk} for bulk deletion operations
+ * @see {@link ConnectionBinaryTree} for main connection indexing
+ * @see {@link ConnectionTypeTree} for type-based indexing
+ */
+export declare function DeleteConnectionById(id: number, token?: string): Promise<boolean>;
+/**
+ * Deletes multiple connections in bulk from the CCS-JS system.
+ *
+ * This function provides optimized bulk deletion of connections by:
+ * 1. Making a single API call to delete all connections at once on the backend
+ * 2. Removing each connection from the ConnectionBinaryTree cache
+ * 3. Only processing positive IDs (skipping local/temporary connections)
+ *
+ * Bulk deletion is significantly more efficient than individual deletions when
+ * removing multiple connections, as it reduces network overhead and API calls.
+ * The function currently performs a lighter cleanup compared to single deletion,
+ * focusing on the main binary tree index.
+ *
+ * @param ids - Array of connection IDs to delete. Can include negative (local) IDs which will be skipped
+ * @returns A promise that resolves to a boolean indicating whether the bulk backend deletion was successful
+ *
+ * @example
+ * ```typescript
+ * // Delete multiple connections at once
+ * import { DeleteConnectionByIdBulk } from './DeleteConnection';
+ *
+ * const connectionIds = [123, 456, 789, 1011];
+ * const isDeleted = await DeleteConnectionByIdBulk(connectionIds);
+ *
+ * if (isDeleted) {
+ *   console.log("All connections deleted successfully");
+ * } else {
+ *   console.log("Bulk deletion failed");
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete connections when updating composition
+ * const oldConnectionIds = composition.connections
+ *   .filter(conn => shouldDelete(conn))
+ *   .map(conn => conn.id);
+ *
+ * if (oldConnectionIds.length > 0) {
+ *   await DeleteConnectionByIdBulk(oldConnectionIds);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete connections with mixed local and persisted IDs
+ * const connectionIds = [123, -456, 789, -1011];
+ * // Only 123 and 789 will be deleted (positive IDs)
+ * const result = await DeleteConnectionByIdBulk(connectionIds);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle bulk deletion with error checking
+ * try {
+ *   const idsToDelete = getConnectionsToRemove();
+ *   const success = await DeleteConnectionByIdBulk(idsToDelete);
+ *
+ *   if (success) {
+ *     updateUIAfterDeletion();
+ *   } else {
+ *     showErrorMessage("Failed to delete connections");
+ *   }
+ * } catch (error) {
+ *   console.error("Error during bulk deletion:", error);
+ * }
+ * ```
+ *
+ * @remarks
+ * Important implementation details:
+ *
+ * **Performance Optimization:**
+ * - Single API call for all deletions (not one per connection)
+ * - Significantly faster than multiple individual DeleteConnectionById calls
+ * - Recommended for deleting 2 or more connections
+ *
+ * **Partial Cleanup:**
+ * - Only removes from ConnectionBinaryTree, not ConnectionTypeTree
+ * - Does not remove from local IndexedDB (commented out)
+ * - Does not retrieve connection objects to save on queries
+ * - This is intentional for performance but may leave some cache inconsistencies
+ *
+ * **ID Filtering:**
+ * - Only processes positive IDs (id > 0)
+ * - Negative IDs represent local/temporary connections not yet persisted
+ * - Local connections don't exist on backend so they're skipped
+ *
+ * **Atomic Backend Operation:**
+ * - Backend deletion is all-or-nothing via the bulk API
+ * - If backend deletion succeeds, all local cleanup is performed
+ * - If backend deletion fails, no local cleanup occurs
+ *
+ * **Use Cases:**
+ * - Cleaning up connections when updating compositions
+ * - Removing all connections to a deleted concept
+ * - Batch operations in composition management
+ * - Performance-critical deletion scenarios
+ *
+ * **Trade-offs:**
+ * - Faster but less thorough cleanup than individual deletions
+ * - May leave some entries in ConnectionTypeTree
+ * - May leave some entries in IndexedDB
+ * - Acceptable for most use cases where cache will be rebuilt
+ *
+ * **Commented Code:**
+ * The function contains commented-out code for:
+ * - Connection retrieval: `let connection = await GetConnectionById(id);`
+ * - Database cleanup: `removeFromDatabase("connection",id);`
+ * These may be intentionally disabled for performance reasons
+ *
+ * @see {@link DeleteTheConnectionBulkApi} for bulk backend deletion API
+ * @see {@link DeleteConnectionById} for single connection deletion with full cleanup
+ * @see {@link ConnectionBinaryTree} for main connection indexing
+ * @see {@link ConnectionTypeTree} for type-based connection indexing
+ */
+export declare function DeleteConnectionByIdBulk(ids: number[]): Promise<boolean>;

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

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview Concept discovery service from connections for the CCS-JS system.
+ * This module provides functionality to identify and batch-load all concepts referenced by
+ * a set of connections. This is essential for efficiently hydrating the concept cache when
+ * working with compositions and connection graphs.
+ * @module Services/FindConceptsFromConnection
+ */
+import { Connection } from "../DataStructures/Connection";
+/**
+ * Discovers and loads all unique concepts referenced by a list of connections.
+ *
+ * This function analyzes a list of connections to extract all unique concept IDs (both source
+ * and target concepts) and loads them into the local cache via a single bulk API call. This is
+ * a critical optimization function that ensures all concepts needed for a composition or
+ * connection graph are available locally before processing.
+ *
+ * The function performs two main operations:
+ * 1. Extracts all unique concept IDs from the connection list (both ofTheConceptId and toTheConceptId)
+ * 2. Fetches all concepts in a single bulk operation and caches them locally
+ *
+ * This batch loading approach is significantly more efficient than fetching concepts individually
+ * as they're needed, reducing network overhead and improving application performance.
+ *
+ * @param connectionList - Array of connections to analyze for concept references. Defaults to empty array.
+ * @returns A promise that resolves when all concepts have been fetched and cached.
+ *          The function does not return the concepts directly; they are stored in the concept cache.
+ *
+ * @example
+ * ```typescript
+ * // Load concepts for a composition
+ * import { FindConceptsFromConnections } from './FindConeceptsFromConnection';
+ *
+ * const compositionConnections = await GetAllConnectionsOfComposition(123);
+ * await FindConceptsFromConnections(compositionConnections);
+ *
+ * // Now all concepts are cached and can be retrieved synchronously
+ * const concept = await GetTheConcept(456); // Fast cache lookup
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Prepare concepts for graph visualization
+ * const connections = await FindConnectionsOfCompositionsBulkInMemory([100, 101, 102]);
+ * await FindConceptsFromConnections(connections);
+ *
+ * // All concepts in the graph are now cached
+ * connections.forEach(conn => {
+ *   const fromConcept = GetTheConceptSync(conn.ofTheConceptId);
+ *   const toConcept = GetTheConceptSync(conn.toTheConceptId);
+ *   renderConnection(fromConcept, toConcept);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Hydrate cache before processing composition
+ * async function loadCompositionWithConcepts(compositionId: number) {
+ *   // First, get all connections
+ *   const connections = await GetAllConnectionsOfComposition(compositionId);
+ *
+ *   // Then, ensure all concepts are cached
+ *   await FindConceptsFromConnections(connections);
+ *
+ *   // Now process the composition with all data locally available
+ *   return processComposition(connections);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle empty connection list safely
+ * const emptyConnections: Connection[] = [];
+ * await FindConceptsFromConnections(emptyConnections);
+ * // No API call made, function returns immediately
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load concepts for multiple compositions
+ * const compositionIds = [200, 201, 202];
+ * const allConnections = await FindConnectionsOfCompositionsBulkInMemory(compositionIds);
+ *
+ * // Single bulk load for all concepts across all compositions
+ * await FindConceptsFromConnections(allConnections);
+ *
+ * // All concepts are now available
+ * console.log("All concepts loaded for compositions:", compositionIds);
+ * ```
+ *
+ * @remarks
+ * Important implementation details and considerations:
+ *
+ * **Concept ID Extraction:**
+ * - Extracts both ofTheConceptId (source concept) and toTheConceptId (target concept)
+ * - Uses includes() to ensure uniqueness - no duplicate IDs in the final list
+ * - Maintains insertion order of concept IDs
+ * - Only adds IDs that haven't been seen before
+ *
+ * **Duplicate Prevention:**
+ * - Checks if concept ID already exists in list before adding
+ * - Prevents redundant API requests for the same concept
+ * - Important when connections share common concepts
+ * - Uses array.includes() which has O(n) complexity per check
+ *
+ * **Bulk Loading:**
+ * - Makes a single API call via GetConceptBulk instead of individual requests
+ * - Significantly reduces network overhead
+ * - All concepts are fetched and cached in one operation
+ * - More efficient for large connection sets
+ *
+ * **Cache Population:**
+ * - GetConceptBulk automatically stores concepts in the local cache
+ * - Concepts become available for synchronous retrieval after this function completes
+ * - No need to manually cache the results
+ * - Persists to IndexedDB for offline availability
+ *
+ * **Empty Input Handling:**
+ * - Returns immediately if connectionList is empty (length === 0)
+ * - No API call made for empty input
+ * - Safe to call with empty arrays
+ *
+ * **No Return Value:**
+ * - Function doesn't return the loaded concepts
+ * - Concepts are stored in the global concept cache
+ * - Access loaded concepts via GetTheConcept() or similar functions
+ * - This is intentional for cache-based architecture
+ *
+ * **Performance Characteristics:**
+ * - O(n*m) complexity for duplicate checking where n = connections, m = unique concepts
+ * - Could be optimized with Set for better performance on large datasets
+ * - Single API call regardless of number of concepts
+ * - Network time dominates execution time
+ *
+ * **Performance Optimization Alternative:**
+ * ```typescript
+ * // More efficient approach using Set
+ * const conceptIds = new Set<number>();
+ * connectionList.forEach(conn => {
+ *   conceptIds.add(conn.ofTheConceptId);
+ *   conceptIds.add(conn.toTheConceptId);
+ * });
+ * await GetConceptBulk([...conceptIds]);
+ * ```
+ *
+ * **Common Use Cases:**
+ * - Loading concepts before rendering compositions
+ * - Hydrating cache for offline-first operations
+ * - Preparing data for graph analysis
+ * - Ensuring all dependencies are cached before processing
+ * - Optimizing batch operations
+ *
+ * **Integration Patterns:**
+ * ```typescript
+ * // Pattern 1: Composition loading
+ * async function loadComposition(id: number) {
+ *   const connections = await getConnections(id);
+ *   await FindConceptsFromConnections(connections);
+ *   return buildCompositionObject(connections);
+ * }
+ *
+ * // Pattern 2: Graph preparation
+ * async function prepareGraph(compositionIds: number[]) {
+ *   const connections = await FindConnectionsOfCompositionsBulkInMemory(compositionIds);
+ *   await FindConceptsFromConnections(connections);
+ *   return buildGraph();
+ * }
+ * ```
+ *
+ * **Error Handling:**
+ * - No explicit error handling in current implementation
+ * - Will throw if GetConceptBulk fails
+ * - Consider wrapping in try-catch for production use
+ * - Failed bulk load means concepts won't be cached
+ *
+ * @see {@link GetConceptBulk} for bulk concept loading API
+ * @see {@link Connection} for connection data structure
+ * @see {@link Concept} for concept data structure
+ * @see {@link FindConnectionsOfCompositionsBulkInMemory} for bulk connection retrieval
+ * @see {@link GetTheConcept} for retrieving cached concepts
+ */
+export declare function FindConceptsFromConnections(connectionList?: Connection[]): Promise<void>;

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

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Bulk composition connection retrieval service for the CCS-JS system.
+ * This module provides functionality to efficiently retrieve connections for multiple
+ * compositions from local memory/cache, which is essential for performance optimization
+ * when working with complex nested compositions.
+ * @module Services/FindConnectionsOfCompositionBulkInMemory
+ */
+import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves all connections for multiple compositions from local memory in a single operation.
+ *
+ * This function is designed for efficient bulk retrieval of connections across multiple
+ * compositions. Instead of making individual API calls or database queries for each composition,
+ * it retrieves all connections from the local ConnectionData cache, aggregating results from
+ * multiple compositions into a single array.
+ *
+ * The function iterates through each composition ID, fetches its connections from local cache,
+ * and accumulates all connections into a unified list. This is particularly useful for:
+ * - Loading nested composition structures
+ * - Analyzing relationship graphs across multiple compositions
+ * - Preparing data for bulk operations
+ * - Optimizing performance when working with complex composition hierarchies
+ *
+ * @param composition_ids - Array of composition IDs to retrieve connections for. Defaults to empty array.
+ * @returns A promise that resolves to an array containing all connections from all specified compositions.
+ *          The returned array combines connections from all compositions with potential duplicates
+ *          if the same connection belongs to multiple compositions.
+ *
+ * @example
+ * ```typescript
+ * // Retrieve connections for multiple related compositions
+ * import { FindConnectionsOfCompositionsBulkInMemory } from './FindConnectionsOfCompositionBulkInMemory';
+ *
+ * const compositionIds = [123, 456, 789];
+ * const allConnections = await FindConnectionsOfCompositionsBulkInMemory(compositionIds);
+ *
+ * console.log(`Found ${allConnections.length} total connections`);
+ * // Returns all connections from compositions 123, 456, and 789
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load nested composition structure
+ * const mainComposition = await GetComposition(100);
+ * const subcompositionIds = mainComposition.subcompositions; // [101, 102, 103]
+ *
+ * // Get all connections for the nested structure
+ * const nestedConnections = await FindConnectionsOfCompositionsBulkInMemory(subcompositionIds);
+ *
+ * // Process all connections together
+ * nestedConnections.forEach(conn => {
+ *   console.log(`Connection: ${conn.ofTheConceptId} -> ${conn.toTheConceptId}`);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Analyze relationship graph across compositions
+ * const compositionIds = [200, 201, 202];
+ * const connections = await FindConnectionsOfCompositionsBulkInMemory(compositionIds);
+ *
+ * // Find all unique concepts involved
+ * const conceptIds = new Set();
+ * connections.forEach(conn => {
+ *   conceptIds.add(conn.ofTheConceptId);
+ *   conceptIds.add(conn.toTheConceptId);
+ * });
+ *
+ * console.log(`Graph contains ${conceptIds.size} unique concepts`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Prepare data for bulk deletion
+ * const compositionsToDelete = [301, 302, 303];
+ * const connectionsToRemove = await FindConnectionsOfCompositionsBulkInMemory(compositionsToDelete);
+ *
+ * // Delete all connections in bulk
+ * const connectionIds = connectionsToRemove.map(conn => conn.id);
+ * await DeleteConnectionByIdBulk(connectionIds);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle empty composition list
+ * const emptyResult = await FindConnectionsOfCompositionsBulkInMemory([]);
+ * console.log(emptyResult); // Returns: []
+ * ```
+ *
+ * @remarks
+ * Important implementation details and considerations:
+ *
+ * **Data Source:**
+ * - Retrieves data from local cache (ConnectionData) only, not from backend
+ * - Uses GetConnectionsOfCompositionLocal which accesses in-memory storage
+ * - Does not make network requests or database queries
+ * - Assumes connections are already cached locally
+ *
+ * **Performance Characteristics:**
+ * - Significantly faster than making individual API calls for each composition
+ * - Memory-efficient as it uses spread operator to accumulate results
+ * - Sequential processing (not parallel) but from fast local cache
+ * - Suitable for real-time operations without network latency
+ *
+ * **Connection Aggregation:**
+ * - Uses spread operator (...) to merge connection arrays
+ * - Maintains order: connections from first composition ID appear first
+ * - May include duplicate connections if they belong to multiple compositions
+ * - Does not deduplicate results
+ *
+ * **Duplicate Handling:**
+ * - Same connection may appear multiple times if it's in multiple compositions
+ * - Caller should deduplicate if needed using connection IDs
+ * - Example deduplication: `const unique = [...new Map(connections.map(c => [c.id, c])).values()]`
+ *
+ * **Empty Input:**
+ * - Returns empty array if composition_ids is empty
+ * - No error thrown for empty input
+ * - Safe to call with empty array
+ *
+ * **Async Behavior:**
+ * - Function is async due to GetConnectionsOfCompositionLocal being async
+ * - However, it processes compositions sequentially, not in parallel
+ * - For better performance with many compositions, consider parallelizing
+ *
+ * **Error Handling:**
+ * - No explicit error handling in current implementation
+ * - Will throw if GetConnectionsOfCompositionLocal throws
+ * - Consider wrapping in try-catch for production use
+ *
+ * **Use Cases:**
+ * - Loading nested composition structures
+ * - Building relationship graphs
+ * - Preparing bulk operations
+ * - Analyzing composition hierarchies
+ * - Offline-first operations
+ *
+ * **Limitations:**
+ * - Only works with cached data (must be loaded first)
+ * - Does not fetch from backend if cache is empty
+ * - May return stale data if cache isn't updated
+ * - No automatic cache validation
+ *
+ * **Best Practices:**
+ * ```typescript
+ * // Ensure compositions are loaded first
+ * await loadCompositionsIntoCache(compositionIds);
+ * const connections = await FindConnectionsOfCompositionsBulkInMemory(compositionIds);
+ *
+ * // Deduplicate if needed
+ * const uniqueConnections = [...new Map(connections.map(c => [c.id, c])).values()];
+ * ```
+ *
+ * @see {@link ConnectionData.GetConnectionsOfCompositionLocal} for single composition connection retrieval
+ * @see {@link Connection} for connection data structure
+ * @see {@link FindConceptsFromConnections} for retrieving concepts from connection lists
+ * @see {@link DeleteConnectionByIdBulk} for bulk connection deletion
+ */
+export declare function FindConnectionsOfCompositionsBulkInMemory(composition_ids?: number[]): Promise<Connection[]>;

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

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Hexadecimal number generation utility for the CCS-JS system.
+ * This module provides functionality to generate negative pseudo-random numbers based on
+ * hexadecimal calculations, commonly used for creating unique temporary identifiers for
+ * local concepts before they are persisted to the backend.
+ * @module Services/GenerateHexNumber
+ */
+/**
+ * Generates a negative pseudo-random number based on hexadecimal calculations.
+ *
+ * This function creates a negative integer by accumulating random hexadecimal values.
+ * It is primarily used in the CCS-JS system to generate temporary local IDs for concepts
+ * and connections that haven't been persisted to the backend yet. The negative value
+ * convention helps distinguish local (client-side) entities from persisted (server-side)
+ * entities which have positive IDs.
+ *
+ * The algorithm multiplies random hex digits (0-15) by 16 for each iteration, accumulating
+ * the results, then returns the negative of this sum. This ensures the generated numbers
+ * are always negative and within a predictable range based on the length parameter.
+ *
+ * @param len - The number of iterations to perform, affecting the magnitude of the output.
+ *              Higher values produce larger negative numbers. Common values are 1-4.
+ * @returns A negative integer calculated from accumulated random hexadecimal values
+ *
+ * @example
+ * ```typescript
+ * // Generate a small negative ID for a temporary concept
+ * const localId = genHexString(2);
+ * // Returns: a negative number like -512, -768, etc.
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Generate a larger negative ID for more range
+ * const localId = genHexString(4);
+ * // Returns: a negative number like -2048, -3072, etc.
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in concept creation for temporary local ID
+ * import { genHexString } from './GenerateHexNumber';
+ *
+ * const tempConcept = {
+ *   id: genHexString(3),
+ *   type: "tempConcept",
+ *   isLocal: true
+ * };
+ * // tempConcept.id will be a negative number like -1280
+ * ```
+ *
+ * @remarks
+ * Key characteristics of this function:
+ * - Always returns negative numbers to distinguish local entities from persisted ones
+ * - Uses Math.random() for pseudo-random generation (not cryptographically secure)
+ * - The range of output values is roughly: -256 * len (with random variation)
+ * - Multiple calls with the same length can produce the same value (not guaranteed unique)
+ * - This is suitable for temporary IDs but not for security-sensitive applications
+ *
+ * The formula used is: -(sum of [Math.floor(Math.random() * 16) * 16] for len iterations)
+ *
+ * @see {@link Math.random} for details on the random number generation
+ * @see {@link Math.floor} for understanding the rounding behavior
+ */
+export declare function genHexString(len: number): number;