mftsccs-node 0.0.57 → 0.0.59

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

@@ -1 +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;

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

@@ -1,11 +1,342 @@
+/**
+ * Composition Retrieval and Reconstruction Service
+ *
+ * This module provides comprehensive functionality for retrieving compositions (structured
+ * concept graphs) and reconstructing them into JSON objects. It's the deserialization
+ * counterpart to CreateTheComposition, converting graph structures back into hierarchical
+ * data structures.
+ *
+ * The module offers multiple variants for different use cases:
+ * - Basic composition retrieval (from API or memory)
+ * - Composition with metadata (ID, timestamps)
+ * - Composition with sub-composition IDs included
+ * - Bulk operations and optimization strategies
+ *
+ * @module GetComposition
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves a composition from the API and reconstructs it as a JSON object.
+ *
+ * This function fetches all connections that make up a composition from the API,
+ * then recursively reconstructs the original hierarchical structure. It's the primary
+ * function for deserializing compositions that were created using CreateTheComposition.
+ *
+ * The returned object has the composition's type as the root key, containing the
+ * nested data structure.
+ *
+ * @param id - The ID of the root concept of the composition
+ *
+ * @returns A promise that resolves to an object with the composition data
+ *
+ * @example
+ * ```typescript
+ * // Retrieve a user profile composition
+ * const composition = await GetComposition(12345);
+ * console.log(composition);
+ * // Output:
+ * // {
+ * //   "user_profile": {
+ * //     "name": "Alice Johnson",
+ * //     "age": "30",
+ * //     "address": {
+ * //       "street": "123 Main St",
+ * //       "city": "Springfield"
+ * //     }
+ * //   }
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Access specific fields in the composition
+ * const bookData = await GetComposition(789);
+ * const book = bookData["book"];
+ * console.log("Title:", book.title);
+ * console.log("Author:", book.author);
+ * console.log("ISBN:", book.isbn);
+ * ```
+ *
+ * @remarks
+ * - Fetches all connections from the API (not from local cache)
+ * - Recursively reconstructs the hierarchical structure
+ * - The root key is the type of the root concept (e.g., "book", "user_profile")
+ * - Numeric keys indicate array-like structures
+ * - Leaf nodes contain their characterValue as strings
+ * - Uses GetAllConnectionsOfComposition API for data fetching
+ * - For better performance with cached data, use GetCompositionFromMemory
+ *
+ * @see {@link GetCompositionFromMemory} for cached/memory-based retrieval
+ * @see {@link GetCompositionWithId} for including composition metadata
+ * @see {@link CreateTheComposition} for the inverse operation (JSON to composition)
+ * @see {@link recursiveFetch} for the reconstruction algorithm
+ */
 export declare function GetComposition(id: number): Promise<any>;
+/**
+ * Retrieves a composition with sub-composition IDs embedded in the structure.
+ *
+ * Similar to GetComposition, but includes "id" fields for all sub-compositions
+ * within the returned JSON structure. This is useful when you need to reference
+ * or update specific parts of the composition later.
+ *
+ * @param id - The ID of the root concept of the composition
+ *
+ * @returns A promise that resolves to an object with the composition data including IDs
+ *
+ * @example
+ * ```typescript
+ * // Get composition with IDs for updating specific nodes
+ * const composition = await GetCompositionWithAllIds(12345);
+ * console.log(composition);
+ * // Output includes id fields:
+ * // {
+ * //   "user_profile": {
+ * //     "id": 12345,
+ * //     "address": {
+ * //       "id": 12346,
+ * //       "street": "123 Main St"
+ * //     }
+ * //   }
+ * // }
+ * ```
+ *
+ * @remarks
+ * - Each sub-composition node includes its concept ID
+ * - Uses recursiveFetchWithSubCompositions instead of recursiveFetch
+ * - Useful for selective updates or references to composition parts
+ *
+ * @see {@link GetComposition} for standard retrieval without IDs
+ * @see {@link recursiveFetchWithSubCompositions} for the reconstruction algorithm
+ */
 export declare function GetCompositionWithAllIds(id: number): Promise<any>;
