@xeno-js/shared 2.0.1 → 3.0.0

package/dist/ivalidator-service.contracts-DGMounqU.d.cts

@@ -0,0 +1,102 @@
+import { O as Optional } from './common.types-DT8JtZ0E.cjs';
+import { R as ResultType } from './result.types-BNTzjCgR.cjs';
+
+/**
+ * @description Interface for a logger that provides methods for logging messages at different levels (info, warn, error, debug) and tracking exceptions. Each logging method accepts a message and an optional context, while the error method also accepts an optional Error object.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface ILogger {
+    /**
+     * Log a message at the info level with an optional context.
+     * @param message The message to log.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    info(message: string): void;
+    /**
+     * Log a message at the warning level with an optional context.
+     * @param message The message to log.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    warn(message: string): void;
+    /**
+     * Log a message at the error level with an optional error object and context.
+     * @param message The message to log.
+     * @param error An optional unknown object associated with the log message.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    error(message: string, error: Optional<unknown>): void;
+    /**
+     * Log a message at the debug level with an optional context.
+     * @param message The message to log.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    debug(message: string): void;
+}
+
+/**
+ * @description Interface for a validation service that provides methods to check for the existence of validation schemas and to validate data against those schemas. The IValidatorService interface defines two methods: hasSchema, which checks if a validation schema exists for a given key, and validate, which validates data against a specified schema key and returns a ResultType indicating the success or failure of the validation process. This interface can be implemented by various validation services that utilize different schema validation libraries or custom validation logic to ensure that incoming data meets the required criteria before being processed further in the application.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface IValidatorService {
+    /**
+     * @description Validates the provided data against the validation schema associated with the specified key. This method performs the actual validation logic, checking if the data conforms to the rules defined in the corresponding schema. It returns a ResultType indicating whether the validation was successful or if it failed, along with any relevant error information if the validation did not pass.
+     * @param key The key representing the type of data or request for which the validation is being performed. This key is used to identify the appropriate validation schema to apply to the data.
+     * @param data The data to be validated against the schema. This can be any type of data that needs to be checked for conformity with the validation rules defined in the schema.
+     * @returns A ResultType indicating the outcome of the validation. If the validation is successful, it returns a ResultType with a value of true; if the validation fails, it returns a ResultType with a value of false and includes error information.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    validate<T>(key: string, data: T): Promise<ResultType<boolean>>;
+    /**
+     * @description Adds a new validation schema to the service's registry, associating it with the specified key. This method allows for dynamically registering validation schemas that can be used later for validating incoming data. The schema must conform to the expected structure defined by the validation library being used (e.g., Zod schemas). By adding schemas to the service, it enables the application to perform validation checks against those schemas when processing requests or data that require validation.
+     * @param key The key representing the type of data or request for which the validation schema is being added. This key is used to identify the schema when performing validation checks.
+     * @param schema The validation schema to be added, which defines the rules and structure that incoming data must conform to in order to pass validation. The specific type of the schema will depend on the validation library being used (e.g., ZodType for Zod schemas).
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    addSchema(key: string, schema: unknown): void;
+}
+
+export type { ILogger as I, IValidatorService as a };

package/dist/ivalidator-service.contracts-ulue7FGh.d.ts

@@ -0,0 +1,102 @@
+import { O as Optional } from './common.types-DT8JtZ0E.js';
+import { R as ResultType } from './result.types-DRyxvpQs.js';
+
+/**
+ * @description Interface for a logger that provides methods for logging messages at different levels (info, warn, error, debug) and tracking exceptions. Each logging method accepts a message and an optional context, while the error method also accepts an optional Error object.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface ILogger {
+    /**
+     * Log a message at the info level with an optional context.
+     * @param message The message to log.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    info(message: string): void;
+    /**
+     * Log a message at the warning level with an optional context.
+     * @param message The message to log.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    warn(message: string): void;
+    /**
+     * Log a message at the error level with an optional error object and context.
+     * @param message The message to log.
+     * @param error An optional unknown object associated with the log message.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    error(message: string, error: Optional<unknown>): void;
+    /**
+     * Log a message at the debug level with an optional context.
+     * @param message The message to log.
+     * @param context An optional dictionary containing additional context for the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    debug(message: string): void;
+}
+
+/**
+ * @description Interface for a validation service that provides methods to check for the existence of validation schemas and to validate data against those schemas. The IValidatorService interface defines two methods: hasSchema, which checks if a validation schema exists for a given key, and validate, which validates data against a specified schema key and returns a ResultType indicating the success or failure of the validation process. This interface can be implemented by various validation services that utilize different schema validation libraries or custom validation logic to ensure that incoming data meets the required criteria before being processed further in the application.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface IValidatorService {
+    /**
+     * @description Validates the provided data against the validation schema associated with the specified key. This method performs the actual validation logic, checking if the data conforms to the rules defined in the corresponding schema. It returns a ResultType indicating whether the validation was successful or if it failed, along with any relevant error information if the validation did not pass.
+     * @param key The key representing the type of data or request for which the validation is being performed. This key is used to identify the appropriate validation schema to apply to the data.
+     * @param data The data to be validated against the schema. This can be any type of data that needs to be checked for conformity with the validation rules defined in the schema.
+     * @returns A ResultType indicating the outcome of the validation. If the validation is successful, it returns a ResultType with a value of true; if the validation fails, it returns a ResultType with a value of false and includes error information.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    validate<T>(key: string, data: T): Promise<ResultType<boolean>>;
+    /**
+     * @description Adds a new validation schema to the service's registry, associating it with the specified key. This method allows for dynamically registering validation schemas that can be used later for validating incoming data. The schema must conform to the expected structure defined by the validation library being used (e.g., Zod schemas). By adding schemas to the service, it enables the application to perform validation checks against those schemas when processing requests or data that require validation.
+     * @param key The key representing the type of data or request for which the validation schema is being added. This key is used to identify the schema when performing validation checks.
+     * @param schema The validation schema to be added, which defines the rules and structure that incoming data must conform to in order to pass validation. The specific type of the schema will depend on the validation library being used (e.g., ZodType for Zod schemas).
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    addSchema(key: string, schema: unknown): void;
+}
+
+export type { ILogger as I, IValidatorService as a };

package/dist/result.types-BNTzjCgR.d.cts

@@ -0,0 +1,381 @@
+import { O as Optional, M as Maybe } from './common.types-DT8JtZ0E.cjs';
+
+/**
+ * A class representing an application error, which extends the built-in Error class.
+ * It includes additional properties such as an error code and an HTTP status code.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface ErrorPayload {
+    /** The error message describing the error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    message: string;
+    /** The error code representing the type of error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    code: string;
+    /** The HTTP status code associated with the error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    status: number;
+    /** The name of the error, typically the class name.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    name: string;
+    /** An optional property to hold the original error or any additional context.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    cause: Optional<unknown>;
+    /** A Dictionary to hold any additional context or information related to the error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    [key: string]: unknown;
+}
+/**
+ * A class representing an application error, which extends the built-in Error class.
+ * It includes additional properties such as an error code and an HTTP status code.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+declare class AppError extends Error {
+    /**
+     * The error code representing the type of error.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly code: string;
+    /**
+     * The HTTP status code associated with the error.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly status: number;
+    /**
+     * A Dictionary to hold any additional context or information related to the error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly [key: string]: unknown;
+    /**
+     * Private constructor to prevent direct instantiation. Use the static methods `create` and `throw` to create instances.
+     *
+     * @param payload - The payload containing error details.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private constructor();
+    /**
+     * Creates an AppError instance with the given error payload.
+     *
+     * @param payload - The payload containing error details.
+     * @returns An AppError instance representing the error.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static create(payload: ErrorPayload): AppError;
+    /**
+     * Creates an AppError instance and throws it immediately.
+     * @param payload - The payload containing error details.
+     * @throws An AppError instance representing the error.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static throw(payload: ErrorPayload): never;
+    /**
+     * Creates an AppError instance representing an aborted request.
+     * @param name - The name of the error, typically the class name or context where the error occurred.
+     * @returns An AppError instance representing the aborted request error.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static aborted(name: string): AppError;
+    /**
+     * Utility method to check if an AbortSignal has been triggered and throw an AppError if it has.
+     * @param signal - The AbortSignal to check for abortion.
+     * @param name - The name of the error, typically the class name or context where the error occurred.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static throwIfAborted(signal: Maybe<AbortSignal>, name: string): void;
+    /** @description Creates an AppError instance representing an unauthorized access error. This method is used to generate a standardized error response when a user attempts to access a resource or perform an action without the necessary authentication or authorization.
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the unauthorized access. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the unauthorized access error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static unauthorized(name: string, message: string): AppError;
+    static notSupported(name: string, message: string): AppError;
+    /** @description Creates an AppError instance representing a forbidden access error. This method is used to generate a standardized error response when a user attempts to access a resource or perform an action that they are not authorized to access, even if they are authenticated.
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the forbidden access. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the forbidden access error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static forbidden(name: string, message: string): AppError;
+    /** @description Creates an AppError instance representing a bad request error. This method is used to generate a standardized error response when a request made by the client is invalid or cannot be processed due to client-side issues, such as validation errors or malformed requests.
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the bad request. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the bad request error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static badRequest(name: string, message: string): AppError;
+    /** @description Creates an AppError instance representing a validation error. This method is used to generate a standardized error response when one or more input fields fail invariant or schema validation, indicating that the request cannot be processed due to invalid data.
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the validation failure. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the validation error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static validationError(name: string, message: string): AppError;
+    /** @description Creates an AppError instance representing a conflict error. This method is used to generate a standardized error response when a request conflicts with the current state of the resource, such as when attempting to create a resource that already exists or update a resource that has been modified by another process.
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the conflict. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the conflict error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static conflict(name: string, message: string): AppError;
+    /** @description Creates an AppError instance representing a not found error. This method is used to generate a standardized error response when a requested resource does not exist, indicating that the client attempted to access a resource that could not be found on the server.
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the not found error. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the not found error.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static notFound(name: string, message: string): AppError;
+    /** @description Creates an AppError instance representing a Authentication failed. This method is used to generate a standardized error response when an auth requested produce an error..
+     * @param name The name of the error, typically the class name or context where the error occurred. This helps in identifying the source of the error in logs and error reports.
+     * @param message A custom message describing the reason for the Authentication failed. This message is included in the AppError's cause for detailed error reporting.
+     * @returns An AppError instance representing the Authentication failed.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static authFailed(name: string, message: string): AppError;
+}
+
+/**
+ * A class representing the result of an operation, which can either be a success or a failure.
+ * It encapsulates the value of a successful operation or the error of a failed operation.
+ *
+ * @template TValue - The type of the value in case of a successful operation.
+ * @template TError - The type of the error in case of a failed operation (default is never).
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+declare class Result<TValue, TError = never> {
+    /**
+     * Indicates whether the operation was successful or not.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private readonly _isSuccess;
+    /**
+     * The error of the operation in case it failed.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private readonly _error;
+    /**
+     * The value of the operation in case it succeeded.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private readonly _value;
+    /**
+     * Private constructor to prevent direct instantiation. Use the static methods `ok` and `fail` to create instances.
+     *
+     * @param isSuccess - A boolean indicating whether the operation was successful.
+     * @param error - The error of the operation in case it failed (optional).
+     * @param value - The value of the operation in case it succeeded (optional).
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private constructor();
+    /**
+     * Creates a successful result with the given value.
+     *
+     * @param value - The value of the successful operation.
+     * @returns A Result instance representing a successful operation.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static ok<U>(value?: U): Result<U>;
+    /**
+     * Creates a failed result with the given error.
+     *
+     * @param error - The error of the failed operation.
+     * @returns A Result instance representing a failed operation.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    static fail<U, V = never>(error: V): Result<U, V>;
+    /**
+     * Checks if the result is a success.
+     *
+     * @returns True if the result is a success, false otherwise.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    isOk(): boolean;
+    /**
+     * Gets the value of the result or throws an error if the result is a failure.
+     *
+     * @returns The value of the result.
+     * @throws An error if the result is a failure.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    getValueOrThrow(): Optional<TValue>;
+    /**
+     * Gets the error of the result or throws an error if the result is a success.
+     *
+     * @returns The error of the result.
+     * @throws An error if the result is a success.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    getErrorOrThrow(): TError;
+}
+
+/**
+ * A utility type to extract the value type from a Result instance.
+ *
+ * @template T - The type of the Result instance.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type ResultType<T, E = AppError> = Result<T, E>;
+
+export { AppError as A, type ResultType as R, Result as a };