@venizia/ignis-docs 0.0.1-1

package/wiki/references/helpers/queue.md

@@ -0,0 +1,131 @@
+# Queue Helpers
+
+Message queuing and asynchronous task management with BullMQ, MQTT, and in-memory solutions.
+
+## Quick Reference
+
+| Helper | Type | Use Case | Backed By |
+|--------|------|----------|-----------|
+| **BullMQHelper** | Redis-backed job queue | Background job processing, task queue | BullMQ + Redis |
+| **MQTTClientHelper** | Message broker | Real-time messaging, IoT | MQTT broker |
+| **QueueHelper** | In-memory queue | Sequential tasks, single process | Memory |
+
+### BullMQHelper Roles
+
+| Role | Purpose | Key Property |
+|------|---------|--------------|
+| `worker` | Process jobs (consumer) | `onWorkerData`, `onWorkerDataCompleted` |
+| `queue` | Add jobs (producer) | `queue.add(name, data)` |
+
+### Common Operations
+
+| Helper | Subscribe/Consume | Publish/Produce |
+|--------|-------------------|-----------------|
+| **BullMQ** | Create worker role | `queue.add()` |
+| **MQTT** | `subscribe({ topics })` | `publish({ topic, message })` |
+| **In-Memory** | `new QueueHelper({ onMessage })` | `enqueue(payload)` |
+
+## BullMQ Helper
+
+The `BullMQHelper` provides a robust, Redis-backed message queuing system using the [BullMQ](https://docs.bullmq.io/) library. It's ideal for background job processing and can be configured to act as a job producer (queue) or a job consumer (worker).
+
+### Creating a BullMQ Worker
+
+To process jobs, you create a `BullMQHelper` with the `worker` role.
+
+```typescript
+import { BullMQHelper, RedisHelper } from '@venizia/ignis';
+
+const redisConnection = new RedisHelper({
+  name: 'redis-queue',
+  host: 'localhost',
+  port: 6379,
+  password: 'password',
+});
+
+const myWorker = new BullMQHelper({
+  queueName: 'my-email-queue',
+  identifier: 'email-worker',
+  role: 'worker',
+  connection: redisConnection.getClient(),
+  onWorkerData: async (job) => {
+    console.log(`Sending email to ${job.data.email}`);
+    // ... email sending logic
+    return { status: 'ok' };
+  },
+  onWorkerDataCompleted: async (job, result) => {
+    console.log(`Job ${job.id} completed with result:`, result);
+  },
+});
+```
+
+### Creating a BullMQ Queue (Producer)
+
+To add jobs to the queue, you create a `BullMQHelper` with the `queue` role.
+
+```typescript
+import { BullMQHelper, RedisHelper } from '@venizia/ignis';
+
+const redisConnection = new RedisHelper({
+    name: 'redis-queue',
+    host: 'localhost',
+    port: 6379,
+    password: 'password',
+});
+
+const myQueue = new BullMQHelper({
+  queueName: 'my-email-queue',
+  identifier: 'email-queue',
+  role: 'queue',
+  connection: redisConnection.getClient(),
+});
+
+// Add a job to the queue
+myQueue.queue.add('send-welcome-email', { email: 'test@example.com' });
+```
+
+## MQTT Helper
+
+The `MQTTClientHelper` provides an interface for interacting with an MQTT broker, allowing you to publish and subscribe to topics for real-time messaging.
+
+```typescript
+import { MQTTClientHelper } from '@venizia/ignis';
+
+const mqttClient = new MQTTClientHelper({
+  identifier: 'my-mqtt-client',
+  url: 'mqtt://localhost:1883',
+  options: {
+    username: 'user',
+    password: 'password',
+  },
+  onMessage: ({ topic, message }) => {
+    console.log(`Received message on topic ${topic}:`, message.toString());
+  },
+});
+
+// Subscribe to a topic
+mqttClient.subscribe({ topics: ['my-topic'] });
+
+// Publish a message
+mqttClient.publish({ topic: 'my-topic', message: 'Hello, MQTT!' });
+```
+
+## In-Memory Queue Helper
+
+The `QueueHelper` provides a simple, in-memory queue for managing sequential tasks within a single application instance. It's useful when you don't need the overhead of an external message broker.
+
+```typescript
+import { QueueHelper } from '@venizia/ignis';
+
+const myQueue = new QueueHelper<string>({
+  identifier: 'my-in-memory-queue',
+  onMessage: async ({ queueElement }) => {
+    console.log('Processing message:', queueElement.payload);
+    // Simulate some work
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  },
+});
+
+myQueue.enqueue('message 1');
+myQueue.enqueue('message 2');
+```

package/wiki/references/helpers/redis.md

@@ -0,0 +1,121 @@
+# Redis Helper
+
+Powerful Redis abstraction supporting single instances and clusters via `ioredis`.
+
+## Quick Reference
+
+| Helper Class | Use Case |
+|--------------|----------|
+| **RedisHelper** | Single Redis instance |
+| **RedisClusterHelper** | Redis cluster |
+| **DefaultRedisHelper** | Base class with unified API |
+
+### Supported Operations
+
+| Operation | Methods |
+|-----------|---------|
+| **Key-Value** | `set()`, `get()`, `getObject()`, `del()` |
+| **Hashes** | `hset()`, `hget()`, `hgetall()` |
+| **JSON** (RedisJSON) | `jSet()`, `jGet()` (requires RedisJSON module) |
+| **Pub/Sub** | `subscribe()`, `publish()`, `unsubscribe()` |
+| **TTL** | Set expiration on keys |
+
+## Creating a Redis Client
+
+### Single Instance
+
+Use the `RedisHelper` for connecting to a single Redis instance.
+
+```typescript
+import { RedisHelper } from '@venizia/ignis';
+
+const redisClient = new RedisHelper({
+  name: 'my-redis-client',
+  host: 'localhost',
+  port: 6379,
+  password: 'password',
+  autoConnect: true,
+  maxRetry: 5,
+});
+```
+
+### Redis Cluster
+
+Use the `RedisClusterHelper` for connecting to a Redis cluster.
+
+```typescript
+import { RedisClusterHelper } from '@venizia/ignis';
+
+const redisClusterClient = new RedisClusterHelper({
+  name: 'my-redis-cluster',
+  nodes: [
+    { host: 'localhost', port: 7000 },
+    { host: 'localhost', port: 7001 },
+    // ... other nodes
+  ],
+});
+```
+
+## Basic Operations
+
+The helper provides methods for common Redis commands.
+
+### Key-Value
+
+```typescript
+// Set a value
+await redisClient.set({ key: 'mykey', value: { a: 1, b: 2 } });
+
+// Get a value
+const value = await redisClient.getObject({ key: 'mykey' });
+// => { a: 1, b: 2 }
+
+// Delete a key
+await redisClient.del({ keys: ['mykey'] });
+```
+
+### Hashes
+
+```typescript
+// Set hash fields
+await redisClient.hset({ key: 'myhash', value: { field1: 'hello', field2: 'world' } });
+
+// Get all hash fields
+const hash = await redisClient.hgetall({ key: 'myhash' });
+// => { field1: 'hello', field2: 'world' }
+```
+
+## RedisJSON
+
+If your Redis server has the RedisJSON module installed, you can use the `j*` methods to work with JSON documents.
+
+```typescript
+// Set a JSON document
+await redisClient.jSet({ key: 'mydoc', path: '$', value: { a: { b: 1 } } });
+
+// Get a part of the document
+const result = await redisClient.jGet({ key: 'mydoc', path: '$.a.b' });
+// => [1]
+```
+
+## Pub/Sub
+
+The helper also supports Redis Pub/Sub for real-time messaging.
+
+```typescript
+// Subscribe to a topic
+redisClient.subscribe({ topic: 'my-channel' });
+
+// Listen for messages (in a separate part of your app)
+redisClient.getClient().on('message', (channel, message) => {
+  if (channel === 'my-channel') {
+    console.log('Received message:', JSON.parse(message));
+  }
+});
+
+// Publish a message
+await redisClient.publish({
+  topics: ['my-channel'],
+  payload: { data: 'some important update' },
+});
+```

package/wiki/references/helpers/socket-io.md

@@ -0,0 +1,103 @@
+# Socket.IO Helper
+
+Structured Socket.IO client and server management for real-time bidirectional communication.
+
+## Quick Reference
+
+| Helper | Type | Features |
+|--------|------|----------|
+| **SocketIOServerHelper** | Server | Auth flow, room management, Redis scaling |
+| **SocketIOClientHelper** | Client | Structured API, event subscription |
+
+### SocketIOServerHelper Features
+
+| Feature | Description |
+|---------|-------------|
+| **Redis Integration** | `@socket.io/redis-adapter` (scaling), `@socket.io/redis-emitter` (broadcasting) |
+| **Authentication** | Built-in flow - clients emit `authenticate` event |
+| **Client Management** | Track connections and auth state |
+| **Room Management** | Group clients for targeted messaging |
+
+### Common Operations
+
+| Helper | Method | Purpose |
+|--------|--------|---------|
+| **Server** | `send({ destination, payload })` | Send message to room/socket |
+| **Server** | `broadcast({ payload })` | Broadcast to all clients |
+| **Client** | `connect()` | Connect to server |
+| **Client** | `emit({ topic, ...data })` | Emit event |
+| **Client** | `subscribe({ events })` | Subscribe to events |
+
+### Usage
+
+The `SocketIOServerHelper` is typically instantiated and managed by the `SocketIOComponent`. To use it, you need to provide the necessary configurations and handlers when you register the component. See the [Socket.IO Component documentation](../components/socket-io.md) for details on how to set it up.
+
+Once configured, you can inject the `SocketIOServerHelper` instance into your services or controllers to emit events.
+
+```typescript
+import { SocketIOServerHelper, SocketIOBindingKeys, inject } from '@venizia/ignis';
+
+// ... in a service or controller
+
+  @inject({ key: SocketIOBindingKeys.SOCKET_IO_INSTANCE })
+  private io: SocketIOServerHelper;
+
+  sendNotification(userId: string, message: string) {
+    this.io.send({
+      destination: userId, // Room or socket ID
+      payload: {
+        topic: 'notification',
+        data: { message },
+      },
+    });
+  }
+```
+
+## `SocketIOClientHelper`
+
+The `SocketIOClientHelper` provides a structured API for managing client-side Socket.IO connections.
+
+### Creating a Socket.IO Client
+
+```typescript
+import { SocketIOClientHelper } from '@venizia/ignis';
+
+const socketClient = new SocketIOClientHelper({
+  identifier: 'my-socket-client',
+  host: 'http://localhost:3000',
+  options: {
+    path: '/io', // Path to the Socket.IO server
+    extraHeaders: {
+      Authorization: 'Bearer my-jwt-token',
+    },
+    auth: {
+      token: 'my-jwt-token',
+    }
+  },
+});
+
+socketClient.connect();
+```
+
+### Subscribing to Events
+
+```typescript
+socketClient.subscribe({
+  events: {
+    connect: () => {
+      console.log('Connected to Socket.IO server!');
+      // Authenticate with the server
+      socketClient.emit({ topic: 'authenticate' });
+    },
+    authenticated: (data) => {
+      console.log('Successfully authenticated:', data);
+    },
+    notification: (data) => {
+      console.log('Received notification:', data);
+    },
+    disconnect: () => {
+      console.log('Disconnected from server.');
+    },
+  },
+});
+```

package/wiki/references/helpers/storage.md

@@ -0,0 +1,130 @@
+# Storage Helpers
+
+In-memory and external object storage solutions.
+
+## Quick Reference
+
+| Helper | Type | Use Case |
+|--------|------|----------|
+| **MemoryStorageHelper** | In-memory key-value | Caching, temporary state, single-process data |
+| **MinioHelper** | S3-compatible object storage | File uploads, persistent storage, MinIO/S3 |
+
+### MemoryStorageHelper Methods
+
+| Method | Purpose |
+|--------|---------|
+| `set(key, value)` | Store value |
+| `get<T>(key)` | Retrieve value |
+| `isBound(key)` | Check if key exists |
+| `keys()` | Get all keys |
+| `clear()` | Clear all data |
+
+### MinioHelper Operations
+
+| Operation | Methods |
+|-----------|---------|
+| **Bucket** | `createBucket()`, `isBucketExists()`, `removeBucket()` |
+| **Upload** | `upload({ bucket, files })` |
+| **Download** | `getFile({ bucket, name })` |
+| **Delete** | `removeObject()`, `removeObjects()` |
+
+## `MemoryStorageHelper`
+
+The `MemoryStorageHelper` is a simple in-memory key-value store. It's useful for caching, storing temporary application state, or passing data between loosely coupled parts of your application within a single process.
+
+### Creating an Instance
+
+```typescript
+import { MemoryStorageHelper } from '@venizia/ignis';
+
+const memoryStore = new MemoryStorageHelper();
+```
+
+### Usage
+
+```typescript
+// Set a value
+memoryStore.set('my-key', { a: 1, b: 2 });
+
+// Get a value
+const value = memoryStore.get<{ a: number; b: number }>('my-key');
+// => { a: 1, b: 2 }
+
+// Check if a key exists
+const hasKey = memoryStore.isBound('my-key');
+// => true
+
+// Get all keys
+const allKeys = memoryStore.keys();
+// => ['my-key']
+
+// Clear the storage
+memoryStore.clear();
+```
+
+## `MinioHelper`
+
+The `MinioHelper` is a comprehensive client for interacting with MinIO or any S3-compatible object storage service.
+
+### Creating a MinIO Client
+
+```typescript
+import { MinioHelper } from '@venizia/ignis';
+
+const minioClient = new MinioHelper({
+  endPoint: 'localhost',
+  port: 9000,
+  useSSL: false,
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin',
+});
+```
+
+### Bucket Operations
+
+```typescript
+// Create a bucket if it doesn't exist
+const bucketName = 'my-bucket';
+const bucketExists = await minioClient.isBucketExists({ name: bucketName });
+if (!bucketExists) {
+  await minioClient.createBucket({ name: bucketName });
+}
+```
+
+### Object Operations
+
+#### Uploading a File
+
+The `upload` method takes an array of file objects, typically from a multipart form data request.
+
+```typescript
+// Assuming `files` is an array of IUploadFile objects from a request
+const uploadResult = await minioClient.upload({
+  bucket: 'my-bucket',
+  files: files,
+});
+// => [{ bucket: 'my-bucket', fileName: '...', link: '...' }]
+```
+
+#### Getting an Object
+
+The `getFile` method returns a `Readable` stream for an object.
+
+```typescript
+const fileStream = await minioClient.getFile({
+  bucket: 'my-bucket',
+  name: 'my-file.txt',
+});
+
+fileStream.pipe(process.stdout);
+```
+
+#### Removing Objects
+
+```typescript
+// Remove a single object
+await minioClient.removeObject({ bucket: 'my-bucket', name: 'my-file.txt' });
+
+// Remove multiple objects
+await minioClient.removeObjects({ bucket: 'my-bucket', names: ['file1.txt', 'file2.txt'] });
+```

package/wiki/references/helpers/testing.md

@@ -0,0 +1,115 @@
+# Testing Helper
+
+Structured test framework integrating with Node.js's native `node:test` module.
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| **TestPlan** | Organizes test suite with lifecycle hooks and shared context |
+| **TestCase** | Single runnable test unit with metadata |
+| **TestCaseHandler** | Encapsulates test execution and validation logic |
+| **TestDescribe** | Runs test plans |
+
+### Test Lifecycle Hooks
+
+| Hook | When | Purpose |
+|------|------|---------|
+| `before` | Before all tests | Setup (e.g., start server, seed DB) |
+| `after` | After all tests | Cleanup (e.g., close connections) |
+| `beforeEach` | Before each test | Reset state |
+| `afterEach` | After each test | Cleanup per test |
+
+### TestCaseDecisions
+
+| Decision | Meaning |
+|----------|---------|
+| `SUCCESS` | Test passed |
+| `FAIL` | Test failed |
+| `SKIP` | Test skipped |
+
+## Creating a Test Plan
+
+A test plan is the main entry point for a test suite. You define the scope, hooks, and test cases within the plan.
+
+```typescript
+// __tests__/my-feature.test.ts
+import { TestPlan, TestDescribe, TestCase, TestCaseHandler, TestCaseDecisions } from '@venizia/ignis';
+
+// 1. Define a Test Case Handler
+class MyTestHandler extends TestCaseHandler {
+  async execute() {
+    // Perform the action to be tested
+    return { result: 'some-value' };
+  }
+
+  getValidator() {
+    return (opts: { result: string }) => {
+      if (opts.result === 'some-value') {
+        return TestCaseDecisions.SUCCESS;
+      }
+      return TestCaseDecisions.FAIL;
+    };
+  }
+}
+
+// 2. Create a Test Plan
+const myTestPlan = TestPlan.newInstance({
+  scope: 'My Feature',
+  hooks: {
+    before: async () => console.log('Starting My Feature tests...'),
+    after: async () => console.log('Finished My Feature tests.'),
+  },
+  testCases: [
+    TestCase.withOptions({
+      code: 'MY-FEATURE-001',
+      description: 'It should return the correct value',
+      expectation: 'The result should be "some-value"',
+      handler: new MyTestHandler({ context: {} as any }), // Context is provided by the plan
+    }),
+  ],
+});
+
+// 3. Run the Test Plan
+TestDescribe.withTestPlan({ testPlan: myTestPlan }).run();
+```
+
+## Shared Context
+
+The `TestPlan` provides a `context` that can be used to share data between test cases and hooks. This is useful for setup tasks like creating a JWT token or seeding a database.
+
+```typescript
+// __tests__/auth.test.ts
+import { TestPlan, TestDescribe, TestCase, TestCaseHandler, ITestContext } from '@venizia/ignis';
+
+// A handler that uses the context
+class SecureApiHandler extends TestCaseHandler<{ token: string }> {
+  async execute() {
+    const token = this.context.getSync<{ token: string }>({ key: 'token' });
+    const response = await app.request('/api/secure-data', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    return { status: response.status };
+  }
+  // ... validator
+}
+
+const authTestPlan = TestPlan.newInstance({
+  scope: 'Authentication',
+  hooks: {
+    before: async (context: ITestContext<{ token: string }>) => {
+      // Generate a token and bind it to the context
+      const token = await generateTestToken();
+      context.bind({ key: 'token', value: token });
+    },
+  },
+  testCases: [
+    TestCase.withOptions({
+      // ...
+      handler: new SecureApiHandler({ context: {} as any }),
+    }),
+  ],
+});
+
+TestDescribe.withTestPlan({ testPlan: authTestPlan }).run();
+```