mftsccs-node 0.2.6 → 0.2.8

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

@@ -1,6 +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

@@ -1,7 +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

@@ -1,22 +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

@@ -1,9 +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;
 }

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

@@ -1,16 +1,146 @@
+/**
+ * @fileoverview Defines the SearchQuery class for constructing search queries with filtering and pagination.
+ * @module DataStructures/SearchQuery
+ */
 import { FilterSearch } from "./FilterSearch";
+/**
+ * Represents a search query configuration with support for filtering, linking, and pagination.
+ * This class provides a comprehensive structure for building complex search operations
+ * with multiple criteria and logical operators.
+ *
+ * @class SearchQuery
+ *
+ * @example
+ * ```typescript
+ * const query = new SearchQuery();
+ * query.type = "Article";
+ * query.composition = 123;
+ * query.textSearch = "TypeScript tutorial";
+ * query.page = 1;
+ * query.inpage = 25;
+ * query.logic = "and";
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Search with filters
+ * const query = new SearchQuery();
+ * query.type = "Product";
+ * query.doFilter = true;
+ * query.filterSearches = [
+ *   { type: "price", search: "100", logicoperator: ">", index: 0, composition: true, name: "price", operateon: "value" },
+ *   { type: "category", search: "Electronics", logicoperator: "=", index: 1, composition: true, name: "category", operateon: "value" }
+ * ];
+ * ```
+ */
 export declare class SearchQuery {
+    /**
+     * The composition ID to search within.
+     * Specifies which composition context the search should be performed in.
+     *
+     * @type {number}
+     * @default 0
+     */
     composition: number;
+    /**
+     * The type of entity to search for.
+     * Determines the data structure or entity type being queried.
+     *
+     * @type {string}
+     * @default ""
+     */
     type: string;
+    /**
+     * The linker identifier for relationship-based searches.
+     * Used to specify connection types when traversing relationships.
+     *
+     * @type {string}
+     * @default ""
+     */
     linker: string;
+    /**
+     * 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 with inpage for paginating through search results.
+     *
+     * @type {number}
+     * @default 1
+     */
     page: number;
+    /**
+     * Array of linker identifiers for multiple relationship types.
+     * Allows searching across multiple connection types simultaneously.
+     *
+     * @type {string[]}
+     * @default []
+     */
     listLinkers: string[];
+    /**
+     * Array of complete linker specifications for complex relationship queries.
+     * Contains fully qualified linker definitions for advanced searches.
+     *
+     * @type {string[]}
+     * @default []
+     */
     fullLinkers: string[];
+    /**
+     * The text search term or query string.
+     * Primary search criteria for text-based filtering.
+     *
+     * @type {string}
+     * @default ""
+     */
     textSearch: string;
+    /**
+     * The logical operator to combine multiple search criteria.
+     * Determines how multiple conditions are combined (e.g., "or", "and").
+     *
+     * @type {string}
+     * @default "or"
+     */
     logic: string;
+    /**
+     * Flag indicating whether to reverse the search direction.
+     * When true, traverses relationships in the opposite direction.
+     *
+     * @type {boolean}
+     * @default false
+     */
     reverse: boolean;
+    /**
+     * Flag indicating whether to apply filters to the search.
+     * When true, the filterSearches array is applied to narrow results.
+     *
+     * @type {boolean}
+     * @default false
+     */
     doFilter: boolean;
+    /**
+     * Array of FilterSearch objects defining specific filter criteria.
+     * Each filter specifies conditions that must be met for results to be included.
+     *
+     * @type {FilterSearch[]}
+     * @default []
+     */
     filterSearches: FilterSearch[];
+    /**
+     * 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", "createdAt"];
+     * ```
+     */
     selectors: string[];
 }

package/dist/types/DataStructures/Security/TokenStorage.d.ts

@@ -1,4 +1,52 @@
+/**
+ * @fileoverview Defines the TokenStorage class for managing authentication tokens.
+ * @module DataStructures/Security/TokenStorage
+ */
+/**
+ * Centralized storage for authentication tokens.
+ * This class provides a singleton-like static storage mechanism for managing
+ * Bearer access tokens across the application. The token is stored as a static
+ * property, making it accessible throughout the application without instantiation.
+ *
+ * @class TokenStorage
+ *
+ * @example
+ * ```typescript
+ * // Set the access token after authentication
+ * TokenStorage.BearerAccessToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Retrieve the access token for API requests
+ * const token = TokenStorage.BearerAccessToken;
+ * const headers = {
+ *   'Authorization': `Bearer ${token}`
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Clear the token on logout
+ * TokenStorage.BearerAccessToken = "";
+ * ```
+ */
 export declare class TokenStorage {
+    /**
+     * The Bearer access token used for authentication.
+     * This static property stores the JWT or other authentication token
+     * used for authorizing API requests. The token typically has the format
+     * "Bearer <token>" when included in HTTP headers.
+     *
+     * @static
+     * @type {string}
+     * @default ""
+     *
+     * @remarks
+     * As a static property, this token is shared across all instances and modules.
+     * Exercise caution when handling this token to prevent security vulnerabilities.
+     * Consider clearing this value on logout or session expiration.
+     */
     static BearerAccessToken: string;
     static JwtSecret: string;
 }