@venizia/ignis-docs 0.0.5 → 0.0.6-0

package/wiki/references/helpers/logger.md

@@ -1,296 +0,0 @@
-# Logger Helper
-
-Powerful, flexible logging built on Winston - supports multiple transports, log levels, hierarchical scopes, and high-frequency logging for performance-critical applications.
-
-## Quick Reference
-
-| Feature | Description |
-|---------|-------------|
-| **Factory Method** | `LoggerFactory.getLogger(['scope1', 'scope2'])` |
-| **Direct Access** | `Logger.get('scope')` |
-| **Method Scoping** | `logger.for('methodName').info('message')` |
-| **Log Levels** | `error`, `alert`, `emerg`, `warn`, `info`, `http`, `verbose`, `debug`, `silly` |
-| **Transports** | Console (default), DailyRotateFile, UDP/Dgram |
-| **Formats** | JSON (`json`), Pretty Text (`text`) |
-| **HF Logger** | Zero-allocation logging for HFT use cases |
-
-### Common Methods
-
-```typescript
-logger.info('message');                    // Informational
-logger.error('message');                   // Error
-logger.warn('message');                    // Warning
-logger.debug('message');                   // Debug (requires DEBUG=true)
-logger.for('methodName').info('message');  // Method-scoped logging
-```
-
-## Getting a Logger Instance
-
-### Using LoggerFactory (Recommended)
-
-```typescript
-import { LoggerFactory } from '@venizia/ignis-helpers';
-
-const logger = LoggerFactory.getLogger(['MyService']);
-
-logger.info('This is an informational message.');
-logger.error('This is an error message.');
-```
-
-### Using Logger.get() Directly
-
-```typescript
-import { Logger } from '@venizia/ignis-helpers';
-
-const logger = Logger.get('MyService');
-logger.info('Direct logger access');
-```
-
-### Logger Caching
-
-Both methods use internal caching - the same scope always returns the same logger instance:
-
-```typescript
-const logger1 = Logger.get('MyService');
-const logger2 = Logger.get('MyService');
-// logger1 === logger2 (same instance)
-```
-
-## Method-Scoped Logging with `.for()`
-
-The `.for()` method creates a sub-scoped logger for specific methods, making it easy to trace logs:
-
-```typescript
-class UserService {
-  private logger = LoggerFactory.getLogger(['UserService']);
-
-  async createUser(data: CreateUserDto) {
-    this.logger.for('createUser').info('Creating user: %j', data);
-    // Output: [UserService-createUser] Creating user: {...}
-
-    try {
-      const user = await this.userRepo.create({ data });
-      this.logger.for('createUser').info('User created: %s', user.id);
-      return user;
-    } catch (error) {
-      this.logger.for('createUser').error('Failed to create user: %s', error);
-      throw error;
-    }
-  }
-}
-```
-
-## Log Formats
-
-The logger supports two output formats controlled by `APP_ENV_LOGGER_FORMAT`:
-
-### JSON Format
-
-```bash
-APP_ENV_LOGGER_FORMAT=json
-```
-
-Output:
-```json
-{"level":"info","message":"[UserService] User created","timestamp":"2024-01-11T10:30:00.000Z","label":"app"}
-```
-
-### Pretty Text Format (Default)
-
-```bash
-APP_ENV_LOGGER_FORMAT=text
-```
-
-Output:
-```
-2024-01-11T10:30:00.000Z [app] info: [UserService] User created
-```
-
-## File Rotation Configuration
-
-Configure file rotation through environment variables or programmatically:
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `APP_ENV_LOGGER_FILE_FREQUENCY` | `1h` | Rotation frequency |
-| `APP_ENV_LOGGER_FILE_MAX_SIZE` | `100m` | Max file size before rotation |
-| `APP_ENV_LOGGER_FILE_MAX_FILES` | `5d` | Retention period (days) |
-| `APP_ENV_LOGGER_FILE_DATE_PATTERN` | `YYYYMMDD_HH` | Date pattern in filename |
-| `APP_ENV_LOGGER_FOLDER_PATH` | `./` | Log files directory |
-
-### Programmatic Configuration
-
-```typescript
-import { defineCustomLogger, applicationLogFormatter } from '@venizia/ignis-helpers';
-
-const customLogger = defineCustomLogger({
-  loggerFormatter: applicationLogFormatter,
-  transports: {
-    info: {
-      file: {
-        prefix: 'my-app',
-        folder: './logs',
-        frequency: '24h',       // Rotate daily
-        maxSize: '500m',        // 500MB max
-        maxFiles: '30d',        // Keep 30 days
-        datePattern: 'YYYYMMDD' // Daily pattern
-      }
-    },
-    error: {
-      file: {
-        prefix: 'my-app-error',
-        folder: './logs',
-        maxFiles: '90d'         // Keep error logs longer
-      }
-    }
-  }
-});
-```
-
-## High-Frequency Logger (HfLogger)
-
-For performance-critical applications like HFT systems, use `HfLogger` which provides:
-
-- Zero allocation in hot path
-- Lock-free ring buffer (64K entries)
-- Sub-microsecond latency (~100-300ns)
-- Pre-encoded messages
-- Async background flushing
-
-### Basic Usage
-
-```typescript
-import { HfLogger, HfLogFlusher } from '@venizia/ignis-helpers';
-
-// At initialization time (once):
-const logger = HfLogger.get('OrderEngine');
-const MSG_ORDER_SENT = HfLogger.encodeMessage('Order sent');
-const MSG_ORDER_FILLED = HfLogger.encodeMessage('Order filled');
-
-// Start background flusher
-const flusher = new HfLogFlusher();
-flusher.start(100); // Flush every 100ms
-
-// In hot path (~100-300ns, zero allocation):
-logger.log('info', MSG_ORDER_SENT);
-logger.log('info', MSG_ORDER_FILLED);
-```
-
-### HfLogger API
-
-| Method | Description |
-|--------|-------------|
-| `HfLogger.get(scope)` | Get/create a cached logger instance |
-| `HfLogger.encodeMessage(msg)` | Pre-encode a message (cached) |
-| `logger.log(level, msgBytes)` | Log to ring buffer (zero allocation) |
-
-### HfLogFlusher API
-
-| Method | Description |
-|--------|-------------|
-| `flusher.flush()` | Flush buffered entries to output |
-| `flusher.start(intervalMs)` | Start background flush loop |
-
-### Performance Characteristics
-
-| Metric | Value |
-|--------|-------|
-| Log latency | ~100-300 nanoseconds |
-| Buffer size | 64K entries (16MB) |
-| Entry size | 256 bytes fixed |
-| Allocation | Zero in hot path |
-
-## Environment Variables
-
-### Core Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DEBUG` | `false` | Enable debug logging |
-| `APP_ENV_EXTRA_LOG_ENVS` | `` | Additional environments to enable debug |
-| `APP_ENV_LOGGER_FORMAT` | `text` | Output format (`json` or `text`) |
-| `APP_ENV_LOGGER_FOLDER_PATH` | `./` | Log files directory |
-
-### UDP Transport
-
-| Variable | Description |
-|----------|-------------|
-| `APP_ENV_LOGGER_DGRAM_HOST` | UDP log aggregator host |
-| `APP_ENV_LOGGER_DGRAM_PORT` | UDP log aggregator port |
-| `APP_ENV_LOGGER_DGRAM_LABEL` | Label to identify log source |
-| `APP_ENV_LOGGER_DGRAM_LEVELS` | Comma-separated levels to send via UDP |
-
-### Example `.env`
-
-```bash
-# Core
-DEBUG=true
-APP_ENV_LOGGER_FORMAT=json
-APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
-
-# File rotation
-APP_ENV_LOGGER_FILE_FREQUENCY=24h
-APP_ENV_LOGGER_FILE_MAX_SIZE=500m
-APP_ENV_LOGGER_FILE_MAX_FILES=30d
-
-# UDP transport
-APP_ENV_LOGGER_DGRAM_HOST=127.0.0.1
-APP_ENV_LOGGER_DGRAM_PORT=5000
-APP_ENV_LOGGER_DGRAM_LABEL=my-app
-APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
-```
-
-## Best Practices
-
-### 1. Use Method-Scoped Logging
-
-```typescript
-// Good - clear context
-this.logger.for('createOrder').info('Processing order: %s', orderId);
-
-// Less clear
-this.logger.info('[createOrder] Processing order: %s', orderId);
-```
-
-### 2. Pre-encode HfLogger Messages
-
-```typescript
-// Good - pre-encoded at init
-const MSG_TICK = HfLogger.encodeMessage('Tick received');
-logger.log('debug', MSG_TICK);
-
-// Bad - encodes on every call
-logger.log('debug', HfLogger.encodeMessage('Tick received'));
-```
-
-### 3. Use Appropriate Logger for Use Case
-
-| Use Case | Logger |
-|----------|--------|
-| General application | `Logger` / `LoggerFactory` |
-| High-frequency trading | `HfLogger` |
-| Performance-critical paths | `HfLogger` |
-| Debug/development | `Logger` with `DEBUG=true` |
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) - Logging in services
-  - [Controllers](/guides/core-concepts/controllers) - Logging in controllers
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-  - [Error Helper](./error) - Error handling utilities
-
-- **References:**
-  - [Request Tracker Component](/references/components/request-tracker) - Request logging
-  - [Environment Variables](/references/configuration/environment-variables) - All configuration options
-
-- **External Resources:**
-  - [Winston Documentation](https://github.com/winstonjs/winston) - Winston logging library
-
-- **Best Practices:**
-  - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Using logs for debugging
-  - [Performance Optimization](/best-practices/performance-optimization) - High-performance logging

package/wiki/references/helpers/network.md

@@ -1,396 +0,0 @@
-# Network Helper
-
-Comprehensive network communication utilities for HTTP, TCP, and UDP protocols with full TypeScript support and customizable options.
-
-## Quick Reference
-
-| Helper | Protocol | Type | Use Case |
-|--------|----------|------|----------|
-| **AxiosNetworkRequest** | HTTP/HTTPS | Client | REST API calls (axios-based) |
-| **NodeFetchNetworkRequest** | HTTP/HTTPS | Client | REST API calls (native fetch) |
-| **NetworkTcpClient** | TCP/TLS | Client | Raw TCP connections |
-| **NetworkTcpServer** | TCP/TLS | Server | TCP server implementation |
-| **NetworkUdpClient** | UDP | Client | Datagram sockets |
-
-### HTTP Methods
-
-| Method | Purpose |
-|--------|---------|
-| `send({ url, method: 'get' })` | GET request |
-| `send({ url, method: 'post', body })` | POST request |
-| `send({ url, method: 'put', body })` | PUT request |
-| `send({ url, method: 'delete' })` | DELETE request |
-
-### TCP Operations
-
-| Class | Methods |
-|-------|---------|
-| **Client** | `connect()`, `emit({ payload })`, `disconnect()`, `forceReconnect()` |
-| **Server** | `broadcast({ message })`, `sendToClient({ id, message })` |
-
-## HTTP Request
-
-The HTTP request helper provides a flexible and extensible framework for making HTTP requests, supporting both `axios` and the native Node.js `fetch` API.
-
-### Configuration Interfaces
-
-```typescript
-// Axios configuration
-interface IAxiosNetworkRequestOptions {
-  name: string;
-  networkOptions: Omit<AxiosRequestConfig, 'baseURL'> & {
-    baseUrl?: string;
-  };
-}
-
-// Node Fetch configuration
-interface INodeFetchNetworkRequestOptions {
-  name: string;
-  networkOptions: RequestInit & {
-    baseUrl?: string;
-  };
-}
-```
-
-### Using Axios
-
-```typescript
-import { AxiosNetworkRequest } from '@venizia/ignis-helpers';
-
-class MyApiClient extends AxiosNetworkRequest {
-  constructor() {
-    super({
-      name: 'MyApiClient',
-      networkOptions: {
-        baseUrl: 'https://api.example.com',
-        timeout: 5000,
-        headers: {
-          'X-Custom-Header': 'MyValue',
-          'Authorization': 'Bearer token',
-        },
-        // Full axios options available
-        withCredentials: true,
-        validateStatus: (status) => status < 500,
-      },
-    });
-  }
-
-  async getUsers() {
-    const response = await this.getNetworkService().send({
-      url: '/users',
-      method: 'get',
-    });
-    return response.data;
-  }
-
-  async createUser(data: CreateUserDto) {
-    const response = await this.getNetworkService().send({
-      url: '/users',
-      method: 'post',
-      body: data,
-    });
-    return response.data;
-  }
-}
-```
-
-### Using Node.js Fetch
-
-```typescript
-import { NodeFetchNetworkRequest } from '@venizia/ignis-helpers';
-
-class MyApiClient extends NodeFetchNetworkRequest {
-  constructor() {
-    super({
-      name: 'MyApiClient',
-      networkOptions: {
-        baseUrl: 'https://api.example.com',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        // Full RequestInit options available
-        credentials: 'include',
-        mode: 'cors',
-      },
-    });
-  }
-
-  async getUsers() {
-    const response = await this.getNetworkService().send({
-      url: '/users',
-      method: 'get',
-      timeout: 5000, // Timeout support
-    });
-    return response.json();
-  }
-}
-```
-
-### Request Options
-
-#### Axios Request Options
-
-```typescript
-interface IAxiosRequestOptions {
-  url: string;
-  method?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options';
-  params?: Record<string, any>;     // Query parameters
-  body?: any;                        // Request body
-  headers?: Record<string, string>;  // Additional headers
-  rejectUnauthorized?: boolean;      // SSL verification (default: false)
-  // Plus all AxiosRequestConfig options
-}
-```
-
-#### Node Fetch Request Options
-
-```typescript
-interface INodeFetchRequestOptions {
-  url: string;
-  method?: string;
-  params?: Record<string, any>;  // Query parameters
-  body?: any;                     // Request body
-  headers?: Record<string, string>;
-  timeout?: number;               // Request timeout in ms
-  // Plus all RequestInit options
-}
-```
-
-## TCP Socket
-
-The TCP Socket helpers provide robust TCP and TLS/SSL connection management with automatic reconnection.
-
-### TCP Client
-
-```typescript
-import { NetworkTcpClient } from '@venizia/ignis-helpers';
-
-const tcpClient = new NetworkTcpClient({
-  identifier: 'my-tcp-client',
-  options: {
-    host: 'localhost',
-    port: 8080,
-  },
-  reconnect: true,           // Auto-reconnect on disconnect
-  maxRetry: 5,               // Max reconnection attempts
-  encoding: 'utf8',          // Data encoding
-
-  onConnected: ({ client }) => {
-    console.log('Connected to server');
-  },
-  onData: ({ identifier, message }) => {
-    console.log('Received:', message.toString());
-  },
-  onClosed: ({ client }) => {
-    console.log('Connection closed');
-  },
-  onError: (error) => {
-    console.error('Connection error:', error);
-  },
-});
-
-// Connect
-tcpClient.connect({ resetReconnectCounter: true });
-
-// Send data
-tcpClient.emit({ payload: 'Hello, Server!' });
-tcpClient.emit({ payload: Buffer.from([0x01, 0x02, 0x03]) });
-
-// Check connection
-if (tcpClient.isConnected()) {
-  // ...
-}
-
-// Disconnect
-tcpClient.disconnect();
-
-// Force reconnect
-tcpClient.forceReconnect();
-```
-
-### TLS TCP Client
-
-```typescript
-import { NetworkTlsTcpClient } from '@venizia/ignis-helpers';
-
-const tlsClient = new NetworkTlsTcpClient({
-  identifier: 'secure-client',
-  options: {
-    host: 'secure.example.com',
-    port: 443,
-    rejectUnauthorized: true,
-    // TLS options
-    ca: fs.readFileSync('ca.crt'),
-    cert: fs.readFileSync('client.crt'),
-    key: fs.readFileSync('client.key'),
-  },
-  onData: ({ message }) => {
-    console.log('Secure data:', message);
-  },
-});
-```
-
-### TCP Server
-
-```typescript
-import { NetworkTcpServer } from '@venizia/ignis-helpers';
-
-const tcpServer = new NetworkTcpServer({
-  identifier: 'my-tcp-server',
-  listenOptions: {
-    port: 8080,
-    host: '0.0.0.0',
-  },
-  authenticateOptions: {
-    required: true,
-    timeout: 5000,
-  },
-
-  onClientConnect: ({ id, socket }) => {
-    console.log(`Client ${id} connected`);
-  },
-  onClientData: ({ id, data }) => {
-    console.log(`Data from ${id}:`, data.toString());
-  },
-  onClientDisconnect: ({ id }) => {
-    console.log(`Client ${id} disconnected`);
-  },
-  onAuthenticate: async ({ id, data }) => {
-    // Return true to authenticate
-    return data.toString() === 'secret-token';
-  },
-});
-
-// Broadcast to all clients
-tcpServer.broadcast({ message: 'Hello everyone!' });
-
-// Send to specific client
-tcpServer.sendToClient({ clientId: 'client-123', message: 'Private message' });
-
-// Get connected clients
-const clients = tcpServer.getClients();
-```
-
-## UDP Socket
-
-The UDP Socket helper provides datagram socket communication with multicast support.
-
-### UDP Client
-
-```typescript
-import { NetworkUdpClient } from '@venizia/ignis-helpers';
-
-const udpClient = NetworkUdpClient.newInstance({
-  identifier: 'my-udp-client',
-  port: 8081,
-  host: '0.0.0.0',          // Bind address
-  reuseAddr: true,           // Allow address reuse
-
-  // Multicast configuration
-  multicastAddress: {
-    groups: ['239.1.2.3'],
-    interface: '0.0.0.0',
-  },
-
-  onConnected: ({ identifier, port }) => {
-    console.log(`UDP socket bound to port ${port}`);
-  },
-  onData: ({ identifier, message, remoteInfo }) => {
-    console.log(`From ${remoteInfo.address}:${remoteInfo.port}:`, message.toString());
-  },
-  onBind: async ({ socket, multicastAddress }) => {
-    // Join multicast groups after binding
-    if (multicastAddress?.groups) {
-      for (const group of multicastAddress.groups) {
-        socket.addMembership(group, multicastAddress.interface);
-      }
-    }
-  },
-  onError: ({ error }) => {
-    console.error('UDP error:', error);
-  },
-});
-
-// Start listening
-udpClient.connect();
-
-// Check status
-if (udpClient.isConnected()) {
-  // ...
-}
-
-// Close
-udpClient.disconnect();
-```
-
-## Common Patterns
-
-### Service with HTTP Client
-
-```typescript
-import { AxiosNetworkRequest } from '@venizia/ignis-helpers';
-
-class PaymentGateway extends AxiosNetworkRequest {
-  constructor() {
-    super({
-      name: 'PaymentGateway',
-      networkOptions: {
-        baseUrl: process.env.PAYMENT_API_URL,
-        timeout: 30000,
-        headers: {
-          'X-API-Key': process.env.PAYMENT_API_KEY,
-        },
-      },
-    });
-  }
-
-  async charge(amount: number, currency: string) {
-    const response = await this.getNetworkService().send({
-      url: '/v1/charges',
-      method: 'post',
-      body: { amount, currency },
-    });
-
-    this.logger.for('charge').info('Payment processed: %s', response.data.id);
-    return response.data;
-  }
-}
-```
-
-### Real-time Data Feed (TCP)
-
-```typescript
-import { NetworkTcpClient } from '@venizia/ignis-helpers';
-
-class MarketDataFeed extends NetworkTcpClient<TcpSocketConnectOpts, Socket> {
-  constructor() {
-    super({
-      identifier: 'market-data',
-      scope: 'MarketDataFeed',
-      options: { host: 'feed.exchange.com', port: 9000 },
-      reconnect: true,
-      maxRetry: -1, // Infinite retries
-      encoding: 'utf8',
-    });
-  }
-
-  handleData(opts: { identifier: string; message: Buffer }) {
-    const tick = JSON.parse(opts.message.toString());
-    this.emit('tick', tick);
-  }
-}
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) - Network operations in services
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-  - [Queue Helper](./queue) - Message queuing
-  - [Redis Helper](./redis) - Redis connections
-
-- **Best Practices:**
-  - [Security Guidelines](/best-practices/security-guidelines) - Network security
-  - [Performance Optimization](/best-practices/performance-optimization) - Connection pooling