mftsccs-node 0.0.57 → 0.0.58

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

@@ -1,2 +1,107 @@
+/**
+ * @fileoverview Composition patching service for the CCS-JS system.
+ * This module provides functionality to retrieve connections between concepts within a composition,
+ * which is essential for understanding and modifying the relationship structure in the concept graph.
+ * @module Services/PatchComposition
+ */
 import { Concept } from "../DataStructures/Concept";
+/**
+ * Retrieves the connection between two concepts within a specific composition context.
+ *
+ * This function is used to find the relationship connection between a source concept (ofConcept)
+ * and a target concept (toConcept) within the scope of a main composition. It's particularly
+ * useful when you need to verify, modify, or delete a specific connection in a composition,
+ * or when analyzing the relationship structure between concepts.
+ *
+ * The function acts as a service layer wrapper around the API call, providing a cleaner
+ * interface for retrieving composition-specific connections. It ensures that only connections
+ * belonging to the specified composition are considered.
+ *
+ * @param ofConcept - The source concept from which the connection originates
+ * @param MainConcept - The main composition concept that contains both concepts and their connection
+ * @param toConcept - The target concept to which the connection points
+ * @returns The connection object between the two concepts within the composition context,
+ *          or undefined if no such connection exists
+ *
+ * @example
+ * ```typescript
+ * // Find connection between two concepts in a composition
+ * import PatchComposition from './PatchComposition';
+ * import { Concept } from '../DataStructures/Concept';
+ *
+ * const userConcept: Concept = { id: 123, type: "user", ... };
+ * const profileConcept: Concept = { id: 456, type: "profile", ... };
+ * const compositionConcept: Concept = { id: 789, type: "composition", ... };
+ *
+ * const connection = PatchComposition(userConcept, compositionConcept, profileConcept);
+ * // Returns the connection object linking user to profile within the composition
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in connection validation
+ * const userConcept = await GetTheConcept(123);
+ * const addressConcept = await GetTheConcept(456);
+ * const mainComposition = await GetTheConcept(789);
+ *
+ * const existingConnection = PatchComposition(
+ *   userConcept,
+ *   mainComposition,
+ *   addressConcept
+ * );
+ *
+ * if (existingConnection) {
+ *   console.log("Connection already exists");
+ * } else {
+ *   console.log("No connection found, can create new one");
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check connection before deletion
+ * const fromConcept = await GetTheConcept(111);
+ * const toConcept = await GetTheConcept(222);
+ * const composition = await GetTheConcept(333);
+ *
+ * const connection = PatchComposition(fromConcept, composition, toConcept);
+ * if (connection) {
+ *   await DeleteConnectionById(connection.id);
+ * }
+ * ```
+ *
+ * @remarks
+ * Important considerations:
+ *
+ * **Function Purpose:**
+ * - Despite the name "PatchComposition", this function primarily retrieves connection data
+ * - It does not modify or patch the composition itself
+ * - It serves as a query function to find specific connections
+ *
+ * **Composition Context:**
+ * - The MainConcept parameter ensures the connection is searched within a specific composition
+ * - This prevents retrieving connections from other compositions that might link the same concepts
+ * - Provides composition-scoped connection lookup
+ *
+ * **Return Value:**
+ * - The function calls an API method but doesn't explicitly handle the return
+ * - The connection variable is assigned but not returned in the current implementation
+ * - This may be an incomplete implementation that needs a return statement
+ *
+ * **Use Cases:**
+ * - Verifying if a connection exists before creating a new one
+ * - Finding the connection ID for deletion operations
+ * - Validating composition structure
+ * - Analyzing relationship graphs within compositions
+ *
+ * **Potential Issues:**
+ * - Missing return statement means the function currently returns undefined
+ * - The retrieved connection is stored in a local variable but not returned
+ * - May need to be updated to return the connection value
+ *
+ * @see {@link GetCompositionConnectionsBetweenTwoConcepts} for the underlying API implementation
+ * @see {@link Concept} for the concept data structure
+ * @see {@link Connection} for the connection data structure
+ * @see {@link UpdateComposition} for composition update operations
+ */
 export default function PatchComposition(ofConcept: Concept, MainConcept: Concept, toConcept: Concept): void;

