mftsccs-browser 2.2.20-beta → 2.2.22-beta

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

@@ -1,9 +1,96 @@
 import { Concept } from "../DataStructures/Concept";
 /**
- * Get The Concept From Concept Id
- * @param id this is the id that can be used to get the concept.
- * @param userId This is the user that calls the concept
- * @returns Concept if it exists
+ * Retrieves a concept by its ID with intelligent caching and multi-source lookup.
+ *
+ * This is the primary function for fetching concepts in the system. It implements a sophisticated
+ * multi-level retrieval strategy:
+ *
+ * **Retrieval Strategy:**
+ * 1. Checks in-memory promise cache to prevent duplicate requests
+ * 2. For negative IDs: Fetches from local IndexedDB (LocalConceptsData)
+ * 3. For positive IDs: Checks local ConceptsData cache first
+ * 4. If not in cache: Fetches from backend API
+ * 5. Automatically resolves and attaches the concept's type information
+ * 6. Routes through service worker if enabled for better performance
+ *
+ * **Features:**
+ * - Promise caching prevents duplicate concurrent requests for the same concept
+ * - Automatic type resolution (fetches and attaches type concept)
+ * - Access tracking integration (increments access counter if enabled)
+ * - Service worker support for background processing
+ * - Error logging and performance monitoring
+ * - Supports both server concepts (positive IDs) and local concepts (negative IDs)
+ *
+ * @param id - The unique identifier of the concept to retrieve.
+ *            Positive IDs = server concepts, Negative IDs = local-only concepts
+ * @param userId - The ID of the user requesting the concept. Used for access tracking
+ *                and audit logging. Defaults to 999 (system/anonymous user)
+ *
+ * @returns Promise resolving to the Concept object if found, or a default empty Concept if not found
+ *
+ * @example
+ * // Get a server concept
+ * const concept = await GetTheConcept(12345, 101);
+ * console.log(concept.characterValue); // "Alice Smith"
+ * console.log(concept.type?.characterValue); // "Person" (auto-resolved)
+ *
+ * @example
+ * // Get a local concept (negative ID)
+ * const localConcept = await GetTheConcept(-5, 101);
+ * console.log(localConcept.characterValue); // "Local Draft"
+ *
+ * @example
+ * // Multiple concurrent calls use the same promise (efficient)
+ * const [c1, c2, c3] = await Promise.all([
+ *   GetTheConcept(123),
+ *   GetTheConcept(123),  // Same ID - uses cached promise
+ *   GetTheConcept(123)   // Same ID - uses cached promise
+ * ]);
+ * // Only one actual fetch is performed
+ *
+ * @throws Will log errors but returns a default empty concept instead of throwing
+ *
+ * @see {@link CreateTheConcept} for creating new concepts
+ * @see {@link GetConceptBulk} for fetching multiple concepts efficiently
+ * @see {@link AddTypeConcept} for manually adding type information to a concept
  */
 export default function GetTheConcept(id: number, userId?: number): Promise<Concept>;
+/**
+ * Fetches and attaches type information to a concept if not already present.
+ *
+ * This utility function ensures that a concept has its type information loaded and attached.
+ * Every concept has a `typeId` that references another concept representing its type
+ * (e.g., a person concept might have typeId=1 which points to a "Person" type concept).
+ *
+ * **Process:**
+ * 1. Checks if concept.type is already set (if yes, does nothing)
+ * 2. Attempts to fetch type concept from local cache (ConceptsData)
+ * 3. If not in cache and typeId is valid: fetches from backend API
+ * 4. Attaches the type concept to concept.type property
+ * 5. Routes through service worker if enabled
+ *
+ * **Type Concept:**
+ * A type concept is a special concept that represents a classification or category.
+ * For example: "Person", "Document", "Organization" are type concepts.
+ *
+ * @param concept - The concept object to which type information should be added.
+ *                 The concept must have a valid `typeId` property.
+ *
+ * @returns Promise that resolves when type information has been attached (or confirmed present)
+ *
+ * @example
+ * const concept = await GetTheConcept(12345);
+ * console.log(concept.type); // might be null
+ *
+ * await AddTypeConcept(concept);
+ * console.log(concept.type?.characterValue); // "Person"
+ *
+ * @example
+ * // Ensure multiple concepts have their types loaded
+ * const concepts = await GetConceptBulk([1, 2, 3, 4, 5]);
+ * await Promise.all(concepts.map(c => AddTypeConcept(c)));
+ * // All concepts now have their type information
+ *
+ * @see {@link GetTheConcept} which automatically calls this function
+ */
 export declare function AddTypeConcept(concept: Concept): Promise<Concept | undefined>;

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

