mftsccs-node 0.0.57 → 0.0.59

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

@@ -1,5 +1,184 @@
+/**
+ * Concept creation service module.
+ * Provides functions for creating concepts in different modes: normal, temporary, and immediate.
+ *
+ * @module Services/CreateTheConcept
+ * @see https://documentation.freeschema.com/#concept for concept documentation
+ */
 import { Concept } from "../DataStructures/Concept";
 import { InnerActions } from "../DataStructures/Transaction/Transaction";
+/**
+ * Creates a new concept and adds it to the sync queue for backend synchronization.
+ * This is the standard way to create a concept that will be persisted to the backend.
+ * The concept is marked as new (isNew=true) and non-temporary (isTemp=false), and
+ * added to both SyncData (for backend sync) and the transaction actions list.
+ *
+ * @param referent - The character/string value representing the concept's content
+ * @param userId - The ID of the user creating this concept
+ * @param categoryId - The ID of the category concept this concept belongs to
+ * @param categoryUserId - The user ID of the category concept owner
+ * @param typeId - The ID of the type concept that defines this concept's type
+ * @param typeUserId - The user ID of the type concept owner
+ * @param referentId - The ID of the referent concept (what this concept refers to)
+ * @param referentUserId - The user ID of the referent concept owner
+ * @param securityId - The ID of the security concept controlling access
+ * @param securityUserId - The user ID of the security concept owner
+ * @param accessId - The ID of the access concept defining permissions
+ * @param accessUserId - The user ID of the access concept owner
+ * @param sessionInformationId - The ID of the session concept for tracking
+ * @param sessionInformationUserId - The user ID of the session concept owner
+ * @param actions - Transaction object to track all concepts and connections created in this operation
+ * @returns A Promise that resolves to the newly created Concept instance
+ *
+ * @example
+ * ```typescript
+ * // Create a new concept with all required metadata
+ * const concept = await CreateTheConcept(
+ *   'John Doe',           // referent (the actual value)
+ *   1,                    // userId
+ *   10, 1,                // categoryId, categoryUserId
+ *   20, 1,                // typeId, typeUserId (e.g., "Person" type)
+ *   0, 0,                 // referentId, referentUserId (no referent)
+ *   30, 1,                // securityId, securityUserId
+ *   40, 1,                // accessId, accessUserId
+ *   50, 1,                // sessionInformationId, sessionInformationUserId
+ *   { concepts: [], connections: [] }  // transaction actions
+ * );
+ *
+ * console.log(concept.id);  // Auto-generated unique ID
+ * console.log(concept.isNew);  // true - will be synced to backend
+ * console.log(concept.isTemp);  // false - permanent concept
+ * ```
+ *
+ * @remarks
+ * - Automatically generates a unique ID using ReservedIds.getId()
+ * - Sets creation and update timestamps to current time
+ * - Marks concept as new (isNew=true) for backend synchronization
+ * - Marks concept as non-temporary (isTemp=false) for persistence
+ * - Adds concept to SyncData queue for eventual backend sync
+ * - Adds concept to transaction actions for tracking within a transaction context
+ * - Does NOT immediately call the backend API; sync happens separately
+ *
+ * @see CreateTheConceptTemporary for creating temporary concepts
+ * @see CreateTheConceptImmediate for creating concepts with immediate backend sync
+ * @see Concept for the concept data structure
+ * @see SyncData for sync queue management
+ * @see ReservedIds for ID generation
+ */
 export default function CreateTheConcept(referent: string, userId: number, categoryId: number, categoryUserId: number, typeId: number, typeUserId: number, referentId: number, referentUserId: number, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionInformationId: number, sessionInformationUserId: number, actions?: InnerActions): Promise<Concept>;
