mftsccs-node 0.0.57 → 0.0.58

package/dist/types/Api/GetAllConnectionsOfComposition.d.ts

@@ -1,3 +1,82 @@
+/**
+ * API module for retrieving connections associated with a specific composition.
+ * This module handles both local caching and remote fetching of composition connections,
+ * with automatic synchronization and deletion detection.
+ *
+ * @module Api/GetAllConnectionsOfComposition
+ * @see https://documentation.freeschema.com for more information on the Concept Connection System
+ */
 import { Connection } from '../DataStructures/Connection';
+/**
+ * Retrieves all connections associated with a specific composition, using local cache when available.
+ * This function implements a smart caching strategy: it first checks for locally stored connections,
+ * and if found, fetches fresh data from the server to detect any deletions or changes. If no local
+ * data exists, it directly fetches from the server.
+ *
+ * A composition represents a group or collection of related concepts and their connections.
+ * This function ensures that all connections within a composition are available and synchronized
+ * with the remote server.
+ *
+ * @param composition_id - The unique identifier of the composition whose connections should be retrieved
+ *
+ * @returns A promise that resolves to an array of Connection objects belonging to the composition
+ *
+ * @example
+ * ```typescript
+ * // Fetch all connections for composition 456
+ * const connections = await GetAllConnectionsOfComposition(456);
+ *
+ * // Process the connections
+ * connections.forEach(conn => {
+ *   console.log(`Connection: ${conn.id} links concepts`);
+ * });
+ * ```
+ *
+ * @remarks
+ * This function implements a two-step synchronization process:
+ * 1. First fetch: Retrieves from local cache if available
+ * 2. Online fetch: Always fetches fresh data from server
+ * 3. Deletion check: Compares old and new data to detect removed connections
+ *
+ * This approach ensures data consistency while maintaining local performance benefits.
+ *
+ * @see GetAllConnectionsOfCompositionOnline for the underlying server fetch operation
+ * @see CheckForConnectionDeletion for how deleted connections are detected
+ * @see ConnectionData.GetConnectionsOfCompositionLocal for local cache access
+ */
 export declare function GetAllConnectionsOfComposition(composition_id: number): Promise<Connection[]>;
+/**
+ * Fetches connections for a specific composition directly from the remote server.
+ * This function bypasses local caching and always retrieves fresh data from the backend,
+ * making it suitable for ensuring data accuracy and detecting server-side changes.
+ *
+ * All retrieved connections are automatically added to the local ConnectionData store
+ * for subsequent use throughout the application.
+ *
+ * @param composition_id - The unique identifier of the composition whose connections should be fetched
+ *
+ * @returns A promise that resolves to an array of Connection objects retrieved from the server
+ *
+ * @example
+ * ```typescript
+ * // Fetch fresh connections directly from server
+ * const connections = await GetAllConnectionsOfCompositionOnline(456);
+ *
+ * // Compare with cached data
+ * const cachedConnections = await ConnectionData.GetConnectionsOfCompositionLocal(456);
+ * ```
+ *
+ * @remarks
+ * This is the underlying server communication function used by GetAllConnectionsOfComposition.
+ * It should generally not be called directly unless you specifically need to bypass caching
+ * and force a fresh server fetch.
+ *
+ * Each retrieved connection is added to ConnectionData, making it available for local queries
+ * and reducing the need for subsequent server requests.
+ *
+ * @throws Will throw an error if the network request fails or if the server returns an error response
+ *
+ * @see GetAllConnectionsOfComposition for the recommended high-level function with caching
+ * @see ConnectionData.AddConnection for how connections are stored locally
+ */
 export declare function GetAllConnectionsOfCompositionOnline(composition_id: number): Promise<Connection[]>;

package/dist/types/Api/GetAllConnectionsOfCompositionBulk.d.ts

@@ -1,3 +1,93 @@
+/**
+ * API module for retrieving connections for multiple compositions in a single bulk operation.
+ * This module optimizes performance by fetching connections for multiple compositions at once,
+ * with automatic synchronization, deletion detection, and concept resolution.
+ *
+ * @module Api/GetAllConnectionsOfCompositionBulk
+ * @see https://documentation.freeschema.com for more information on the Concept Connection System
+ */
 import { Connection } from '../DataStructures/Connection';