package/dist/types/Services/Search/DataIdFormat.d.ts

@@ -1,32 +1,104 @@
+/**
+ * @module DataIdFormat
+ * @description Provides formatting functions for DATA-ID format output, which includes both data and ID information for each concept
+ */
 import { Connection } from "../../app";
 /**
-* ## Format DATA-ID ##
-* this function takes in connections and creates a single level objects so that all the data are added to its object/ array.
-* This is then passed on further for stiching.
-* @param connections
-* @param compositionData
-* @param reverse
-* @returns
-*/
+ * Converts connections to single-level objects in DATA-ID format, preparing data for stitching.
+ * Creates objects with both ID and data properties for each concept.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of Connection objects to process
+ * @param {any[]} compositionData - Array/dictionary that stores composition data indexed by concept ID
+ * @param {number[]} [reverse=[]] - Array of connection IDs for reverse direction processing
+ * @returns {Promise<any[]>} A promise that resolves to the updated compositionData with ID and data structure
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = [];
+ * const reverse = [102];
+ * const result = await FormatFunctionDataForData(connections, compositionData, reverse);
+ * // result = { 123: { user: { name: { id: 1, data: { type: "John" } } } } }
+ * ```
+ *
+ * @remarks
+ * Format: DATA-ID - First pass formatting with ID information
+ * This function:
+ * - Processes connections in order without sorting
+ * - Creates nested data structure with explicit ID and data fields
+ * - Handles numeric linkers as arrays
+ * - Uses linker character or concept type (with prefix removed) as key
+ * - Skips "_s_" type linkers
+ * - Supports reverse connections with "_reverse" suffix
+ */
 export declare function FormatFunctionDataForData(connections: Connection[], compositionData: any[], reverse?: number[]): Promise<any[]>;
 /**
-* ############ Format is data-id and is used for list. ############
-* This is helpful in building a format that has multiple mainCompositions i.e. in the context of the list
-* The list format is helpful because you do not have to go over each individual query.
-* @param connections the type connections that need (external connections) to be passed
-* @param compositionData  this is a dictionary type of format that has all the build compositions {id: { actual data}}
-* @param mainComposition this is list of  ids of the main composition that builds the tree
-* @param reverse this is the list of connections ids that needs to go to the reverse direction (to---->from)
-* @returns
-*/
+ * Formats concepts and connections for list views in DATA-ID format, stitching together multiple compositions.
+ * Each result includes concept ID, nested data object, and creation timestamp.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of type connections (external connections) to process
+ * @param {any[]} compositionData - Dictionary format with all built compositions indexed by ID
+ * @param {any} newCompositionData - New composition data to be populated (unused parameter)
+ * @param {number[]} mainComposition - Array of main composition IDs that build the tree
+ * @param {number[]} [reverse=[]] - Array of connection IDs for reverse direction (to -> from)
+ * @param {any[]} CountDictionary - Dictionary containing count information for connections
+ * @returns {Promise<any[]>} A promise that resolves to an array of formatted main compositions with DATA-ID structure
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = { 123: { user: "data" } };
+ * const mainIds = [123];
+ * const result = await FormatFromConnectionsAlteredArrayExternal(
+ *   connections,
+ *   compositionData,
+ *   {},
+ *   mainIds,
+ *   [],
+ *   {}
+ * );
+ * // result = [{ id: 123, data: {...}, created_on: timestamp }]
+ * ```
+ *
+ * @remarks
+ * Format: DATA-ID - Used for list views with full ID and data information
+ * This function:
+ * - Processes type connections to link compositions
+ * - Creates objects with id, data, and created_on properties
+ * - Handles both "_s_" (array) and regular (object) linker types
+ * - Supports reverse connections with "_reverse" suffix
+ * - Includes creation timestamp for each linked concept
+ * - Returns array of formatted main compositions
+ */
 export declare function FormatFromConnectionsAlteredArrayExternal(connections: Connection[], compositionData: any[], newCompositionData: any, mainComposition: number[], reverse: number[] | undefined, CountDictionary: any[]): Promise<any[]>;
 /**
- * ## Format DATA-ID ##
- * this function takes in connections and creates a single level objects so that all the data are added to its object/ array.
- * This is then passed on further for stiching.
- * @param connections
- * @param compositionData
- * @param reverse
- * @returns
+ * Converts connections to initial single-level concept objects in DATA-ID format.
+ * This is the first pass that creates the basic concept structure before data nesting.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of Connection objects to process
+ * @param {any[]} compositionData - Array/dictionary that stores composition data indexed by concept ID
+ * @param {number[]} [reverse=[]] - Array of connection IDs for reverse direction processing
+ * @returns {Promise<any[]>} A promise that resolves to the updated compositionData with initial structure
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = [];
+ * const reverse = [];
+ * const result = await FormatFunctionData(connections, compositionData, reverse);
+ * // result = { 123: { user: {} }, 456: { post: {} } }
+ * ```
+ *
+ * @remarks
+ * Format: DATA-ID - Initial pass for concept creation
+ * This function:
+ * - Creates empty concept structures indexed by ID
+ * - Sets up the foundation for subsequent data population
+ * - Handles "_s_" type linkers by storing basic concept info
+ * - Does not add nested data (handled by FormatFunctionDataForData)
+ * - Supports reverse connections
  */
 export declare function FormatFunctionData(connections: Connection[], compositionData: any[], reverse?: number[]): Promise<any[]>;

