@venizia/ignis-docs 0.0.1-1

package/wiki/references/components/health-check.md

@@ -0,0 +1,190 @@
+# Health Check Component
+
+Simple endpoint for monitoring application health - essential for microservices and containerized deployments.
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| **HealthCheckComponent** | Registers health check controller |
+| **HealthCheckController** | Provides health check routes |
+
+### Default Endpoints
+
+| Method | Path | Purpose | Response |
+|--------|------|---------|----------|
+| `GET` | `/health` | Basic health check | `{ "status": "ok" }` |
+| `POST` | `/health/ping` | Echo test | `{ "type": "PONG", "date": "...", "message": "..." }` |
+
+### Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `restOptions.path` | `/health` | Base path for health endpoints |
+
+## Architecture Components
+
+-   **`HealthCheckComponent`**: Registers `HealthCheckController`
+-   **`HealthCheckController`**: Uses decorators (`@api`) to define routes
+-   **Self-contained**: No external dependencies required
+
+## Implementation Details
+
+### Tech Stack
+
+-   **Hono**
+-   **`@hono/zod-openapi`**
+
+### Configuration
+
+The health check endpoint path can be configured by binding a custom `IHealthCheckOptions` object to the `HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS` key in the DI container.
+
+**Default options:**
+
+```typescript
+const DEFAULT_OPTIONS: IHealthCheckOptions = {
+  restOptions: { path: '/health' },
+};
+```
+
+#### Customizing the Health Check Path
+
+In your `src/application.ts`, you can bind your custom options:
+
+```typescript
+import { HealthCheckBindingKeys, IHealthCheckOptions, HealthCheckComponent } from '@venizia/ignis';
+
+// ... in your Application class's preConfigure method
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.bind<IHealthCheckOptions>({
+      key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS,
+    }).toValue({
+      restOptions: { path: '/health-check' },
+    });
+    this.component(HealthCheckComponent);
+    // ...
+  }
+```
+
+### Code Samples
+
+#### Controller Implementation
+
+The `HealthCheckController` is a simple controller that uses decorators to define its routes. It now includes a `GET /` for a simple status check and a `POST /ping` that echoes a message.
+
+```typescript
+// packages/core/src/components/health-check/controller.ts
+import { BaseController, IControllerOptions, TRouteContext, api, jsonContent, jsonResponse, HTTP, z } from '@venizia/ignis';
+
+const ROUTE_CONFIGS = {
+  '/': {
+    method: HTTP.Methods.GET,
+    path: '/',
+    responses: jsonResponse({
+      schema: z.object({ status: z.string() }).openapi({
+        description: 'HealthCheck Schema',
+        examples: [{ status: 'ok' }],
+      }),
+      description: 'Health check status',
+    }),
+  },
+  '/ping': {
+    method: HTTP.Methods.POST,
+    path: '/ping',
+    request: {
+      body: jsonContent({
+        description: 'PING | Request body',
+        schema: z.object({
+          type: z.string().optional().default('PING'),
+          message: z.string().min(1).max(255),
+        }),
+      }),
+    },
+    responses: jsonResponse({
+      schema: z
+        .object({
+          type: z.string().optional().default('PONG'),
+          date: z.iso.datetime(),
+          message: z.string(),
+        })
+        .openapi({
+          description: 'HealthCheck PingPong Schema',
+          examples: [{ date: new Date().toISOString(), message: 'ok' }],
+        }),
+      description: 'HealthCheck PingPong Message',
+    }),
+  },
+} as const;
+
+@controller({ path: '/health' }) // Base path is configured by options
+export class HealthCheckController extends BaseController {
+  constructor(opts: IControllerOptions) {
+    super({ ...opts, scope: HealthCheckController.name });
+    // Note: This is optional declare internal controller route definitions
+    this.definitions = ROUTE_CONFIGS;
+  }
+
+  @api({ configs: ROUTE_CONFIGS['/'] })
+  checkHealth(c: TRouteContext<typeof ROUTE_CONFIGS['/']>) {
+    return c.json({ status: 'ok' });
+  }
+
+  @api({ configs: ROUTE_CONFIGS['/ping'] })
+  pingPong(c: TRouteContext<typeof ROUTE_CONFIGS['/ping']>) {
+    // context.req.valid('json') is automatically typed as { type?: string, message: string }
+    const { message } = c.req.valid('json');
+
+    // Return type is automatically validated against the response schema
+    return c.json(
+      { type: 'PONG', date: new Date().toISOString(), message },
+      HTTP.ResultCodes.RS_2.Ok,
+    );
+  }
+}
+```
+
+#### Registering the Health Check Component
+
+In your `src/application.ts`, simply register the `HealthCheckComponent`.
+
+```typescript
+// src/application.ts
+import { HealthCheckComponent } from '@venizia/ignis';
+
+// ... in your Application class's preConfigure method
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.component(HealthCheckComponent);
+    // ...
+  }
+```
+
+## API or Interface Specifications
+
+-   **Endpoint:** `GET /health` (or the custom path you configured)
+-   **Method:** `GET`
+-   **Success Response (200 OK):**
+    ```json
+    {
+      "status": "ok"
+    }
+    ```
+-   **Endpoint:** `POST /health/ping`
+-   **Method:** `POST`
+-   **Request Body:**
+    ```json
+    {
+      "message": "Any string here"
+    }
+    ```
+-   **Success Response (200 OK):**
+    ```json
+    {
+      "type": "PONG",
+      "date": "YYYY-MM-DDTHH:mm:ss.sssZ",
+      "message": "Any string here"
+    }
+    ```
+
+This component provides a simple and effective way to monitor the health of your `Ignis` application.

