mftsccs-browser 2.2.20-beta → 2.2.22-beta

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

@@ -1,16 +1,140 @@
 import { Concept, InnerActions } from "../../app";
 /**
- * This function creates a connection for the concept connection system. This connection will only be created in real sense
- * once the data is synced using LocalSyncData.SyncDataOnline()
- * Here id and ghostId are created which are negative(these are virtual ids). After they are synced then they become real ids
- * The real ids are then associated with these ghost ids in node server (backend) and also in the local memory.
- * @param ofTheConceptId Of the concept Id for the connection
- * @param toTheConceptId To the concept Id for the connection
- * @param typeId Type of the connection, should be the composition id for internal connection and type concept in case
- * of external connection.
- * @param orderId current context is that for internal connections the order id is less than 3 and for external connections greater than 999
- * @param typeString this is the typeString in the case of external connections.
- * @returns a connection that is created and stored in the local system.
+ * Creates a connection in local storage (IndexedDB) without syncing to the backend.
+ *
+ * This is the primary function for creating offline-first connections. The connection is stored
+ * locally in IndexedDB and memory, but NOT immediately sent to the backend. Sync happens
+ * later via LocalSyncData.SyncDataOnline().
+ *
+ * **Virtual ID System:**
+ * - Generates a negative ID (e.g., -67890) 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 backend and LocalGhostIdTree
+ *
+ * **Connection Types:**
+ * - **Internal Connections**: orderId < 3 (within a composition)
+ *   - typeId is typically the composition ID
+ * - **External Connections**: orderId >= 999 (between different entities)
+ *   - typeId is a type concept ID
+ *   - typeString provides human-readable type name
+ *
+ * **Self-Connection Prevention:**
+ * If ofTheConceptId equals toTheConceptId, returns an empty connection (prevents loops).
+ *
+ * @param ofTheConceptId - Source concept ID (FROM). The connection originates here.
+ *                        Can be negative (local) or positive (server) ID.
+ * @param toTheConceptId - Target concept ID (TO). The connection points here.
+ *                        Can be negative (local) or positive (server) ID.
+ * @param typeId - The type classification for this connection.
+ *                - For internal connections: composition ID
+ *                - For external connections: type concept ID
+ * @param orderId - Order identifier for sorting multiple connections.
+ *                 - < 3: Internal connection
+ *                 - >= 999: External connection
+ *                 - Defaults to 1
+ * @param typeString - Human-readable type name (e.g., "the_person_email").
+ *                    Used primarily for external connections. Defaults to empty string.
+ * @param userId - The ID of the user creating this connection. Defaults to 999 (system).
+ * @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 Connection object with negative ID.
+ *         Returns empty connection (all IDs = 0) if self-connection attempted.
+ *
+ * @example
+ * // Create internal connection (within composition)
+ * const internalConn = await CreateTheConnectionLocal(
+ *   projectId,    // -12345
+ *   taskId,       // -67890
+ *   compositionId,// -11111
+ *   1,            // orderId < 3 = internal
+ *   "",           // no typeString needed
+ *   101           // userId
+ * );
+ * console.log(internalConn.id); // -99999 (negative = local)
+ *
+ * @example
+ * // Create external connection (between entities)
+ * const externalConn = await CreateTheConnectionLocal(
+ *   personId,           // 123
+ *   emailId,            // 456
+ *   emailTypeId,        // 789
+ *   1000,               // orderId >= 999 = external
+ *   "the_person_email", // typeString for external
+ *   101
+ * );
+ *
+ * @example
+ * // Track actions for batch operations
+ * const actions = { concepts: [], connections: [] };
+ * await CreateTheConnectionLocal(id1, id2, typeId, 1, "", 101, actions);
+ * await CreateTheConnectionLocal(id2, id3, typeId, 1, "", 101, actions);
+ * console.log(actions.connections.length); // 2
+ * // All created connections tracked for potential rollback
+ *
+ * @example
+ * // Self-connection prevention
+ * const selfConn = await CreateTheConnectionLocal(123, 123, 5, 1);
+ * console.log(selfConn.id); // 0 (empty connection, prevented)
+ *
+ * @throws Logs errors and re-throws for handling by caller
+ *
+ * @see {@link CreateConnection} for simplified connection creation with concepts
+ * @see {@link LocalSyncData} for syncing local connections to backend
+ * @see {@link createTheConnection} for creating server-synced connections directly
  */
 export declare function CreateTheConnectionLocal(ofTheConceptId: number, toTheConceptId: number, typeId: number, orderId?: number, typeString?: string, userId?: number, actions?: InnerActions): Promise<any>;
