@xeno-js/shared 2.0.0 → 3.0.0

package/dist/supabase.js

@@ -0,0 +1,2402 @@
+// src/shared/constants/concurrency.constants.ts
+var DEFAULT_CONCURRENCY = Object.freeze({
+  /**
+   * @description Number of maximum retry attempts for handling concurrency conflicts in the pipeline. If the number of attempts exceeds this value, the pipeline will return a failed Result with an AppError indicating that the maximum retry attempts have been exceeded due to concurrency conflicts.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  MAX_RETRIES: 3,
+  /**
+   * @description Base delay in milliseconds for retrying a request after a concurrency conflict is detected. The actual delay will be calculated using an exponential backoff strategy with added jitter to prevent thundering herd problems when multiple requests are retried simultaneously.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  BASE_DELAY: 20,
+  /**
+   * @description Maximum jitter in milliseconds to be added to the base delay when retrying a request after a concurrency conflict is detected. This helps to randomize the retry attempts and reduce the likelihood of multiple requests being retried at the same time, which can lead to further conflicts. The actual delay for each retry will be calculated as baseDelayMs * (2 ** attempt) + randomJitter, where randomJitter is a random value between 0 and maxJitterMs.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  MAX_JITTER: 30
+});
+
+// src/shared/constants/error.constants.ts
+var ERROR_CODES = Object.freeze({
+  // ── Generic / System ─────────────────────────────────────────────────────
+  /** @description Unclassified or unexpected infrastructure-level failure.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SYSTEM_ERROR: "SYSTEM_ERROR",
+  /** @description An operation that has not yet been implemented was invoked.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  NOT_IMPLEMENTED: "NOT_IMPLEMENTED",
+  /** @description An external API call failed due to network issues or a 5xx response.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR",
+  /** @description One or more input fields failed invariant or schema validation.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  /** @description Authentication failed due to invalid credentials or token.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  AUTHENTICATION_FAILED: "AUTHENTICATION_FAILED",
+  /** @description The caller is not authenticated.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  UNAUTHORIZED: "UNAUTHORIZED",
+  /** @description The caller is authenticated but lacks the required permissions.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  FORBIDDEN: "FORBIDDEN",
+  /** @description The request was well-formed but semantically invalid.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  BAD_REQUEST: "BAD_REQUEST",
+  /** @description The request was aborted before it could be processed.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  ABORTED: "ABORTED",
+  /** @description Required service scope is not available in the request context.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SCOPE_NOT_AVAILABLE: "SCOPE_NOT_AVAILABLE",
+  /** @description The request conflicts with the current state of the resource.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CONFLICT: "CONFLICT",
+  /** @description The requested resource does not exist.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  NOT_FOUND: "NOT_FOUND",
+  /** @description No handler was found for the given request type.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  HANDLER_NOT_FOUND: "HANDLER_NOT_FOUND",
+  /** @description No pipeline behavior was found for the given request type.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  PIPELINE_NOT_AVAILABLE: "PIPELINE_NOT_AVAILABLE",
+  NOT_ALLOWED: "METHOD_NOT_ALLOWED",
+  TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS"
+});
+var STATUS_CODES = Object.freeze({
+  // ── 2xx Success ───────────────────────────────────────────────────────────
+  /** @description The request succeeded and a response body is present.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  OK: 200,
+  /** @description A new resource has been successfully created.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CREATED: 201,
+  /** @description The request succeeded but there is no response body (e.g. DELETE).
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  NO_CONTENT: 204,
+  // ── 4xx Client Errors ─────────────────────────────────────────────────────
+  /** @description The request payload is malformed or contains invalid parameters.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  BAD_REQUEST: 400,
+  /** @description Authentication credentials are missing or invalid.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  UNAUTHORIZED: 401,
+  /** @description The caller lacks permission to perform the requested operation.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  FORBIDDEN: 403,
+  /** @description The requested resource does not exist.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  NOT_FOUND: 404,
+  NOT_ALLOWED: 405,
+  /** @description The request conflicts with the current state of the resource.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CONFLICT: 409,
+  /** @description The payload is syntactically valid but semantically unprocessable.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  UNPROCESSABLE_ENTITY: 422,
+  /** @description The caller has exceeded its allowed rate limit.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  TOO_MANY_REQUESTS: 429,
+  /** @description The client closed the connection before the server finished responding.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  ABORTED: 499,
+  // ── 5xx Server Errors ─────────────────────────────────────────────────────
+  /** @description An unexpected condition was encountered by the server.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  INTERNAL_SERVER_ERROR: 500,
+  /** @description A downstream dependency is temporarily unavailable.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SERVICE_UNAVAILABLE: 503
+});
+var ERROR_CODE_MESSAGES = Object.freeze({
+  [ERROR_CODES.SYSTEM_ERROR]: "errors.system_error",
+  [ERROR_CODES.NOT_IMPLEMENTED]: "errors.not_implemented",
+  [ERROR_CODES.EXTERNAL_SERVICE_ERROR]: "errors.external_service_error",
+  [ERROR_CODES.VALIDATION_FAILED]: "errors.validation_failed",
+  [ERROR_CODES.UNAUTHORIZED]: "errors.unauthorized",
+  [ERROR_CODES.FORBIDDEN]: "errors.forbidden",
+  [ERROR_CODES.BAD_REQUEST]: "errors.bad_request",
+  [ERROR_CODES.ABORTED]: "errors.aborted",
+  [ERROR_CODES.AUTHENTICATION_FAILED]: "errors.authentication_failed",
+  [ERROR_CODES.SCOPE_NOT_AVAILABLE]: "errors.scope_not_available",
+  [ERROR_CODES.CONFLICT]: "errors.conflict",
+  [ERROR_CODES.NOT_FOUND]: "errors.not_found",
+  [ERROR_CODES.HANDLER_NOT_FOUND]: "errors.handler_not_found",
+  [ERROR_CODES.PIPELINE_NOT_AVAILABLE]: "errors.pipeline_not_available",
+  [ERROR_CODES.NOT_ALLOWED]: "errors.method_not_allowed",
+  [ERROR_CODES.TOO_MANY_REQUESTS]: "errors.too_many_requests"
+});
+
+// src/shared/constants/roles.constants.ts
+var ROLES = Object.freeze({
+  /** @description The SUPER_ADMIN role, which typically has the highest level of permissions and access within the application.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SUPER_ADMIN: "super_admin",
+  /** @description The ADMIN role, which typically has elevated permissions and access within the application, but may have some restrictions compared to the SUPER_ADMIN role.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  ADMIN: "admin",
+  /** @description The USER role, which typically has standard permissions and access within the application, allowing them to perform regular user actions but with limited administrative capabilities.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  USER: "user",
+  /** @description The GUEST role, which typically has the most limited permissions and access within the application, often used for unauthenticated users or users with very restricted access.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  GUEST: "guest"
+});
+var PERMISSIONS = Object.freeze({
+  /** @description The READ permission, which typically allows access to resources or actions within the application that require read-only access.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  READ: "read"
+});
+
+// src/shared/constants/guest.constants.ts
+var GUEST = Object.freeze({
+  /** @description The unique identifier for the guest user, which is set to undefined since guest users do not have a specific user ID. This allows the application to differentiate between authenticated users with valid IDs and unauthenticated guest users.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  userId: void 0,
+  /** @description The email for guest user, which is set to undefined since guest users do not have a specific email.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  email: void 0,
+  /** @description The unique identifier for the tenant associated with the guest user, which is set to undefined since guest users do not belong to a specific tenant. This allows the application to handle multi-tenancy scenarios while still accommodating unauthenticated users who do not have an associated tenant.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  tenantId: void 0,
+  /** @description An array of roles assigned to the guest user, which includes only the GUEST role. This indicates that the user has minimal access rights and is typically used to represent unauthenticated users or users with limited permissions in the application.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  roles: [ROLES.GUEST],
+  /** @description An array of permissions assigned to the guest user, which is empty since guest users do not have any specific permissions. This reinforces the idea that guest users have minimal access rights and cannot perform actions that require specific permissions in the application.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  permissions: [PERMISSIONS.READ]
+});
+
+// src/shared/constants/idempotency.constants.ts
+var IDEMPOTENCY_CONSTANTS = Object.freeze({
+  /**
+   * @description Prefix for keys used to store locks in the idempotency store. This prefix is used to differentiate lock entries from other types of entries in the cache, allowing for efficient management of locks when acquiring and releasing them during command processing. The lock key prefix helps ensure that lock-related data is organized and easily identifiable within the caching mechanism.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  LOCK_KEY_PREFIX: "idempotency_lock:",
+  /**
+   * @description Prefix for keys used to store processed command results in the idempotency store. This prefix is used to differentiate processed command entries from lock entries and other types of data in the cache, allowing for efficient retrieval of stored results when checking if a command has already been processed. The processed key prefix helps maintain a clear structure within the caching mechanism, making it easier to manage and query processed command data.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  PROCESSED_KEY_PREFIX: "idempotency_processed:",
+  /**
+   * @description Default time-to-live (TTL) in seconds for locks and processed command entries in the idempotency store. This value is used when acquiring locks and marking commands as processed to specify how long the lock or stored result should remain valid before it expires. The default TTL helps ensure that locks and processed command entries do not persist indefinitely, allowing for automatic cleanup of stale data and preventing potential issues with long-lived locks or outdated results in the idempotency store.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  DEFAULT_TTL_SECONDS: 86400,
+  /**
+   * @description Default time-to-live (TTL) in seconds for locks in the idempotency store. This value is used when acquiring locks to specify how long the lock should remain valid before it expires. The default lock TTL helps ensure that locks do not persist indefinitely, allowing for automatic cleanup of stale locks and preventing potential issues with long-lived locks in the idempotency mechanism.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  DEFAULT_IDEMPOTENCY_LOCK_TTL_SECONDS: 60,
+  /**
+   * @description Standard value used to indicate that a lock has been acquired for a specific commandId in the idempotency store. This value is stored in the cache when a lock is successfully acquired, allowing other instances of the command to recognize that the command is currently being processed and prevent duplicate processing. The locked value serves as a marker for active locks in the idempotency mechanism, helping to manage concurrent command processing effectively.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  LOCKED_VALUE: "LOCKED",
+  /**
+   * @description Standard value used to indicate that a command has been processed and its result has been stored in the idempotency store. This value is stored in the cache when a command is marked as processed, allowing subsequent attempts to process the same commandId to recognize that it has already been handled and return the stored result instead of executing the command again. The processed value serves as a marker for completed commands in the idempotency mechanism, helping to manage command processing outcomes and prevent redundant executions.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  PROCESSED_VALUE: "PROCESSED"
+});
+
+// src/shared/constants/log-level.constants.ts
+var LOG_LEVEL = Object.freeze({
+  /** * Debug level for detailed debugging information. This level is typically used during development and should be turned off in production to avoid verbose logging.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  DEBUG: 0,
+  /** * Info level for general informational messages that highlight the progress of the application at a coarse-grained level. This level is suitable for production environments to track the normal operation of the application.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  INFO: 1,
+  /** * Warn level for potentially harmful situations that are not necessarily errors but may require attention. This level is useful for identifying issues that could lead to errors if not addressed.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  WARN: 2,
+  /** * Error level for serious issues that have caused or are likely to cause the application to fail. This level is critical for identifying and addressing problems that need immediate attention.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  ERROR: 3
+});
+var LOG_LEVEL_NAMES = {
+  /** Debug level for detailed debugging information. This level is typically used during development and should be turned off in production to avoid verbose logging.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  [LOG_LEVEL.DEBUG]: "DEBUG",
+  /** Info level for general informational messages that highlight the progress of the application at a coarse-grained level. This level is suitable for production environments to track the normal operation of the application.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  [LOG_LEVEL.INFO]: "INFO",
+  /** Warn level for potentially harmful situations that are not necessarily errors but may require attention. This level is useful for identifying issues that could lead to errors if not addressed.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  [LOG_LEVEL.WARN]: "WARN",
+  /** Error level for serious issues that have caused or are likely to cause the application to fail. This level is critical for identifying and addressing problems that need immediate attention.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  [LOG_LEVEL.ERROR]: "ERROR"
+};
+
+// src/shared/constants/pagination.constants.ts
+var DEFAULT_PAGE = 1;
+var DEFAULT_PAGE_SIZE = 20;
+var MAX_PAGE_SIZE = 100;
+var PAGINATION_DEFAULTS = Object.freeze({
+  /** @description Default page index (1-based).
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  PAGE: DEFAULT_PAGE,
+  /** @description Default maximum items per page.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  PAGE_SIZE: DEFAULT_PAGE_SIZE,
+  /** @description Hard ceiling on page size accepted by the system.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  MAX_PAGE_SIZE
+});
+var SORT_DIRECTION = Object.freeze({
+  /** @description Ascending order (A → Z, 0 → 9, oldest → newest).
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  ASC: "asc",
+  /** @description Descending order (Z → A, 9 → 0, newest → oldest).
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  DESC: "desc"
+});
+
+// src/shared/constants/request.constants.ts
+var REQUEST_TYPE = Object.freeze({
+  /** @description A request that intends to modify state (e.g. create, update, delete).
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  COMMAND: "COMMAND",
+  /** @description A request that intends to retrieve data without modifying state.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  QUERY: "QUERY"
+});
+
+// src/shared/constants/resilience.constants.ts
+var RESILIENCE_DEFAULTS = Object.freeze({
+  /** @description Default retry policy values.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  RETRY: Object.freeze({
+    /** @description Default number of retry attempts.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    ATTEMPTS: 3,
+    /** @description Default base delay in milliseconds for retry backoff.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    BASE_DELAY_MS: 100,
+    /** @description Default maximum delay in milliseconds for retry backoff.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    MAX_DELAY_MS: 1e3
+  }),
+  /** @description Default circuit breaker policy values.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CIRCUIT_BREAKER: Object.freeze({
+    /** @description Default number of consecutive failures before opening the circuit.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    CONSECUTIVE_FAILURES: 5,
+    /** @description Default half-open timeout in milliseconds.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    HALF_OPEN_TIMEOUT_MS: 3e4
+  }),
+  /** @description Default bulkhead policy values.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  BULKHEAD: Object.freeze({
+    /** @description Default maximum number of concurrent operations.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    MAX_CONCURRENT: 10
+  })
+});
+
+// src/shared/constants/tokens.constants.ts
+var TOKENS = Object.freeze({
+  /** @description Token used to register and resolve the Extendend AuthService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  AUTH_SERVICE: "AUTH_SERVICE",
+  /** @description Token used to register and resolve the BaseAuthService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  BASE_AUTH_SERVICE: "BASE_AUTH_SERVICE",
+  /** @description Token used to register and resolve the InMemoryCache instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CACHE: "CACHE",
+  /** @description Token used to register and resolve the CacheKeyBuilder instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CACHE_KEY_BUILDER: "CACHE_KEY_BUILDER",
+  /** @description Token used to register and resolve command pipeline behaviors in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  COMMAND_PIPELINES_BEHAVIOR: "COMMAND_PIPELINES_BEHAVIOR",
+  /** @description Token used to register and resolve the ConcurrencyService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CONCURRENCY_SERVICE: "CONCURRENCY_SERVICE",
+  /** @description Token used to register and resolve the ConfigurationService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CONFIGURATION_SERVICE: "CONFIGURATION_SERVICE",
+  /** @description Token used to register and resolve the ContextAccessor instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CONTEXT_ACCESSOR: "CONTEXT_ACCESSOR",
+  /** @description Token used to register and resolve the CryptoService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CRYPTO_SERVICE: "CRYPTO_SERVICE",
+  /** @description Token used to register and resolve the CsrfTokenService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  CSRF_TOKEN_SERVICE: "CSRF_TOKEN_SERVICE",
+  /** @description Token used to register and resolve the DbContext instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  DB_CONTEXT: "DB_CONTEXT",
+  /** @description Token used to register and resolve the IdentityAccessor instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  IDENTITY_ACCESSOR: "IDENTITY_ACCESSOR",
+  /** @description Token used to register and resolve the Logger instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  LOGGER: "LOGGER",
+  /** @description Token used to register and resolve the Mediator instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  MEDIATOR: "MEDIATOR",
+  /** @description Token used to register and resolve the NetworkContextFactory in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  NETWORK_CONTEXT_ACCESSOR: "NETWORK_CONTEXT_ACCESSOR",
+  /** @description Token used to register and resolve query pipeline behaviors in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  QUERY_PIPELINES_BEHAVIOR: "QUERY_PIPELINES_BEHAVIOR",
+  /** @description Token used to register and resolve the RequestContext instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  REQUEST_CONTEXT: "REQUEST_CONTEXT",
+  /** @description Token used to register and resolve the CompositeMiddleware in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  MIDDLEWARE: "MIDDLEWARE",
+  /** @description Token used to register and resolve the IServiceResilience instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  RESILIENCE_CLIENT: "RESILIENCE_CLIENT",
+  /** @description Token used to register and resolve the SchemaValidationStrategy instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SCHEMA_VALIDATION_STRATEGY: "SCHEMA_VALIDATION_STRATEGY",
+  /** @description Token used to register and resolve the ServiceContainer instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SERVICE_CONTAINER: "SERVICE_CONTAINER",
+  /** @description Token used to register and resolve the ServiceExtractor instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SERVICE_EXTRACTOR: "SERVICE_EXTRACTOR",
+  /** @description Token used to register and resolve the ServiceScopeAccessor in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  SERVICE_SCOPE_ACCESSOR: "SERVICE_SCOPE_ACCESSOR",
+  /** @description Token used to register and resolve the UnitOfWork instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  UNIT_OF_WORK: "UNIT_OF_WORK",
+  /** @description Token used to register and resolve the ValidatorService instance in the dependency injection container.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  VALIDATOR_SERVICE: "VALIDATOR_SERVICE"
+});
+
+// src/shared/utils/guards.utils.ts
+var OBJECT_TAG = "[object Object]";
+var DATE_TAG = "[object Date]";
+var Guards = Object.freeze({
+  /**
+   * @description Checks value is neither null nor undefined.
+   * @param value Candidate value.
+   * @returns True when value is defined.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isDefined(value) {
+    return value !== null && value !== void 0 && value !== "" && !Number.isNaN(value);
+  },
+  /**
+   * @description Checks value is null, undefined, empty string, or false.
+   * @param value Candidate value.
+   * @returns True when value is null, undefined, empty string, or false.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isNullOrEmpty(value) {
+    return !Guards.isDefined(value) || Guards.isString(value) && value.trim() === "" || Guards.isArray(value) && value.length === 0;
+  },
+  /**
+   * @description Throws an error if the value is null, undefined, empty string, or false.
+   * @param value Candidate value.
+   * @param errorMessage Error message to throw if the check fails.
+   * @throws Error with the provided message if the value is null, undefined, empty string, or false.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  throwIfNullOrEmpty(value, errorMessage) {
+    if (Guards.isNullOrEmpty(value)) {
+      throw new Error(errorMessage);
+    }
+  },
+  /**
+   * @description Throws an error if the value is not a positive integer.
+   * @param value Candidate value.
+   * @param errorMessage Error message to throw if the check fails.
+   * @throws Error with the provided message if the value is not a positive integer.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  throwIfNegative(value, errorMessage) {
+    if (Guards.isInteger(value) && value < 0) {
+      throw new Error(errorMessage);
+    }
+  },
+  /**
+   * @description Throws an error if the value is not an integer.
+   * @param value Candidate value.
+   * @param errorMessage Error message to throw if the check fails.
+   * @throws Error with the provided message if the value is not an integer.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  throwIfNotInteger(value, errorMessage) {
+    if (!Guards.isInteger(value)) {
+      throw new Error(errorMessage);
+    }
+  },
+  /**
+   * @description Checks if an object has a method with the given name.
+   * @param obj Object to check.
+   * @param methodName Name of the method to look for.
+   * @returns True when obj has a function property named methodName.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  hasMethod(obj, methodName) {
+    if (!this.isDefined(obj)) return false;
+    return Guards.isFunction(obj[methodName]);
+  },
+  /**
+   * @description Checks value is a string.
+   * @param value Candidate value.
+   * @returns True when value is string.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isString(value) {
+    return typeof value === "string";
+  },
+  /**
+   * @description Checks value is a finite number.
+   * @param value Candidate value.
+   * @returns True when value is finite number.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+  },
+  /**
+   * @description Checks value is an integer number.
+   * @param value Candidate value.
+   * @returns True when value is integer number.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isInteger(value) {
+    return Guards.isNumber(value) && Number.isInteger(value);
+  },
+  /**
+   * @description Checks value is boolean.
+   * @param value Candidate value.
+   * @returns True when value is boolean.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isBoolean(value) {
+    return typeof value === "boolean";
+  },
+  /**
+   * @description Checks value is bigint.
+   * @param value Candidate value.
+   * @returns True when value is bigint.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isBigInt(value) {
+    return typeof value === "bigint";
+  },
+  /**
+   * @description Checks value is symbol.
+   * @param value Candidate value.
+   * @returns True when value is symbol.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isSymbol(value) {
+    return typeof value === "symbol";
+  },
+  /**
+   * @description Checks value is a function.
+   * @param value Candidate value.
+   * @returns True when value is function.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isFunction(value) {
+    return typeof value === "function";
+  },
+  /**
+   * @description Checks value is an array.
+   * @param value Candidate value.
+   * @returns True when value is array.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isArray(value) {
+    return Array.isArray(value);
+  },
+  /**
+   * @description Checks value is a Date instance with valid timestamp.
+   * @param value Candidate value.
+   * @returns True when value is valid Date.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isDate(value) {
+    if (Object.prototype.toString.call(value) !== DATE_TAG) {
+      return false;
+    }
+    return Number.isFinite(value.getTime());
+  },
+  /**
+   * @description Checks value is an Error instance.
+   * @param value Candidate value.
+   * @returns True when value is Error.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isError(value) {
+    return value instanceof Error;
+  },
+  /**
+   * @description Checks value is a plain object record.
+   * @param value Candidate value.
+   * @returns True when value is object record.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isObjectRecord(value) {
+    if (!Guards.isDefined(value)) {
+      return false;
+    }
+    return Object.prototype.toString.call(value) === OBJECT_TAG;
+  },
+  /**
+   * @description Checks value is an object (not null).
+   * @param value Candidate value.
+   * @returns True when value is object.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isObject(value) {
+    return typeof value === "object" && Guards.isDefined(value);
+  },
+  /**
+   * @description Checks value is PromiseLike.
+   * @param value Candidate value.
+   * @returns True when value has then function.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isPromiseLike(value) {
+    if (!Guards.isDefined(value)) {
+      return false;
+    }
+    if (!Guards.isObject(value) && !Guards.isFunction(value)) {
+      return false;
+    }
+    const thenMember = value["then"];
+    return Guards.isFunction(thenMember);
+  }
+});
+
+// src/shared/utils/abort.utils.ts
+var AbortSignalHelper = Object.freeze({
+  /**
+   * Executes a promise with an optional AbortSignal. If the signal is provided and is aborted, the promise will be rejected with the signal's reason.
+   * @template T - The type of the promise's resolved value.
+   * @param promise - The promise to execute.
+   * @param signal - An optional AbortSignal to cancel the promise.
+   * @returns A promise that resolves with the original promise's value or rejects if the signal is aborted.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link www.github.com/Mattia-Carcione/xeno-js
+   */
+  execute(promise, signal) {
+    if (!Guards.isDefined(signal)) return promise;
+    if (signal.aborted) return Promise.reject(new Error("Operation aborted"));
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        signal.removeEventListener("abort", onAbort);
+        reject(new Error("Operation aborted by the client."));
+      };
+      signal.addEventListener("abort", onAbort);
+      promise.then((res) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(res);
+      }).catch((_err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(new Error("Operation aborted by the client."));
+      });
+    });
+  }
+});
+
+// src/shared/utils/date.utils.ts
+var MS_PER_DAY = 864e5;
+var DateHelper = Object.freeze({
+  /**
+   * @description Converts a Date to an ISO 8601 string.
+   * @param date Input date.
+   * @returns ISO 8601 UTC string.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  toISOString(date) {
+    return date.toISOString();
+  },
+  /**
+   * @description Returns a new Date with the given number of days added.
+   * @param date Base date.
+   * @param days Number of days to add (negative values subtract).
+   * @returns New Date instance.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  addDays(date, days) {
+    return new Date(date.getTime() + days * MS_PER_DAY);
+  },
+  /**
+   * @description Checks whether a date has elapsed relative to a reference time.
+   * @param expiresAt Expiry date.
+   * @param nowMs Reference epoch in milliseconds (defaults to Date.now()).
+   * @returns True when expiresAt is in the past.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isExpired(expiresAt, nowMs) {
+    const now = nowMs ?? Date.now();
+    return expiresAt.getTime() < now;
+  },
+  /**
+   * @description Checks if one date is after another.
+   * @param after Date to check if it is after.
+   * @param before Date to check against.
+   * @returns True when after is after before.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isAfter(after, before) {
+    return Guards.isDate(after) && Guards.isDate(before) && after.getTime() > before.getTime();
+  },
+  /**
+   * @description Checks if a date is in the future relative to now.
+   * @param date Date to check.
+   * @returns True when date is in the future.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isFuture(date) {
+    return Guards.isDate(date) && date.getTime() > Date.now();
+  }
+});
+
+// src/shared/utils/enumerable.utils.ts
+var Enumerable = Object.freeze({
+  /**
+   * Retrieves the first element of an array that satisfies the provided predicate function. If no predicate is provided, it returns the first element of the array. If the array is empty or no elements satisfy the predicate, an error is thrown.
+   * @template T - The type of elements in the array.
+   * @param array - The array to search.
+   * @param predicate - An optional function to test each element.
+   * @returns The first element that satisfies the predicate.
+   * @throws {Error} If the array is empty or no elements satisfy the predicate.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link www.github.com/Mattia-Carcione/xeno-js
+   */
+  first(array, predicate) {
+    const item = Guards.isDefined(predicate) ? array.find(predicate) : array[0];
+    if (!Guards.isDefined(item)) {
+      throw new Error("Sequence contains no elements.");
+    }
+    return item;
+  },
+  /**
+   * Retrieves the first element of an array that satisfies the provided predicate function. If no predicate is provided, it returns the first element of the array. If the array is empty or no elements satisfy the predicate, undefined is returned.
+   * @template T - The type of elements in the array.
+   * @param array - The array to search.
+   * @param predicate - An optional function to test each element.
+   * @returns The first element that satisfies the predicate or undefined.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link www.github.com/Mattia-Carcione/xeno-js
+   */
+  firstOrDefault(array, predicate) {
+    const item = Guards.isDefined(predicate) ? array.find(predicate) : array[0];
+    return Guards.isDefined(item) ? item : void 0;
+  }
+});
+
+// src/shared/utils/guid.utils.ts
+var GuidHelper = Object.freeze({
+  /**
+   * @description Generates a cryptographically-random UUID v4.
+   * @returns Lowercase UUID v4 string.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  generate() {
+    return crypto.randomUUID();
+  },
+  /**
+   * @description Validates if a value is a valid GUID (UUID v4) and not empty.
+   * @param value The value to validate.
+   * @returns True if the value is a valid and non-empty GUID, false otherwise.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isValidGuid(value) {
+    const guid = value.toString();
+    return GuidHelper.isValid(guid) && !GuidHelper.isEmpty(guid);
+  },
+  /**
+   * @description Validates if a string is a valid UUID v4.
+   * @param value Candidate string to validate.
+   * @returns True if the string is a valid UUID v4, false otherwise.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isValid(value) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(value);
+  },
+  /**
+   * @description Converts a string to a GUID if it's valid.
+   * @param value The string to convert.
+   * @returns The GUID if the string is valid, otherwise undefined.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  parse(value) {
+    if (!Guards.isNullOrEmpty(value) && this.isValid(value) && !this.isEmpty(value)) {
+      return value;
+    }
+    return void 0;
+  },
+  /**
+   * @description Checks if a GUID is the empty GUID (all zeros).
+   * @param value The GUID to check.
+   * @returns True if the GUID is the empty GUID, false otherwise.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  isEmpty(value) {
+    const emptyGuid = "00000000-0000-0000-0000-000000000000";
+    return value === emptyGuid;
+  }
+});
+
+// src/shared/utils/http.utils.ts
+var HttpHelper = Object.freeze({
+  /**
+   * @description A function that masks the IP address in the given headers object.
+   * @param ip The IP address to mask.
+   * @returns The masked IP address.
+   */
+  maskIp(ip) {
+    if (!Guards.isDefined(ip)) return void 0;
+    if (ip.includes(".")) {
+      const parts = ip.split(".");
+      if (parts.length === 4) {
+        parts[3] = "x";
+        return parts.join(".");
+      }
+    }
+    if (ip.includes(":")) {
+      const parts = ip.split(":");
+      if (parts.length > 0) {
+        parts[parts.length - 1] = "x";
+        return parts.join(":");
+      }
+    }
+    return ip;
+  },
+  /**
+   * @description Normalizes HTTP headers by converting all header values to strings. If a header value is an array, it joins the array elements into a single string separated by commas. This method ensures that the headers are in a consistent format, which can be particularly useful when working with different HTTP client libraries that may represent headers in various ways. If the input headers are not defined or not an object, it returns an empty object.
+   * @param headers The input headers to be normalized, which can be of any type. The method checks if the headers are defined and are an object before processing them.
+   * @returns An object containing the normalized headers, where each header value is a string. If the input headers were not valid, it returns an empty object.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  normalizeHeaders(headers) {
+    if (!Guards.isDefined(headers) || !Guards.isObject(headers)) return {};
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+      if (!Guards.isDefined(value)) {
+        continue;
+      }
+      normalized[key] = Array.isArray(value) ? value.map((part) => String(part)).join(",") : String(value);
+    }
+    return normalized;
+  },
+  /**
+   * @description Sanitizes the origin URL by parsing it and extracting the origin part. If the URL is not valid or cannot be parsed or does not contain an origin, it returns undefined.
+   * @param url The URL to be sanitized.
+   * @returns The sanitized origin URL or undefined if the URL is not valid or cannot be parsed or does not contain an origin.
+   *
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  sanitizeOriginUrl(url) {
+    if (!Guards.isDefined(url)) return void 0;
+    try {
+      const parsed = new URL(url);
+      return parsed.origin;
+    } catch {
+      return void 0;
+    }
+  },
+  /**
+   * @description Generates a standardized successful HTTP response with the provided data, status code, metadata, and custom headers. The response includes a success flag set to true, the data payload, and any additional metadata. The headers include a default 'Content-Type' of 'application/json' along with any custom headers provided.
+   * @param data The actual data payload to be included in the successful response. This can be of any type and will be wrapped in a SuccessResponseDto structure.
+   * @param status The HTTP status code for the response, defaulting to 200 (OK) if not provided. This allows for flexibility in indicating different types of successful responses (e.g., 201 for created, 204 for no content).
+   * @param meta Optional metadata to be included in the response. This can contain additional information relevant to the response, such as pagination details, rate limit information, or any other contextual data that may be useful for clients consuming the API.
+   * @param customHeaders Optional custom HTTP headers to be included in the response. This allows for adding any additional headers that may be necessary for specific responses, such as caching directives, custom authentication headers, or other relevant information.
+   * @returns A ResponseDto object representing the successful HTTP response, containing the status code, success flag, headers, and data payload structured as a SuccessResponseDto.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  success(data, status = 200, meta = {}, customHeaders = {}) {
+    const successPayload = {
+      success: true,
+      data,
+      meta
+    };
+    return {
+      status,
+      ok: true,
+      headers: {
+        ...customHeaders,
+        "Content-Type": ["application/json"]
+      },
+      data: successPayload
+    };
+  },
+  /**
+   * @description Generates a standardized error HTTP response with the provided error details, status code, correlation ID, request ID, timestamp, and custom headers. The response includes a success flag set to false, an error object containing the error code, message, and optional details, as well as metadata such as correlation ID and request ID for tracking purposes. The headers include a default 'Content-Type' of 'application/json' along with any custom headers provided.
+   * @param dto An object containing the error details, including the error code, message, optional details, and optional path. This information is structured as an ErrorResponseDto and provides context about the error that occurred.
+   * @param status The HTTP status code for the response, defaulting to 500 (Internal Server Error) if not provided. This allows for flexibility in indicating different types of error responses (e.g., 400 for bad request, 404 for not found).
+   * @param customHeaders Optional custom HTTP headers to be included in the response. This allows for adding any additional headers that may be necessary for specific error responses, such as caching directives, custom authentication headers, or other relevant information.
+   * @returns A ResponseDto object representing the error HTTP response, containing the status code, success flag, headers, and data payload structured as an ErrorResponseDto.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  error(dto, status = STATUS_CODES.INTERNAL_SERVER_ERROR, customHeaders = void 0) {
+    const errorPayload = {
+      success: false,
+      error: {
+        code: dto.error.code,
+        message: dto.error.message,
+        details: dto.error.details,
+        path: dto.error.path
+      },
+      correlationId: dto.correlationId,
+      requestId: dto.requestId,
+      spanId: dto.spanId,
+      timestamp: DateHelper.toISOString(/* @__PURE__ */ new Date())
+    };
+    return {
+      status,
+      ok: false,
+      headers: {
+        "Content-Type": ["application/json"],
+        "X-Correlation-Id": [dto.correlationId],
+        "X-Request-Id": [dto.requestId],
+        "X-Span-Id": [dto.spanId ?? ""],
+        "Cache-Control": ["no-store, no-cache, must-revalidate, proxy-revalidate"],
+        "Pragma": ["no-cache"],
+        "Expires": ["0"],
+        ...customHeaders ?? {}
+      },
+      data: errorPayload
+    };
+  }
+});
+
+// src/shared/utils/math.utils.ts
+var MathHelper = Object.freeze({
+  /**
+   * @description Constrains a value within an inclusive min-max range.
+   * @param value Input value.
+   * @param min Minimum bound.
+   * @param max Maximum bound.
+   * @returns Clamped value.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+  },
+  /**
+   * @description Rounds a number to the specified decimal precision.
+   * @param value Input value.
+   * @param decimals Number of decimal places.
+   * @returns Rounded value.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  roundTo(value, decimals) {
+    const factor = 10 ** decimals;
+    return Math.round(value * factor) / factor;
+  },
+  /**
+   * @description Divides two numbers, returning a safe fallback on zero denominator.
+   * @param numerator Numerator.
+   * @param denominator Denominator.
+   * @param fallback Return value when denominator is zero.
+   * @returns Division result or fallback.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  safeDivide(numerator, denominator, fallback = 0) {
+    if (denominator === 0) return fallback;
+    return numerator / denominator;
+  },
+  /**
+   * @description Returns the percentage of part over total (0–100 scale).
+   * @param part Part value.
+   * @param total Total value.
+   * @returns Percentage or 0 when total is zero.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  toPercentage(part, total) {
+    if (total === 0) return 0;
+    return part / total * 100;
+  },
+  /**
+   * @description Converts a value to a number, returning a fallback for non-numeric inputs.
+   * @param value Input value.
+   * @param fallback Fallback value for non-numeric inputs.
+   * @returns Numeric value or fallback.
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+  toNumber(value, fallback = 0) {
+    if (!Guards.isDefined(value) || !Guards.isNumber(value)) return fallback;
+    const num = Number(value);
+    return isNaN(num) ? fallback : num;
+  }
+});
+
+// src/shared/utils/promise.utils.ts
+var PromiseHelper = Object.freeze({
+  /**
+   * @description Sospende l'esecuzione asincrona per un numero esatto di millisecondi.
+   * @param ms I millisecondi di attesa.
+   * @returns Una Promise che si risolve al termine del tempo.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  },
+  /**
+   * @description Introduce un ritardo asincrono composto da un tempo base più una variazione casuale.
+   * Fondamentale per mitigare il "Thundering Herd problem" (effetto gregge) distribuendo
+   * nel tempo i retry simultanei di più client.
+   * * @param baseDelayMs Il ritardo minimo garantito.
+   * @param maxJitterMs La variazione massima casuale aggiuntiva.
+   * @returns Una Promise che si risolve al termine del calcolo.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  delayWithJitter(baseDelayMs, maxJitterMs) {
+    const jitter = Math.floor(Math.random() * maxJitterMs);
+    return new Promise((resolve) => setTimeout(resolve, baseDelayMs + jitter));
+  }
+});
+
+// src/shared/utils/sanitize.utils.ts
+var start = String.fromCharCode(0);
+var end = String.fromCharCode(31);
+var del = String.fromCharCode(127);
+var CONTROL_CHARS_REGEX = new RegExp(`[\\r\\n\\t${start}-${end}${del}]`, "g");
+var DANGEROUS_PROTOCOLS_REGEX = /^(javascript|data|vbscript):/i;
+var SanitizeHelper = Object.freeze({
+  /**
+   * @description Removes carriage returns, line feeds, null bytes, and non-printable control characters.
+   * Mitigates Log Forging and Log Injection attacks (CWE-117).
+   * @param value The candidate string to sanitize.
+   * @param maxLength Maximum allowable length after sanitization. Defaults to 256.
+   * @returns Sanitized string or undefined if empty/non-string.
+   */
+  stripControlChars(value, maxLength = 256) {
+    if (Guards.isNullOrEmpty(value)) return void 0;
+    const clean = value.replace(CONTROL_CHARS_REGEX, "").trim();
+    if (Guards.isNullOrEmpty(clean)) return void 0;
+    return clean.slice(0, maxLength);
+  },
+  /**
+   * @description Sanitizes navigation paths and URLs, removing control characters
+   * and preventing execution of dangerous pseudo-protocols (e.g. javascript:, data:).
+   * @param path The path string to sanitize.
+   * @param maxLength Maximum length of the path. Defaults to 512.
+   * @returns Sanitized path or '/' fallback for unsafe inputs.
+   */
+  sanitizePath(path, maxLength = 512) {
+    if (Guards.isNullOrEmpty(path)) return void 0;
+    const clean = path.replace(CONTROL_CHARS_REGEX, "").trim();
+    if (Guards.isNullOrEmpty(clean) || DANGEROUS_PROTOCOLS_REGEX.test(clean)) {
+      return "/";
+    }
+    return clean.slice(0, maxLength);
+  },
+  /**
+   * @description Sanitizes an array of strings (e.g. roles, permissions, scopes).
+   * Strips control characters, filters out empty entries, and limits collection size.
+   * @param items Array of strings to sanitize.
+   * @param maxItemLength Maximum allowable character length per item. Defaults to 64.
+   * @param maxItems Maximum total number of elements kept. Defaults to 50.
+   * @returns Immutable array of sanitized strings.
+   */
+  sanitizeStringArray(items, maxItemLength = 64, maxItems = 50) {
+    if (Guards.isNullOrEmpty(items)) return void 0;
+    const sanitized = items.slice(0, maxItems).map((item) => SanitizeHelper.stripControlChars(item, maxItemLength)).filter((item) => Guards.isDefined(item));
+    return sanitized;
+  }
+});
+
+// src/shared/utils/string.utils.ts
+var StringHelper = Object.freeze({
+  /**
+   * @description Safely converts a value to a JSON string, falling back to String() on failure.
+   * @param value The value to stringify.
+   * @returns A JSON string representation of the value, or a fallback string if serialization fails.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  safeStringify(value) {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  },
+  /**
+   * @description Safely parses a JSON string, returning a fallback value on failure.
+   * @param input The JSON string to parse.
+   * @param fallback Optional fallback value to return if parsing fails.
+   * @returns The parsed value, or the fallback value if parsing fails.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  safeParse(input, fallback = void 0) {
+    try {
+      return JSON.parse(input);
+    } catch {
+      return fallback ?? input;
+    }
+  },
+  /**
+   * @description Converts a string to camelCase.
+   * @param input Input string (supports snake_case, kebab-case, or space-separated).
+   * @returns camelCase string.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  camelCase(input) {
+    const segments = input.split(/[-_\s]+/);
+    const [first, ...rest] = segments;
+    const head = Guards.isDefined(first) ? first.toLowerCase() : "";
+    return head + rest.map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1)).join("");
+  },
+  /**
+   * @description Interpolates {{key}} placeholders in a template string.
+   * @param template Template string with {{key}} tokens.
+   * @param vars Key-value substitution map.
+   * @returns Interpolated string with resolved placeholders.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  interpolate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+      const value = vars[key];
+      return Guards.isDefined(value) ? String(value) : `{{${key}}}`;
+    });
+  },
+  /**
+   * @description Truncates a string to maxLength, appending a suffix when truncated.
+   * @param input Input string.
+   * @param maxLength Maximum character length including the suffix.
+   * @param suffix Appended suffix on truncation.
+   * @returns Truncated string.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  truncate(input, maxLength, suffix = "\u2026") {
+    if (input.length <= maxLength) return input;
+    const cutAt = Math.max(0, maxLength - suffix.length);
+    return input.slice(0, cutAt) + suffix;
+  },
+  /**
+   * @description Generates a reference code with a prefix, random alphanumeric part, and year.
+   * @param prefix Custom prefix for the reference code (e.g., "TRV" for travel).
+   * @returns Formatted reference code string.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  generateReferenceCode(prefix) {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    let randomPart = "";
+    for (let i = 0; i < 6; i++) {
+      randomPart += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    const year = (/* @__PURE__ */ new Date()).getFullYear();
+    return `${prefix}-${randomPart}-${year}`;
+  },
+  /**
+   * @description Extracts a single string value from a header that may be a string or an array of strings.
+   * @param value The header value, which can be a string or an array of strings.
+   * @returns The first string value if it's an array, the string itself if it's a string, or undefined if it's empty or not defined.
+  
+   * 
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js 
+   */
+  getSingleValue(value, separator) {
+    if (!Guards.isDefined(value)) return value;
+    if (Guards.isArray(value)) {
+      if (Guards.isNullOrEmpty(value)) {
+        return void 0;
+      }
+      if (Guards.isDefined(separator))
+        return StringHelper.getSingleValueWithSplit(value[0], separator);
+      return value[0];
+    }
+    if (Guards.isDefined(separator)) return StringHelper.getSingleValueWithSplit(value, separator);
+    return value;
+  },
+  getSingleValueWithSplit(value, separator) {
+    if (value.includes(separator)) return value.split(separator)[0].trim();
+    return value;
+  }
+});
+
+// src/infrastructure/auth/storage/cookie.storage.ts
+var createCookieStorage = (opts) => ({
+  getItem: (key) => {
+    if (!Guards.isDefined(document)) return null;
+    const match = new RegExp(`(^| )${encodeURIComponent(key)}=([^;]+)`).exec(document.cookie);
+    return Guards.isDefined(match) ? decodeURIComponent(match[2]) : null;
+  },
+  setItem: (key, value) => {
+    if (!Guards.isDefined(document)) return;
+    let cookieSuffix = "";
+    if (Guards.isDefined(opts.path)) cookieSuffix += `; path=${opts.path}`;
+    if (Guards.isDefined(opts.maxAge)) cookieSuffix += `; max-age=${opts.maxAge}`;
+    if (Guards.isDefined(opts.domain)) cookieSuffix += `; domain=${opts.domain}`;
+    if (Guards.isDefined(opts.secure)) cookieSuffix += `; Secure`;
+    if (Guards.isDefined(opts.sameSite)) cookieSuffix += `; SameSite=${opts.sameSite}`;
+    document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)}${cookieSuffix}`;
+  },
+  removeItem: (key) => {
+    if (!Guards.isDefined(document)) return;
+    document.cookie = `${encodeURIComponent(key)}=; path=${opts.path ?? "/"}; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+  }
+});
+
+// src/infrastructure/auth/storage/memory.storage.ts
+var createMemoryStorage = () => {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => store.get(key) ?? null,
+    setItem: (key, value) => {
+      store.set(key, value);
+    },
+    removeItem: (key) => {
+      store.delete(key);
+    }
+  };
+};
+
+// src/infrastructure/auth/storage/storage.utils.ts
+var StorageHelper = Object.freeze({
+  create(opts) {
+    switch (opts.type) {
+      case "memory":
+        return createMemoryStorage();
+      case "cookie":
+        if (!Guards.isDefined(opts.cookieOpts)) throw new Error("At least ");
+        return createCookieStorage(opts.cookieOpts);
+      case "session":
+        return sessionStorage;
+      case "local":
+        return localStorage;
+      default:
+        return opts.storage;
+    }
+  }
+});
+
+// src/domain/errors/app-error.ts
+var AppError = 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)
+    });
+  }
+};
+
+// src/domain/results/result.ts
+var Result = class _Result {
+  /**
+   * 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 
+   */
+  _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 
+   */
+  _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 
+   */
+  _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 
+   */
+  constructor(isSuccess, error, value) {
+    this._isSuccess = isSuccess;
+    this._error = error;
+    this._value = value;
+  }
+  /**
+   * 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(value) {
+    return new _Result(true, void 0, value);
+  }
+  /**
+   * 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(error) {
+    return new _Result(false, error, void 0);
+  }
+  /**
+   * 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() {
+    return this._isSuccess;
+  }
+  /**
+   * 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() {
+    if (!this._isSuccess) {
+      throw new Error("Cannot get the value of a failed result.");
+    }
+    return this._value;
+  }
+  /**
+   * 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() {
+    if (this._isSuccess) {
+      throw new Error("Cannot get the error of a successful result.");
+    }
+    return this._error;
+  }
+};
+
+// src/infrastructure/auth/supabase-auth.service.ts
+var SupabaseAuthService = class {
+  constructor(_supabase, _mapper, _sessionMapper, _opts) {
+    this._supabase = _supabase;
+    this._mapper = _mapper;
+    this._sessionMapper = _sessionMapper;
+    this._opts = _opts;
+  }
+  _supabase;
+  _mapper;
+  _sessionMapper;
+  _opts;
+  async authenticate(token) {
+    const { data, error } = await this._supabase.auth.getUser(token);
+    if (Guards.isDefined(error) || !Guards.isDefined(data.user)) {
+      return Result.fail(
+        AppError.authFailed("SupabaseAuthenticationService", error?.message ?? "Unknown error")
+      );
+    }
+    const user = data.user;
+    const claims = this._mapper.map(user);
+    return Result.ok(claims);
+  }
+  async isAuthenticated() {
+    const session = await this._supabase.auth.getSession();
+    return Guards.isDefined(session.data.session);
+  }
+  async exchangeCodeForSession(code) {
+    const { data, error } = await this._supabase.auth.exchangeCodeForSession(code);
+    if (Guards.isDefined(error) || !Guards.isDefined(data.session))
+      return Result.fail(
+        AppError.authFailed("SupabaseAuthenticationService", error?.message ?? "Unknown error")
+      );
+    const session = data.session;
+    if (Guards.isDefined(session)) return Result.ok(this._sessionMapper.map(session));
+    return Result.ok();
+  }
+  async signInWithProvider(provider) {
+    const { data, error } = await this._supabase.auth.signInWithOAuth({
+      provider,
+      options: { redirectTo: this._opts.redirectTo }
+    });
+    if (Guards.isDefined(error) || Guards.isNullOrEmpty(data.url)) {
+      return Result.fail(
+        AppError.authFailed("SupabaseFrontendAuthService", error?.message ?? "Unexpected error")
+      );
+    }
+    return Result.ok({ url: data.url });
+  }
+  async getSession() {
+    const { data, error } = await this._supabase.auth.getSession();
+    if (Guards.isDefined(error)) {
+      return Result.fail(AppError.authFailed("SupabaseFrontendAuthService", error.message));
+    }
+    const session = data.session;
+    if (Guards.isDefined(session)) return Result.ok(this._sessionMapper.map(data.session));
+    return Result.ok();
+  }
+  async getUser() {
+    const { data, error } = await this._supabase.auth.getUser();
+    if (Guards.isDefined(error)) {
+      return Result.fail(AppError.authFailed("SupabaseFrontendAuthService", error.message));
+    }
+    const user = data.user;
+    if (Guards.isDefined(user)) return Result.ok(this._mapper.map(user));
+    return Result.ok();
+  }
+  async signOut() {
+    const { error } = await this._supabase.auth.signOut();
+    if (Guards.isDefined(error)) {
+      return Result.fail(AppError.authFailed("SupabaseFrontendAuthService", error.message));
+    }
+    return Result.ok();
+  }
+  async getSessionToken() {
+    const sessionResult = await this.getSession();
+    if (!sessionResult.isOk()) {
+      return Result.fail(sessionResult.getErrorOrThrow());
+    }
+    const session = sessionResult.getValueOrThrow();
+    return Result.ok(session?.accessToken);
+  }
+};
+
+// src/infrastructure/mappers/supabase-claims.mapper.ts
+var SupabaseClaimsMapper = class {
+  map(user) {
+    const appMetadata = user.app_metadata ?? {};
+    return {
+      sub: user.id,
+      email: user.email,
+      name: Guards.isString(user.user_metadata?.["name"]) ? user.user_metadata?.["name"] : void 0,
+      tenantId: Guards.isString(appMetadata?.["tenant_id"]) ? appMetadata?.["tenant_id"] : void 0,
+      roles: Guards.isArray(appMetadata["roles"]) ? appMetadata["roles"] : void 0,
+      permissions: Guards.isArray(appMetadata["permissions"]) ? appMetadata["permissions"] : void 0
+    };
+  }
+};
+
+// src/infrastructure/mappers/supabase-session.mapper.ts
+var SupabaseSessionMapper = class {
+  constructor(_claimsMapper) {
+    this._claimsMapper = _claimsMapper;
+  }
+  _claimsMapper;
+  map(source) {
+    const claims = this._claimsMapper.map(source.user);
+    return {
+      accessToken: source.access_token,
+      refreshToken: source.refresh_token,
+      expiresAt: source.expires_at,
+      user: claims
+    };
+  }
+};
+export {
+  SupabaseAuthService,
+  SupabaseClaimsMapper,
+  SupabaseSessionMapper
+};
+//# sourceMappingURL=supabase.js.map