package/wiki/references/components/index.md

@@ -0,0 +1,61 @@
+# Components
+
+Reusable, pluggable modules that encapsulate specific features in Ignis applications.
+
+## Built-in Components
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| [Authentication](./authentication.md) | JWT-based auth | Token generation, protected routes, user payload |
+| [Health Check](./health-check.md) | Monitoring endpoint | `/health` endpoint, ping/pong functionality |
+| [Swagger](./swagger.md) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
+| [Socket.IO](./socket-io.md) | Real-time communication | WebSocket support, Redis adapter, event-based |
+
+## Creating a Component
+
+To create a new component, you need to create a class that extends `BaseComponent`.
+
+```typescript
+import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise } from '@venizia/ignis';
+
+export class MyCustomComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
+  ) {
+    super({ scope: MyCustomComponent.name });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    // This is where you bind your component's resources.
+    this.application.service(MyCustomService);
+    this.application.controller(MyCustomController);
+  }
+}
+```
+
+## Component Lifecycle
+
+| Phase | When | Purpose |
+|-------|------|---------|
+| **`constructor()`** | Component instantiation | Receive dependencies, define default bindings |
+| **`binding()`** | Application startup | Register controllers, services, repositories with DI container |
+
+## Registering a Component
+
+To use a component, you need to register it with the application instance, usually in the `preConfigure` method of your `Application` class.
+
+```typescript
+// in src/application.ts
+import { MyCustomComponent } from './components/my-custom.component';
+
+// ... inside your Application class
+
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.component(MyCustomComponent);
+  }
+```
+
+When the application starts, it will automatically call the `binding()` method of the registered component, setting up all the resources it provides.
+
+Using components is a great way to organize your application's features into modular, reusable pieces of code, keeping your main application class clean and focused on high-level configuration.

package/wiki/references/components/request-tracker.md

@@ -0,0 +1,35 @@
+# Request Tracker Component
+
+The Request Tracker component logs incoming requests and adds a unique request ID for tracing purposes.
+
+## Overview
+
+-   **Feature Name:** Request Tracker
+-   **Purpose:** To log incoming requests and add a unique request ID for tracing purposes.
+-   **Background:** In a production environment, it is crucial to have detailed logs for debugging and monitoring. The Request Tracker component provides a way to automatically log every incoming request with a unique ID, making it easier to trace the entire lifecycle of a request.
+-   **Related Features/Modules:** This component is a default middleware that is registered at the application level and integrates with the core logging feature.
+
+## Design and Architecture
+
+-   **`RequestTrackerComponent`:** This component registers the `RequestSpyMiddleware`.
+-   **`RequestSpyMiddleware`:** A middleware that intercepts incoming requests, logs them, and adds a request ID to the context. It uses the `requestId` middleware from `hono/request-id` to generate the unique ID.
+
+## Implementation Details
+
+### Tech Stack
+
+-   **Hono**
+-   **`hono/request-id`**
+
+### Configuration
+
+The `RequestTrackerComponent` is enabled by default in `BaseApplication` and requires no manual registration or configuration. It is automatically registered as part of the application's default middleware stack during the `initialize()` lifecycle step.
+
+When the component is active, it adds the `requestId` and `RequestSpyMiddleware` to the Hono application instance. A sample log output for a request would look like this:
+
+```
+[spy][<request-id>] START | Handling Request | forwardedIp: 127.0.0.1 | path: /hello | method: GET
+[spy][<request-id>] DONE  | Handling Request | forwardedIp: 127.0.0.1 | path: /hello | method: GET | Took: 1.234 (ms)
+```
+
+This feature is essential for building production-ready applications with proper logging and traceability.

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

