@xeno-js/shared 2.0.1 → 3.0.0

package/dist/result.types-DRyxvpQs.d.ts

@@ -0,0 +1,381 @@
+import { O as Optional, M as Maybe } from './common.types-DT8JtZ0E.js';
+
+/**
+ * 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 };