mftsccs-node 0.0.57 → 0.0.59

package/dist/types/DataStructures/Local/LocalSyncData.d.ts

@@ -1,14 +1,103 @@
+/**
+ * @fileoverview Local Synchronization Data management for the Concept Connection System.
+ * This module manages temporary storage of concepts and connections that need to be
+ * synchronized with the local database periodically.
+ * @module DataStructures/Local/LocalSyncData
+ */
 import { LConcept } from "./LConcept";
 import { LConnection } from "./LConnection";
+/**
+ * Manages synchronization data for local concepts and connections.
+ * Provides static methods for staging data before batch synchronization to the local database.
+ *
+ * @class LocalSyncData
+ * @export
+ */
 export declare class LocalSyncData {
+    /**
+     * Static array storing concepts pending synchronization.
+     * @type {LConcept[]}
+     * @static
+     */
     static conceptsSyncArray: LConcept[];
+    /**
+     * Static array storing connections pending synchronization.
+     * @type {LConnection[]}
+     * @static
+     */
     static connectionSyncArray: LConnection[];
+    /**
+     * Checks if a concept already exists in the sync array.
+     *
+     * @static
+     * @method CheckContains
+     * @param {LConcept} concept - The concept to check
+     * @returns {boolean} True if the concept exists, false otherwise
+     */
     static CheckContains(concept: LConcept): boolean;
+    /**
+     * Removes related concepts and connections from sync arrays when a concept is deleted.
+     * Removes the concept itself and any connections that reference it.
+     *
+     * @static
+     * @method SyncDataDelete
+     * @param {number} id - The ID of the concept being deleted
+     * @returns {void}
+     */
     static SyncDataDelete(id: number): void;
+    /**
+     * Checks if a connection already exists in the sync array.
+     *
+     * @static
+     * @method CheckContainsConnection
+     * @param {LConnection} connection - The connection to check
+     * @returns {boolean} True if the connection exists, false otherwise
+     */
     static CheckContainsConnection(connection: LConnection): boolean;
+    /**
+     * Adds a concept to the sync array for later batch synchronization.
+     *
+     * @static
+     * @method AddConcept
+     * @param {LConcept} concept - The concept to add
+     * @returns {void}
+     */
     static AddConcept(concept: LConcept): void;
+    /**
+     * Removes a concept from the sync array.
+     *
+     * @static
+     * @method RemoveConcept
+     * @param {LConcept} concept - The concept to remove
+     * @returns {void}
+     */
     static RemoveConcept(concept: LConcept): void;
+    /**
+     * Adds a connection to the sync array for later batch synchronization.
+     *
+     * @static
+     * @method AddConnection
+     * @param {LConnection} connection - The connection to add
+     * @returns {void}
+     */
     static AddConnection(connection: LConnection): void;
+    /**
+     * Removes a connection from the sync array.
+     *
+     * @static
+     * @method RemoveConnection
+     * @param {LConnection} connection - The connection to remove
+     * @returns {void}
+     */
     static RemoveConnection(connection: LConnection): void;
+    /**
+     * Synchronizes all pending concepts and connections to the local database.
+     * Clears the sync arrays after successful synchronization.
+     *
+     * @static
+     * @async
+     * @method syncDataLocalDb
+     * @returns {Promise<string>} Returns "done" when synchronization is complete
+     */
     static syncDataLocalDb(): Promise<string>;
 }

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

