@xeno-js/shared 0.1.0

package/dist/domain/entities/__tests__/entity.test.js

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { UniqueId } from '../../../domain';
+import { GuidHelper } from '../../../shared';
+import { Entity } from '../entity';
+class SampleEntity extends Entity {
+    constructor(props, id) {
+        super(props, id);
+    }
+}
+describe('Entity', () => {
+    it('creates a new UniqueId when no id is provided', () => {
+        const props = { name: 'alice', tags: ['admin'] };
+        const entity = new SampleEntity(props);
+        expect(entity.id).toBeInstanceOf(UniqueId);
+        expect(entity.getProps()).toEqual(props);
+    });
+    it('uses the provided UniqueId when it is valid', () => {
+        const props = { name: 'bob', tags: ['user'] };
+        const id = GuidHelper.generate();
+        const entity = new SampleEntity(props, id);
+        expect(entity.id.getValue()).toBe(id);
+        expect(entity.getProps()).toEqual(props);
+    });
+    it('throws when an invalid UniqueId is provided', () => {
+        const props = { name: 'carol', tags: [] };
+        const invalidId = 'not-a-guid';
+        expect(() => new SampleEntity(props, invalidId)).toThrow(`Invalid UniqueId provided: ${invalidId}.`);
+    });
+    it('getProps returns the properties of the entity', () => {
+        const props = { name: 'dave', tags: ['editor'] };
+        const entity = new SampleEntity(props);
+        expect(entity.getProps()).toEqual(props);
+    });
+    it('properties are immutable', () => {
+        const props = { name: 'eve', tags: ['viewer'] };
+        const entity = new SampleEntity(props);
+        const retrievedProps = entity.getProps();
+        retrievedProps.name = 'mallory';
+        retrievedProps.tags.push('hacker');
+        expect(entity.getProps()).toEqual(props);
+    });
+    it('entity instance is frozen', () => {
+        const props = { name: 'frank', tags: ['contributor'] };
+        const entity = new SampleEntity(props);
+        expect(Object.isFrozen(entity)).toBe(true);
+    });
+    it('getId returns the UniqueId of the entity', () => {
+        const props = { name: 'grace', tags: ['moderator'] };
+        const entity = new SampleEntity(props);
+        expect(entity.getId()).toBe(entity.id);
+    });
+});
+//# sourceMappingURL=entity.test.js.map

package/dist/domain/entities/__tests__/entity.test.js.map

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

package/dist/domain/entities/entity.d.ts

