mftsccs-node 0.2.7 → 0.2.9

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

@@ -1,5 +1,167 @@
+/**
+ * @module GetRelation
+ * @description Retrieves related concepts in the Concept Connection System (CCS).
+ * This module provides functions to traverse concept relationships, supporting both
+ * forward and reverse traversal, pagination, and multiple return formats (compositions,
+ * raw concepts, or connections). Relations define semantic connections between concepts.
+ */
 import { Connection } from "../DataStructures/Connection";
 import { Concept } from "./../DataStructures/Concept";
+/**
+ * Retrieves related concepts as compositions through a specified relation.
+ *
+ * This function traverses concept relationships in either forward or reverse direction:
+ * - Forward: Finds concepts that the source concept points TO via the relation
+ * - Reverse: Finds concepts that point TO the source concept via the relation
+ *
+ * The process:
+ * 1. Gets the source concept by ID
+ * 2. Finds the relation concept by character and category
+ * 3. Retrieves connections in the specified direction
+ * 4. Prefetches all related concepts for performance
+ * 5. Converts each concept to its composition representation
+ *
+ * @param id - The ID of the source concept to find relations for
+ * @param relation - The name of the relation (e.g., "author", "parent", "tag")
+ * @param inpage - Number of results per page (default: 10)
+ * @param page - Page number to retrieve (default: 1)
+ * @param reverse - If true, finds concepts pointing TO this concept; if false, finds concepts this concept points TO (default: false)
+ *
+ * @returns Promise resolving to an array of compositions representing related concepts
+ *
+ * @remarks
+ * - Uses GetConceptByCharacterAndCategory to find the relation concept
+ * - Forward direction uses GetConnectionOfTheConcept (from -> to)
+ * - Reverse direction uses GetConnectionToTheConcept (to <- from)
+ * - Uses bulk prefetching for performance optimization
+ * - Returns compositions with full connection data
+ * - Empty array if relation concept not found
+ *
+ * @example
+ * ```typescript
+ * // Get all posts authored by a user (forward relation)
+ * const userPosts = await GetRelation(123, "author", 10, 1, false);
+ *
+ * // Get the author of a post (reverse relation)
+ * const postAuthor = await GetRelation(456, "author", 1, 1, true);
+ *
+ * // Get tags for an article (forward)
+ * const tags = await GetRelation(789, "tag", 20, 1, false);
+ *
+ * // Get all articles with a specific tag (reverse)
+ * const taggedArticles = await GetRelation(789, "tag", 20, 1, true);
+ *
+ * // Each result is a composition with connections
+ * userPosts.forEach(post => {
+ *   console.log("Related composition:", post);
+ * });
+ * ```
+ *
+ * @see {@link GetRelationRaw} - Returns raw concepts instead of compositions
+ * @see {@link GetRelationConnections} - Returns connection objects
+ * @see {@link GetTheConcept} - Retrieves individual concepts
+ * @see {@link GetCompositionWithIdAndDateFromMemory} - Converts concepts to compositions
+ */
 export declare function GetRelation(id: number, relation: string, inpage?: number, page?: number, reverse?: boolean): Promise<any[]>;
