mftsccs-node 0.0.56 → 0.0.58

package/dist/types/DataStructures/SyncData.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview SyncData module for managing synchronization of concepts and connections in CCS-JS.
+ * This module provides queuing and batch synchronization of local changes to the backend server,
+ * with support for transactional operations and rollback capabilities.
+ * @module DataStructures/SyncData
+ */
+import { Concept } from "./Concept";
+import { Connection } from "./Connection";
+import { InnerActions } from "./Transaction/Transaction";
+/**
+ * Container for transactional sync data.
+ * Stores concepts and connections that are part of a transaction.
+ */
+type syncContainer = {
+    /** Unique transaction identifier */
+    id: string;
+    /** Transaction data containing concepts and connections */
+    data: InnerActions;
+    /** ISO timestamp of when the transaction was created */
+    createdDate: string;
+};
+/**
+ * Manages synchronization of concepts and connections between local storage and backend.
+ * Provides queuing, batch processing, and transaction support for data synchronization.
+ *
+ * @class SyncData
+ * @example
+ * ```typescript
+ * // Add items to sync queue
+ * SyncData.AddConcept(myConcept);
+ * SyncData.AddConnection(myConnection);
+ *
+ * // Sync to backend
+ * await SyncData.SyncDataOnline();
+ *
+ * // Transaction support
+ * await SyncData.initializeTransaction("txn-123");
+ * await SyncData.markTransactionActions("txn-123", actions);
+ * await SyncData.SyncDataOnline("txn-123");
+ * ```
+ *
+ * @remarks
+ * This class provides both immediate and batched synchronization modes.
+ * Transactions are automatically cleaned up after 7 days (604800000 ms).
+ */
+export declare class SyncData {
+    /** Queue of concepts waiting to be synchronized to backend */
+    static conceptsSyncArray: Concept[];
+    /** Queue of connections waiting to be synchronized to backend */
+    static connectionSyncArray: Connection[];
+    /** Collection of transactional sync operations */
+    static transactionCollections: syncContainer[];
+    /**
+     * Checks if a concept already exists in the sync queue.
+     *
+     * @param {Concept} concept - The concept to check
+     * @returns {boolean} True if the concept is in the sync queue, false otherwise
+     *
+     * @private
+     */
+    static CheckContains(concept: Concept): boolean;
+    /**
+     * Removes all sync data related to a specific concept ID.
+     * Removes the concept and any connections that reference it.
+     *
+     * @param {number} id - The concept ID to remove from sync queues
+     *
+     * @example
+     * ```typescript
+     * SyncData.SyncDataDelete(123);
+     * ```
+     *
+     * @remarks
+     * Also removes connections where the concept appears as ofTheConceptId, toTheConceptId, or typeId.
+     */
+    static SyncDataDelete(id: number): void;
+    /**
+     * Checks if a connection already exists in the sync queue.
+     *
+     * @param {Connection} connection - The connection to check
+     * @returns {boolean} True if the connection is in the sync queue, false otherwise
+     *
+     * @private
+     */
+    static CheckContainsConnection(connection: Connection): boolean;
+    /**
+     * Adds a concept to the synchronization queue.
+     *
+     * @param {Concept} concept - The concept to add to sync queue
+     *
+     * @example
+     * ```typescript
+     * SyncData.AddConcept(myConcept);
+     * // Later...
+     * await SyncData.SyncDataOnline();
+     * ```
+     */
+    static AddConcept(concept: Concept): void;
+    /**
+    * Removes a concept from the synchronization queue.
+    *
+    * @param {Concept} concept - The concept to remove from sync queue
+    *
+    * @example
+    * ```typescript
+    * SyncData.RemoveConcept(myConcept);
+    * ```
+    */
+    static RemoveConcept(concept: Concept): void;
+    /**
+    * Adds a connection to the synchronization queue.
+    *
+    * @param {Connection} connection - The connection to add to sync queue
+    *
+    * @example
+    * ```typescript
+    * SyncData.AddConnection(myConnection);
+    * // Later...
+    * await SyncData.SyncDataOnline();
+    * ```
+    */
+    static AddConnection(connection: Connection): void;
+    /**
+    * Removes a connection from the synchronization queue.
+    *
+    * @param {Connection} connection - The connection to remove from sync queue
+    *
+    * @example
+    * ```typescript
+    * SyncData.RemoveConnection(myConnection);
+    * ```
+    */
+    static RemoveConnection(connection: Connection): void;
+    /**
+    * Synchronizes queued data to the backend server.
+    * Can sync either a specific transaction or all queued data.
+    *
+    * @param {string} [transactionId] - Optional transaction ID to sync specific transaction
+    * @returns {Promise<string>} Returns "done" when synchronization completes
+    * @throws {Error} If synchronization fails
+    *
+    * @example
+    * ```typescript
+    * // Sync all queued data
+    * await SyncData.SyncDataOnline();
+    *
+    * // Sync specific transaction
+    * await SyncData.SyncDataOnline("txn-123");
+    * ```
+    *
+    * @remarks
+    * - If transactionId is provided, only that transaction is synced and removed from collection
+    * - Otherwise, all queued concepts and connections are synced
+    * - Automatically cleans up transactions older than 7 days (604800000 ms)
+    * - Adds data to permanent storage before sending to backend
+    */
+    static SyncDataOnline(transactionId?: string): Promise<"done" | undefined>;
+    /**
+     * Initializes a new transaction container for tracking related changes.
+     *
+     * @param {string} transactionId - Unique identifier for the transaction
+     *
+     * @example
+     * ```typescript
+     * await SyncData.initializeTransaction("txn-123");
+     * // Make changes...
+     * await SyncData.markTransactionActions("txn-123", actions);
+     * await SyncData.SyncDataOnline("txn-123");
+     * ```
+     *
+     * @remarks
+     * Does nothing if a transaction with the same ID already exists.
+     * Creates an empty container with the current timestamp.
+     */
+    static initializeTransaction(transactionId: string): Promise<void>;
+    /**
+     * Marks specific actions as part of a transaction.
+     * Removes these actions from the general sync queues to prevent duplication.
+     *
+     * @param {string} transactionId - The transaction ID
+     * @param {InnerActions} actions - The concepts and connections to mark as part of transaction
+     *
+     * @example
+     * ```typescript
+     * const actions = {
+     *   concepts: [concept1, concept2],
+     *   connections: [connection1, connection2]
+     * };
+     * await SyncData.markTransactionActions("txn-123", actions);
+     * ```
+     *
+     * @remarks
+     * - Updates the transaction container with the actions
+     * - Removes marked items from conceptsSyncArray and connectionSyncArray
+     * - Matches items by both id and ghostId to handle temporary IDs
+     */
+    static markTransactionActions(transactionId: string, actions: InnerActions): Promise<void>;
+    /**
+     * Rolls back a transaction by removing it from the transaction collection.
+     *
+     * @param {string} transactionId - The transaction ID to rollback
+     * @param {InnerActions} actions - The actions to rollback (currently unused)
+     *
+     * @example
+     * ```typescript
+     * await SyncData.rollbackTransaction("txn-123", actions);
+     * ```
+     *
+     * @remarks
+     * Currently only removes the transaction from collection if it doesn't already exist.
+     * The logic may need review as it checks for existence before removal.
+     */
+    static rollbackTransaction(transactionId: string, actions: InnerActions): Promise<void>;
+    /**
+    * Synchronizes queued data to local IndexedDB storage only (not to backend).
+    *
+    * @returns {Promise<string>} Returns "done" when local sync completes
+    *
+    * @example
+    * ```typescript
+    * await SyncData.syncDataLocalDb();
+    * ```
+    *
+    * @remarks
+    * - Stores concepts to "localconcept" database
+    * - Stores connections to "localconnection" database
+    * - Clears the sync queues after storing
+    * - Used for offline persistence without backend sync
+    */
+    static syncDataLocalDb(): Promise<string>;
+}
+export {};

