@wnodex/errors 0.2.1

package/.turbo/turbo-build.log

@@ -0,0 +1,7 @@
+
+> @wnodex/errors@0.2.1 build /home/runner/work/wnodex/wnodex/packages/errors
+> rolldown -c && tsc
+
+[log] <DIR>/index.js  chunk │ size: 6.67 kB
+[log]
+[success] rolldown v1.0.0-rc.1 Finished in 49.36 ms

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Di Criscito
+
+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,19 @@
+# @wnodex/errors
+
+wnodex custom application errors
+
+---
+
+## Table of Content
+
+- [License](#license)
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+**Copyright (c) 2026 Davide Di Criscito**
+
+For the full details, see the [LICENSE](LICENSE) file.

package/dist/base-error.d.ts

@@ -0,0 +1,57 @@
+import type { ErrorMetadataInput } from './error-metadata.js';
+/**
+ * Base class for all custom application errors.
+ * Extends the native `Error` to preserve stack traces and adds structured, validated metadata.
+ *
+ * Provides consistent error information for debugging and structured logging.
+ */
+export declare class BaseError extends Error {
+    /**
+     * The machine-readable error code, suitable for programmatic handling.
+     * @readonly
+     */
+    readonly code: string;
+    /**
+     * The optional cause that triggered this error instance.
+     * May be any value, but usually another Error object for chained errors.
+     * @override
+     * @readonly
+     */
+    readonly cause?: unknown;
+    /**
+     * Additional error context for debugging (may contain any serializable data).
+     * @readonly
+     */
+    readonly context?: unknown;
+    /**
+     * Constructs a new instance of BaseError.
+     * Validates the provided metadata to ensure it matches the ErrorMetadataSchema.
+     * @param message The human-readable error message.
+     * @param metadata Structured metadata for this error instance. It will be validated.
+     * @throws {Error} Throws if the metadata is invalid according to ErrorMetadataSchema.
+     * @example
+     * const err = new BaseError('User not found', { code: 'USER_NOT_FOUND' });
+     */
+    constructor(message: string, metadata: ErrorMetadataInput);
+    /**
+     * Validates the error metadata using ErrorMetadataSchema.
+     * Throws a clear error if validation fails, including the original Zod error as the cause.
+     * @param input The raw metadata input.
+     * @param parentErrorMessage The message of the error being constructed, for improved diagnostics.
+     * @returns {ErrorMetadataOutput} Parsed and validated metadata.
+     * @throws {Error} If the metadata does not pass validation.
+     * @example
+     * this.validateMetadata({ code: 'INVALID', context: { foo: 42 } }, 'Something failed');
+     */
+    private validateMetadata;
+    /**
+     * Returns a plain object representation of the error,
+     * useful for structured logging, serialization, or external error reporting.
+     * Nested error causes include their name, message, and stack trace.
+     * @returns {object} A plain, serializable object representing this error.
+     * @example
+     * JSON.stringify(err.toJSON());
+     */
+    toJSON(): object;
+}
+//# sourceMappingURL=base-error.d.ts.map

package/dist/base-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-error.d.ts","sourceRoot":"","sources":["../src/base-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,qBAAqB,CAAC;AAG7B;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC;;;OAGG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhC;;;OAGG;IACH,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;;;OAQG;gBACS,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB;IAgBzD;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM;CAmBjB"}

package/dist/base-error.js

@@ -0,0 +1,90 @@
+import { ErrorMetadataSchema } from './error-metadata.js';
+/**
+ * Base class for all custom application errors.
+ * Extends the native `Error` to preserve stack traces and adds structured, validated metadata.
+ *
+ * Provides consistent error information for debugging and structured logging.
+ */
+export class BaseError extends Error {
+    /**
+     * The machine-readable error code, suitable for programmatic handling.
+     * @readonly
+     */
+    code;
+    /**
+     * The optional cause that triggered this error instance.
+     * May be any value, but usually another Error object for chained errors.
+     * @override
+     * @readonly
+     */
+    cause;
+    /**
+     * Additional error context for debugging (may contain any serializable data).
+     * @readonly
+     */
+    context;
+    /**
+     * Constructs a new instance of BaseError.
+     * Validates the provided metadata to ensure it matches the ErrorMetadataSchema.
+     * @param message The human-readable error message.
+     * @param metadata Structured metadata for this error instance. It will be validated.
+     * @throws {Error} Throws if the metadata is invalid according to ErrorMetadataSchema.
+     * @example
+     * const err = new BaseError('User not found', { code: 'USER_NOT_FOUND' });
+     */
+    constructor(message, metadata) {
+        super(message);
+        // Sets the name property to the actual class name (useful with inheritance).
+        this.name = new.target.name;
+        const validatedMetadata = this.validateMetadata(metadata, message);
+        this.code = validatedMetadata.code;
+        this.cause = validatedMetadata.cause;
+        this.context = validatedMetadata.context;
+        // Ensures proper prototype chain for custom errors (required for ES5/TypeScript).
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Validates the error metadata using ErrorMetadataSchema.
+     * Throws a clear error if validation fails, including the original Zod error as the cause.
+     * @param input The raw metadata input.
+     * @param parentErrorMessage The message of the error being constructed, for improved diagnostics.
+     * @returns {ErrorMetadataOutput} Parsed and validated metadata.
+     * @throws {Error} If the metadata does not pass validation.
+     * @example
+     * this.validateMetadata({ code: 'INVALID', context: { foo: 42 } }, 'Something failed');
+     */
+    validateMetadata(input, parentErrorMessage) {
+        const result = ErrorMetadataSchema.safeParse(input);
+        if (!result.success) {
+            const errorMessage = `Invalid metadata provided for error "${parentErrorMessage}" (Code: ${input.code || 'N/A'}).`;
+            console.error(result.error);
+            throw new Error(errorMessage);
+        }
+        return result.data;
+    }
+    /**
+     * Returns a plain object representation of the error,
+     * useful for structured logging, serialization, or external error reporting.
+     * Nested error causes include their name, message, and stack trace.
+     * @returns {object} A plain, serializable object representing this error.
+     * @example
+     * JSON.stringify(err.toJSON());
+     */
+    toJSON() {
+        const normalizedCause = this.cause instanceof Error
+            ? {
+                name: this.cause.name,
+                message: this.cause.message,
+                stack: this.cause.stack,
+            }
+            : this.cause;
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            cause: normalizedCause,
+            context: this.context,
+            stack: this.stack,
+        };
+    }
+}

package/dist/config-error.d.ts

@@ -0,0 +1,20 @@
+import { BaseError } from './base-error.js';
+/**
+ * Custom error class for configuration failures.
+ * Represents issues occurring during loading, parsing, or applying application configuration.
+ * Automatically sets the error code to `"CONFIG_ERROR"`. Useful for problems involving environment
+ * variables, config files, or settings.
+ */
+export declare class ConfigError extends BaseError {
+    /**
+     * Constructs a new ConfigError instance.
+     * @param message The human-readable error message describing the configuration problem.
+     * @param cause Optional original error or value that triggered the configuration failure, such as a file system or validation error.
+     * @param context Optional additional context data, such as the config file path, setting name, or problematic value.
+     *
+     * @example
+     * throw new ConfigError('Failed to load config file', readError, { file: './config.json' });
+     */
+    constructor(message: string, cause?: unknown, context?: Record<string | number | symbol, unknown>);
+}
+//# sourceMappingURL=config-error.d.ts.map

package/dist/config-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-error.d.ts","sourceRoot":"","sources":["../src/config-error.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,SAAS;IACxC;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;CAQtD"}

package/dist/config-error.js

@@ -0,0 +1,26 @@
+import { ERROR_CODES } from './error-codes.js';
+import { BaseError } from './base-error.js';
+/**
+ * Custom error class for configuration failures.
+ * Represents issues occurring during loading, parsing, or applying application configuration.
+ * Automatically sets the error code to `"CONFIG_ERROR"`. Useful for problems involving environment
+ * variables, config files, or settings.
+ */
+export class ConfigError extends BaseError {
+    /**
+     * Constructs a new ConfigError instance.
+     * @param message The human-readable error message describing the configuration problem.
+     * @param cause Optional original error or value that triggered the configuration failure, such as a file system or validation error.
+     * @param context Optional additional context data, such as the config file path, setting name, or problematic value.
+     *
+     * @example
+     * throw new ConfigError('Failed to load config file', readError, { file: './config.json' });
+     */
+    constructor(message, cause, context) {
+        super(message, {
+            code: ERROR_CODES.CONFIG_ERROR,
+            cause,
+            context,
+        });
+    }
+}

package/dist/error-codes.d.ts

@@ -0,0 +1,10 @@
+export declare const ERROR_CODES: {
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+};
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW;;;;;;;;CAQd,CAAC"}

package/dist/error-codes.js

@@ -0,0 +1,9 @@
+export const ERROR_CODES = {
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    CONFIG_ERROR: 'CONFIG_ERROR',
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    NOT_FOUND: 'NOT_FOUND',
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    FORBIDDEN: 'FORBIDDEN',
+    BAD_REQUEST: 'BAD_REQUEST',
+};

package/dist/error-handler.d.ts

@@ -0,0 +1,4 @@
+import type { NextFunction, Request, Response } from 'express';
+import { HttpError } from './http-error.js';
+export declare const errorHandler: (err: HttpError | Error, _req: Request, res: Response, _next: NextFunction) => void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,eAAO,MAAM,YAAY,GACvB,KAAK,SAAS,GAAG,KAAK,EACtB,MAAM,OAAO,EACb,KAAK,QAAQ,EACb,OAAO,YAAY,SA2BpB,CAAC"}

package/dist/error-handler.js

@@ -0,0 +1,22 @@
+export const errorHandler = (err, _req, res, _next) => {
+    // Log the error for server debugging
+    console.error(err);
+    // Determine HTTP status code; default to 500 if unavailable
+    const statusCode = typeof err === 'object' && err !== null && 'statusCode' in err
+        ? err.statusCode
+        : 500;
+    // Get message or default to 'Internal Server Error'
+    const message = typeof err === 'object' && err !== null && 'message' in err
+        ? err.message
+        : 'Internal Server Error';
+    // Send JSON response
+    res.status(statusCode).json({
+        error: {
+            message,
+            // Show stack trace only in development environment
+            ...(process.env.NODE_ENV !== 'production' && {
+                stack: err.stack,
+            }),
+        },
+    });
+};

package/dist/error-metadata.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const ErrorMetadataSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        VALIDATION_ERROR: "VALIDATION_ERROR";
+        CONFIG_ERROR: "CONFIG_ERROR";
+        INTERNAL_ERROR: "INTERNAL_ERROR";
+        NOT_FOUND: "NOT_FOUND";
+        UNAUTHORIZED: "UNAUTHORIZED";
+        FORBIDDEN: "FORBIDDEN";
+        BAD_REQUEST: "BAD_REQUEST";
+    }>;
+    cause: z.ZodOptional<z.ZodUnknown>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ErrorMetadata = z.infer<typeof ErrorMetadataSchema>;
+export type ErrorMetadataInput = z.input<typeof ErrorMetadataSchema>;
+export type ErrorMetadataOutput = z.output<typeof ErrorMetadataSchema>;
+//# sourceMappingURL=error-metadata.d.ts.map

