wnodex 0.1.0 → 0.2.1

package/src/errors/base-error.ts

@@ -1,111 +0,0 @@
-import type {
-  ErrorMetadataInput,
-  ErrorMetadataOutput,
-} from '../schemas/error-metadata.js';
-import { ErrorMetadataSchema } 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 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 override 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'}).`;
-
-      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(): 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/errors/config-error.ts

@@ -1,31 +0,0 @@
-import { ERROR_CODES } from '../consts/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/errors/http-error.ts

@@ -1,21 +0,0 @@
-/**
- * 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/errors/index.ts

@@ -1,4 +0,0 @@
-export * from './base-error.js';
-export * from './config-error.js';
-export * from './http-error.js';
-export * from './validation-error.js';

package/src/errors/validation-error.ts

@@ -1,30 +0,0 @@
-import { ERROR_CODES } from '../consts/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/src/helpers/get-node-env.ts

@@ -1,27 +0,0 @@
-import { NODE_ENV_VALUES } from '../consts/node-env.js';
-import { ValidationError } from '../errors/validation-error.js';
-import { type NodeEnv, NodeEnvSchema } from '../schemas/node-env.js';
-
-/**
- * Parses the `NODE_ENV` environment variable from `process.env`.
- * @returns {NodeEnv} The validated environment value.
- * @throws {ValidationError} Thrown if `NODE_ENV` is invalid or not defined according to schema.
- *
- * @example
- * // Example usage:
- * const env = getNodeEnv();
- * // env will be one of 'production', 'development', etc.
- */
-export function getNodeEnv(): NodeEnv {
-  const rawNodeEnv = process.env.NODE_ENV;
-  const result = NodeEnvSchema.safeParse(rawNodeEnv);
-
-  if (!result.success) {
-    throw new ValidationError('Invalid Node Env', result.error, {
-      provided: rawNodeEnv,
-      expected: Object.values(NODE_ENV_VALUES).join('|'),
-    });
-  }
-
-  return result.data;
-}

package/src/helpers/index.ts

@@ -1,4 +0,0 @@
-export * from './get-node-env.js';
-export * from './is-development.js';
-export * from './setup-config.js';
-export * from './setup-middlewares.js';

package/src/helpers/is-development.ts

@@ -1,15 +0,0 @@
-import { NODE_ENV_VALUES } from '../consts/node-env.js';
-import { getNodeEnv } from './get-node-env.js';
-
-/**
- * Returns true if process.env.NODE_ENV is set to 'development'.
- * @returns {boolean} Returns `true` if the current Node environment is development, otherwise `false`.
- *
- * @example
- * const dev = isDevelopment();
- */
-export function isDevelopment(): boolean {
-  const nodeEnv = getNodeEnv();
-
-  return nodeEnv === NODE_ENV_VALUES.DEVELOPMENT;
-}

package/src/helpers/setup-config.ts

@@ -1,25 +0,0 @@
-import { ConfigError } from '../errors/config-error.js';
-import {
-  WnodexConfigInput,
-  WnodexConfigOutput,
-  WnodexConfigSchema,
-} from '../schemas';
-
-/**
- * Validates the provided config using NodexConfigSchema.
- * Throws ValidationError if validation fails.
- * @param config Raw configuration input for Nodex.
- * @returns Validated configuration.
- * @throws {ConfigError} If configuration is invalid.
- * @example
- * const config = setupConfig(rawConfig);
- */
-export function setupConfig(config: WnodexConfigInput): WnodexConfigOutput {
-  const result = WnodexConfigSchema.safeParse(config);
-
-  if (!result.success) {
-    throw new ConfigError('Invalid Nodex Configuration', result.error);
-  }
-
-  return result.data;
-}

package/src/helpers/setup-middlewares.ts

@@ -1,56 +0,0 @@
-import express, { type Application } from 'express';
-
-import { configureCompression } from '../middlewares/compression.js';
-import { configureCookieParser } from '../middlewares/cookie-parser.ts.js';
-import { configureCors } from '../middlewares/cors.js';
-import { errorHandler } from '../middlewares/error-handler.js';
-import { configureHelmet } from '../middlewares/helmet.js';
-import { configureHpp } from '../middlewares/hpp.js';
-import { configurePassport } from '../middlewares/passport.js';
-import { configureRateLimit } from '../middlewares/rate-limit.js';
-import { configureSession } from '../middlewares/session.js';
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Sets up Express middlewares for the application.
- * Currently applies the helmet security middleware.
- * @param app The express application instance.
- * @param config The Nodex parsed config object.
- * @example
- * this.config = setupMiddlewares();
- */
-export function setupMiddlewares(
-  app: Application,
-  config: WnodexConfigOutput
-): void {
-  // Helmet
-  configureHelmet(app, config);
-
-  // CORS
-  configureCors(app, config);
-
-  // Body Parsers
-  app.use(express.json());
-  app.use(express.urlencoded({ extended: true }));
-
-  // cookie-parser
-  configureCookieParser(app, config);
-
-  // compression
-  configureCompression(app, config);
-
-  // express-rate-limit
-  configureRateLimit(app, config);
-
-  // hpp
-  configureHpp(app, config);
-
-  // express-session - Session management
-  configureSession(app, config);
-
-  // passport - Authentication middleware
-  configurePassport(app, config);
-
-  // Error Handler (keep it last)
-  app.use(errorHandler);
-}