+/**
+ * Simplified connection creator that accepts concepts and a type string.
+ *
+ * This is a convenience wrapper around CreateTheConnectionLocal that:
+ * 1. Accepts Concept objects instead of IDs
+ * 2. Creates the connection type concept if it doesn't exist
+ * 3. Extracts necessary IDs automatically
+ * 4. Sets appropriate defaults for local connections
+ *
+ * **Advantages:**
+ * - More intuitive API (pass concepts, not IDs)
+ * - Automatic type concept creation/retrieval
+ * - Less boilerplate code
+ * - Type-safe with TypeScript
+ *
+ * **Process:**
+ * 1. Creates/retrieves type concept from connectionTypeString
+ * 2. Extracts userId from source concept
+ * 3. Calls CreateTheConnectionLocal with extracted IDs
+ * 4. Returns the created connection
+ *
+ * @param ofTheConcept - The source Concept object (FROM)
+ * @param toTheConcept - The target Concept object (TO)
+ * @param connectionTypeString - Type name as string (e.g., "the_person_email").
+ *                              A type concept will be created if it doesn't exist.
+ * @param actions - Action tracking object for batch operations. Defaults to empty arrays.
+ *
+ * @returns Promise resolving to the created Connection object
+ *
+ * @example
+ * // Simple usage with concepts
+ * const person = await CreateTheConceptLocal('Alice', 'the_person', 101, 1, 1, 2);
+ * const email = await CreateTheConceptLocal('alice@example.com', 'the_email', 101, 1, 2, 2);
+ *
+ * const connection = await CreateConnection(person, email, 'the_person_email');
+ * // Connection created with:
+ * // - ofTheConceptId: person.id
+ * // - toTheConceptId: email.id
+ * // - typeId: auto-generated from 'the_person_email'
+ * // - orderId: 1000 (external connection)
+ *
+ * @example
+ * // With action tracking
+ * const actions = { concepts: [], connections: [] };
+ * const conn1 = await CreateConnection(concept1, concept2, 'links_to', actions);
+ * const conn2 = await CreateConnection(concept2, concept3, 'links_to', actions);
+ * console.log(actions.connections.length); // 2
+ *
+ * @see {@link CreateTheConnectionLocal} for the underlying implementation
+ * @see {@link MakeTheTypeConceptLocal} for type concept creation
+ */
 export declare function CreateConnection(ofTheConcept: Concept, toTheConcept: Concept, connectionTypeString: string, actions?: InnerActions): Promise<any>;

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

