wnodex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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,103 @@
+# wnodex
+
+An extensible and robust Express.js server class designed for effortless customization and rapid deployment.
+
+## Table of Contents
+
+- [Features](#features)
+- [Usage](#usage)
+  - [Import and Instantiate](#import-and-instantiate)
+  - [Access the Logger](#access-the-logger)
+  - [Get Validated Config](#get-validated-config)
+  - [Access the Express App](#access-the-express-app)
+  - [Start the Server](#start-the-server)
+  - [Graceful Shutdown](#graceful-shutdown)
+- [API Reference](#api-reference)
+  - [class Wnodex](#class-wnodex)
+    - [Constructor](#constructor)
+    - [Methods](#methods)
+- [License](#license)
+
+## Features
+
+- **Express App Instantiation**: Quickly create a new Express application instance.
+- **Configuration Validation**: Validate and store configuration using Zod schemas.
+- **Middleware Setup**: Automatically applies global middlewares (helmet, cors, compression, rate-limit, etc.).
+- **Logging**: Integrated with Pino for structured logging.
+- **Error Handling**: Centralized error handler for Express.
+- **Server Startup**: Simple method to start the server and listen on a specified port.
+- **Graceful Shutdown**: Built-in support for graceful server shutdown and async cleanup chores.
+
+## Usage
+
+### Import and Instantiate
+
+```ts
+import { Wnodex } from 'wnodex';
+
+const wnodex = new Wnodex({ port: 3000 });
+```
+
+### Access the Logger
+
+```ts
+const log = wnodex.getLogger();
+log.info('Custom log message');
+```
+
+### Get Validated Config
+
+```ts
+const config = wnodex.getConfig();
+console.log(config.port); // 3000
+```
+
+### Access the Express App
+
+```ts
+const app = wnodex.getApp();
+app.get('/health', (req, res) => res.send('OK'));
+```
+
+### Start the Server
+
+```ts
+await wnodex.start();
+```
+
+### Graceful Shutdown
+
+```ts
+await wnodex.shutdown(async () => {
+  await db.close();
+  await cache.clear();
+});
+```
+
+## API Reference
+
+### class `Wnodex`
+
+#### Constructor
+
+```ts
+new Wnodex(config: WnodexConfigInput)
+```
+
+- `config`: Configuration input validated by `WnodexConfigSchema`.
+
+#### Methods
+
+- `getLogger(): Logger` — Returns the logger instance.
+- `getConfig(): WnodexConfigOutput` — Returns the validated configuration.
+- `getApp(): Application` — Returns the Express app instance.
+- `start(): Promise<void>` — Starts the server and listens on the configured port.
+- `shutdown(chores?: () => Promise<void> | void): Promise<void>` — Gracefully shuts down the server, running optional async cleanup chores.
+
+## License
+
+This project is licensed under the MIT License.
+
+Copyright (c) 2025 Davide Di Criscito
+
+For the full details, see the [LICENSE](./LICENSE) file.

package/dist/consts/cors.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULT_CORS_ORIGINS: string[];
+export declare const DEFAULT_CORS_METHODS: readonly ["GET", "POST", "PUT", "DELETE", "OPTIONS"];
+export declare const DEFAULT_CORS_ALLOWED_HEADERS: string[];
+export declare const DEFAULT_CORS_CREDENTIALS = true;
+export declare const DEFAULT_CORS_OPTIONS_SUCCESS_STATUS = 204;
+export declare const DEFAULT_CORS_ENABLED = true;
+export declare const DEFAULT_CORS_OPTIONS: {
+    enabled: boolean;
+    origin: string[];
+    methods: ("GET" | "POST" | "PUT" | "DELETE" | "OPTIONS")[];
+    allowedHeaders: string[];
+    credentials: boolean;
+    optionsSuccessStatus: number;
+};
+//# sourceMappingURL=cors.d.ts.map

package/dist/consts/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/consts/cors.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,UAAuC,CAAC;AACzE,eAAO,MAAM,oBAAoB,sDAMvB,CAAC;AACX,eAAO,MAAM,4BAA4B,UAKxC,CAAC;AACF,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,mCAAmC,MAAM,CAAC;AACvD,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,oBAAoB;;;;;;;CAOhC,CAAC"}

package/dist/consts/cors.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CORS_OPTIONS = exports.DEFAULT_CORS_ENABLED = exports.DEFAULT_CORS_OPTIONS_SUCCESS_STATUS = exports.DEFAULT_CORS_CREDENTIALS = exports.DEFAULT_CORS_ALLOWED_HEADERS = exports.DEFAULT_CORS_METHODS = exports.DEFAULT_CORS_ORIGINS = void 0;
+const port_js_1 = require("./port.js");
+exports.DEFAULT_CORS_ORIGINS = [`http://localhost:${port_js_1.DEFAULT_PORT}`];
+exports.DEFAULT_CORS_METHODS = [
+    'GET',
+    'POST',
+    'PUT',
+    'DELETE',
+    'OPTIONS',
+];
+exports.DEFAULT_CORS_ALLOWED_HEADERS = [
+    'Content-Type',
+    'Authorization',
+    'Origin',
+    'X-Requested-With',
+];
+exports.DEFAULT_CORS_CREDENTIALS = true;
+exports.DEFAULT_CORS_OPTIONS_SUCCESS_STATUS = 204;
+exports.DEFAULT_CORS_ENABLED = true;
+exports.DEFAULT_CORS_OPTIONS = {
+    enabled: exports.DEFAULT_CORS_ENABLED,
+    origin: exports.DEFAULT_CORS_ORIGINS,
+    methods: [...exports.DEFAULT_CORS_METHODS],
+    allowedHeaders: exports.DEFAULT_CORS_ALLOWED_HEADERS,
+    credentials: exports.DEFAULT_CORS_CREDENTIALS,
+    optionsSuccessStatus: exports.DEFAULT_CORS_OPTIONS_SUCCESS_STATUS,
+};

package/dist/consts/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/consts/error-codes.d.ts.map

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

package/dist/consts/error-codes.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_CODES = void 0;
+exports.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/consts/index.d.ts

@@ -0,0 +1,8 @@
+export * from './cors.js';
+export * from './error-codes.js';
+export * from './log-levels.js';
+export * from './node-env.js';
+export * from './port.js';
+export * from './rate-limit.js';
+export * from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/consts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/consts/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/consts/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./cors.js"), exports);
+tslib_1.__exportStar(require("./error-codes.js"), exports);
+tslib_1.__exportStar(require("./log-levels.js"), exports);
+tslib_1.__exportStar(require("./node-env.js"), exports);
+tslib_1.__exportStar(require("./port.js"), exports);
+tslib_1.__exportStar(require("./rate-limit.js"), exports);
+tslib_1.__exportStar(require("./session.js"), exports);

package/dist/consts/log-levels.d.ts

@@ -0,0 +1,8 @@
+export declare const LOG_LEVELS: {
+    readonly ERROR: "error";
+    readonly WARN: "warn";
+    readonly INFO: "info";
+    readonly DEBUG: "debug";
+    readonly TRACE: "trace";
+};
+//# sourceMappingURL=log-levels.d.ts.map

package/dist/consts/log-levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-levels.d.ts","sourceRoot":"","sources":["../../src/consts/log-levels.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC"}

package/dist/consts/log-levels.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_LEVELS = void 0;
+exports.LOG_LEVELS = {
+    ERROR: 'error',
+    WARN: 'warn',
+    INFO: 'info',
+    DEBUG: 'debug',
+    TRACE: 'trace',
+};

package/dist/consts/node-env.d.ts

@@ -0,0 +1,7 @@
+export declare const NODE_ENV_VALUES: {
+    readonly DEVELOPMENT: "development";
+    readonly PRODUCTION: "production";
+    readonly TEST: "test";
+    readonly STAGING: "staging";
+};
+//# sourceMappingURL=node-env.d.ts.map

package/dist/consts/node-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-env.d.ts","sourceRoot":"","sources":["../../src/consts/node-env.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;CAKlB,CAAC"}

package/dist/consts/node-env.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_ENV_VALUES = void 0;
+exports.NODE_ENV_VALUES = {
+    DEVELOPMENT: 'development',
+    PRODUCTION: 'production',
+    TEST: 'test',
+    STAGING: 'staging',
+};

package/dist/consts/port.d.ts

@@ -0,0 +1,6 @@
+export declare const RESERVED_PORTS: Record<number, string>;
+export declare const DEFAULT_PORT = 4000;
+export declare const MIN_PORT = 1024;
+export declare const MAX_PORT = 65535;
+export declare const ALLOWED_PORTS: Set<number>;
+//# sourceMappingURL=port.d.ts.map

package/dist/consts/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/consts/port.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBjD,CAAC;AACF,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,QAAQ,QAAS,CAAC;AAC/B,eAAO,MAAM,aAAa,aAAsC,CAAC"}

package/dist/consts/port.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_PORTS = exports.MAX_PORT = exports.MIN_PORT = exports.DEFAULT_PORT = exports.RESERVED_PORTS = void 0;
+exports.RESERVED_PORTS = {
+    // Databases
+    3306: 'MySQL',
+    5432: 'PostgreSQL',
+    6379: 'Redis',
+    27_017: 'MongoDB',
+    27_018: 'MongoDB shard/replica',
+    9200: 'Elasticsearch',
+    5601: 'Kibana',
+    // Dev tools
+    5173: 'Vite default port',
+    8888: 'Jupyter Notebook',
+    // AI / ML servers
+    6006: 'TensorBoard',
+    5000: 'MLflow (also common for Flask)',
+    8265: 'Ray Dashboard',
+    8787: 'Dask Dashboard',
+    11_434: 'Ollama API',
+};
+exports.DEFAULT_PORT = 4000;
+exports.MIN_PORT = 1024;
+exports.MAX_PORT = 65_535;
+exports.ALLOWED_PORTS = new Set([exports.DEFAULT_PORT, 8000, 8080]);

package/dist/consts/rate-limit.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_RATE_LIMIT_WINDOW_MS: number;
+export declare const DEFAULT_RATE_LIMIT_MAX = 100;
+export declare const DEFAULT_RATE_LIMIT_MESSAGE = "Too many requests, please try again later.";
+export declare const DEFAULT_RATE_LIMIT_OPTIONS: {
+    windowMs: number;
+    max: number;
+    message: string;
+};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/consts/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/consts/rate-limit.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAC3D,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,0BAA0B,+CACO,CAAC;AAC/C,eAAO,MAAM,0BAA0B;;;;CAItC,CAAC"}

package/dist/consts/rate-limit.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RATE_LIMIT_OPTIONS = exports.DEFAULT_RATE_LIMIT_MESSAGE = exports.DEFAULT_RATE_LIMIT_MAX = exports.DEFAULT_RATE_LIMIT_WINDOW_MS = void 0;
+exports.DEFAULT_RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+exports.DEFAULT_RATE_LIMIT_MAX = 100;
+exports.DEFAULT_RATE_LIMIT_MESSAGE = 'Too many requests, please try again later.';
+exports.DEFAULT_RATE_LIMIT_OPTIONS = {
+    windowMs: exports.DEFAULT_RATE_LIMIT_WINDOW_MS,
+    max: exports.DEFAULT_RATE_LIMIT_MAX,
+    message: exports.DEFAULT_RATE_LIMIT_MESSAGE,
+};

package/dist/consts/session.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_SESSION_COOKIE_MAX_AGE: number;
+export declare const DEFAULT_SESSION_COOKIE_SECURE: boolean;
+export declare const DEFAULT_SESSION_COOKIE_HTTP_ONLY = true;
+export declare const DEFAULT_SESSION_RESAVE = false;
+export declare const DEFAULT_SESSION_SAVE_UNINITIALIZED = false;
+//# sourceMappingURL=session.d.ts.map

package/dist/consts/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/consts/session.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,8BAA8B,QAAsB,CAAC;AAClE,eAAO,MAAM,6BAA6B,SACH,CAAC;AACxC,eAAO,MAAM,gCAAgC,OAAO,CAAC;AACrD,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAC5C,eAAO,MAAM,kCAAkC,QAAQ,CAAC"}

package/dist/consts/session.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SESSION_SAVE_UNINITIALIZED = exports.DEFAULT_SESSION_RESAVE = exports.DEFAULT_SESSION_COOKIE_HTTP_ONLY = exports.DEFAULT_SESSION_COOKIE_SECURE = exports.DEFAULT_SESSION_COOKIE_MAX_AGE = void 0;
+exports.DEFAULT_SESSION_COOKIE_MAX_AGE = 1000 * 60 * 60 * 24; // 1 day
+exports.DEFAULT_SESSION_COOKIE_SECURE = process.env.NODE_ENV === 'production';
+exports.DEFAULT_SESSION_COOKIE_HTTP_ONLY = true;
+exports.DEFAULT_SESSION_RESAVE = false;
+exports.DEFAULT_SESSION_SAVE_UNINITIALIZED = false;

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

@@ -0,0 +1,57 @@
+import type { ErrorMetadataInput } from '../schemas/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/errors/base-error.d.ts.map

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

package/dist/errors/base-error.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseError = void 0;
+const error_metadata_js_1 = require("../schemas/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.
+ */
+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 = error_metadata_js_1.ErrorMetadataSchema.safeParse(input);
+        if (!result.success) {
+            const errorMessage = `Invalid metadata provided for error "${parentErrorMessage}" (Code: ${input.code || 'N/A'}).`;
+            throw new Error(errorMessage, { cause: result.error });
+        }
+        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,
+        };
+    }
+}
+exports.BaseError = BaseError;

package/dist/errors/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/errors/config-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-error.d.ts","sourceRoot":"","sources":["../../src/errors/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/errors/config-error.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+const error_codes_js_1 = require("../consts/error-codes.js");
+const base_error_js_1 = require("./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.
+ */
+class ConfigError extends base_error_js_1.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_js_1.ERROR_CODES.CONFIG_ERROR,
+            cause,
+            context,
+        });
+    }
+}
+exports.ConfigError = ConfigError;

package/dist/errors/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/errors/http-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-error.d.ts","sourceRoot":"","sources":["../../src/errors/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/errors/http-error.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
+/**
+ * Custom HTTP error class with status code.
+ * Represents an HTTP error with both status code and message.
+ */
+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;
+    }
+}
+exports.HttpError = HttpError;

package/dist/errors/index.d.ts

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

package/dist/errors/index.d.ts.map

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

package/dist/errors/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./base-error.js"), exports);
+tslib_1.__exportStar(require("./config-error.js"), exports);
+tslib_1.__exportStar(require("./http-error.js"), exports);
+tslib_1.__exportStar(require("./validation-error.js"), exports);