@@ -1,8 +1,94 @@
+/**
+ * @fileoverview Defines the PatcherStructure class for patching/updating compositions.
+ * @module DataStructures/PatcherStructure
+ */
+/**
+ * Represents a structure for patching or updating composition data.
+ * This class encapsulates all necessary information for performing partial updates
+ * on compositions, including identification, permissions, and the actual patch data.
+ *
+ * @class PatcherStructure
+ *
+ * @example
+ * ```typescript
+ * const patcher = new PatcherStructure();
+ * patcher.compositionId = 123;
+ * patcher.userId = 1;
+ * patcher.sessionId = 456;
+ * patcher.accessId = 4;
+ * patcher.ofTheCompositionId = 789;
+ * patcher.patchObject = { name: "Updated Name", description: "New description" };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Patching a user profile composition
+ * const profilePatcher = new PatcherStructure();
+ * profilePatcher.compositionId = 100;
+ * profilePatcher.userId = 25;
+ * profilePatcher.patchObject = {
+ *   email: "newemail@example.com",
+ *   bio: "Updated bio"
+ * };
+ * ```
+ */
 export declare class PatcherStructure {
+    /**
+     * The ID of the composition to be patched.
+     * Identifies which composition will receive the update.
+     *
+     * @type {number}
+     * @default 0
+     */
     compositionId: number;
+    /**
+     * The ID of the user performing the patch operation.
+     * Used for access control and audit purposes.
+     *
+     * @type {number}
+     * @default 999
+     */
     userId: number;
+    /**
+     * The session ID associated with the patch operation.
+     * Links the patch to a specific user session for tracking.
+     *
+     * @type {number}
+     * @default 999
+     */
     sessionId: number;
+    /**
+     * The access level ID for the patch operation.
+     * Determines what level of access is required to perform this patch.
+     *
+     * @type {number}
+     * @default 4
+     */
     accessId: number;
+    /**
+     * The ID of the parent or related composition.
+     * Used when patching within a composition hierarchy or relationship.
+     *
+     * @type {number}
+     * @default 0
+     */
     ofTheCompositionId: number;
+    /**
+     * The object containing the patch data.
+     * Contains key-value pairs representing the fields to update and their new values.
+     * Can be any structure depending on the composition being patched.
+     *
+     * @type {any}
+     * @default {}
+     *
+     * @example
+     * ```typescript
+     * patchObject = {
+     *   name: "New Name",
+     *   age: 30,
+     *   tags: ["tag1", "tag2"]
+     * }
+     * ```
+     */
     patchObject: any;
 }

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

@@ -1,7 +1,75 @@
+/**
+ * @fileoverview Referent information data structure for the CCS-JS system.
+ * @module DataStructures/ReferentInfo
+ */
+/**
+ * Represents referent information that links concept data with character data.
+ *
+ * @remarks
+ * ReferentInfo serves as a bridge between concept entities and character entities in the
+ * system. It maintains both the data IDs and the associated user IDs for each entity,
+ * enabling cross-referencing and ownership tracking across different data types. This is
+ * particularly useful for establishing semantic relationships between abstract concepts
+ * and their concrete character representations.
+ *
+ * @example
+ * ```typescript
+ * const referentInfo = new ReferentInfo(
+ *   1001,  // conceptDataId
+ *   2001,  // conceptDataUserId
+ *   3001,  // characterDataId
+ *   2001   // characterDataUserId
+ * );
+ *
+ * // Use for linking concept to character
+ * console.log(`Concept ${referentInfo.conceptDataId} ` +
+ *             `maps to Character ${referentInfo.characterDataId}`);
+ * ```
+ */
 export declare class ReferentInfo {
+    /**
+     * Unique identifier for the concept data.
+     */
     conceptDataId: number;
+    /**
+     * User ID associated with the concept data.
+     *
+     * @remarks
+     * Tracks ownership of the concept entity.
+     */
     conceptDataUserId: number;
+    /**
+     * Unique identifier for the character data.
+     */
     characterDataId: number;
+    /**
+     * User ID associated with the character data.
+     *
+     * @remarks
+     * Tracks ownership of the character entity. May differ from conceptDataUserId
+     * when characters are shared across users.
+     */
     characterDataUserId: number;
+    /**
+     * Creates a new ReferentInfo instance.
+     *
+     * @param conceptDataId - The ID of the concept data
+     * @param conceptDataUserId - The user ID who owns the concept data
+     * @param characterDataId - The ID of the character data
+     * @param characterDataUserId - The user ID who owns the character data
+     *
+     * @remarks
+     * Both concept and character entities maintain their own user ownership,
+     * allowing for flexible sharing and access control scenarios.
+     *
+     * @example
+     * ```typescript
+     * // Create a referent linking concept 100 to character 200
+     * const ref = new ReferentInfo(100, 1, 200, 1);
+     *
+     * // Verify the mapping
+     * console.log(`Concept: ${ref.conceptDataId} -> Character: ${ref.characterDataId}`);
+     * ```
+     */
     constructor(conceptDataId: number, conceptDataUserId: number, characterDataId: number, characterDataUserId: number);
 }

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