@@ -1,2 +1,41 @@
 import { Concept } from "../../DataStructures/Concept";
+/**
+ * Converts a local concept (LConcept) to a standard Concept format.
+ *
+ * This function is part of the local/server concept conversion system. Currently, it
+ * performs a passthrough as LConcept and Concept share the same structure. This function
+ * exists for:
+ * - API consistency and symmetry with convertFromConceptToLConcept
+ * - Future extensibility if conversion logic is needed
+ * - Type clarity in code (explicit conversion intent)
+ *
+ * **LConcept vs Concept:**
+ * - LConcept: Local-only concepts stored in IndexedDB (negative IDs)
+ * - Concept: Server-synced concepts (positive IDs)
+ * - Both use the same Concept class structure
+ *
+ * **When to Use:**
+ * - Preparing local concepts for backend sync
+ * - Converting local concepts to server format
+ * - Type-safe conversion in TypeScript
+ * - Maintaining code clarity and intent
+ *
+ * @param lconcept - The local concept to convert
+ *
+ * @returns The concept in standard Concept format (currently identical to input)
+ *
+ * @example
+ * // Convert local concept before syncing
+ * const localConcept = await CreateTheConceptLocal('Draft', 'the_note', 101, 1, 3, 2);
+ * const serverConcept = ConvertFromLConceptToConcept(localConcept);
+ * // Now ready for backend sync
+ *
+ * @example
+ * // Type-safe conversion
+ * const lconcepts = await GetAllLocalConcepts();
+ * const concepts = lconcepts.map(lc => ConvertFromLConceptToConcept(lc));
+ *
+ * @see {@link convertFromConceptToLConcept} for the reverse conversion
+ * @see {@link CreateTheConceptLocal} for creating local concepts
+ */
 export declare function ConvertFromLConceptToConcept(lconcept: Concept): Concept;

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

@@ -1,2 +1,47 @@
 import { Connection } from "../../DataStructures/Connection";
+/**
+ * Converts a local connection (LConnection) to a standard Connection format.
+ *
+ * This function extracts the essential properties from a local connection and creates
+ * a new Connection object. It's part of the local/server conversion system used when
+ * preparing local connections for backend sync.
+ *
+ * **Properties Transferred:**
+ * - id: Connection identifier
+ * - ofTheConceptId: Source concept ID
+ * - toTheConceptId: Target concept ID
+ * - typeId: Connection type ID
+ * - orderId: Order for sorting connections
+ *
+ * **LConnection vs Connection:**
+ * - LConnection: Local-only connections stored in IndexedDB (negative IDs)
+ * - Connection: Server-synced connections (positive IDs)
+ * - Both use the same Connection class structure
+ *
+ * **Use Cases:**
+ * - Preparing local connections for backend sync
+ * - Converting local data to server format
+ * - Data export and serialization
+ * - Maintaining consistency across local and server data
+ *
+ * @param lconnection - The local connection to convert
+ *
+ * @returns A new Connection object with properties copied from the local connection
+ *
+ * @example
+ * // Convert local connection before syncing
+ * const localConn = await CreateTheConnectionLocal(fromId, toId, typeId, 1);
+ * const serverConn = ConvertFromLConnectionToConnection(localConn);
+ * // Now ready for backend sync
+ *
+ * @example
+ * // Batch conversion
+ * const localConnections = await GetAllLocalConnections();
+ * const serverConnections = localConnections.map(lc =>
+ *   ConvertFromLConnectionToConnection(lc)
+ * );
+ *
+ * @see {@link CreateTheConnectionLocal} for creating local connections
+ * @see {@link ConvertFromLConceptToConcept} for concept conversion
+ */
 export declare function ConvertFromLConnectionToConnection(lconnection: Connection): Connection;

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

