mftsccs-node 0.2.6 → 0.2.8

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

@@ -1,2 +1,132 @@
+/**
+ * Composition List Retrieval Service
+ *
+ * This module provides functionality for retrieving multiple compositions of the same
+ * type in paginated batches. It's designed for scenarios where you need to fetch lists
+ * of structured data, such as "all user profiles", "all blog posts", or "all products".
+ *
+ * The module implements bulk prefetching optimizations to minimize API calls and
+ * improve performance when retrieving multiple compositions.
+ *
+ * @module GetCompositionList
+ */
+/**
+ * Retrieves a paginated list of compositions by type name.
+ *
+ * This function fetches multiple compositions that share the same type (e.g., all "blog_post"
+ * compositions) with pagination support. It implements a bulk prefetch optimization strategy:
+ * first fetching all concepts of the given type, then bulk-prefetching all their connections,
+ * and finally reconstructing each composition from cached data.
+ *
+ * This approach is much more efficient than fetching compositions individually, especially
+ * for large lists.
+ *
+ * @param compositionName - The type name of compositions to retrieve (e.g., "blog_post", "user_profile")
+ * @param userId - The user ID who owns the compositions
+ * @param inpage - Number of items per page (default: 10)
+ * @param page - Page number, 1-indexed (default: 1)
+ *
+ * @returns A promise that resolves to an array of composition objects
+ *
+ * @example
+ * ```typescript
+ * // Get the first page of blog posts (10 items)
+ * const blogPosts = await GetCompositionList("blog_post", 999, 10, 1);
+ * console.log(`Retrieved ${blogPosts.length} blog posts`);
+ *
+ * blogPosts.forEach(post => {
+ *   const postData = post["blog_post"];
+ *   console.log("Title:", postData.title);
+ *   console.log("Author:", postData.author);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get the second page of user profiles (20 per page)
+ * const profiles = await GetCompositionList("user_profile", 456, 20, 2);
+ * // Returns profiles 21-40
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Implement pagination for all products
+ * const PAGE_SIZE = 25;
+ * let currentPage = 1;
+ * let products = [];
+ *
+ * do {
+ *   const pageProducts = await GetCompositionList("product", 999, PAGE_SIZE, currentPage);
+ *   products.push(...pageProducts);
+ *   currentPage++;
+ * } while (pageProducts.length === PAGE_SIZE);
+ *
+ * console.log(`Total products: ${products.length}`);
+ * ```
+ *
+ * @remarks
+ * - Uses bulk prefetch optimization for better performance
+ * - First fetches all concepts of the specified type
+ * - Then bulk-prefetches all connections for the page
+ * - Finally reconstructs compositions from cached data
+ * - Pagination is 1-indexed (page 1 is the first page)
+ * - Returns empty array if composition type doesn't exist
+ * - Uses GetCompositionFromMemory for fast reconstruction
+ * - Efficient for large lists due to bulk operations
+ *
+ * @see {@link GetCompositionListWithId} for version that includes metadata
+ * @see {@link GetCompositionFromMemory} for individual composition retrieval
+ * @see {@link GetAllConceptsByType} for fetching concepts by type
+ * @see {@link GetAllConnectionsOfCompositionBulk} for bulk connection prefetch
+ */
 export declare function GetCompositionList(compositionName: string, userId: number, inpage?: number, page?: number): Promise<any>;
