@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/error/report.js

@@ -0,0 +1,153 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from "../di/inversify.js";
+import { AppError, } from "./app-error.js";
+import { StatusCode } from "./status-code.js";
+/**
+ * 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 {
+    name = "Report Provider";
+    version = "4.0.0";
+    author = "Richard Zampieri";
+    repo = "https://github.com/expressots/expressots";
+    static stack;
+    /**
+     * The Error method is responsible for generating a standardized error object,
+     * logging the error, and then throwing it for further handling.
+     * The error thrown is of the custom type AppError, which extends the built-in Error class.
+     *
+     * @param error - An instance of Error or a string that describes the error.
+     * @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, options) {
+        let message = "";
+        if (error == null) {
+            // error is null or undefined
+            message = "";
+        }
+        else if (typeof error === "string") {
+            message = error;
+        }
+        else if (error instanceof Error) {
+            message = error.message;
+        }
+        else if (typeof error === "object" && "message" in error) {
+            message = error.message;
+        }
+        else {
+            message = String(error);
+        }
+        return new AppError(message, statusCode, service, options);
+    }
+    /**
+     * Creates a BadRequest (400) error
+     * @param message - Error message
+     * @param details - Additional error details
+     */
+    badRequest(message, details) {
+        return 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 AppError.notFound(resource, id);
+    }
+    /**
+     * Creates an Unauthorized (401) error
+     * @param message - Error message (default: "Unauthorized")
+     */
+    unauthorized(message = "Unauthorized") {
+        return AppError.unauthorized(message);
+    }
+    /**
+     * Creates a Forbidden (403) error
+     * @param message - Error message (default: "Forbidden")
+     */
+    forbidden(message = "Forbidden") {
+        return AppError.forbidden(message);
+    }
+    /**
+     * Creates an UnprocessableEntity (422) validation error
+     * @param errors - Array of validation errors
+     */
+    validationFailed(errors) {
+        return AppError.validationFailed(errors);
+    }
+    /**
+     * Creates a Conflict (409) error
+     * @param message - Error message
+     * @param details - Additional error details
+     */
+    conflict(message, details) {
+        return 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 AppError(message, StatusCode.InternalServerError, service, {
+            type: "https://expressots.dev/errors/internal-server-error",
+        });
+    }
+};
+Report = __decorate([
+    injectable()
+], Report);
+export { Report };

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