package/dist/types/DataStructures/TheCharacter.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Character data structure for the CCS-JS system.
+ * @module DataStructures/TheCharacter
+ */
+/**
+ * Represents a character entity in the system with associated user, security, access, and session information.
+ *
+ * @remarks
+ * TheCharacter class encapsulates character data along with comprehensive metadata including
+ * user ownership, security credentials, access control, and session tracking. Each character
+ * maintains references to multiple user contexts for fine-grained authorization control.
+ *
+ * @example
+ * ```typescript
+ * const character = new TheCharacter(
+ *   1001,                    // userId
+ *   "A",                     // data
+ *   5001,                    // securityId
+ *   1001,                    // securityUserId
+ *   6001,                    // accessId
+ *   1001,                    // accessUserId
+ *   7001,                    // sessionId
+ *   1001,                    // sessionUserId
+ *   "2025-10-30T12:00:00Z",  // entryTimestamp
+ *   true                     // isNew
+ * );
+ * ```
+ */
+export declare class TheCharacter {
+    /**
+     * Unique identifier for the character.
+     * @defaultValue 0
+     */
+    id: number;
+    /**
+     * ID of the user who owns this character.
+     */
+    userId: number;
+    /**
+     * The actual character data (typically a single character string).
+     */
+    data: string;
+    /**
+     * Security level or security context identifier for this character.
+     */
+    securityId: number;
+    /**
+     * User ID associated with the security context.
+     */
+    securityUserId: number;
+    /**
+     * Access control identifier for this character.
+     */
+    accessId: number;
+    /**
+     * User ID associated with the access control.
+     */
+    accessUserId: number;
+    /**
+     * Session identifier tracking when this character was accessed.
+     */
+    sessionId: number;
+    /**
+     * User ID associated with the session.
+     */
+    sessionUserId: number;
+    /**
+     * Flag indicating whether this is a newly created character.
+     * @defaultValue false
+     */
+    isNew: boolean;
+    /**
+     * Creates a new TheCharacter instance.
+     *
+     * @param userId - The ID of the user who owns this character
+     * @param data - The character data (will be converted to string)
+     * @param securityId - Security level or context identifier
+     * @param securityUserId - User ID for the security context
+     * @param accessId - Access control identifier
+     * @param accessUserId - User ID for access control
+     * @param sessionId - Session tracking identifier
+     * @param sessionUserId - User ID for the session
+     * @param entryTimestamp - Timestamp when the character was created/entered (currently unused in initialization)
+     * @param isNew - Whether this is a newly created character
+     *
+     * @remarks
+     * The data parameter is explicitly converted to a string using template literals.
+     * The entryTimestamp parameter is accepted but not currently stored in the instance.
+     *
+     * @example
+     * ```typescript
+     * const char = new TheCharacter(
+     *   1, "X", 100, 1, 200, 1, 300, 1, "2025-10-30", true
+     * );
+     * console.log(char.data); // "X"
+     * console.log(char.isNew); // true
+     * ```
+     */
+    constructor(userId: number, data: string, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionId: number, sessionUserId: number, entryTimestamp: string, isNew: boolean);
+}