+/**
+ * Retrieves a paginated list of compositions with metadata wrappers.
+ *
+ * Similar to GetCompositionList, but each composition in the returned array includes
+ * metadata (ID, creation timestamp) in addition to the composition data. This is useful
+ * when you need to track or reference individual compositions by their IDs.
+ *
+ * The function uses the same bulk prefetch optimization strategy for efficient retrieval.
+ *
+ * @param compositionName - The type name of compositions to retrieve
+ * @param userId - The user ID who owns the compositions
+ * @param inpage - Number of items per page (default: 10)
+ * @param page - Page number, 1-indexed (default: 1)
+ *
+ * @returns A promise that resolves to an array of objects with id, created_at, and data fields
+ *
+ * @example
+ * ```typescript
+ * // Get blog posts with IDs and timestamps
+ * const posts = await GetCompositionListWithId("blog_post", 999, 10, 1);
+ *
+ * posts.forEach(post => {
+ *   console.log("Post ID:", post.id);
+ *   console.log("Created:", post.created_at);
+ *   console.log("Title:", post.data["blog_post"].title);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Build a list of editable items with their IDs
+ * const items = await GetCompositionListWithId("task", 456, 50, 1);
+ *
+ * const editableList = items.map(item => ({
+ *   id: item.id,
+ *   name: item.data["task"].name,
+ *   editUrl: `/edit/${item.id}`
+ * }));
+ * ```
+ *
+ * @remarks
+ * - Each item includes: { id, created_at, data }
+ * - Uses bulk prefetch for performance
+ * - Uses GetCompositionWithIdFromMemory for reconstruction
+ * - Otherwise identical to GetCompositionList
+ *
+ * @see {@link GetCompositionList} for version without metadata
+ * @see {@link GetCompositionWithIdFromMemory} for individual composition with ID
+ */
 export declare function GetCompositionListWithId(compositionName: string, userId: number, inpage?: number, page?: number): Promise<any>;

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

@@ -1,3 +1,87 @@
+/**
+ * @module GetConceptByCharacter
+ * @description Retrieves concepts by their character value in the Concept Connection System (CCS).
+ * This module provides functions to look up concepts based on character strings,
+ * utilizing both local cache (ConceptsData) and remote API calls for comprehensive
+ * concept retrieval with automatic fallback mechanisms.
+ */
 import { Concept } from "../DataStructures/Concept";
+/**
+ * Retrieves a concept by its character value.
+ *
+ * This function performs a two-tier lookup strategy to find concepts:
+ * 1. First checks the local ConceptsData cache for the concept
+ * 2. If not found or has invalid ID, calls the API to fetch from remote storage
+ * 3. After API call, checks the cache again as API updates the cache
+ *
+ * This approach optimizes performance by using cached data when available while
+ * ensuring data consistency through API fallback.
+ *
+ * @param characterValue - The character string to search for (e.g., "the_user", "hello")
+ *
+ * @returns Promise resolving to the found Concept, or a Concept with id=0 if not found
+ *
+ * @remarks
+ * - Uses ConceptsData.GetConceptByCharacter for local cache lookup
+ * - Falls back to GetConceptByCharacterValue API when cache misses
+ * - API call updates the local cache automatically
+ * - Returns null-safe with Concept having id=0 when not found
+ * - Template literal ensures characterValue is treated as string
+ *
+ * @example
+ * ```typescript
+ * // Retrieve a type concept
+ * const userType = await GetConceptByCharacter("the_user");
+ * if (userType.id > 0) {
+ *   console.log("Found user type:", userType);
+ * }
+ *
+ * // Search for a specific name
+ * const name = await GetConceptByCharacter("John Doe");
+ *
+ * // Check for non-existent concept
+ * const missing = await GetConceptByCharacter("nonexistent");
+ * console.log(missing.id); // 0
+ * ```
+ *
+ * @see {@link GetConceptByCharacterUpdated} - Alternative implementation with same behavior
+ * @see {@link ConceptsData.GetConceptByCharacter} - Local cache lookup
+ * @see {@link GetConceptByCharacterValue} - Remote API lookup
+ */
 export default function GetConceptByCharacter(characterValue: string): Promise<Concept>;