@@ -0,0 +1,106 @@
+/**
+ * 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
+ */
+/* Http Error Code Response */
+var InformationResponse;
+(function (InformationResponse) {
+    InformationResponse[InformationResponse["Continue"] = 100] = "Continue";
+    InformationResponse[InformationResponse["SwitchingProtocols"] = 101] = "SwitchingProtocols";
+    InformationResponse[InformationResponse["Processing"] = 102] = "Processing";
+    InformationResponse[InformationResponse["eEarlyHints"] = 103] = "eEarlyHints";
+})(InformationResponse || (InformationResponse = {}));
+var SuccessfulResponse;
+(function (SuccessfulResponse) {
+    SuccessfulResponse[SuccessfulResponse["OK"] = 200] = "OK";
+    SuccessfulResponse[SuccessfulResponse["Created"] = 201] = "Created";
+    SuccessfulResponse[SuccessfulResponse["Accepted"] = 202] = "Accepted";
+    SuccessfulResponse[SuccessfulResponse["NonAuthoritativeInformation"] = 203] = "NonAuthoritativeInformation";
+    SuccessfulResponse[SuccessfulResponse["NoContent"] = 204] = "NoContent";
+    SuccessfulResponse[SuccessfulResponse["ResetContent"] = 205] = "ResetContent";
+    SuccessfulResponse[SuccessfulResponse["PartialContent"] = 206] = "PartialContent";
+    SuccessfulResponse[SuccessfulResponse["MultiStatus"] = 207] = "MultiStatus";
+    SuccessfulResponse[SuccessfulResponse["AlreadyReported"] = 208] = "AlreadyReported";
+    SuccessfulResponse[SuccessfulResponse["IMUsed"] = 226] = "IMUsed";
+})(SuccessfulResponse || (SuccessfulResponse = {}));
+var RedirectionMessage;
+(function (RedirectionMessage) {
+    RedirectionMessage[RedirectionMessage["MultipleChoices"] = 300] = "MultipleChoices";
+    RedirectionMessage[RedirectionMessage["MovedPermanently"] = 301] = "MovedPermanently";
+    RedirectionMessage[RedirectionMessage["Found"] = 302] = "Found";
+    RedirectionMessage[RedirectionMessage["SeeOther"] = 303] = "SeeOther";
+    RedirectionMessage[RedirectionMessage["NotModified"] = 304] = "NotModified";
+    RedirectionMessage[RedirectionMessage["TemporaryRedirect"] = 307] = "TemporaryRedirect";
+    RedirectionMessage[RedirectionMessage["PermanentRedirect"] = 308] = "PermanentRedirect";
+})(RedirectionMessage || (RedirectionMessage = {}));
+var ClientErrorResponse;
+(function (ClientErrorResponse) {
+    ClientErrorResponse[ClientErrorResponse["BadRequest"] = 400] = "BadRequest";
+    ClientErrorResponse[ClientErrorResponse["Unauthorized"] = 401] = "Unauthorized";
+    ClientErrorResponse[ClientErrorResponse["PaymentRequired"] = 402] = "PaymentRequired";
+    ClientErrorResponse[ClientErrorResponse["Forbidden"] = 403] = "Forbidden";
+    ClientErrorResponse[ClientErrorResponse["NotFound"] = 404] = "NotFound";
+    ClientErrorResponse[ClientErrorResponse["MethodNotAllowed"] = 405] = "MethodNotAllowed";
+    ClientErrorResponse[ClientErrorResponse["NotAcceptable"] = 406] = "NotAcceptable";
+    ClientErrorResponse[ClientErrorResponse["ProxyAuthenticationRequired"] = 407] = "ProxyAuthenticationRequired";
+    ClientErrorResponse[ClientErrorResponse["RequestTimeout"] = 408] = "RequestTimeout";
+    ClientErrorResponse[ClientErrorResponse["Conflict"] = 409] = "Conflict";
+    ClientErrorResponse[ClientErrorResponse["Gone"] = 410] = "Gone";
+    ClientErrorResponse[ClientErrorResponse["LengthRequired"] = 411] = "LengthRequired";
+    ClientErrorResponse[ClientErrorResponse["PreconditionFailed"] = 412] = "PreconditionFailed";
+    ClientErrorResponse[ClientErrorResponse["PayloadTooLarge"] = 413] = "PayloadTooLarge";
+    ClientErrorResponse[ClientErrorResponse["URITooLong"] = 414] = "URITooLong";
+    ClientErrorResponse[ClientErrorResponse["UnsupportedMediaType"] = 415] = "UnsupportedMediaType";
+    ClientErrorResponse[ClientErrorResponse["RangeNotSatisfiable"] = 416] = "RangeNotSatisfiable";
+    ClientErrorResponse[ClientErrorResponse["ExpectationFailed"] = 417] = "ExpectationFailed";
+    ClientErrorResponse[ClientErrorResponse["ImATeapot"] = 418] = "ImATeapot";
+    ClientErrorResponse[ClientErrorResponse["MisdirectedRequest"] = 421] = "MisdirectedRequest";
+    ClientErrorResponse[ClientErrorResponse["UnprocessableEntity"] = 422] = "UnprocessableEntity";
+    ClientErrorResponse[ClientErrorResponse["Locked"] = 423] = "Locked";
+    ClientErrorResponse[ClientErrorResponse["FailedDependency"] = 424] = "FailedDependency";
+    ClientErrorResponse[ClientErrorResponse["TooEarly"] = 425] = "TooEarly";
+    ClientErrorResponse[ClientErrorResponse["UpgradeRequired"] = 426] = "UpgradeRequired";
+    ClientErrorResponse[ClientErrorResponse["PreconditionRequired"] = 428] = "PreconditionRequired";
+    ClientErrorResponse[ClientErrorResponse["TooManyRequests"] = 429] = "TooManyRequests";
+    ClientErrorResponse[ClientErrorResponse["RequestHeaderFieldsTooLarge"] = 431] = "RequestHeaderFieldsTooLarge";
+    ClientErrorResponse[ClientErrorResponse["UnavailableForLegalReasons"] = 451] = "UnavailableForLegalReasons";
+})(ClientErrorResponse || (ClientErrorResponse = {}));
+var ServerErrorResponse;
+(function (ServerErrorResponse) {
+    ServerErrorResponse[ServerErrorResponse["InternalServerError"] = 500] = "InternalServerError";
+    ServerErrorResponse[ServerErrorResponse["NotImplemented"] = 501] = "NotImplemented";
+    ServerErrorResponse[ServerErrorResponse["BadGateway"] = 502] = "BadGateway";
+    ServerErrorResponse[ServerErrorResponse["ServiceUnavailable"] = 503] = "ServiceUnavailable";
+    ServerErrorResponse[ServerErrorResponse["GatewayTimeout"] = 504] = "GatewayTimeout";
+    ServerErrorResponse[ServerErrorResponse["HTTPVersionNotSupported"] = 505] = "HTTPVersionNotSupported";
+    ServerErrorResponse[ServerErrorResponse["VariantAlsoNegotiates"] = 506] = "VariantAlsoNegotiates";
+    ServerErrorResponse[ServerErrorResponse["InsufficientStorage"] = 507] = "InsufficientStorage";
+    ServerErrorResponse[ServerErrorResponse["LoopDetected"] = 508] = "LoopDetected";
+    ServerErrorResponse[ServerErrorResponse["NotExtended"] = 510] = "NotExtended";
+    ServerErrorResponse[ServerErrorResponse["NetworkAuthenticationRequired"] = 511] = "NetworkAuthenticationRequired";
+})(ServerErrorResponse || (ServerErrorResponse = {}));
+const HttpStatusErrorCode = {
+    ...InformationResponse,
+    ...SuccessfulResponse,
+    ...RedirectionMessage,
+    ...ClientErrorResponse,
+    ...ServerErrorResponse,
+};
+const StatusCode = { ...HttpStatusErrorCode };
+export { StatusCode };

package/lib/esm/error/utils.js

@@ -0,0 +1,252 @@
+import { colorCodes } from "../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}${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
+ */
+export function beautifyStackTrace(stack) {
+    if (!stack)
+        return "";
+    const lines = stack.split("\n");
+    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/esm/error/validation.error.js

@@ -0,0 +1,15 @@
+import { AppError, } from "./app-error.js";
+import { StatusCode } from "./status-code.js";
+/**
+ * ValidationError - Specific error type for validation failures
+ */
+export class ValidationError extends AppError {
+    errors;
+    constructor(errors) {
+        super("Validation failed", StatusCode.UnprocessableEntity, undefined, {
+            type: "https://expressots.dev/errors/validation-failed",
+            validationErrors: errors,
+        });
+        this.errors = errors;
+    }
+}