Design of a Decade Server

A modern, type-safe Node.js server framework with built-in WebSocket support, routing, static file handling, and middleware capabilities. Built with TypeScript for Node.js 24+.

Upgrading from an older major? See MIGRATION.md for a consolidated 6.x -> 10.x checklist, or CHANGELOG.md for the full history.

Features

• ✅ Full TypeScript support with comprehensive type definitions
• ✅ ESM (ES Modules) compatible
• ✅ Secure error handling with automatic sensitive data protection
• ✅ WebSocket server with message formatting and event handling
• ✅ Flexible routing system with URL pattern matching
• ✅ Static file serving with MIME type detection
• ✅ Built-in middleware support (request logging, etc.)
• ✅ Application state management
• ✅ Event system with pub/sub pattern
• ✅ HTML sanitization utilities
• ✅ Comprehensive test coverage with Vitest
• ✅ Modern async/await API

📦 Installation

npm install @designofadecade/server

Or using other package managers:

# Yarn
yarn add @designofadecade/server

# pnpm
pnpm add @designofadecade/server

# Bun
bun add @designofadecade/server

Requirements

• Node.js >= 24.0.0
• ES Modules support (package uses "type": "module")
• TypeScript >= 5.0 (if using TypeScript)

Quick Start

import { Server } from '@designofadecade/server';

// Create a new server instance
const server = new Server({
  port: 3000,
  hostname: 'localhost',
});

// Start the server
await server.start();
console.log('Server running on http://localhost:3000');

Architecture Overview

The server is composed of several modular components:

Server Core

• Server: Main HTTP/HTTPS server with WebSocket upgrade support
• Router: URL pattern-based routing with request handlers
• Routes: Route collection and management

WebSocket Support

• WebSocketServer: WebSocket connection management
• WebSocketMessageFormatter: Message serialization/deserialization

Middleware & Utilities

• RequestLogger: HTTP request logging middleware
• StaticFileHandler: Static file serving with caching
• HtmlSanitizer: XSS protection for HTML content
• HtmlRenderer: Server-side HTML rendering

State & Events

• AppState: Application-wide state management
• Events: Event emitter with type-safe event handling
• EventsManager: Event subscription and lifecycle management

Storage

• Local: Local file system utilities

Integrations

• Slack: Slack notifications integration
• ApiClient: HTTP client for external APIs

Usage Examples

Basic Routing

import { Router } from '@designofadecade/server';

const router = new Router();

// Add routes
router.addRoute({
  pattern: '/api/users/:id',
  method: 'GET',
  handler: async (req, res, params) => {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ userId: params.id }));
  },
});

// Handle requests
await router.route(request, response);

WebSocket Communication

import { WebSocketServer } from '@designofadecade/server';

const wsServer = new WebSocketServer({ port: 8080 });

wsServer.on('connection', (ws) => {
  console.log('Client connected');

  ws.on('message', (data) => {
    console.log('Received:', data);
    ws.send('Echo: ' + data);
  });
});

Static File Serving

import { StaticFileHandler } from '@designofadecade/server';

const staticHandler = new StaticFileHandler({
  rootDir: './public',
  cacheControl: 'public, max-age=3600',
});

await staticHandler.serve(request, response, '/assets/style.css');

Event System

import { Events, EventsManager } from '@designofadecade/server';

const events = new Events();
const manager = new EventsManager(events);

// Subscribe to events
manager.on('user:login', (data) => {
  console.log('User logged in:', data);
});

// Emit events
events.emit('user:login', { userId: 123, timestamp: Date.now() });

Documentation

Comprehensive documentation is available in the /docs directory:

• Logger Documentation - CloudWatch Logger with AWS Lambda integration, sensitive data redaction, and performance tracking
• API Documentation - OpenAPI/Swagger documentation generation guide
• New Features - Performance benchmarks, pre-commit hooks, and recent additions
• Changelog - Version history and release notes
• Contributing Guide - How to contribute to the project

Development

Install Dependencies

npm install

Run Tests

npm test                 # Run tests once
npm run test:watch      # Run tests in watch mode
npm run test:ui         # Open Vitest UI
npm run test:coverage   # Generate coverage report

Build

npm run build           # Build once
npm run build:watch     # Build in watch mode

Linting & Formatting

npm run lint            # Run ESLint
npm run format          # Format code with Prettier
npm run typecheck       # Type-check without emitting

Project Structure

src/
├── client/             # API client utilities
├── context/            # Request context handling
├── docs/               # OpenAPI/Swagger documentation generators
├── events/             # Event system with pub/sub pattern
├── local/              # Local storage utilities
├── logger/             # Logging utilities with CloudWatch support
├── middleware/         # Request middleware (logging, etc.)
├── notifications/      # Notification integrations (Slack, etc.)
├── router/             # Routing system with URL pattern matching
├── sanitizer/          # HTML sanitization for XSS protection
├── server/             # Core HTTP/HTTPS server implementation
├── state/              # Application state management
├── types/              # TypeScript type definitions
├── utils/              # Utilities and helpers
└── websocket/          # WebSocket server implementation

API Reference

Full API documentation is available in the docs directory:

• Server - Core server setup and configuration
• Router - Routing and request handling
• WebSocket - WebSocket server and messaging
• Logger - CloudWatch logging and performance tracking
• Events Manager - Event system usage
• API Documentation - OpenAPI/Swagger setup
• State & Context - State management
• Utilities - Helper functions and utilities

Security

This package includes built-in security features:

• HTML Sanitization - XSS protection for user-generated content
• Type Safety - Full TypeScript support for compile-time safety
• Input Validation - URL pattern matching and parameter validation

If you discover a security vulnerability, please send an email to info@designofadecade.com instead of using the issue tracker.

Versioning

This project follows Semantic Versioning. For available versions, see the tags on this repository or the npm registry.

See CHANGELOG.md for a history of changes.

Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on:

• Code of Conduct
• Development workflow
• Pull request process
• Coding standards
• Testing requirements

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Design of a Decade
Email: info@designofadecade.com
Website: designofadecade.com

Links

• GitHub Repository
• npm Package
• Issue Tracker
• Changelog

Acknowledgments

Built with:

• TypeScript - Type-safe JavaScript
• Vitest - Unit testing framework
• ws - WebSocket implementation

---

Made with ❤️ by Design of a Decade