@@ -0,0 +1,43 @@
+import type { Optional } from '../../shared';
+import { UniqueId } from '../unique_id/unique-id';
+import type { IEntity } from './ientity.contracts';
+/**
+ * A base class representing a generic entity in the domain. An entity is an object that has a unique identity and is defined by its properties.
+ *
+ * @template T - The type of the properties of the entity.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare abstract class Entity<T> implements IEntity<T> {
+    readonly id: UniqueId;
+    /**
+     * The properties of the entity. This is a private property that holds the state of the entity. It should be accessed and modified through methods defined in the concrete entity classes to ensure encapsulation and maintain invariants.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private readonly props;
+    /**
+     * Protected constructor to prevent direct instantiation. Concrete entity classes should extend this base class and call this constructor with the appropriate properties and an optional unique identifier.
+     *
+     * @param props - The properties of the entity.
+     * @param id - An optional unique identifier for the entity. If not provided, a new UniqueId will be generated.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    protected constructor(props: T, id?: Optional<string>);
+    getProps(): T;
+    getId(): UniqueId;
+}
+//# sourceMappingURL=entity.d.ts.map

package/dist/domain/entities/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/domain/entities/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGxC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD;;;;;;;;;;KAUK;AACL,8BAAsB,MAAM,CAAC,CAAC,CAAE,YAAW,OAAO,CAAC,CAAC,CAAC;IACnD,SAAgB,EAAE,EAAE,QAAQ,CAAA;IAE5B;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAG;IAEzB;;;;;;;;;;;OAWG;IACH,SAAS,aAAa,KAAK,EAAE,CAAC,EAAE,EAAE,GAAE,QAAQ,CAAC,MAAM,CAAa;IAUzD,QAAQ,IAAI,CAAC;IAIb,KAAK,IAAI,QAAQ;CAGzB"}

package/dist/domain/entities/entity.js

@@ -0,0 +1,55 @@
+import { Guards, GuidHelper } from '../../shared';
+import { UniqueId } from '../unique_id/unique-id';
+/**
+ * A base class representing a generic entity in the domain. An entity is an object that has a unique identity and is defined by its properties.
+ *
+ * @template T - The type of the properties of the entity.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export class Entity {
+    id;
+    /**
+     * The properties of the entity. This is a private property that holds the state of the entity. It should be accessed and modified through methods defined in the concrete entity classes to ensure encapsulation and maintain invariants.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    props;
+    /**
+     * Protected constructor to prevent direct instantiation. Concrete entity classes should extend this base class and call this constructor with the appropriate properties and an optional unique identifier.
+     *
+     * @param props - The properties of the entity.
+     * @param id - An optional unique identifier for the entity. If not provided, a new UniqueId will be generated.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    constructor(props, id = undefined) {
+        if (Guards.isNullOrEmpty(id) || GuidHelper.isValid(id)) {
+            this.id = UniqueId.create(id);
+        }
+        else {
+            throw new Error(`Invalid UniqueId provided: ${id}.`);
+        }
+        this.props = Object.freeze({ ...props });
+        Object.freeze(this);
+    }
+    getProps() {
+        return structuredClone(this.props);
+    }
+    getId() {
+        return this.id;
+    }
+}
+//# sourceMappingURL=entity.js.map

package/dist/domain/entities/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../../src/domain/entities/entity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE7C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEjD;;;;;;;;;;KAUK;AACL,MAAM,OAAgB,MAAM;IACV,EAAE,CAAU;IAE5B;;;;;;;;OAQG;IACc,KAAK,CAAG;IAEzB;;;;;;;;;;;OAWG;IACH,YAAsB,KAAQ,EAAE,KAAuB,SAAS;QAC9D,IAAI,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YACvD,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QAC/B,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAA;QACtD,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAA;QACxC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;IAEM,QAAQ;QACb,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpC,CAAC;IAEM,KAAK;QACV,OAAO,IAAI,CAAC,EAAE,CAAA;IAChB,CAAC;CACF"}

package/dist/domain/entities/ientity.contracts.d.ts

@@ -0,0 +1,43 @@
+import type { UniqueId } from '../unique_id/unique-id';
+/**
+ * An interface representing a generic entity in the domain. An entity is an object that has a unique identity and is defined by its properties.
+ *
+ * @template T - The type of the properties of the entity.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export interface IEntity<T> {
+    /**
+     * The unique identifier of the entity. This is a read-only property that should be assigned when the entity is created and should not change throughout the lifecycle of the entity.
+     * @see UniqueId for more details on the unique identifier.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly id: UniqueId;
+    /** Retrieves the properties of the entity.
+     *
+     * @returns The properties of the entity.
+     * @throws An error if the entity is in an invalid state or if the properties cannot be retrieved.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    getProps(): T;
+    /** Retrieves the unique identifier of the entity.
+     *
+     * @returns The unique identifier of the entity.
+     */
+    getId(): UniqueId;
+}
+//# sourceMappingURL=ientity.contracts.d.ts.map

package/dist/domain/entities/ientity.contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ientity.contracts.d.ts","sourceRoot":"","sources":["../../../src/domain/entities/ientity.contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD;;;;;;;;;;KAUK;AACL,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAA;IAErB;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,CAAC,CAAA;IAEb;;;OAGG;IACH,KAAK,IAAI,QAAQ,CAAA;CAClB"}

package/dist/domain/entities/ientity.contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ientity.contracts.js.map

package/dist/domain/entities/ientity.contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ientity.contracts.js","sourceRoot":"","sources":["../../../src/domain/entities/ientity.contracts.ts"],"names":[],"mappings":""}

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

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

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

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

package/dist/domain/entities/index.js

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

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

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

package/dist/domain/errors/__tests__/app-error.test.d.ts

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

