mftsccs-node 0.2.7 → 0.2.9

package/dist/types/Helpers/RemoveFromArray.d.ts

@@ -1,6 +1,72 @@
+/**
+ * Remove From Array Helper Module for Concept Connection System (CCS-JS)
+ *
+ * This module provides utility functions for removing concepts and connections from arrays.
+ * These functions mutate the original arrays by splicing out matching elements by ID.
+ *
+ * @module Helpers/RemoveFromArray
+ * @see https://documentation.freeschema.com for data structure reference
+ */
 import { Concept } from "../DataStructures/Concept";
 import { Connection } from "../DataStructures/Connection";
 import { LConnection } from "../app";
+/**
+ * Removes a concept from an array by matching its ID.
+ *
+ * @param conceptList - Array of concepts to remove from (will be mutated)
+ * @param concept - The concept to remove from the array
+ *
+ * @example
+ * ```typescript
+ * const concepts = [concept1, concept2, concept3];
+ * RemoveConceptFromList(concepts, concept2);
+ * console.log(concepts.length); // 2 (concept2 has been removed)
+ * ```
+ *
+ * @remarks
+ * This function mutates the original array using splice().
+ * If the concept is not found (findIndex returns -1), splice will remove the last element.
+ * Ensure the concept exists in the array before calling this function to avoid unintended removals.
+ */
 export declare function RemoveConceptFromList(conceptList: Concept[] | undefined, concept: Concept): void;
+/**
+ * Removes a connection from an array by matching its ID.
+ *
+ * @param connectionList - Array of connections to remove from (will be mutated)
+ * @param connection - The connection to remove from the array
+ *
+ * @example
+ * ```typescript
+ * const connections = [conn1, conn2, conn3];
+ * RemoveConnectionFromList(connections, conn2);
+ * console.log(connections.length); // 2 (conn2 has been removed)
+ * ```
+ *
+ * @remarks
+ * This function mutates the original array using splice().
+ * If the connection is not found (findIndex returns -1), splice will remove the last element.
+ * Ensure the connection exists in the array before calling this function to avoid unintended removals.
+ */
 export declare function RemoveConnectionFromList(connectionList: Connection[] | undefined, connection: Connection): void;
+/**
+ * Removes an LConnection (lightweight connection) from an array by matching its ID.
+ *
+ * @param connectionList - Array of LConnections to remove from (will be mutated)
+ * @param connection - The LConnection to remove from the array
+ *
+ * @example
+ * ```typescript
+ * const lconnections = [lconn1, lconn2, lconn3];
+ * RemoveLConnectionFromList(lconnections, lconn2);
+ * console.log(lconnections.length); // 2 (lconn2 has been removed)
+ * ```
+ *
+ * @remarks
+ * This is the LConnection variant of RemoveConnectionFromList.
+ * LConnection is a lightweight representation used for performance optimization.
+ * This function mutates the original array using splice().
+ * If the connection is not found (findIndex returns -1), splice will remove the last element.
+ *
+ * @see {@link RemoveConnectionFromList}
+ */
 export declare function RemoveLConnectionFromList(connectionList: LConnection[] | undefined, connection: LConnection): void;

package/dist/types/Helpers/UniqueInsert.d.ts

@@ -1 +1,29 @@
+/**
+ * Unique Insert Helper Module for Concept Connection System (CCS-JS)
+ *
+ * This module provides utility functions for inserting values into arrays while ensuring uniqueness.
+ * It prevents duplicate entries by checking if the value already exists before insertion.
+ *
+ * @module Helpers/UniqueInsert
+ * @see https://documentation.freeschema.com for data structure reference
+ */
+/**
+ * Inserts a number into an array only if it doesn't already exist.
+ *
+ * @param Array - Array of numbers to insert into (will be mutated if insertion occurs)
+ * @param toInsert - The number to insert into the array
+ * @returns The modified array with the number inserted (or unchanged if it already existed)
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3];
+ * InsertUniqueNumber(numbers, 4); // [1, 2, 3, 4]
+ * InsertUniqueNumber(numbers, 2); // [1, 2, 3, 4] (2 already exists, no change)
+ * ```
+ *
+ * @remarks
+ * This function mutates the original array by pushing the value if it's not found.
+ * Uses indexOf() for checking existence, which has O(n) time complexity.
+ * For large arrays with frequent insertions, consider using a Set data structure instead.
+ */
 export default function InsertUniqueNumber(Array: number[], toInsert: number): number[];

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

