@asaidimu/utils-error 1.1.1 → 1.1.2

package/index.d.mts

@@ -7,15 +7,15 @@ type Severity = "error" | "warning" | "info";
  * Designed to be machine-readable while remaining human-friendly.
  */
 interface Issue {
-    /** Machine-readable identifier (e.g., "REQUIRED_FIELD_MISSING"). */
+    /** Machine-readable identifier (e.g., `"REQUIRED_FIELD_MISSING"`). */
     readonly code: string;
     /** Human-readable description of the problem. */
     readonly message: string;
-    /** Field path in a document or state (e.g., "users.0.email"). */
+    /** Field path in a document or state (e.g., `"users.0.email"`). */
     readonly path?: string;
     /** Optional array index when the issue relates to a specific element. */
     readonly index?: number;
-    /** Seriousness of the issue. Defaults to "error". */
+    /** Seriousness of the issue. Defaults to `"error"`. */
     readonly severity?: Severity;
     /** Optional detailed explanation, can be multi-line. */
     readonly description?: string;
@@ -23,31 +23,37 @@ interface Issue {
     readonly cause?: readonly Issue[];
 }
 /**
- * Standardized error code format: CATEGORY-XXX[-SUFFIX]
- * Examples:
- * - VAL-001 (Validation: required field missing)
- * - DB-002-NF (Database: not found)
- * - AUTH-003-DENIED (Auth: permission denied)
+ * Standardized error code format: `CATEGORY-XXX[-SUFFIX]`
+ *
+ * @example
+ * ```typescript
+ * // VAL-001 (Validation: required field missing)
+ * // DB-001-NF (Database: not found)
+ * // AUTH-001-DENIED (Auth: permission denied)
+ * ```
  */
 interface ErrorCodeMetadata {
-    /** The formal error code (e.g., "VAL-001") */
+    /** The formal unique error code identifier (e.g., `"VAL-001"`). */
     readonly code: string;
-    /** Human-readable name for the error type */
+    /** Human-readable uppercase name for the error type (e.g., `"VALIDATION_FAILED"`). */
     readonly name: string;
-    /** Detailed description of when this error occurs */
+    /** Detailed description of when and why this error occurs. */
     readonly description: string;
-    /** Suggested action for handling or resolving the error */
+    /** Suggested immediate action for engineers or systems to handle or resolve the error. */
     readonly action?: string;
-    /** HTTP status code mapping (if applicable) */
+    /** HTTP status code mapping for upstream REST APIs (e.g., `404`, `500`). */
     readonly httpStatus?: number;
-    /** Category of the error */
+    /** Operational category this error belongs to. */
     readonly category: ErrorCategory;
-    /** Whether this error should be logged as warning vs error */
+    /** Recommended logging level threshold (`"debug" | "info" | "warn" | "error"`). */
     readonly logLevel?: "debug" | "info" | "warn" | "error";
 }
+/**
+ * Categories classifying the origin and nature of an error.
+ */
 type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
 /**
- * Central registry of built-in error codes.
+ * Central registry of built-in system error codes.
  */
 declare const ErrorCodes: {
     readonly VALIDATION_FAILED: {
@@ -163,96 +169,144 @@ declare const ErrorCodes: {
     };
 };
 /**
- * Register a custom error code at runtime.
- * @throws if code already exists as a built-in error
+ * Register a custom error code at application runtime.
+ * @param metadata - The complete configuration and documentation for the new error code.
+ * @throws {Error} If the code already exists within built-in codes or is already registered.
  */
 declare function registerErrorCode(metadata: ErrorCodeMetadata): void;
 /**
- * Get metadata for any error code (built-in or custom).
- * Returns default metadata for unknown codes instead of throwing.
+ * Retrieve metadata details for any error code (built-in or custom dynamically registered).
+ * Falls back to a generic `custom` category block if the code is entirely unrecognized.
+ * @param code - The error code string to query.
+ * @returns The documented metadata configuration.
  */
 declare function getErrorMetadata(code: string): ErrorCodeMetadata;
 /**
- * Check if an error code is known (built-in or registered custom).
+ * Determines whether an error code exists in built-in configuration or runtime registries.
  */
 declare function isKnownErrorCode(code: string): boolean;
 /**
- * SystemError is the primary error type for all operational and validation errors.
- * Supports both predefined and custom error codes with full metadata.
+ * Configuration options container used when constructing a new `SystemError`.
+ */
+interface SystemErrorParams {
+    /** The unique registered error code identifier (e.g., `ErrorCodes.INTERNAL_ERROR.code`). */
+    code: string;
+    /** Explicit error message overrides. If omitted, defaults to the error code's description. */
+    message?: string;
+    /** Operational severity tier. Defaults to `"error"`. */
+    severity?: Severity;
+    /** State path or key where the operational failure occurred (e.g., `"users.0.email"`). */
+    path?: string;
+    /** The function block, track component, or routing process executing during failure. */
+    operation?: string;
+    /** Flat array of precise granular input issues or schema violations. */
+    issues?: readonly Issue[];
+    /** The underlying trigger cause. Accepts native `Error` instances, custom errors, or concurrent `Error[]` arrays. */
+    cause?: unknown | unknown[];
+    /** Ad-hoc modifications overriding base properties mapped from the code registry. */
+    metadata?: Partial<Omit<ErrorCodeMetadata, "code" | "category">>;
+}
+/**
+ * A single frame in a chronological error trace.
+ */
+interface TraceFrame {
+    operation: string;
+    message: string;
+    code?: string;
+    category?: string;
+}
+/**
+ * Represents a set of parallel error tracks (e.g., from `AggregateError`).
+ */
+interface ParallelTrace {
+    type: "parallel";
+    tracks: TraceNode[][];
+}
+/** A node in the trace is either a single frame or a parallel group. */
+type TraceNode = TraceFrame | ParallelTrace;
+/** The full chronological trace is always an array of nodes. */
+type ChronologicalTrace = TraceNode[];
+/**
+ * Primary domain operational error wrapper.
+ * Unfolds historical deep error hierarchies into flat, parallel-aware trace timelines.
  */
 declare class SystemError extends Error {
+    /** The associated error identifier code (e.g., `"SYS-001"`). */
     readonly code: string;
+    /** Static documentation mapping and registration rules bound to this code type. */
     readonly codeMetadata: ErrorCodeMetadata;
+    /** Severity tier grading the operational consequence of this failure. */
     readonly severity: Severity;
+    /** Target state or document path where processing failed. */
     readonly path?: string;
+    /** Active system segment, workflow node, or function context executing during failure. */
     readonly operation?: string;
+    /** Detailed sub-layer list representing structural data validation failures. */
     readonly issues: readonly Issue[];
+    /** Raw backing trigger, array of concurrent branches, or source error instance. */
     readonly cause?: unknown | unknown[];
-    constructor(params: {
-        code: string;
-        message?: string;
-        severity?: Severity;
-        path?: string;
-        operation?: string;
-        issues?: readonly Issue[];
-        cause?: unknown | unknown[];
-        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
-    });
+    /** Exact moment this error was instantiated (ISO string). */
+    readonly timestamp: string;
+    /**
+     * Instantiate a structurally traceable `SystemError`.
+     * @param params - Configuration parameters outlining the error's state context.
+     */
+    constructor(params: SystemErrorParams);
     /**
-     * Returns a new SystemError with the specified path.
+     * Generates a separate immutable clone assigning a target file, state, or field path.
      */
     withPath(path: string): SystemError;
     /**
-     * Returns a new SystemError with the specified operation name.
+     * Generates a separate immutable clone assigning a specific execution block or track tracking context.
      */
     withOperation(operation: string): SystemError;
     /**
-     * Returns a new SystemError with the specified issue appended.
+     * Appends an operational validation structural issue to a fresh clone of this error.
      */
     withIssue(issue: Issue): SystemError;
     /**
-     * Returns a new SystemError with multiple issues appended.
+     * Appends multiple validation issues onto a fresh clone of this error instance.
      */
     withIssues(issues: readonly Issue[]): SystemError;
     /**
-     * Returns a new SystemError wrapping the specified cause.
+     * Maps a backing raw trigger or concurrent array tracking set to a fresh clone of this error instance.
      */
     withCause(cause: unknown | unknown[]): SystemError;
     /**
-     * Returns the HTTP status code for this error (if applicable).
+     * Retrieves the recommended HTTP Status code mapped to this error's code metadata registry.
      */
     getHttpStatus(): number | undefined;
     /**
-     * Recursively extracts errors and builds a chronological chain (deepest leaf first).
+     * Unrolls execution hierarchies chronologically, isolating parallel pipelines into clear trace frames.
+     * Always returns an array of trace nodes.
      */
-    private extractChronologicalChain;
+    private extractChronologicalTrace;
     /**
-     * Formats the error for logging with an inverted, chronological execution path.
+     * Transforms the error payload into a flattened transmission format.
+     * Strips recursive depth in favor of an array-mapped chronological failure `trace`.
      */
-    toLogEntry(): Record<string, unknown>;
-    /**
-     * Helper to recursively serialize any cause (single error, system error, or an array of them)
-     */
-    private serializeCause;
+    toJSON(): Record<string, unknown>;
     /**
-     * Automatically invoked by JSON.stringify().
+     * Generates a flat payload matching `toJSON` format requirements for centralized platform ingestion engines.
      */
-    toJSON(): Record<string, unknown>;
+    toLogEntry(): Record<string, unknown>;
     /**
-     * Produces a human-readable representation suitable for logging.
+     * Terminal terminal dump representation formatting details cleanly into plain strings.
      */
     toString(): string;
 }
 /**
- * Factory for creating a new SystemError with automatic metadata.
+ * Utility wrapper compiling a standard configured `SystemError`.
+ * @param code - The target static identifier code from the system directory registry.
+ * @param message - Custom overriding error description string.
  */
 declare function createError(code: string, message?: string): SystemError;
 /**
- * Helper for quick ad-hoc errors (useful for testing or prototyping).
+ * Helper generating quick ad-hoc test or assertion validation operational failures.
  */
 declare function error(code: string, message?: string): SystemError;
 /**
- * Predefined error codes for common scenarios (backward compatibility).
+ * Constant definitions providing direct string matching references to global built-in errors.
  */
 declare const CommonErrors: {
     readonly NOT_FOUND: "DB-001-NF";
@@ -267,18 +321,23 @@ declare const CommonErrors: {
     readonly OPERATION_ABORTED: "BUS-002-ABORT";
 };
 /**
- * Convenience factory functions for common errors.
+ * Immediate instantiation factory shortcodes.
  */
 declare const Errors: {
+    /** Resource missing exception handler factory. */
     notFound: (path?: string, message?: string) => SystemError;
+    /** Data key conflict handler factory. */
     duplicateKey: (path?: string, message?: string) => SystemError;
+    /** RBAC enforcement execution violation factory. */
     permissionDenied: (operation?: string, message?: string) => SystemError;
+    /** Structural form or schema processing failure collection compiler. */
     validationFailed: (issues: Issue[], path?: string) => SystemError;
+    /** Unexpected component thread collapse generic factory. */
     internalError: (cause?: unknown, message?: string) => SystemError;
 };
 /**
- * A functional wrapper for operations that can fail.
- * Encourages explicit error handling over try/catch blocks.
+ * Monadic functional wrapper container representing either an expected return type value,
+ * or a structural failure wrapper sequence without forcing explicit `throw` mechanics.
  */
 type Result<T, E = SystemError> = {
     readonly ok: true;
@@ -288,11 +347,13 @@ type Result<T, E = SystemError> = {
     readonly error: E;
 };
 /**
- * Type-safe helpers for creating Results.
+ * Type-guarded factory wrappers generating functional operational processing `Result` sets.
  */
 declare const Result: {
+    /** Compiles a verified positive execution return contract carrying processing changes. */
     ok: <T>(value: T) => Result<T, never>;
-    fail: <E>(error: E) => Result<never, E>;
+    /** Compiles a tracked failure tracking context avoiding stack engine halts. */
+    fail: <E>(err: E) => Result<never, E>;
 };
 
-export { CommonErrors, type ErrorCategory, type ErrorCodeMetadata, ErrorCodes, Errors, type Issue, Result, type Severity, SystemError, createError, error, getErrorMetadata, isKnownErrorCode, registerErrorCode };
+export { type ChronologicalTrace, CommonErrors, type ErrorCategory, type ErrorCodeMetadata, ErrorCodes, Errors, type Issue, type ParallelTrace, Result, type Severity, SystemError, type SystemErrorParams, type TraceFrame, type TraceNode, createError, error, getErrorMetadata, isKnownErrorCode, registerErrorCode };

package/index.d.ts

@@ -7,15 +7,15 @@ type Severity = "error" | "warning" | "info";
  * Designed to be machine-readable while remaining human-friendly.
  */
 interface Issue {
-    /** Machine-readable identifier (e.g., "REQUIRED_FIELD_MISSING"). */
+    /** Machine-readable identifier (e.g., `"REQUIRED_FIELD_MISSING"`). */
     readonly code: string;
     /** Human-readable description of the problem. */
     readonly message: string;
-    /** Field path in a document or state (e.g., "users.0.email"). */
+    /** Field path in a document or state (e.g., `"users.0.email"`). */
     readonly path?: string;
     /** Optional array index when the issue relates to a specific element. */
     readonly index?: number;
-    /** Seriousness of the issue. Defaults to "error". */
+    /** Seriousness of the issue. Defaults to `"error"`. */
     readonly severity?: Severity;
     /** Optional detailed explanation, can be multi-line. */
     readonly description?: string;
@@ -23,31 +23,37 @@ interface Issue {
     readonly cause?: readonly Issue[];
 }
 /**
- * Standardized error code format: CATEGORY-XXX[-SUFFIX]
- * Examples:
- * - VAL-001 (Validation: required field missing)
- * - DB-002-NF (Database: not found)
- * - AUTH-003-DENIED (Auth: permission denied)
+ * Standardized error code format: `CATEGORY-XXX[-SUFFIX]`
+ *
+ * @example
+ * ```typescript
+ * // VAL-001 (Validation: required field missing)
+ * // DB-001-NF (Database: not found)
+ * // AUTH-001-DENIED (Auth: permission denied)
+ * ```
  */
 interface ErrorCodeMetadata {
-    /** The formal error code (e.g., "VAL-001") */
+    /** The formal unique error code identifier (e.g., `"VAL-001"`). */
     readonly code: string;
-    /** Human-readable name for the error type */
+    /** Human-readable uppercase name for the error type (e.g., `"VALIDATION_FAILED"`). */
     readonly name: string;
-    /** Detailed description of when this error occurs */
+    /** Detailed description of when and why this error occurs. */
     readonly description: string;
-    /** Suggested action for handling or resolving the error */
+    /** Suggested immediate action for engineers or systems to handle or resolve the error. */
     readonly action?: string;
-    /** HTTP status code mapping (if applicable) */
+    /** HTTP status code mapping for upstream REST APIs (e.g., `404`, `500`). */
     readonly httpStatus?: number;
-    /** Category of the error */
+    /** Operational category this error belongs to. */
     readonly category: ErrorCategory;
-    /** Whether this error should be logged as warning vs error */
+    /** Recommended logging level threshold (`"debug" | "info" | "warn" | "error"`). */
     readonly logLevel?: "debug" | "info" | "warn" | "error";
 }
+/**
+ * Categories classifying the origin and nature of an error.
+ */
 type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
 /**
- * Central registry of built-in error codes.
+ * Central registry of built-in system error codes.
  */
 declare const ErrorCodes: {
     readonly VALIDATION_FAILED: {
@@ -163,96 +169,144 @@ declare const ErrorCodes: {
     };
 };
 /**
- * Register a custom error code at runtime.
- * @throws if code already exists as a built-in error
+ * Register a custom error code at application runtime.
+ * @param metadata - The complete configuration and documentation for the new error code.
+ * @throws {Error} If the code already exists within built-in codes or is already registered.
  */
 declare function registerErrorCode(metadata: ErrorCodeMetadata): void;
 /**
- * Get metadata for any error code (built-in or custom).
- * Returns default metadata for unknown codes instead of throwing.
+ * Retrieve metadata details for any error code (built-in or custom dynamically registered).
+ * Falls back to a generic `custom` category block if the code is entirely unrecognized.
+ * @param code - The error code string to query.
+ * @returns The documented metadata configuration.
  */
 declare function getErrorMetadata(code: string): ErrorCodeMetadata;
 /**
- * Check if an error code is known (built-in or registered custom).
+ * Determines whether an error code exists in built-in configuration or runtime registries.
  */
 declare function isKnownErrorCode(code: string): boolean;
 /**
- * SystemError is the primary error type for all operational and validation errors.
- * Supports both predefined and custom error codes with full metadata.
+ * Configuration options container used when constructing a new `SystemError`.
+ */
+interface SystemErrorParams {
+    /** The unique registered error code identifier (e.g., `ErrorCodes.INTERNAL_ERROR.code`). */
+    code: string;
+    /** Explicit error message overrides. If omitted, defaults to the error code's description. */
+    message?: string;
+    /** Operational severity tier. Defaults to `"error"`. */
+    severity?: Severity;
+    /** State path or key where the operational failure occurred (e.g., `"users.0.email"`). */
+    path?: string;
+    /** The function block, track component, or routing process executing during failure. */
+    operation?: string;
+    /** Flat array of precise granular input issues or schema violations. */
+    issues?: readonly Issue[];
+    /** The underlying trigger cause. Accepts native `Error` instances, custom errors, or concurrent `Error[]` arrays. */
+    cause?: unknown | unknown[];
+    /** Ad-hoc modifications overriding base properties mapped from the code registry. */
+    metadata?: Partial<Omit<ErrorCodeMetadata, "code" | "category">>;
+}
+/**
+ * A single frame in a chronological error trace.
+ */
+interface TraceFrame {
+    operation: string;
+    message: string;
+    code?: string;
+    category?: string;
+}
+/**
+ * Represents a set of parallel error tracks (e.g., from `AggregateError`).
+ */
+interface ParallelTrace {
+    type: "parallel";
+    tracks: TraceNode[][];
+}
+/** A node in the trace is either a single frame or a parallel group. */
+type TraceNode = TraceFrame | ParallelTrace;
+/** The full chronological trace is always an array of nodes. */
+type ChronologicalTrace = TraceNode[];
+/**
+ * Primary domain operational error wrapper.
+ * Unfolds historical deep error hierarchies into flat, parallel-aware trace timelines.
  */
 declare class SystemError extends Error {
+    /** The associated error identifier code (e.g., `"SYS-001"`). */
     readonly code: string;
+    /** Static documentation mapping and registration rules bound to this code type. */
     readonly codeMetadata: ErrorCodeMetadata;
+    /** Severity tier grading the operational consequence of this failure. */
     readonly severity: Severity;
+    /** Target state or document path where processing failed. */
     readonly path?: string;
+    /** Active system segment, workflow node, or function context executing during failure. */
     readonly operation?: string;
+    /** Detailed sub-layer list representing structural data validation failures. */
     readonly issues: readonly Issue[];
+    /** Raw backing trigger, array of concurrent branches, or source error instance. */
     readonly cause?: unknown | unknown[];
-    constructor(params: {
-        code: string;
-        message?: string;
-        severity?: Severity;
-        path?: string;
-        operation?: string;
-        issues?: readonly Issue[];
-        cause?: unknown | unknown[];
-        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
-    });
+    /** Exact moment this error was instantiated (ISO string). */
+    readonly timestamp: string;
+    /**
+     * Instantiate a structurally traceable `SystemError`.
+     * @param params - Configuration parameters outlining the error's state context.
+     */
+    constructor(params: SystemErrorParams);
     /**
-     * Returns a new SystemError with the specified path.
+     * Generates a separate immutable clone assigning a target file, state, or field path.
      */
     withPath(path: string): SystemError;
     /**
-     * Returns a new SystemError with the specified operation name.
+     * Generates a separate immutable clone assigning a specific execution block or track tracking context.
      */
     withOperation(operation: string): SystemError;
     /**
-     * Returns a new SystemError with the specified issue appended.
+     * Appends an operational validation structural issue to a fresh clone of this error.
      */
     withIssue(issue: Issue): SystemError;
     /**
-     * Returns a new SystemError with multiple issues appended.
+     * Appends multiple validation issues onto a fresh clone of this error instance.
      */
     withIssues(issues: readonly Issue[]): SystemError;
     /**
-     * Returns a new SystemError wrapping the specified cause.
+     * Maps a backing raw trigger or concurrent array tracking set to a fresh clone of this error instance.
      */
     withCause(cause: unknown | unknown[]): SystemError;
     /**
-     * Returns the HTTP status code for this error (if applicable).
+     * Retrieves the recommended HTTP Status code mapped to this error's code metadata registry.
      */
     getHttpStatus(): number | undefined;
     /**
-     * Recursively extracts errors and builds a chronological chain (deepest leaf first).
+     * Unrolls execution hierarchies chronologically, isolating parallel pipelines into clear trace frames.
+     * Always returns an array of trace nodes.
      */
-    private extractChronologicalChain;
+    private extractChronologicalTrace;
     /**
-     * Formats the error for logging with an inverted, chronological execution path.
+     * Transforms the error payload into a flattened transmission format.
+     * Strips recursive depth in favor of an array-mapped chronological failure `trace`.
      */
-    toLogEntry(): Record<string, unknown>;
-    /**
-     * Helper to recursively serialize any cause (single error, system error, or an array of them)
-     */
-    private serializeCause;
+    toJSON(): Record<string, unknown>;
     /**
-     * Automatically invoked by JSON.stringify().
+     * Generates a flat payload matching `toJSON` format requirements for centralized platform ingestion engines.
      */
-    toJSON(): Record<string, unknown>;
+    toLogEntry(): Record<string, unknown>;
     /**
-     * Produces a human-readable representation suitable for logging.
+     * Terminal terminal dump representation formatting details cleanly into plain strings.
      */
     toString(): string;
 }
 /**
- * Factory for creating a new SystemError with automatic metadata.
+ * Utility wrapper compiling a standard configured `SystemError`.
+ * @param code - The target static identifier code from the system directory registry.
+ * @param message - Custom overriding error description string.
  */
 declare function createError(code: string, message?: string): SystemError;
 /**
- * Helper for quick ad-hoc errors (useful for testing or prototyping).
+ * Helper generating quick ad-hoc test or assertion validation operational failures.
  */
 declare function error(code: string, message?: string): SystemError;
 /**
- * Predefined error codes for common scenarios (backward compatibility).
+ * Constant definitions providing direct string matching references to global built-in errors.
  */
 declare const CommonErrors: {
     readonly NOT_FOUND: "DB-001-NF";
@@ -267,18 +321,23 @@ declare const CommonErrors: {
     readonly OPERATION_ABORTED: "BUS-002-ABORT";
 };
 /**
- * Convenience factory functions for common errors.
+ * Immediate instantiation factory shortcodes.
  */
 declare const Errors: {
+    /** Resource missing exception handler factory. */
     notFound: (path?: string, message?: string) => SystemError;
+    /** Data key conflict handler factory. */
     duplicateKey: (path?: string, message?: string) => SystemError;
+    /** RBAC enforcement execution violation factory. */
     permissionDenied: (operation?: string, message?: string) => SystemError;
+    /** Structural form or schema processing failure collection compiler. */
     validationFailed: (issues: Issue[], path?: string) => SystemError;
+    /** Unexpected component thread collapse generic factory. */
     internalError: (cause?: unknown, message?: string) => SystemError;
 };
 /**
- * A functional wrapper for operations that can fail.
- * Encourages explicit error handling over try/catch blocks.
+ * Monadic functional wrapper container representing either an expected return type value,
+ * or a structural failure wrapper sequence without forcing explicit `throw` mechanics.
  */
 type Result<T, E = SystemError> = {
     readonly ok: true;
@@ -288,11 +347,13 @@ type Result<T, E = SystemError> = {
     readonly error: E;
 };
 /**
- * Type-safe helpers for creating Results.
+ * Type-guarded factory wrappers generating functional operational processing `Result` sets.
  */
 declare const Result: {
+    /** Compiles a verified positive execution return contract carrying processing changes. */
     ok: <T>(value: T) => Result<T, never>;
-    fail: <E>(error: E) => Result<never, E>;
+    /** Compiles a tracked failure tracking context avoiding stack engine halts. */
+    fail: <E>(err: E) => Result<never, E>;
 };
 
-export { CommonErrors, type ErrorCategory, type ErrorCodeMetadata, ErrorCodes, Errors, type Issue, Result, type Severity, SystemError, createError, error, getErrorMetadata, isKnownErrorCode, registerErrorCode };
+export { type ChronologicalTrace, CommonErrors, type ErrorCategory, type ErrorCodeMetadata, ErrorCodes, Errors, type Issue, type ParallelTrace, Result, type Severity, SystemError, type SystemErrorParams, type TraceFrame, type TraceNode, createError, error, getErrorMetadata, isKnownErrorCode, registerErrorCode };

package/index.js

@@ -1 +1 @@
-"use strict";var e={VALIDATION_FAILED:{code:"VAL-001",name:"VALIDATION_FAILED",description:"Input validation failed due to one or more invalid fields",category:"validation",httpStatus:400,logLevel:"warn"},REQUIRED_FIELD_MISSING:{code:"VAL-002",name:"REQUIRED_FIELD_MISSING",description:"A required field was not provided in the request",category:"validation",httpStatus:400,logLevel:"warn"},INVALID_FORMAT:{code:"VAL-003",name:"INVALID_FORMAT",description:"Field value does not match expected format",category:"validation",httpStatus:400,logLevel:"warn"},NOT_FOUND:{code:"DB-001-NF",name:"NOT_FOUND",description:"The requested resource could not be found",category:"database",httpStatus:404,logLevel:"info",action:"Verify the resource identifier exists before accessing"},DUPLICATE_KEY:{code:"DB-002-DUP",name:"DUPLICATE_KEY",description:"A unique constraint violation occurred",category:"database",httpStatus:409,logLevel:"warn",action:"Check if the resource already exists before creation"},RESOURCE_LOCKED:{code:"DB-003-LOCK",name:"RESOURCE_LOCKED",description:"The resource is currently locked by another operation",category:"database",httpStatus:409,logLevel:"warn",action:"Retry the operation after a brief delay"},PERMISSION_DENIED:{code:"AUTH-001-DENIED",name:"PERMISSION_DENIED",description:"The authenticated user lacks permission for this operation",category:"auth",httpStatus:403,logLevel:"warn",action:"Check user roles and permissions"},UNAUTHENTICATED:{code:"AUTH-002-UNAUTH",name:"UNAUTHENTICATED",description:"Authentication is required for this operation",category:"auth",httpStatus:401,logLevel:"info",action:"Provide valid authentication credentials"},INVALID_COMMAND:{code:"BUS-001",name:"INVALID_COMMAND",description:"The command or operation is invalid for the current state",category:"business",httpStatus:400,logLevel:"warn"},OPERATION_ABORTED:{code:"BUS-002-ABORT",name:"OPERATION_ABORTED",description:"The operation was explicitly aborted",category:"business",httpStatus:409,logLevel:"info"},INTERNAL_ERROR:{code:"SYS-001",name:"INTERNAL_ERROR",description:"An unexpected internal error occurred",category:"system",httpStatus:500,logLevel:"error",action:"Check system logs for stack traces and diagnostic information"},BACKEND_ERROR:{code:"SYS-002",name:"BACKEND_ERROR",description:"An error occurred in a backend service",category:"system",httpStatus:502,logLevel:"error"},CONCURRENCY_ERROR:{code:"CON-001",name:"CONCURRENCY_ERROR",description:"A concurrency conflict occurred during the operation",category:"concurrency",httpStatus:409,logLevel:"warn",action:"Retry the operation with updated data"}},t=new Map;function s(s){const a=Object.values(e).find(e=>e.code===s);if(a)return a;const r=t.get(s);return r||{code:s,name:s.replace(/-/g,"_"),description:`Unknown error: ${s}`,category:"custom",httpStatus:500,logLevel:"error",action:"Check if this error code is properly registered or handle as unknown error"}}var a=class e extends Error{code;codeMetadata;severity;path;operation;issues;cause;constructor(t){const a={...s(t.code),...t.metadata,code:t.code};super(t.message??a.description),this.name="SystemError",this.code=t.code,this.codeMetadata=a,this.severity=t.severity??"error",this.path=t.path,this.operation=t.operation,this.issues=t.issues??[],this.cause=t.cause,Object.setPrototypeOf(this,e.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,e)}withPath(t){return new e({code:this.code,message:this.message,severity:this.severity,path:t,operation:this.operation,issues:this.issues,cause:this.cause,metadata:this.codeMetadata})}withOperation(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:t,issues:this.issues,cause:this.cause,metadata:this.codeMetadata})}withIssue(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:[...this.issues,t],cause:this.cause,metadata:this.codeMetadata})}withIssues(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:[...this.issues,...t],cause:this.cause,metadata:this.codeMetadata})}withCause(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:this.issues,cause:t,metadata:this.codeMetadata})}getHttpStatus(){return this.codeMetadata.httpStatus}extractChronologicalChain(e){if(!e)return[];if(Array.isArray(e))return e.flatMap(e=>this.extractChronologicalChain(e));if(e instanceof AggregateError)return e.errors.flatMap(e=>this.extractChronologicalChain(e));let t={name:e instanceof Error?e.name:"UnknownError",message:e instanceof Error?e.message:"object"==typeof e&&null!==e?JSON.stringify(e):String(e),code:e?.code,operation:e?.operation};if(!(e instanceof Error)&&"object"==typeof e&&null!==e){const t=Object.keys(e);if(1===t.length&&"object"==typeof e[t[0]])return this.extractChronologicalChain(e[t[0]])}const s=e?.cause;return s?[...this.extractChronologicalChain(s),t]:[t]}toLogEntry(){const e=this.extractChronologicalChain(this.cause);e.push({name:this.name,message:this.message,code:this.code,operation:this.operation});const t=e.map(e=>`${e.operation||e.code||e.name} (${e.message})`).join(" --\x3e ");return{name:this.name,code:this.code,category:this.codeMetadata.category,severity:this.severity,message:`${this.message} | Failure Path: ${t}`,operation:this.operation,path:this.path,issues:this.issues,history:e,stack:this.stack,timestamp:(new Date).toISOString()}}serializeCause(e){return e?Array.isArray(e)?e.map(e=>this.serializeCause(e)):e instanceof AggregateError?{name:e.name,message:e.message,errors:e.errors.map(e=>this.serializeCause(e)),stack:e.stack}:e instanceof Error?"function"==typeof e.toJSON?e.toJSON():{name:e.name,message:e.message,stack:e.stack}:e:e}toJSON(){return{name:this.name,code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,codeMetadata:this.codeMetadata,issues:this.issues,cause:this.serializeCause(this.cause)}}toString(){let e=`[${this.code}] ${this.message} (${this.codeMetadata.category})`;return this.path&&(e+=` at '${this.path}'`),this.operation&&(e+=` during '${this.operation}'`),this.issues.length>0&&(e+="\nIssues:\n"+this.issues.map((e,t)=>`  ${t+1}. ${e.message} [${e.code}]`).join("\n")),this.cause&&(e+=`\nCause: ${this.cause instanceof Error?this.cause.message:String(this.cause)}`),e}};var r={NOT_FOUND:"DB-001-NF",DUPLICATE_KEY:"DB-002-DUP",INVALID_COMMAND:"BUS-001",PERMISSION_DENIED:"AUTH-001-DENIED",BACKEND_ERROR:"SYS-002",INTERNAL_ERROR:"SYS-001",VALIDATION_FAILED:"VAL-001",CONCURRENCY_ERROR:"CON-001",RESOURCE_LOCKED:"DB-003-LOCK",OPERATION_ABORTED:"BUS-002-ABORT"},o={notFound:(e,t)=>new a({code:r.NOT_FOUND,message:t,path:e}),duplicateKey:(e,t)=>new a({code:r.DUPLICATE_KEY,message:t,path:e}),permissionDenied:(e,t)=>new a({code:r.PERMISSION_DENIED,message:t,operation:e}),validationFailed:(e,t)=>new a({code:r.VALIDATION_FAILED,issues:e,path:t}),internalError:(e,t)=>new a({code:r.INTERNAL_ERROR,message:t,cause:e})};exports.CommonErrors=r,exports.ErrorCodes=e,exports.Errors=o,exports.Result={ok:e=>({ok:!0,value:e}),fail:e=>({ok:!1,error:e})},exports.SystemError=a,exports.createError=function(e,t){return new a({code:e,message:t})},exports.error=function(e,t){return new a({code:e,message:t})},exports.getErrorMetadata=s,exports.isKnownErrorCode=function(s){return Object.values(e).some(e=>e.code===s)||t.has(s)},exports.registerErrorCode=function(s){if(Object.values(e).find(e=>e.code===s.code))throw new Error(`Cannot register custom error code "${s.code}": already exists as built-in error`);if(t.has(s.code))throw new Error(`Custom error code "${s.code}" is already registered`);t.set(s.code,s)};
+"use strict";var e={VALIDATION_FAILED:{code:"VAL-001",name:"VALIDATION_FAILED",description:"Input validation failed due to one or more invalid fields",category:"validation",httpStatus:400,logLevel:"warn"},REQUIRED_FIELD_MISSING:{code:"VAL-002",name:"REQUIRED_FIELD_MISSING",description:"A required field was not provided in the request",category:"validation",httpStatus:400,logLevel:"warn"},INVALID_FORMAT:{code:"VAL-003",name:"INVALID_FORMAT",description:"Field value does not match expected format",category:"validation",httpStatus:400,logLevel:"warn"},NOT_FOUND:{code:"DB-001-NF",name:"NOT_FOUND",description:"The requested resource could not be found",category:"database",httpStatus:404,logLevel:"info",action:"Verify the resource identifier exists before accessing"},DUPLICATE_KEY:{code:"DB-002-DUP",name:"DUPLICATE_KEY",description:"A unique constraint violation occurred",category:"database",httpStatus:409,logLevel:"warn",action:"Check if the resource already exists before creation"},RESOURCE_LOCKED:{code:"DB-003-LOCK",name:"RESOURCE_LOCKED",description:"The resource is currently locked by another operation",category:"database",httpStatus:409,logLevel:"warn",action:"Retry the operation after a brief delay"},PERMISSION_DENIED:{code:"AUTH-001-DENIED",name:"PERMISSION_DENIED",description:"The authenticated user lacks permission for this operation",category:"auth",httpStatus:403,logLevel:"warn",action:"Check user roles and permissions"},UNAUTHENTICATED:{code:"AUTH-002-UNAUTH",name:"UNAUTHENTICATED",description:"Authentication is required for this operation",category:"auth",httpStatus:401,logLevel:"info",action:"Provide valid authentication credentials"},INVALID_COMMAND:{code:"BUS-001",name:"INVALID_COMMAND",description:"The command or operation is invalid for the current state",category:"business",httpStatus:400,logLevel:"warn"},OPERATION_ABORTED:{code:"BUS-002-ABORT",name:"OPERATION_ABORTED",description:"The operation was explicitly aborted",category:"business",httpStatus:409,logLevel:"info"},INTERNAL_ERROR:{code:"SYS-001",name:"INTERNAL_ERROR",description:"An unexpected internal error occurred",category:"system",httpStatus:500,logLevel:"error",action:"Check system logs for stack traces and diagnostic information"},BACKEND_ERROR:{code:"SYS-002",name:"BACKEND_ERROR",description:"An error occurred in a backend service",category:"system",httpStatus:502,logLevel:"error"},CONCURRENCY_ERROR:{code:"CON-001",name:"CONCURRENCY_ERROR",description:"A concurrency conflict occurred during the operation",category:"concurrency",httpStatus:409,logLevel:"warn",action:"Retry the operation with updated data"}},t=new Map(Object.values(e).map(e=>[e.code,e])),s=new Map;function r(e){const r=t.get(e);if(r)return r;const a=s.get(e);return a||{code:e,name:e.replace(/-/g,"_"),description:`Unknown error: ${e}`,category:"custom",httpStatus:500,logLevel:"error",action:"Check if this error code is properly registered or handle as unknown error"}}var a=class e extends Error{code;codeMetadata;severity;path;operation;issues;cause;timestamp;constructor(t){const s={...r(t.code),...t.metadata,code:t.code};super(t.message??s.description),this.name="SystemError",this.code=t.code,this.codeMetadata=s,this.severity=t.severity??"error",this.path=t.path,this.operation=t.operation,this.issues=t.issues??[],this.cause=t.cause,this.timestamp=(new Date).toISOString(),Object.setPrototypeOf(this,e.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,e)}withPath(t){return new e({code:this.code,message:this.message,severity:this.severity,operation:this.operation,issues:this.issues,cause:this.cause,path:t,metadata:this.codeMetadata})}withOperation(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,issues:this.issues,cause:this.cause,operation:t,metadata:this.codeMetadata})}withIssue(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,cause:this.cause,issues:[...this.issues,t],metadata:this.codeMetadata})}withIssues(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,cause:this.cause,issues:[...this.issues,...t],metadata:this.codeMetadata})}withCause(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:this.issues,cause:t,metadata:this.codeMetadata})}getHttpStatus(){return this.codeMetadata.httpStatus}extractChronologicalTrace(e){if(!e)return[];if(e instanceof AggregateError||Array.isArray(e)){return[{type:"parallel",tracks:(Array.isArray(e)?e:e.errors).map(e=>this.extractChronologicalTrace(e))}]}if(!(e instanceof Error)&&"object"==typeof e&&null!==e){const t=Object.keys(e);if(1===t.length&&"object"==typeof e[t[0]])return this.extractChronologicalTrace(e[t[0]])}const t={operation:e?.operation||e?.code||(e instanceof Error?e.name:"UnknownError"),message:e instanceof Error?e.message:"object"==typeof e&&null!==e?JSON.stringify(e):String(e)};e?.code&&(t.code=e.code),e?.codeMetadata?.category&&(t.category=e.codeMetadata.category);const s=e?.cause;if(s){return[...this.extractChronologicalTrace(s),t]}return[t]}toJSON(){const e=this.extractChronologicalTrace(this.cause);return e.push({operation:this.operation||this.code||this.name,message:this.message,code:this.code,category:this.codeMetadata.category}),{name:this.name,code:this.code,message:this.message,severity:this.severity,category:this.codeMetadata.category,httpStatus:this.codeMetadata.httpStatus,operation:this.operation,path:this.path,issues:this.issues.length>0?this.issues:void 0,trace:e,action:this.codeMetadata.action,timestamp:this.timestamp,stack:this.stack}}toLogEntry(){return this.toJSON()}toString(){let e=`[${this.code}] ${this.message} (${this.codeMetadata.category})`;return this.path&&(e+=` at '${this.path}'`),this.operation&&(e+=` during '${this.operation}'`),this.issues.length>0&&(e+="\nIssues:\n"+this.issues.map((e,t)=>`  ${t+1}. ${e.message} [${e.code}]`).join("\n")),e}};var o={NOT_FOUND:"DB-001-NF",DUPLICATE_KEY:"DB-002-DUP",INVALID_COMMAND:"BUS-001",PERMISSION_DENIED:"AUTH-001-DENIED",BACKEND_ERROR:"SYS-002",INTERNAL_ERROR:"SYS-001",VALIDATION_FAILED:"VAL-001",CONCURRENCY_ERROR:"CON-001",RESOURCE_LOCKED:"DB-003-LOCK",OPERATION_ABORTED:"BUS-002-ABORT"},i={notFound:(e,t)=>new a({code:o.NOT_FOUND,message:t,path:e}),duplicateKey:(e,t)=>new a({code:o.DUPLICATE_KEY,message:t,path:e}),permissionDenied:(e,t)=>new a({code:o.PERMISSION_DENIED,message:t,operation:e}),validationFailed:(e,t)=>new a({code:o.VALIDATION_FAILED,issues:e,path:t}),internalError:(e,t)=>new a({code:o.INTERNAL_ERROR,message:t,cause:e})};exports.CommonErrors=o,exports.ErrorCodes=e,exports.Errors=i,exports.Result={ok:e=>({ok:!0,value:e}),fail:e=>({ok:!1,error:e})},exports.SystemError=a,exports.createError=function(e,t){return new a({code:e,message:t})},exports.error=function(e,t){return new a({code:e,message:t})},exports.getErrorMetadata=r,exports.isKnownErrorCode=function(e){return t.has(e)||s.has(e)},exports.registerErrorCode=function(e){if(t.has(e.code))throw new Error(`Cannot register custom error code "${e.code}": already exists as built-in error`);if(s.has(e.code))throw new Error(`Custom error code "${e.code}" is already registered`);s.set(e.code,e)};