package/dist/domain/errors/__tests__/app-error.test.d.ts.map

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

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

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { AppError } from '../app-error';
+describe('AppError', () => {
+    it('creates an AppError with the provided message, code, status, name, and cause', () => {
+        const error = AppError.create({
+            message: 'Something went wrong',
+            code: 'ERROR_CODE',
+            status: 400,
+            name: 'TestError',
+            cause: new Error('Underlying error'),
+        });
+        expect(error).toBeInstanceOf(AppError);
+        expect(error.name).toBe('TestError');
+        expect(error.message).toBe('Something went wrong');
+        expect(error.code).toBe('ERROR_CODE');
+        expect(error.status).toBe(400);
+        expect(error.cause).toBeInstanceOf(Error);
+    });
+    it('supports undefined as a valid cause', () => {
+        const error = AppError.create({
+            message: 'Failed to process request',
+            code: 'PROCESSING_ERROR',
+            status: 500,
+            name: 'TestError',
+            cause: undefined,
+        });
+        expect(error.cause).toBeUndefined();
+    });
+    it('supports null as a valid cause', () => {
+        const error = AppError.create({
+            message: 'Failed to process request',
+            code: 'PROCESSING_ERROR',
+            status: 500,
+            name: 'TestError',
+            cause: null,
+        });
+        expect(error.cause).toBeNull();
+    });
+    it('throws an AppError when using the throw method', () => {
+        expect(() => AppError.throw({
+            message: 'Unauthorized access',
+            code: 'UNAUTHORIZED',
+            status: 401,
+            name: 'TestError',
+            cause: new Error('Invalid credentials'),
+        })).toThrowError(AppError);
+    });
+    it('creates an aborted AppError with the correct properties', () => {
+        const error = AppError.aborted('TestContext');
+        expect(error).toBeInstanceOf(AppError);
+        expect(error.name).toBe('TestContext');
+        expect(error.message).toBe('errors.aborted');
+        expect(error.code).toBe('ABORTED');
+        expect(error.status).toBe(499);
+        expect(error.cause).toBeInstanceOf(Error);
+        expect(error.cause).toEqual(new Error('The client closed the connection before the server finished responding.'));
+    });
+    it('throws an AppError when signal is aborted', () => {
+        const abortController = new AbortController();
+        abortController.abort();
+        expect(() => AppError.throwIfAborted(abortController.signal, 'TestContext')).toThrowError(AppError);
+    });
+    it('does not throw when signal is not aborted', () => {
+        const abortController = new AbortController();
+        expect(() => AppError.throwIfAborted(abortController.signal, 'TestContext')).not.toThrow();
+    });
+    it('does not throw when signal is undefined', () => {
+        expect(() => AppError.throwIfAborted(undefined, 'TestContext')).not.toThrow();
+    });
+    it('does not throw when signal is null', () => {
+        expect(() => AppError.throwIfAborted(null, 'TestContext')).not.toThrow();
+    });
+    it('is an instance of the built-in Error class', () => {
+        const error = AppError.create({
+            message: 'An error occurred',
+            code: 'ERROR_CODE',
+            status: 500,
+            name: 'TestError',
+            cause: new Error('Underlying error'),
+        });
+        expect(error).toBeInstanceOf(Error);
+    });
+    it('has a stack trace', () => {
+        const error = AppError.create({
+            message: 'An error occurred',
+            code: 'ERROR_CODE',
+            status: 500,
+            name: 'TestError',
+            cause: new Error('Underlying error'),
+        });
+        expect(error.stack).toBeDefined();
+    });
+});
+//# sourceMappingURL=app-error.test.js.map

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

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

package/dist/domain/errors/app-error.d.ts

@@ -0,0 +1,243 @@
+import type { Maybe, Optional } 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
+   */
+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
+   */
+export 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;
+}
+export {};
+//# sourceMappingURL=app-error.d.ts.map

package/dist/domain/errors/app-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/app-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAE/C;;;;;;;;;KASK;AACL,UAAU,YAAY;IACpB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACxB;;;;;;OAMG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;;KASK;AACL,qBAAa,QAAS,SAAQ,KAAK;IACjC;;;;;;;;OAQG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B;;;;;;;;OAQG;IACH,SAAgB,MAAM,EAAE,MAAM,CAAA;IAE9B;;;;;;;OAOG;IACH,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAE/B;;;;;;;;;;OAUG;IACH,OAAO;IAOP;;;;;;;;;;;OAWG;WACW,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ;IAIrD;;;;;;;;;;OAUG;WACW,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK;IAIjD;;;;;;;;;;OAUG;WACW,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAU7C;;;;;;;;;;OAUG;WACW,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAM5E;;;;;;;;;OASG;WACW,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;WAWrD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAUnE;;;;;;;;;OASG;WACW,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAUhE;;;;;;;;;OASG;WACW,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAUjE;;;;;;;;;OASG;WACW,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAUtE;;;;;;;;;OASG;WACW,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAU/D;;;;;;;;;OASG;WACW,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAU/D;;;;;;;;;OASG;WACW,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;CASlE"}