+/**
+ * Retrieves related concepts in raw form through a specified relation.
+ *
+ * This function is similar to GetRelation but returns raw Concept objects instead
+ * of compositions. It supports both forward and reverse traversal and uses bulk
+ * concept retrieval for optimal performance. This is more lightweight when only
+ * concept data is needed without full composition details.
+ *
+ * @param id - The ID of the source concept to find relations for
+ * @param relation - The name of the relation (e.g., "author", "parent", "tag")
+ * @param inpage - Number of results per page (default: 10)
+ * @param page - Page number to retrieve (default: 1)
+ * @param reverse - If true, finds concepts pointing TO this concept; if false, finds concepts this concept points TO (default: false)
+ *
+ * @returns Promise resolving to an array of raw Concept objects
+ *
+ * @remarks
+ * - Returns Concept objects directly without composition wrapper
+ * - More lightweight than GetRelation - use when compositions not needed
+ * - Uses GetConceptBulk for efficient bulk retrieval
+ * - Supports both forward and reverse traversal
+ * - Empty array if relation concept not found
+ * - Better performance for simple concept retrieval
+ *
+ * @example
+ * ```typescript
+ * // Get raw author concepts
+ * const authors = await GetRelationRaw(123, "author", 10, 1, true);
+ * authors.forEach(author => {
+ *   console.log("Author ID:", author.id);
+ *   console.log("Author Type:", author.type);
+ * });
+ *
+ * // Get related tags without composition overhead
+ * const tags = await GetRelationRaw(456, "tag", 20, 1, false);
+ *
+ * // Quick check for existence
+ * const parents = await GetRelationRaw(789, "parent", 1, 1, false);
+ * const hasParent = parents.length > 0;
+ * ```
+ *
+ * @see {@link GetRelation} - Returns full compositions instead of raw concepts
+ * @see {@link GetRelationConnections} - Returns connection objects
+ * @see {@link GetConceptBulk} - Bulk concept retrieval
+ */
 export declare function GetRelationRaw(id: number, relation: string, inpage?: number, page?: number, reverse?: boolean): Promise<Concept[]>;
+/**
+ * Retrieves connection objects for a specified relation.
+ *
+ * This function returns the actual Connection objects that link concepts through
+ * a relation, rather than the related concepts themselves. This is useful when
+ * you need to inspect or manipulate the connection metadata, timestamps, or
+ * relationship properties directly.
+ *
+ * Unlike GetRelation and GetRelationRaw which return concepts, this returns the
+ * connections that define the relationships, allowing access to connection-specific
+ * data like creation time, sync status, and connection properties.
+ *
+ * @param id - The ID of the source concept to find relation connections for
+ * @param relation - The name of the relation (e.g., "author", "parent", "tag")
+ * @param inpage - Number of results per page (default: 10)
+ * @param page - Page number to retrieve (default: 1)
+ * @param reverse - If true, finds connections pointing TO this concept; if false, finds connections FROM this concept (default: false)
+ *
+ * @returns Promise resolving to an array of Connection objects
+ *
+ * @remarks
+ * - Returns Connection objects, not Concept objects
+ * - Provides access to connection metadata and properties
+ * - Supports both forward and reverse traversal
+ * - Does not fetch or return the actual concepts being connected
+ * - Empty array if relation concept not found
+ * - Useful for connection-level operations and analysis
+ * - Connection objects contain: typeId, ofTheConceptId, toTheConceptId, etc.
+ *
+ * @example
+ * ```typescript
+ * // Get connection objects for author relations
+ * const authorConnections = await GetRelationConnections(123, "author", 10, 1, false);
+ * authorConnections.forEach(conn => {
+ *   console.log("Connection Type ID:", conn.typeId);
+ *   console.log("From Concept:", conn.ofTheConceptId);
+ *   console.log("To Concept:", conn.toTheConceptId);
+ *   console.log("Created:", conn.localSyncTime);
+ * });
+ *
+ * // Get tag connections in reverse
+ * const tagConnections = await GetRelationConnections(456, "tag", 20, 1, true);
+ *
+ * // Check connection metadata
+ * const parentConnections = await GetRelationConnections(789, "parent", 1, 1, false);
+ * if (parentConnections.length > 0) {
+ *   console.log("Parent connection exists");
+ *   console.log("Connection details:", parentConnections[0]);
+ * }
+ * ```
+ *
+ * @see {@link GetRelation} - Returns related concepts as compositions
+ * @see {@link GetRelationRaw} - Returns related concepts as raw objects
+ * @see {@link Connection} - Connection data structure
+ */
 export declare function GetRelationConnections(id: number, relation: string, inpage?: number, page?: number, reverse?: boolean): Promise<Connection[]>;

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

@@ -1,2 +1,73 @@
+/**
+ * Concept Retrieval Service
+ *
+ * This module provides the primary interface for retrieving concepts from the system.
+ * It implements a multi-tier caching strategy that checks local memory first, then
+ * falls back to API calls. It also handles special ghost concepts (negative IDs) and
+ * ensures concept type information is properly populated.
+ *
+ * @module GetTheConcept
+ */
 import { Concept } from "../DataStructures/Concept";