package/dist/error-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-metadata.d.ts","sourceRoot":"","sources":["../src/error-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;kBAMrB,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACrE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/error-metadata.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { ERROR_CODES } from './error-codes.js';
+export const ErrorMetadataSchema = z
+    .object({
+    code: z.enum(Object.values(ERROR_CODES)),
+    cause: z.unknown().optional(),
+    context: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();

package/dist/http-error.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Custom HTTP error class with status code.
+ * Represents an HTTP error with both status code and message.
+ */
+export declare class HttpError extends Error {
+    readonly statusCode: number;
+    /**
+     * Creates an instance of HttpError.
+     * @param message Error message describing the problem.
+     * @param statusCode HTTP status code, default is 500.
+     * @example
+     * // Throws an error with 404 status code
+     * throw new HttpError('Not Found', 404);
+     */
+    constructor(message: string, statusCode?: number);
+}
+//# sourceMappingURL=http-error.d.ts.map

package/dist/http-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-error.d.ts","sourceRoot":"","sources":["../src/http-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;;;;;;OAOG;gBACS,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM;CAK9C"}

package/dist/http-error.js

@@ -0,0 +1,20 @@
+/**
+ * Custom HTTP error class with status code.
+ * Represents an HTTP error with both status code and message.
+ */
+export class HttpError extends Error {
+    statusCode;
+    /**
+     * Creates an instance of HttpError.
+     * @param message Error message describing the problem.
+     * @param statusCode HTTP status code, default is 500.
+     * @example
+     * // Throws an error with 404 status code
+     * throw new HttpError('Not Found', 404);
+     */
+    constructor(message, statusCode = 500) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = this.constructor.name;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './base-error.js';
+export * from './config-error.js';
+export * from './error-codes.js';
+export * from './error-handler.js';
+export * from './error-metadata.js';
+export * from './http-error.js';
+export * from './validation-error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './base-error.js';
+export * from './config-error.js';
+export * from './error-codes.js';
+export * from './error-handler.js';
+export * from './error-metadata.js';
+export * from './http-error.js';
+export * from './validation-error.js';

package/dist/validation-error.d.ts

@@ -0,0 +1,19 @@
+import { BaseError } from './base-error.js';
+/**
+ * Custom error class for validation failures.
+ * Used for input errors, schema violations, or data integrity issues.
+ * Automatically sets the error code to `"VALIDATION_ERROR"` to allow standard handling of validation errors.
+ */
+export declare class ValidationError extends BaseError {
+    /**
+     * Constructs a new ValidationError instance.
+     * @param message The human-readable error message describing what failed validation.
+     * @param cause Optional original error or value that caused the validation failure, such as a ZodError or validation detail.
+     * @param context Optional additional context data, for example the invalid field, config path, or offending input.
+     *
+     * @example
+     * throw new ValidationError('Invalid email format', zodResult.error, { field: 'email' });
+     */
+    constructor(message: string, cause?: unknown, context?: Record<string | number | symbol, unknown>);
+}
+//# sourceMappingURL=validation-error.d.ts.map

package/dist/validation-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-error.d.ts","sourceRoot":"","sources":["../src/validation-error.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;CAQtD"}

package/dist/validation-error.js

@@ -0,0 +1,25 @@
+import { ERROR_CODES } from './error-codes.js';
+import { BaseError } from './base-error.js';
+/**
+ * Custom error class for validation failures.
+ * Used for input errors, schema violations, or data integrity issues.
+ * Automatically sets the error code to `"VALIDATION_ERROR"` to allow standard handling of validation errors.
+ */
+export class ValidationError extends BaseError {
+    /**
+     * Constructs a new ValidationError instance.
+     * @param message The human-readable error message describing what failed validation.
+     * @param cause Optional original error or value that caused the validation failure, such as a ZodError or validation detail.
+     * @param context Optional additional context data, for example the invalid field, config path, or offending input.
+     *
+     * @example
+     * throw new ValidationError('Invalid email format', zodResult.error, { field: 'email' });
+     */
+    constructor(message, cause, context) {
+        super(message, {
+            code: ERROR_CODES.VALIDATION_ERROR,
+            cause,
+            context,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@wnodex/errors",
+  "version": "0.2.1",
+  "private": false,
+  "description": "wnodex custom application errors",
+  "keywords": [
+    "wnodex",
+    "errors"
+  ],
+  "homepage": "https://github.com/wnodex/wnodex#readme",
+  "bugs": {
+    "url": "https://github.com/wnodex/wnodex/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wnodex/wnodex.git",
+    "directory": "packages/errors"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "express": "^5.2.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.10",
+    "rolldown": "1.0.0-rc.1",
+    "typescript": "5.9.2",
+    "@wnodex/typescript-config": "0.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rolldown -c && tsc"
+  }
+}

package/rolldown.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'rolldown';
+
+export default defineConfig([
+  {
+    input: ['src/index.ts'],
+    output: {
+      format: 'esm',
+      dir: 'dist',
+      entryFileNames: '[name].js',
+      chunkFileNames: '[name]-[hash].js',
+      assetFileNames: '[name]-[hash][extname]',
+    },
+    platform: 'node',
+    external: (id) => {
+      if (id.startsWith('node:')) return true;
+      if (id.startsWith('.') || id.startsWith('/')) return false;
+      return true;
+    },
+  },
+]);

package/src/base-error.ts

@@ -0,0 +1,112 @@
+import type {
+  ErrorMetadataInput,
+  ErrorMetadataOutput,
+} from './error-metadata.js';
+import { ErrorMetadataSchema } from './error-metadata.js';
+
+/**
+ * Base class for all custom application errors.
+ * Extends the native `Error` to preserve stack traces and adds structured, validated metadata.
+ *
+ * Provides consistent error information for debugging and structured logging.
+ */
+export class BaseError extends Error {
+  /**
+   * The machine-readable error code, suitable for programmatic handling.
+   * @readonly
+   */
+  public readonly code: string;
+
+  /**
+   * The optional cause that triggered this error instance.
+   * May be any value, but usually another Error object for chained errors.
+   * @override
+   * @readonly
+   */
+  public readonly cause?: unknown;
+
+  /**
+   * Additional error context for debugging (may contain any serializable data).
+   * @readonly
+   */
+  public readonly context?: unknown;
+
+  /**
+   * Constructs a new instance of BaseError.
+   * Validates the provided metadata to ensure it matches the ErrorMetadataSchema.
+   * @param message The human-readable error message.
+   * @param metadata Structured metadata for this error instance. It will be validated.
+   * @throws {Error} Throws if the metadata is invalid according to ErrorMetadataSchema.
+   * @example
+   * const err = new BaseError('User not found', { code: 'USER_NOT_FOUND' });
+   */
+  constructor(message: string, metadata: ErrorMetadataInput) {
+    super(message);
+
+    // Sets the name property to the actual class name (useful with inheritance).
+    this.name = new.target.name;
+
+    const validatedMetadata = this.validateMetadata(metadata, message);
+
+    this.code = validatedMetadata.code;
+    this.cause = validatedMetadata.cause;
+    this.context = validatedMetadata.context;
+
+    // Ensures proper prototype chain for custom errors (required for ES5/TypeScript).
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  /**
+   * Validates the error metadata using ErrorMetadataSchema.
+   * Throws a clear error if validation fails, including the original Zod error as the cause.
+   * @param input The raw metadata input.
+   * @param parentErrorMessage The message of the error being constructed, for improved diagnostics.
+   * @returns {ErrorMetadataOutput} Parsed and validated metadata.
+   * @throws {Error} If the metadata does not pass validation.
+   * @example
+   * this.validateMetadata({ code: 'INVALID', context: { foo: 42 } }, 'Something failed');
+   */
+  private validateMetadata(
+    input: ErrorMetadataInput,
+    parentErrorMessage: string
+  ): ErrorMetadataOutput {
+    const result = ErrorMetadataSchema.safeParse(input);
+
+    if (!result.success) {
+      const errorMessage = `Invalid metadata provided for error "${parentErrorMessage}" (Code: ${input.code || 'N/A'}).`;
+
+      console.error(result.error);
+      throw new Error(errorMessage);
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Returns a plain object representation of the error,
+   * useful for structured logging, serialization, or external error reporting.
+   * Nested error causes include their name, message, and stack trace.
+   * @returns {object} A plain, serializable object representing this error.
+   * @example
+   * JSON.stringify(err.toJSON());
+   */
+  toJSON(): object {
+    const normalizedCause =
+      this.cause instanceof Error
+        ? {
+            name: this.cause.name,
+            message: this.cause.message,
+            stack: this.cause.stack,
+          }
+        : this.cause;
+
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      cause: normalizedCause,
+      context: this.context,
+      stack: this.stack,
+    };
+  }
+}

package/src/config-error.ts

@@ -0,0 +1,31 @@
+import { ERROR_CODES } from './error-codes.js';
+import { BaseError } from './base-error.js';
+
+/**
+ * Custom error class for configuration failures.
+ * Represents issues occurring during loading, parsing, or applying application configuration.
+ * Automatically sets the error code to `"CONFIG_ERROR"`. Useful for problems involving environment
+ * variables, config files, or settings.
+ */
+export class ConfigError extends BaseError {
+  /**
+   * Constructs a new ConfigError instance.
+   * @param message The human-readable error message describing the configuration problem.
+   * @param cause Optional original error or value that triggered the configuration failure, such as a file system or validation error.
+   * @param context Optional additional context data, such as the config file path, setting name, or problematic value.
+   *
+   * @example
+   * throw new ConfigError('Failed to load config file', readError, { file: './config.json' });
+   */
+  constructor(
+    message: string,
+    cause?: unknown,
+    context?: Record<string | number | symbol, unknown>
+  ) {
+    super(message, {
+      code: ERROR_CODES.CONFIG_ERROR,
+      cause,
+      context,
+    });
+  }
+}

package/src/error-codes.ts

@@ -0,0 +1,9 @@
+export const ERROR_CODES = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  CONFIG_ERROR: 'CONFIG_ERROR',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  BAD_REQUEST: 'BAD_REQUEST',
+} as const;

package/src/error-handler.ts

@@ -0,0 +1,36 @@
+import type { NextFunction, Request, Response } from 'express';
+
+import { HttpError } from './http-error.js';
+
+export const errorHandler = (
+  err: HttpError | Error,
+  _req: Request,
+  res: Response,
+  _next: NextFunction
+) => {
+  // Log the error for server debugging
+  console.error(err);
+
+  // Determine HTTP status code; default to 500 if unavailable
+  const statusCode =
+    typeof err === 'object' && err !== null && 'statusCode' in err
+      ? err.statusCode
+      : 500;
+
+  // Get message or default to 'Internal Server Error'
+  const message =
+    typeof err === 'object' && err !== null && 'message' in err
+      ? err.message
+      : 'Internal Server Error';
+
+  // Send JSON response
+  res.status(statusCode).json({
+    error: {
+      message,
+      // Show stack trace only in development environment
+      ...(process.env.NODE_ENV !== 'production' && {
+        stack: err.stack,
+      }),
+    },
+  });
+};

package/src/error-metadata.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+import { ERROR_CODES } from './error-codes.js';
+
+export const ErrorMetadataSchema = z
+  .object({
+    code: z.enum(Object.values(ERROR_CODES)),
+    cause: z.unknown().optional(),
+    context: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+export type ErrorMetadata = z.infer<typeof ErrorMetadataSchema>;
+export type ErrorMetadataInput = z.input<typeof ErrorMetadataSchema>;
+export type ErrorMetadataOutput = z.output<typeof ErrorMetadataSchema>;

package/src/http-error.ts

@@ -0,0 +1,21 @@
+/**
+ * Custom HTTP error class with status code.
+ * Represents an HTTP error with both status code and message.
+ */
+export class HttpError extends Error {
+  public readonly statusCode: number;
+
+  /**
+   * Creates an instance of HttpError.
+   * @param message Error message describing the problem.
+   * @param statusCode HTTP status code, default is 500.
+   * @example
+   * // Throws an error with 404 status code
+   * throw new HttpError('Not Found', 404);
+   */
+  constructor(message: string, statusCode = 500) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = this.constructor.name;
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './base-error.js';
+export * from './config-error.js';
+export * from './error-codes.js';
+export * from './error-handler.js';
+export * from './error-metadata.js';
+export * from './http-error.js';
+export * from './validation-error.js';

package/src/validation-error.ts

@@ -0,0 +1,30 @@
+import { ERROR_CODES } from './error-codes.js';
+import { BaseError } from './base-error.js';
+
+/**
+ * Custom error class for validation failures.
+ * Used for input errors, schema violations, or data integrity issues.
+ * Automatically sets the error code to `"VALIDATION_ERROR"` to allow standard handling of validation errors.
+ */
+export class ValidationError extends BaseError {
+  /**
+   * Constructs a new ValidationError instance.
+   * @param message The human-readable error message describing what failed validation.
+   * @param cause Optional original error or value that caused the validation failure, such as a ZodError or validation detail.
+   * @param context Optional additional context data, for example the invalid field, config path, or offending input.
+   *
+   * @example
+   * throw new ValidationError('Invalid email format', zodResult.error, { field: 'email' });
+   */
+  constructor(
+    message: string,
+    cause?: unknown,
+    context?: Record<string | number | symbol, unknown>
+  ) {
+    super(message, {
+      code: ERROR_CODES.VALIDATION_ERROR,
+      cause,
+      context,
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@wnodex/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}