+/**
+ * Creates a temporary concept that is NOT added to the sync queue or persisted to backend.
+ * Temporary concepts are useful for UI state management, draft operations, or transient data
+ * that doesn't need to be saved. The concept is marked as temporary (isTemp=true) and new (isNew=true).
+ *
+ * @param referent - The character/string value representing the concept's content
+ * @param userId - The ID of the user creating this concept
+ * @param categoryId - The ID of the category concept this concept belongs to
+ * @param categoryUserId - The user ID of the category concept owner
+ * @param typeId - The ID of the type concept that defines this concept's type
+ * @param typeUserId - The user ID of the type concept owner
+ * @param referentId - The ID of the referent concept (what this concept refers to)
+ * @param referentUserId - The user ID of the referent concept owner
+ * @param securityId - The ID of the security concept controlling access
+ * @param securityUserId - The user ID of the security concept owner
+ * @param accessId - The ID of the access concept defining permissions
+ * @param accessUserId - The user ID of the access concept owner
+ * @param sessionInformationId - The ID of the session concept for tracking
+ * @param sessionInformationUserId - The user ID of the session concept owner
+ * @returns A Promise that resolves to the newly created temporary Concept instance
+ *
+ * @example
+ * ```typescript
+ * // Create a temporary concept for UI draft state
+ * const draftConcept = await CreateTheConceptTemporary(
+ *   'Draft Note',         // referent
+ *   1,                    // userId
+ *   10, 1,                // categoryId, categoryUserId
+ *   20, 1,                // typeId, typeUserId
+ *   0, 0,                 // referentId, referentUserId
+ *   30, 1,                // securityId, securityUserId
+ *   40, 1,                // accessId, accessUserId
+ *   50, 1                 // sessionInformationId, sessionInformationUserId
+ * );
+ *
+ * console.log(draftConcept.isTemp);  // true - won't be synced
+ * console.log(draftConcept.isNew);   // true - marked as new
+ * // This concept will NOT be added to SyncData or saved to backend
+ * ```
+ *
+ * @remarks
+ * - Automatically generates a unique ID using ReservedIds.getId()
+ * - Sets creation and update timestamps to current time
+ * - Marks concept as new (isNew=true) but also temporary (isTemp=true)
+ * - Does NOT add concept to SyncData (no backend sync)
+ * - Does NOT add concept to transaction actions
+ * - Useful for draft states, temporary UI elements, or client-only data
+ * - The concept exists only in client memory until explicitly converted/saved
+ *
+ * @see CreateTheConcept for creating persistent concepts
+ * @see CreateTheConceptImmediate for creating concepts with immediate backend sync
+ * @see Concept for the concept data structure
+ */
 export declare function CreateTheConceptTemporary(referent: string, userId: number, categoryId: number, categoryUserId: number, typeId: number, typeUserId: number, referentId: number, referentUserId: number, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionInformationId: number, sessionInformationUserId: number): Promise<Concept>;
+/**
+ * Creates a concept and immediately adds it to ConceptsData for instant availability in queries.
+ * Unlike CreateTheConcept, this function adds the concept to the in-memory ConceptsData store
+ * immediately (not just SyncData), making it instantly searchable. It also sets updateRecursion=true
+ * to enable recursive updates. The concept is marked as not new (isNew=false) and non-temporary.
+ *
+ * @param referent - The character/string value representing the concept's content
+ * @param userId - The ID of the user creating this concept
+ * @param categoryId - The ID of the category concept this concept belongs to
+ * @param categoryUserId - The user ID of the category concept owner
+ * @param typeId - The ID of the type concept that defines this concept's type
+ * @param typeUserId - The user ID of the type concept owner
+ * @param referentId - The ID of the referent concept (what this concept refers to)
+ * @param referentUserId - The user ID of the referent concept owner
+ * @param securityId - The ID of the security concept controlling access
+ * @param securityUserId - The user ID of the security concept owner
+ * @param accessId - The ID of the access concept defining permissions
+ * @param accessUserId - The user ID of the access concept owner
+ * @param sessionInformationId - The ID of the session concept for tracking
+ * @param sessionInformationUserId - The user ID of the session concept owner
+ * @param actions - Transaction object to track all concepts and connections created in this operation
+ * @returns A Promise that resolves to the newly created Concept instance
+ *
+ * @example
+ * ```typescript
+ * // Create a concept that's immediately available for queries
+ * const concept = await CreateTheConceptImmediate(
+ *   'Important User',     // referent
+ *   1,                    // userId
+ *   10, 1,                // categoryId, categoryUserId
+ *   20, 1,                // typeId, typeUserId
+ *   0, 0,                 // referentId, referentUserId
+ *   30, 1,                // securityId, securityUserId
+ *   40, 1,                // accessId, accessUserId
+ *   50, 1,                // sessionInformationId, sessionInformationUserId
+ *   { concepts: [], connections: [] }  // transaction actions
+ * );
+ *
+ * // Concept is immediately available in ConceptsData
+ * const found = ConceptsData.getConceptById(concept.id);
+ * console.log(found !== null);  // true - immediately findable
+ * console.log(concept.isNew);   // false - treated as existing
+ * console.log(concept.updateRecursion);  // true - enables recursive updates
+ * ```
+ *
+ * @remarks
+ * - Automatically generates a unique ID using ReservedIds.getId()
+ * - Sets creation and update timestamps to current time
+ * - Marks concept as NOT new (isNew=false) - treated as existing concept
+ * - Marks concept as non-temporary (isTemp=false)
+ * - Adds concept to ConceptsData immediately for instant query availability
+ * - Sets updateRecursion=true to enable recursive composition updates
+ * - Adds concept to SyncData for backend synchronization
+ * - Adds concept to transaction actions for tracking
+ * - The commented-out line suggests this previously triggered immediate API sync
+ *
+ * @see CreateTheConcept for standard concept creation with delayed sync
+ * @see CreateTheConceptTemporary for creating temporary concepts
+ * @see ConceptsData for the in-memory concept store
+ * @see SyncData for sync queue management
+ */
 export declare function CreateTheConceptImmediate(referent: string, userId: number, categoryId: number, categoryUserId: number, typeId: number, typeUserId: number, referentId: number, referentUserId: number, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionInformationId: number, sessionInformationUserId: number, actions?: InnerActions): Promise<Concept>;

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

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

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

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

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

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

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

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

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

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