+/**
+ * Retrieves a concept by ID with automatic caching and type population.
+ *
+ * This is the primary function for concept retrieval in the CCS system. It implements
+ * a sophisticated multi-tier lookup strategy:
+ * 1. For negative IDs: Retrieves ghost concepts from user-specific storage
+ * 2. For positive IDs: Checks local cache (ConceptsData) first
+ * 3. Falls back to API call (GetConcept) if not in cache
+ * 4. Ensures the concept's type information is populated
+ * 5. Returns default concept if all retrieval attempts fail
+ *
+ * Ghost concepts (negative IDs) are special user-specific concepts that exist in
+ * local storage rather than the main database. They're converted from LConcept format
+ * to standard Concept format during retrieval.
+ *
+ * @param id - The ID of the concept to retrieve (negative IDs are ghost concepts)
+ * @param userId - The user ID for ghost concept lookup (default: 999)
+ *
+ * @returns A promise that resolves to the retrieved Concept, or a default concept if not found
+ *
+ * @example
+ * ```typescript
+ * // Retrieve a regular concept
+ * const concept = await GetTheConcept(12345);
+ * console.log("Concept type:", concept.type?.characterValue);
+ * console.log("Concept value:", concept.characterValue);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Retrieve a ghost concept (negative ID)
+ * const ghostConcept = await GetTheConcept(-100, 456);
+ * console.log("Ghost concept:", ghostConcept.characterValue);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check if concept was found
+ * const concept = await GetTheConcept(99999);
+ * if (concept.id === 0) {
+ *   console.log("Concept not found, using default");
+ * } else {
+ *   console.log("Found concept:", concept.id);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Negative IDs indicate ghost concepts stored in user-specific storage
+ * - Ghost concepts are converted from LConcept to Concept format
+ * - The function checks local cache (ConceptsData) before making API calls
+ * - If a concept is found but has no type populated, fetches and attaches the type
+ * - Type concepts are also cached for efficiency
+ * - Returns a default concept (id=0) if retrieval fails at all levels
+ * - The function is null-safe; always returns a Concept instance
+ * - Automatically populates concept.type if it's null but typeId exists
+ *
+ * @see {@link CreateDefaultConcept} for the default concept structure
+ * @see {@link ConceptsData.GetConcept} for cache lookup
+ * @see {@link GetConcept} for API-based retrieval
+ * @see {@link GetUserGhostId} for ghost concept retrieval
+ */
 export default function GetTheConcept(id: number, userId?: number): Promise<Concept>;

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

@@ -1,2 +1,76 @@
+/**
+ * @module GetTheReferent
+ * @description Retrieves referent concepts in the Concept Connection System (CCS).
+ * This module provides functionality to fetch the referent concept of a given concept.
+ * Referents are concepts that serve as the actual data or value that another concept
+ * points to, creating a level of indirection that enables flexible data modeling.
+ */
 import { Concept } from "../DataStructures/Concept";