@@ -1,3 +1,44 @@
 import { Concept } from "../../app";
 import { InnerActions } from "../../Constants/general.const";
+/**
+ * Creates a named connection between two concepts with optional bidirectional linking.
+ *
+ * **Complex Naming Logic**:
+ * - Forward connection type: "{ofType}_s_{linker}_s" (e.g., "person_s_knows_s")
+ * - Backward connection type: "{toType}_s_{linker}_by" (e.g., "person_s_knows_by")
+ * - Uses type.characterValue from concepts to build meaningful connection names
+ *
+ * **Bidirectional Mode (both=true)**:
+ * - Creates two connections: A→B and B→A
+ * - Forward: ofTheConcept → toTheConcept with "{ofType}_s_{linker}_s"
+ * - Backward: toTheConcept → ofTheConcept with "{toType}_s_{linker}_by"
+ *
+ * @param ofTheConcept - Source concept (connection starts here)
+ * @param toTheConcept - Target concept (connection points here)
+ * @param linker - Relationship name (e.g., "knows", "works_at", "has")
+ * @param both - If true, creates bidirectional connection (both A→B and B→A)
+ * @param actions - Action tracking for batch operations
+ * @returns The forward connection object
+ * @throws Error if connection creation fails
+ *
+ * @example
+ * // Create unidirectional "Alice knows Bob"
+ * const conn = await CreateConnectionBetweenTwoConceptsLocal(
+ *   aliceConcept,
+ *   bobConcept,
+ *   "knows",
+ *   false
+ * );
+ * // Creates: person_s_knows_s connection from Alice to Bob
+ *
+ * @example
+ * // Create bidirectional "Alice friends Bob" (both directions)
+ * await CreateConnectionBetweenTwoConceptsLocal(
+ *   aliceConcept,
+ *   bobConcept,
+ *   "friends",
+ *   true
+ * );
+ * // Creates: person_s_friends_s (Alice→Bob) AND person_s_friends_by (Bob→Alice)
+ */
 export declare function CreateConnectionBetweenTwoConceptsLocal(ofTheConcept: Concept, toTheConcept: Concept, linker: string, both?: boolean, actions?: InnerActions): Promise<any>;

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

@@ -1,2 +1,46 @@
 import { Concept } from "../../DataStructures/Concept";
+/**
+ * Creates a default empty local concept with all properties set to zero/default values.
+ *
+ * This utility function generates a blank Concept object that can be used as a placeholder
+ * or default return value when a concept is not found. All IDs and values are set to 0
+ * or empty defaults.
+ *
+ * **Default Values:**
+ * - id: 0 (indicates empty/not found)
+ * - userId: 0
+ * - typeId: 0
+ * - categoryId: 0
+ * - referentId: 0
+ * - characterValue: "0"
+ * - accessId: 0
+ * - isNew: false
+ * - entryTimeStamp: current date
+ * - updatedTimeStamp: current date
+ * - typeCharacter: "0"
+ *
+ * **Use Cases:**
+ * - Default return value when concept not found
+ * - Placeholder for conditional logic
+ * - Initial state before loading data
+ * - Template for creating new concepts
+ *
+ * @returns A Concept object with all properties set to default/zero values
+ *
+ * @example
+ * // Use as default return
+ * let concept = await GetTheConceptLocal(id);
+ * if (concept.id === 0) {
+ *   concept = CreateDefaultLConcept();
+ * }
+ *
+ * @example
+ * // Check if concept is valid
+ * const concept = CreateDefaultLConcept();
+ * console.log(concept.id); // 0
+ * console.log(concept.characterValue); // "0"
+ *
+ * @see {@link CreateTheConceptLocal} for creating actual local concepts
+ * @see {@link GetTheConceptLocal} for retrieving local concepts
+ */
 export declare function CreateDefaultLConcept(): Concept;

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