+/**
+ * Retrieves a concept by its character value (updated variant).
+ *
+ * This function is functionally identical to GetConceptByCharacter, providing
+ * an alternative export for the same lookup behavior. It follows the same
+ * two-tier strategy of checking local cache first, then falling back to API.
+ *
+ * The "Updated" suffix may indicate a versioning strategy or future enhancement
+ * point, but currently implements the same logic as the default export.
+ *
+ * @param characterValue - The character string to search for (e.g., "the_user", "hello")
+ *
+ * @returns Promise resolving to the found Concept, or a Concept with id=0 if not found
+ *
+ * @remarks
+ * - Identical implementation to GetConceptByCharacter
+ * - Exported as named export rather than default
+ * - May be used for API versioning or compatibility
+ * - Follows same cache-first, API-fallback pattern
+ *
+ * @example
+ * ```typescript
+ * import { GetConceptByCharacterUpdated } from './GetConceptByCharacter';
+ *
+ * // Use updated variant explicitly
+ * const concept = await GetConceptByCharacterUpdated("the_post");
+ * if (concept.id > 0) {
+ *   console.log("Found concept:", concept);
+ * }
+ * ```
+ *
+ * @see {@link GetConceptByCharacter} - Default export with identical behavior
+ * @see {@link ConceptsData.GetConceptByCharacter} - Local cache lookup
+ * @see {@link GetConceptByCharacterValue} - Remote API lookup
+ */
 export declare function GetConceptByCharacterUpdated(characterValue: string): Promise<Concept>;

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

@@ -1,2 +1,74 @@
+/**
+ * Connection Retrieval Service
+ *
+ * This module provides functions for retrieving connection objects from the system.
+ * It implements a caching strategy that checks local memory first before falling
+ * back to API calls, similar to concept retrieval.
+ *
+ * @module GetConnections
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves a connection by its ID with automatic caching.
+ *
+ * This function implements a two-tier lookup strategy for connection retrieval:
+ * 1. First checks the local cache (ConnectionData)
+ * 2. Falls back to an API call (GetConnection) if not found in cache
+ *
+ * The function ensures that valid connections are returned when available, and
+ * handles cases where connections don't exist or retrieval fails gracefully.
+ *
+ * @param id - The ID of the connection to retrieve
+ *
+ * @returns A promise that resolves to the Connection object, or a connection with id=0 if not found
+ *
+ * @example
+ * ```typescript
+ * // Retrieve a connection and check its type
+ * const connection = await GetConnectionById(12345);
+ *
+ * if (connection.id === 0) {
+ *   console.log("Connection not found");
+ * } else {
+ *   console.log("Connection from:", connection.ofTheConceptId);
+ *   console.log("Connection to:", connection.toTheConceptId);
+ *   console.log("Connection type:", connection.typeId);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in a connection validation scenario
+ * const connectionIds = [123, 456, 789];
+ * const connections = await Promise.all(
+ *   connectionIds.map(id => GetConnectionById(id))
+ * );
+ *
+ * const validConnections = connections.filter(conn => conn.id !== 0);
+ * console.log(`Found ${validConnections.length} valid connections`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Retrieve connection and navigate to connected concepts
+ * const connection = await GetConnectionById(555);
+ * if (connection.id !== 0) {
+ *   const fromConcept = await GetTheConcept(connection.ofTheConceptId);
+ *   const toConcept = await GetTheConcept(connection.toTheConceptId);
+ *   console.log(`${fromConcept.characterValue} -> ${toConcept.characterValue}`);
+ * }
+ * ```
+ *
+ * @remarks
+ * - First checks ConnectionData cache for optimal performance
+ * - Makes an API call only if connection is not in cache or has id=0
+ * - Returns a connection with id=0 if retrieval fails at all levels
+ * - The function validates that id is not null or undefined before API call
+ * - Connections are automatically cached by the GetConnection API call
+ * - This function is null-safe for ID checks but may throw if API fails
+ *
+ * @see {@link ConnectionData.GetConnection} for cache lookup
+ * @see {@link GetConnection} for API-based retrieval
+ * @see {@link Connection} for the connection data structure
+ */
 export declare function GetConnectionById(id: number): Promise<Connection>;

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

