@xeno-js/shared 0.1.0

package/dist/domain/errors/app-error.js

@@ -0,0 +1,259 @@
+import { ERROR_CODE_MESSAGES, ERROR_CODES, Guards, STATUS_CODES } from '../../shared';
+/**
+ * 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
+   */
+export 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
+     */
+    code;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    constructor(payload) {
+        super(payload.message);
+        this.code = payload.code;
+        this.status = payload.status;
+        Object.assign(this, payload);
+    }
+    /**
+     * 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) {
+        return new AppError(payload);
+    }
+    /**
+     * 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) {
+        throw new AppError(payload);
+    }
+    /**
+     * 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) {
+        return new AppError({
+            code: ERROR_CODES.ABORTED,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.ABORTED],
+            status: STATUS_CODES.ABORTED,
+            name,
+            cause: new Error('The client closed the connection before the server finished responding.'),
+        });
+    }
+    /**
+     * 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, name) {
+        if (Guards.isDefined(signal) && signal.aborted) {
+            throw AppError.aborted(name);
+        }
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.UNAUTHORIZED,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.UNAUTHORIZED],
+            status: STATUS_CODES.UNAUTHORIZED,
+            name,
+            cause: new Error(message),
+            header: { 'WWW-Authenticate': ['Bearer realm="api"'] },
+        });
+    }
+    static notSupported(name, message) {
+        return AppError.create({
+            code: ERROR_CODES.NOT_ALLOWED,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.NOT_ALLOWED],
+            status: STATUS_CODES.NOT_ALLOWED,
+            name,
+            cause: new Error(message),
+        });
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.FORBIDDEN,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.FORBIDDEN],
+            status: STATUS_CODES.FORBIDDEN,
+            name,
+            cause: new Error(message),
+        });
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.BAD_REQUEST,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.BAD_REQUEST],
+            status: STATUS_CODES.BAD_REQUEST,
+            name,
+            cause: new Error(message),
+        });
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.VALIDATION_FAILED,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.VALIDATION_FAILED],
+            status: STATUS_CODES.BAD_REQUEST,
+            name,
+            cause: new Error(message),
+        });
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.CONFLICT,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.CONFLICT],
+            status: STATUS_CODES.CONFLICT,
+            name,
+            cause: new Error(message),
+        });
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.NOT_FOUND,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.NOT_FOUND],
+            status: STATUS_CODES.NOT_FOUND,
+            name,
+            cause: new Error(message),
+        });
+    }
+    /** @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, message) {
+        return AppError.create({
+            code: ERROR_CODES.AUTHENTICATION_FAILED,
+            message: ERROR_CODE_MESSAGES[ERROR_CODES.AUTHENTICATION_FAILED],
+            name,
+            status: STATUS_CODES.UNAUTHORIZED,
+            cause: new Error(message),
+        });
+    }
+}
+//# sourceMappingURL=app-error.js.map

package/dist/domain/errors/app-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.js","sourceRoot":"","sources":["../../../src/domain/errors/app-error.ts"],"names":[],"mappings":"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"}

package/dist/domain/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from './app-error';
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/dist/domain/errors/index.js

@@ -0,0 +1,2 @@
+export * from './app-error';
+//# sourceMappingURL=index.js.map

package/dist/domain/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/domain/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/dist/domain/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './config/index';
+export type * from './contracts/index';
+export * from './entities/index';
+export * from './errors/index';
+export * from './results/index';
+export * from './unique_id/index';
+export * from './value_objects/index';
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,gBAAgB,CAAA;AACnC,mBAAmB,mBAAmB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA"}

package/dist/domain/index.js

@@ -0,0 +1,6 @@
+export * from './entities/index';
+export * from './errors/index';
+export * from './results/index';
+export * from './unique_id/index';
+export * from './value_objects/index';
+//# sourceMappingURL=index.js.map

package/dist/domain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA"}

package/dist/domain/results/__tests__/result.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=result.test.d.ts.map

package/dist/domain/results/__tests__/result.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.test.d.ts","sourceRoot":"","sources":["../../../../src/domain/results/__tests__/result.test.ts"],"names":[],"mappings":""}

package/dist/domain/results/__tests__/result.test.js

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { Result } from '../../../domain';
+describe('Result', () => {
+    describe('ok', () => {
+        it('creates a successful result and returns its value', () => {
+            const result = Result.ok('value');
+            expect(result.isOk()).toBe(true);
+            expect(result.getValueOrThrow()).toBe('value');
+        });
+        it('supports undefined as a valid success payload', () => {
+            const result = Result.ok();
+            expect(result.isOk()).toBe(true);
+            expect(result.getValueOrThrow()).toBeUndefined();
+        });
+        it('throws when requesting value from a failed result', () => {
+            const result = Result.fail('domain-error');
+            expect(() => result.getValueOrThrow()).toThrowError('Cannot get the value of a failed result.');
+        });
+        it('supports complex objects as success payloads', () => {
+            const payload = { id: '123', name: 'Alice' };
+            const result = Result.ok(payload);
+            expect(result.isOk()).toBe(true);
+            expect(result.getValueOrThrow()).toEqual(payload);
+        });
+        it('supports generic type parameters for value and error', () => {
+            const result = Result.ok(42);
+            expect(result.isOk()).toBe(true);
+            expect(result.getValueOrThrow()).toBe(42);
+        });
+        it('supports null as a valid success payload', () => {
+            const result = Result.ok(null);
+            expect(result.isOk()).toBe(true);
+            expect(result.getValueOrThrow()).toBeNull();
+        });
+    });
+    describe('fail', () => {
+        it('creates a failed result and returns its error', () => {
+            const error = new Error('failure');
+            const result = Result.fail(error);
+            expect(result.isOk()).toBe(false);
+            expect(result.getErrorOrThrow()).toBe(error);
+        });
+        it('supports non-Error failure values', () => {
+            const result = Result.fail('domain-error');
+            expect(result.isOk()).toBe(false);
+            expect(result.getErrorOrThrow()).toBe('domain-error');
+        });
+        it('throws when requesting value from a failed result', () => {
+            const result = Result.fail('domain-error');
+            expect(() => result.getValueOrThrow()).toThrowError('Cannot get the value of a failed result.');
+        });
+    });
+    describe('isOk', () => {
+        it('returns true for successful results', () => {
+            const result = Result.ok('value');
+            expect(result.isOk()).toBe(true);
+        });
+        it('returns false for failed results', () => {
+            const result = Result.fail('domain-error');
+            expect(result.isOk()).toBe(false);
+        });
+        it('returns true for successful results with undefined payload', () => {
+            const result = Result.ok();
+            expect(result.isOk()).toBe(true);
+        });
+        it('returns false for failed results with non-Error payload', () => {
+            const result = Result.fail('domain-error');
+            expect(result.isOk()).toBe(false);
+        });
+        it('returns true for successful results with null payload', () => {
+            const result = Result.ok(null);
+            expect(result.isOk()).toBe(true);
+        });
+    });
+    describe('getValueOrThrow', () => {
+        it('returns the value for successful results', () => {
+            const result = Result.ok('value');
+            expect(result.getValueOrThrow()).toBe('value');
+        });
+        it('throws an error when called on a failed result', () => {
+            const result = Result.fail('domain-error');
+            expect(() => result.getValueOrThrow()).toThrowError('Cannot get the value of a failed result.');
+        });
+        it('returns undefined for successful results with undefined payload', () => {
+            const result = Result.ok();
+            expect(result.getValueOrThrow()).toBeUndefined();
+        });
+        it('returns null for successful results with null payload', () => {
+            const result = Result.ok(null);
+            expect(result.getValueOrThrow()).toBeNull();
+        });
+    });
+    describe('getErrorOrThrow', () => {
+        it('returns the error for failed results', () => {
+            const error = new Error('failure');
+            const result = Result.fail(error);
+            expect(result.getErrorOrThrow()).toBe(error);
+        });
+        it('throws an error when called on a successful result', () => {
+            const result = Result.ok('value');
+            expect(() => result.getErrorOrThrow()).toThrowError('Cannot get the error of a successful result.');
+        });
+        it('returns non-Error payloads for failed results', () => {
+            const result = Result.fail('domain-error');
+            expect(result.getErrorOrThrow()).toBe('domain-error');
+        });
+    });
+});
+//# sourceMappingURL=result.test.js.map

package/dist/domain/results/__tests__/result.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.test.js","sourceRoot":"","sources":["../../../../src/domain/results/__tests__/result.test.ts"],"names":[],"mappings":"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"}

package/dist/domain/results/index.d.ts

@@ -0,0 +1,3 @@
+export * from './result';
+export type * from './result.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/results/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/domain/results/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,mBAAmB,gBAAgB,CAAA"}

package/dist/domain/results/index.js

@@ -0,0 +1,2 @@
+export * from './result';
+//# sourceMappingURL=index.js.map

package/dist/domain/results/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/domain/results/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA"}

package/dist/domain/results/result.d.ts

@@ -0,0 +1,125 @@
+import type { Optional } from '../../shared';
+/**
+ * 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
+   */
+export 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;
+}
+//# sourceMappingURL=result.d.ts.map

package/dist/domain/results/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/domain/results/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC;;;;;;;;;;;;KAYK;AACL,qBAAa,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK;IACxC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC;;;;;;;;;;;;OAYG;IACH,OAAO;IAMP;;;;;;;;;;;OAWG;WACW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAIzC;;;;;;;;;;;OAWG;WACW,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAIxD;;;;;;;;;;OAUG;IACI,IAAI,IAAI,OAAO;IAItB;;;;;;;;;;;OAWG;IACI,eAAe,IAAI,QAAQ,CAAC,MAAM,CAAC;IAO1C;;;;;;;;;;;OAWG;IACI,eAAe,IAAI,MAAM;CAMjC"}