+/**
+ * Retrieves the referent concept for a given concept.
+ *
+ * This function fetches the concept that serves as the referent (the actual value or
+ * data) for another concept. In the CCS system, concepts often point to other concepts
+ * as their referents, creating a flexible hierarchy where concepts can reference
+ * other concepts as their underlying data.
+ *
+ * For example, a name concept might reference a character concept as its referent,
+ * or a typed instance might reference its data concept as a referent.
+ *
+ * @param id - The ID of the concept (currently unused in implementation)
+ * @param userId - The user ID of the concept (currently unused in implementation)
+ * @param referentId - The ID of the referent concept to retrieve
+ *
+ * @returns Promise resolving to the referent Concept
+ *
+ * @remarks
+ * - Currently only uses the referentId parameter, id and userId are not utilized
+ * - The id and userId parameters may be used for future access control or validation
+ * - Returns the full Concept object of the referent
+ * - Uses nullish coalescing to default referentId to 0 if null/undefined
+ * - Previously returned ReferentInfo (commented out code shows this)
+ * - Simplified to directly return the referent concept
+ *
+ * @example
+ * ```typescript
+ * // Get the referent of a name concept
+ * const nameConcept = await GetTheConcept(123);
+ * const referent = await GetTheReferent(
+ *   nameConcept.id,
+ *   nameConcept.userId,
+ *   nameConcept.referentId
+ * );
+ * console.log("Referent concept:", referent);
+ * // referent might be a character concept
+ *
+ * // Get character data from a typed concept
+ * const typedConcept = await GetTheConcept(456);
+ * const characterData = await GetTheReferent(
+ *   typedConcept.id,
+ *   typedConcept.userId,
+ *   typedConcept.referentId
+ * );
+ * console.log("Character value:", characterData.characterValue);
+ *
+ * // Chain referent lookups
+ * const concept = await GetTheConcept(789);
+ * const firstReferent = await GetTheReferent(
+ *   concept.id,
+ *   concept.userId,
+ *   concept.referentId
+ * );
+ * if (firstReferent.referentId) {
+ *   const secondReferent = await GetTheReferent(
+ *     firstReferent.id,
+ *     firstReferent.userId,
+ *     firstReferent.referentId
+ *   );
+ *   console.log("Nested referent:", secondReferent);
+ * }
+ * ```
+ *
+ * @see {@link GetTheConcept} - Retrieves the referent concept by ID
+ * @see {@link ReferentInfo} - Data structure for referent information (legacy)
+ * @see {@link Concept} - The concept data structure
+ */
 export default function GetTheReferent(id: number, userId: number, referentId: number): Promise<Concept>;

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

@@ -1,2 +1,121 @@
+/**
+ * System Initialization Service
+ *
+ * This module provides core initialization functionality for the CCS-JS system, handling
+ * the startup sequence including settings retrieval, AI data synchronization, and system
+ * configuration. It manages both the initial system bootstrap and subsequent synchronization
+ * status updates.
+ *
+ * The initialization process ensures that all necessary data structures, settings, and
+ * AI-related data are properly loaded before the application becomes fully operational.
+ *
+ * @module InitializeSystem
+ */
+/**
+ * Initializes the CCS-JS system by loading settings and AI data.
+ *
+ * This is the primary initialization function that bootstraps the application by:
+ * 1. Retrieving system statistics and settings from the database
+ * 2. Loading AI-related data through the GetAiData API call
+ * 3. Returning a success indicator to confirm initialization completion
+ *
+ * This function should be called once during application startup before any other
+ * operations are performed. It ensures the system is in a ready state with all
+ * necessary configuration and data loaded.
+ *
+ * @returns A promise that resolves to true when initialization is complete
+ *
+ * @example
+ * ```typescript
+ * // Initialize the system at application startup
+ * const initialized = await InitializeSystem();
+ * if (initialized) {
+ *   console.log('System initialized successfully');
+ *   // Proceed with application logic
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in an async initialization flow
+ * async function startApplication() {
+ *   try {
+ *     await InitializeSystem();
+ *     // Load additional data structures
+ *     await CreateBinaryTreeFromData();
+ *     console.log('Application ready');
+ *   } catch (error) {
+ *     console.error('Initialization failed:', error);
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * - Should be called once during application bootstrap
+ * - Loads statsData from database and casts it to SettingData type
+ * - Retrieves AI data from external API or data source
+ * - Always returns true upon successful completion
+ * - Does not handle errors explicitly; calling code should wrap in try-catch if needed
+ *
+ * @see {@link GetStatsFromDatabase} for statistics and settings retrieval
+ * @see {@link GetAiData} for AI data loading implementation
+ * @see {@link SettingData} for the settings data structure
+ * @see {@link PurgatoryDatabaseUpdated} for post-sync initialization
+ */
 export default function InitializeSystem(): Promise<boolean>;