package/dist/types/Services/Search/FormatData.d.ts

@@ -1,26 +1,101 @@
+/**
+ * @module FormatData
+ * @description Provides functions to format connection data into structured composition objects for Normal format output
+ */
 import { Connection } from "../../app";
 /**
+ * Converts connections to single-level objects by processing concepts and their relationships.
+ * This is the initial builder function that creates the foundation for composition arrays/objects.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of Connection objects to process
+ * @param {any} compositionData - Dictionary object that stores composition data indexed by concept ID
+ * @param {number[]} reverse - Array of connection IDs that should be processed in reverse direction
+ * @returns {Promise<any>} A promise that resolves to the updated compositionData dictionary
  *
- * ## Format Normal ##
- * This function takes in the connections and then converts the connections to the single level objects for further processing
- * This function is the builder of the arrays/ objects from the connections.
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = {};
+ * const reverse = [102];
+ * const result = await formatFunction(connections, compositionData, reverse);
+ * // result = { 123: { type: "value" }, 456: { type: "data" } }
+ * ```
+ *
+ * @remarks
+ * Format: Normal - First pass formatting
+ * This function:
+ * - Processes each connection to extract concepts
+ * - Handles both forward (of->to) and reverse (to->of) directions
+ * - Creates initial concept structures without nested data
+ * - Special handling for "_s_" linker types (skipped in output)
  */
 export declare function formatFunction(connections: Connection[], compositionData: any, reverse: number[]): Promise<any>;
 /**
-*
-* ## Format Normal ##
-* This function takes in the connections and then converts the connections to the single level objects for further processing
-* This function is the builder of the arrays/ objects from the connections.
-*/
+ * Converts connections to single-level objects with nested data relationships.
+ * This is the second pass that adds detailed data properties to the composition structure.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of Connection objects to process
+ * @param {any} compositionData - Dictionary object that stores composition data indexed by concept ID
+ * @param {number[]} reverse - Array of connection IDs that should be processed in reverse direction
+ * @returns {Promise<any>} A promise that resolves to the updated compositionData dictionary with nested data
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = { 123: { user: {} } };
+ * const reverse = [];
+ * const result = await formatFunctionForData(connections, compositionData, reverse);
+ * // result = { 123: { user: { name: { type: "John" } } } }
+ * ```
+ *
+ * @remarks
+ * Format: Normal - Second pass formatting with data nesting
+ * This function:
+ * - Sorts connections by ID in descending order
+ * - Adds nested data properties to concepts
+ * - Handles numeric vs string linker types differently
+ * - Numeric linkers create arrays, string linkers create objects
+ * - Uses linker character value as property key or removes prefix if empty
+ * - Skips "_s_" type linkers in the output
+ */
 export declare function formatFunctionForData(connections: Connection[], compositionData: any, reverse: number[]): Promise<any>;
 /**
-* ######### Format is normal ######### used for listing. This only provides type connections.
-* This is helpful in building a format that has multiple mainCompositions i.e. in the context of the list
-* The list format is helpful because you do not have to go over each individual query.
-* @param connections the type connections that need (external connections) to be passed
-* @param compositionData  this is a dictionary type of format that has all the build compositions {id: { actual data}}
-* @param mainComposition this is list of  ids of the main composition that builds the tree
-* @param reverse this is the list of connections ids that needs to go to the reverse direction (to---->from)
-* @returns
-*/
+ * Formats concepts and connections for list views in Normal format, stitching together multiple compositions.
+ * This function handles type connections and builds a tree structure from multiple main compositions.
+ *
+ * @async
+ * @param {Connection[]} [connections=[]] - Array of type connections (external connections) to process
+ * @param {any[]} [compositionData=[]] - Dictionary format with all built compositions indexed by ID
+ * @param {number[]} [mainComposition=[]] - Array of main composition IDs that build the tree
+ * @param {any} newCompositionData - New composition data to be populated (unused parameter)
+ * @param {number[]} [reverse=[]] - Array of connection IDs for reverse direction (to -> from)
+ * @returns {Promise<any[]>} A promise that resolves to an array of formatted main composition objects
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = { 123: { user: "data" }, 456: { post: "info" } };
+ * const mainIds = [123, 456];
+ * const result = await FormatConceptsAndConnectionsNormalList(
+ *   connections,
+ *   compositionData,
+ *   mainIds,
+ *   {},
+ *   []
+ * );
+ * // result = [{ id: 123, user: "data" }, { id: 456, post: "info" }]
+ * ```
+ *
+ * @remarks
+ * Format: Normal - Used for listing multiple compositions
+ * This function:
+ * - Processes type connections to link compositions together
+ * - Sorts connections by ID in descending order
+ * - Handles both "_s_" (array) and regular (object) linker types
+ * - Supports reverse connections with "_reverse" suffix
+ * - Returns an array of main compositions with their linked data
+ * - Useful for list views where multiple compositions need to be queried efficiently
+ */
 export declare function FormatConceptsAndConnectionsNormalList(connections: Connection[] | undefined, compositionData: any[] | undefined, mainComposition: number[] | undefined, newCompositionData: any, reverse?: number[]): Promise<any[]>;