+/**
+ * Retrieves connections for multiple compositions in a single bulk operation for improved performance.
+ * This function fetches connections for multiple composition IDs at once, checks for deletions by
+ * comparing with in-memory data, and automatically resolves all referenced concepts.
+ *
+ * Bulk operations are significantly more efficient than individual requests when working with
+ * multiple compositions, reducing network overhead and improving application responsiveness.
+ *
+ * @param composition_ids - Array of composition IDs whose connections should be retrieved. Defaults to empty array.
+ *
+ * @returns A promise that resolves to an array of Connection objects from all specified compositions
+ *
+ * @example
+ * ```typescript
+ * // Fetch connections for multiple compositions at once
+ * const compositionIds = [100, 200, 300];
+ * const connections = await GetAllConnectionsOfCompositionBulk(compositionIds);
+ *
+ * console.log(`Retrieved ${connections.length} connections`);
+ *
+ * // All referenced concepts are automatically fetched
+ * connections.forEach(conn => {
+ *   console.log(`Connection ${conn.id} is ready with its concepts`);
+ * });
+ *
+ * // Handle empty array case
+ * const noConnections = await GetAllConnectionsOfCompositionBulk([]);
+ * console.log(noConnections); // Returns empty array
+ * ```
+ *
+ * @remarks
+ * This function performs several important operations:
+ * 1. Early return if composition_ids array is empty
+ * 2. Retrieves old connections from in-memory storage for comparison
+ * 3. Fetches fresh connections from server via bulk endpoint
+ * 4. Detects and handles deleted connections via CheckForConnectionDeletion
+ * 5. Automatically resolves all concepts referenced by the connections
+ *
+ * The automatic concept resolution ensures that all concepts referenced in the connections
+ * are available locally, preventing the need for additional lookups.
+ *
+ * @see GetAllConnectionsOfCompositionOnline for the underlying bulk server fetch
+ * @see FindConnectionsOfCompositionsBulkInMemory for in-memory lookup
+ * @see FindConceptsFromConnections for automatic concept resolution
+ * @see CheckForConnectionDeletion for deletion detection logic
+ */
 export declare function GetAllConnectionsOfCompositionBulk(composition_ids?: number[]): Promise<Connection[]>;
+/**
+ * Fetches connections for multiple compositions directly from the remote server in a single request.
+ * This function bypasses local caching and retrieves fresh data from the bulk endpoint,
+ * which is optimized for handling multiple composition IDs efficiently.
+ *
+ * All retrieved connections are automatically added to the local ConnectionData store
+ * for subsequent use throughout the application.
+ *
+ * @param composition_ids - Array of composition IDs to fetch connections for. Defaults to empty array.
+ *
+ * @returns A promise that resolves to an array of Connection objects retrieved from the server
+ *
+ * @example
+ * ```typescript
+ * // Fetch connections for multiple compositions from server
+ * const connections = await GetAllConnectionsOfCompositionOnline([100, 200, 300]);
+ *
+ * // Process the bulk results
+ * console.log(`Fetched ${connections.length} connections from server`);
+ * ```
+ *
+ * @remarks
+ * This is the underlying server communication function for bulk composition queries.
+ * It uses JSON serialization for the request body to send the array of composition IDs,
+ * and the server returns all connections for those compositions in a single response.
+ *
+ * The function handles both successful and error responses gracefully, logging appropriate
+ * error messages with the prefix 'Get all connections of composition bulk error message'.
+ *
+ * Each retrieved connection is added to ConnectionData, making it available for local queries.
+ *
+ * @throws Will throw an error if the network request fails or if the server returns an error response
+ *
+ * @see GetAllConnectionsOfCompositionBulk for the recommended high-level function
+ * @see ConnectionData.AddConnection for how connections are stored locally
+ */
 export declare function GetAllConnectionsOfCompositionOnline(composition_ids?: number[]): Promise<Connection[]>;