+/**
+ * Updates the system settings to reflect that the purgatory database has been synchronized.
+ *
+ * This function is called after the purgatory database (a staging or temporary database)
+ * has been successfully updated or synchronized with the main system. It marks the system
+ * as being in an online sync state and persists this status to the database.
+ *
+ * The purgatory database concept typically represents a temporary holding area for data
+ * that needs to be processed, reviewed, or synchronized before being committed to the
+ * main data structures. This function signals that such synchronization has completed.
+ *
+ * @returns A promise that resolves when the sync flag has been updated in the database
+ *
+ * @example
+ * ```typescript
+ * // After synchronizing the purgatory database
+ * async function syncPurgatoryData() {
+ *   // ... perform synchronization logic ...
+ *
+ *   // Update the system to reflect successful sync
+ *   await PurgatoryDatabaseUpdated();
+ *   console.log('System marked as synced');
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in a data migration or sync workflow
+ * async function migrateDataFromPurgatory() {
+ *   try {
+ *     // Migrate concepts and connections
+ *     await migratePurgatoryData();
+ *
+ *     // Mark the operation as complete
+ *     await PurgatoryDatabaseUpdated();
+ *
+ *     console.log('Purgatory sync complete, system online');
+ *   } catch (error) {
+ *     console.error('Sync failed:', error);
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * - Sets Settings.isOnlineSync to true, indicating the system is in sync
+ * - Creates a new SettingData instance with the updated sync status
+ * - Persists the updated settings to the database via AiUpdateFlag
+ * - Should be called after completing purgatory database synchronization
+ * - Part of the data synchronization lifecycle management
+ *
+ * @see {@link AiUpdateFlag} for database update implementation
+ * @see {@link SettingData} for the settings data structure
+ * @see {@link Settings} for the global settings object
+ * @see {@link InitializeSystem} for system initialization
+ */
 export declare function PurgatoryDatabaseUpdated(): Promise<void>;

package/dist/types/Services/Local/CreateDefaultLConcept.d.ts

@@ -1,2 +1,50 @@
+/**
+ * Default Local Concept Creation Module
+ *
+ * This module provides a factory function for creating empty/default local concepts.
+ * These default concepts are useful as placeholders, initial values, or for representing
+ * "not found" states in the Concept Connection System.
+ *
+ * @module CreateDefaultLConcept
+ */
 import { LConcept } from "../../DataStructures/Local/LConcept";
+/**
+ * Creates a default empty local concept with all fields initialized to zero or default values.
+ *
+ * This function generates a placeholder concept that can be used for initialization,
+ * default return values, or to represent the absence of a concept. All numeric fields
+ * are set to 0, and string fields are set to "0", which allows calling code to check
+ * for validity (e.g., `if (concept.id === 0)` to detect a default concept).
+ *
+ * @returns A new LConcept instance with all fields set to default/zero values
+ *
+ * @remarks
+ * - All numeric IDs (id, userId, typeId, categoryId, accessId, referentId) are set to 0
+ * - Character fields (referent, typecharacter) are set to "0"
+ * - isNew flag is set to false (not a new concept)
+ * - created_on and updated_on are set to current timestamp
+ * - Commonly used as a null object pattern to avoid null checks
+ *
+ * @example
+ * ```typescript
+ * // Use as a default return value when concept is not found
+ * function findConcept(id: number): LConcept {
+ *   const found = database.find(id);
+ *   return found || CreateDefaultLConcept();
+ * }
+ *
+ * const concept = findConcept(123);
+ * if (concept.id === 0) {
+ *   console.log("Concept not found");
+ * }
+ *
+ * // Use as initial value for variables
+ * let mainConcept = CreateDefaultLConcept();
+ * // ... later assign actual concept
+ * mainConcept = await fetchConcept();
+ * ```
+ *
+ * @see {@link LConcept} - The local concept data structure
+ * @see {@link CreateTheConceptLocal} - Creates actual concepts with real data
+ */
 export declare function CreateDefaultLConcept(): LConcept;

package/dist/types/Services/Local/CreateLocalBinaryTreeFromData.d.ts