@@ -1,10 +1,111 @@
+/**
+ * @fileoverview ReservedIds module for managing pre-allocated concept and connection IDs.
+ * This module provides a pool of reserved IDs to avoid database round-trips during bulk operations.
+ * @module DataStructures/ReservedIds
+ */
+/**
+ * Manages a pool of pre-allocated concept IDs from the backend.
+ * Automatically refills the pool when it gets low to ensure smooth operation.
+ *
+ * @class ReservedIds
+ * @example
+ * ```typescript
+ * // Get a reserved ID for a new concept
+ * const newId = await ReservedIds.getId();
+ *
+ * // Add an ID to the pool
+ * ReservedIds.AddId(123);
+ * ```
+ *
+ * @remarks
+ * Maintains a pool of at least 10 IDs. When the pool has fewer than 10 IDs,
+ * it automatically requests more from the backend.
+ */
 export declare class ReservedIds {
+    /** Pool of reserved concept IDs */
     static ids: number[];
+    /**
+    * Gets the next available reserved ID from the pool.
+    * Automatically refills the pool if it has fewer than 10 IDs.
+    *
+    * @returns {Promise<number>} A unique reserved concept ID
+    *
+    * @example
+    * ```typescript
+    * const id = await ReservedIds.getId();
+    * const concept = new Concept(id, ...);
+    * ```
+    *
+    * @remarks
+    * Uses FIFO (first in, first out) to retrieve IDs.
+    * Triggers a backend call to GetReservedIds when pool is low.
+    */
     static getId(): Promise<number>;
+    /**
+     * Adds an ID to the reserved IDs pool.
+     *
+     * @param {number} id - The ID to add to the pool
+     *
+     * @example
+     * ```typescript
+     * ReservedIds.AddId(123);
+     * ```
+     *
+     * @remarks
+     * Prevents duplicate IDs from being added to the pool.
+     */
     static AddId(id: number): void;
 }
+/**
+ * Manages a pool of pre-allocated connection IDs from the backend.
+ * Automatically refills the pool when it gets low to ensure smooth operation.
+ *
+ * @class ReservedConnectionIds
+ * @example
+ * ```typescript
+ * // Get a reserved ID for a new connection
+ * const newId = await ReservedConnectionIds.getId();
+ *
+ * // Add an ID to the pool
+ * ReservedConnectionIds.AddId(456);
+ * ```
+ *
+ * @remarks
+ * Maintains a pool of at least 10 IDs. When the pool has fewer than 10 IDs,
+ * it automatically requests more from the backend.
+ */
 export declare class ReservedConnectionIds {
+    /** Pool of reserved connection IDs */
     static connectionIds: number[];
+    /**
+     * Gets the next available reserved connection ID from the pool.
+     * Automatically refills the pool if it has fewer than 10 IDs.
+     *
+     * @returns {Promise<number>} A unique reserved connection ID
+     *
+     * @example
+     * ```typescript
+     * const id = await ReservedConnectionIds.getId();
+     * const connection = new Connection(id, ...);
+     * ```
+     *
+     * @remarks
+     * Uses FIFO (first in, first out) to retrieve IDs.
+     * Triggers a backend call to GetReservedConnectionIds when pool is low.
+     */
     static getId(): Promise<number>;
+    /**
+     * Adds an ID to the reserved connection IDs pool.
+     *
+     * @param {number} id - The ID to add to the pool
+     *
+     * @example
+     * ```typescript
+     * ReservedConnectionIds.AddId(456);
+     * ```
+     *
+     * @remarks
+     * Prevents duplicate IDs from being added to the pool.
+     */
     static AddId(id: number): void;
 }

