@codisolutions23/node-utils 1.0.0 → 1.1.0

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/comprehensive-improvements.md

@@ -0,0 +1,29 @@
+---
+"@codisolutions23/node-utils": minor
+---
+
+# 🚀 Comprehensive Package Enhancement
+
+## ✨ New Features
+- **NEW**: `ConflictError` class for HTTP 409 responses
+- **NEW**: Enhanced `AuthenticatedRequest` interface with better TypeScript support
+- **NEW**: Comprehensive README documentation with usage examples and API reference
+
+## 🔧 Improvements
+- **Enhanced**: Auth middleware with improved token handling and error messages
+- **Improved**: Error handler middleware with better import paths
+- **Simplified**: Configuration system for better flexibility
+- **Updated**: All AWS SDK packages to latest versions (3.857.x → 3.859.x)
+- **Updated**: Redis ecosystem packages (redis 5.6.1 → 5.8.0, ioredis 5.6.1 → 5.7.0)
+- **Updated**: TypeScript to 5.9.2 for improved type safety
+
+## 📚 Documentation
+- Complete README overhaul with detailed usage examples
+- API reference for all utilities and middleware
+- Best practices and configuration guides
+- Testing support examples and mock utilities
+
+## 🛡️ Security & Performance
+- Latest security patches through dependency updates
+- Improved error handling and logging
+- Better TypeScript type definitions

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/README.md