package/src/logger.ts

@@ -1,22 +0,0 @@
-import pretty from 'pino-pretty';
-
-import pino from 'pino';
-
-import { LOG_LEVELS } from './consts/log-levels.js';
-import { isDevelopment } from './helpers/is-development.js';
-
-const prettyStream = pretty({
-  colorize: true,
-  levelFirst: true,
-  translateTime: true,
-  ignore: 'pid,hostname',
-  singleLine: true,
-});
-
-const baseOptions = {
-  level: LOG_LEVELS.INFO,
-};
-
-export const logger = isDevelopment()
-  ? pino(baseOptions, prettyStream)
-  : pino(baseOptions);

package/src/middlewares/compression.ts

@@ -1,32 +0,0 @@
-import type { Application } from 'express';
-
-import compression from 'compression';
-
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures compression middleware to compress HTTP responses,
- * improving network performance by reducing response size.
- * Reads a flag from the app configuration to enable or disable compression.
- * @param app Express Application instance to apply compression middleware on.
- * @param config Typed Nodex configuration object containing compression option.
- *
- * @returns The result of app.use(compression()) if enabled, otherwise undefined.
- *
- * @example
- * private setupMiddlewares() {
- *    configureCors(this.app, this.config);
- * }
- */
-export function configureCompression(
-  app: Application,
-  config: WnodexConfigOutput
-) {
-  const { compression: isCompressionEnabled } = config;
-
-  if (!isCompressionEnabled) {
-    return;
-  }
-
-  return app.use(compression());
-}

package/src/middlewares/cookie-parser.ts.ts

@@ -1,37 +0,0 @@
-import type { Application } from 'express';
-
-import cookieParser from 'cookie-parser';
-
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures the cookie-parser middleware for the Express app based on the provided configuration.
- * @param app The Express application instance to configure.
- * @param config The application configuration object, which includes cookieParser options.
- * @returns Void.
- *
- * @example
- * ```
- * import express from 'express';
- * import { configureCookieParser } from './middlewares/cookie-parser';
- * import config from './config';
- *
- * const app = express();
- * configureCookieParser(app, config);
- * ```
- */
-export function configureCookieParser(
-  app: Application,
-  config: WnodexConfigOutput
-) {
-  const { cookieParser: options } = config;
-
-  if (typeof options === 'boolean') {
-    if (!options) return;
-    return app.use(cookieParser());
-  } else {
-    const { secret, options: opts } = options;
-
-    return app.use(cookieParser(secret, opts));
-  }
-}

package/src/middlewares/cors.ts

@@ -1,35 +0,0 @@
-import type { Application } from 'express';
-
-import cors from 'cors';
-
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures the CORS middleware for an Express application.
- * Reads the `cors` option from the provided config.
- * If the option is a boolean:
- * - `false` disables CORS middleware.
- * - `true` enables CORS middleware with default settings.
- * If the option is an object, it is spread into the CORS middleware options.
- * @param app The Express Application instance to attach middleware to.
- * @param config Typed configuration input that includes the CORS option.
- *
- * @returns The Express Application instance with CORS middleware applied,
- * or undefined if CORS is disabled.
- *
- * @example
- * private setupMiddlewares() {
- *    configureCors(this.app, this.config);
- * }
- */
-export function configureCors(app: Application, config: WnodexConfigOutput) {
-  const { cors: options } = config;
-
-  if (typeof options === 'boolean') {
-    if (options === false || !options) return;
-
-    return app.use(cors());
-  } else {
-    return app.use(cors({ ...options }));
-  }
-}

package/src/middlewares/error-handler.ts

@@ -1,54 +0,0 @@
-import type { NextFunction, Request, Response } from 'express';
-
-import type { HttpError } from '../errors/http-error.js';
-import { isDevelopment } from '../helpers/is-development.js';
-
-/**
- * Middleware for centralized error handling.
- * Catches all errors thrown in the application and responds with a structured JSON.
- * Logs the error for debugging purposes.
- * @param err The thrown error object or value.
- * @param _req The current Express request object.
- * @param res The current Express response object.
- * @param _next Next middleware function in chain.
- *
- * @example
- * private setupMiddlewares() {
- *   // other middlewares
- *   // ...
- *   // Configure errorHandler as the last one middleware.
- *   app.use(errorHandler);
- * }
- */
-export function errorHandler(
-  err: HttpError | Error,
-  _req: Request,
-  res: Response,
-  _next: NextFunction
-): void {
-  // 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
-      ...(isDevelopment() && {
-        stack: err.stack,
-      }),
-    },
-  });
-}