+/**
+ * Retrieves a composition from local memory cache without API calls.
+ *
+ * This optimized version retrieves composition data from the local ConnectionData
+ * cache rather than making API calls. It's significantly faster but requires that
+ * the connections have been previously cached (e.g., via bulk prefetch operations).
+ *
+ * @param id - The ID of the root concept of the composition
+ *
+ * @returns A promise that resolves to an object with the composition data
+ *
+ * @example
+ * ```typescript
+ * // After bulk prefetch, retrieve from memory
+ * await GetAllConnectionsOfCompositionBulk([123, 456, 789]);
+ *
+ * // Now quickly retrieve from cache
+ * const comp1 = await GetCompositionFromMemory(123);
+ * const comp2 = await GetCompositionFromMemory(456);
+ * const comp3 = await GetCompositionFromMemory(789);
+ * // Much faster than individual API calls
+ * ```
+ *
+ * @remarks
+ * - Only works if connections are already cached in ConnectionData
+ * - Returns empty or incomplete data if connections aren't cached
+ * - Use after bulk prefetch operations for optimal performance
+ * - Much faster than GetComposition for batch operations
+ *
+ * @see {@link GetComposition} for API-based retrieval
+ * @see {@link GetAllConnectionsOfCompositionBulk} for bulk prefetching
+ */
 export declare function GetCompositionFromMemory(id: number): Promise<any>;
+/**
+ * Retrieves a composition from memory with metadata wrapper.
+ *
+ * Returns composition data wrapped in an object that includes the root concept's
+ * ID and creation timestamp along with the data. This is useful for tracking
+ * when compositions were created and referencing them by ID.
+ *
+ * @param id - The ID of the root concept of the composition
+ *
+ * @returns A promise that resolves to an object with id, created_at, and data fields
+ *
+ * @example
+ * ```typescript
+ * const result = await GetCompositionWithIdFromMemory(12345);
+ * console.log(result);
+ * // Output:
+ * // {
+ * //   id: 12345,
+ * //   created_at: "1/15/2024 3:45:30 PM",
+ * //   data: {
+ * //     "book": {
+ * //       "title": "Example Book",
+ * //       "author": "Jane Doe"
+ * //     }
+ * //   }
+ * // }
+ * ```
+ *
+ * @remarks
+ * - Requires connections to be cached in memory
+ * - Includes root concept's entryTimeStamp as created_at
+ * - Data structure: { id, created_at, data }
+ *
+ * @see {@link GetCompositionFromMemory} for unwrapped retrieval
+ * @see {@link GetCompositionWithId} for API-based version
+ */
 export declare function GetCompositionWithIdFromMemory(id: number): Promise<any>;
+/**
+ * Retrieves a composition from memory with ID and timestamp metadata.
+ *
+ * Similar to GetCompositionWithIdFromMemory but with a slightly different
+ * field order in the returned object. This variant exists for backward
+ * compatibility with different parts of the codebase.
+ *
+ * @param id - The ID of the root concept of the composition
+ *
+ * @returns A promise that resolves to an object with data, id, and created_at fields
+ *
+ * @remarks
+ * - Field order: data, id, created_at (vs id, created_at, data in other variant)
+ * - Otherwise identical to GetCompositionWithIdFromMemory
+ *
+ * @see {@link GetCompositionWithIdFromMemory} for the primary variant
+ */
 export declare function GetCompositionWithIdAndDateFromMemory(id: number): Promise<any>;
+/**
+ * Reconstructs a composition from a provided list of connections.
+ *
+ * This specialized function allows you to reconstruct a composition when you
+ * already have the connections in memory. Useful for optimized bulk operations
+ * where connections have been fetched once and reused for multiple compositions.
+ *
+ * @param id - The ID of the root concept of the composition
+ * @param connectionList - Pre-fetched array of Connection objects
+ *
+ * @returns A promise that resolves to an object with id, created_at, and data fields
+ *
+ * @example
+ * ```typescript
+ * // Fetch connections once for multiple compositions
+ * const connections = await GetAllConnectionsOfCompositionBulk([123, 456]);
+ *
+ * // Reconstruct multiple compositions from the same connection set
+ * const comp1 = await GetCompositionWithIdFromMemoryFromConnections(123, connections);
+ * const comp2 = await GetCompositionWithIdFromMemoryFromConnections(456, connections);
+ * ```
+ *
+ * @remarks
+ * - Most efficient when connections are shared across compositions
+ * - Extracts composition list from provided connections
+ * - No API or cache lookups for connections
+ *
+ * @see {@link GetCompositionFromConnectionsWithDataId} for newer variant
+ */
 export declare function GetCompositionWithIdFromMemoryFromConnections(id: number, connectionList: Connection[]): Promise<any>;