package/dist/types/Api/GetAllLinkerConnectionsFromTheConcept.d.ts

@@ -1,2 +1,54 @@
+/**
+ * API module for retrieving all linker connections originating from a specific concept.
+ * This module fetches outbound linker connections where the specified concept acts as the source,
+ * enabling navigation and analysis of concept relationships in the forward direction.
+ *
+ * @module Api/GetAllLinkerConnectionsFromTheConcept
+ * @see https://documentation.freeschema.com for more information on the Concept Connection System
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves all linker connections that originate from a specific concept.
+ * This function fetches connections where the specified concept is the source (from-concept),
+ * allowing you to discover all concepts that this concept links to or relates with.
+ *
+ * Linker connections represent directed relationships in the concept graph, and this function
+ * specifically returns outbound connections where the given concept acts as the origin point.
+ * This is essential for graph traversal, relationship discovery, and understanding how a
+ * concept connects to other parts of the knowledge graph.
+ *
+ * @param conceptId - The unique identifier of the concept whose outbound linker connections should be retrieved
+ *
+ * @returns A promise that resolves to an array of Connection objects originating from the specified concept
+ *
+ * @example
+ * ```typescript
+ * // Get all connections from concept 789
+ * const outboundConnections = await GetAllLinkerConnectionsFromTheConcept(789);
+ *
+ * // Discover what this concept links to
+ * outboundConnections.forEach(connection => {
+ *   console.log(`Concept 789 links to concept ${connection.toConceptId}`);
+ * });
+ *
+ * // Use for graph navigation
+ * async function traverseFromConcept(conceptId: number) {
+ *   const connections = await GetAllLinkerConnectionsFromTheConcept(conceptId);
+ *   return connections.map(conn => conn.toConceptId);
+ * }
+ * ```
+ *
+ * @remarks
+ * This function uses a GET request with the concept ID as a query parameter.
+ * Unlike some other API functions, it does not automatically add connections to ConnectionData,
+ * allowing the caller to decide how to handle the returned connections.
+ *
+ * The function returns an empty array if the request fails or if no connections are found.
+ * Errors are logged with the prefix 'Get all linker connection from the concepts error'.
+ *
+ * @throws Will throw an error if the network request fails or if the server returns an error response
+ *
+ * @see GetAllLinkerConnectionsToTheConcept for retrieving inbound connections to a concept
+ * @see Connection for the connection data structure
+ */
 export declare function GetAllLinkerConnectionsFromTheConcept(conceptId: number): Promise<Connection[]>;

package/dist/types/Api/GetAllLinkerConnectionsToTheConcept.d.ts

@@ -1,2 +1,63 @@
+/**
+ * API module for retrieving all linker connections pointing to a specific concept.
+ * This module fetches inbound linker connections where the specified concept acts as the target,
+ * enabling discovery of what other concepts reference or link to the given concept.
+ *
+ * @module Api/GetAllLinkerConnectionsToTheConcept
+ * @see https://documentation.freeschema.com for more information on the Concept Connection System
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves all linker connections that point to a specific concept.
+ * This function fetches connections where the specified concept is the target (to-concept),
+ * allowing you to discover all concepts that link to or reference this concept.
+ *
+ * Linker connections represent directed relationships in the concept graph, and this function
+ * specifically returns inbound connections where the given concept acts as the destination.
+ * This is essential for reverse graph traversal, finding references, and understanding what
+ * other concepts depend on or relate to the specified concept.
+ *
+ * @param conceptId - The unique identifier of the concept whose inbound linker connections should be retrieved
+ *
+ * @returns A promise that resolves to an array of Connection objects pointing to the specified concept
+ *
+ * @example
+ * ```typescript
+ * // Get all connections to concept 789
+ * const inboundConnections = await GetAllLinkerConnectionsToTheConcept(789);
+ *
+ * // Discover what links to this concept
+ * inboundConnections.forEach(connection => {
+ *   console.log(`Concept ${connection.fromConceptId} links to concept 789`);
+ * });
+ *
+ * // Find all references to a concept
+ * async function findReferences(conceptId: number) {
+ *   const connections = await GetAllLinkerConnectionsToTheConcept(conceptId);
+ *   return connections.map(conn => conn.fromConceptId);
+ * }
+ *
+ * // Check if a concept is referenced
+ * async function isConceptReferenced(conceptId: number): Promise<boolean> {
+ *   const connections = await GetAllLinkerConnectionsToTheConcept(conceptId);
+ *   return connections.length > 0;
+ * }
+ * ```
+ *
+ * @remarks
+ * This function uses a GET request with the concept ID as a query parameter.
+ * Unlike some other API functions, it does not automatically add connections to ConnectionData,
+ * allowing the caller to decide how to handle the returned connections.
+ *
+ * The function returns an empty array if the request fails or if no connections are found.
+ * Errors are logged with the prefix 'Get all linker connection To the concepts error'.
+ *
+ * This function is the complement to GetAllLinkerConnectionsFromTheConcept - together they
+ * provide complete bidirectional navigation of the concept graph.
+ *
+ * @throws Will throw an error if the network request fails or if the server returns an error response
+ *
+ * @see GetAllLinkerConnectionsFromTheConcept for retrieving outbound connections from a concept
+ * @see Connection for the connection data structure
+ */
 export declare function GetAllLinkerConnectionsToTheConcept(conceptId: number): Promise<Connection[]>;