package/dist/types/DataStructures/TheTexts.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Text data structure for the CCS-JS system.
+ * @module DataStructures/TheTexts
+ */
+/**
+ * Represents a text entity in the system with comprehensive metadata and security tracking.
+ *
+ * @remarks
+ * TheTexts class encapsulates text data along with user ownership, security credentials,
+ * access control, session tracking, and timestamp information. This class is similar to
+ * TheCharacter but designed for longer text strings and includes an entry timestamp for
+ * temporal tracking. It provides complete audit trail capabilities through its multiple
+ * user context references.
+ *
+ * @example
+ * ```typescript
+ * const text = new TheTexts(
+ *   1001,                    // userId
+ *   "Hello World",           // data
+ *   5001,                    // securityId
+ *   1001,                    // securityUserId
+ *   6001,                    // accessId
+ *   1001,                    // accessUserId
+ *   7001,                    // sessionId
+ *   1001,                    // sessionUserId
+ *   "2025-10-30T12:00:00Z",  // entryTimestamp
+ *   true                     // isNew
+ * );
+ * ```
+ */
+export declare class TheTexts {
+    /**
+     * Unique identifier for the text entity.
+     * @defaultValue 0
+     */
+    id: number;
+    /**
+     * ID of the user who owns this text.
+     */
+    userId: number;
+    /**
+     * The actual text data content.
+     */
+    data: string;
+    /**
+     * Security level or security context identifier for this text.
+     */
+    securityId: number;
+    /**
+     * User ID associated with the security context.
+     */
+    securityUserId: number;
+    /**
+     * Access control identifier for this text.
+     */
+    accessId: number;
+    /**
+     * User ID associated with the access control.
+     */
+    accessUserId: number;
+    /**
+     * Session identifier tracking when this text was accessed.
+     */
+    sessionId: number;
+    /**
+     * User ID associated with the session.
+     */
+    sessionUserId: number;
+    /**
+     * ISO 8601 timestamp indicating when this text entry was created or modified.
+     */
+    entryTimestamp: string;
+    /**
+     * Flag indicating whether this is a newly created text entry.
+     */
+    isNew: boolean;
+    /**
+     * Creates a new TheTexts instance.
+     *
+     * @param userId - The ID of the user who owns this text
+     * @param data - The text content
+     * @param securityId - Security level or context identifier
+     * @param securityUserId - User ID for the security context
+     * @param accessId - Access control identifier
+     * @param accessUserId - User ID for access control
+     * @param sessionId - Session tracking identifier
+     * @param sessionUserId - User ID for the session
+     * @param entryTimestamp - ISO 8601 timestamp when the text was created/entered
+     * @param isNew - Whether this is a newly created text entry
+     *
+     * @remarks
+     * Unlike TheCharacter, this constructor stores the entryTimestamp property,
+     * making it suitable for temporal tracking and audit trails.
+     *
+     * @example
+     * ```typescript
+     * const text = new TheTexts(
+     *   1, "Sample text", 100, 1, 200, 1, 300, 1,
+     *   new Date().toISOString(), true
+     * );
+     * console.log(text.data); // "Sample text"
+     * console.log(text.entryTimestamp); // "2025-10-30T12:00:00.000Z"
+     * ```
+     */
+    constructor(userId: number, data: string, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionId: number, sessionUserId: number, entryTimestamp: string, isNew: boolean);
+}