+/**
+ * Reconstructs a composition from connections with optional pre-computed composition list.
+ *
+ * An optimized variant that accepts an optional pre-computed list of composition IDs,
+ * avoiding the need to extract it from connections. This is the most efficient variant
+ * for bulk operations.
+ *
+ * @param id - The ID of the root concept of the composition
+ * @param connectionList - Pre-fetched array of Connection objects
+ * @param compositionList - Optional pre-computed array of composition concept IDs (default: empty array)
+ *
+ * @returns A promise that resolves to an object with id, created_at, and data fields
+ *
+ * @remarks
+ * - Most efficient variant when composition list is pre-computed
+ * - If compositionList is empty, computes it from connections
+ * - Useful in high-performance scenarios with many compositions
+ *
+ * @see {@link GetCompositionWithIdFromMemoryFromConnections} for basic variant
+ */
 export declare function GetCompositionWithIdFromMemoryFromConnectionsNew(id: number, connectionList: Connection[], compositionList?: number[]): Promise<any>;
+/**
+ * Retrieves a composition from API with metadata wrapper.
+ *
+ * Similar to GetComposition but includes the composition ID and wraps the data
+ * in a structured object. Uses API calls rather than memory cache.
+ *
+ * @param id - The ID of the root concept of the composition
+ *
+ * @returns A promise that resolves to an object with data and id fields
+ *
+ * @example
+ * ```typescript
+ * const result = await GetCompositionWithId(12345);
+ * console.log("Composition ID:", result.id);
+ * console.log("Data:", result.data);
+ * ```
+ *
+ * @remarks
+ * - Fetches from API, not from cache
+ * - Includes composition ID in return structure
+ * - Data structure: { data, id }
+ *
+ * @see {@link GetComposition} for unwrapped version
+ * @see {@link GetCompositionWithIdFromMemory} for cached version
+ */
 export declare function GetCompositionWithId(id: number): Promise<any>;
+/**
+ * Recursively reconstructs a composition structure from connections.
+ *
+ * This is the core algorithm that traverses connections and rebuilds the hierarchical
+ * JSON structure from the graph representation. It handles both object-like structures
+ * (with string keys) and array-like structures (with numeric keys).
+ *
+ * The algorithm works by:
+ * 1. Checking if the concept is a leaf node (not in compositionList) - returns its value
+ * 2. For composition nodes, iterating through all outgoing connections
+ * 3. Recursively processing each connected concept
+ * 4. Building either an object or array based on key type
+ * 5. Preventing infinite loops by tracking visited concepts
+ *
+ * @param id - The ID of the concept to process
+ * @param connectionList - All connections in the composition
+ * @param compositionList - Array of concept IDs that are composition nodes (not leaves)
+ * @param visitedConcepts - Internal tracker to prevent circular reference loops (default: empty array)
+ *
+ * @returns A promise that resolves to the reconstructed data structure (object, array, or primitive value)
+ *
+ * @example
+ * ```typescript
+ * // This function is typically called internally by GetComposition functions
+ * // Manual usage:
+ * const connections = await GetAllConnectionsOfComposition(12345);
+ * const compositionList = extractCompositionList(connections);
+ * const result = await recursiveFetch(12345, connections, compositionList);
+ * ```
+ *
+ * @remarks
+ * - Strips "the_" prefix from concept type names when used as keys
+ * - Numeric keys create array-like structures, string keys create object structures
+ * - Leaf nodes (not in compositionList) return their characterValue
+ * - Returns empty string for circular references (visited concepts)
+ * - Fetches concept type information if not cached
+ * - Handles null/undefined concept types gracefully
+ * - Returns null for id=0
+ *
+ * @see {@link GetComposition} which uses this function
+ * @see {@link recursiveFetchWithSubCompositions} for variant that includes IDs
+ */
 export declare function recursiveFetch(id: number, connectionList: Connection[], compositionList: number[], visitedConcepts?: number[]): Promise<any>;