@@ -1,5 +1,10 @@
 /**
- * This will create a binary tree of local concepts that is saved from the indexdb.
+ * Loads local concepts from IndexedDB into memory-based binary tree for fast lookup.
+ *
+ * Retrieves all stored local concepts from IndexedDB and adds them to LocalConceptsData
+ * in-memory structure. Sets flags indicating local data is ready for use.
+ *
+ * @throws Error if IndexedDB read fails (retries after 2s delay)
  */
 export default function CreateLocalBinaryTreeFromIndexDb(): Promise<void>;
 /**

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

@@ -1 +1,9 @@
+/**
+ * Builds a binary search tree indexed by typeId for fast type-based concept lookup.
+ *
+ * Loads all local concepts from IndexedDB and organizes them into a binary tree
+ * structure where each node is keyed by typeId. Enables O(log n) lookups by type.
+ *
+ * @throws Error if IndexedDB read or tree construction fails
+ */
 export declare function CreateLocalBinaryTypeTreeFromData(): Promise<void>;

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

@@ -1 +1,9 @@
+/**
+ * Builds a binary search tree indexed by characterValue for fast text-based concept lookup.
+ *
+ * Loads all local concepts from IndexedDB and organizes them into a binary tree
+ * structure where each node is keyed by characterValue. Enables O(log n) lookups by text.
+ *
+ * @throws Error if IndexedDB read or tree construction fails
+ */
 export declare function CreateLocalCharacterBinaryTreeFromData(): Promise<void>;

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

