@venizia/ignis-docs 0.0.1-1

package/wiki/references/helpers/crypto.md

@@ -0,0 +1,117 @@
+# Crypto Helper
+
+Cryptographic utilities for AES symmetric encryption, RSA asymmetric encryption, and hashing.
+
+## Quick Reference
+
+| Class/Function | Algorithm | Use Case |
+|----------------|-----------|----------|
+| **AES** | Symmetric | Fast encryption for data at rest (AES-256-CBC, AES-256-GCM) |
+| **RSA** | Asymmetric | Key exchange, digital signatures (public/private keys) |
+| **hash()** | MD5, SHA256 | Passwords, data integrity (HMAC support) |
+
+### AES Algorithms
+
+| Algorithm | Mode | Features |
+|-----------|------|----------|
+| `aes-256-cbc` | CBC | Standard block cipher mode |
+| `aes-256-gcm` | GCM | Authenticated encryption |
+
+### Common Methods
+
+| Operation | AES | RSA |
+|-----------|-----|-----|
+| Encrypt | `aes.encrypt(message, secret)` | `rsa.encrypt(message, publicKey)` |
+| Decrypt | `aes.decrypt(encrypted, secret)` | `rsa.decrypt(encrypted, privateKey)` |
+| Key Generation | N/A (use secret) | `rsa.generateDERKeyPair()` |
+
+## AES (Symmetric Encryption)
+
+The `AES` class provides an interface for encrypting and decrypting data using the Advanced Encryption Standard.
+
+### Creating an AES Instance
+
+You can create an `AES` instance by specifying the algorithm (`aes-256-cbc` or `aes-256-gcm`).
+
+```typescript
+import { AES } from '@venizia/ignis';
+
+const aes = AES.withAlgorithm('aes-256-cbc');
+```
+
+### Encrypting Data
+
+The `encrypt` method takes a message and a secret key.
+
+```typescript
+const secret = 'a-32-byte-long-secret-key-for-aes';
+const message = 'This is a secret message.';
+
+const encryptedMessage = aes.encrypt(message, secret);
+// => Returns a base64 encoded string containing the IV and encrypted data
+```
+
+### Decrypting Data
+
+The `decrypt` method takes the encrypted message and the same secret key.
+
+```typescript
+const decryptedMessage = aes.decrypt(encryptedMessage, secret);
+// => 'This is a secret message.'
+```
+
+## RSA (Asymmetric Encryption)
+
+The `RSA` class provides an interface for encrypting and decrypting data using the RSA algorithm.
+
+### Creating an RSA Instance
+
+```typescript
+import { RSA } from '@venizia/ignis';
+
+const rsa = RSA.withAlgorithm();
+```
+
+### Generating a Key Pair
+
+The `generateDERKeyPair` method creates a new public/private key pair in DER format.
+
+```typescript
+const { publicKey, privateKey } = rsa.generateDERKeyPair();
+```
+
+### Encrypting Data
+
+Encrypt data using the public key.
+
+```typescript
+const message = 'This is another secret.';
+const encrypted = rsa.encrypt(message, publicKey.toString('base64'));
+```
+
+### Decrypting Data
+
+Decrypt data using the private key.
+
+```typescript
+const decrypted = rsa.decrypt(encrypted, privateKey.toString('base64'));
+// => 'This is another secret.'
+```
+
+## Hash Utility
+
+In addition to the `Crypto` helper, `Ignis` also provides a standalone `hash` utility function for creating hashes (e.g., for passwords or data integrity checks).
+
+```typescript
+import { hash } from '@venizia/ignis';
+
+// MD5 Hash
+const md5Hash = hash('some text', { algorithm: 'MD5', outputType: 'hex' });
+
+// SHA256 HMAC
+const sha256Hash = hash('some text', {
+  algorithm: 'SHA256',
+  secret: 'a-secret-key',
+  outputType: 'hex',
+});
+```

package/wiki/references/helpers/env.md

