wnodex 0.1.0 → 0.2.1

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');
+  });
+});

package/tests/index.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import supertest from 'supertest';
+
+import { Wnodex } from '../src/index.js';
+
+describe('Wnodex', () => {
+  let wnodex: Wnodex;
+
+  beforeEach(() => {
+    // To see the logs, uncomment the following line
+    // vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('should create a new Wnodex instance', () => {
+    wnodex = new Wnodex({ port: 3000 });
+    expect(wnodex).toBeInstanceOf(Wnodex);
+  });
+
+  it('should get the express app instance', () => {
+    wnodex = new Wnodex({ port: 3000 });
+    const app = wnodex.getApp();
+    expect(app).toBeDefined();
+  });
+
+  it('should get the config', () => {
+    const config = { port: 3001 };
+    wnodex = new Wnodex(config);
+    const wnodexConfig = wnodex.getConfig();
+    expect(wnodexConfig.port).toBe(3001);
+  });
+
+  it('should get the logger', () => {
+    wnodex = new Wnodex({ port: 3000 });
+    const logger = wnodex.getLogger();
+    expect(logger).toBeDefined();
+  });
+
+  it('should start and shutdown the server', async () => {
+    wnodex = new Wnodex({ port: 3002 });
+    const logger = wnodex.getLogger();
+    const infoSpy = vi.spyOn(logger, 'info');
+
+    await wnodex.start();
+    expect(infoSpy).toHaveBeenCalledWith(
+      'Server running @ http://localhost:3002'
+    );
+
+    await wnodex.shutdown();
+    expect(infoSpy).toHaveBeenCalledWith('Shutdown initiated...');
+    expect(infoSpy).toHaveBeenCalledWith('Server stopped gracefully.');
+  });
+
+  it('should respond to a basic request', async () => {
+    wnodex = new Wnodex({ port: 3003 });
+    const app = wnodex.getApp();
+
+    app.get('/test', (req, res) => {
+      res.status(200).send('OK');
+    });
+
+    await wnodex.start();
+
+    const response = await supertest(app).get('/test');
+    expect(response.status).toBe(200);
+    expect(response.text).toBe('OK');
+    await wnodex.shutdown();
+  });
+
+  it('should not throw when shutdown is called on a non-running server', async () => {
+    wnodex = new Wnodex({ port: 3000 });
+    const logger = wnodex.getLogger();
+    const warnSpy = vi.spyOn(logger, 'warn');
+
+    await wnodex.shutdown();
+
+    expect(warnSpy).toHaveBeenCalledWith('Server not running.');
+  });
+
+  it('should call cleanup chores on shutdown', async () => {
+    wnodex = new Wnodex({ port: 3004 });
+    const chores = vi.fn().mockImplementation(() => Promise.resolve());
+
+    await wnodex.start();
+    await wnodex.shutdown(chores);
+
+    expect(chores).toHaveBeenCalled();
+  });
+
+  it('should handle errors during cleanup chores', async () => {
+    wnodex = new Wnodex({ port: 3005 });
+    const logger = wnodex.getLogger();
+    const errorSpy = vi.spyOn(logger, 'error');
+    const chores = vi.fn().mockRejectedValue(new Error('Cleanup failed'));
+
+    await wnodex.start();
+    await wnodex.shutdown(chores);
+
+    expect(chores).toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.any(Error),
+      'Error during cleanup chores'
+    );
+  });
+});