@igxjs/node-components 1.0.9 → 1.0.10

package/docs/flex-router.md

@@ -1,167 +0,0 @@
-# FlexRouter
-
-A flexible routing utility for Express.js that allows mounting routers with custom context paths and middleware handlers.
-
-## Overview
-
-FlexRouter provides a convenient way to organize and mount Express routers with predefined context paths and optional middleware. This is particularly useful for:
-- API versioning (e.g., `/api/v1`, `/api/v2`)
-- Separating public and protected routes
-- Applying middleware to specific route groups
-- Managing complex routing hierarchies
-
-## Usage Example
-
-```javascript
-import { Router } from 'express';
-import { FlexRouter } from '@igxjs/node-components';
-// Assuming you have an authenticate middleware
-// import { authenticate } from './middlewares/auth.js';
-
-// Create routers
-const publicRouter = Router();
-const privateRouter = Router();
-
-publicRouter.get('/health', (req, res) => {
-  res.send('OK');
-});
-
-privateRouter.get('/users', (req, res) => {
-  res.json({ users: [] });
-});
-
-// Define flex routers with context paths and optional middleware
-export const routers = [
-  new FlexRouter('/api/v1/public', publicRouter),
-  new FlexRouter('/api/v1/protected', privateRouter, [authenticate]), // with middleware
-];
-
-// Mount all routers to your Express app
-const app = express();
-const basePath = '';
-
-routers.forEach(router => {
-  router.mount(app, basePath);
-});
-
-// Routes will be available at:
-// - /api/v1/public/health
-// - /api/v1/protected/users (with authenticate middleware)
-```
-
-## Advanced Usage
-
-### Multiple Middleware
-
-You can apply multiple middleware functions to a FlexRouter:
-
-```javascript
-import { rateLimiter } from './middlewares/rate-limiter.js';
-import { logger } from './middlewares/logger.js';
-import { authenticate } from './middlewares/auth.js';
-
-const apiRouter = Router();
-
-apiRouter.get('/data', (req, res) => {
-  res.json({  [] });
-});
-
-// Apply multiple middleware in order
-const protectedApi = new FlexRouter(
-  '/api/v1',
-  apiRouter,
-  [logger, rateLimiter, authenticate] // Applied in this order
-);
-
-protectedApi.mount(app, '');
-```
-
-### Using Base Paths
-
-You can add a base path when mounting routers, useful for multi-tenant applications:
-
-```javascript
-const tenantRouter = Router();
-
-tenantRouter.get('/dashboard', (req, res) => {
-  res.json({ tenant: req.params.tenantId });
-});
-
-const flexRouter = new FlexRouter('/api', tenantRouter);
-
-// Mount with tenant-specific base path
-flexRouter.mount(app, '/tenant/:tenantId');
-
-// Route will be available at: /tenant/:tenantId/api/dashboard
-```
-
-### Organizing Routes by Feature
-
-```javascript
-// features/users/routes.js
-const usersRouter = Router();
-usersRouter.get('/', getAllUsers);
-usersRouter.post('/', createUser);
-export const usersFlexRouter = new FlexRouter('/users', usersRouter);
-
-// features/products/routes.js
-const productsRouter = Router();
-productsRouter.get('/', getAllProducts);
-export const productsFlexRouter = new FlexRouter('/products', productsRouter);
-
-// app.js
-import { usersFlexRouter } from './features/users/routes.js';
-import { productsFlexRouter } from './features/products/routes.js';
-
-const apiRouters = [usersFlexRouter, productsFlexRouter];
-
-apiRouters.forEach(router => router.mount(app, '/api/v1'));
-
-// Routes available:
-// - /api/v1/users
-// - /api/v1/products
-```
-
-## API
-
-### Constructor
-
-**`new FlexRouter(context, router, handlers?)`**
-
-Creates a new FlexRouter instance.
-
-**Parameters:**
-- `context` (string) - The context path for the router (e.g., `/api/v1`)
-- `router` (Router) - Express Router instance containing your route definitions
-- `handlers` (Array, optional) - Array of middleware handler functions to apply to all routes in this router
-
-**Returns:** FlexRouter instance
-
-### Methods
-
-**`mount(app, basePath)`**
-
-Mounts the router to an Express application with the specified base path.
-
-**Parameters:**
-- `app` (Express) - Express application instance
-- `basePath` (string) - Base path to prepend to the context path
-
-**Example:**
-```javascript
-const flexRouter = new FlexRouter('/api', router);
-flexRouter.mount(app, '/v1'); // Mounts at /v1/api
-```
-
-## Best Practices
-
-1. **Group Related Routes**: Use FlexRouter to group related routes together
-2. **Apply Middleware Strategically**: Apply middleware at the FlexRouter level for route groups that share the same requirements
-3. **Consistent Naming**: Use consistent naming conventions for context paths (e.g., all lowercase, kebab-case)
-4. **Version Your APIs**: Use FlexRouter to manage different API versions easily
-5. **Keep Routers Focused**: Each router should handle a specific feature or resource type
-
-## Related Documentation
-
-- [SessionManager](./session-manager.md) - For authentication middleware usage
-- [Back to main documentation](../README.md)