@@ -1,3 +1,193 @@
+/**
+ * @fileoverview Connection deletion check service for the CCS-JS system.
+ * This module provides utilities for identifying and removing connections that are no longer
+ * needed by comparing old and new connection sets. It's essential for maintaining cache
+ * consistency when compositions are updated or refreshed.
+ * @module Services/CheckForConnectionDeletion
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Identifies and removes connections that exist in the old set but not in the new set.
+ *
+ * This function performs a differential check between old and new connection arrays to find
+ * connections that should be deleted. It's commonly used when updating compositions or
+ * refreshing data from the backend, ensuring that removed connections are cleaned from
+ * the local cache.
+ *
+ * The function iterates through old connections and checks if each one exists in the new
+ * connections array by comparing IDs. If a connection is not found in the new array,
+ * it's removed from the ConnectionData cache.
+ *
+ * @param newConnections - Array of current/updated connections. Defaults to empty array.
+ * @param oldConnections - Array of previous connections to check against. Defaults to empty array.
+ *
+ * @example
+ * ```typescript
+ * // Check and remove deleted connections after composition update
+ * import { CheckForConnectionDeletion } from './CheckForConnectionDeletion';
+ *
+ * const oldConnections = await getCompositionConnections(compositionId);
+ * const newConnections = await refreshCompositionFromBackend(compositionId);
+ *
+ * CheckForConnectionDeletion(newConnections, oldConnections);
+ * // Removes any connections that were deleted on the backend
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle composition refresh with connection cleanup
+ * const cachedConnections = composition.connections;
+ * const freshConnections = await fetchLatestConnections();
+ *
+ * CheckForConnectionDeletion(freshConnections, cachedConnections);
+ * composition.connections = freshConnections;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Clean up connections when switching between compositions
+ * const currentCompositionConnections = getCurrentConnections();
+ * const newCompositionConnections = loadNewComposition();
+ *
+ * CheckForConnectionDeletion(newCompositionConnections, currentCompositionConnections);
+ * ```
+ *
+ * @remarks
+ * **Comparison Logic:**
+ * - Uses array.find() to check if each old connection exists in new connections
+ * - Compares connections by ID (obj.id === oldConnections[i].id)
+ * - Only removes connections that are completely absent from new array
+ *
+ * **Safety Check:**
+ * - Verifies newConnections is an array before comparison
+ * - This prevents errors if newConnections is null or undefined
+ * - Skips deletion if newConnections is not a valid array
+ *
+ * **Side Effects:**
+ * - Directly modifies ConnectionData cache by removing connections
+ * - Permanent removal from cache (cannot be undone)
+ * - Does not affect backend data, only local cache
+ *
+ * **Performance:**
+ * - O(n*m) complexity where n = oldConnections.length, m = newConnections.length
+ * - Uses array.find() for each old connection
+ * - Consider using CheckForConnectionDeletionWithIds for better performance with large arrays
+ *
+ * **Use Cases:**
+ * - Synchronizing local cache with backend state
+ * - Cleaning up after composition updates
+ * - Maintaining cache consistency during data refresh
+ * - Removing orphaned connections
+ *
+ * @see {@link CheckForConnectionDeletionWithIds} for ID-based comparison (better performance)
+ * @see {@link ConnectionData.RemoveConnection} for connection removal implementation
+ * @see {@link Connection} for connection data structure
+ */
 export declare function CheckForConnectionDeletion(newConnections?: Connection[], oldConnections?: Connection[]): void;
