wnodex 0.1.0 → 0.2.2

package/package.json

@@ -1,18 +1,31 @@
 {
   "name": "wnodex",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "private": false,
-  "homepage": "https://github.com/dcdavidev/wnodex#readme",
+  "description": "An extensible and robust Express.js server framework designed for effortless customization and rapid deployment with sensible defaults.",
+  "keywords": [
+    "wnodex",
+    "express",
+    "framework",
+    "typescript",
+    "nodejs",
+    "server",
+    "http",
+    "web",
+    "security",
+    "middleware"
+  ],
+  "homepage": "https://github.com/wnodex/wnodex#readme",
   "bugs": {
-    "url": "https://github.com/dcdavidev/wnodex/issues"
+    "url": "https://github.com/wnodex/wnodex/issues"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/dcdavidev/wnodex.git",
+    "url": "git+https://github.com/wnodex/wnodex.git",
     "directory": "packages/wnodex"
   },
   "license": "MIT",
-  "author": "Davide Di Criscito",
+  "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -25,30 +38,53 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "compression": "^1.8.1",
+    "@types/body-parser": "^1.19.6",
+    "body-parser": "^2.2.2",
     "cookie-parser": "^1.4.7",
-    "cors": "^2.8.5",
-    "express": "^5.1.0",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
     "express-rate-limit": "^8.2.1",
-    "express-session": "^1.18.2",
+    "express-session": "^1.19.0",
     "helmet": "^8.1.0",
     "hpp": "^0.2.3",
     "passport": "^0.7.0",
-    "pino": "^10.1.0",
-    "pino-pretty": "^13.1.2",
-    "tslib": "^2.3.0",
-    "zod": "^4.1.12"
+    "pino": "^10.3.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.3.6",
+    "@wnodex/body-parser": "0.2.2",
+    "@wnodex/cookie-parser": "0.2.2",
+    "@wnodex/cors": "0.2.2",
+    "@wnodex/errors": "0.2.2",
+    "@wnodex/hpp": "0.2.2",
+    "@wnodex/compression": "0.2.2",
+    "@wnodex/passport": "0.2.2",
+    "@wnodex/logger": "0.2.2",
+    "@wnodex/helmet": "0.2.2",
+    "@wnodex/session": "0.2.2",
+    "@wnodex/rate-limit": "0.2.2"
   },
   "devDependencies": {
     "@types/compression": "^1.8.1",
     "@types/cookie-parser": "^1.4.10",
     "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.5",
+    "@types/express": "^5.0.6",
     "@types/express-session": "^1.18.2",
     "@types/hpp": "^0.2.7",
-    "@types/passport": "^1.0.17"
+    "@types/node": "^25.0.10",
+    "@types/passport": "^1.0.17",
+    "@types/supertest": "^6.0.3",
+    "rolldown": "1.0.0-rc.1",
+    "supertest": "^7.2.2",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.18",
+    "@wnodex/typescript-config": "0.2.2"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rolldown -c && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

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/config.ts

@@ -0,0 +1,27 @@
+import z from 'zod';
+import { BodyParserOptionsSchema } from '@wnodex/body-parser';
+import { CompressionOptionsSchema } from '@wnodex/compression';
+import { CookieParserOptionsSchema } from '@wnodex/cookie-parser';
+import { CorsOptionsSchema } from '@wnodex/cors';
+import { HelmetOptionsSchema } from '@wnodex/helmet';
+import { HppOptionsSchema } from '@wnodex/hpp';
+import { PassportOptionsSchema } from '@wnodex/passport';
+import { RateLimitOptionsSchema } from '@wnodex/rate-limit';
+import { SessionOptionsSchema } from '@wnodex/session';
+
+export const WnodexConfigSchema = z.object({
+  port: z.union([z.number(), z.string()]).optional().default(3000),
+  bodyParsers: BodyParserOptionsSchema,
+  helmet: HelmetOptionsSchema,
+  cors: CorsOptionsSchema,
+  compression: CompressionOptionsSchema,
+  rateLimit: RateLimitOptionsSchema,
+  cookieParser: CookieParserOptionsSchema,
+  hpp: HppOptionsSchema,
+  session: SessionOptionsSchema,
+  passport: PassportOptionsSchema,
+});
+
+export type WnodexConfig = z.infer<typeof WnodexConfigSchema>;
+export type WnodexConfigInput = z.input<typeof WnodexConfigSchema>;
+export type WnodexConfigOutput = z.output<typeof WnodexConfigSchema>;

package/src/index.ts

@@ -1,38 +1,149 @@
-export * from './consts/cors.js';
-export * from './consts/error-codes.js';
-export * from './consts/log-levels.js';
-export * from './consts/node-env.js';
-export * from './consts/port.js';
-export * from './consts/rate-limit.js';
-export * from './consts/session.js';
-export * from './errors/base-error.js';
-export * from './errors/config-error.js';
-export * from './errors/http-error.js';
-export * from './errors/validation-error.js';
-export * from './helpers/get-node-env.js';
-export * from './helpers/is-development.js';
-export * from './helpers/setup-config.js';
-export * from './helpers/setup-middlewares.js';
-export * from './logger.js';
-export * from './middlewares/compression.js';
-export * from './middlewares/cookie-parser.ts.js';
-export * from './middlewares/cors.js';
-export * from './middlewares/error-handler.js';
-export * from './middlewares/helmet.js';
-export * from './middlewares/hpp.js';
-export * from './middlewares/passport.js';
-export * from './middlewares/rate-limit.js';
-export * from './middlewares/session.js';
-export * from './schemas/compression.js';
-export * from './schemas/cookie-parser.js';
-export * from './schemas/cors.js';
-export * from './schemas/error-metadata.js';
-export * from './schemas/helmet.js';
-export * from './schemas/hpp.js';
-export * from './schemas/node-env.js';
-export * from './schemas/passport.js';
-export * from './schemas/port.js';
-export * from './schemas/rate-limit.js';
-export * from './schemas/session.js';
-export * from './schemas/wnodex-config.js';
-export * from './wnodex.js';
+import { Server } from 'node:http';
+
+import express, { type Application } from 'express';
+
+import type { Logger } from 'pino';
+import { logger } from '@wnodex/logger';
+
+import { type WnodexConfigInput, type WnodexConfigOutput } from './config.js';
+import { setupConfig } from './setup-config.js';
+import { setupMiddlewares } from './setup-middlewares.js';
+
+/**
+ * Main application class for the Wnodex server.
+ *
+ * Handles Express app instantiation, configuration validation,
+ * middleware setup, logging, error handling, server startup, and graceful shutdown.
+ */
+export class Wnodex {
+  private readonly app: Application;
+  private readonly config: WnodexConfigOutput;
+  private readonly logger: Logger;
+  private server?: Server;
+
+  /**
+   * Constructs a new Wnodex server instance.
+   * Initializes the Express app, logger, validates and stores configuration, and applies middlewares.
+   * @param config Configuration input for Wnodex, validated by WnodexConfigSchema.
+   * @example
+   * const wnodex = new Wnodex({ port: 3000 });
+   */
+  constructor(config: WnodexConfigInput) {
+    this.app = express();
+
+    // Logger
+    this.logger = logger;
+    this.app.set('logger', logger);
+
+    // Config
+    this.config = setupConfig(config);
+
+    // Global Middlewares
+    setupMiddlewares(this.app, this.config);
+  }
+
+  /**
+   * Provides access to the application's logger instance.
+   * @returns Logger instance.
+   * @example
+   * const log = wnodex.getLogger();
+   */
+  public getLogger(): Logger {
+    return this.logger;
+  }
+
+  /**
+   * Returns the validated Wnodex configuration.
+   * @returns WnodexConfigOutput object.
+   * @example
+   * const config = wnodex.getConfig();
+   */
+  public getConfig(): WnodexConfigOutput {
+    return this.config;
+  }
+
+  /**
+   * Public getter for the express app instance.
+   * @returns The express application instance.
+   * @example
+   * const app = Wnodex.getApp();
+   */
+  public getApp(): Application {
+    return this.app;
+  }
+
+  // --- Wnodex Start Helper ---
+
+  /**
+   * Starts the Wnodex server and listens on the specified port.
+   * Resolves when the server is ready.
+   * @returns Promise that resolves once server is running.
+   * @example
+   * await wnodex.start();
+   */
+  public start(): Promise<void> {
+    const logger = this.getLogger();
+    const { port } = this.getConfig();
+
+    return new Promise((resolve) => {
+      this.server = this.app.listen(port, () => {
+        logger.info(`Server running @ http://localhost:${port}`);
+        resolve();
+      });
+
+      // Attach error handler immediately after server creation
+      this.server?.on('error', (err) => {
+        logger.error(err, 'Server error:');
+      });
+    });
+  }
+
+  // --- Wnodex Graceful Shutdown ---
+
+  /**
+   * Gracefully shuts down the Wnodex server.
+   * Stops accepting new connections, allows active connections to finish,
+   * runs optional asynchronous cleanup chores, and closes the server.
+   * @param chores An optional async callback function to perform cleanup tasks
+   * before shutdown (e.g., closing DB connections, clearing cache). This function is awaited before closing the server.
+   *
+   * @returns Promise that resolves when the server has stopped gracefully.
+   *
+   * @example
+   * await wnodex.shutdown(async () => {
+   *   await db.close();
+   *   await cache.clear();
+   * });
+   */
+  public async shutdown(chores?: () => Promise<void> | void): Promise<void> {
+    const logger = this.getLogger();
+
+    if (!this.server) {
+      logger.warn('Server not running.');
+      return;
+    }
+
+    logger.info('Shutdown initiated...');
+
+    if (chores) {
+      try {
+        await chores();
+      } catch (error) {
+        logger.error(error, 'Error during cleanup chores');
+        // Proceed with shutdown even if chores fail
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      this.server!.close((err) => {
+        if (err) {
+          logger.error(err, 'Error during server shutdown');
+          reject(err);
+          return;
+        }
+        logger.info('Server stopped gracefully.');
+        resolve();
+      });
+    });
+  }
+}

package/src/setup-config.ts

@@ -0,0 +1,17 @@
+import { ConfigError } from '@wnodex/errors';
+
+import {
+  WnodexConfigInput,
+  WnodexConfigOutput,
+  WnodexConfigSchema,
+} from './config.js';
+
+export const setupConfig = (config: WnodexConfigInput): WnodexConfigOutput => {
+  const result = WnodexConfigSchema.safeParse(config);
+
+  if (!result.success) {
+    throw new ConfigError('Invalid wnodex configuration', result.error);
+  }
+
+  return result.data;
+};

package/src/setup-middlewares.ts

@@ -0,0 +1,49 @@
+import { Application } from 'express';
+
+import { configureBodyParsers } from '@wnodex/body-parser';
+import { configureCompression } from '@wnodex/compression';
+import { configureCookieParser } from '@wnodex/cookie-parser';
+import { configureCors } from '@wnodex/cors';
+import { errorHandler } from '@wnodex/errors';
+import { configureHelmet } from '@wnodex/helmet';
+import { configureHpp } from '@wnodex/hpp';
+import { configurePassport } from '@wnodex/passport';
+import { configureRateLimit } from '@wnodex/rate-limit';
+import { configureSession } from '@wnodex/session';
+
+import { WnodexConfigOutput } from './config.js';
+
+export const setupMiddlewares = (
+  app: Application,
+  config: WnodexConfigOutput
+): void => {
+  // Helmet
+  configureHelmet(app, config.helmet);
+
+  // CORS
+  configureCors(app, config.cors);
+
+  // Body Parsers
+  configureBodyParsers(app, config.bodyParsers);
+
+  // cookie-parser
+  configureCookieParser(app, config.cookieParser);
+
+  // compression
+  configureCompression(app, config.compression);
+
+  // express-rate-limit
+  configureRateLimit(app, config.rateLimit);
+
+  // hpp
+  configureHpp(app, config.hpp);
+
+  // express-session - Session management
+  configureSession(app, config.session);
+
+  // passport - Authentication middleware
+  configurePassport(app, config.passport);
+
+  // Error Handler (keep it last)
+  app.use(errorHandler);
+};

package/tests/body-parser.schema.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseBodyParserOptions } from '../../body-parser/src/parse-options';
+
+describe('BodyParserOptionsSchema', () => {
+  it('should return default when input is undefined', () => {
+    const options = parseBodyParserOptions();
+    expect(options).toBe(true);
+  });
+
+  it('should return true when input is true', () => {
+    const options = parseBodyParserOptions(true);
+    expect(options).toBe(true);
+  });
+
+  it('should return false when input is false', () => {
+    const options = parseBodyParserOptions(false);
+    expect(options).toBe(false);
+  });
+
+  it('should return an empty object when input is an empty object', () => {
+    const options = parseBodyParserOptions({});
+    expect(options).toEqual({});
+  });
+
+  it('should return the json options when provided', () => {
+    const jsonOptions = { limit: '10mb' };
+    const options = parseBodyParserOptions({ json: jsonOptions });
+    expect(options).toEqual({ json: jsonOptions });
+  });
+
+  it('should return the urlencoded options when provided', () => {
+    const urlencodedOptions = { extended: false };
+    const options = parseBodyParserOptions({ urlencoded: urlencodedOptions });
+    expect(options).toEqual({ urlencoded: urlencodedOptions });
+  });
+
+  it('should return both json and urlencoded options when provided', () => {
+    const jsonOptions = { limit: '10mb' };
+    const urlencodedOptions = { extended: false };
+    const options = parseBodyParserOptions({
+      json: jsonOptions,
+      urlencoded: urlencodedOptions,
+    });
+    expect(options).toEqual({
+      json: jsonOptions,
+      urlencoded: urlencodedOptions,
+    });
+  });
+
+  it('should throw an error for invalid input', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseBodyParserOptions(123)).toThrow(
+      'Invalid body-parser options'
+    );
+  });
+});