+/**
+ * Recursively reconstructs a composition with concept IDs embedded in the structure.
+ *
+ * Similar to recursiveFetch but adds an "id" field to each sub-composition node in the
+ * returned structure. This enables tracking which concept ID corresponds to each part
+ * of the reconstructed data.
+ *
+ * @param id - The ID of the concept to process
+ * @param connectionList - All connections in the composition
+ * @param compositionList - Array of concept IDs that are composition nodes
+ * @param visitedConcepts - Internal tracker to prevent circular loops (default: empty array)
+ *
+ * @returns A promise that resolves to the reconstructed structure with embedded IDs
+ *
+ * @remarks
+ * - Each composition node includes an "id" field
+ * - Otherwise identical to recursiveFetch
+ * - Used by GetCompositionWithAllIds
+ *
+ * @see {@link recursiveFetch} for the standard version
+ * @see {@link GetCompositionWithAllIds} which uses this function
+ */
 export declare function recursiveFetchWithSubCompositions(id: number, connectionList: Connection[], compositionList: number[], visitedConcepts?: number[]): Promise<any>;

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

@@ -1,11 +1,259 @@
+/**
+ * Bulk Composition Retrieval Service
+ *
+ * This module provides high-performance functions for retrieving multiple compositions
+ * simultaneously. It implements sophisticated bulk prefetching and caching strategies
+ * to minimize API calls and optimize performance when dealing with large batches of
+ * compositions.
+ *
+ * The module offers several variants optimized for different scenarios:
+ * - Basic bulk retrieval
+ * - Bulk with metadata (IDs and timestamps)
+ * - Optimized variants using pre-fetched connection data
+ * - Connection and concept prefetching utilities
+ *
+ * @module GetCompositionBulk
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves multiple compositions in bulk with optimized prefetching.
+ *
+ * This function fetches multiple compositions simultaneously by first bulk-prefetching
+ * all their connections in a single API call, then reconstructing each composition
+ * from cached data. This is significantly more efficient than fetching compositions
+ * individually.
+ *
+ * @param ids - Array of composition root concept IDs to retrieve (default: empty array)
+ *
+ * @returns A promise that resolves to an array of composition objects
+ *
+ * @example
+ * ```typescript
+ * // Fetch multiple blog posts at once
+ * const postIds = [123, 456, 789, 101112];
+ * const posts = await GetCompositionBulk(postIds);
+ *
+ * console.log(`Retrieved ${posts.length} posts`);
+ * posts.forEach((post, index) => {
+ *   console.log(`Post ${postIds[index]}:`, post);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load user profiles for a list of users
+ * const userIds = await getUserIdsFromSearch("John");
+ * const profiles = await GetCompositionBulk(userIds);
+ *
+ * profiles.forEach(profile => {
+ *   const userData = profile["user_profile"];
+ *   console.log(`Name: ${userData.name}, Email: ${userData.email}`);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Bulk prefetches all connections in a single API call
+ * - Reconstructs compositions from cached connection data
+ * - Much more efficient than individual GetComposition calls
+ * - Returns compositions in the same order as input IDs
+ * - Empty compositions returned for invalid IDs
+ * - Uses GetAllConnectionsOfCompositionBulk for prefetch
+ * - Uses GetCompositionFromMemory for reconstruction
+ *
+ * @see {@link GetCompositionBulkWithDataId} for version with metadata
+ * @see {@link GetAllConnectionsOfCompositionBulk} for bulk connection prefetch
+ * @see {@link GetCompositionFromMemory} for individual reconstruction
+ */
 export declare function GetCompositionBulk(ids?: number[]): Promise<any[]>;
