mftsccs-node 0.0.56 → 0.0.58

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

@@ -0,0 +1,236 @@
+/**
+ * @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.
+     *
+     * @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);
+    /**
+     * 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.
+     *
+     * @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
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * response.setStatus(404)
+     *         .setMessage("Resource not found");
+     * ```
+     */
+    setStatus(status: number): FreeSchemaResponse;
+    /**
+     * Retrieves the response data payload.
+     *
+     * @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
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * if (response.getOk()) {
+     *   // Process successful response
+     * } else {
+     *   // Handle error
+     * }
+     * ```
+     */
+    getOk(): boolean;
+    /**
+     * Sets the success status flag. Supports method chaining.
+     *
+     * @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
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * response.setUrl("https://api.example.com/users/123")
+     *         .setStatus(404);
+     * ```
+     */
+    setUrl(url: string): FreeSchemaResponse;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Defines the FreeschemaResponse interface for standardized API responses.
+ * @module DataStructures/Responses/StandardResponses
+ */
+/**
+ * Represents a standardized response structure for Freeschema API operations.
+ * This interface provides a consistent format for all API responses, including
+ * success and error cases, making it easier to handle responses uniformly across the application.
+ *
+ * @interface FreeschemaResponse
+ *
+ * @example
+ * ```typescript
+ * const response: FreeschemaResponse = {
+ *   message: "User created successfully",
+ *   status: true,
+ *   statusCode: 201,
+ *   data: { id: 123, name: "John Doe" }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error response example
+ * const errorResponse: FreeschemaResponse = {
+ *   message: "User not found",
+ *   status: false,
+ *   statusCode: 404,
+ *   data: null
+ * };
+ * ```
+ */
+export interface FreeschemaResponse {
+    /**
+     * A human-readable message describing the result of the operation.
+     * Provides context about the success or failure of the request.
+     *
+     * @type {string}
+     */
+    message: string;
+    /**
+     * A boolean flag indicating whether the operation was successful.
+     * True indicates success, false indicates failure.
+     *
+     * @type {boolean}
+     */
+    status: boolean;
+    /**
+     * The HTTP status code representing the result of the operation.
+     * Standard HTTP status codes are used (e.g., 200 for success, 404 for not found, 500 for server error).
+     *
+     * @type {number}
+     *
+     * @example
+     * 200 - OK
+     * 201 - Created
+     * 400 - Bad Request
+     * 401 - Unauthorized
+     * 404 - Not Found
+     * 500 - Internal Server Error
+     */
+    statusCode: number;
+    /**
+     * The response data payload.
+     * Can contain any type of data depending on the operation performed.
+     * May be null or undefined for operations that don't return data.
+     *
+     * @type {any}
+     */
+    data: any;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Returner data structure for tracking referent relationships in the CCS-JS system.
+ * @module DataStructures/Returner
+ */
+/**
+ * Represents a returner entity that establishes a relationship between a user and a referent.
+ *
+ * @remarks
+ * The Returner class is a lightweight data structure that links entities through referent
+ * relationships. It tracks which user owns a particular referent reference and whether
+ * the relationship is newly created. This is commonly used in bidirectional relationship
+ * tracking within the concept composition system.
+ *
+ * @example
+ * ```typescript
+ * const returner = new Returner(
+ *   1001,   // id
+ *   2001,   // userId
+ *   3001,   // referentId
+ *   true    // isNew
+ * );
+ * console.log(returner.referentId); // 3001
+ * ```
+ */
+export declare class Returner {
+    /**
+     * Unique identifier for this returner entity.
+     */
+    id: number;
+    /**
+     * ID of the user who owns this returner relationship.
+     */
+    userId: number;
+    /**
+     * ID of the referent being referenced by this returner.
+     *
+     * @remarks
+     * The referentId typically points to another entity in the system,
+     * establishing a directional relationship.
+     */
+    referentId: number;
+    /**
+     * Flag indicating whether this returner relationship is newly created.
+     */
+    isNew: boolean;
+    /**
+     * Creates a new Returner instance.
+     *
+     * @param id - Unique identifier for this returner
+     * @param userId - ID of the user who owns this relationship
+     * @param referentId - ID of the entity being referenced
+     * @param isNew - Whether this is a newly created relationship
+     *
+     * @example
+     * ```typescript
+     * // Create a returner linking user 100 to referent 500
+     * const returner = new Returner(1, 100, 500, false);
+     *
+     * // Check the relationship
+     * if (!returner.isNew) {
+     *   console.log(`Existing relationship to referent ${returner.referentId}`);
+     * }
+     * ```
+     */
+    constructor(id: number, userId: number, referentId: number, isNew: boolean);
+}

package/dist/types/DataStructures/Search/FreeschemaQuery.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Defines the FreeschemaQuery class for complex, flexible query construction.
+ * @module DataStructures/Search/FreeschemaQuery
+ */
+import { Concept } from "../Concept";
+import { FilterSearch } from "../FilterSearch";
+/**
+ * Represents a flexible, schema-free query structure for complex data retrieval operations.
+ * This class supports nested queries, filtering, ordering, and various output formats.
+ * It is designed to handle advanced querying scenarios with multiple concepts and connections.
+ *
+ * @class FreeschemaQuery
+ *
+ * @example
+ * ```typescript
+ * const query = new FreeschemaQuery();
+ * query.type = "User";
+ * query.inpage = 20;
+ * query.page = 1;
+ * query.order = "ASC";
+ * query.filters = [filterSearch1, filterSearch2];
+ * query.filterLogic = "AND";
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nested query example
+ * const parentQuery = new FreeschemaQuery();
+ * const childQuery = new FreeschemaQuery();
+ * childQuery.type = "Comment";
+ * parentQuery.freeschemaQueries = [childQuery];
+ * ```
+ */
+export declare class FreeschemaQuery {
+    /**
+     * The type of entity to query (e.g., "User", "Post", "Comment").
+     * Determines the primary data structure being queried.
+     *
+     * @type {string}
+     * @default ""
+     */
+    type: string;
+    /**
+     * The number of results to return per page (page size).
+     * Controls pagination by limiting results in the response.
+     *
+     * @type {number}
+     * @default 10
+     */
+    inpage: number;
+    /**
+     * The page number to retrieve (1-indexed).
+     * Used with inpage for paginating through large result sets.
+     *
+     * @type {number}
+     * @default 1
+     */
+    page: number;
+    /**
+     * Array of Concept objects to include in the query.
+     * Contains the actual concept instances used for filtering or joining.
+     *
+     * @type {Concept[]}
+     * @default []
+     */
+    concepts: Concept[];
+    /**
+     * Array of concept IDs to filter by.
+     * Alternative to using full Concept objects when only IDs are needed.
+     *
+     * @type {number[]}
+     * @default []
+     */
+    conceptIds: number[];
+    /**
+     * Array of field selectors to include in the query results.
+     * Specifies which properties should be returned in the response.
+     *
+     * @type {string[]}
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * query.selectors = ["id", "name", "email"];
+     * ```
+     */
+    selectors: string[];
+    /**
+     * Array of nested FreeschemaQuery objects for complex hierarchical queries.
+     * Enables querying related data structures in a single operation.
+     *
+     * @type {FreeschemaQuery[]}
+     * @default []
+     */
+    freeschemaQueries: FreeschemaQuery[];
+    /**
+     * Array of FilterSearch objects to apply to the query.
+     * Each filter defines specific criteria for narrowing results.
+     *
+     * @type {FilterSearch[]}
+     * @default []
+     */
+    filters: FilterSearch[];
+    /**
+     * The logical operator to combine multiple filters.
+     * Typically "AND" or "OR" to determine how filters are applied together.
+     *
+     * @type {string}
+     * @default ""
+     */
+    filterLogic: string;
+    /**
+     * The type of connection to query when dealing with relationships.
+     * Specifies the connection type when traversing between concepts.
+     *
+     * @type {string}
+     * @default ""
+     */
+    typeConnection: string;
+    /**
+     * The sort order for query results.
+     * Determines whether results are sorted in ascending or descending order.
+     *
+     * @type {string}
+     * @default "DESC"
+     */
+    order: string;
+    /**
+     * The output format for query results.
+     * Determines the structure and presentation of returned data.
+     *
+     * @type {number}
+     * @default NORMAL
+     *
+     * @see {@link FormatConstants.NORMAL}
+     * @see {@link FormatConstants.ALLID}
+     */
+    outputFormat: number;
+    /**
+     * A descriptive name for this query.
+     * Useful for identifying or debugging complex nested queries.
+     *
+     * @type {string}
+     * @default ""
+     */
+    name: string;
+    /**
+     * Flag indicating whether to reverse the query direction.
+     * When true, traverses relationships in the opposite direction.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    reverse: boolean;
+    /**
+     * Flag indicating whether to apply a limit to the query results.
+     * When true, enforces the page size limit strictly.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    limit: boolean;
+    /**
+     * Filter criteria applied to ancestor nodes in hierarchical queries.
+     * Used for filtering based on parent or ancestor relationships.
+     *
+     * @type {string}
+     * @default ""
+     */
+    filterAncestor: string;
+    /**
+     * Flag indicating whether to include this query in parent filter operations.
+     * When true, the query results are considered in parent-level filtering.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    includeInFilter: boolean;
+    /**
+     * Flag indicating whether to use legacy connection type behavior.
+     * Maintains backward compatibility with older connection type systems.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    isOldConnectionType: boolean;
+}

package/dist/types/DataStructures/Search/SearchStructure.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Defines the SearchStructure class for configuring search operations.
+ * @module DataStructures/Search/SearchStructure
+ */
+/**
+ * Represents a search structure configuration for querying data.
+ * This class encapsulates all parameters needed to perform a search operation,
+ * including filtering, pagination, and composition settings.
+ *
+ * @class SearchStructure
+ *
+ * @example
+ * ```typescript
+ * const search = new SearchStructure();
+ * search.type = "concept";
+ * search.search = "user profile";
+ * search.page = 1;
+ * search.inpage = 20;
+ * ```
+ */
+export declare class SearchStructure {
+    /**
+     * The type of entity to search for (e.g., "concept", "connection").
+     * Determines which data structure will be queried.
+     *
+     * @type {string}
+     * @default ""
+     */
+    type: string;
+    /**
+     * The search term or query string to match against.
+     * This is the primary search criteria used for filtering results.
+     *
+     * @type {string}
+     * @default ""
+     */
+    search: string;
+    /**
+     * The composition identifier or filter for searching within compositions.
+     * Used to narrow search results to specific composition contexts.
+     *
+     * @type {string}
+     * @default ""
+     */
+    composition: string;
+    /**
+     * Internal composition identifier for nested or hierarchical composition searches.
+     * Allows for more granular filtering within composition structures.
+     *
+     * @type {string}
+     * @default ""
+     */
+    internalComposition: string;
+    /**
+     * The user ID associated with the search operation.
+     * Used for access control and filtering results based on user permissions.
+     *
+     * @type {number}
+     * @default 999
+     */
+    userId: number;
+    /**
+     * The number of results to display per page (page size).
+     * Controls pagination by limiting the number of results returned.
+     *
+     * @type {number}
+     * @default 10
+     */
+    inpage: number;
+    /**
+     * The page number to retrieve (1-indexed).
+     * Used in conjunction with inpage for pagination of search results.
+     *
+     * @type {number}
+     * @default 1
+     */
+    page: number;
+}