@@ -1 +1,47 @@
+/**
+ * Deletes a concept from local storage (IndexedDB).
+ *
+ * This function removes a concept from LocalConceptsData, effectively deleting it
+ * from the local IndexedDB cache. This is a local-only delete - it does NOT sync
+ * the deletion to the backend.
+ *
+ * **Important Notes:**
+ * - Only deletes from local storage (IndexedDB)
+ * - Does NOT delete from backend server
+ * - Does NOT automatically delete related connections
+ * - For full deletion including backend, use DeleteConceptById
+ * - Works with both negative (local) and positive (synced) IDs
+ *
+ * **Use Cases:**
+ * - Cleaning up local draft concepts
+ * - Removing concepts before they're synced
+ * - Local cache management
+ * - Testing and development
+ *
+ * **Process:**
+ * 1. Fetches the concept via GetTheConceptLocal
+ * 2. Removes it from LocalConceptsData
+ * 3. Updates IndexedDB
+ *
+ * @param id - The concept ID to delete (negative for local, positive for synced)
+ *
+ * @returns Promise that resolves when deletion is complete
+ *
+ * @example
+ * // Delete a local concept
+ * await DeleteConceptLocal(-12345);
+ * console.log("Local concept deleted");
+ *
+ * @example
+ * // Delete after checking existence
+ * const concept = await GetTheConceptLocal(-67890);
+ * if (concept.id !== 0) {
+ *   await DeleteConceptLocal(concept.id);
+ *   console.log("Deleted:", concept.characterValue);
+ * }
+ *
+ * @see {@link DeleteConceptById} for full deletion including backend
+ * @see {@link GetTheConceptLocal} for retrieving concepts before deletion
+ * @see {@link LocalConceptsData.RemoveConcept} for the underlying removal operation
+ */
 export declare function DeleteConceptLocal(id: number): Promise<any>;

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

@@ -1,14 +1,37 @@
 /**
- * This function returns the list of composition which have the type @param compositionName
- * @param compositionName The type of the composition to pull
- * @param userId User Id of the user trying to pull the list
- * @returns list of compositions.
+ * Retrieves all compositions of a specific type from local storage.
+ *
+ * **Process Flow**:
+ * 1. Finds the type concept by compositionName (e.g., "the_project")
+ * 2. Queries all concepts with that typeId belonging to the user
+ * 3. Fetches full composition for each concept
+ * 4. Returns array of complete compositions
+ *
+ * @param compositionName - The type name of compositions to retrieve (e.g., "the_project", "the_person")
+ * @param userId - User ID to filter compositions by ownership
+ * @returns Array of composition objects (empty array if type not found)
+ * @throws Error if lookup or composition fetching fails
+ *
+ * @example
+ * // Get all local projects for a user
+ * const projects = await GetCompositionListLocal("the_project", 101);
+ * // Returns: [{id: -1, data: {...}}, {id: -2, data: {...}}]
  */
 export declare function GetCompositionListLocal(compositionName: string, userId: number): Promise<any>;
 /**
- * This function returns the list of composition with data - id format which have the type @param compositionName
- * @param compositionName The type of the composition to pull
- * @param userId User Id of the user trying to pull the list
- * @returns list of compositions with data - id format.
+ * Retrieves all compositions of a specific type with DATAID format (includes concept ID).
+ *
+ * Same as GetCompositionListLocal but returns compositions in data-id wrapper format,
+ * which includes both the composition data and its concept ID for easier reference.
+ *
+ * @param compositionName - The type name of compositions to retrieve
+ * @param userId - User ID to filter compositions by ownership
+ * @returns Array of composition objects in {id, data} format
+ * @throws Error if lookup or composition fetching fails
+ *
+ * @example
+ * // Get all local projects with IDs
+ * const projects = await GetCompositionListLocalWithId("the_project", 101);
+ * // Returns: [{id: -1, data: {the_name: "Project A"}}, {id: -2, data: {...}}]
  */
 export declare function GetCompositionListLocalWithId(compositionName: string, userId: number): Promise<any>;

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