+/**
+ * Retrieves multiple compositions in bulk with metadata wrappers.
+ *
+ * Similar to GetCompositionBulk, but each composition includes metadata (ID and
+ * creation timestamp) in the returned structure. This is useful when you need to
+ * track or reference individual compositions while processing bulk data.
+ *
+ * @param ids - Array of composition root concept IDs to retrieve (default: empty array)
+ *
+ * @returns A promise that resolves to an array of objects with id, created_at, and data fields
+ *
+ * @example
+ * ```typescript
+ * // Fetch posts with metadata for display
+ * const postIds = [123, 456, 789];
+ * const postsWithMeta = await GetCompositionBulkWithDataId(postIds);
+ *
+ * postsWithMeta.forEach(post => {
+ *   console.log(`Post ID: ${post.id}`);
+ *   console.log(`Created: ${post.created_at}`);
+ *   console.log(`Title: ${post.data["blog_post"].title}`);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Each item includes: { id, created_at, data }
+ * - Uses bulk prefetch for optimal performance
+ * - Otherwise identical to GetCompositionBulk
+ *
+ * @see {@link GetCompositionBulk} for version without metadata
+ * @see {@link GetCompositionWithIdFromMemory} for individual retrieval with metadata
+ */
 export declare function GetCompositionBulkWithDataId(ids?: number[]): Promise<any[]>;
+/**
+ * Retrieves compositions using a specific set of connection IDs.
+ *
+ * This function fetches compositions but allows you to specify exactly which connections
+ * to use for reconstruction. It also performs connection deletion checking to ensure
+ * cached data is up-to-date.
+ *
+ * @param ids - Array of composition root concept IDs
+ * @param connections - Array of specific connection IDs to use (default: empty array)
+ *
+ * @returns A promise that resolves to an array of objects with id, created_at, and data fields
+ *
+ * @example
+ * ```typescript
+ * // Fetch compositions using specific connections
+ * const compositionIds = [123, 456];
+ * const connectionIds = [789, 101112, 131415];
+ *
+ * const compositions = await GetCompositionFromConnectionsWithDataId(
+ *   compositionIds,
+ *   connectionIds
+ * );
+ * ```
+ *
+ * @remarks
+ * - Fetches only specified connections
+ * - Checks for connection deletions to maintain cache validity
+ * - Updates cache with newly fetched connections
+ * - Uses GetCompositionWithIdFromMemory for reconstruction
+ *
+ * @see {@link GetCompositionBulkWithDataId} for standard bulk retrieval
+ * @see {@link CheckForConnectionDeletionWithIds} for deletion checking
+ */
 export declare function GetCompositionFromConnectionsWithDataId(ids?: number[], connections?: number[]): Promise<any[]>;
 /**
- * Used to prefetch all the connections and their related concepts.
- * @param connectionIds these are the connection ids that are used to fetch all the connections and also their related concepts.
- * @returns all the connections that are passed as ids.
+ * Prefetches connections and their related concepts for optimal performance.
+ *
+ * This utility function fetches a batch of connections by ID and also prefetches all
+ * the concepts referenced by those connections (ofTheConcept, toTheConcept, and type).
+ * This ensures that when you later reconstruct compositions, all necessary data is
+ * already in the cache.
+ *
+ * The function implements a smart caching strategy: it first checks the local cache
+ * for each connection, then bulk-fetches only the missing ones from the API.
+ *
+ * @param connectionIds - Array of connection IDs to prefetch (default: empty array)
+ *
+ * @returns A promise that resolves to an array of all prefetched Connection objects
+ *
+ * @example
+ * ```typescript
+ * // Prefetch connections before processing
+ * const connectionIds = [123, 456, 789, 101112];
+ * const connections = await GetConnectionDataPrefetch(connectionIds);
+ *
+ * console.log(`Prefetched ${connections.length} connections`);
+ * // Now all related concepts are also cached
+ *
+ * // Subsequent operations will be faster
+ * for (const conn of connections) {
+ *   const fromConcept = await GetTheConcept(conn.ofTheConceptId); // Fast, from cache
+ *   const toConcept = await GetTheConcept(conn.toTheConceptId);   // Fast, from cache
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use before bulk composition operations
+ * const compositionIds = [123, 456, 789];
+ *
+ * // First, get all connection IDs for these compositions
+ * const allConnectionIds = await getConnectionIdsForCompositions(compositionIds);
+ *
+ * // Prefetch everything
+ * await GetConnectionDataPrefetch(allConnectionIds);
+ *
+ * // Now reconstruct compositions - will be very fast
+ * const compositions = await Promise.all(
+ *   compositionIds.map(id => GetCompositionFromMemory(id))
+ * );
+ * ```
+ *
+ * @remarks
+ * - Checks ConnectionData cache before making API calls
+ * - Only fetches connections that aren't already cached
+ * - Automatically prefetches all concepts referenced by connections:
+ *   - ofTheConceptId (source concept)
+ *   - toTheConceptId (target concept)
+ *   - typeId (connection type concept)
+ * - Uses GetConnectionBulk for efficient batch fetching
+ * - Uses GetConceptBulk to prefetch all related concepts
+ * - Returns all connections, both cached and newly fetched
+ * - Significantly improves performance for composition reconstruction
+ *
+ * @see {@link GetConnectionBulk} for bulk connection fetching
+ * @see {@link GetConceptBulk} for bulk concept prefetching
+ * @see {@link ConnectionData.GetConnection} for cache lookup
  */
 export declare function GetConnectionDataPrefetch(connectionIds?: number[]): Promise<Connection[]>;