package/dist/types/Services/Search/JustIdFormat.d.ts

@@ -1,23 +1,98 @@
+/**
+ * @module JustIdFormat
+ * @description Provides formatting functions for JustId format output, which includes simplified ID-based data structures
+ */
 import { Connection } from "../../app";
 /**
-* ## Format Just-Id ##
-* this function takes in connections and creates a single level objects so that all the data are added to its object/ array.
-* This is then passed on further for stiching.
-* @param connections
-* @param compositionData
-* @param reverse
-* @returns
-*/
+ * Converts connections to single-level objects in JustId format, preparing simplified data for stitching.
+ * Creates lightweight objects with ID and essential data properties.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of Connection objects to process
+ * @param {any[]} compositionData - Array/dictionary that stores composition data indexed by concept ID
+ * @param {number[]} [reverse=[]] - Array of connection IDs for reverse direction processing
+ * @returns {Promise<any[]>} A promise that resolves to the updated compositionData with JustId structure
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = [];
+ * const reverse = [];
+ * const result = await FormatFunctionDataForDataJustId(connections, compositionData, reverse);
+ * // result = { 123: { user: { name: { id: 1, data: "John", created_on: timestamp } } } }
+ * ```
+ *
+ * @remarks
+ * Format: JustId - Lightweight formatting with minimal data
+ * This function:
+ * - Creates simplified data structure with ID, data value, and timestamp
+ * - Handles numeric linkers as arrays
+ * - Uses linker character or concept type (with prefix removed) as key
+ * - Skips "_s_" type linkers
+ * - Supports reverse connections with "_reverse" suffix
+ * - Optimized for list views and reduced data transfer
+ */
 export declare function FormatFunctionDataForDataJustId(connections: Connection[], compositionData: any[], reverse?: number[]): Promise<any[]>;
 /**
- * ############ Format is Just Id and is used for list. ############
- * This is helpful in building a format that has multiple mainCompositions i.e. in the context of the list
- * The list format is helpful because you do not have to go over each individual query.
- * @param connections the type connections that need (external connections) to be passed
- * @param compositionData  this is a dictionary type of format that has all the build compositions {id: { actual data}}
- * @param mainComposition this is list of  ids of the main composition that builds the tree
- * @param reverse this is the list of connections ids that needs to go to the reverse direction (to---->from)
- * @returns
+ * Formats concepts and connections for list views in JustId format, stitching together multiple compositions.
+ * Creates lightweight list view with ID, data, and timestamp for each concept.
+ *
+ * @async
+ * @param {Connection[]} connections - Array of type connections (external connections) to process
+ * @param {any[]} compositionData - Dictionary format with all built compositions indexed by ID
+ * @param {number[]} mainComposition - Array of main composition IDs that build the tree
+ * @param {number[]} [reverse=[]] - Array of connection IDs for reverse direction (to -> from)
+ * @param {any[]} CountDictionary - Dictionary containing count information for connections by concept ID
+ * @returns {Promise<any[]>} A promise that resolves to an array of formatted main compositions with JustId structure
+ *
+ * @example
+ * ```typescript
+ * const connections: Connection[] = [...];
+ * const compositionData = { 123: { user: "data" } };
+ * const mainIds = [123];
+ * const countDict = { 123: { count: 5, connectionType: "follows" } };
+ * const result = await FormatFromConnectionsAlteredArrayExternalJustId(
+ *   connections,
+ *   compositionData,
+ *   mainIds,
+ *   [],
+ *   countDict
+ * );
+ * // result = [{ id: 123, user: { id: 1, data: "value", created_on: timestamp }, follows_count: 5 }]
+ * ```
+ *
+ * @remarks
+ * Format: JustId - Used for list views with lightweight ID-based structure
+ * This function:
+ * - Processes type connections to link compositions
+ * - Creates objects with id, data, and created_on properties
+ * - Handles both "_s_" (array) and regular (object) linker types
+ * - Supports reverse connections with "_reverse" suffix
+ * - Adds count information from CountDictionary (e.g., "follows_count")
+ * - Optimized for performance with minimal data payload
+ * - Useful for paginated lists and mobile applications
  */
 export declare function FormatFromConnectionsAlteredArrayExternalJustId(connections: Connection[], compositionData: any[], mainComposition: number[], reverse: number[] | undefined, CountDictionary: any[]): Promise<any[]>;
+/**
+ * Adds count information to the concept data based on the CountDictionary.
+ * Appends a "_count" suffix to the connection type name.
+ *
+ * @param {number} ofTheConceptId - The ID of the concept to add count information for
+ * @param {any} CountDictionary - Dictionary containing count information indexed by concept ID
+ * @param {any} newData - The data object to add count information to
+ *
+ * @example
+ * ```typescript
+ * const conceptId = 123;
+ * const countDict = { 123: { connectionType: "follows", count: 42 } };
+ * const data = { user: "data" };
+ * AddCount(conceptId, countDict, data);
+ * // data now includes: { user: "data", follows_count: 42 }
+ * ```
+ *
+ * @remarks
+ * This function mutates the newData object by adding a count property
+ * The count property name format is: "{connectionType}_count"
+ * If the concept ID is not in CountDictionary, no changes are made
+ */
 export declare function AddCount(ofTheConceptId: number, CountDictionary: any, newData: any): void;

package/dist/types/Services/Search/SearchLinkInternal.d.ts

@@ -1,2 +1,30 @@
+/**
+ * @module SearchLinkInternal
+ * @description Provides functionality to search for internal links within concepts and return formatted data
+ */
 import { SearchStructure } from "../../app";
+/**
+ * Searches for internal links within concepts based on the provided search query
+ * and returns the formatted internal data view.
+ *
+ * @async
+ * @param {SearchStructure} searchQuery - The search query structure containing search criteria
+ * @param {string} [token=""] - Optional authentication token for API requests
+ * @returns {Promise<any[]>} A promise that resolves to an array of formatted concept connections
+ *
+ * @example
+ * ```typescript
+ * const searchQuery: SearchStructure = {
+ *   composition: 123,
+ *   linker: 456
+ * };
+ * const results = await SearchLinkInternal(searchQuery, "auth-token");
+ * console.log(results);
+ * ```
+ *
+ * @remarks
+ * This function performs a two-step process:
+ * 1. Fetches internal concept connections using the SearchInternalApi
+ * 2. Formats the connections into a readable view using ViewInternalData
+ */
 export declare function SearchLinkInternal(searchQuery: SearchStructure, token?: string): Promise<any[]>;

package/dist/types/Services/Search/SearchLinkMultiple.d.ts

@@ -1,3 +1,61 @@
+/**
+ * @module SearchLinkMultiple
+ * @description Provides functionality to search for multiple links across compositions and format the results
+ */
 import { SearchQuery } from "../../DataStructures/SearchQuery";
+/**
+ * Searches for multiple links across compositions based on an array of search queries.
+ * Returns formatted data with all linked concepts and their relationships.
+ *
+ * @async
+ * @param {SearchQuery[]} searchQuery - Array of search query objects containing composition and link criteria
+ * @param {string} [token=""] - Optional authentication token for API requests
+ * @returns {Promise<any>} A promise that resolves to formatted composition data with all linked concepts
+ *
+ * @example
+ * ```typescript
+ * const queries: SearchQuery[] = [
+ *   { composition: 123, linker: 456, reverse: false },
+ *   { composition: 789, linker: 456, reverse: true }
+ * ];
+ * const result = await SearchLinkMultipleAll(queries, "auth-token");
+ * console.log(result);
+ * ```
+ *
+ * @remarks
+ * This function:
+ * 1. Fetches multiple linked compositions from the API
+ * 2. Retrieves all related concepts and connections
+ * 3. Formats the data structure with proper linker relationships
+ * 4. Handles both forward and reverse link directions
+ */
 export declare function SearchLinkMultipleAll(searchQuery: SearchQuery[], token?: string): Promise<any>;
+/**
+ * Formats composition data from connection linkers, organizing concepts into a hierarchical structure.
+ * Handles both forward and reverse relationships between concepts.
+ *
+ * @async
+ * @param {number[]} linkers - Array of connection IDs that link concepts together
+ * @param {any[]} compositionData - Dictionary of composition data indexed by concept ID
+ * @param {number} mainComposition - The ID of the main composition to return
+ * @param {number[]} [reverse=[]] - Array of connection IDs that should be treated as reverse connections
+ * @returns {Promise<any>} A promise that resolves to the formatted main composition data with all linked concepts
+ *
+ * @example
+ * ```typescript
+ * const linkers = [101, 102, 103];
+ * const compositionData = { 123: { type: "data" }, 456: { type: "info" } };
+ * const mainId = 123;
+ * const reverseConnections = [102];
+ * const result = await FormatFromConnections(linkers, compositionData, mainId, reverseConnections);
+ * ```
+ *
+ * @remarks
+ * This function:
+ * - Fetches all connections from the provided linker IDs
+ * - Processes each connection to build relationships
+ * - Handles reverse connections (to -> from instead of from -> to)
+ * - Uses the linker concept's character value as the relationship key
+ * - Appends "_reverse" suffix for reverse relationships
+ */
 export declare function FormatFromConnections(linkers: number[], compositionData: any[], mainComposition: number, reverse?: number[]): Promise<any>;