@@ -0,0 +1,127 @@
+# Socket.IO Component
+
+Real-time, bidirectional, event-based communication using Socket.IO.
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| **SocketIOComponent** | Sets up Socket.IO server and bindings |
+| **SocketIOServerHelper** | Encapsulates Socket.IO server instance |
+| **Redis Adapter** | Enables horizontal scaling with Redis |
+| **Redis Emitter** | Emit events from other processes/services |
+
+### Required Bindings
+
+| Binding Key | Type | Purpose |
+|-------------|------|---------|
+| `SERVER_OPTIONS` | `ISocketIOOptions` | Socket.IO server configuration (optional) |
+| `REDIS_CONNECTION` | `DefaultRedisHelper` | Redis instance for scaling |
+| `AUTHENTICATE_HANDLER` | `Function` | Authenticate socket connections |
+| `CLIENT_CONNECTED_HANDLER` | `Function` | Handle successful connections (optional) |
+
+### Use Cases
+
+- Live notifications
+- Real-time chat
+- Collaborative editing
+- Live data streams
+
+## Architecture Components
+
+-   **`SocketIOComponent`**: Sets up Socket.IO server, binds `SocketIOServerHelper` to DI
+-   **`SocketIOServerHelper`**: Wraps Socket.IO server, provides interaction methods
+-   **`@socket.io/redis-adapter`**: Scales Socket.IO with Redis
+-   **`@socket.io/redis-emitter`**: Emits events from external processes
+-   **Integration**: Works with HTTP server and authentication system
+
+## Implementation Details
+
+### Tech Stack
+
+-   **Socket.IO**
+-   **`@socket.io/redis-adapter`**
+-   **`@socket.io/redis-emitter`**
+-   **`ioredis`** (if using Redis)
+
+### Configuration
+
+To use the Socket.IO component, you need to provide a few things in your application's DI container:
+
+-   **`SocketIOBindingKeys.SERVER_OPTIONS`**: (Optional) Custom options for the Socket.IO server.
+-   **`SocketIOBindingKeys.REDIS_CONNECTION`**: An instance of `DefaultRedisHelper` (or a compatible class) for the Redis adapter.
+-   **`SocketIOBindingKeys.AUTHENTICATE_HANDLER`**: A function to handle the authentication of new socket connections.
+-   **`SocketIOBindingKeys.CLIENT_CONNECTED_HANDLER`**: (Optional) A function to be called when a client is successfully connected and authenticated.
+
+### Code Samples
+
+#### 1. Setting up the Socket.IO Component
+
+In your `src/application.ts`:
+
+```typescript
+import {
+  SocketIOComponent,
+  SocketIOBindingKeys,
+  RedisHelper, // Your Redis helper
+  BaseApplication,
+  ValueOrPromise,
+  IHandshake,
+} from '@venizia/ignis';
+
+// ...
+
+export class Application extends BaseApplication {
+  // ...
+
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+
+    // 1. Bind Redis connection
+    const redis = new RedisHelper({
+      name: 'redis',
+      host: 'localhost',
+      port: 6379,
+      password: 'password',
+    });
+    this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION }).toValue(redis);
+
+    // 2. Bind authentication handler
+    const authenticateFn = async (handshake: IHandshake) => {
+      const { token } = handshake.auth;
+      // Your custom authentication logic here
+      // e.g., verify a JWT
+      return !!token;
+    };
+    this.bind({ key: SocketIOBindingKeys.AUTHENTICATE_HANDLER }).toValue(authenticateFn);
+
+    // 3. Register the component
+    this.component(SocketIOComponent);
+  }
+
+  // ...
+}
+```
+
+#### 2. Emitting Events
+
+You can get the `SocketIOServerHelper` instance from the container and use it 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 },
+      },
+    });
+  }
+```

package/wiki/references/components/swagger.md

@@ -0,0 +1,175 @@
+# Swagger/OpenAPI Component
+
+Automatic interactive API documentation generation using OpenAPI specifications.
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| **SwaggerComponent** | Configures documentation UI and routes |
+| **UIProviderFactory** | Manages UI providers (Swagger UI, Scalar) |
+| **Default UI** | Scalar (can be changed to Swagger UI) |
+
+### Default Endpoints
+
+| Path | Description |
+|------|-------------|
+| `/doc/explorer` | Documentation UI (Scalar by default) |
+| `/doc/openapi.json` | Raw OpenAPI specification |
+
+### UI Provider Types
+
+| Provider | Value | When to Use |
+|----------|-------|-------------|
+| **Scalar** | `'scalar'` | Modern, clean UI (default) |
+| **Swagger UI** | `'swagger'` | Classic Swagger interface |
+
+## Architecture Components
+
+-   **`SwaggerComponent`**: Configures documentation UI and registers routes
+-   **`UIProviderFactory`**: Manages different UI providers
+-   **`@hono/zod-openapi`**: Powers OpenAPI generation from Zod schemas
+-   **Integration**: Works with controller `defineRoute` methods using Zod schemas
+
+## Implementation Details
+
+### Tech Stack
+
+-   **Hono**
+-   **`@hono/zod-openapi`**
+-   **`@hono/swagger-ui`** (for Swagger UI)
+-   **`@scalar/hono-api-reference`** (for Scalar UI)
+-   **`zod`**
+
+### Configuration
+
+The Swagger component can be configured via the `ISwaggerOptions` binding. You can customize the documentation path, OpenAPI version, and the UI provider type.
+
+**`ISwaggerOptions` Interface:**
+
+```typescript
+export interface ISwaggerOptions {
+  restOptions: {
+    base: { path: string }; // Base path for all documentation routes
+    doc: { path: string };  // Path to the raw openapi.json file
+    ui: {
+      path: string;         // Path to the documentation UI
+      type: 'swagger' | 'scalar'; // Type of UI to render
+    };
+  };
+  explorer: {
+    openapi: string;
+    info?: { /* ... */ };
+    servers?: Array<{ url: string; description?: string; }>;
+  };
+  uiConfig?: Record<string, any>; // Custom config for the UI provider
+}
+```
+
+**Default Options:**
+
+The default UI provider is `scalar`.
+
+```typescript
+const DEFAULT_SWAGGER_OPTIONS: ISwaggerOptions = {
+  restOptions: {
+    base: { path: '/doc' },
+    doc: { path: '/openapi.json' },
+    ui: { path: '/explorer', type: 'scalar' },
+  },
+  // ...
+};
+```
+
+### Code Samples
+
+#### 1. Registering the Swagger Component
+
+In your `src/application.ts`, register the `SwaggerComponent`.
+
+```typescript
+// src/application.ts
+import { SwaggerComponent, BaseApplication, ValueOrPromise } from '@venizia/ignis';
+
+export class Application extends BaseApplication {
+    // ...
+    preConfigure(): ValueOrPromise<void> {
+        // ...
+        this.component(SwaggerComponent);
+        // ...
+    }
+    // ...
+}
+```
+
+#### 2. Customizing the UI Provider
+
+To change the UI provider to Swagger UI, you can bind custom options in your application's `preConfigure` method.
+
+```typescript
+import { SwaggerComponent, SwaggerBindingKeys, ISwaggerOptions } from '@venizia/ignis';
+
+// ... in your Application class's preConfigure method
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.bind<ISwaggerOptions>({
+      key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+    }).toValue({
+      restOptions: {
+        base: { path: '/doc' },
+        doc: { path: '/openapi.json' },
+        ui: { path: '/explorer', type: 'swagger' }, // Use Swagger UI
+      },
+      explorer: {
+        openapi: '3.0.0',
+      },
+    });
+
+    this.component(SwaggerComponent);
+    // ...
+  }
+```
+
+#### 3. Defining Routes with Zod Schemas
+
+To get the most out of the documentation, define your routes with `zod` schemas.
+
+```typescript
+// src/controllers/hello.controller.ts
+import { z } from '@hono/zod-openapi';
+import { BaseController, controller, HTTP, jsonContent, ValueOrPromise } from '@venizia/ignis';
+
+@controller({ path: '/hello' })
+export class HelloController extends BaseController {
+  constructor() {
+    super({ scope: HelloController.name, path: '/hello' });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    this.defineRoute({
+      configs: {
+        path: '/',
+        method: 'get',
+        responses: {
+          [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
+            description: 'A simple hello message',
+            schema: z.object({ message: z.string() }),
+          }),
+        },
+      },
+      handler: (c) => {
+        return c.json({ message: 'Hello, `Ignis`!' });
+      },
+    });
+  }
+}
+```
+
+## API or Interface Specifications
+
+By default, the documentation is available at the following endpoints:
+
+-   **/doc/explorer**: The documentation UI (`scalar` by default).
+-   **/doc/openapi.json**: The raw OpenAPI specification.
+
+These paths can be configured by providing custom `ISwaggerOptions`. This feature provides a powerful and flexible way to document your APIs, making them easier to consume and understand.

package/wiki/references/helpers/cron.md

@@ -0,0 +1,94 @@
+# Cron Helper
+
+Schedule and manage recurring tasks (cron jobs) using cron patterns.
+
+## Quick Reference
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `cronTime` | `string` | Cron pattern (e.g., `'0 */1 * * * *'` = every minute) |
+| `onTick` | `Function` | Callback executed on schedule |
+| `autoStart` | `boolean` | Start automatically (default: `false`) |
+| `tz` | `string` | Timezone (e.g., `'America/New_York'`) |
+| `errorHandler` | `Function` | Handle errors in `onTick` |
+
+### Common Cron Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `'0 */1 * * * *'` | Every minute |
+| `'0 */5 * * * *'` | Every 5 minutes |
+| `'0 0 * * * *'` | Every hour |
+| `'0 0 0 * * *'` | Every day at midnight |
+| `'0 0 0 * * 1'` | Every Monday at midnight |
+
+### Key Methods
+
+| Method | Purpose |
+|--------|---------|
+| `start()` | Start the cron job manually |
+| `modifyCronTime({ cronTime })` | Change schedule dynamically |
+| `duplicate({ cronTime })` | Create new job with same config |
+
+## Creating a Cron Job
+
+To create a cron job, you instantiate the `CronHelper` with your desired options.
+
+### `ICronHelperOptions`
+
+-   `cronTime` (string): The cron pattern that defines when the job should run (e.g., `'0 */1 * * * *'` for every minute).
+-   `onTick` (() => void | Promise<void>): The function to be executed when the cron job triggers.
+-   `onCompleted` (CronOnCompleteCommand | null, optional): A function to be executed when the job stops.
+-   `autoStart` (boolean, optional): If `true`, the job will start automatically. Defaults to `false`.
+-   `tz` (string, optional): The timezone to use for the schedule.
+-   `errorHandler` ((error: unknown) => void | null, optional): A function to handle errors that occur during the `onTick` execution.
+
+### Example
+
+Here's how to create a simple cron job that logs a message every minute:
+
+```typescript
+import { CronHelper } from '@venizia/ignis';
+
+const myJob = new CronHelper({
+  cronTime: '0 */1 * * * *', // Every minute
+  onTick: () => {
+    console.log('This message will be logged every minute.');
+  },
+  autoStart: true,
+  tz: 'America/New_York',
+});
+```
+
+## Managing Cron Jobs
+
+The `CronHelper` instance provides several methods for managing the cron job:
+
+### `start()`
+
+Manually starts the cron job if `autoStart` was set to `false`.
+
+```typescript
+myJob.start();
+```
+
+### `modifyCronTime(opts)`
+
+Dynamically changes the schedule of an existing cron job.
+
+-   `cronTime` (string): The new cron pattern.
+-   `shouldFireOnTick` (boolean, optional): If `true`, the `onTick` function will be executed immediately after the time is changed.
+
+```typescript
+// Change the job to run every 5 minutes
+myJob.modifyCronTime({ cronTime: '0 */5 * * * *' });
+```
+
+### `duplicate(opts)`
+
+Creates a new `CronHelper` instance with the same configuration but a new `cronTime`.
+
+```typescript
+const anotherJob = myJob.duplicate({ cronTime: '0 0 * * *' }); // Runs once at midnight
+anotherJob.start();
+```