@@ -1,2 +1,81 @@
+/**
+ * IndexedDB Data Retrieval Service
+ *
+ * This module provides comprehensive functionality for loading data from IndexedDB into
+ * in-memory data structures. It handles both regular and local database data, loading
+ * connections and concepts into their respective memory structures for efficient access.
+ *
+ * The service supports two data contexts:
+ * - Global/synced data: Loaded from standard IndexedDB stores
+ * - Local data: Loaded from local-only IndexedDB stores for offline or user-specific data
+ *
+ * @module GetDataFromIndexDb
+ */
+/**
+ * Loads data from the standard IndexedDB stores into memory.
+ *
+ * This is the main entry point for initializing the application's in-memory data structures
+ * from persisted database records. Currently focuses on loading connections, with concept
+ * loading functionality commented out for optimization or architectural reasons.
+ *
+ * The function delegates to specialized helpers to load different data types, ensuring
+ * proper separation of concerns and maintainability.
+ *
+ * @returns A promise that resolves when all data has been loaded into memory
+ *
+ * @example
+ * ```typescript
+ * // Initialize application data from IndexedDB
+ * await GetDataFromIndexDb();
+ * console.log('Global data loaded successfully');
+ *
+ * // Access loaded connections
+ * const connections = ConnectionData.getAllConnections();
+ * console.log('Loaded connections:', connections.length);
+ * ```
+ *
+ * @remarks
+ * - Concept loading is currently disabled (commented out lines 11-21)
+ * - Only connections are actively loaded into memory
+ * - This function is typically called during application initialization
+ * - Loads from the standard database, not the local-only database
+ *
+ * @see {@link GetConnectionsFromIndexDb} for connection loading implementation
+ * @see {@link GetDataFromIndexDbLocal} for local database equivalent
+ * @see {@link ConnectionData.AddConnectionToMemory} for how connections are stored
+ */
 export declare function GetDataFromIndexDb(): Promise<void>;
+/**
+ * Loads data from the local IndexedDB stores into memory.
+ *
+ * This function serves as the local database equivalent of GetDataFromIndexDb, handling
+ * data that is stored in local-only database stores. This is typically used for user-specific
+ * data, offline data, or data that should not be synchronized across devices.
+ *
+ * Like its global counterpart, concept loading is currently disabled, with only connection
+ * data being actively loaded into the LocalConnectionData memory structure.
+ *
+ * @returns A promise that resolves when all local data has been loaded into memory
+ *
+ * @example
+ * ```typescript
+ * // Initialize local application data from IndexedDB
+ * await GetDataFromIndexDbLocal();
+ * console.log('Local data loaded successfully');
+ *
+ * // Access loaded local connections
+ * const localConnections = LocalConnectionData.getAllConnections();
+ * console.log('Loaded local connections:', localConnections.length);
+ * ```
+ *
+ * @remarks
+ * - Concept loading is currently disabled (commented out lines 25-33)
+ * - Only local connections are actively loaded into memory
+ * - Uses getAllFromLocalDb instead of getFromDatabaseWithTypeOld for local stores
+ * - Typically called during initialization for applications supporting offline mode
+ *
+ * @see {@link GetConnectionsFromIndexDbLocal} for local connection loading implementation
+ * @see {@link GetDataFromIndexDb} for standard database equivalent
+ * @see {@link LocalConnectionData.AddConnection} for how local connections are stored
+ */
 export declare function GetDataFromIndexDbLocal(): Promise<void>;

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

@@ -1,3 +1,107 @@
+/**
+ * @module GetLink
+ * @description Retrieves linked concepts in the Concept Connection System (CCS).
+ * This module provides functions to traverse concept relationships through linkers,
+ * supporting pagination and both composition-based and raw concept retrieval.
+ * Linkers are special concepts that define typed relationships between concepts.
+ */
 import { Concept } from "./../DataStructures/Concept";