@@ -1,2 +1,97 @@
+/**
+ * Retrieves a complete composition structure from local storage (IndexedDB).
+ *
+ * This function fetches a composition using local-only data, building a hierarchical
+ * structure from local connections and concepts. If the concept has been synced to the
+ * backend, it can automatically fall back to fetching from the server.
+ *
+ * **Process:**
+ * 1. Fetches all local connections for the composition
+ * 2. Identifies all connected concept IDs
+ * 3. Retrieves the main concept from LocalConceptsData
+ * 4. If concept not found locally, checks if it's been synced (TranslateLocalToReal)
+ * 5. Falls back to server GetComposition if concept is synced
+ * 6. Recursively builds composition tree from local data
+ * 7. Organizes output by concept type
+ *
+ * **Local vs Server:**
+ * - Prioritizes local data (IndexedDB)
+ * - Automatic fallback to server if concept synced
+ * - Uses LocalConnectionData for connections
+ * - Uses LocalConceptsData for concepts
+ *
+ * **Output Format (JUSTDATA):**
+ * Returns an object keyed by the main concept's type:
+ * ```
+ * {
+ *   "Person": {
+ *     name: "Alice",
+ *     email: {...},
+ *     projects: {...}
+ *   }
+ * }
+ * ```
+ *
+ * @param id - The concept ID (can be negative for local or positive for synced)
+ *
+ * @returns Promise resolving to composition data organized by concept type
+ *
+ * @example
+ * // Get local composition
+ * const localComp = await GetCompositionLocal(-12345);
+ * console.log(localComp["Project"]);
+ * // Returns all data connected to this local project
+ *
+ * @example
+ * // Get synced concept (automatically falls back to server)
+ * const syncedComp = await GetCompositionLocal(-67890);
+ * // If concept synced to server, fetches from there
+ *
+ * @throws Re-throws errors for handling by caller
+ *
+ * @see {@link GetCompositionLocalWithId} for composition with ID and data wrapper
+ * @see {@link GetComposition} for server-only composition retrieval
+ * @see {@link recursiveFetchLocal} for the recursive building logic
+ */
 export declare function GetCompositionLocal(id: number): Promise<any>;
+/**
+ * Retrieves a local composition with ID and data wrapper (DATAID format).
+ *
+ * This is a variant of GetCompositionLocal that returns the composition data
+ * wrapped in an object that includes both the data and the concept ID. This format
+ * is useful for tracking which concept the data belongs to.
+ *
+ * **Output Format (DATAID):**
+ * ```
+ * {
+ *   data: {
+ *     "Person": {
+ *       name: "Alice",
+ *       email: {...}
+ *     }
+ *   },
+ *   id: 12345
+ * }
+ * ```
+ *
+ * **Differences from GetCompositionLocal:**
+ * - Returns { data, id } wrapper object
+ * - Same local data retrieval process
+ * - Same recursive building logic
+ * - No automatic server fallback
+ *
+ * @param id - The concept ID (negative for local, positive for synced)
+ *
+ * @returns Promise resolving to object with { data, id } structure
+ *
+ * @example
+ * const result = await GetCompositionLocalWithId(-12345);
+ * console.log(result.id);           // -12345
+ * console.log(result.data.Project); // Composition data
+ *
+ * @throws Re-throws errors for handling by caller
+ *
+ * @see {@link GetCompositionLocal} for standard format without ID wrapper
+ * @see {@link GetCompositionWithId} for server version
+ */
 export declare function GetCompositionLocalWithId(id: number): Promise<any>;

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

@@ -1,10 +1,56 @@
 import { Concept } from "../../app";
+/**
+ * Retrieves a local concept by character value with typeId=51 (standard type).
+ *
+ * Simple lookup in LocalConceptsData for concepts matching the character value
+ * and having typeId of 51.
+ *
+ * @param characterValue - The character value to search for
+ * @returns Concept matching the character and type, or empty concept if not found
+ */
 export default function GetConceptByCharacterLocal(characterValue: string): Promise<Concept>;
 /**
+ * Retrieves a local concept by character value, handling hierarchical type names.
  *
- * @param character the character value of the concept we want to find in our local system.
- * @returns LConcept which will be the associated concept with the character Value.
+ * **Complex Logic**: For compound names (e.g., "the_person_email"):
+ * 1. Splits string by underscore
+ * 2. Recursively processes first part to get category ID
+ * 3. Searches using character value and derived category
+ * 4. Falls back to simple character search for single words
+ *
+ * **Special Case**: Returns concept with id=1 for character value "the".
+ *
+ * @param character - The character value to find (e.g., "the_status", "the_person_email")
+ * @returns Concept associated with the character value
+ *
+ * @example
+ * const concept = await GetConceptByCharacterAndCategoryLocal("the_person_email");
+ * // Splits into "the_person" (category) and searches with that context
  */
 export declare function GetConceptByCharacterAndCategoryLocal(character: string): Promise<any>;