+/**
+ * Retrieves compositions in bulk with optimized connection reuse, returning an object map.
+ *
+ * This is a highly optimized function for retrieving multiple compositions. Instead of
+ * returning an array, it returns an object where keys are composition IDs and values
+ * are the composition data. It reuses a single set of connections for all compositions,
+ * making it extremely efficient for large batches.
+ *
+ * The function fetches connections once, then reconstructs all compositions from the
+ * same connection pool. This approach minimizes memory usage and processing time.
+ *
+ * @param ids - Array of composition root concept IDs
+ * @param connections - Array of connection IDs to use for all compositions (default: empty array)
+ *
+ * @returns A promise that resolves to an object mapping composition IDs to their data
+ *
+ * @example
+ * ```typescript
+ * // Fetch multiple compositions as a map
+ * const compositionIds = [123, 456, 789];
+ * const connectionIds = [1001, 1002, 1003, 1004, 1005];
+ *
+ * const compositionMap = await GetCompositionFromConnectionsWithDataIdInObject(
+ *   compositionIds,
+ *   connectionIds
+ * );
+ *
+ * // Access by ID
+ * console.log("Composition 123:", compositionMap[123]);
+ * console.log("Composition 456:", compositionMap[456]);
+ * console.log("Composition 789:", compositionMap[789]);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Efficient lookup for UI rendering
+ * const ids = [10, 20, 30, 40, 50];
+ * const connectionIds = await getAllConnectionIds(ids);
+ * const dataMap = await GetCompositionFromConnectionsWithDataIdInObject(ids, connectionIds);
+ *
+ * // Fast random access
+ * renderComponent(dataMap[20]);
+ * renderComponent(dataMap[40]);
+ * ```
+ *
+ * @remarks
+ * - Returns object instead of array for O(1) lookup by ID
+ * - Fetches connections once and reuses for all compositions
+ * - Separates cached and non-cached connections for efficiency
+ * - Computes composition list once and reuses it
+ * - Each composition includes: { id, created_at, data }
+ * - Uses GetCompositionWithIdFromMemoryFromConnectionsNew for reconstruction
+ * - Includes console.time/timeEnd for performance monitoring
+ * - Most efficient for large batches with shared connections
+ *
+ * @see {@link GetCompositionBulkWithDataId} for array-based bulk retrieval
+ * @see {@link GetConnectionBulk} for connection fetching
+ * @see {@link GetCompositionWithIdFromMemoryFromConnectionsNew} for reconstruction
+ */
 export declare function GetCompositionFromConnectionsWithDataIdInObject(ids?: number[], connections?: number[]): Promise<any>;