package/dist/types/Api/GetAllPrefetchConnections.d.ts

@@ -1 +1,52 @@
+/**
+ * API module for prefetching connections to optimize application performance.
+ * This module retrieves frequently accessed or anticipated connections in advance,
+ * storing them for faster access and improved user experience.
+ *
+ * @module Api/GetAllPrefetchConnections
+ * @see https://documentation.freeschema.com for more information on the Concept Connection System
+ */
+/**
+ * Prefetches connections for a user to optimize application performance and reduce load times.
+ * This function retrieves connections that are likely to be needed soon, such as connections
+ * for concepts on the current or next page, and stores them in persistent storage for fast access.
+ *
+ * Prefetching is a performance optimization technique that loads data before it's explicitly requested,
+ * reducing perceived latency and improving user experience. This function is particularly useful
+ * for pagination scenarios or predictive loading based on user behavior.
+ *
+ * @param userId - The unique identifier of the user whose connections should be prefetched
+ * @param inpage - The page number or index indicating which set of connections to prefetch
+ *
+ * @returns A promise that resolves when all prefetch connections have been fetched and stored
+ *
+ * @example
+ * ```typescript
+ * // Prefetch connections for user 123 on page 1
+ * await GetAllPrefetchConnections(123, 1);
+ *
+ * // Prefetch connections for the next page in advance
+ * const currentPage = 2;
+ * await GetAllPrefetchConnections(userId, currentPage + 1);
+ *
+ * // Connections are now in storage and will load instantly when needed
+ * const connections = await ConnectionData.GetConnectionsFromStorage();
+ * ```
+ *
+ * @remarks
+ * This function includes performance timing to measure the prefetch operation duration,
+ * logging the elapsed time in milliseconds to help monitor and optimize performance.
+ *
+ * Unlike other connection fetch functions, this uses AddConnectionToStorage rather than
+ * AddConnection, which may indicate a different storage mechanism optimized for prefetching.
+ *
+ * The function uses URLSearchParams to encode the user_id parameter in the request body.
+ * Errors are logged with the prefix 'Get all prefetch connections error message' and are
+ * re-thrown to allow calling code to handle failures.
+ *
+ * @throws Will throw an error if the network request fails or if the server returns an error response
+ *
+ * @see ConnectionData.AddConnectionToStorage for the specialized storage mechanism
+ * @see GetRequestHeader for request header configuration
+ */
 export declare function GetAllPrefetchConnections(userId: number, inpage: number): Promise<void>;

package/dist/types/Api/GetCharacterDataByCharacter.d.ts