+/**
+ * Retrieves a concept by character value and category ID from local memory.
+ *
+ * Direct lookup in LocalConceptsData without server fallback.
+ *
+ * @param value - The character value to search for
+ * @param categoryId - The category ID to filter by
+ * @returns Concept matching the character and category, or empty concept if not found
+ */
 export declare function GetConceptByCategoryAndCharacterLocalMemory(value: string, categoryId: number): Promise<Concept>;
+/**
+ * Retrieves a concept by character value with automatic server fallback.
+ *
+ * **Complex Logic**:
+ * 1. First checks LocalConceptsData for existing concept
+ * 2. If not found (id==0 or null), fetches from server via GetLocalConceptByCharacterValue
+ * 3. After server fetch, rechecks LocalConceptsData (now populated)
+ * 4. Returns the concept or throws error
+ *
+ * Use this when you need guaranteed concept retrieval with server sync.
+ *
+ * @param characterValue - The character value to search for
+ * @returns Concept from local storage, fetching from server if needed
+ * @throws Error if server fetch fails
+ */
 export declare function GetConceptByCharacterLocalFull(characterValue: string): Promise<Concept>;

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

@@ -1,2 +1,19 @@
 import { Connection } from "../../app";
+/**
+ * Retrieves all connections originating from a specific concept with a given type.
+ *
+ * Searches local storage (IndexedDB) for connections where:
+ * - ofTheConceptId matches the provided concept ID
+ * - typeId matches the provided type
+ *
+ * @param ofTheConcept - The source concept ID (connections originating from this concept)
+ * @param typeId - The connection type ID to filter by
+ * @param userId - User ID (currently not used in filtering)
+ * @returns Array of Connection objects matching the criteria (empty array if none found)
+ * @throws Error if local storage query fails
+ *
+ * @example
+ * // Get all "has_property" connections from a person concept
+ * const connections = await GetConnectionOfTheConceptLocal(personId, 42, userId);
+ */
 export declare function GetConnectionOfTheConceptLocal(ofTheConcept: number, typeId: number, userId: number): Promise<Connection[]>;

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

@@ -1 +1,21 @@
+/**
+ * Retrieves all related compositions from local storage by relation name.
+ *
+ * **Process Flow (Complex Logic)**:
+ * 1. Converts relation string to type concept (e.g., "the_email" → type concept)
+ * 2. Finds all connections from source concept with that relation type
+ * 3. For each connection, retrieves the target composition
+ * 4. Returns array of all related compositions
+ *
+ * @param id - The source concept ID to get relations from
+ * @param relation - The relation name (e.g., "the_email", "the_address")
+ * @param userId - User ID for permissions
+ * @returns Array of composition objects representing related entities
+ * @throws Error if relation lookup or composition retrieval fails
+ *
+ * @example
+ * // Get all email addresses related to a person
+ * const emails = await GetRelationLocal(personId, "the_email", userId);
+ * // Returns: [emailComposition1, emailComposition2, ...]
+ */
 export declare function GetRelationLocal(id: number, relation: string, userId: number): Promise<any>;

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