package/index.mjs

@@ -1 +1 @@
-var e={VALIDATION_FAILED:{code:"VAL-001",name:"VALIDATION_FAILED",description:"Input validation failed due to one or more invalid fields",category:"validation",httpStatus:400,logLevel:"warn"},REQUIRED_FIELD_MISSING:{code:"VAL-002",name:"REQUIRED_FIELD_MISSING",description:"A required field was not provided in the request",category:"validation",httpStatus:400,logLevel:"warn"},INVALID_FORMAT:{code:"VAL-003",name:"INVALID_FORMAT",description:"Field value does not match expected format",category:"validation",httpStatus:400,logLevel:"warn"},NOT_FOUND:{code:"DB-001-NF",name:"NOT_FOUND",description:"The requested resource could not be found",category:"database",httpStatus:404,logLevel:"info",action:"Verify the resource identifier exists before accessing"},DUPLICATE_KEY:{code:"DB-002-DUP",name:"DUPLICATE_KEY",description:"A unique constraint violation occurred",category:"database",httpStatus:409,logLevel:"warn",action:"Check if the resource already exists before creation"},RESOURCE_LOCKED:{code:"DB-003-LOCK",name:"RESOURCE_LOCKED",description:"The resource is currently locked by another operation",category:"database",httpStatus:409,logLevel:"warn",action:"Retry the operation after a brief delay"},PERMISSION_DENIED:{code:"AUTH-001-DENIED",name:"PERMISSION_DENIED",description:"The authenticated user lacks permission for this operation",category:"auth",httpStatus:403,logLevel:"warn",action:"Check user roles and permissions"},UNAUTHENTICATED:{code:"AUTH-002-UNAUTH",name:"UNAUTHENTICATED",description:"Authentication is required for this operation",category:"auth",httpStatus:401,logLevel:"info",action:"Provide valid authentication credentials"},INVALID_COMMAND:{code:"BUS-001",name:"INVALID_COMMAND",description:"The command or operation is invalid for the current state",category:"business",httpStatus:400,logLevel:"warn"},OPERATION_ABORTED:{code:"BUS-002-ABORT",name:"OPERATION_ABORTED",description:"The operation was explicitly aborted",category:"business",httpStatus:409,logLevel:"info"},INTERNAL_ERROR:{code:"SYS-001",name:"INTERNAL_ERROR",description:"An unexpected internal error occurred",category:"system",httpStatus:500,logLevel:"error",action:"Check system logs for stack traces and diagnostic information"},BACKEND_ERROR:{code:"SYS-002",name:"BACKEND_ERROR",description:"An error occurred in a backend service",category:"system",httpStatus:502,logLevel:"error"},CONCURRENCY_ERROR:{code:"CON-001",name:"CONCURRENCY_ERROR",description:"A concurrency conflict occurred during the operation",category:"concurrency",httpStatus:409,logLevel:"warn",action:"Retry the operation with updated data"}},t=new Map;function s(s){if(Object.values(e).find(e=>e.code===s.code))throw new Error(`Cannot register custom error code "${s.code}": already exists as built-in error`);if(t.has(s.code))throw new Error(`Custom error code "${s.code}" is already registered`);t.set(s.code,s)}function a(s){const a=Object.values(e).find(e=>e.code===s);if(a)return a;const o=t.get(s);return o||{code:s,name:s.replace(/-/g,"_"),description:`Unknown error: ${s}`,category:"custom",httpStatus:500,logLevel:"error",action:"Check if this error code is properly registered or handle as unknown error"}}function o(s){return Object.values(e).some(e=>e.code===s)||t.has(s)}var r=class e extends Error{code;codeMetadata;severity;path;operation;issues;cause;constructor(t){const s={...a(t.code),...t.metadata,code:t.code};super(t.message??s.description),this.name="SystemError",this.code=t.code,this.codeMetadata=s,this.severity=t.severity??"error",this.path=t.path,this.operation=t.operation,this.issues=t.issues??[],this.cause=t.cause,Object.setPrototypeOf(this,e.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,e)}withPath(t){return new e({code:this.code,message:this.message,severity:this.severity,path:t,operation:this.operation,issues:this.issues,cause:this.cause,metadata:this.codeMetadata})}withOperation(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:t,issues:this.issues,cause:this.cause,metadata:this.codeMetadata})}withIssue(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:[...this.issues,t],cause:this.cause,metadata:this.codeMetadata})}withIssues(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:[...this.issues,...t],cause:this.cause,metadata:this.codeMetadata})}withCause(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:this.issues,cause:t,metadata:this.codeMetadata})}getHttpStatus(){return this.codeMetadata.httpStatus}extractChronologicalChain(e){if(!e)return[];if(Array.isArray(e))return e.flatMap(e=>this.extractChronologicalChain(e));if(e instanceof AggregateError)return e.errors.flatMap(e=>this.extractChronologicalChain(e));let t={name:e instanceof Error?e.name:"UnknownError",message:e instanceof Error?e.message:"object"==typeof e&&null!==e?JSON.stringify(e):String(e),code:e?.code,operation:e?.operation};if(!(e instanceof Error)&&"object"==typeof e&&null!==e){const t=Object.keys(e);if(1===t.length&&"object"==typeof e[t[0]])return this.extractChronologicalChain(e[t[0]])}const s=e?.cause;return s?[...this.extractChronologicalChain(s),t]:[t]}toLogEntry(){const e=this.extractChronologicalChain(this.cause);e.push({name:this.name,message:this.message,code:this.code,operation:this.operation});const t=e.map(e=>`${e.operation||e.code||e.name} (${e.message})`).join(" --\x3e ");return{name:this.name,code:this.code,category:this.codeMetadata.category,severity:this.severity,message:`${this.message} | Failure Path: ${t}`,operation:this.operation,path:this.path,issues:this.issues,history:e,stack:this.stack,timestamp:(new Date).toISOString()}}serializeCause(e){return e?Array.isArray(e)?e.map(e=>this.serializeCause(e)):e instanceof AggregateError?{name:e.name,message:e.message,errors:e.errors.map(e=>this.serializeCause(e)),stack:e.stack}:e instanceof Error?"function"==typeof e.toJSON?e.toJSON():{name:e.name,message:e.message,stack:e.stack}:e:e}toJSON(){return{name:this.name,code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,codeMetadata:this.codeMetadata,issues:this.issues,cause:this.serializeCause(this.cause)}}toString(){let e=`[${this.code}] ${this.message} (${this.codeMetadata.category})`;return this.path&&(e+=` at '${this.path}'`),this.operation&&(e+=` during '${this.operation}'`),this.issues.length>0&&(e+="\nIssues:\n"+this.issues.map((e,t)=>`  ${t+1}. ${e.message} [${e.code}]`).join("\n")),this.cause&&(e+=`\nCause: ${this.cause instanceof Error?this.cause.message:String(this.cause)}`),e}};function i(e,t){return new r({code:e,message:t})}function n(e,t){return new r({code:e,message:t})}var c={NOT_FOUND:"DB-001-NF",DUPLICATE_KEY:"DB-002-DUP",INVALID_COMMAND:"BUS-001",PERMISSION_DENIED:"AUTH-001-DENIED",BACKEND_ERROR:"SYS-002",INTERNAL_ERROR:"SYS-001",VALIDATION_FAILED:"VAL-001",CONCURRENCY_ERROR:"CON-001",RESOURCE_LOCKED:"DB-003-LOCK",OPERATION_ABORTED:"BUS-002-ABORT"},h={notFound:(e,t)=>new r({code:c.NOT_FOUND,message:t,path:e}),duplicateKey:(e,t)=>new r({code:c.DUPLICATE_KEY,message:t,path:e}),permissionDenied:(e,t)=>new r({code:c.PERMISSION_DENIED,message:t,operation:e}),validationFailed:(e,t)=>new r({code:c.VALIDATION_FAILED,issues:e,path:t}),internalError:(e,t)=>new r({code:c.INTERNAL_ERROR,message:t,cause:e})},d={ok:e=>({ok:!0,value:e}),fail:e=>({ok:!1,error:e})};export{c as CommonErrors,e as ErrorCodes,h as Errors,d as Result,r as SystemError,i as createError,n as error,a as getErrorMetadata,o as isKnownErrorCode,s as registerErrorCode};
+var e={VALIDATION_FAILED:{code:"VAL-001",name:"VALIDATION_FAILED",description:"Input validation failed due to one or more invalid fields",category:"validation",httpStatus:400,logLevel:"warn"},REQUIRED_FIELD_MISSING:{code:"VAL-002",name:"REQUIRED_FIELD_MISSING",description:"A required field was not provided in the request",category:"validation",httpStatus:400,logLevel:"warn"},INVALID_FORMAT:{code:"VAL-003",name:"INVALID_FORMAT",description:"Field value does not match expected format",category:"validation",httpStatus:400,logLevel:"warn"},NOT_FOUND:{code:"DB-001-NF",name:"NOT_FOUND",description:"The requested resource could not be found",category:"database",httpStatus:404,logLevel:"info",action:"Verify the resource identifier exists before accessing"},DUPLICATE_KEY:{code:"DB-002-DUP",name:"DUPLICATE_KEY",description:"A unique constraint violation occurred",category:"database",httpStatus:409,logLevel:"warn",action:"Check if the resource already exists before creation"},RESOURCE_LOCKED:{code:"DB-003-LOCK",name:"RESOURCE_LOCKED",description:"The resource is currently locked by another operation",category:"database",httpStatus:409,logLevel:"warn",action:"Retry the operation after a brief delay"},PERMISSION_DENIED:{code:"AUTH-001-DENIED",name:"PERMISSION_DENIED",description:"The authenticated user lacks permission for this operation",category:"auth",httpStatus:403,logLevel:"warn",action:"Check user roles and permissions"},UNAUTHENTICATED:{code:"AUTH-002-UNAUTH",name:"UNAUTHENTICATED",description:"Authentication is required for this operation",category:"auth",httpStatus:401,logLevel:"info",action:"Provide valid authentication credentials"},INVALID_COMMAND:{code:"BUS-001",name:"INVALID_COMMAND",description:"The command or operation is invalid for the current state",category:"business",httpStatus:400,logLevel:"warn"},OPERATION_ABORTED:{code:"BUS-002-ABORT",name:"OPERATION_ABORTED",description:"The operation was explicitly aborted",category:"business",httpStatus:409,logLevel:"info"},INTERNAL_ERROR:{code:"SYS-001",name:"INTERNAL_ERROR",description:"An unexpected internal error occurred",category:"system",httpStatus:500,logLevel:"error",action:"Check system logs for stack traces and diagnostic information"},BACKEND_ERROR:{code:"SYS-002",name:"BACKEND_ERROR",description:"An error occurred in a backend service",category:"system",httpStatus:502,logLevel:"error"},CONCURRENCY_ERROR:{code:"CON-001",name:"CONCURRENCY_ERROR",description:"A concurrency conflict occurred during the operation",category:"concurrency",httpStatus:409,logLevel:"warn",action:"Retry the operation with updated data"}},t=new Map(Object.values(e).map(e=>[e.code,e])),s=new Map;function a(e){if(t.has(e.code))throw new Error(`Cannot register custom error code "${e.code}": already exists as built-in error`);if(s.has(e.code))throw new Error(`Custom error code "${e.code}" is already registered`);s.set(e.code,e)}function o(e){const a=t.get(e);if(a)return a;const o=s.get(e);return o||{code:e,name:e.replace(/-/g,"_"),description:`Unknown error: ${e}`,category:"custom",httpStatus:500,logLevel:"error",action:"Check if this error code is properly registered or handle as unknown error"}}function r(e){return t.has(e)||s.has(e)}var i=class e extends Error{code;codeMetadata;severity;path;operation;issues;cause;timestamp;constructor(t){const s={...o(t.code),...t.metadata,code:t.code};super(t.message??s.description),this.name="SystemError",this.code=t.code,this.codeMetadata=s,this.severity=t.severity??"error",this.path=t.path,this.operation=t.operation,this.issues=t.issues??[],this.cause=t.cause,this.timestamp=(new Date).toISOString(),Object.setPrototypeOf(this,e.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,e)}withPath(t){return new e({code:this.code,message:this.message,severity:this.severity,operation:this.operation,issues:this.issues,cause:this.cause,path:t,metadata:this.codeMetadata})}withOperation(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,issues:this.issues,cause:this.cause,operation:t,metadata:this.codeMetadata})}withIssue(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,cause:this.cause,issues:[...this.issues,t],metadata:this.codeMetadata})}withIssues(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,cause:this.cause,issues:[...this.issues,...t],metadata:this.codeMetadata})}withCause(t){return new e({code:this.code,message:this.message,severity:this.severity,path:this.path,operation:this.operation,issues:this.issues,cause:t,metadata:this.codeMetadata})}getHttpStatus(){return this.codeMetadata.httpStatus}extractChronologicalTrace(e){if(!e)return[];if(e instanceof AggregateError||Array.isArray(e)){return[{type:"parallel",tracks:(Array.isArray(e)?e:e.errors).map(e=>this.extractChronologicalTrace(e))}]}if(!(e instanceof Error)&&"object"==typeof e&&null!==e){const t=Object.keys(e);if(1===t.length&&"object"==typeof e[t[0]])return this.extractChronologicalTrace(e[t[0]])}const t={operation:e?.operation||e?.code||(e instanceof Error?e.name:"UnknownError"),message:e instanceof Error?e.message:"object"==typeof e&&null!==e?JSON.stringify(e):String(e)};e?.code&&(t.code=e.code),e?.codeMetadata?.category&&(t.category=e.codeMetadata.category);const s=e?.cause;if(s){return[...this.extractChronologicalTrace(s),t]}return[t]}toJSON(){const e=this.extractChronologicalTrace(this.cause);return e.push({operation:this.operation||this.code||this.name,message:this.message,code:this.code,category:this.codeMetadata.category}),{name:this.name,code:this.code,message:this.message,severity:this.severity,category:this.codeMetadata.category,httpStatus:this.codeMetadata.httpStatus,operation:this.operation,path:this.path,issues:this.issues.length>0?this.issues:void 0,trace:e,action:this.codeMetadata.action,timestamp:this.timestamp,stack:this.stack}}toLogEntry(){return this.toJSON()}toString(){let e=`[${this.code}] ${this.message} (${this.codeMetadata.category})`;return this.path&&(e+=` at '${this.path}'`),this.operation&&(e+=` during '${this.operation}'`),this.issues.length>0&&(e+="\nIssues:\n"+this.issues.map((e,t)=>`  ${t+1}. ${e.message} [${e.code}]`).join("\n")),e}};function n(e,t){return new i({code:e,message:t})}function c(e,t){return new i({code:e,message:t})}var h={NOT_FOUND:"DB-001-NF",DUPLICATE_KEY:"DB-002-DUP",INVALID_COMMAND:"BUS-001",PERMISSION_DENIED:"AUTH-001-DENIED",BACKEND_ERROR:"SYS-002",INTERNAL_ERROR:"SYS-001",VALIDATION_FAILED:"VAL-001",CONCURRENCY_ERROR:"CON-001",RESOURCE_LOCKED:"DB-003-LOCK",OPERATION_ABORTED:"BUS-002-ABORT"},d={notFound:(e,t)=>new i({code:h.NOT_FOUND,message:t,path:e}),duplicateKey:(e,t)=>new i({code:h.DUPLICATE_KEY,message:t,path:e}),permissionDenied:(e,t)=>new i({code:h.PERMISSION_DENIED,message:t,operation:e}),validationFailed:(e,t)=>new i({code:h.VALIDATION_FAILED,issues:e,path:t}),internalError:(e,t)=>new i({code:h.INTERNAL_ERROR,message:t,cause:e})},u={ok:e=>({ok:!0,value:e}),fail:e=>({ok:!1,error:e})};export{h as CommonErrors,e as ErrorCodes,d as Errors,u as Result,i as SystemError,n as createError,c as error,o as getErrorMetadata,r as isKnownErrorCode,a as registerErrorCode};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-error",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "A collection of error utilities.",
   "main": "index.js",
   "module": "index.mjs",