@@ -1 +1,50 @@
+/**
+ * Local Binary Tree Initialization Module
+ *
+ * This module handles the initialization of the in-memory binary tree data structure
+ * from persisted local concepts stored in IndexedDB. It loads all concepts from the
+ * database and populates the in-memory cache for fast access.
+ *
+ * @module CreateLocalBinaryTreeFromData
+ */
+/**
+ * Initializes the local binary tree structure by loading concepts from IndexedDB.
+ *
+ * This function retrieves all locally stored concepts from the IndexedDB database
+ * and populates the in-memory LocalConceptsData structure. This is typically called
+ * during application initialization to hydrate the memory cache from persistent storage.
+ *
+ * The function ensures that all previously created local concepts are available in
+ * memory for fast lookup operations without needing to query the database repeatedly.
+ *
+ * @returns A promise that resolves when all concepts have been loaded into memory
+ *
+ * @remarks
+ * - Retrieves all concepts from the "localconcept" store in IndexedDB
+ * - Uses `LocalConceptsData.AddConceptToMemory` to add each concept to the in-memory structure
+ * - The commented code suggests this originally used a traditional binary tree (Node-based)
+ *   but now uses a more efficient data structure via LocalConceptsData
+ * - Safe to call multiple times; duplicate concepts will be handled by AddConceptToMemory
+ * - This is a synchronization step from persistent storage to volatile memory
+ *
+ * @example
+ * ```typescript
+ * // During application initialization
+ * async function initializeApp() {
+ *   console.log("Loading local concepts...");
+ *   await CreateLocalBinaryTreeFromData();
+ *   console.log("Local concepts loaded into memory");
+ *
+ *   // Now concepts can be accessed quickly from memory
+ *   const concept = await LocalConceptsData.GetConcept(123);
+ * }
+ *
+ * initializeApp();
+ * ```
+ *
+ * @see {@link LocalConceptsData.AddConceptToMemory} - Adds concepts to in-memory storage
+ * @see {@link getAllFromLocalDb} - Retrieves all records from IndexedDB
+ * @see {@link CreateLocalBinaryTypeTreeFromData} - Similar function for type-indexed tree
+ * @see {@link CreateLocalCharacterBinaryTreeFromData} - Similar function for character-indexed tree
+ */
 export default function CreateLocalBinaryTreeFromData(): Promise<void>;

package/dist/types/Services/Local/CreateLocalBinaryTypeTreeFromData.d.ts

@@ -1 +1,55 @@
+/**
+ * Local Binary Type Tree Initialization Module
+ *
+ * This module creates and populates a binary search tree indexed by concept type IDs.
+ * This specialized tree structure enables efficient lookup of concepts by their type,
+ * which is crucial for querying all concepts of a particular type.
+ *
+ * @module CreateLocalBinaryTypeTreeFromData
+ */
+/**
+ * Initializes a binary search tree indexed by concept type IDs from IndexedDB.
+ *
+ * This function retrieves all locally stored concepts and builds a binary search tree
+ * where each node is indexed by the concept's typeId. This structure allows for O(log n)
+ * lookup time when searching for concepts of a specific type, significantly improving
+ * performance over linear searches.
+ *
+ * The function includes performance measurement via timestamps to monitor initialization time.
+ *
+ * @returns A promise that resolves when the type-indexed tree is fully populated
+ *
+ * @remarks
+ * - Creates LNode instances with typeId as the key for each concept
+ * - Builds a balanced binary search tree structure via LocalBinaryTypeTree
+ * - Measures execution time for performance monitoring (though not returned)
+ * - Called during application initialization, typically after CreateLocalBinaryTreeFromData
+ * - Enables efficient queries like "get all concepts of type X"
+ * - Tree structure allows for fast insertion, deletion, and lookup operations
+ *
+ * @example
+ * ```typescript
+ * // Initialize the type-indexed tree during app startup
+ * async function initializeTrees() {
+ *   await CreateLocalBinaryTreeFromData(); // General tree first
+ *   await CreateLocalBinaryTypeTreeFromData(); // Then type-specific tree
+ *
+ *   // Now can efficiently query concepts by type
+ *   const userConcepts = LocalBinaryTypeTree.getConceptsByType(51); // typeId 51
+ *   console.log(`Found ${userConcepts.length} concepts of type 51`);
+ * }
+ *
+ * // Measure initialization performance
+ * const start = performance.now();
+ * await CreateLocalBinaryTypeTreeFromData();
+ * const duration = performance.now() - start;
+ * console.log(`Type tree initialized in ${duration}ms`);
+ * ```
+ *
+ * @see {@link LocalBinaryTypeTree} - The binary tree structure for type-indexed concepts
+ * @see {@link LNode} - The node structure used in the tree
+ * @see {@link getAllFromLocalDb} - Retrieves all concepts from IndexedDB
+ * @see {@link CreateLocalBinaryTreeFromData} - General concept tree initialization
+ * @see {@link CreateLocalCharacterBinaryTreeFromData} - Character-indexed tree initialization
+ */
 export declare function CreateLocalBinaryTypeTreeFromData(): Promise<void>;