@@ -1,9 +1,63 @@
 /**
- * This function converts any local/ virtual or real concept id to a LConcept.
- * In case that the id is virtual then it tries to find it from the local memory. This will return -ve id.
- * In case that the virtual id has already been synced to the backend then it gets this from the relational binary tree(LocalGhostIdTree). This will return +ve id.
- * In case that we pass real id then this will return real concept but formatted in LConcept form. This might have undefined ghostId.
- * @param id the id that you want to find out the concept of. This could be a negative (virtual id ) or a real concept id.
- * @returns LConcept with either (-ve or +ve id)
+ * Retrieves a concept by ID with support for both local (virtual) and server concepts.
+ *
+ * This is the primary function for fetching concepts in offline/local mode. It intelligently
+ * handles three types of concept IDs and retrieves from appropriate sources:
+ *
+ * **ID Types Handled:**
+ * 1. **Negative IDs (Virtual/Local)**: Concepts created locally not yet synced
+ *    - Stored in LocalConceptsData (IndexedDB)
+ *    - Return negative IDs
+ *
+ * 2. **Synced Virtual IDs**: Originally local concepts now synced to backend
+ *    - Looked up via LocalGhostIdTree (maps negative to positive IDs)
+ *    - Returns positive (real) ID with ghostId reference
+ *
+ * 3. **Positive IDs (Server)**: Real backend concepts
+ *    - Fetched via GetTheConcept from backend
+ *    - Converted to LConcept format
+ *    - May have undefined ghostId
+ *
+ * **Retrieval Strategy:**
+ * - If id < 0: Check LocalConceptsData → Check LocalGhostIdTree
+ * - If id >= 0: Fetch from backend → Convert to LConcept
+ * - Routes through service worker if enabled
+ * - Returns default empty concept if not found
+ *
+ * **Ghost ID System:**
+ * - ghostId: Original negative ID (preserved after sync)
+ * - id: Current ID (negative if local, positive if synced)
+ * - LocalGhostIdTree maintains the mapping
+ *
+ * @param id - The concept ID to retrieve. Can be:
+ *            - Negative (e.g., -12345) for local-only concepts
+ *            - Positive (e.g., 789) for server concepts
+ *
+ * @returns Promise resolving to a Concept object in LConcept format.
+ *         Returns default concept (id=0) if not found.
+ *
+ * @example
+ * // Get a local concept (negative ID)
+ * const localConcept = await GetTheConceptLocal(-12345);
+ * console.log(localConcept.id); // -12345
+ * console.log(localConcept.characterValue); // "Draft Note"
+ *
+ * @example
+ * // Get a synced concept (originally local, now on server)
+ * const syncedConcept = await GetTheConceptLocal(-12345);
+ * console.log(syncedConcept.id); // 789 (now positive, synced)
+ * console.log(syncedConcept.ghostId); // -12345 (original ID preserved)
+ *
+ * @example
+ * // Get a server concept
+ * const serverConcept = await GetTheConceptLocal(456);
+ * console.log(serverConcept.id); // 456
+ * // Converted to LConcept format for consistency
+ *
+ * @throws Logs errors but returns default concept instead of throwing
+ *
+ * @see {@link CreateTheConceptLocal} for creating local concepts
+ * @see {@link GetTheConcept} for fetching server concepts only
+ * @see {@link convertFromConceptToLConcept} for format conversion
  */
 export declare function GetTheConceptLocal(id: number): Promise<any>;

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

@@ -1,2 +1,22 @@
 import { InnerActions } from "../../app";
+/**
+ * Gets or creates a local concept - implements get-or-create pattern.
+ *
+ * Checks LocalConceptsData for existing concept matching referent and typeId.
+ * If found, returns existing concept. If not found, creates new local concept.
+ *
+ * **Special Case**: If typeCharacter is "the", sets categoryId to 1 (system category).
+ *
+ * @param referent - The character value/name of the concept
+ * @param typeCharacter - Type name string (e.g., "the_name")
+ * @param userId - User ID creating the concept
+ * @param categoryId - Category classification ID
+ * @param typeId - Type classification ID
+ * @param actions - Action tracking for batch operations
+ * @returns Existing or newly created Concept
+ *
+ * @example
+ * const concept = await MakeTheConceptLocal("Active", "the_status", 101, 1, 5);
+ * // Returns existing "Active" status or creates new one
+ */
 export default function MakeTheConceptLocal(referent: string, typeCharacter: string, userId: number, categoryId: number, typeId: number, actions?: InnerActions): Promise<any>;