package/docs/http-handlers.md

@@ -1,302 +0,0 @@
-# HTTP Handlers
-
-Custom error handling utilities with standardized HTTP status codes and error responses for Express.js applications.
-
-## Overview
-
-The HTTP Handlers module provides:
-- Standardized error handling middleware
-- Custom error classes
-- HTTP status codes and messages constants
-- 404 handler for unmatched routes
-- Utility functions for error formatting
-- Axios error handling helpers
-
-## Available Exports
-
-```javascript
-import { 
-  httpCodes,           // HTTP status code constants
-  httpMessages,        // HTTP status message constants
-  httpErrorHandler,    // Error handling middleware
-  httpNotFoundHandler, // 404 handler middleware
-  CustomError,         // Custom error class
-  httpHelper,          // Utility functions
-  httpError            // Error factory function
-} from '@igxjs/node-components';
-```
-
-## Quick Start
-
-```javascript
-import express from 'express';
-import {
-  httpCodes,
-  httpErrorHandler,
-  httpNotFoundHandler,
-  httpError
-} from '@igxjs/node-components';
-
-const app = express();
-
-// Your routes
-app.get('/api/data', async (req, res, next) => {
-  try {
-    const data = await fetchData();
-    res.json(data);
-  } catch (error) {
-    next(httpError(httpCodes.SYSTEM_FAILURE, 'Failed to fetch data', error));
-  }
-});
-
-// Add 404 handler before error handler
-app.use(httpNotFoundHandler);
-
-// Add error handler as the last middleware
-app.use(httpErrorHandler);
-
-app.listen(3000);
-```
-
-## HTTP Status Codes
-
-The `httpCodes` object provides constants for common HTTP status codes:
-
-```javascript
-import { httpCodes } from '@igxjs/node-components';
-
-// Success codes
-httpCodes.OK                  // 200
-httpCodes.CREATED             // 201
-httpCodes.NO_CONTENT          // 204
-
-// Client error codes
-httpCodes.BAD_REQUEST         // 400
-httpCodes.UNAUTHORIZED        // 401
-httpCodes.FORBIDDEN           // 403
-httpCodes.NOT_FOUND           // 404
-httpCodes.NOT_ACCEPTABLE      // 406
-httpCodes.CONFLICT            // 409
-httpCodes.LOCKED              // 423
-
-// Server error codes
-httpCodes.SYSTEM_FAILURE      // 500
-httpCodes.NOT_IMPLEMENTED     // 501
-```
-
-## HTTP Status Messages
-
-Corresponding status messages are available via `httpMessages`:
-
-```javascript
-import { httpMessages } from '@igxjs/node-components';
-
-httpMessages.OK               // 'OK'
-httpMessages.BAD_REQUEST      // 'Bad Request'
-httpMessages.UNAUTHORIZED     // 'Unauthorized'
-// ... etc.
-```
-
-## CustomError Class
-
-Create custom errors with specific HTTP status codes:
-
-```javascript
-import { CustomError, httpCodes } from '@igxjs/node-components';
-
-// Constructor: new CustomError(code, message, error?, data?)
-throw new CustomError(
-  httpCodes.BAD_REQUEST,
-  'Email is required',
-  null,
-  { field: 'email' }
-);
-```
-
-**Properties:**
-- `code` (number) - HTTP status code
-- `message` (string) - Error message
-- `error` (object, optional) - Original error object
-- `data` (object, optional) - Additional error data
-
-## httpError Function
-
-Convenience function to create CustomError instances:
-
-```javascript
-import { httpError, httpCodes } from '@igxjs/node-components';
-
-// Same as: new CustomError(code, message, error, data)
-throw httpError(
-  httpCodes.UNAUTHORIZED,
-  'Invalid credentials',
-  originalError,
-  { attempted: username }
-);
-```
-
-## Middleware
-
-### httpErrorHandler
-
-Express error handling middleware that processes CustomError and other errors:
-
-```javascript
-import { httpErrorHandler } from '@igxjs/node-components';
-
-// Add as the last middleware
-app.use(httpErrorHandler);
-```
-
-**Features:**
-- Automatically handles `CustomError` instances
-- Sets appropriate HTTP status codes
-- Adds CORS headers
-- Logs error details to console
-- Returns standardized JSON error responses
-
-**Response Format:**
-```json
-{
-  "error": {
-    "code": 400,
-    "message": "Email is required",
-    "data": { "field": "email" }
-  }
-}
-```
-
-### httpNotFoundHandler
-
-Middleware that catches all unmatched routes and returns 404:
-
-```javascript
-import { httpNotFoundHandler } from '@igxjs/node-components';
-
-// Add before error handler
-app.use(httpNotFoundHandler);
-app.use(httpErrorHandler);
-```
-
-## httpHelper Utilities
-
-### `handleAxiosError(error, defaultMessage?)`
-
-Analyze and convert Axios/HTTP errors to CustomError:
-
-```javascript
-import axios from 'axios';
-import { httpHelper } from '@igxjs/node-components';
-
-try {
-  const response = await axios.get('https://api.example.com/data');
-  return response.data;
-} catch (error) {
-  // Converts Axios error to CustomError with extracted status and message
-  throw httpHelper.handleAxiosError(error, 'API request failed');
-}
-```
-
-### `format(str, ...args)`
-
-Format strings with placeholders:
-
-```javascript
-import { httpHelper } from '@igxjs/node-components';
-
-const message = httpHelper.format(
-  'User {0} not found in {1}',
-  'john@example.com',
-  'database'
-);
-// Result: 'User john@example.com not found in database'
-```
-
-### `toZodMessage(error)`
-
-Generate friendly Zod validation error messages:
-
-```javascript
-import { z } from 'zod';
-import { httpHelper, httpError, httpCodes } from '@igxjs/node-components';
-
-const userSchema = z.object({
-  email: z.string().email(),
-  age: z.number().min(18)
-});
-
-app.post('/api/users', (req, res, next) => {
-  try {
-    const validated = userSchema.parse(req.body);
-    // Process validated data
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      const message = httpHelper.toZodMessage(error);
-      throw httpError(httpCodes.BAD_REQUEST, message, error);
-    }
-    next(error);
-  }
-});
-```
-
-## Complete Example
-
-```javascript
-import express from 'express';
-import {
-  httpCodes,
-  httpMessages,
-  httpError,
-  httpErrorHandler,
-  httpNotFoundHandler,
-  CustomError
-} from '@igxjs/node-components';
-
-const app = express();
-app.use(express.json());
-
-// Routes
-app.get('/api/health', (req, res) => {
-  res.json({ status: httpMessages.OK });
-});
-
-app.post('/api/login', async (req, res, next) => {
-  try {
-    const { username, password } = req.body;
-    
-    if (!username || !password) {
-      throw httpError(
-        httpCodes.BAD_REQUEST,
-        'Username and password are required'
-      );
-    }
-    
-    const user = await authenticate(username, password);
-    
-    if (!user) {
-      throw new CustomError(
-        httpCodes.UNAUTHORIZED,
-        'Invalid credentials'
-      );
-    }
-    
-    res.json({ user });
-  } catch (error) {
-    next(error);
-  }
-});
-
-// 404 handler
-app.use(httpNotFoundHandler);
-
-// Error handler (must be last)
-app.use(httpErrorHandler);
-
-app.listen(3000);
-```
-
-## Related Documentation
-
-- [JWT Manager](./jwt-manager.md) - For token-based authentication
-- [SessionManager](./session-manager.md) - For session-based authentication
-- [Back to main documentation](../README.md)

