@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/error/report.js

@@ -7,17 +7,56 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Report = void 0;
-const inversify_1 = require("../di/inversify");
-const app_error_1 = require("./app-error");
+const inversify_js_1 = require("../di/inversify.js");
+const app_error_js_1 = require("./app-error.js");
+const status_code_js_1 = require("./status-code.js");
 /**
- * Report class is a utility class to manage and log errors within the application.
- * It is responsible for creating a standardized error object, logging it,
- * and then throwing the error for further handling.
+ * Error reporting utility with helper methods for common error scenarios.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept error-reporting
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use Report to create standardized application errors.
+ *
+ * @example
+ * ```typescript
+ * @inject(Report) private report: Report;
+ *
+ * // Create error
+ * throw this.report.error("Something went wrong", 500, "MyService");
+ *
+ * // Use helper methods
+ * throw this.report.badRequest("Invalid input");
+ * throw this.report.notFound("User", "123");
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Report provides:
+ * - Standardized error creation
+ * - Helper methods for common HTTP errors
+ * - AppError factory
+ * - Service identification
+ *
+ * **Design Decisions**
+ * - Injectable service (can be injected anywhere)
+ * - Helper methods for common scenarios
+ * - Wraps AppError creation
+ *
+ * @see {@link AppError} for error class
+ *
+ * @public API
  */
 let Report = class Report {
     constructor() {
         this.name = "Report Provider";
-        this.version = "3.0.0";
+        this.version = "4.0.0";
         this.author = "Richard Zampieri";
         this.repo = "https://github.com/expressots/expressots";
     }
@@ -30,12 +69,13 @@ let Report = class Report {
      * @param statusCode - The HTTP status code associated with the error (default is 500).
      * @param service - The service name associated with the error. If not specified,
      *                  it defaults to the name of the calling function.
+     * @param options - Additional error metadata options.
      *
      * @throws An object of the custom type AppError, which includes details about the error.
      */
     error(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    error, statusCode, service) {
+    error, statusCode, service, options) {
         let message = "";
         if (error == null) {
             // error is null or undefined
@@ -53,10 +93,65 @@ let Report = class Report {
         else {
             message = String(error);
         }
-        return new app_error_1.AppError(message, statusCode, service);
+        return new app_error_js_1.AppError(message, statusCode, service, options);
+    }
+    /**
+     * Creates a BadRequest (400) error
+     * @param message - Error message
+     * @param details - Additional error details
+     */
+    badRequest(message, details) {
+        return app_error_js_1.AppError.badRequest(message, details);
+    }
+    /**
+     * Creates a NotFound (404) error
+     * @param resource - Resource name that was not found
+     * @param id - Optional resource ID
+     */
+    notFound(resource, id) {
+        return app_error_js_1.AppError.notFound(resource, id);
+    }
+    /**
+     * Creates an Unauthorized (401) error
+     * @param message - Error message (default: "Unauthorized")
+     */
+    unauthorized(message = "Unauthorized") {
+        return app_error_js_1.AppError.unauthorized(message);
+    }
+    /**
+     * Creates a Forbidden (403) error
+     * @param message - Error message (default: "Forbidden")
+     */
+    forbidden(message = "Forbidden") {
+        return app_error_js_1.AppError.forbidden(message);
+    }
+    /**
+     * Creates an UnprocessableEntity (422) validation error
+     * @param errors - Array of validation errors
+     */
+    validationFailed(errors) {
+        return app_error_js_1.AppError.validationFailed(errors);
+    }
+    /**
+     * Creates a Conflict (409) error
+     * @param message - Error message
+     * @param details - Additional error details
+     */
+    conflict(message, details) {
+        return app_error_js_1.AppError.conflict(message, details);
+    }
+    /**
+     * Creates an InternalServerError (500) error
+     * @param message - Error message (default: "Internal Server Error")
+     * @param service - Service identifier
+     */
+    internalServerError(message = "Internal Server Error", service) {
+        return new app_error_js_1.AppError(message, status_code_js_1.StatusCode.InternalServerError, service, {
+            type: "https://expressots.dev/errors/internal-server-error",
+        });
     }
 };
 exports.Report = Report;
 exports.Report = Report = __decorate([
-    (0, inversify_1.injectable)()
+    (0, inversify_js_1.injectable)()
 ], Report);

package/lib/cjs/error/status-code.js

@@ -1,4 +1,24 @@
 "use strict";
+/**
+ * HTTP Status Code Enumerations
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept http-status-codes
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use StatusCode enum for HTTP status codes in errors and responses.
+ *
+ * @example
+ * ```typescript
+ * import { StatusCode } from "@expressots/core";
+ *
+ * throw new AppError("Not found", StatusCode.NotFound);
+ * ```
+ *
+ * @public API
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StatusCode = void 0;
 /* Http Error Code Response */

package/lib/cjs/error/utils.js

@@ -1,41 +1,255 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.beautifyStackTrace = beautifyStackTrace;
-const chalk_1 = __importDefault(require("chalk"));
+const color_codes_js_1 = require("../console/color-codes.js");
+// ANSI escape codes for text formatting
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+// Regex to strip ANSI escape codes
+// eslint-disable-next-line no-control-regex
+const ANSI_STRIP_REGEX = /\x1b\[[0-9;]*m/g;
+// Box configuration - matches ExpressoTS banner width
+const BOX_WIDTH = 90;
+const CONTENT_WIDTH = BOX_WIDTH - 4; // Account for "║ " and " ║"
+/**
+ * Strip ANSI escape codes to get visible text.
+ */
+function stripAnsi(text) {
+    return text.replace(ANSI_STRIP_REGEX, "");
+}
+/**
+ * Get the visible length of a string (excluding ANSI codes).
+ * Accounts for emojis which display as 2 characters wide in terminals.
+ */
+function visibleLength(text) {
+    const stripped = stripAnsi(text);
+    let len = 0;
+    // Iterate using Array.from to properly handle surrogate pairs
+    for (const char of Array.from(stripped)) {
+        const code = char.codePointAt(0) || 0;
+        // Emojis typically display as 2 characters wide in terminals
+        // These ranges cover most common emojis
+        if (code >= 0x1f000) {
+            // Emoji range starts at U+1F000
+            len += 2;
+        }
+        else {
+            len += 1;
+        }
+    }
+    return len;
+}
+/**
+ * Color text helper.
+ */
+function colorText(text, color, bold = false) {
+    const boldCode = bold ? BOLD : "";
+    return `${boldCode}${color_codes_js_1.colorCodes[color]}${text}${RESET}`;
+}
+/**
+ * Write to stdout directly.
+ */
+function writeStdout(text) {
+    process.stdout.write(text);
+}
+/**
+ * Write a boxed line with proper padding.
+ */
+function writeBoxLine(content) {
+    const visLen = visibleLength(content);
+    const padding = Math.max(0, CONTENT_WIDTH - visLen);
+    writeStdout(colorText("║", "red") +
+        " " +
+        content +
+        " ".repeat(padding) +
+        " " +
+        colorText("║", "red") +
+        "\n");
+}
+/**
+ * Write a horizontal border line.
+ */
+function writeBorder(type) {
+    const chars = {
+        top: { left: "╔", right: "╗", fill: "═" },
+        middle: { left: "╠", right: "╣", fill: "═" },
+        bottom: { left: "╚", right: "╝", fill: "═" },
+        divider: { left: "╟", right: "╢", fill: "─" },
+    };
+    const { left, right, fill } = chars[type];
+    writeStdout(colorText(`${left}${fill.repeat(BOX_WIDTH - 2)}${right}`, "red") + "\n");
+}
+/**
+ * Truncate text to fit within max width, adding ellipsis if needed.
+ */
+function truncateText(text, maxWidth) {
+    if (text.length <= maxWidth) {
+        return text;
+    }
+    return text.substring(0, maxWidth - 3) + "...";
+}
+/**
+ * Parse a stack frame line into structured data.
+ */
+function parseStackFrame(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("at"))
+        return null;
+    const isExternal = trimmed.includes("node_modules");
+    // Match: at FunctionName (filepath:line:col) or at filepath:line:col
+    const matchWithFunc = trimmed.match(/at\s+(.+?)\s+\((.+):(\d+):(\d+)\)/);
+    const matchWithoutFunc = trimmed.match(/at\s+(.+):(\d+):(\d+)/);
+    let functionName = "";
+    let filePath = "";
+    let lineNumber = "";
+    let columnNumber = "";
+    if (matchWithFunc) {
+        functionName = matchWithFunc[1];
+        filePath = matchWithFunc[2];
+        lineNumber = matchWithFunc[3];
+        columnNumber = matchWithFunc[4];
+    }
+    else if (matchWithoutFunc) {
+        functionName = "<anonymous>";
+        filePath = matchWithoutFunc[1];
+        lineNumber = matchWithoutFunc[2];
+        columnNumber = matchWithoutFunc[3];
+    }
+    else {
+        return null;
+    }
+    // Create short path (last 2 segments or from src/)
+    const pathParts = filePath.split(/[/\\]/);
+    let shortPath = filePath;
+    const srcIndex = pathParts.findIndex((p) => p === "src");
+    if (srcIndex !== -1) {
+        shortPath = pathParts.slice(srcIndex).join("/");
+    }
+    else if (pathParts.length > 2) {
+        shortPath = ".../" + pathParts.slice(-2).join("/");
+    }
+    return {
+        isExternal,
+        functionName,
+        filePath,
+        lineNumber,
+        columnNumber,
+        shortPath,
+    };
+}
+/**
+ * Beautify stack trace with professional ExpressoTS styling.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept error-visualization
+ *
+ * @summary
+ * Formats error stack traces with visual clarity for development debugging.
+ * Separates application code from external libraries and highlights the error origin.
+ *
+ * @param stack - Raw stack trace string
+ * @returns Empty string (output is written directly to stdout)
+ *
+ * @public API
+ */
 function beautifyStackTrace(stack) {
     if (!stack)
-        return;
+        return "";
     const lines = stack.split("\n");
-    const errorMessage = lines.shift()?.trim();
-    const maxOriginLength = "[External Library]".length;
-    const stackLines = lines
-        .filter((line) => line.trim().startsWith("at"))
-        .map((line) => line.trim())
-        .map((line) => {
-        const isExternalLib = line.includes("node_modules");
-        const filePathMatch = line.match(/\((.*):(\d+):(\d+)\)/);
-        const filePath = filePathMatch
-            ? `${filePathMatch[1]}:${filePathMatch[2]}:${filePathMatch[3]}`
-            : "";
-        const stackMessage = line.replace(/\(.*\)/, "").trim();
-        return {
-            origin: isExternalLib
-                ? chalk_1.default.gray("[External Library]").padEnd(maxOriginLength)
-                : chalk_1.default.gray("[Application]     ").padEnd(maxOriginLength),
-            stackMessage: chalk_1.default.green(stackMessage),
-            filePath: chalk_1.default.white(filePath),
-        };
-    });
-    if (stackLines.length > 0) {
-        console.log(chalk_1.default.red.bold(`Error Originated From: ${chalk_1.default.bold.white(stackLines[0]?.filePath || "unknown")}`));
-    }
-    console.log(chalk_1.default.red.bold(errorMessage));
-    console.log(chalk_1.default.blue.bold("\nStack Trace:\n"));
-    stackLines.forEach(({ origin, stackMessage, filePath }) => {
-        console.log(`${origin} | ${stackMessage} | ${filePath}`);
-    });
+    const errorMessage = lines.shift()?.trim() || "Unknown Error";
+    // Parse all stack frames
+    const frames = [];
+    for (const line of lines) {
+        const frame = parseStackFrame(line);
+        if (frame) {
+            frames.push(frame);
+        }
+    }
+    if (frames.length === 0) {
+        writeStdout(colorText(`\n[ERROR] ${errorMessage}`, "red", true) + "\n");
+        return "";
+    }
+    // Separate application and external frames
+    const appFrames = frames.filter((f) => !f.isExternal);
+    const extFrames = frames.filter((f) => f.isExternal);
+    // Draw the error box
+    writeStdout("\n");
+    writeBorder("top");
+    // Header - centered title (using ASCII for consistent width)
+    const headerText = "[!] RUNTIME ERROR";
+    const headerPadding = Math.floor((CONTENT_WIDTH - headerText.length) / 2);
+    writeBoxLine(" ".repeat(headerPadding) +
+        colorText(headerText, "red", true) +
+        " ".repeat(CONTENT_WIDTH - headerPadding - headerText.length));
+    writeBorder("middle");
+    // Error message - truncate if too long
+    const truncatedMessage = truncateText(errorMessage, CONTENT_WIDTH);
+    writeBoxLine(colorText(truncatedMessage, "white", true));
+    writeBorder("middle");
+    // Error origin (first application frame)
+    const origin = appFrames[0] || frames[0];
+    writeBoxLine(colorText("[>] Origin:", "yellow", true));
+    writeBoxLine("    " +
+        colorText(truncateText(origin.functionName, CONTENT_WIDTH - 4), "cyan"));
+    // File path - truncate and wrap if needed
+    const originLocation = `${origin.filePath}:${origin.lineNumber}:${origin.columnNumber}`;
+    const truncatedLocation = truncateText(originLocation, CONTENT_WIDTH - 8);
+    writeBoxLine("    -> " + colorText(truncatedLocation, "white"));
+    writeBorder("middle");
+    // Application Stack Frames
+    if (appFrames.length > 0) {
+        writeBoxLine(colorText(`[+] Application Stack (${appFrames.length} frames):`, "green", true));
+        const maxAppFrames = Math.min(appFrames.length, 5);
+        for (let i = 0; i < maxAppFrames; i++) {
+            const frame = appFrames[i];
+            const connector = i === maxAppFrames - 1 && appFrames.length <= 5 ? "`-" : "|-";
+            const frameNum = String(i + 1).padStart(2, " ");
+            const funcName = truncateText(frame.functionName, CONTENT_WIDTH - 16);
+            writeBoxLine(`    ${connector} ` +
+                colorText(`#${frameNum}`, "blue") +
+                " " +
+                colorText(funcName, "cyan"));
+            // Location line (shortened path)
+            const locText = truncateText(`${frame.shortPath}:${frame.lineNumber}`, CONTENT_WIDTH - 10);
+            writeBoxLine(`       ${DIM}${locText}${RESET}`);
+        }
+        if (appFrames.length > 5) {
+            const remaining = appFrames.length - 5;
+            writeBoxLine(`    \`- ${colorText(`... +${remaining} more`, "white")}`);
+        }
+    }
+    // External Library Frames (collapsed summary)
+    if (extFrames.length > 0) {
+        writeBorder("divider");
+        writeBoxLine(colorText(`[~] External Libraries (${extFrames.length} frames):`, "blue"));
+        // Show first 3 external frames in compact form
+        const maxExtFrames = Math.min(extFrames.length, 3);
+        for (let i = 0; i < maxExtFrames; i++) {
+            const frame = extFrames[i];
+            const connector = i === maxExtFrames - 1 && extFrames.length <= 3 ? "`-" : "|-";
+            // Extract package name from node_modules path
+            const nodeModulesMatch = frame.filePath.match(/node_modules[/\\](@[^/\\]+[/\\][^/\\]+|[^/\\]+)/);
+            const packageName = nodeModulesMatch
+                ? nodeModulesMatch[1].replace(/\\/g, "/")
+                : "external";
+            const funcName = truncateText(frame.functionName, 30);
+            const pkgName = truncateText(packageName, 25);
+            writeBoxLine(`    ${connector} ` +
+                colorText(funcName, "white") +
+                ` ${DIM}(${pkgName})${RESET}`);
+        }
+        if (extFrames.length > 3) {
+            const remaining = extFrames.length - 3;
+            writeBoxLine(`    \`- ${colorText(`... +${remaining} more`, "white")}`);
+        }
+    }
+    // Footer with timestamp
+    writeBorder("middle");
+    const timestamp = new Date().toISOString();
+    writeBoxLine(colorText(`[*] ${timestamp}`, "yellow"));
+    writeBorder("bottom");
+    writeStdout("\n");
     return "";
 }

package/lib/cjs/error/validation.error.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+const app_error_js_1 = require("./app-error.js");
+const status_code_js_1 = require("./status-code.js");
+/**
+ * ValidationError - Specific error type for validation failures
+ */
+class ValidationError extends app_error_js_1.AppError {
+    constructor(errors) {
+        super("Validation failed", status_code_js_1.StatusCode.UnprocessableEntity, undefined, {
+            type: "https://expressots.dev/errors/validation-failed",
+            validationErrors: errors,
+        });
+        this.errors = errors;
+    }
+}
+exports.ValidationError = ValidationError;