# @6thbridge/utils Documentation
[](https://badge.fury.io/js/%406thbridge%2Futils)[](https://opensource.org/licenses/ISC)
A comprehensive TypeScript utility library for Node.js applications, providing reusable components for common development tasks including database operations, caching, messaging, logging, and more.
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Modules](#core-modules)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

## Installation
``` bash
# Using npm
npm install @6thbridge/utils

# Using yarn
yarn add @6thbridge/utils
```
### Dependencies
This package includes the following key dependencies:
- **Database**: `mongoose`, , `ioredis` `mongoose-paginate-v2`
- **Messaging**: `amqplib`, , `kafkajs` `amqp-connection-manager`
- **Utilities**: `lodash`, `dayjs`, `joi`, `axios`
- **Monitoring**: , `rollbar` `@opentelemetry/auto-instrumentations-node`

## Quick Start
``` typescript
import { 
  HelperUtil, 
  ReferenceUtil, 
  RedisClient, 
  RabbitMQClient,
  MongoDBRepository,
  logger 
} from '@6thbridge/utils';

// Generate a reference
const reference = ReferenceUtil.generateReference('production');

// Use Redis
const redis = RedisClient.getInstance();
await redis.connect({ url: 'redis://localhost:6379' });

// Clean data
const cleanData = HelperUtil.removeFieldsWithEmptyValue(data);

// Log information
logger.info('Application started', { reference });
```
## Core Modules
### 🔧 [Utilities](./src/utils/README.md)
Essential utility functions for data manipulation, reference generation, and common operations.
- **HelperUtil**: Data cleaning, activity logging, async utilities
- **ReferenceUtil**: Reference and UUID generation
- **Phone Number Formatting**: International phone number formatting

### 🗄️ [Database](./src/database/README.md)
Database abstraction layers and repository patterns.
- **MongoDBRepository**: MongoDB operations with Mongoose
- **Redis Integration**: Caching and session management

### 📨 [Brokers](./src/brokers/README.md)
Message broker implementations for event-driven architecture.
- **RabbitMQClient**: AMQP messaging with RabbitMQ
- **KafkaJS Integration**: Apache Kafka message streaming

### 💾 [Cache](./src/cache/README.md)
Caching solutions for improved performance.
- **RedisClient**: Redis-based caching with clustering support
- **Node-Cache**: In-memory caching for lightweight applications

### 📝 [Logger](./src/logger/README.md)
Comprehensive logging system with multiple levels and integrations.
- **Structured Logging**: JSON-formatted logs
- **Multiple Transports**: Console, file, and external service logging
- **Error Tracking**: Integration with monitoring services

### 🛡️ [Middlewares](./src/middlewares/README.md)
Express.js middlewares for common functionality.
- **Authentication**: JWT and API key validation
- **Validation**: Request/response validation
- **Error Handling**: Centralized error processing

### 📊 [Monitoring](./src/monitoring/README.md)
Application monitoring and observability tools.
- **OpenTelemetry**: Distributed tracing
- **Rollbar Integration**: Error monitoring and alerting

## API Reference
### HelperUtil
``` typescript
class HelperUtil {
  // Async utility
  static async sleep(durationInMs: number = 1000): Promise<void>
  
  // Data cleaning
  static removeFieldsWithEmptyValue(value: any): any
  
  // Activity logging
  static async saveActivityLog(activityLog: SaveActivityLogDTO, options?: any): Promise<void>
}
```
### ReferenceUtil
``` typescript
class ReferenceUtil {
  // Generate environment-specific reference
  static generateReference(env: string): string
  
  // Generate reference with custom prefix
  static generateReferenceWithPrefix(env: string, prefix: string): string
  
  // Generate UUID
  static generateUUID(options?: any): string
}
```
### RedisClient
``` typescript
class RedisClient {
  // Singleton pattern
  static getInstance(): RedisClient
  static resetInstance(): void
  
  // Connection management
  connect(config?: RedisConnect): Commander
  
  // Redis operations
  static getRedis(): Commander
}
```
### RabbitMQClient
``` typescript
class RabbitMQClient {
  // Singleton pattern
  static getInstance(): RabbitMQClient
  static resetInstance(): void
  
  // Connection and messaging
  connect(config: RabbitMQConnectConfig): AmqpConnectionManager
  static async sendToQueue(queueName: string, payload: any, options?: PublishOptions): Promise<any>
  static async publishToExchange(exchangeName: string, routeKey: string, payload: any, options?: PublishOptions): Promise<any>
  
  // Message consumption
  static listen(queueName: string, options: any, callback: Function): Promise<void>
}
```
### MongoDBRepository
``` typescript
class MongoDBRepository {
  constructor(Model: TypedModel<any>)
  
  // CRUD operations
  create(payload: Record<string, any>, options?: CreateOptions): Promise<any>
  findById(id: string, projection?: ProjectionType<any>, options?: QueryOptions): Promise<any>
  findOne(condition: Record<string, any>, sort?: Record<string, number>, options?: FindOptions): Promise<any>
  find(condition: Record<string, any>, sort?: Record<string, any>, options?: FindOptions): Promise<any>
  
  // Advanced operations
  paginate(condition: Record<string, any>, sort?: Record<string, any>, options?: FindOptions): Promise<PaginateResult<any>>
  updateOne(query: Record<string, any>, update: Record<string, any>, options?: MongooseOptions): Promise<any>
  bulkWrite(bulkWritePayload: any): Promise<any>
}
```
## Examples
### Basic Usage Examples
#### Data Cleaning
``` typescript
import { HelperUtil } from '@6thbridge/utils';

const dirtyData = {
  name: 'John Doe',
  email: '',
  phone: null,
  address: undefined,
  age: 30
};

const cleanData = HelperUtil.removeFieldsWithEmptyValue(dirtyData);
// Result: { name: 'John Doe', age: 30 }
```
#### Reference Generation
``` typescript
import { ReferenceUtil } from '@6thbridge/utils';

// Production reference
const prodRef = ReferenceUtil.generateReference('production');
// Example: L20240101120000ABCDE

// Development reference with prefix
const devRef = ReferenceUtil.generateReferenceWithPrefix('development', 'ORDER');
// Example: DORDER20240101120000ABCDE
```
#### Redis Operations
``` typescript
import { RedisClient } from '@6thbridge/utils';

async function cacheExample() {
  const redis = RedisClient.getInstance();
  redis.connect({
    url: 'redis://localhost:6379',
    keepAlive: true
  });

  // Cache operations
  await RedisClient.getRedis().set('user:123', JSON.stringify({ name: 'John' }));
  const user = await RedisClient.getRedis().get('user:123');
}
```
#### Message Queue
``` typescript
import { RabbitMQClient } from '@6thbridge/utils';

async function messagingExample() {
  const broker = RabbitMQClient.getInstance();
  broker.connect({
    url: 'amqp://localhost:5672',
    queues: [
      { queueName: 'user.created' }
    ],
    exchanges: [],
    exchangeBindings: []
  });

  // Send message
  await RabbitMQClient.sendToQueue('user.created', {
    userId: '123',
    event: 'USER_CREATED',
    timestamp: new Date()
  });

  // Listen for messages
  RabbitMQClient.listen('user.created', {}, (message, options) => {
    console.log('Received:', JSON.parse(message));
    options.ack();
  });
}
```
### Phone Number Formatting
``` typescript
import { formatPhoneNumber, formatPhoneNumberArray } from '@6thbridge/utils';

// Single phone number
let phoneNumber = '08012345678';
phoneNumber = formatPhoneNumber(phoneNumber, 'NG');
console.log(phoneNumber); // 2348012345678

// Multiple phone numbers
let phoneNumbers = ['08012345678', '08012345679'];
phoneNumbers = formatPhoneNumberArray(phoneNumbers, 'NG');
console.log(phoneNumbers); // ['2348012345678', '2348012345679']
```
### Logging
``` typescript
import { logger } from '@6thbridge/utils';

// Different log levels
logger.error('Database connection failed', { error: 'Connection refused' });
logger.warn('High memory usage detected', { usage: '85%' });
logger.info('User logged in', { userId: '123' });
logger.debug('Processing request', { requestId: 'req-456' });

// Exception logging
try {
  // risky operation
} catch (error) {
  logger.exception(error, { context: 'user-registration' });
}
```
## Environment Variables
The library supports various environment variables for configuration:
``` bash
# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_password
REDIS_URL=redis://localhost:6379
REDIS_CLUSTER_URL=redis://node1:6379,redis://node2:6379

# RabbitMQ Configuration
RABBITMQ_URL=amqp://localhost:5672
RABBITMQ_CLUSTER_URL=amqp://node1:5672,amqp://node2:5672

# Application Configuration
APP_NAME=your-app-name
TZ=Africa/Lagos
LOG_OUT=1

# Service URLs
USER_SERVICE_URL=http://user-service:3000
```
## Testing
The library includes comprehensive test suites using Jest:
``` bash
# Run all tests
yarn test

# Run tests in watch mode
yarn test --watch

# Run tests with coverage
yarn test --coverage

# Run specific test file
yarn test reference.util.test.ts
```
### Writing Tests
``` typescript
import { ReferenceUtil } from '@6thbridge/utils';

describe('ReferenceUtil', () => {
  it('should generate production reference', () => {
    const ref = ReferenceUtil.generateReference('production');
    expect(ref).toMatch(/^L\d{14}[A-Z]{5}$/);
  });
});
```
## TypeScript Support
This library is written in TypeScript and provides full type definitions:
``` typescript
import { 
  RedisConnect, 
  RabbitMQConnectConfig, 
  SaveActivityLogDTO,
  MongooseOptions 
} from '@6thbridge/utils';

// Type-safe configuration
const redisConfig: RedisConnect = {
  url: 'redis://localhost:6379',
  keepAlive: true,
  heartbeat: 30
};
```
## Performance Considerations
- **Connection Pooling**: Redis and RabbitMQ clients use connection pooling
- **Singleton Pattern**: Database and cache clients follow singleton pattern
- **Lazy Loading**: Connections are established only when needed
- **Memory Management**: Proper cleanup and connection closing

## Error Handling
The library implements comprehensive error handling:
``` typescript
try {
  await RedisClient.getRedis().set('key', 'value');
} catch (error) {
  logger.exception(error, { operation: 'redis-set' });
}
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup
``` bash
# Clone repository
git clone https://github.com/6thbridge/utils.git

# Install dependencies
yarn install

# Run tests
yarn test

# Build library
yarn build
```
## License
This project is licensed under the ISC License.
## Contributors
- [Micheal Akinwonmi](https://github.com/blackhades)

## Support
For support and questions, please open an issue on the GitHub repository.
**Note**: This library is actively maintained and used in production environments. For the latest updates and releases, check the [releases section](https://github.com/6thbridge/utils/releases).