+/**
+ * Retrieves linked concepts as compositions through a specified linker.
+ *
+ * This function follows a multi-step process to retrieve related concepts:
+ * 1. Gets the source concept by ID
+ * 2. Constructs a linker string from the concept's type and provided linker name
+ * 3. Finds the linker concept (type 16)
+ * 4. Retrieves all connections using that linker from the source concept
+ * 5. Prefetches all target concepts for performance
+ * 6. Converts each target concept to its composition representation
+ *
+ * The linker string format is: "{type}_s_{linker}" (e.g., "user_s_posts").
+ *
+ * @param id - The ID of the source concept to find links from
+ * @param linker - The name of the linker relationship (e.g., "posts", "comments", "likes")
+ * @param inpage - Number of results per page (default: 10)
+ * @param page - Page number to retrieve (default: 1)
+ *
+ * @returns Promise resolving to an array of compositions representing linked concepts
+ *
+ * @remarks
+ * - Linker concepts have type ID 16
+ * - Uses bulk prefetching for performance optimization
+ * - Returns compositions with full connection data
+ * - Empty array if linker concept not found
+ * - Linker format: "{source_type}_s_{linker_name}"
+ * - The "_s" suffix indicates a plural/collection relationship
+ *
+ * @example
+ * ```typescript
+ * // Get all posts linked to a user (page 1, 10 per page)
+ * const userPosts = await GetLink(123, "posts");
+ *
+ * // Get comments with custom pagination
+ * const comments = await GetLink(456, "comments", 20, 2);
+ *
+ * // Get likes for a post
+ * const likes = await GetLink(789, "likes", 50, 1);
+ *
+ * // Each result is a composition with connections
+ * userPosts.forEach(post => {
+ *   console.log("Post composition:", post);
+ * });
+ * ```
+ *
+ * @see {@link GetLinkRaw} - Returns raw concepts instead of compositions
+ * @see {@link GetTheConcept} - Retrieves individual concepts
+ * @see {@link GetCompositionWithIdAndDateFromMemory} - Converts concepts to compositions
+ * @see {@link GetConnectionOfTheConcept} - Retrieves connections
+ */
 export declare function GetLink(id: number, linker: string, inpage?: number, page?: number): Promise<any[]>;
+/**
+ * Retrieves linked concepts in raw form through a specified linker.
+ *
+ * This function is similar to GetLink but returns raw Concept objects instead
+ * of compositions. It follows the same linker-based traversal but skips the
+ * composition conversion step, making it more lightweight when only concept
+ * data is needed without full connection details.
+ *
+ * Unlike GetLink, this function does not call GetAllConnectionsOfCompositionBulk
+ * since it doesn't need to build compositions.
+ *
+ * @param id - The ID of the source concept to find links from
+ * @param linker - The name of the linker relationship (e.g., "posts", "comments", "likes")
+ * @param inpage - Number of results per page (default: 10)
+ * @param page - Page number to retrieve (default: 1)
+ *
+ * @returns Promise resolving to an array of raw Concept objects
+ *
+ * @remarks
+ * - Returns Concept objects directly without composition wrapper
+ * - More lightweight than GetLink - use when compositions not needed
+ * - Does not prefetch connection data
+ * - Same linker string format: "{source_type}_s_{linker_name}"
+ * - Empty array if linker concept not found
+ * - Better performance for simple concept retrieval
+ *
+ * @example
+ * ```typescript
+ * // Get raw post concepts
+ * const posts = await GetLinkRaw(123, "posts");
+ * posts.forEach(post => {
+ *   console.log("Post ID:", post.id);
+ *   console.log("Post Type:", post.type);
+ * });
+ *
+ * // Get comments without composition overhead
+ * const comments = await GetLinkRaw(456, "comments", 20, 2);
+ *
+ * // Quick check for existence
+ * const likes = await GetLinkRaw(789, "likes", 1, 1);
+ * const hasLikes = likes.length > 0;
+ * ```
+ *
+ * @see {@link GetLink} - Returns full compositions instead of raw concepts
+ * @see {@link GetTheConcept} - Retrieves individual concepts
+ * @see {@link GetConnectionOfTheConcept} - Retrieves connections
+ */
 export declare function GetLinkRaw(id: number, linker: string, inpage?: number, page?: number): Promise<Concept[]>;

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