@@ -1,14 +1,104 @@
 import { InnerActions } from "../../app";
 /**
- * This function converts a json data to concept connection and also preserves its relation.
- * @param json The json data that needs to be converted to the concept connection system
- * @param ofTheConceptId If in case that this composition is part of other composition then this must be the connecting concept.
- * @param ofTheConceptUserId If in case that this composition is part of other composition then this must be the user Id of the  connecting concept.
- * @param mainKey If in case that this composition is part of other composition then this must be the main composition
- * @param userId The user Id of the user creating the composition.
- * @param accessId The accessId of the user creating the composition.
- * @param sessionInformationId Session of the user.
- * @param automaticSync for future use.
- * @returns the main concept of this composition.
+ * Converts a JSON object into a local composition structure with concepts and connections.
+ *
+ * This powerful function recursively transforms any JSON object into the concept-connection
+ * system, creating local concepts for each key-value pair and establishing connections
+ * between them to preserve the hierarchical structure.
+ *
+ * **JSON to Composition Conversion:**
+ * - JSON keys become type concepts (e.g., "name", "email")
+ * - JSON string/number values become instance concepts
+ * - Nested objects/arrays create sub-compositions
+ * - Connections preserve parent-child relationships
+ * - All data stored locally (IndexedDB) for offline use
+ *
+ * **Recursive Process:**
+ * 1. Iterates through each key in JSON object
+ * 2. For nested objects/arrays: Creates composition concept + recurse
+ * 3. For primitive values: Creates instance concept
+ * 4. Creates connections from parent to child concepts
+ * 5. Returns the main/root concept
+ *
+ * **Example Transformation:**
+ * ```javascript
+ * Input JSON:
+ * {
+ *   name: "Alice",
+ *   email: "alice@example.com",
+ *   address: {
+ *     city: "NYC",
+ *     zip: "10001"
+ *   }
+ * }
+ *
+ * Creates:
+ * - Concept: "name" (type) → "Alice" (instance)
+ * - Concept: "email" (type) → "alice@example.com" (instance)
+ * - Concept: "address" (composition concept)
+ *   - Concept: "city" → "NYC"
+ *   - Concept: "zip" → "10001"
+ * - Connections linking all concepts in hierarchy
+ * ```
+ *
+ * @param json - The JSON object/array to convert to composition structure.
+ *              Can be any depth of nesting.
+ * @param ofTheConceptId - Parent concept ID if this is a sub-composition.
+ *                        Null for root composition. Used for connecting to parent.
+ * @param ofTheConceptUserId - User ID of the parent concept.
+ *                            Used for ownership tracking in nested structures.
+ * @param mainKey - The main composition ID (root concept ID).
+ *               Used as typeId for internal connections. Null for root.
+ * @param userId - User ID of the creator. Defaults to 999 (system).
+ * @param accessId - Access control level. Defaults to 999 (system).
+ * @param sessionInformationId - Session ID. Defaults to 999 (system).
+ * @param automaticSync - Reserved for future automatic sync feature.
+ *                       Currently not fully implemented.
+ * @param actions - Action tracking object that accumulates all created concepts
+ *                 and connections for batch operations. Defaults to empty arrays.
+ *
+ * @returns Promise resolving to the main/root Concept of the composition
+ *
+ * @example
+ * // Simple flat object
+ * const json = { name: "Alice", age: 30 };
+ * const mainConcept = await CreateTheCompositionLocal(
+ *   json,
+ *   null,  // No parent
+ *   null,
+ *   null,
+ *   101,   // userId
+ *   2,     // accessId
+ *   999
+ * );
+ * console.log(mainConcept.id); // Root concept ID
+ *
+ * @example
+ * // Nested object with action tracking
+ * const actions = { concepts: [], connections: [] };
+ * const userData = {
+ *   profile: {
+ *     firstName: "Alice",
+ *     lastName: "Smith"
+ *   },
+ *   settings: {
+ *     theme: "dark"
+ *   }
+ * };
+ * const root = await CreateTheCompositionLocal(
+ *   userData,
+ *   null, null, null,
+ *   101, 2, 999,
+ *   false,
+ *   actions
+ * );
+ * console.log(actions.concepts.length); // Total concepts created
+ * console.log(actions.connections.length); // Total connections created
+ *
+ * @throws Logs errors but does not throw. Returns created concepts even on partial failure.
+ *
+ * @see {@link MakeTheInstanceConceptLocal} for individual concept creation
+ * @see {@link CreateTheConnectionLocal} for connection creation
+ * @see {@link GetCompositionLocal} for retrieving created compositions
  */
 export declare function CreateTheCompositionLocal(json: any, ofTheConceptId?: number | null, ofTheConceptUserId?: number | null, mainKey?: number | null, userId?: number | null, accessId?: number | null, sessionInformationId?: number | null, automaticSync?: boolean, actions?: InnerActions): Promise<any>;

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