+/**
+ * Identifies and removes connections using ID-based comparison for improved performance.
+ *
+ * This function is a more efficient variant of CheckForConnectionDeletion that compares
+ * connection IDs directly instead of searching through connection objects. It uses
+ * Array.includes() which is faster than array.find() for ID lookups, making it better
+ * suited for large datasets.
+ *
+ * The function checks each old connection against an array of new connection IDs.
+ * If an old connection's ID is not in the new ID array, it's removed from the cache.
+ * This is particularly useful when you already have a list of IDs or when working
+ * with large numbers of connections.
+ *
+ * @param newConnectionIds - Array of current connection IDs. Defaults to empty array.
+ * @param oldConnections - Array of previous connection objects to check. Defaults to empty array.
+ *
+ * @example
+ * ```typescript
+ * // Efficient cleanup using ID array
+ * import { CheckForConnectionDeletionWithIds } from './CheckForConnectionDeletion';
+ *
+ * const newConnectionIds = [123, 456, 789];
+ * const oldConnections = cachedComposition.connections;
+ *
+ * CheckForConnectionDeletionWithIds(newConnectionIds, oldConnections);
+ * // Removes connections whose IDs are not in [123, 456, 789]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use when fetching connections from API
+ * const apiResponse = await getConnectionsFromBackend(compositionId);
+ * const newIds = apiResponse.map(conn => conn.id);
+ * const cachedConnections = getLocalConnections();
+ *
+ * CheckForConnectionDeletionWithIds(newIds, cachedConnections);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cleanup connections for a composition update
+ * const updatedConnectionIds = composition.connections.map(c => c.id);
+ * const previousConnections = await getPreviousConnections(composition.id);
+ *
+ * CheckForConnectionDeletionWithIds(updatedConnectionIds, previousConnections);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Filter out deleted connections during sync
+ * const syncedIds = syncData.connectionIds;
+ * const localConnections = ConnectionData.GetAllConnections();
+ *
+ * CheckForConnectionDeletionWithIds(syncedIds, localConnections);
+ * // Removes any local connections not present in sync data
+ * ```
+ *
+ * @remarks
+ * **Performance Advantages:**
+ * - Uses Array.includes() which is O(n) instead of array.find()
+ * - More efficient for large connection arrays
+ * - Better memory usage as only IDs are compared
+ * - Recommended for datasets with 100+ connections
+ *
+ * **Comparison Logic:**
+ * - Checks if oldConnection.id exists in newConnectionIds array
+ * - Simple inclusion check without object comparison
+ * - No need to iterate through connection properties
+ *
+ * **No Safety Check:**
+ * - Does not verify if newConnectionIds is an array
+ * - Will throw if newConnectionIds is null/undefined
+ * - Caller should ensure newConnectionIds is a valid array
+ *
+ * **Side Effects:**
+ * - Removes connections from ConnectionData cache
+ * - Permanent local cache modification
+ * - Does not affect backend or persistent storage
+ *
+ * **When to Use:**
+ * - Large numbers of connections (100+)
+ * - When you already have ID arrays
+ * - Performance-critical operations
+ * - Batch processing scenarios
+ *
+ * **When to Use CheckForConnectionDeletion Instead:**
+ * - Small datasets (< 100 connections)
+ * - When you don't have IDs readily available
+ * - When newConnections might be null/undefined
+ * - When the array check is needed
+ *
+ * **Common Patterns:**
+ * ```typescript
+ * // Pattern 1: Extract IDs from API response
+ * const ids = apiData.map(conn => conn.id);
+ * CheckForConnectionDeletionWithIds(ids, oldConnections);
+ *
+ * // Pattern 2: Use with composition updates
+ * const validIds = getValidConnectionIds(composition);
+ * CheckForConnectionDeletionWithIds(validIds, currentConnections);
+ * ```
+ *
+ * @see {@link CheckForConnectionDeletion} for object-based comparison with safety checks
+ * @see {@link ConnectionData.RemoveConnection} for connection removal implementation
+ * @see {@link Connection} for connection data structure
+ */
 export declare function CheckForConnectionDeletionWithIds(newConnectionIds?: number[], oldConnections?: Connection[]): void;

package/dist/types/Services/Common/DecodeCountInfo.d.ts

@@ -1,3 +1,57 @@
+/**
+ * @module DecodeCountInfo
+ * @description Provides functions to decode and process count information for connections
+ */
 import { CountInfo } from "../../DataStructures/Count/CountInfo";
+/**
+ * Decodes an array of count information strings into CountInfo objects.
+ * Parses encoded count data for connection statistics.
+ *
+ * @param {string[]} [countStrings=[]] - Array of count strings in format "conceptId_connectionTypeId_count"
+ * @returns {CountInfo[]} Array of decoded CountInfo objects
+ *
+ * @example
+ * ```typescript
+ * const countStrings = ["123_456_42", "789_456_15"];
+ * const countInfos = DecodeCountInfo(countStrings);
+ * // countInfos = [
+ * //   { conceptId: 123, connectionTypeId: 456, count: 42 },
+ * //   { conceptId: 789, connectionTypeId: 456, count: 15 }
+ * // ]
+ * ```
+ *
+ * @remarks
+ * - Each string must be in format: "conceptId_connectionTypeId_count"
+ * - All three parts must be numeric
+ * - Returns empty array if no strings provided
+ * - Throws error if string format is invalid
+ */
 export declare function DecodeCountInfo(countStrings?: string[]): CountInfo[];