@@ -1,2 +1,33 @@
+/**
+ * Module for retrieving character data by character value from the CCS API.
+ * This module provides functionality to fetch TheCharacter objects using their unique character values.
+ *
+ * @module Api/GetCharacterDataByCharacter
+ * @see https://documentation.freeschema.com for API reference
+ */
 import { TheCharacter } from "../DataStructures/TheCharacter";
+/**
+ * Retrieves a character object from the database by its character value.
+ * This function makes an API call to fetch character data and returns the corresponding TheCharacter object.
+ *
+ * @param characterValue - The unique string identifier for the character to retrieve
+ * @returns A promise that resolves to the TheCharacter object containing the character data
+ *
+ * @throws {Error} Throws an error if the HTTP request fails or if the response status is not OK
+ *
+ * @example
+ * ```typescript
+ * // Fetch a character by its character value
+ * const character = await GetCharacterByCharacter("a");
+ * console.log(character.id, character.characterValue);
+ * ```
+ *
+ * @remarks
+ * This function uses form-urlencoded content type for the POST request.
+ * The character_value is sent as a form parameter to the API endpoint.
+ * Any HTTP errors are logged and handled through the HandleHttpError service.
+ *
+ * @see TheCharacter for the structure of the returned object
+ * @see BaseUrl.GetCharacterByCharacterUrl for the API endpoint
+ */
 export declare function GetCharacterByCharacter(characterValue: string): Promise<TheCharacter>;

package/dist/types/Api/GetCompositionConnectionsBetweenTwoConcepts.d.ts

@@ -1,2 +1,41 @@
+/**
+ * Module for retrieving composition connections between two concepts in the CCS system.
+ * Composition connections represent hierarchical or structural relationships where one concept is composed of or contains another.
+ *
+ * @module Api/GetCompositionConnectionsBetweenTwoConcepts
+ * @see https://documentation.freeschema.com for composition connection details
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves all composition connections that exist between two specific concepts.
+ * Composition connections define structural relationships where concepts are part of or contained within other concepts.
+ *
+ * @param ofConceptId - The ID of the source concept (the concept that has the composition relationship)
+ * @param toConcept - The ID of the target concept (the concept being composed or contained)
+ * @param mainKey - The main key identifier used for additional filtering or context
+ * @returns A promise that resolves to an array of Connection objects representing the composition relationships
+ *
+ * @example
+ * ```typescript
+ * // Get composition connections from concept 100 to concept 200
+ * const connections = await GetCompositionConnectionsBetweenTwoConcepts(100, 200, 1);
+ * connections.forEach(conn => {
+ *   console.log(`Connection ID: ${conn.id}`);
+ * });
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Sends FormData with concept IDs and main key to the API
+ * - Automatically caches all retrieved connections in ConnectionData
+ * - Returns an empty array if the request fails rather than throwing
+ * - Logs errors but doesn't propagate them unless an exception occurs
+ *
+ * The connections are bidirectional composition relationships that help build
+ * hierarchical concept structures in the CCS system.
+ *
+ * @see Connection for the structure of connection objects
+ * @see ConnectionData.AddConnection for how connections are cached
+ * @see BaseUrl.GetCompositionConnectionBetweenTwoConceptsUrl for the API endpoint
+ */
 export declare function GetCompositionConnectionsBetweenTwoConcepts(ofConceptId: number, toConcept: number, mainKey: number): Promise<Connection[]>;

package/dist/types/Api/GetConcept.d.ts

@@ -1,2 +1,49 @@
+/**
+ * Module for retrieving individual concepts from the CCS system.
+ * Provides caching and optimized retrieval of Concept objects by their unique identifiers.
+ *
+ * @module Api/GetConcept
+ * @see https://documentation.freeschema.com for concept details
+ */
 import { Concept } from "./../DataStructures/Concept";