package/dist/types/DataStructures/Responses/ErrorResponse.d.ts

@@ -1,74 +1,236 @@
 /**
- * This is a class that is used to standardize the Response that is sent by FreeSchema.
- * This is done so that we do not have to send a HttpResponse codes.
+ * @fileoverview Defines the FreeSchemaResponse class for standardized error and response handling.
+ * @module DataStructures/Responses/ErrorResponse
+ */
+/**
+ * Standardized response class for FreeSchema API operations.
+ * This class provides a consistent response structure across all API operations,
+ * eliminating the need to manually handle HTTP response codes. It supports method
+ * chaining through fluent setters and provides accessors for all response properties.
+ *
+ * @class FreeSchemaResponse
+ *
+ * @example
+ * ```typescript
+ * // Create a success response
+ * const response = new FreeSchemaResponse(
+ *   "Data retrieved successfully",
+ *   true,
+ *   200,
+ *   { users: [...] }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create an error response with chaining
+ * const errorResponse = new FreeSchemaResponse("", false, 500, null)
+ *   .setMessage("Internal server error")
+ *   .setUrl("https://api.example.com/users");
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Accessing response data
+ * if (response.getOk()) {
+ *   const data = response.getData();
+ *   console.log(response.getMessage());
+ * }
+ * ```
  */
 export declare class FreeSchemaResponse {
+    /**
+     * Human-readable message describing the result of the operation.
+     * @private
+     * @type {string}
+     */
     private message;
+    /**
+     * HTTP status code representing the result of the operation.
+     * Standard codes include: 200 (OK), 401 (Unauthorized), 500 (Internal Server Error), etc.
+     * @private
+     * @type {number}
+     */
     private status;
+    /**
+     * The response data payload.
+     * Can contain any type of data depending on the operation performed.
+     * @private
+     * @type {any}
+     */
     private data;
+    /**
+     * Boolean flag indicating operation success (true) or failure (false).
+     * @private
+     * @type {boolean}
+     */
     private ok;
+    /**
+     * The URL that originated the response or error.
+     * Defaults to the base API URL.
+     * @private
+     * @type {string}
+     */
     private url;
     /**
+     * Creates a new FreeSchemaResponse instance.
      *
-     * @param message this is the message for the response
-     * @param ok  this is the status can be true or false boolean in case that request succeds or fails
-     * @param status this is the standard http codes 200 for ok, 500 for internal error etc.
-     * @param data  this is the standard data that can be anything.
+     * @constructor
+     * @param {string} message - Human-readable message describing the result of the operation
+     * @param {boolean} ok - Status flag indicating success (true) or failure (false)
+     * @param {number} status - Standard HTTP status code (e.g., 200 for OK, 500 for internal error)
+     * @param {any} data - The response data payload, can be any type
+     *
+     * @example
+     * ```typescript
+     * const response = new FreeSchemaResponse(
+     *   "User created successfully",
+     *   true,
+     *   201,
+     *   { id: 123, username: "johndoe" }
+     * );
+     * ```
      */
     constructor(message: string, ok: boolean, status: number, data: any);
     /**
-     * This function gets the message of the error
-     * @returns
+     * Retrieves the response message.
+     *
+     * @public
+     * @returns {string} The human-readable message describing the operation result
+     *
+     * @example
+     * ```typescript
+     * const message = response.getMessage();
+     * console.log(message); // "User created successfully"
+     * ```
      */
     getMessage(): string;
     /**
+     * Sets the response message. Supports method chaining.
      *
-     * @param message This allows you to set a message variable in the FreeSchemaResponse
-     * @returns
+     * @public
+     * @param {string} message - The message to set in the FreeSchemaResponse
+     * @returns {FreeSchemaResponse} The current instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * response.setMessage("Operation completed successfully")
+     *         .setStatus(200);
+     * ```
      */
     setMessage(message: string): FreeSchemaResponse;
     /**
+     * Retrieves the HTTP status code.
+     *
+     * @public
+     * @returns {number} The HTTP status code
      *
-     * @returns status code of the FreeSchemaResponse
+     * @example
+     * ```typescript
+     * const statusCode = response.getStatus();
+     * if (statusCode === 200) {
+     *   // Handle success
+     * }
+     * ```
      */
     getStatus(): number;
     /**
+     * Sets the HTTP status code. Supports method chaining.
+     *
+     * @public
+     * @param {number} status - Standard HTTP status code (200 OK, 401 Unauthorized, 500 Internal Server Error, etc.)
+     * @returns {FreeSchemaResponse} The current instance for method chaining
      *
-     * @param status standard http error codes (200 ok , 401 unauthorized, 500 internal server error etc.)
-     * @returns
+     * @example
+     * ```typescript
+     * response.setStatus(404)
+     *         .setMessage("Resource not found");
+     * ```
      */
     setStatus(status: number): FreeSchemaResponse;
     /**
+     * Retrieves the response data payload.
      *
-     * @returns returns the data for the request
+     * @public
+     * @returns {any} The data associated with the response
+     *
+     * @example
+     * ```typescript
+     * const data = response.getData();
+     * console.log(data.users);
+     * ```
      */
     getData(): any;
     /**
+     * Sets the response data payload. Supports method chaining.
+     *
+     * @public
+     * @param {any} data - The data to include in the response (can be of any type)
+     * @returns {FreeSchemaResponse} The current instance for method chaining
      *
-     * @param data any type of data can be given here
-     * @returns FreeSchemaReponse
+     * @example
+     * ```typescript
+     * response.setData({ users: [...], total: 100 })
+     *         .setOk(true);
+     * ```
      */
     setData(data: any): FreeSchemaResponse;
     /**
+     * Retrieves the success status flag.
+     *
+     * @public
+     * @returns {boolean} True if the operation was successful, false otherwise
      *
-     * @returns the status of the FreeSchemaReponse (either true or false)
+     * @example
+     * ```typescript
+     * if (response.getOk()) {
+     *   // Process successful response
+     * } else {
+     *   // Handle error
+     * }
+     * ```
      */
     getOk(): boolean;
     /**
+     * Sets the success status flag. Supports method chaining.
      *
-     * @param status if the status is true then the response was successful else the success was not achieved.
-     * @returns returns the FreeSchemaResponse
+     * @public
+     * @param {boolean} ok - True if the operation was successful, false if it failed
+     * @returns {FreeSchemaResponse} The current instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * response.setOk(false)
+     *         .setStatus(500)
+     *         .setMessage("Internal server error");
+     * ```
      */
     setOk(ok: boolean): FreeSchemaResponse;
     /**
+     * Retrieves the URL associated with this response.
+     *
+     * @public
+     * @returns {string} The URL from which the response originated
      *
-     * @returns the url that caused the error
+     * @example
+     * ```typescript
+     * const url = response.getUrl();
+     * console.log(url); // "https://api.example.com/users"
+     * ```
      */
     getUrl(): string;
     /**
+     * Sets the URL associated with this response. Supports method chaining.
+     *
+     * @public
+     * @param {string} url - The URL from which the response or error originates
+     * @returns {FreeSchemaResponse} The current instance for method chaining
      *
-     * @param url the url from which the error or response originates
-     * @returns FreeSchemaResponse
+     * @example
+     * ```typescript
+     * response.setUrl("https://api.example.com/users/123")
+     *         .setStatus(404);
+     * ```
      */
     setUrl(url: string): FreeSchemaResponse;
 }