@@ -1 +1,517 @@
-# codi-node-utils
+# @codisolutions23/node-utils
+
+A comprehensive collection of production-ready Node.js utilities, middleware, and helper functions for building scalable enterprise applications. This foundational package provides essential building blocks for authentication, database operations, caching, logging, and more.
+
+## 🚀 Features
+
+### **🔧 Core Utilities**
+- **Authentication** - JWT token management and password hashing
+- **Database** - MongoDB Atlas connection and query helpers
+- **Caching** - Redis and IoRedis integration with advanced patterns
+- **Logging** - Structured logging with Winston
+- **Email** - Transactional email with Handlebars templating
+- **File Storage** - AWS S3 integration for file uploads
+- **Validation** - HTTP error handling and request validation
+- **Pagination** - Standardized pagination utilities
+
+### **🛡️ Middleware Collection**
+- **Auth Middleware** - JWT authentication and authorization
+- **Error Handler** - Global error handling with proper HTTP responses
+- **Request Validation** - Input sanitization and validation
+
+### **📊 Advanced Features**
+- **Connection Pooling** - Optimized database connections
+- **Cache Strategies** - Intelligent caching with TTL support
+- **Error Context** - Enhanced error tracking and debugging
+- **Template Engine** - Dynamic email and document generation
+- **File Upload** - Secure file handling with S3 integration
+
+## 📦 Installation
+
+```bash
+npm install @codisolutions23/node-utils
+# or
+yarn add @codisolutions23/node-utils
+```
+
+## 🛠️ Quick Start
+
+### Basic Setup
+
+```typescript
+import {
+  useAtlas,
+  useRedis,
+  logger,
+  authenticate,
+  errorHandler
+} from '@codisolutions23/node-utils';
+
+// Initialize database connection
+await useAtlas.connect();
+
+// Initialize Redis
+const redis = useRedis();
+
+// Setup logging
+logger.info('Application started');
+```
+
+## 🔐 Authentication
+
+### JWT Token Management
+
+```typescript
+import { signJwtToken, hashPassword, comparePasswords } from '@codisolutions23/node-utils';
+
+// Generate JWT tokens
+const accessToken = signJwtToken({
+  payload: { userId: '12345', role: 'admin' },
+  secretKey: process.env.JWT_SECRET,
+  signOptions: { expiresIn: '15m' }
+});
+
+// Password hashing and comparison
+const hashedPassword = await hashPassword('userPassword');
+const isValid = await comparePasswords('userPassword', hashedPassword);
+```
+
+### Auth Middleware
+
+```typescript
+import { authenticate } from '@codisolutions23/node-utils';
+
+// Create authentication middleware with your secret
+const authMiddleware = authenticate(process.env.ACCESS_TOKEN_SECRET);
+
+// Protect routes with authentication
+app.use('/api/protected', authMiddleware);
+
+// Access user info in protected routes
+app.get('/api/profile', authMiddleware, (req, res) => {
+  // req.user contains the decoded JWT payload
+  const userId = req.user.id;
+  res.json({ message: `Welcome user ${userId}` });
+});
+```
+
+## 🗄️ Database Operations
+
+### MongoDB Atlas Integration
+
+```typescript
+import { useAtlas, toObjectId } from '@codisolutions23/node-utils';
+
+// Connect to MongoDB Atlas
+await useAtlas.connect();
+
+// Get database instance
+const db = useAtlas.getDb();
+const users = db.collection('users');
+
+// Convert string to ObjectId safely
+const userId = toObjectId('507f1f77bcf86cd799439011');
+const user = await users.findOne({ _id: userId });
+```
+
+### Pagination Helper
+
+```typescript
+import { paginate } from '@codisolutions23/node-utils';
+
+// Standardized pagination
+const page = 0;
+const limit = 10;
+const total = 250;
+const items = await users.find().skip(page * limit).limit(limit).toArray();
+
+const paginatedResult = paginate(items, page, limit, total);
+// Returns: { items, pagination: { page, limit, total, pages, hasNext, hasPrev } }
+```
+
+## 🧠 Caching
+
+### Redis Integration
+
+```typescript
+import { useRedis, useIoRedis, getCacheKey } from '@codisolutions23/node-utils';
+
+// Basic Redis operations
+const redis = useRedis();
+await redis.set('user:123', JSON.stringify(userData), 'EX', 3600);
+const cached = await redis.get('user:123');
+
+// Advanced Redis with IoRedis
+const ioredis = useIoRedis();
+await ioredis.hset('user:123:profile', 'name', 'John Doe', 'email', 'john@example.com');
+
+// Smart cache key generation
+const cacheKey = getCacheKey('user', { id: '123', type: 'profile' });
+// Returns: 'user:123:profile'
+```
+
+### Cache Patterns
+
+```typescript
+// Cache-aside pattern
+async function getUser(userId: string) {
+  const cacheKey = getCacheKey('user', { id: userId });
+  
+  // Try cache first
+  const cached = await redis.get(cacheKey);
+  if (cached) {
+    return JSON.parse(cached);
+  }
+  
+  // Fetch from database
+  const user = await db.collection('users').findOne({ _id: toObjectId(userId) });
+  
+  // Cache for 1 hour
+  if (user) {
+    await redis.setex(cacheKey, 3600, JSON.stringify(user));
+  }
+  
+  return user;
+}
+```
+
+## 📧 Email & Templates
+
+### Handlebars Email Templates
+
+```typescript
+import { sendMail, compileTemplate, getTemplatePath } from '@codisolutions23/node-utils';
+
+// Compile and send templated emails
+const templatePath = getTemplatePath('welcome-email');
+const compiledTemplate = compileTemplate(templatePath);
+
+const html = compiledTemplate({
+  userName: 'John Doe',
+  activationLink: 'https://app.com/activate/token123'
+});
+
+await sendMail({
+  to: 'user@example.com',
+  subject: 'Welcome to Our Platform',
+  html
+});
+```
+
+### Email Configuration
+
+```typescript
+// Environment setup
+process.env.MAILER_HOST = 'smtp.gmail.com';
+process.env.MAILER_PORT = '587';
+process.env.MAILER_USER = 'your-email@gmail.com';
+process.env.MAILER_PASS = 'your-app-password';
+
+// Send emails
+await sendMail({
+  from: 'noreply@yourcompany.com',
+  to: 'recipient@example.com',
+  subject: 'Your Subject',
+  text: 'Plain text content',
+  html: '<h1>HTML Content</h1>'
+});
+```
+
+## ☁️ File Storage (AWS S3)
+
+### S3 Integration
+
+```typescript
+import { useS3 } from '@codisolutions23/node-utils';
+
+const s3Client = useS3();
+
+// Upload file
+const uploadParams = {
+  Bucket: 'your-bucket-name',
+  Key: 'uploads/user-avatar.jpg',
+  Body: fileBuffer,
+  ContentType: 'image/jpeg'
+};
+
+const result = await s3Client.upload(uploadParams).promise();
+console.log('File uploaded:', result.Location);
+
+// Generate signed URL for secure access
+const signedUrl = s3Client.getSignedUrl('getObject', {
+  Bucket: 'your-bucket-name',
+  Key: 'uploads/user-avatar.jpg',
+  Expires: 3600 // 1 hour
+});
+```
+
+## 📝 Logging
+
+### Structured Logging with Winston
+
+```typescript
+import { logger } from '@codisolutions23/node-utils';
+
+// Different log levels
+logger.info('Application started', { port: 3000, env: 'production' });
+logger.warn('High memory usage detected', { usage: '85%' });
+logger.error('Database connection failed', { 
+  error: error.message, 
+  stack: error.stack,
+  timestamp: new Date().toISOString()
+});
+
+// Structured logging for better searchability
+logger.info('User action', {
+  userId: '12345',
+  action: 'login',
+  ip: req.ip,
+  userAgent: req.get('user-agent'),
+  timestamp: new Date().toISOString()
+});
+```
+
+## 🚨 Error Handling
+
+### HTTP Error Classes
+
+```typescript
+import {
+  BadRequestError,
+  NotFoundError,
+  UnauthorizedError,
+  ConflictError,
+  InternalServerError
+} from '@codisolutions23/node-utils';
+
+// Use in your route handlers
+app.post('/api/users', async (req, res, next) => {
+  try {
+    const { email } = req.body;
+    
+    if (!email) {
+      throw new BadRequestError('Email is required');
+    }
+    
+    const existingUser = await users.findOne({ email });
+    if (existingUser) {
+      throw new ConflictError('User already exists');
+    }
+    
+    // Create user logic...
+    res.json({ success: true });
+  } catch (error) {
+    next(error); // Handled by errorHandler middleware
+  }
+});
+```
+
+### Global Error Handler
+
+```typescript
+import { errorHandler } from '@codisolutions23/node-utils';
+
+// Apply global error handling
+app.use(errorHandler);
+
+// All errors are automatically formatted as:
+// {
+//   "status": "error",
+//   "message": "Email is required"
+// }
+```
+
+## 🧪 Testing Support
+
+### Mock Utilities
+
+```typescript
+// Mock Redis for testing
+jest.mock('@codisolutions23/node-utils', () => ({
+  ...jest.requireActual('@codisolutions23/node-utils'),
+  useRedis: () => ({
+    get: jest.fn(),
+    set: jest.fn(),
+    del: jest.fn(),
+  }),
+}));
+
+// Mock database
+const mockDb = {
+  collection: jest.fn(() => ({
+    findOne: jest.fn(),
+    find: jest.fn(),
+    insertOne: jest.fn(),
+  }))
+};
+
+jest.spyOn(require('@codisolutions23/node-utils'), 'useAtlas').mockImplementation(() => ({
+  getDb: () => mockDb,
+}));
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+The package only requires minimal global environment configuration. Most services accept configuration as parameters for maximum flexibility:
+
+```env
+# Required for Redis utilities
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=your-redis-password
+
+# Optional - defaults to development if not set
+NODE_ENV=production
+```
+
+### Service-Specific Configuration
+
+Other services accept configuration when instantiated:
+
+```typescript
+// Database - pass config to connect method
+await useAtlas.connect({
+  uri: 'mongodb://localhost:27017',
+  db: 'your-database'
+});
+
+// Email - pass config to constructor
+const mailer = new useMailer({
+  host: 'smtp.gmail.com',
+  port: 587,
+  secure: false,
+  email: 'your-email@gmail.com',
+  password: 'your-app-password'
+});
+
+// S3 - pass config to constructor
+const s3 = new useS3({
+  accessKeyId: 'your-access-key',
+  secretAccessKey: 'your-secret-key',
+  region: 'us-east-1',
+  endpoint: 'https://s3.amazonaws.com',
+  bucket: 'your-bucket-name',
+  forcePathStyle: false
+});
+
+// Auth - pass secret to middleware function
+const authMiddleware = authenticate('your-jwt-secret');
+```
+
+## 📚 API Reference
+
+### Core Functions
+
+| Function | Description | Usage |
+|----------|-------------|-------|
+| `signJwtToken()` | Generate JWT tokens | `signJwtToken({ payload, secretKey, signOptions })` |
+| `hashPassword()` | Hash passwords with bcrypt | `await hashPassword('password')` |
+| `comparePasswords()` | Compare password with hash | `await comparePasswords('password', hash)` |
+| `toObjectId()` | Convert string to MongoDB ObjectId | `toObjectId('507f1f77bcf86cd799439011')` |
+| `paginate()` | Create pagination object | `paginate(items, page, limit, total)` |
+| `getCacheKey()` | Generate cache keys | `getCacheKey('user', { id: '123' })` |
+
+### Middleware
+
+| Middleware | Description | Usage |
+|------------|-------------|-------|
+| `authenticate()` | JWT authentication | `const authMiddleware = authenticate(secretKey); app.use('/protected', authMiddleware)` |
+| `errorHandler` | Global error handling | `app.use(errorHandler)` |
+
+### Database & Cache
+
+| Function | Description | Usage |
+|----------|-------------|-------|
+| `useAtlas.connect()` | Connect to MongoDB Atlas | `await useAtlas.connect()` |
+| `useAtlas.getDb()` | Get database instance | `const db = useAtlas.getDb()` |
+| `useRedis()` | Get Redis client | `const redis = useRedis()` |
+| `useIoRedis()` | Get IoRedis client | `const ioredis = useIoRedis()` |
+
+## 🎯 Best Practices
+
+### 1. **Error Handling**
+```typescript
+// Always use specific error types
+throw new BadRequestError('Specific error message');
+// Instead of generic Error
+```
+
+### 2. **Logging**
+```typescript
+// Structure your logs for better searchability
+logger.info('User action', {
+  userId,
+  action: 'create_post',
+  metadata: { postId, timestamp }
+});
+```
+
+### 3. **Caching**
+```typescript
+// Use consistent cache key patterns
+const cacheKey = getCacheKey('user:profile', { id: userId });
+// Results in: 'user:profile:123'
+```
+
+### 4. **Database Operations**
+```typescript
+// Always convert string IDs to ObjectId for MongoDB
+const user = await users.findOne({ _id: toObjectId(userId) });
+```
+
+## 🔧 Advanced Configuration
+
+### Custom Logger Configuration
+
+```typescript
+import winston from 'winston';
+import { logger } from '@codisolutions23/node-utils';
+
+// The logger is pre-configured with console and file transports
+// But you can extend it:
+logger.add(new winston.transports.File({
+  filename: 'error.log',
+  level: 'error',
+  format: winston.format.json()
+}));
+```
+
+### Custom Redis Configuration
+
+```typescript
+// The package uses standard Redis configuration
+// But you can override with environment variables:
+process.env.REDIS_URL = 'redis://username:password@host:port';
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`yarn test`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## 📜 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Related Packages
+
+- [@codisolutions23/api-core](https://www.npmjs.com/package/@codisolutions23/api-core) - Enhanced API core with performance optimizations
+- [@codisolutions23/codi-api-server](https://www.npmjs.com/package/@codisolutions23/codi-api-server) - Complete API server implementation
+
+## 📊 Package Stats
+
+- **Zero Dependencies Conflicts** - All dependencies are carefully managed
+- **TypeScript Support** - Full type definitions included
+- **Production Ready** - Used in enterprise applications
+- **Well Tested** - Comprehensive test coverage
+- **Actively Maintained** - Regular updates and improvements
+
+---
+
+Built with ❤️ by the Codi Solutions team