package/src/middlewares/helmet.ts

@@ -1,29 +0,0 @@
-import type { Application } from 'express';
-
-import helmet from 'helmet';
-
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures the Helmet middleware in an Express app.
- * @param app The Express Application instance on which to apply Helmet.
- * @param config Typed project configuration from which the Helmet option is read.
- *
- * @returns The Express Application instance (`app`) if Helmet is enable.
- *
- * @example
- * private setupMiddlewares() {
- *    configureHelmet(this.app, this.config);
- * }
- */
-export function configureHelmet(app: Application, config: WnodexConfigOutput) {
-  const { helmet: options } = config;
-
-  if (typeof options === 'boolean') {
-    if (options === false || !options) return;
-
-    return app.use(helmet());
-  } else {
-    return app.use(helmet({ ...options }));
-  }
-}

package/src/middlewares/hpp.ts

@@ -1,31 +0,0 @@
-import type { Application } from 'express';
-
-import hpp from 'hpp';
-
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures the hpp middleware protection against HTTP Parameter Pollution.
- *
- * Applies the hpp middleware to the Express application instance based on the
- * provided configuration. If configuration is a boolean and true, applies with default.
- * If configuration is an array, uses it as a whitelist of allowed duplicate parameters.
- * @param app The Express application instance.
- * @param config The normalized middleware configuration, specifying hpp options.
- * @returns Void.
- *
- * @example
- * configureHpp(app, { hpp: true });
- * configureHpp(app, { hpp: ['param1', 'param2'] });
- */
-export function configureHpp(app: Application, config: WnodexConfigOutput) {
-  const { hpp: options } = config;
-
-  if (typeof options === 'boolean') {
-    if (options === false || !options) return;
-
-    return app.use(hpp());
-  } else {
-    return app.use(hpp({ whitelist: [...options] }));
-  }
-}

package/src/middlewares/index.ts

@@ -1,9 +0,0 @@
-export * from './compression.js';
-export * from './cookie-parser.ts.js';
-export * from './cors.js';
-export * from './error-handler.js';
-export * from './helmet.js';
-export * from './hpp.js';
-export * from './passport.js';
-export * from './rate-limit.js';
-export * from './session.js';

package/src/middlewares/passport.ts

@@ -1,30 +0,0 @@
-import type { Application } from 'express';
-
-import type { WnodexConfigInput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures the passport instance.
- * @param app The express application instance.
- * @param config The Wnodex raw config.
- * @returns The passport instance.
- * @example
- * construction(config: WnodexConfigInput) {
- *   this.app = express();
- *   this.config = configureConfig(config);
- *   this.passport = configurePassport(this.app, this.config)
- * }
- */
-export function configurePassport(app: Application, config: WnodexConfigInput) {
-  const { passport } = config;
-
-  /**
-   * If config.passport is either undefined, true (invalid config), or false, passport won't be instantiated.
-   */
-  if (!passport || typeof passport === 'boolean') return;
-
-  app.set('passport', passport);
-  app.use(passport.initialize());
-  app.use(passport.session());
-
-  return passport;
-}

package/src/middlewares/rate-limit.ts

@@ -1,39 +0,0 @@
-import type { Application } from 'express';
-
-import rateLimit from 'express-rate-limit';
-
-import type { WnodexConfigOutput } from '../schemas/wnodex-config.js';
-
-/**
- * Configures the rate limiting middleware to protect the application
- * from excessive requests, mitigating abuse and denial of service attacks.
- *
- * It reads the `rateLimit` option from the provided config.
- * If it's a boolean:
- * - `false` disables rate limiting.
- * - `true` enables rate limiting with default settings.
- * If it's an object, it spreads the properties into the rateLimit options.
- * @param app Express Application instance to apply the rate limiter to.
- * @param config Typed application configuration object containing rateLimit option.
- *
- * @returns The result of `app.use(rateLimit())` if rate limiting is enabled, otherwise `undefined`.
- *
- * @example
- * private setupMiddlewares() {
- *    configureHelmet(this.app, this.config);
- * }
- */
-export function configureRateLimit(
-  app: Application,
-  config: WnodexConfigOutput
-) {
-  const { rateLimit: options } = config;
-
-  if (typeof options === 'boolean') {
-    if (options === false || !options) return;
-
-    return app.use(rateLimit());
-  } else {
-    return app.use(rateLimit({ ...options }));
-  }
-}