+/**
+ * Retrieves a concept by its unique ID with built-in caching and request deduplication.
+ * This is the primary function for fetching individual concepts in the CCS system.
+ *
+ * @param id - The unique numeric identifier of the concept to retrieve
+ * @returns A promise that resolves to the Concept object, or a default concept if not found
+ *
+ * @example
+ * ```typescript
+ * // Fetch a concept by ID
+ * const concept = await GetConcept(123);
+ * if (concept.id !== 0) {
+ *   console.log(`Found concept: ${concept.characterValue}`);
+ * }
+ * ```
+ *
+ * @remarks
+ * This function implements a sophisticated multi-layer retrieval strategy:
+ *
+ * 1. Request Deduplication: If a request for the same ID is already in-flight,
+ *    returns the existing promise instead of making a duplicate API call.
+ *
+ * 2. Local Cache Check: First checks ConceptsData for a cached concept or NPC marker.
+ *
+ * 3. API Fallback: If not found locally, fetches from the API endpoint.
+ *
+ * 4. NPC Tracking: If the API returns a concept with id = 0, marks it as an NPC
+ *    (Non-Persistent Concept) to avoid repeated failed lookups.
+ *
+ * 5. Cache Cleanup: The in-flight request cache is automatically cleaned up
+ *    after each request completes (success or failure).
+ *
+ * The function always returns a Concept object - either the found concept,
+ * or a default concept with id = 0 if not found.
+ *
+ * @see Concept for the structure of concept objects
+ * @see ConceptsData.GetConcept for local cache retrieval
+ * @see CreateDefaultConcept for default concept creation
+ * @see GetConceptBulk for retrieving multiple concepts efficiently
+ */
 export declare function GetConcept(id: number): Promise<Concept>;

package/dist/types/Api/GetConceptBulk.d.ts

@@ -1,3 +1,71 @@
+/**
+ * Module for bulk retrieval of concepts from the CCS system.
+ * Provides optimized batch fetching of multiple concepts in a single API request.
+ *
+ * @module Api/GetConceptBulk
+ * @see https://documentation.freeschema.com for bulk operation details
+ */
 import { Concept } from "./../DataStructures/Concept";
+/**
+ * Retrieves multiple concepts in a single optimized API request.
+ * This function checks the local cache first and only fetches uncached concepts from the API.
+ *
+ * @param conceptIds - Array of concept IDs to retrieve
+ * @returns A promise that resolves to an array of Concept objects
+ *
+ * @example
+ * ```typescript
+ * // Fetch multiple concepts at once
+ * const concepts = await GetConceptBulk([1, 2, 3, 4, 5]);
+ * concepts.forEach(concept => {
+ *   console.log(`Concept ${concept.id}: ${concept.characterValue}`);
+ * });
+ * ```
+ *
+ * @remarks
+ * Performance optimization strategy:
+ * 1. Checks ConceptsData cache for each requested concept ID
+ * 2. Immediately returns cached concepts without API call
+ * 3. Batches all uncached IDs into a single bulk API request
+ * 4. Caches all newly fetched concepts for future use
+ * 5. Returns empty array if all concepts are cached or if the API request fails
+ *
+ * This is significantly more efficient than calling GetConcept() multiple times
+ * when you need to retrieve multiple concepts, as it reduces network overhead.
+ *
+ * @see Concept for the structure of concept objects
+ * @see ConceptsData.AddConcept for caching mechanism
+ * @see GetConcept for single concept retrieval
+ * @see BulkConceptGetterApi for alternative bulk fetching without cache checking
+ */
 export declare function GetConceptBulk(conceptIds: number[]): Promise<Concept[]>;
+/**
+ * Alternative bulk concept fetcher that directly queries the API without pre-checking the cache.
+ * This function is useful when you want to force-fetch concepts from the API regardless of cache state.
+ *
+ * @param bulkConceptFetch - Array of concept IDs to fetch from the API
+ * @returns A promise that resolves to an array of Concept objects
+ *
+ * @example
+ * ```typescript
+ * // Force fetch concepts from API bypassing cache check
+ * const freshConcepts = await BulkConceptGetterApi([10, 20, 30]);
+ * console.log(`Fetched ${freshConcepts.length} concepts`);
+ * ```
+ *
+ * @remarks
+ * Differences from GetConceptBulk:
+ * - Does NOT check ConceptsData cache before making the API request
+ * - Always makes an API call if IDs are provided (except when array is empty)
+ * - Still caches the fetched concepts in ConceptsData after retrieval
+ * - Uses JSON content type for the request
+ *
+ * Use this function when:
+ * - You need the latest data from the server
+ * - You want to refresh cached concepts
+ * - Cache invalidation is needed for specific concepts
+ *
+ * @see GetConceptBulk for cache-aware bulk retrieval
+ * @see ConceptsData.AddConcept for caching mechanism
+ */
 export declare function BulkConceptGetterApi(bulkConceptFetch: number[]): Promise<Concept[]>;