@@ -1,3 +1,102 @@
+/**
+ * @module GetLinkerConnectionFromConcept
+ * @description Retrieves linker connections in the Concept Connection System (CCS).
+ * This module provides functions to fetch all linker-type connections associated with
+ * a concept, supporting both outgoing (from) and incoming (to) directions. Linker
+ * connections are special connections that use linker concepts to define typed
+ * collection relationships between concepts.
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Retrieves all linker connections originating from a concept.
+ *
+ * This function fetches all connections where the specified concept is the source
+ * (ofTheConcept) and the connection type is a linker concept. It enriches each
+ * connection by fetching and attaching the full type concept, allowing inspection
+ * of what kind of linker relationship is being used.
+ *
+ * Linker connections typically represent collection relationships like "user_s_posts"
+ * where the "_s" indicates a plural/collection relationship defined by a linker concept.
+ *
+ * @param id - The ID of the concept to get linker connections from
+ *
+ * @returns Promise resolving to an array of Connection objects with type concepts attached
+ *
+ * @remarks
+ * - Fetches all linker connections without pagination
+ * - Each connection's type property is populated with the full Concept
+ * - Linker connections have special type concepts (typically type ID 16)
+ * - Iterates through all connections to enrich with type data
+ * - Connection.type will be a fully populated Concept object
+ * - Used for traversing collection-based relationships
+ *
+ * @example
+ * ```typescript
+ * // Get all linker connections from a user
+ * const userLinkers = await GetLinkerConnectionFromConcepts(123);
+ * userLinkers.forEach(connection => {
+ *   console.log("Linker type:", connection.type?.characterValue);
+ *   console.log("Points to:", connection.toTheConceptId);
+ *   console.log("Connection ID:", connection.id);
+ * });
+ *
+ * // Find all collection relationships a concept participates in
+ * const conceptLinkers = await GetLinkerConnectionFromConcepts(456);
+ * const linkerTypes = conceptLinkers.map(c => c.type?.characterValue);
+ * console.log("This concept has linkers:", linkerTypes);
+ * // Output: ["user_s_posts", "user_s_comments", ...]
+ * ```
+ *
+ * @see {@link GetLinkerConnectionToConcepts} - Gets linker connections pointing to a concept
+ * @see {@link GetAllLinkerConnectionsFromTheConcept} - API function for fetching connections
+ * @see {@link GetTheConcept} - Fetches the type concept for each connection
+ */
 export declare function GetLinkerConnectionFromConcepts(id: number): Promise<Connection[]>;
+/**
+ * Retrieves all linker connections pointing to a concept.
+ *
+ * This function fetches all connections where the specified concept is the target
+ * (toTheConcept) and the connection type is a linker concept. It enriches each
+ * connection by fetching and attaching the full type concept, allowing inspection
+ * of what kind of linker relationship is being used.
+ *
+ * This is the inverse of GetLinkerConnectionFromConcepts - it finds all collection
+ * relationships where this concept is included as a member of the collection.
+ *
+ * @param id - The ID of the concept to get linker connections to
+ *
+ * @returns Promise resolving to an array of Connection objects with type concepts attached
+ *
+ * @remarks
+ * - Fetches all incoming linker connections without pagination
+ * - Each connection's type property is populated with the full Concept
+ * - Useful for finding all collections that include this concept
+ * - Connection.type will be a fully populated Concept object
+ * - Reverse direction of GetLinkerConnectionFromConcepts
+ * - Used for reverse traversal of collection relationships
+ *
+ * @example
+ * ```typescript
+ * // Find all collections that include this post
+ * const postInCollections = await GetLinkerConnectionToConcepts(789);
+ * postInCollections.forEach(connection => {
+ *   console.log("Included in collection:", connection.type?.characterValue);
+ *   console.log("Collection owner:", connection.ofTheConceptId);
+ * });
+ *
+ * // Check if a concept is part of any linker collections
+ * const incomingLinkers = await GetLinkerConnectionToConcepts(456);
+ * const isInCollections = incomingLinkers.length > 0;
+ * console.log("Is part of collections:", isInCollections);
+ *
+ * // Find what users have this comment in their collection
+ * const commentCollections = await GetLinkerConnectionToConcepts(123);
+ * const ownerIds = commentCollections.map(c => c.ofTheConceptId);
+ * console.log("Owned by concepts:", ownerIds);
+ * ```
+ *
+ * @see {@link GetLinkerConnectionFromConcepts} - Gets linker connections from a concept
+ * @see {@link GetAllLinkerConnectionsToTheConcept} - API function for fetching connections
+ * @see {@link GetTheConcept} - Fetches the type concept for each connection
+ */
 export declare function GetLinkerConnectionToConcepts(id: number): Promise<Connection[]>;

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