package/docs/jwt-manager.md

@@ -1,124 +0,0 @@
-# JWT Manager
-
-Provides JWT (JSON Web Token) encryption and decryption utilities using the `jose` library with JWE (JSON Web Encryption) for secure token management.
-
-## Overview
-
-JwtManager provides secure token-based authentication using:
-- JWE (JSON Web Encryption) for encrypted tokens
-- Configurable expiration times
-- Standard JWT claims (issuer, audience, subject)
-- Clock tolerance for time synchronization issues
-- Easy integration with Express.js applications
-
-## Configuration Options
-
-```javascript
-// Example configuration object
-const jwtOptions = {
-  algorithm: 'dir',              // JWE algorithm (default: 'dir')
-  encryption: 'A256GCM',         // JWE encryption method (default: 'A256GCM')
-  expirationTime: '10m',         // Token expiration (default: '10m')
-  clockTolerance: 30,            // Clock tolerance in seconds (default: 30)
-  secretHashAlgorithm: 'SHA-256', // Hash algorithm for secret derivation (default: 'SHA-256')
-  issuer: 'your-app',            // Optional JWT issuer claim
-  audience: 'your-users',        // Optional JWT audience claim
-  subject: 'user-session'        // Optional JWT subject claim
-};
-```
-
-## Basic Usage
-
-```javascript
-import { JwtManager } from '@igxjs/node-components';
-
-// Create instance with default configuration
-const jwtManager = new JwtManager({
-  expirationTime: '1h',
-  issuer: 'my-app',
-  audience: 'my-users'
-});
-
-// Encrypt user data
-const userData = {
-  userId: '12345',
-  email: 'user@example.com',
-  roles: ['admin', 'user']
-};
-
-const secret = 'your-secret-key';
-const token = await jwtManager.encrypt(userData, secret);
-
-console.log('Encrypted Token:', token);
-
-// Decrypt token
-try {
-  const result = await jwtManager.decrypt(token, secret);
-  console.log('Decrypted Payload:', result.payload);
-  console.log('Protected Header:', result.protectedHeader);
-} catch (error) {
-  console.error('Token validation failed:', error);
-}
-```
-
-## API Reference
-
-### Constructor
-
-**`new JwtManager(options?)`**
-
-Create a new JwtManager instance. All options are optional with sensible defaults.
-
-**Parameters:**
-- `options` (JwtManagerOptions, optional) - Configuration options
-
-### Methods
-
-#### `encrypt(data, input, options?)`
-
-Generate an encrypted JWT token.
-
-**Parameters:**
-- `data` (JWTPayload) - User data payload to encrypt
-- `input` (string) - Secret key or password for encryption
-- `options` (JwtEncryptOptions, optional) - Per-call configuration overrides
-
-**Returns:** `Promise<string>` - Encrypted JWT token
-
-#### `decrypt(token, input, options?)`
-
-Decrypt and validate a JWT token.
-
-**Parameters:**
-- `token` (string) - JWT token to decrypt
-- `input` (string) - Secret key or password for decryption
-- `options` (JwtDecryptOptions, optional) - Per-call configuration overrides
-
-**Returns:** `Promise<JWTDecryptResult>` - Object containing `payload` and `protectedHeader`
-
-## Configuration Details
-
-### Algorithms
-- `'dir'` (default) - Direct encryption with shared symmetric key
-- `'A128KW'`, `'A192KW'`, `'A256KW'` - AES Key Wrap algorithms
-
-### Encryption Methods
-- `'A256GCM'` (default) - AES-GCM with 256-bit key
-- `'A128GCM'`, `'A192GCM'` - AES-GCM with 128/192-bit keys
-
-### Expiration Time Format
-- `'10m'` - 10 minutes
-- `'1h'` - 1 hour
-- `'7d'` - 7 days
-- `'30s'` - 30 seconds
-
-### JWT Claims
-- `issuer` (iss) - Token issuer identification
-- `audience` (aud) - Intended token recipient
-- `subject` (sub) - Token subject (usually user ID)
-
-## Related Documentation
-
-- [SessionManager](./session-manager.md) - For SSO-based session management
-- [HTTP Handlers](./http-handlers.md) - For error handling in authentication flows
-- [Back to main documentation](../README.md)