@igxjs/node-components 1.0.7 → 1.0.8

package/components/jwt.js

@@ -27,7 +27,7 @@ export class JwtManager {
   /**
    * Generate JWT token for user session
    * @param {import('jose').JWTPayload} data User data payload
-   * @param {string} input Secret key or password for encryption
+   * @param {string} secret Secret key or password for encryption
    * @param {Object} [options] Per-call configuration overrides
    * @param {string} [options.algorithm] Override default algorithm
    * @param {string} [options.encryption] Override default encryption method
@@ -38,7 +38,7 @@ export class JwtManager {
    * @param {string} [options.subject] Override default subject claim
    * @returns {Promise<string>} Returns encrypted JWT token
    */
-  async encrypt(data, input, options = {}) {
+  async encrypt(data, secret, options = {}) {
     const algorithm = options.algorithm || this.algorithm;
     const encryption = options.encryption || this.encryption;
     const expirationTime = options.expirationTime || this.expirationTime;
@@ -47,9 +47,9 @@ export class JwtManager {
     const audience = options.audience || this.audience;
     const subject = options.subject || this.subject;
 
-    const secret = await crypto.subtle.digest(
+    const secretHash = await crypto.subtle.digest(
       secretHashAlgorithm,
-      new TextEncoder().encode(input)
+      new TextEncoder().encode(secret)
     );
 
     const jwt = new EncryptJWT(data)
@@ -65,13 +65,13 @@ export class JwtManager {
     if (audience) jwt.setAudience(audience);
     if (subject) jwt.setSubject(subject);
 
-    return await jwt.encrypt(new Uint8Array(secret));
+    return await jwt.encrypt(new Uint8Array(secretHash));
   }
 
   /**
    * Decrypt JWT token for user session
    * @param {string} token JWT token to decrypt
-   * @param {string} input Secret key or password for decryption
+   * @param {string} secret Secret key or password for decryption
    * @param {Object} [options] Per-call configuration overrides
    * @param {number} [options.clockTolerance] Override default clock tolerance
    * @param {string} [options.secretHashAlgorithm] Override default hash algorithm
@@ -80,16 +80,16 @@ export class JwtManager {
    * @param {string} [options.subject] Expected subject claim for validation
    * @returns {Promise<import('jose').JWTDecryptResult<import('jose').EncryptJWT>>} Returns decrypted JWT token
    */
-  async decrypt(token, input, options = {}) {
+  async decrypt(token, secret, options = {}) {
     const clockTolerance = options.clockTolerance ?? this.clockTolerance;
     const secretHashAlgorithm = options.secretHashAlgorithm || this.secretHashAlgorithm;
     const issuer = options.issuer || this.issuer;
     const audience = options.audience || this.audience;
     const subject = options.subject || this.subject;
 
-    const secret = await crypto.subtle.digest(
+    const secretHash = await crypto.subtle.digest(
       secretHashAlgorithm,
-      new TextEncoder().encode(input)
+      new TextEncoder().encode(secret)
     );
 
     const decryptOptions = { clockTolerance };
@@ -99,6 +99,6 @@ export class JwtManager {
     if (audience) decryptOptions.audience = audience;
     if (subject) decryptOptions.subject = subject;
 
-    return await jwtDecrypt(token, new Uint8Array(secret), decryptOptions);
+    return await jwtDecrypt(token, new Uint8Array(secretHash), decryptOptions);
   }
 }

package/docs/README.md

@@ -0,0 +1,54 @@
+# Node Components Documentation
+
+Detailed documentation for `@igxjs/node-components` - shared components for Express.js applications.
+
+## 📚 Component Documentation
+
+### Core Modules
+
+- **[SessionManager](./session-manager.md)** - SSO session management with Redis and memory storage
+  - Configuration options and singleton pattern
+  - Complete setup and usage examples
+  - API reference for all methods
+
+- **[FlexRouter](./flex-router.md)** - Flexible routing utility for Express.js
+  - Context path and middleware management
+  - API versioning and route organization
+  - Advanced usage patterns
+
+- **[RedisManager](./redis-manager.md)** - Redis connection management
+  - TLS/SSL support
+  - Connection monitoring and error handling
+  - Direct Redis operations
+
+- **[JWT Manager](./jwt-manager.md)** - JWT encryption and decryption
+  - Secure token-based authentication
+  - Express.js integration patterns
+  - Refresh token implementation
+
+- **[HTTP Handlers](./http-handlers.md)** - Standardized error handling
+  - Custom error classes and middleware
+  - HTTP status codes and messages
+  - Axios error handling and validation helpers
+
+## 🚀 Quick Links
+
+- [Main README](../README.md) - Package overview and installation
+- [GitHub Repository](https://github.com/igxjs/node-components)
+
+## 💡 Getting Help
+
+If you need help:
+1. Check the relevant component documentation above
+2. Review the examples in each guide
+3. Look at the type definitions in `index.d.ts`
+4. Open an issue on GitHub
+
+## 📖 Documentation Structure
+
+Each component documentation includes:
+- Overview of features
+- Configuration options
+- Basic and advanced usage examples
+- Complete API reference
+- Related documentation links

package/docs/flex-router.md

@@ -0,0 +1,167 @@
+# 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

@@ -0,0 +1,302 @@
+# 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)