@@ -1,2 +1,59 @@
+/**
+ * @module GetMaximumConnectionSyncTime
+ * @description Utility for finding maximum sync times in the Concept Connection System (CCS).
+ * This module provides functionality to determine the most recent synchronization time
+ * from a collection of connections, enabling efficient incremental synchronization and
+ * tracking of data freshness across the distributed concept system.
+ */
 import { Connection } from "../DataStructures/Connection";
+/**
+ * Finds the maximum (most recent) local sync time from an array of connections.
+ *
+ * This function iterates through all provided connections and identifies the most
+ * recent localSyncTime value. This is useful for incremental synchronization operations
+ * where you need to know when the last sync occurred to fetch only newer data.
+ *
+ * The function compares Date objects and returns the maximum timestamp, which can
+ * then be used as a "since" parameter in subsequent sync operations to fetch only
+ * connections that have been modified after this time.
+ *
+ * @param connections - Array of Connection objects to examine for sync times
+ *
+ * @returns The most recent Date found in the connections' localSyncTime fields,
+ *          or Date(0) (January 1, 1970) if no connections or all have earlier times
+ *
+ * @remarks
+ * - Initializes maxTime to Date(0) (Unix epoch: January 1, 1970, 00:00:00 UTC)
+ * - Compares Date objects directly using > operator
+ * - Returns Date(0) if connections array is empty
+ * - Useful for implementing incremental sync strategies
+ * - localSyncTime represents when the connection was last synchronized locally
+ *
+ * @example
+ * ```typescript
+ * // Get max sync time from user's connections
+ * const userConnections = await GetConnectionsForUser(123);
+ * const lastSyncTime = GetMaximumConnectionSyncTime(userConnections);
+ * console.log("Last sync occurred at:", lastSyncTime);
+ *
+ * // Use for incremental sync
+ * const connections = await GetAllConnections();
+ * const maxTime = GetMaximumConnectionSyncTime(connections);
+ * // Fetch only newer connections
+ * const newConnections = await GetConnectionsSince(maxTime);
+ *
+ * // Check if any connections exist
+ * const emptyArray: Connection[] = [];
+ * const emptyMaxTime = GetMaximumConnectionSyncTime(emptyArray);
+ * console.log(emptyMaxTime.getTime()); // 0 (epoch)
+ *
+ * // Track sync status
+ * const connections = await GetConceptConnections(456);
+ * const lastSync = GetMaximumConnectionSyncTime(connections);
+ * const hoursSinceSync = (Date.now() - lastSync.getTime()) / (1000 * 60 * 60);
+ * console.log(`Last synced ${hoursSinceSync} hours ago`);
+ * ```
+ *
+ * @see {@link Connection} - Connection data structure with localSyncTime property
+ */
 export declare function GetMaximumConnectionSyncTime(connections: Connection[]): Date;