@xeno-js/shared 0.1.0

package/dist/infrastructure/validators/zod.validator.js

@@ -0,0 +1,53 @@
+import { AppError, Result } from '../../domain';
+import { Guards } from '../../shared';
+/**
+ * @description Implementation of the IValidatorService interface using Zod schemas for validation. This service maintains a registry of Zod schemas identified by unique keys and provides methods to check for the existence of a schema and to validate data against a specified schema. The validate method returns a ResultType indicating success or failure, with detailed error information in case of validation failure, including formatted error messages from Zod.
+
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+export class ZodValidatorService {
+    _cache;
+    _logger;
+    /**
+     * @description Constructs a new instance of the ZodValidatorService class, which takes an ICache instance as a parameter. This cache is used to store and manage the validation schemas that will be applied to incoming data. The constructor initializes the service with the provided cache, allowing it to perform validation checks based on the cached schemas when the validate method is called.
+     *
+     * @param _cache An instance of ICache used to store and retrieve Zod schemas. This cache is essential for the operation of the validator service, as it allows it to look up and apply the correct schema for validating incoming data.
+     * @param _logger An instance of ILogger used to log warning when schema was not found.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    constructor(_cache = new Map(), _logger) {
+        this._cache = _cache;
+        this._logger = _logger;
+    }
+    static formatIssue(issue) {
+        const issuePath = !Guards.isNullOrEmpty(issue.path) ? issue.path.map(String).join('.') : 'root';
+        return `[${issuePath}] ${issue.message}`;
+    }
+    addSchema(key, schema) {
+        this._cache.set(key, schema);
+    }
+    async validate(key, data) {
+        const schema = this._cache.get(key);
+        if (!Guards.isDefined(schema)) {
+            this._logger.warn(`Schema for intent: ${key} was not found`);
+            return Result.ok();
+        }
+        const zodResult = schema.safeParse(data);
+        if (!zodResult.success) {
+            const errorMessage = zodResult.error.issues
+                .map((issue) => ZodValidatorService.formatIssue(issue))
+                .join(', ');
+            return Result.fail(AppError.validationError('ZodValidatorService', `Validation failed for schema: ${errorMessage}`));
+        }
+        return Result.ok(true);
+    }
+}
+//# sourceMappingURL=zod.validator.js.map

package/dist/infrastructure/validators/zod.validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.validator.js","sourceRoot":"","sources":["../../../src/infrastructure/validators/zod.validator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAmB;IAaX;IACA;IAbnB;;;;;;;;;;OAUG;IACH,YACmB,SAA+B,IAAI,GAAG,EAAE,EACxC,OAAgB;QADhB,WAAM,GAAN,MAAM,CAAkC;QACxC,YAAO,GAAP,OAAO,CAAS;IAChC,CAAC;IAEI,MAAM,CAAC,WAAW,CAAC,KAAqB;QAC9C,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;QAE/F,OAAO,IAAI,SAAS,KAAK,KAAK,CAAC,OAAO,EAAE,CAAA;IAC1C,CAAC;IAEM,SAAS,CAAC,GAAW,EAAE,MAAe;QAC3C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAC9B,CAAC;IAEM,KAAK,CAAC,QAAQ,CAAI,GAAW,EAAE,IAAO;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAsB,GAAG,gBAAgB,CAAC,CAAA;YAC5D,OAAO,MAAM,CAAC,EAAE,EAAE,CAAA;QACpB,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QAExC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM;iBACxC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;iBACtD,IAAI,CAAC,IAAI,CAAC,CAAA;YAEb,OAAO,MAAM,CAAC,IAAI,CAChB,QAAQ,CAAC,eAAe,CACtB,qBAAqB,EACrB,iCAAiC,YAAY,EAAE,CAChD,CACF,CAAA;QACH,CAAC;QAED,OAAO,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;CACF"}

package/dist/shared/constants/concurrency.constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @description This module defines constants related to concurrency handling in the application, specifically for the ConcurrencyRetryPipeline. These constants include the maximum number of retry attempts, the base delay for retries, and the maximum jitter to be added to the delay. The constants are exported as a frozen object to prevent modification at runtime, ensuring consistent behavior across the application when handling concurrency conflicts.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare const DEFAULT_CONCURRENCY: Readonly<{
+    /**
+     * @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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly MAX_JITTER: 30;
+}>;
+//# sourceMappingURL=concurrency.constants.d.ts.map

package/dist/shared/constants/concurrency.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.constants.d.ts","sourceRoot":"","sources":["../../../src/shared/constants/concurrency.constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;KAQK;AACL,eAAO,MAAM,mBAAmB;IAC9B;;;;;;;;OAQG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;;;;OAQG;;EAEM,CAAA"}

package/dist/shared/constants/concurrency.constants.js

@@ -0,0 +1,42 @@
+/**
+ * @description This module defines constants related to concurrency handling in the application, specifically for the ConcurrencyRetryPipeline. These constants include the maximum number of retry attempts, the base delay for retries, and the maximum jitter to be added to the delay. The constants are exported as a frozen object to prevent modification at runtime, ensuring consistent behavior across the application when handling concurrency conflicts.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export const 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,
+});
+//# sourceMappingURL=concurrency.constants.js.map

package/dist/shared/constants/concurrency.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.constants.js","sourceRoot":"","sources":["../../../src/shared/constants/concurrency.constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;KAQK;AACL,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC;IACd;;;;;;;;OAQG;IACH,UAAU,EAAE,EAAE;IACd;;;;;;;;OAQG;IACH,UAAU,EAAE,EAAE;CACN,CAAC,CAAA"}

package/dist/shared/constants/error.constants.d.ts

@@ -0,0 +1,272 @@
+/**
+ * @description Machine-readable, kebab-case error codes for all cross-cutting failures.
+ * Used by AppError and Result to communicate failure semantics across layer boundaries
+ * without relying on human-readable strings.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare const ERROR_CODES: Readonly<{
+    /** @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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly PIPELINE_NOT_AVAILABLE: "PIPELINE_NOT_AVAILABLE";
+    readonly NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+    readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
+}>;
+/** @description Inferred union of every valid ERROR_CODES value.
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * @description Canonical HTTP status codes used across Presentation and Infrastructure layers.
+ * Centralising these values prevents magic-number sprawl and ensures
+ * consistent semantics between the AppError, Result and ApiResponse contracts.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare const STATUS_CODES: Readonly<{
+    /** @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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly NO_CONTENT: 204;
+    /** @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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly NOT_FOUND: 404;
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly 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
+     */
+    readonly ABORTED: 499;
+    /** @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
+     */
+    readonly 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
+     */
+    readonly SERVICE_UNAVAILABLE: 503;
+}>;
+/** @description Inferred union of every valid STATUS_CODES value.
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+export type StatusCode = (typeof STATUS_CODES)[keyof typeof STATUS_CODES];
+/**
+ * @description A mapping of ERROR_CODES to human-readable messages, used for logging and user feedback when an AppError is created with a specific error code. This allows for consistent and centralized management of error messages across the application, ensuring that each error code corresponds to a clear and descriptive message that can be easily maintained and localized if necessary.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare const ERROR_CODE_MESSAGES: Record<ErrorCode, string>;
+//# sourceMappingURL=error.constants.d.ts.map

package/dist/shared/constants/error.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.constants.d.ts","sourceRoot":"","sources":["../../../src/shared/constants/error.constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;KAUK;AACL,eAAO,MAAM,WAAW;IAGtB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAEH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;;;EAMM,CAAA;AAEX;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAItE;;;;;;;;;;KAUK;AACL,eAAO,MAAM,YAAY;IAGvB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAKH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;;IAKH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAKH;;;;;;OAMG;;IAGH;;;;;;OAMG;;EAEM,CAAA;AAEX;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAA;AAEzE;;;;;;;;KAQK;AACL,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAiB/C,CAAA"}