+/**
+ * Fetches connection type concepts for count information and creates a dictionary.
+ * Enriches CountInfo objects with connection type names and indexes them by concept ID.
+ *
+ * @async
+ * @param {CountInfo[]} countInfos - Array of CountInfo objects to process
+ * @returns {Promise<any>} A promise that resolves to a dictionary mapping concept IDs to enriched CountInfo objects
+ *
+ * @example
+ * ```typescript
+ * const countInfos: CountInfo[] = [
+ *   { conceptId: 123, connectionTypeId: 456, count: 42 },
+ *   { conceptId: 789, connectionTypeId: 456, count: 15 }
+ * ];
+ * const dictionary = await GetConnectionTypeForCount(countInfos);
+ * // dictionary = {
+ * //   123: { conceptId: 123, connectionTypeId: 456, count: 42, connectionType: "follows" },
+ * //   789: { conceptId: 789, connectionTypeId: 456, count: 15, connectionType: "follows" }
+ * // }
+ * ```
+ *
+ * @remarks
+ * - Fetches concept objects for each connectionTypeId
+ * - Adds connectionType (character value) to each CountInfo
+ * - Returns dictionary indexed by conceptId for fast lookup
+ * - Used by formatting functions to add count information
+ */
 export declare function GetConnectionTypeForCount(countInfos: CountInfo[]): Promise<any>;

package/dist/types/Services/Common/ErrorPosting.d.ts

@@ -1,2 +1,51 @@
+/**
+ * @module ErrorPosting
+ * @description Provides error handling functions for HTTP and internal errors with structured error responses
+ */
+/**
+ * Handles HTTP errors by creating and throwing structured error responses.
+ * Specifically handles 401 Unauthorized errors.
+ *
+ * @param {Response} response - The HTTP Response object to process
+ * @throws {FreeSchemaResponse} Throws a structured error response for unauthorized requests
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch("https://api.example.com/data");
+ * HandleHttpError(response);
+ * // Throws FreeSchemaResponse if status is 401
+ * ```
+ *
+ * @remarks
+ * - Currently only handles 401 status codes
+ * - Creates FreeSchemaResponse with status text, success=false, status code, and URL
+ * - Other status codes are not handled (function returns normally)
+ * - Useful for API call error handling
+ */
 export declare function HandleHttpError(response: Response): void;
+/**
+ * Handles internal application errors by creating and throwing structured error responses.
+ * Wraps any error object into a FreeSchemaResponse.
+ *
+ * @param {any} error - The error object to process
+ * @param {string} [url=""] - Optional URL associated with the error
+ * @throws {FreeSchemaResponse} Always throws a structured error response
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Some operation
+ *   throw new Error("Something went wrong");
+ * } catch (error) {
+ *   HandleInternalError(error, "https://api.example.com/data");
+ * }
+ * ```
+ *
+ * @remarks
+ * - Checks if error has a status property to use, defaults to 500
+ * - Creates FreeSchemaResponse with error message, success=false, status, and stack trace
+ * - Sets URL if provided
+ * - Useful for consistent error handling throughout the application
+ * - Always throws after creating the response (never returns)
+ */
 export declare function HandleInternalError(error: any, url?: string): void;

package/dist/types/Services/Common/RegexFunction.d.ts

@@ -1 +1,29 @@
+/**
+ * @module RegexFunction
+ * @description Provides string manipulation functions for concept type names
+ */
+/**
+ * Removes the "the_" prefix from a string if it exists.
+ * Used for cleaning concept type names in the CCS system.
+ *
+ * @param {string} inputString - The string to process
+ * @returns {string} The string with "the_" prefix removed, or the original string if prefix not found
+ *
+ * @example
+ * ```typescript
+ * const typeName = "the_user";
+ * const cleaned = removeThePrefix(typeName);
+ * // cleaned = "user"
+ *
+ * const noPrefix = "post";
+ * const unchanged = removeThePrefix(noPrefix);
+ * // unchanged = "post"
+ * ```
+ *
+ * @remarks
+ * - Only removes prefix if string starts with exactly "the_"
+ * - Case-sensitive matching
+ * - Returns original string if prefix not found
+ * - Used throughout formatting functions to clean type names
+ */
 export declare function removeThePrefix(inputString: string): string;