package/dist/types/Api/GetConceptByCharacterAndType.d.ts

@@ -1,3 +1,78 @@
+/**
+ * Module for retrieving concepts by their character value and type combination.
+ * Provides specialized lookup for concepts using both character identifier and type classification.
+ *
+ * @module Api/GetConceptByCharacterAndType
+ * @see https://documentation.freeschema.com for character and type system details
+ */
 import { Concept } from "./../DataStructures/Concept";
+/**
+ * Retrieves a concept by its character value and type ID combination.
+ * This provides a more specific lookup than character value alone, useful when the same
+ * character can represent different concepts of different types.
+ *
+ * @param characterValue - The character string identifier of the concept
+ * @param typeId - The type ID that classifies the concept
+ * @returns A promise that resolves to the Concept object matching both criteria
+ *
+ * @example
+ * ```typescript
+ * // Get a specific concept by character and type
+ * const concept = await GetConceptByCharacterAndType("user", 5);
+ * if (concept && concept.id !== 0) {
+ *   console.log(`Found concept: ${concept.id}`);
+ * }
+ * ```
+ *
+ * @remarks
+ * This function implements a multi-layer lookup strategy:
+ *
+ * 1. Request Deduplication: Caches in-flight requests using a composite key
+ *    (characterValue + typeId) to prevent duplicate API calls.
+ *
+ * 2. Local Cache Check: First attempts to retrieve from ConceptsData using
+ *    GetConceptByCharacterAndTypeLocal() method.
+ *
+ * 3. API Fallback: If not found locally, makes an API request with both
+ *    character_value and type_id as JSON parameters.
+ *
+ * 4. Automatic Caching: Successfully retrieved concepts are cached in
+ *    ConceptsData for future lookups.
+ *
+ * This is particularly useful in systems where the same character string
+ * can represent different semantic concepts based on context or type.
+ *
+ * @see Concept for the structure of concept objects
+ * @see ConceptsData.GetConceptByCharacterAndTypeLocal for local cache lookup
+ * @see GetConceptByCharacterValue for type-agnostic character lookup
+ * @see GetConceptByTypeBulk for bulk retrieval by type
+ */
 export declare function GetConceptByCharacterAndType(characterValue: string, typeId: number): Promise<Concept>;
+/**
+ * Retrieves multiple concepts matching any of the specified connection types in bulk.
+ * This function first fetches concept IDs by type, then retrieves the full concept data.
+ *
+ * @param connectionTypes - Array of connection type strings to match
+ * @returns A promise that resolves to an array of Concept objects matching the specified types
+ *
+ * @example
+ * ```typescript
+ * // Get all concepts associated with specific connection types
+ * const concepts = await GetConceptByTypeBulk(["friendship", "colleague", "family"]);
+ * console.log(`Found ${concepts.length} concepts`);
+ * ```
+ *
+ * @remarks
+ * This function performs a two-stage retrieval:
+ * 1. First API call: Sends connection types to get matching concept IDs
+ * 2. Second stage: Uses GetConceptBulk to efficiently fetch all concept data
+ *
+ * The connection types are sent as a JSON array to the API endpoint.
+ * This is useful for finding all concepts that participate in connections
+ * of specific types, enabling type-based concept discovery and filtering.
+ *
+ * @see GetConceptBulk for the bulk concept retrieval mechanism
+ * @see GetConceptByCharacterAndType for single concept lookup by character and type
+ * @see BaseUrl.GetConceptConnectionByType for the API endpoint
+ */
 export declare function GetConceptByTypeBulk(connectionTypes: string[]): Promise<Concept[]>;