@designofadecade/server 4.0.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [4.0.0] - 2026-02-28
+
+### Changed
+- Updated package to publish to npm.js registry instead of GitHub Packages
+- Improved package.json with enhanced keywords and metadata
+- Enhanced README.md with comprehensive badges, installation instructions, and documentation links
+- Optimized build configuration to exclude test and benchmark files from distribution
+- Updated GitHub Actions workflow for npm publishing with provenance
+- Improved .gitignore with additional patterns
+
+### Added
+- .npmignore file to ensure only necessary files are published
+- Security section in README
+- API Reference section in README with links to all documentation
+- Support and Links sections in README
+- Additional badges for npm version, TypeScript, and build status
+
+### Removed
+- .npmrc file (no longer needed for public npm registry)
+- Test and benchmark files from compiled output
+
+## [3.0.0] - 2026-02-27
+
+### Added
+- Core HTTP/HTTPS server implementation
+- WebSocket server with message formatting
+- Flexible routing system with URL pattern matching
+- Static file serving with MIME type detection
+- Middleware support (request logging)
+- Application state management
+- Event system with pub/sub pattern
+- HTML sanitization utilities
+- Slack notifications integration
+- Comprehensive test suite with Vitest
+- TypeScript definitions and ESM support
+- Performance benchmarks using Vitest bench for Router, AppState, EventsManager, and HtmlSanitizer
+- OpenAPI/Swagger documentation generator with TypeScript support
+- Pre-commit hooks using Husky and lint-staged for code quality (Prettier, ESLint, tests)
+- Swagger UI HTML generation for interactive API documentation
+- Benchmark npm scripts (`bench` and `bench:watch`)
+- API client utility (ApiClient)
+- Context object for request handling
+- Route error handling (RouteError)
+- HTML rendering utilities
+
+## [1.0.0] - 2026-02-26
+
+### Added
+- Initial package setup
+- GitHub Actions workflows for testing and publishing
+- ESLint and Prettier configuration
+- MIT License
+- README and contributing guidelines

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Design of a Decade
+
+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,297 @@
+# Design of a Decade Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@designofadecade/server.svg)](https://www.npmjs.com/package/@designofadecade/server)
+[![Node.js Version](https://img.shields.io/badge/node->=24.0.0-brightgreen.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+[![Build Status](https://github.com/designofadecade/server/workflows/Test/badge.svg)](https://github.com/designofadecade/server/actions)
+
+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+.
+
+## Features
+
+- ✅ Full TypeScript support with comprehensive type definitions
+- ✅ ESM (ES Modules) compatible
+- ✅ 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
+
+```bash
+npm install @designofadecade/server
+```
+
+Or using other package managers:
+
+```bash
+# 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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](docs/logger.md)** - CloudWatch Logger with AWS Lambda integration, sensitive data redaction, and performance tracking
+- **[API Documentation](docs/api-documentation.md)** - OpenAPI/Swagger documentation generation guide
+- **[New Features](FEATURES.md)** - Performance benchmarks, pre-commit hooks, and recent additions
+- **[Changelog](CHANGELOG.md)** - Version history and release notes
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
+
+## Development
+
+### Install Dependencies
+```bash
+npm install
+```
+
+### Run Tests
+```bash
+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
+```bash
+npm run build           # Build once
+npm run build:watch     # Build in watch mode
+```
+
+### Linting & Formatting
+```bash
+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](docs/) directory:
+
+- **[Server](docs/server.md)** - Core server setup and configuration
+- **[Router](docs/router.md)** - Routing and request handling
+- **[WebSocket](docs/websocket.md)** - WebSocket server and messaging
+- **[Logger](docs/logger.md)** - CloudWatch logging and performance tracking
+- **[Events Manager](docs/events-manager.md)** - Event system usage
+- **[API Documentation](docs/api-documentation.md)** - OpenAPI/Swagger setup
+- **[State & Context](docs/context-state.md)** - State management
+- **[Utilities](docs/utilities.md)** - 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](https://semver.org/). For available versions, see the [tags on this repository](https://github.com/designofadecade/server/tags) or the [npm registry](https://www.npmjs.com/package/@designofadecade/server).
+
+See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
+
+## Support
+
+- **Documentation**: [GitHub Repository](https://github.com/designofadecade/server)
+- **Issues**: [GitHub Issues](https://github.com/designofadecade/server/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/designofadecade/server/discussions)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](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](LICENSE) file for details.
+
+## Author
+
+**Design of a Decade**  
+Email: info@designofadecade.com  
+Website: [designofadecade.com](https://designofadecade.com)
+
+## Links
+
+- [GitHub Repository](https://github.com/designofadecade/server)
+- [npm Package](https://www.npmjs.com/package/@designofadecade/server)
+- [Issue Tracker](https://github.com/designofadecade/server/issues)
+- [Changelog](CHANGELOG.md)
+
+## Acknowledgments
+
+Built with:
+- [TypeScript](https://www.typescriptlang.org/) - Type-safe JavaScript
+- [Vitest](https://vitest.dev/) - Unit testing framework
+- [ws](https://github.com/websockets/ws) - WebSocket implementation
+
+---
+
+Made with ❤️ by Design of a Decade

package/dist/client/ApiClient.d.ts

@@ -0,0 +1,121 @@
+/**
+ * API Client for making HTTP requests
+ * @class ApiClient
+ * @example
+ * const client = new ApiClient('https://api.example.com');
+ * client.setAuthToken('your-token');
+ * const result = await client.get('/users', { page: 1, limit: 10 });
+ */
+interface ApiClientOptions {
+    timeout?: number;
+    retryAttempts?: number;
+    retryDelay?: number;
+}
+interface RequestOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface ApiResponse {
+    ok: boolean;
+    status: number | null;
+    statusText: string;
+    data: any;
+    error: string | null;
+    headers: Record<string, string>;
+}
+type RequestInterceptor = (config: RequestInit & {
+    signal: AbortSignal;
+}) => Promise<RequestInit & {
+    signal: AbortSignal;
+}> | RequestInit & {
+    signal: AbortSignal;
+};
+type ResponseInterceptor = (response: ApiResponse) => Promise<ApiResponse> | ApiResponse;
+export default class ApiClient {
+    #private;
+    /**
+     * Create an API Client
+     * @param {string} baseUrl - Base URL for all requests
+     * @param {Object} options - Configuration options
+     * @param {number} options.timeout - Request timeout in milliseconds (default: 30000)
+     * @param {number} options.retryAttempts - Number of retry attempts for failed requests (default: 0)
+     * @param {number} options.retryDelay - Delay between retries in milliseconds (default: 1000)
+     */
+    constructor(baseUrl: string, options?: ApiClientOptions);
+    /**
+     * Set authentication token
+     * @param {string} token - Authentication token
+     * @param {string} type - Token type (default: 'Bearer')
+     */
+    setAuthToken(token: string, type?: string): void;
+    /**
+     * Clear authentication token
+     */
+    clearAuthToken(): void;
+    /**
+     * Set default headers for all requests
+     * @param {Object} headers - Headers object
+     */
+    setDefaultHeaders(headers: Record<string, string>): void;
+    /**
+     * Add a request interceptor
+     * @param {Function} interceptor - Function that receives and modifies request config
+     */
+    addRequestInterceptor(interceptor: RequestInterceptor): void;
+    /**
+     * Add a response interceptor
+     * @param {Function} interceptor - Function that receives and modifies response
+     */
+    addResponseInterceptor(interceptor: ResponseInterceptor): void;
+    /**
+     * Make GET request
+     * @param {string} url - Request URL
+     * @param {Object} params - Query parameters (optional)
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    get(url: string, params?: Record<string, any> | null, options?: RequestOptions): Promise<ApiResponse>;
+    /**
+     * Make POST request
+     * @param {string} url - Request URL
+     * @param {Object|FormData} data - Request body
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    post(url: string, data: any, options?: RequestOptions): Promise<ApiResponse>;
+    /**
+     * Make PUT request
+     * @param {string} url - Request URL
+     * @param {Object|FormData} data - Request body
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    put(url: string, data: any, options?: RequestOptions): Promise<ApiResponse>;
+    /**
+     * Make DELETE request
+     * @param {string} url - Request URL
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    delete(url: string, options?: RequestOptions): Promise<ApiResponse>;
+    /**
+     * Make PATCH request
+     * @param {string} url - Request URL
+     * @param {Object} data - Request body
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    patch(url: string, data: any, options?: RequestOptions): Promise<ApiResponse>;
+}
+export {};
+//# sourceMappingURL=ApiClient.d.ts.map

package/dist/client/ApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../../src/client/ApiClient.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,UAAU,gBAAgB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,cAAc;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,UAAU,WAAW;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,KAAK,kBAAkB,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC,WAAW,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC,GAAG,WAAW,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AACpK,KAAK,mBAAmB,GAAG,CAAC,QAAQ,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC;AAEzF,MAAM,CAAC,OAAO,OAAO,SAAS;;IAY1B;;;;;;;OAOG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAO3D;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAiB,GAAG,IAAI;IAK1D;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIxD;;;OAGG;IACH,qBAAqB,CAAC,WAAW,EAAE,kBAAkB,GAAG,IAAI;IAI5D;;;OAGG;IACH,sBAAsB,CAAC,WAAW,EAAE,mBAAmB,GAAG,IAAI;IAwI9D;;;;;;;;OAQG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IASrH;;;;;;;;OAQG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAiBtF;;;;;;;;OAQG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAiBrF;;;;;;;OAOG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAU7E;;;;;;;;OAQG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;CAS1F"}