package/dist/types/Services/Composition/BuildComposition.d.ts

@@ -1,3 +1,40 @@
+/**
+ * @module BuildComposition
+ * @description Provides functions to recursively build composition structures from concepts and connections with caching support
+ */
 import { Connection } from '../../DataStructures/Connection';
 import { Concept } from '../../DataStructures/Concept';
+/**
+ * Recursively fetches and builds a composition structure from provided concepts and connections.
+ * Uses passed data rather than querying externally, with backend fallback for missing data.
+ *
+ * @async
+ * @param {number} id - The concept ID to start building the composition from
+ * @param {Connection[]} connectionList - Array of all connections to use for building
+ * @param {Concept[]} conceptList - Array of all concepts available for building
+ * @param {compositionList} compositionList - Array of concept IDs that are compositions (not leaf values)
+ * @param {number[]} [visitedConcepts=[]] - Array tracking visited concept IDs to prevent circular references
+ * @returns {Promise<any>} A promise that resolves to the built composition object or character value
+ *
+ * @example
+ * ```typescript
+ * const conceptId = 123;
+ * const connections: Connection[] = [...];
+ * const concepts: Concept[] = [...];
+ * const compositionIds = [123, 456];
+ * const visited: number[] = [];
+ * const result = await recursiveFetchNew(conceptId, connections, concepts, compositionIds, visited);
+ * // result = { user: { name: "John", email: "john@example.com" } }
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Works with pre-loaded concepts and connections (no external queries during recursion)
+ * - Falls back to backend API if concept/connection not found in provided lists
+ * - Tracks visited concepts to prevent infinite loops in circular relationships
+ * - Distinguishes between composition nodes (objects/arrays) and leaf values (strings)
+ * - Removes "the_" prefix from type names for cleaner keys
+ * - Handles numeric types as arrays, string types as objects
+ * - Returns empty string for concepts not in compositionList (leaf values)
+ */
 export declare function recursiveFetchNew(id: number, connectionList: Connection[], conceptList: Concept[], compositionList: number[], visitedConcepts?: number[]): Promise<any>;

package/dist/types/Services/Composition/CompositionCache.d.ts

@@ -1,4 +1,93 @@
+/**
+ * @module CompositionCache
+ * @description Provides composition retrieval functions with caching support for improved performance
+ */
 import { Connection } from '../../DataStructures/Connection';
+/**
+ * Retrieves a composition by ID with caching support, optionally using provided connections.
+ * Returns a formatted composition object with all internal connections.
+ *
+ * @async
+ * @param {number} id - The composition concept ID to retrieve
+ * @param {Connection[]} [connectionListPassed=[]] - Optional pre-fetched connections for this composition
+ * @returns {Promise<any>} A promise that resolves to the formatted composition object
+ *
+ * @example
+ * ```typescript
+ * // Retrieve composition without pre-loaded connections
+ * const composition = await GetCompositionWithCache(123);
+ * // composition = { user: { name: "John", email: "john@example.com" } }
+ *
+ * // Retrieve composition with pre-loaded connections (more efficient)
+ * const connections: Connection[] = [...]; // Previously fetched
+ * const composition = await GetCompositionWithCache(123, connections);
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Checks local cache (ConceptsData) before making API calls
+ * - Uses provided connections if available, otherwise fetches them
+ * - Builds list of composition IDs and concept IDs from connections
+ * - Recursively builds the composition structure
+ * - Returns empty string if concept ID is 0
+ * - Uses concept type as the root key in returned object
+ */
 export declare function GetCompositionWithCache(id: number, connectionListPassed?: Connection[]): Promise<any>;
