@asaidimu/utils-error 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# `@asaidimu/utils-error`
+
+This package provides error utilities.

package/index.d.mts

@@ -0,0 +1,286 @@
+/**
+ * Severity levels for structured issues and errors.
+ */
+type Severity = "error" | "warning" | "info";
+/**
+ * Represents a detailed validation or operational problem.
+ * Designed to be machine-readable while remaining human-friendly.
+ */
+interface Issue {
+    /** 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"). */
+    readonly path?: string;
+    /** Optional array index when the issue relates to a specific element. */
+    readonly index?: number;
+    /** Seriousness of the issue. Defaults to "error". */
+    readonly severity?: Severity;
+    /** Optional detailed explanation, can be multi-line. */
+    readonly description?: string;
+    /** Nested issues that caused this one. */
+    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)
+ */
+interface ErrorCodeMetadata {
+    /** The formal error code (e.g., "VAL-001") */
+    readonly code: string;
+    /** Human-readable name for the error type */
+    readonly name: string;
+    /** Detailed description of when this error occurs */
+    readonly description: string;
+    /** Suggested action for handling or resolving the error */
+    readonly action?: string;
+    /** HTTP status code mapping (if applicable) */
+    readonly httpStatus?: number;
+    /** Category of the error */
+    readonly category: ErrorCategory;
+    /** Whether this error should be logged as warning vs error */
+    readonly logLevel?: "debug" | "info" | "warn" | "error";
+}
+type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
+/**
+ * Central registry of built-in error codes.
+ */
+declare const ErrorCodes: {
+    readonly VALIDATION_FAILED: {
+        readonly code: "VAL-001";
+        readonly name: "VALIDATION_FAILED";
+        readonly description: "Input validation failed due to one or more invalid fields";
+        readonly category: "validation";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly REQUIRED_FIELD_MISSING: {
+        readonly code: "VAL-002";
+        readonly name: "REQUIRED_FIELD_MISSING";
+        readonly description: "A required field was not provided in the request";
+        readonly category: "validation";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly INVALID_FORMAT: {
+        readonly code: "VAL-003";
+        readonly name: "INVALID_FORMAT";
+        readonly description: "Field value does not match expected format";
+        readonly category: "validation";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly NOT_FOUND: {
+        readonly code: "DB-001-NF";
+        readonly name: "NOT_FOUND";
+        readonly description: "The requested resource could not be found";
+        readonly category: "database";
+        readonly httpStatus: 404;
+        readonly logLevel: "info";
+        readonly action: "Verify the resource identifier exists before accessing";
+    };
+    readonly DUPLICATE_KEY: {
+        readonly code: "DB-002-DUP";
+        readonly name: "DUPLICATE_KEY";
+        readonly description: "A unique constraint violation occurred";
+        readonly category: "database";
+        readonly httpStatus: 409;
+        readonly logLevel: "warn";
+        readonly action: "Check if the resource already exists before creation";
+    };
+    readonly RESOURCE_LOCKED: {
+        readonly code: "DB-003-LOCK";
+        readonly name: "RESOURCE_LOCKED";
+        readonly description: "The resource is currently locked by another operation";
+        readonly category: "database";
+        readonly httpStatus: 409;
+        readonly logLevel: "warn";
+        readonly action: "Retry the operation after a brief delay";
+    };
+    readonly PERMISSION_DENIED: {
+        readonly code: "AUTH-001-DENIED";
+        readonly name: "PERMISSION_DENIED";
+        readonly description: "The authenticated user lacks permission for this operation";
+        readonly category: "auth";
+        readonly httpStatus: 403;
+        readonly logLevel: "warn";
+        readonly action: "Check user roles and permissions";
+    };
+    readonly UNAUTHENTICATED: {
+        readonly code: "AUTH-002-UNAUTH";
+        readonly name: "UNAUTHENTICATED";
+        readonly description: "Authentication is required for this operation";
+        readonly category: "auth";
+        readonly httpStatus: 401;
+        readonly logLevel: "info";
+        readonly action: "Provide valid authentication credentials";
+    };
+    readonly INVALID_COMMAND: {
+        readonly code: "BUS-001";
+        readonly name: "INVALID_COMMAND";
+        readonly description: "The command or operation is invalid for the current state";
+        readonly category: "business";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly OPERATION_ABORTED: {
+        readonly code: "BUS-002-ABORT";
+        readonly name: "OPERATION_ABORTED";
+        readonly description: "The operation was explicitly aborted";
+        readonly category: "business";
+        readonly httpStatus: 409;
+        readonly logLevel: "info";
+    };
+    readonly INTERNAL_ERROR: {
+        readonly code: "SYS-001";
+        readonly name: "INTERNAL_ERROR";
+        readonly description: "An unexpected internal error occurred";
+        readonly category: "system";
+        readonly httpStatus: 500;
+        readonly logLevel: "error";
+        readonly action: "Check system logs for stack traces and diagnostic information";
+    };
+    readonly BACKEND_ERROR: {
+        readonly code: "SYS-002";
+        readonly name: "BACKEND_ERROR";
+        readonly description: "An error occurred in a backend service";
+        readonly category: "system";
+        readonly httpStatus: 502;
+        readonly logLevel: "error";
+    };
+    readonly CONCURRENCY_ERROR: {
+        readonly code: "CON-001";
+        readonly name: "CONCURRENCY_ERROR";
+        readonly description: "A concurrency conflict occurred during the operation";
+        readonly category: "concurrency";
+        readonly httpStatus: 409;
+        readonly logLevel: "warn";
+        readonly action: "Retry the operation with updated data";
+    };
+};
+/**
+ * Register a custom error code at runtime.
+ * @throws if code already exists as a built-in error
+ */
+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.
+ */
+declare function getErrorMetadata(code: string): ErrorCodeMetadata;
+/**
+ * Check if an error code is known (built-in or registered custom).
+ */
+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.
+ */
+declare class SystemError extends Error {
+    readonly code: string;
+    readonly codeMetadata: ErrorCodeMetadata;
+    readonly severity: Severity;
+    readonly path?: string;
+    readonly operation?: string;
+    readonly issues: readonly Issue[];
+    readonly cause?: unknown;
+    constructor(params: {
+        code: string;
+        message?: string;
+        severity?: Severity;
+        path?: string;
+        operation?: string;
+        issues?: readonly Issue[];
+        cause?: unknown;
+        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
+    });
+    /**
+     * Returns a new SystemError with the specified path.
+     */
+    withPath(path: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified operation name.
+     */
+    withOperation(operation: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified issue appended.
+     */
+    withIssue(issue: Issue): SystemError;
+    /**
+     * Returns a new SystemError with multiple issues appended.
+     */
+    withIssues(issues: readonly Issue[]): SystemError;
+    /**
+     * Returns a new SystemError wrapping the specified cause.
+     */
+    withCause(cause: unknown): SystemError;
+    /**
+     * Returns the HTTP status code for this error (if applicable).
+     */
+    getHttpStatus(): number | undefined;
+    /**
+     * Formats the error for logging with structured metadata.
+     */
+    toLogEntry(): Record<string, unknown>;
+    /**
+     * Produces a human-readable representation suitable for logging.
+     */
+    toString(): string;
+}
+/**
+ * Factory for creating a new SystemError with automatic metadata.
+ */
+declare function createError(code: string, message?: string): SystemError;
+/**
+ * Helper for quick ad-hoc errors (useful for testing or prototyping).
+ */
+declare function error(code: string, message?: string): SystemError;
+/**
+ * Predefined error codes for common scenarios (backward compatibility).
+ */
+declare const CommonErrors: {
+    readonly NOT_FOUND: "DB-001-NF";
+    readonly DUPLICATE_KEY: "DB-002-DUP";
+    readonly INVALID_COMMAND: "BUS-001";
+    readonly PERMISSION_DENIED: "AUTH-001-DENIED";
+    readonly BACKEND_ERROR: "SYS-002";
+    readonly INTERNAL_ERROR: "SYS-001";
+    readonly VALIDATION_FAILED: "VAL-001";
+    readonly CONCURRENCY_ERROR: "CON-001";
+    readonly RESOURCE_LOCKED: "DB-003-LOCK";
+    readonly OPERATION_ABORTED: "BUS-002-ABORT";
+};
+/**
+ * Convenience factory functions for common errors.
+ */
+declare const Errors: {
+    notFound: (path?: string, message?: string) => SystemError;
+    duplicateKey: (path?: string, message?: string) => SystemError;
+    permissionDenied: (operation?: string, message?: string) => SystemError;
+    validationFailed: (issues: Issue[], path?: string) => SystemError;
+    internalError: (cause?: unknown, message?: string) => SystemError;
+};
+/**
+ * A functional wrapper for operations that can fail.
+ * Encourages explicit error handling over try/catch blocks.
+ */
+type Result<T, E = SystemError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/**
+ * Type-safe helpers for creating Results.
+ */
+declare const Result: {
+    ok: <T>(value: T) => Result<T, never>;
+    fail: <E>(error: E) => Result<never, E>;
+};
+
+export { CommonErrors, type ErrorCategory, type ErrorCodeMetadata, ErrorCodes, Errors, type Issue, Result, type Severity, SystemError, createError, error, getErrorMetadata, isKnownErrorCode, registerErrorCode };

package/index.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Severity levels for structured issues and errors.
+ */
+type Severity = "error" | "warning" | "info";
+/**
+ * Represents a detailed validation or operational problem.
+ * Designed to be machine-readable while remaining human-friendly.
+ */
+interface Issue {
+    /** 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"). */
+    readonly path?: string;
+    /** Optional array index when the issue relates to a specific element. */
+    readonly index?: number;
+    /** Seriousness of the issue. Defaults to "error". */
+    readonly severity?: Severity;
+    /** Optional detailed explanation, can be multi-line. */
+    readonly description?: string;
+    /** Nested issues that caused this one. */
+    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)
+ */
+interface ErrorCodeMetadata {
+    /** The formal error code (e.g., "VAL-001") */
+    readonly code: string;
+    /** Human-readable name for the error type */
+    readonly name: string;
+    /** Detailed description of when this error occurs */
+    readonly description: string;
+    /** Suggested action for handling or resolving the error */
+    readonly action?: string;
+    /** HTTP status code mapping (if applicable) */
+    readonly httpStatus?: number;
+    /** Category of the error */
+    readonly category: ErrorCategory;
+    /** Whether this error should be logged as warning vs error */
+    readonly logLevel?: "debug" | "info" | "warn" | "error";
+}
+type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
+/**
+ * Central registry of built-in error codes.
+ */
+declare const ErrorCodes: {
+    readonly VALIDATION_FAILED: {
+        readonly code: "VAL-001";
+        readonly name: "VALIDATION_FAILED";
+        readonly description: "Input validation failed due to one or more invalid fields";
+        readonly category: "validation";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly REQUIRED_FIELD_MISSING: {
+        readonly code: "VAL-002";
+        readonly name: "REQUIRED_FIELD_MISSING";
+        readonly description: "A required field was not provided in the request";
+        readonly category: "validation";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly INVALID_FORMAT: {
+        readonly code: "VAL-003";
+        readonly name: "INVALID_FORMAT";
+        readonly description: "Field value does not match expected format";
+        readonly category: "validation";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly NOT_FOUND: {
+        readonly code: "DB-001-NF";
+        readonly name: "NOT_FOUND";
+        readonly description: "The requested resource could not be found";
+        readonly category: "database";
+        readonly httpStatus: 404;
+        readonly logLevel: "info";
+        readonly action: "Verify the resource identifier exists before accessing";
+    };
+    readonly DUPLICATE_KEY: {
+        readonly code: "DB-002-DUP";
+        readonly name: "DUPLICATE_KEY";
+        readonly description: "A unique constraint violation occurred";
+        readonly category: "database";
+        readonly httpStatus: 409;
+        readonly logLevel: "warn";
+        readonly action: "Check if the resource already exists before creation";
+    };
+    readonly RESOURCE_LOCKED: {
+        readonly code: "DB-003-LOCK";
+        readonly name: "RESOURCE_LOCKED";
+        readonly description: "The resource is currently locked by another operation";
+        readonly category: "database";
+        readonly httpStatus: 409;
+        readonly logLevel: "warn";
+        readonly action: "Retry the operation after a brief delay";
+    };
+    readonly PERMISSION_DENIED: {
+        readonly code: "AUTH-001-DENIED";
+        readonly name: "PERMISSION_DENIED";
+        readonly description: "The authenticated user lacks permission for this operation";
+        readonly category: "auth";
+        readonly httpStatus: 403;
+        readonly logLevel: "warn";
+        readonly action: "Check user roles and permissions";
+    };
+    readonly UNAUTHENTICATED: {
+        readonly code: "AUTH-002-UNAUTH";
+        readonly name: "UNAUTHENTICATED";
+        readonly description: "Authentication is required for this operation";
+        readonly category: "auth";
+        readonly httpStatus: 401;
+        readonly logLevel: "info";
+        readonly action: "Provide valid authentication credentials";
+    };
+    readonly INVALID_COMMAND: {
+        readonly code: "BUS-001";
+        readonly name: "INVALID_COMMAND";
+        readonly description: "The command or operation is invalid for the current state";
+        readonly category: "business";
+        readonly httpStatus: 400;
+        readonly logLevel: "warn";
+    };
+    readonly OPERATION_ABORTED: {
+        readonly code: "BUS-002-ABORT";
+        readonly name: "OPERATION_ABORTED";
+        readonly description: "The operation was explicitly aborted";
+        readonly category: "business";
+        readonly httpStatus: 409;
+        readonly logLevel: "info";
+    };
+    readonly INTERNAL_ERROR: {
+        readonly code: "SYS-001";
+        readonly name: "INTERNAL_ERROR";
+        readonly description: "An unexpected internal error occurred";
+        readonly category: "system";
+        readonly httpStatus: 500;
+        readonly logLevel: "error";
+        readonly action: "Check system logs for stack traces and diagnostic information";
+    };
+    readonly BACKEND_ERROR: {
+        readonly code: "SYS-002";
+        readonly name: "BACKEND_ERROR";
+        readonly description: "An error occurred in a backend service";
+        readonly category: "system";
+        readonly httpStatus: 502;
+        readonly logLevel: "error";
+    };
+    readonly CONCURRENCY_ERROR: {
+        readonly code: "CON-001";
+        readonly name: "CONCURRENCY_ERROR";
+        readonly description: "A concurrency conflict occurred during the operation";
+        readonly category: "concurrency";
+        readonly httpStatus: 409;
+        readonly logLevel: "warn";
+        readonly action: "Retry the operation with updated data";
+    };
+};
+/**
+ * Register a custom error code at runtime.
+ * @throws if code already exists as a built-in error
+ */
+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.
+ */
+declare function getErrorMetadata(code: string): ErrorCodeMetadata;
+/**
+ * Check if an error code is known (built-in or registered custom).
+ */
+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.
+ */
+declare class SystemError extends Error {
+    readonly code: string;
+    readonly codeMetadata: ErrorCodeMetadata;
+    readonly severity: Severity;
+    readonly path?: string;
+    readonly operation?: string;
+    readonly issues: readonly Issue[];
+    readonly cause?: unknown;
+    constructor(params: {
+        code: string;
+        message?: string;
+        severity?: Severity;
+        path?: string;
+        operation?: string;
+        issues?: readonly Issue[];
+        cause?: unknown;
+        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
+    });
+    /**
+     * Returns a new SystemError with the specified path.
+     */
+    withPath(path: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified operation name.
+     */
+    withOperation(operation: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified issue appended.
+     */
+    withIssue(issue: Issue): SystemError;
+    /**
+     * Returns a new SystemError with multiple issues appended.
+     */
+    withIssues(issues: readonly Issue[]): SystemError;
+    /**
+     * Returns a new SystemError wrapping the specified cause.
+     */
+    withCause(cause: unknown): SystemError;
+    /**
+     * Returns the HTTP status code for this error (if applicable).
+     */
+    getHttpStatus(): number | undefined;
+    /**
+     * Formats the error for logging with structured metadata.
+     */
+    toLogEntry(): Record<string, unknown>;
+    /**
+     * Produces a human-readable representation suitable for logging.
+     */
+    toString(): string;
+}
+/**
+ * Factory for creating a new SystemError with automatic metadata.
+ */
+declare function createError(code: string, message?: string): SystemError;
+/**
+ * Helper for quick ad-hoc errors (useful for testing or prototyping).
+ */
+declare function error(code: string, message?: string): SystemError;
+/**
+ * Predefined error codes for common scenarios (backward compatibility).
+ */
+declare const CommonErrors: {
+    readonly NOT_FOUND: "DB-001-NF";
+    readonly DUPLICATE_KEY: "DB-002-DUP";
+    readonly INVALID_COMMAND: "BUS-001";
+    readonly PERMISSION_DENIED: "AUTH-001-DENIED";
+    readonly BACKEND_ERROR: "SYS-002";
+    readonly INTERNAL_ERROR: "SYS-001";
+    readonly VALIDATION_FAILED: "VAL-001";
+    readonly CONCURRENCY_ERROR: "CON-001";
+    readonly RESOURCE_LOCKED: "DB-003-LOCK";
+    readonly OPERATION_ABORTED: "BUS-002-ABORT";
+};
+/**
+ * Convenience factory functions for common errors.
+ */
+declare const Errors: {
+    notFound: (path?: string, message?: string) => SystemError;
+    duplicateKey: (path?: string, message?: string) => SystemError;
+    permissionDenied: (operation?: string, message?: string) => SystemError;
+    validationFailed: (issues: Issue[], path?: string) => SystemError;
+    internalError: (cause?: unknown, message?: string) => SystemError;
+};
+/**
+ * A functional wrapper for operations that can fail.
+ * Encourages explicit error handling over try/catch blocks.
+ */
+type Result<T, E = SystemError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/**
+ * Type-safe helpers for creating Results.
+ */
+declare const Result: {
+    ok: <T>(value: T) => Result<T, never>;
+    fail: <E>(error: E) => Result<never, E>;
+};
+
+export { CommonErrors, type ErrorCategory, type ErrorCodeMetadata, ErrorCodes, Errors, type Issue, Result, type Severity, SystemError, createError, error, getErrorMetadata, isKnownErrorCode, registerErrorCode };

package/index.js

@@ -0,0 +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}toLogEntry(){return{name:this.name,code:this.code,category:this.codeMetadata.category,message:this.message,path:this.path,operation:this.operation,issues:this.issues,cause:this.cause instanceof Error?this.cause.message:this.cause,stack:this.stack,timestamp:(new Date).toISOString()}}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)};

package/index.mjs

@@ -0,0 +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 i=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}toLogEntry(){return{name:this.name,code:this.code,category:this.codeMetadata.category,message:this.message,path:this.path,operation:this.operation,issues:this.issues,cause:this.cause instanceof Error?this.cause.message:this.cause,stack:this.stack,timestamp:(new Date).toISOString()}}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 r(e,t){return new i({code:e,message:t})}function n(e,t){return new i({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"},d={notFound:(e,t)=>new i({code:c.NOT_FOUND,message:t,path:e}),duplicateKey:(e,t)=>new i({code:c.DUPLICATE_KEY,message:t,path:e}),permissionDenied:(e,t)=>new i({code:c.PERMISSION_DENIED,message:t,operation:e}),validationFailed:(e,t)=>new i({code:c.VALIDATION_FAILED,issues:e,path:t}),internalError:(e,t)=>new i({code:c.INTERNAL_ERROR,message:t,cause:e})},h={ok:e=>({ok:!0,value:e}),fail:e=>({ok:!1,error:e})};export{c as CommonErrors,e as ErrorCodes,d as Errors,h as Result,i as SystemError,r as createError,n as error,a as getErrorMetadata,o as isKnownErrorCode,s as registerErrorCode};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@asaidimu/utils-error",
+  "version": "1.0.0",
+  "description": "A collection of error utilities.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "keywords": [
+    "typescript",
+    "utility"
+  ],
+  "author": "Saidimu <47994458+asaidimu@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/erp-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asaidimu/erp-utils/issues"
+  },
+  "homepage": "https://github.com/asaidimu/erp-utils/tree/main/src/error#readme",
+  "files": [
+    "./*"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    }
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest",
+    "access": "public"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/npm",
+        {
+          "pkgRoot": "./dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): Release @asaidimu/utils-error v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}