@@ -0,0 +1,67 @@
+# Environment Helper
+
+Structured access to application-specific environment variables with prefix filtering.
+
+## Quick Reference
+
+| Feature | Description |
+|---------|-------------|
+| **Singleton** | `applicationEnvironment` - auto-initialized at startup |
+| **Prefix** | Default `APP_ENV_` (customizable via `APPLICATION_ENV_PREFIX`) |
+| **Type-safe** | `get<T>(key)` with type inference |
+| **Isolation** | Filters `process.env` to prevent conflicts |
+
+### Common Methods
+
+| Method | Purpose | Example |
+|--------|---------|---------|
+| `get<T>(key)` | Get typed environment variable | `get<string>(EnvironmentKeys.APP_ENV_JWT_SECRET)` |
+| `isDevelopment()` | Check if dev environment | `if (env.isDevelopment()) { ... }` |
+
+### Key Features
+
+-   **Prefix-based Filtering**: Isolates app vars (e.g., `APP_ENV_*`)
+-   **Type-safe Access**: `get<T>()` with type inference
+-   **Centralized Management**: Single consistent access point
+
+## Usage
+
+You can import the `applicationEnvironment` instance and use it to retrieve your configuration values.
+
+### Getting Environment Variables
+
+```typescript
+import { applicationEnvironment, EnvironmentKeys } from '@venizia/ignis';
+
+// Get the JWT secret
+const jwtSecret = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_JWT_SECRET);
+
+// Get the server port, parsing it as a number
+const serverPort = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_SERVER_PORT);
+```
+
+### Checking the Current Environment
+
+You can use the `isDevelopment()` method to check if the application is running in a development environment.
+
+```typescript
+import { applicationEnvironment } from '@venizia/ignis';
+
+if (applicationEnvironment.isDevelopment()) {
+  // Do something only in development
+}
+```
+
+## Configuration
+
+The prefix for the environment variables can be configured by setting the `APPLICATION_ENV_PREFIX` variable in your environment.
+
+**Example `.env` file:**
+
+```
+APPLICATION_ENV_PREFIX=MY_APP_ENV
+
+# Now, your application variables should use the new prefix
+MY_APP_ENV_SERVER_HOST=0.0.0.0
+MY_APP_ENV_SERVER_PORT=3000
+```

package/wiki/references/helpers/error.md