package/tests/compression.schema.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseCompressionOptions } from '../../compression/src/parse-options';
+
+describe('CompressionOptionsSchema', () => {
+  it('should return default when input is undefined', () => {
+    const options = parseCompressionOptions();
+    expect(options).toBe(true);
+  });
+
+  it('should return true when input is true', () => {
+    const options = parseCompressionOptions(true);
+    expect(options).toBe(true);
+  });
+
+  it('should return false when input is false', () => {
+    const options = parseCompressionOptions(false);
+    expect(options).toBe(false);
+  });
+
+  it('should throw an error for invalid input', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseCompressionOptions(123)).toThrow(
+      'Invalid compression options'
+    );
+  });
+});

package/tests/cookie-parser.schema.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseCookieParserOptions } from '../../cookie-parser/src/parse-options';
+
+describe('CookieParserOptionsSchema', () => {
+  it('should return default when input is undefined', () => {
+    const options = parseCookieParserOptions();
+    expect(options).toBe(false);
+  });
+
+  it('should return true when input is true', () => {
+    const options = parseCookieParserOptions(true);
+    expect(options).toBe(true);
+  });
+
+  it('should return false when input is false', () => {
+    const options = parseCookieParserOptions(false);
+    expect(options).toBe(false);
+  });
+
+  it('should return the secret when a string is provided', () => {
+    const secret = 'my-secret';
+    const options = parseCookieParserOptions({ secret });
+    expect(options).toEqual({ secret });
+  });
+
+  it('should return the secret when an array is provided', () => {
+    const secret = ['my-secret-1', 'my-secret-2'];
+    const options = parseCookieParserOptions({ secret });
+    expect(options).toEqual({ secret });
+  });
+
+  it('should return the secret and options when provided', () => {
+    const secret = 'my-secret';
+    const cookieOptions = { maxAge: 1000 };
+    const options = parseCookieParserOptions({
+      secret,
+      options: cookieOptions,
+    });
+    expect(options).toEqual({ secret, options: cookieOptions });
+  });
+
+  it('should throw an error for invalid input', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseCookieParserOptions(123)).toThrow(
+      'Invalid cookie-parser options'
+    );
+  });
+
+  it('should throw an error for an empty object', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseCookieParserOptions({})).toThrow(
+      'Invalid cookie-parser options'
+    );
+  });
+});