+/**
+ * Retrieves a composition by ID in DATA-ID format with caching support.
+ * Returns composition with id, data, and created_at fields.
+ *
+ * @async
+ * @param {number} id - The composition concept ID to retrieve
+ * @param {Connection[]} [connectionListPassed=[]] - Optional pre-fetched connections for this composition
+ * @returns {Promise<any>} A promise that resolves to composition object with id, data, and created_at properties
+ *
+ * @example
+ * ```typescript
+ * const composition = await GetCompositionWithDataIdWithCache(123);
+ * // composition = {
+ * //   id: 123,
+ * //   data: { user: { name: "John", email: "john@example.com" } },
+ * //   created_at: "2023-10-30T12:00:00Z"
+ * // }
+ * ```
+ *
+ * @remarks
+ * Format: DATA-ID - Includes explicit ID and timestamp information
+ * This function:
+ * - Similar to GetCompositionWithCache but includes ID metadata
+ * - Returns object with id, data (composition tree), and created_at
+ * - Uses caching for improved performance
+ * - Returns empty string if concept ID is 0
+ */
 export declare function GetCompositionWithDataIdWithCache(id: number, connectionListPassed?: Connection[]): Promise<any>;
+/**
+ * Retrieves multiple compositions in bulk using DATA-ID format.
+ * Efficiently fetches multiple compositions with their internal connections in one operation.
+ *
+ * @async
+ * @param {number[]} ids - Array of composition concept IDs to retrieve
+ * @param {number[]} connections - Array of connection IDs for all compositions
+ * @returns {Promise<any[]>} A promise that resolves to array of composition objects with DATA-ID format
+ *
+ * @example
+ * ```typescript
+ * const compositionIds = [123, 456, 789];
+ * const connectionIds = [1, 2, 3, 4, 5];
+ * const compositions = await GetCompositionWithDataIdBulk(compositionIds, connectionIds);
+ * // compositions = [
+ * //   { id: 123, data: {...}, created_at: timestamp },
+ * //   { id: 456, data: {...}, created_at: timestamp },
+ * //   { id: 789, data: {...}, created_at: timestamp }
+ * // ]
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Optimized for bulk operations to reduce API calls
+ * - Fetches all connections once, then filters per composition
+ * - Each result includes id, data object, and created_at timestamp
+ * - Filters out null/undefined compositions from results
+ * - More efficient than calling GetCompositionWithDataIdWithCache individually
+ */
 export declare function GetCompositionWithDataIdBulk(ids: number[], connections: number[]): Promise<any[]>;

package/dist/types/Services/Composition/CreateCompositionCache.d.ts

@@ -1,3 +1,46 @@
+/**
+ * @module CreateCompositionCache
+ * @description Provides functionality to create compositions from JSON objects with caching support
+ */
 import { Concept } from '../../DataStructures/Concept';
 import { Composition } from '../../DataStructures/Composition/Composition';
+/**
+ * Creates a composition from a JSON object with caching mechanism.
+ * Recursively processes nested objects/arrays to create concepts and connections.
+ *
+ * @async
+ * @param {any} json - The JSON object to convert into a composition
+ * @param {number | null} [ofTheConceptId=null] - Parent concept ID (null for root)
+ * @param {number | null} [ofTheConceptUserId=null] - Parent concept's user ID
+ * @param {number | null} [mainKey=null] - Main composition ID (root concept ID)
+ * @param {number | null} [userId=null] - User ID creating the composition (defaults to 999)
+ * @param {number | null} [accessId=null] - Access level ID (defaults to 4)
+ * @param {number | null} [sessionInformationId=null] - Session ID (defaults to 999)
+ * @param {Composition | null} [composition=null] - Existing Composition object to populate
+ * @returns {Promise<Concept>} A promise that resolves to the main (root) Concept of the composition
+ *
+ * @example
+ * ```typescript
+ * const jsonData = {
+ *   user: {
+ *     name: "John",
+ *     email: "john@example.com",
+ *     age: 30
+ *   }
+ * };
+ * const mainConcept = await CreateTheCompositionWithCache(jsonData, null, null, null, 1, 4, 1);
+ * // Creates concepts for user, name, email, age with proper connections
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Recursively processes nested JSON structures
+ * - Creates concepts for each key-value pair
+ * - Establishes connections between parent and child concepts
+ * - Distinguishes between composition nodes (objects/arrays) and leaf values (primitives)
+ * - Populates the Composition object with all concepts and connections
+ * - Uses caching for improved performance
+ * - First call (no parent) creates the root concept
+ * - Subsequent recursive calls create child concepts linked to parents
+ */
 export declare function CreateTheCompositionWithCache(json: any, ofTheConceptId?: number | null, ofTheConceptUserId?: number | null, mainKey?: number | null, userId?: number | null, accessId?: number | null, sessionInformationId?: number | null, composition?: Composition | null): Promise<Concept>;