@@ -0,0 +1,80 @@
+# Error Helper
+
+Standardized error handling with consistent responses across the application.
+
+## Quick Reference
+
+| Class/Function | Purpose |
+|----------------|---------|
+| **ApplicationError** | Custom error class with `statusCode` and `messageCode` |
+| **getError()** | Utility to create `ApplicationError` instances |
+| **appErrorHandler** | Middleware catching and formatting errors |
+
+### Error Response Format
+
+| Environment | Includes |
+|-------------|----------|
+| **Production** | `message`, `statusCode`, `requestId` |
+| **Development** | Above + `stack`, `cause`, `url`, `path` |
+
+## `ApplicationError`
+
+Extends native `Error` with HTTP status codes and machine-readable message codes.
+
+### Creating an `ApplicationError`
+
+You can create a new `ApplicationError` with a message, status code, and an optional message code.
+
+```typescript
+import { ApplicationError, HTTP } from '@venizia/ignis';
+
+// Throw an error for a resource not found
+throw new ApplicationError({
+  message: 'User not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+  messageCode: 'USER_NOT_FOUND',
+});
+```
+
+### `getError()` Utility
+
+For convenience, you can use the `getError()` utility function to create `ApplicationError` instances.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis';
+
+throw getError({
+  message: 'Invalid credentials',
+  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+});
+```
+
+## Error Handling Middleware
+
+`Ignis` provides a default error handling middleware (`appErrorHandler`) that catches instances of `ApplicationError` (and other errors) and formats them into a consistent JSON response.
+
+In development mode, the response will include the stack trace and error cause for easier debugging. In production, these details are omitted.
+
+**Example Error Response (Production):**
+
+```json
+{
+  "message": "User not found",
+  "statusCode": 404,
+  "requestId": "some-request-id"
+}
+```
+
+**Example Error Response (Development):**
+
+```json
+{
+  "message": "User not found",
+  "statusCode": 404,
+  "requestId": "some-request-id",
+  "stack": "Error: User not found\n    at ...",
+  "cause": "...",
+  "url": "/api/users/123",
+  "path": "/api/users/123"
+}
+```

package/wiki/references/helpers/index.md

@@ -0,0 +1,21 @@
+# Helpers
+
+Reusable classes and functions providing common functionality - designed for easy injection and configuration.
+
+## Available Helpers
+
+| Helper | Purpose | Key Features |
+|--------|---------|--------------|
+| [Cron](./cron.md) | Job scheduling | Cron expressions, task management |
+| [Crypto](./crypto.md) | Cryptographic operations | Hashing, AES/RSA encryption/decryption |
+| [Environment](./env.md) | Environment variables | Centralized config access |
+| [Error](./error.md) | Error handling | `ApplicationError`, consistent responses |
+| [Inversion](./inversion.md) | Dependency injection | DI container implementation |
+| [Logger](./logger.md) | Logging | Winston-based, multiple transports, scopes |
+| [Network](./network.md) | Network requests | HTTP, TCP, UDP helpers |
+| [Queue](./queue.md) | Message queues | BullMQ, MQTT support |
+| [Redis](./redis.md) | Redis operations | Single/cluster, key-value, hashes, JSON, pub/sub |
+| [Socket.IO](./socket-io.md) | Real-time communication | Socket.IO client/server helpers |
+| [Storage](./storage.md) | File storage | In-memory, Minio object storage |
+| [Testing](./testing.md) | Test utilities | Test plan runner, base test classes |
+| [Worker Thread](./worker-thread.md) | Worker threads | Node.js worker management |

package/wiki/references/helpers/inversion.md

@@ -0,0 +1,141 @@
+# Inversion of Control (IoC) and Dependency Injection (DI)
+
+Core DI system enabling loosely coupled, testable, and extensible code.
+
+> **Package Architecture Note:** The core DI container functionality has been extracted to a standalone package `@venizia/ignis-inversion`. The `@venizia/ignis-helpers` package extends and re-exports this functionality with application-specific enhancements (logging, framework metadata). All imports from `@venizia/ignis-helpers` or `@venizia/ignis` continue to work as before - backward compatibility is maintained.
+
+## Quick Reference
+
+| Concept | Description |
+|---------|-------------|
+| **Container** | Central registry for services/dependencies (Application extends Container) |
+| **Binding** | Register class/value with container under a key |
+| **Injection** | Request dependency from container using `@inject` decorator |
+| **MetadataRegistry** | Stores decorator metadata for DI and routing |
+
+### Binding Methods
+
+| Method | Purpose | Example |
+|--------|---------|---------|
+| `app.service(MyService)` | Bind service | Key: `services.MyService` |
+| `app.controller(MyController)` | Bind controller | Key: `controllers.MyController` |
+| `app.repository(MyRepo)` | Bind repository | Key: `repositories.MyRepo` |
+| `bind().toClass()` | Custom class binding | `bind({ key: 'MyClass' }).toClass(MyClass)` |
+| `bind().toValue()` | Bind constant value | `bind({ key: 'API_KEY' }).toValue('secret')` |
+
+### Binding Scopes
+
+| Scope | Behavior |
+|-------|----------|
+| `BindingScopes.TRANSIENT` | New instance each request (default) |
+| `BindingScopes.SINGLETON` | Single instance, reused |
+
+### Injection Styles
+
+| Style | When to Use |
+|-------|-------------|
+| **Constructor Injection** | Recommended - explicit, available at instantiation |
+| **Property Injection** | Alternative - inject as class property |
+
+## Binding Dependencies
+
+Before a dependency can be injected, it must be bound to the container. The `Application` class provides helper methods for binding common resource types:
+
+-   `app.component(MyComponent)`
+-   `app.controller(MyController)`
+-   `app.service(MyService)`
+-   `app.repository(MyRepository)`
+-   `app.dataSource(MyDataSource)`
+
+These methods automatically create a binding for the class with a conventional key (e.g., `services.MyService`).
+
+### Advanced Binding
+
+For more advanced use cases, you can create custom bindings using the `bind` method on the container.
+
+```typescript
+// In your application class or a component's binding() method
+
+// Bind a class
+this.bind<MyCustomClass>({ key: 'MyCustomClass' }).toClass(MyCustomClass);
+
+// Bind a constant value
+this.bind<string>({ key: 'API_KEY' }).toValue('my-secret-api-key');
+
+// Bind a provider (for complex creation logic)
+this.bind<DatabaseConnection>({ key: 'DatabaseConnection' }).toProvider(() => {
+  return new DatabaseConnection(process.env.DATABASE_URL);
+});
+```
+
+### Binding Scopes
+
+You can control the lifecycle of a bound dependency using scopes:
+
+-   `BindingScopes.TRANSIENT` (default): A new instance is created every time the dependency is requested.
+-   `BindingScopes.SINGLETON`: A single instance is created and reused for all subsequent requests.
+
+```typescript
+this.bind<MySingletonService>({ key: 'services.MySingletonService' })
+  .toClass(MySingletonService)
+  .setScope(BindingScopes.SINGLETON);
+```
+
+## Injecting Dependencies
+
+`Ignis` provides an `@inject` decorator to handle dependency injection. You can use it on constructor parameters or class properties.
+
+### Constructor Injection
+
+This is the recommended way to inject dependencies, as it makes them explicit and ensures they are available when the class is instantiated.
+
+```typescript
+import { BaseController, controller, inject } from '@venizia/ignis';
+import { UserService } from '../services/user.service';
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+  constructor(
+    @inject({ key: 'services.UserService' }) private userService: UserService
+  ) {
+    super({ scope: UserController.name, path: '/users' });
+  }
+
+  // ... use this.userService
+}
+```
+
+### Property Injection
+
+You can also inject dependencies as class properties.
+
+```typescript
+import { BaseController, controller, inject } from '@venizia/ignis';
+import { UserService } from '../services/user.service';
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+  @inject({ key: 'services.UserService' })
+  private userService: UserService;
+
+  constructor() {
+    super({ scope: UserController.name, path: '/users' });
+  }
+
+  // ... use this.userService
+}
+```
+
+## `MetadataRegistry`
+
+The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a singleton class responsible for storing and retrieving all the metadata attached by decorators like `@inject`, `@controller`, `@get`, etc.
+
+-   **Base File:** `packages/inversion/src/registry.ts` (core MetadataRegistry)
+-   **Extended File:** `packages/helpers/src/helpers/inversion/registry.ts` (with framework metadata)
+
+### Role in DI
+
+-   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
+-   When the `Container` instantiates a class, it queries the `MetadataRegistry` to find out which dependencies need to be injected and where.
+
+You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.

package/wiki/references/helpers/logger.md

@@ -0,0 +1,98 @@
+# Logger Helper
+
+Powerful, flexible logging built on Winston - supports multiple transports, log levels, and hierarchical scopes.
+
+## Quick Reference
+
+| Feature | Description |
+|---------|-------------|
+| **Factory Method** | `LoggerFactory.getLogger(['scope1', 'scope2'])` |
+| **Log Levels** | `error`, `alert`, `emerg`, `warn`, `info`, `http`, `verbose`, `debug`, `silly` |
+| **Transports** | Console (default), DailyRotateFile, UDP/Dgram |
+| **Scopes** | Hierarchical context tracking (e.g., `['MyService', 'MyMethod']`) |
+
+### Common Methods
+
+```typescript
+logger.info('message');      // Informational
+logger.error('message');     // Error
+logger.warn('message');      // Warning
+logger.debug('message');     // Debug
+```
+
+## Getting a Logger Instance
+
+The recommended way to get a logger instance is by using the `LoggerFactory`.
+
+```typescript
+import { LoggerFactory } from '@venizia/ignis';
+
+const logger = LoggerFactory.getLogger(['MyService']);
+
+logger.info('This is an informational message.');
+logger.error('This is an error message.');
+```
+
+### Scopes
+
+You can provide an array of scopes to the `getLogger` method to create a hierarchical logger. This is useful for identifying the source of log messages.
+
+```typescript
+const logger = LoggerFactory.getLogger(['MyService', 'MyMethod']);
+logger.info('This message is from MyService-MyMethod');
+```
+
+## Configuration
+
+The logger is configured through environment variables and the `defineCustomLogger` function, which sets up the `winston` instance.
+
+### Log Levels
+
+The logger supports the following log levels (from highest to lowest priority): `error`, `alert`, `emerg`, `warn`, `info`, `http`, `verbose`, `debug`, `silly`.
+
+### Transports
+
+`Ignis` comes with three main types of transports:
+
+1.  **Console:** Logs messages to the console. Enabled by default.
+2.  **DailyRotateFile:** Logs messages to files that are rotated on a daily or hourly basis.
+3.  **Dgram (UDP):** Sends log messages over UDP to a remote log aggregation service.
+
+### Environment Variables for Configuration
+
+-   `APP_ENV_LOGGER_FOLDER_PATH`: The directory to store log files.
+-   `APP_ENV_APPLICATION_NAME`: Used as a prefix for log files and as a label in log messages.
+-   `APP_ENV_LOGGER_DGRAM_HOST`: The host for the UDP log transport.
+-   `APP_ENV_LOGGER_DGRAM_PORT`: The port for the UDP log transport.
+-   `APP_ENV_LOGGER_DGRAM_LABEL`: A label to identify the source of UDP logs.
+-   `APP_ENV_LOGGER_DGRAM_LEVELS`: A comma-separated list of log levels to be sent via UDP (e.g., `error,warn,info`).
+
+**Example `.env` file:**
+
+```
+APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
+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,debug
+```
+
+## Custom Logger
+
+While the default logger is powerful, you can create your own custom logger by extending the `Logger` class and providing a custom `winston.Logger` instance.
+
+```typescript
+import { Logger, defineCustomLogger, applicationLogFormatter } from '@venizia/ignis';
+import winston from 'winston';
+
+const myCustomWinstonLogger = defineCustomLogger({
+  loggerFormatter: applicationLogFormatter,
+  transports: {
+    info: { file: { prefix: 'my-app', folder: './logs' } },
+    error: { file: { prefix: 'my-app-error', folder: './logs' } },
+  },
+});
+
+const myLogger = new Logger({ customLogger: myCustomWinstonLogger });
+myLogger.withScope('CustomScope').info('This is a custom log message.');
+```

package/wiki/references/helpers/network.md

@@ -0,0 +1,143 @@
+# Network Helper
+
+Comprehensive network communication utilities for HTTP, TCP, and UDP protocols.
+
+## 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 |
+|--------|---------|
+| `get({ url })` | GET request |
+| `post({ url, data })` | POST request |
+| `put({ url, data })` | PUT request |
+| `delete({ url })` | DELETE request |
+
+### TCP Operations
+
+| Class | Methods |
+|-------|---------|
+| **Client** | `connect()`, `emit({ payload })`, `disconnect()` |
+| **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 as underlying clients.
+
+### Creating an HTTP Client
+
+You can create a new HTTP client instance by extending either `AxiosNetworkRequest` or `NodeFetchNetworkRequest`.
+
+**Using Axios:**
+
+```typescript
+import { AxiosNetworkRequest } from '@venizia/ignis';
+
+class MyApiClient extends AxiosNetworkRequest {
+  constructor() {
+    super({
+      name: 'MyApiClient',
+      networkOptions: {
+        baseUrl: 'https://api.example.com',
+        timeout: 5000,
+        headers: {
+          'X-Custom-Header': 'MyValue',
+        },
+      },
+    });
+  }
+
+  async getUsers() {
+    const response = await this.getNetworkService().get({ url: '/users' });
+    return response.data;
+  }
+}
+```
+
+**Using Node.js Fetch:**
+
+```typescript
+import { NodeFetchNetworkRequest } from '@venizia/ignis';
+
+class MyApiClient extends NodeFetchNetworkRequest {
+  constructor() {
+    super({
+      name: 'MyApiClient',
+      networkOptions: {
+        baseUrl: 'https://api.example.com',
+        timeout: 5000,
+      },
+    });
+  }
+
+  async getUsers() {
+    const response = await this.getNetworkService().get({ url: '/users' });
+    return response.json();
+  }
+}
+```
+
+## TCP Socket
+
+The TCP Socket helpers provide a robust way to create and manage TCP and TLS/SSL connections.
+
+### TCP Client
+
+```typescript
+import { NetworkTcpClient } from '@venizia/ignis';
+
+const tcpClient = new NetworkTcpClient({
+  identifier: 'my-tcp-client',
+  options: { host: 'localhost', port: 8080 },
+  reconnect: true,
+  onData: ({ message }) => {
+    console.log('Received data:', message.toString());
+  },
+});
+
+tcpClient.connect({ resetReconnectCounter: true });
+tcpClient.emit({ payload: 'Hello, Server!' });
+```
+
+### TCP Server
+
+```typescript
+import { NetworkTcpServer } from '@venizia/ignis';
+
+const tcpServer = new NetworkTcpServer({
+  identifier: 'my-tcp-server',
+  listenOptions: { port: 8080 },
+  authenticateOptions: { required: false },
+  onClientData: ({ id, data }) => {
+    console.log(`Received data from client ${id}:`, data.toString());
+  },
+});
+```
+
+## UDP Socket
+
+The UDP Socket helper provides a way to create and manage UDP datagram sockets.
+
+### UDP Client
+
+```typescript
+import { NetworkUdpClient } from '@venizia/ignis';
+
+const udpClient = new NetworkUdpClient({
+  identifier: 'my-udp-client',
+  port: 8081,
+  onData: ({ message, remoteInfo }) => {
+    console.log(`Received message from ${remoteInfo.address}:${remoteInfo.port}:`, message.toString());
+  },
+});
+
+udpClient.connect();
+```