package/tests/cors.schema.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_CORS_OPTIONS } from '../../cors/src/defaults';
+import { parseCorsOptions } from '../../cors/src/parse-options';
+
+describe('CorsOptionsSchema', () => {
+  it('should return default when input is undefined', () => {
+    const options = parseCorsOptions();
+    expect(options).toEqual(DEFAULT_CORS_OPTIONS);
+  });
+
+  it('should return true when input is true', () => {
+    const options = parseCorsOptions(true);
+    expect(options).toBe(true);
+  });
+
+  it('should return false when input is false', () => {
+    const options = parseCorsOptions(false);
+    expect(options).toBe(false);
+  });
+
+  it('should return the custom options when provided', () => {
+    const customOptions = {
+      origin: 'https://example.com',
+      methods: ['GET', 'POST'],
+    };
+    const options = parseCorsOptions(customOptions);
+    expect(options).toEqual(customOptions);
+  });
+
+  it('should throw an error for invalid input', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseCorsOptions(123)).toThrow('Invalid CORS options');
+  });
+});

package/tests/helmet.schema.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseHelmetOptions } from '../../helmet/src/parse-options';
+
+describe('HelmetOptionsSchema', () => {
+  it('should return default when input is undefined', () => {
+    const options = parseHelmetOptions();
+    expect(options).toBe(false);
+  });
+
+  it('should return true when input is true', () => {
+    const options = parseHelmetOptions(true);
+    expect(options).toBe(true);
+  });
+
+  it('should return false when input is false', () => {
+    const options = parseHelmetOptions(false);
+    expect(options).toBe(false);
+  });
+
+  it('should return the custom options when provided', () => {
+    const customOptions = {
+      contentSecurityPolicy: false,
+    };
+    const options = parseHelmetOptions(customOptions);
+    expect(options).toEqual(customOptions);
+  });
+
+  it('should throw an error for invalid input', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseHelmetOptions(123)).toThrow('Invalid Helmet options');
+  });
+});

package/tests/hpp.schema.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseHppOptions } from '../../hpp/src/parse-options';
+
+describe('HppOptionsSchema', () => {
+  it('should return default when input is undefined', () => {
+    const options = parseHppOptions();
+    expect(options).toBe(true);
+  });
+
+  it('should return true when input is true', () => {
+    const options = parseHppOptions(true);
+    expect(options).toBe(true);
+  });
+
+  it('should return false when input is false', () => {
+    const options = parseHppOptions(false);
+    expect(options).toBe(false);
+  });
+
+  it('should return the whitelist array when provided', () => {
+    const whitelist = ['param1', 'param2'];
+    const options = parseHppOptions(whitelist);
+    expect(options).toEqual(whitelist);
+  });
+
+  it('should throw an error for invalid input', () => {
+    // @ts-expect-error - Testing invalid input
+    expect(() => parseHppOptions(123)).toThrow('Invalid Hpp options');
+  });
+});