package/dist/types/Services/Local/CreateLocalCharacterBinaryTree.d.ts

@@ -1 +1,61 @@
+/**
+ * Local Character Binary Tree Initialization Module
+ *
+ * This module creates and populates a binary search tree indexed by concept character values.
+ * This specialized tree structure enables efficient lookup of concepts by their character/name,
+ * supporting fast string-based queries without requiring full database scans.
+ *
+ * @module CreateLocalCharacterBinaryTree
+ */
+/**
+ * Initializes a binary search tree indexed by concept character values from IndexedDB.
+ *
+ * This function retrieves all locally stored concepts and builds a binary search tree
+ * where each node is indexed by the concept's characterValue (the string content/name
+ * of the concept). This structure enables efficient O(log n) lookup when searching for
+ * concepts by their character/string value.
+ *
+ * The function includes performance measurement to monitor initialization time.
+ *
+ * @returns A promise that resolves when the character-indexed tree is fully populated
+ *
+ * @remarks
+ * - Creates LNode instances with characterValue as the key for each concept
+ * - Builds a balanced binary search tree structure via LocalBinaryCharacterTree
+ * - Measures execution time for performance monitoring (though not returned)
+ * - Particularly useful for autocomplete, search, and lookup-by-name operations
+ * - Called during application initialization alongside other tree structures
+ * - Enables queries like "find concept with character value 'John Doe'"
+ * - Character values are typically stored as strings and compared lexicographically
+ *
+ * @example
+ * ```typescript
+ * // Initialize all tree structures during app startup
+ * async function initializeAllTrees() {
+ *   await CreateLocalBinaryTreeFromData();
+ *   await CreateLocalBinaryTypeTreeFromData();
+ *   await CreateLocalCharacterBinaryTreeFromData();
+ *
+ *   // Now can efficiently query concepts by character value
+ *   const concept = LocalBinaryCharacterTree.findByCharacter("John Doe");
+ *   if (concept) {
+ *     console.log(`Found concept: ${concept.id}`);
+ *   }
+ * }
+ *
+ * // Use for autocomplete functionality
+ * async function searchConcepts(prefix: string) {
+ *   await CreateLocalCharacterBinaryTreeFromData();
+ *   const results = LocalBinaryCharacterTree.findByPrefix(prefix);
+ *   return results; // All concepts starting with prefix
+ * }
+ * ```
+ *
+ * @see {@link LocalBinaryCharacterTree} - The binary tree structure for character-indexed concepts
+ * @see {@link LNode} - The node structure used in the tree
+ * @see {@link getAllFromLocalDb} - Retrieves all concepts from IndexedDB
+ * @see {@link CreateLocalBinaryTreeFromData} - General concept tree initialization
+ * @see {@link CreateLocalBinaryTypeTreeFromData} - Type-indexed tree initialization
+ * @see {@link GetConceptByCharacterLocal} - Related function that uses this tree
+ */
 export declare function CreateLocalCharacterBinaryTreeFromData(): Promise<void>;