@@ -1,22 +1,84 @@
 import { InnerActions } from "../../app";
 /**
- * This function creates the concept in the local system (Local memory and IndexDb) but not in the backend database
- * To create this concept in the backend database you need to sync the local data to the backend by LocalSyncData class.
- *
- * This function creates a id and ghost id which are equal to each other.
- * These id and ghostId are negative which means that they are virtual concepts. After these concepts have been synced with the backend
- * they are converted to real id. After returning from the backend the id changes to positive(+) and real id while the ghostId remains the same
- *
- * The system then saves this relation between -ve id and real id in the backend server and also in the local memory.
- *
- * @param referent This is the string that is the actual value of the concept.
- * @param typecharacter The string that defines the type of the concept.
- * @param userId This is the userId of the creator.
- * @param categoryId This is the category Id of the concept.
- * @param typeId This is the type Id of the concept that relates to the typecharacter passed above.
- * @param accessId This is the accessId of the concept(most probably is the accessId of the user)
- * @param isComposition This is set in the case that the composition needs to be created.
- * @param referentId if this concept refers to any other concept then this needs to be passed.
- * @returns
+ * Creates a concept in local storage (IndexedDB) without syncing to the backend.
+ *
+ * This is the primary function for creating offline-first concepts. The concept is stored
+ * locally in IndexedDB and memory, but NOT immediately sent to the backend. Sync happens
+ * later via the LocalSyncData class.
+ *
+ * **Virtual ID System:**
+ * - Generates a negative ID (e.g., -12345) to indicate local/virtual status
+ * - id and ghostId are initially equal and both negative
+ * - After backend sync: id becomes positive (real backend ID)
+ * - ghostId remains negative (preserves original local ID)
+ * - Mapping is stored in LocalGhostIdTree for future lookups
+ *
+ * **Sync Process:**
+ * 1. Create locally with negative ID
+ * 2. Use LocalSyncData to sync to backend
+ * 3. Backend returns positive ID
+ * 4. Update local concept with positive ID
+ * 5. Preserve negative ID as ghostId
+ * 6. Store mapping in LocalGhostIdTree
+ *
+ * **Special Case:**
+ * If referent is "the", returns a special concept with id=1 (system concept).
+ *
+ * @param referent - The character value (text/name) of the concept.
+ *                  This is the human-readable content (e.g., "Draft Note", "Local Task")
+ * @param typecharacter - The type name as a string (e.g., "the_note", "the_person").
+ *                       Used for display and classification.
+ * @param userId - The ID of the user creating this concept. Used for ownership.
+ * @param categoryId - The category classification ID for further classification within type.
+ * @param typeId - The type classification ID. Must correspond to typecharacter.
+ * @param accessId - Access control level (e.g., 1=Public, 2=Private).
+ *                  Usually matches the user's access level.
+ * @param isComposition - Set to true if this concept represents a composition root.
+ *                       Defaults to false.
+ * @param referentId - Optional reference to another concept ID. Used for instance relationships.
+ *                    Defaults to 0 (no reference).
+ * @param actions - Action tracking object that accumulates created concepts and connections.
+ *                 Used for batch operations and rollback. Defaults to empty arrays.
+ *
+ * @returns Promise resolving to the created Concept object with negative ID
+ *
+ * @example
+ * // Create a local draft note
+ * const draftNote = await CreateTheConceptLocal(
+ *   "Meeting Notes - Draft",  // referent
+ *   "the_note",               // typecharacter
+ *   101,                      // userId
+ *   1,                        // categoryId
+ *   3,                        // typeId
+ *   2                         // accessId (Private)
+ * );
+ * console.log(draftNote.id); // -12345 (negative = local)
+ * console.log(draftNote.ghostId); // -12345 (same initially)
+ *
+ * @example
+ * // Create with composition flag
+ * const project = await CreateTheConceptLocal(
+ *   "Local Project",
+ *   "the_project",
+ *   101,
+ *   1,
+ *   5,
+ *   2,
+ *   true  // isComposition = true
+ * );
+ *
+ * @example
+ * // Track actions for batch operations
+ * const actions = { concepts: [], connections: [] };
+ * const concept1 = await CreateTheConceptLocal("Item 1", "the_item", 101, 1, 4, 2, false, 0, actions);
+ * const concept2 = await CreateTheConceptLocal("Item 2", "the_item", 101, 1, 4, 2, false, 0, actions);
+ * console.log(actions.concepts.length); // 2
+ * // All created concepts tracked in actions array
+ *
+ * @throws Logs errors and re-throws for handling by caller
+ *
+ * @see {@link GetTheConceptLocal} for retrieving local concepts
+ * @see {@link LocalSyncData} for syncing local concepts to backend
+ * @see {@link CreateTheConcept} for creating server-synced concepts directly
  */
 export default function CreateTheConceptLocal(referent: string, typecharacter: string, userId: number, categoryId: number, typeId: number, accessId: number, isComposition?: boolean, referentId?: number | null, actions?: InnerActions): Promise<any>;