@igxjs/node-components 1.0.9 → 1.0.11

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)

package/docs/redis-manager.md

@@ -1,210 +0,0 @@
-# RedisManager
-
-Redis connection management with TLS support and automatic reconnection handling.
-
-## Overview
-
-RedisManager provides a robust Redis client with:
-- TLS/SSL support for secure connections
-- Automatic reconnection handling
-- Connection status monitoring
-- Clean disconnection management
-
-**Note:** RedisManager is used internally by the [SessionManager](./session-manager.md), so you typically don't need to use it directly unless you need custom Redis operations.
-
-## Usage Example
-
-```javascript
-import { RedisManager } from '@igxjs/node-components';
-
-const redisManager = new RedisManager();
-
-// Connect to Redis (with optional TLS certificate)
-const connected = await redisManager.connect(
-  'rediss://localhost:6379',
-  '/path/to/cert.pem'
-);
-
-if (connected) {
-  // Get Redis client for direct operations
-  const client = redisManager.getClient();
-  await client.set('key', 'value');
-  const value = await client.get('key');
-  console.log(value); // 'value'
-  
-  // Check connection status
-  const isConnected = await redisManager.isConnected();
-  console.log('Connected:', isConnected);
-  
-  // Disconnect when done
-  await redisManager.disConnect();
-}
-```
-
-## Connection URLs
-
-RedisManager supports two URL formats:
-
-### Standard Redis (non-TLS)
-```javascript
-await redisManager.connect('redis://localhost:6379');
-await redisManager.connect('redis://username:password@host:6379');
-```
-
-### Secure Redis (TLS)
-```javascript
-// Requires certificate path for TLS
-await redisManager.connect(
-  'rediss://localhost:6379',
-  '/path/to/certificate.pem'
-);
-```
-
-## Advanced Usage
-
-### Custom Operations
-
-```javascript
-import { RedisManager } from '@igxjs/node-components';
-
-const redisManager = new RedisManager();
-await redisManager.connect(process.env.REDIS_URL);
-
-const client = redisManager.getClient();
-
-// String operations
-await client.set('user:1', JSON.stringify({ name: 'John' }));
-const user = JSON.parse(await client.get('user:1'));
-
-// Hash operations
-await client.hSet('user:2', 'name', 'Jane');
-await client.hSet('user:2', 'email', 'jane@example.com');
-const userData = await client.hGetAll('user:2');
-
-// List operations
-await client.lPush('tasks', 'task1');
-await client.lPush('tasks', 'task2');
-const tasks = await client.lRange('tasks', 0, -1);
-
-// Set operations
-await client.sAdd('tags', 'javascript');
-await client.sAdd('tags', 'nodejs');
-const tags = await client.sMembers('tags');
-
-// Expiration
-await client.setEx('temporary', 3600, 'expires in 1 hour');
-await client.expire('user:1', 3600);
-
-// Clean up
-await redisManager.disConnect();
-```
-
-### Connection Monitoring
-
-```javascript
-const redisManager = new RedisManager();
-
-// Check if connected before operations
-if (await redisManager.isConnected()) {
-  const client = redisManager.getClient();
-  // Perform operations
-} else {
-  console.log('Redis not connected');
-}
-```
-
-### Error Handling
-
-```javascript
-const redisManager = new RedisManager();
-
-try {
-  const connected = await redisManager.connect(process.env.REDIS_URL);
-  
-  if (!connected) {
-    console.error('Failed to connect to Redis');
-    // Fall back to memory storage or handle appropriately
-    return;
-  }
-  
-  const client = redisManager.getClient();
-  await client.set('key', 'value');
-  
-} catch (error) {
-  console.error('Redis operation failed:', error);
-} finally {
-  await redisManager.disConnect();
-}
-```
-
-## API Methods
-
-### `connect(redisUrl, certPath?)`
-
-Connect to Redis server.
-
-**Parameters:**
-- `redisUrl` (string) - Redis connection URL (`redis://` or `rediss://`)
-- `certPath` (string, optional) - Path to TLS certificate file (required for `rediss://`)
-
-**Returns:** `Promise<boolean>` - Returns `true` if connected successfully
-
-**Example:**
-```javascript
-// Non-TLS connection
-await redisManager.connect('redis://localhost:6379');
-
-// TLS connection
-await redisManager.connect('rediss://localhost:6379', '/path/to/cert.pem');
-```
-
-### `getClient()`
-
-Get the Redis client instance for direct operations.
-
-**Returns:** Redis client object
-
-**Example:**
-```javascript
-const client = redisManager.getClient();
-await client.set('key', 'value');
-await client.get('key');
-```
-
-### `isConnected()`
-
-Check if Redis connection is active and responsive.
-
-**Returns:** `Promise<boolean>` - Returns `true` if connected and responsive
-
-**Example:**
-```javascript
-const connected = await redisManager.isConnected();
-if (connected) {
-  // Proceed with operations
-}
-```
-
-### `disConnect()`
-
-Disconnect from Redis server and clean up resources.
-
-**Returns:** `Promise<void>`
-
-**Example:**
-```javascript
-await redisManager.disConnect();
-```
-
-## Features
-
-- **Automatic Reconnection**: Handles connection drops and reconnects automatically
-- **TLS Support**: Secure connections with certificate-based authentication
-- **Connection Pooling**: Efficient connection management
-- **Error Handling**: Graceful error handling and logging
-- **Health Checks**: Built-in connection status monitoring
-
-## Related Documentation
-
-- [SessionManager](./session-manager.md) - Uses RedisManager for session storage
-- [Back to main documentation](../README.md)