@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/guides/core-concepts/application/index.md

@@ -23,11 +23,11 @@ export const appConfigs: IApplicationConfigs = {
   host: process.env.APP_ENV_SERVER_HOST,
   port: +(process.env.APP_ENV_SERVER_PORT ?? 3000),
   path: {
-    base: process.env.APP_ENV_SERVER_BASE_PATH,
+    base: process.env.APP_ENV_SERVER_BASE_PATH ?? "/",
     isStrict: true,
   },
   debug: {
-    showRoutes: process.env.NODE_ENV !== "production",
+    shouldShowRoutes: process.env.NODE_ENV !== "production",
   },
 };
 
@@ -40,18 +40,18 @@ export class Application extends BaseApplication {
   staticConfigure(): void {
     // e.g., this.static({ folderPath: './public' })
   }
-  
+
   preConfigure(): ValueOrPromise<void> {
     // Register your resources
     this.dataSource(MyDataSource);
     this.service(MyService);
     this.controller(MyController);
   }
-  
+
   postConfigure(): ValueOrPromise<void> {
     // Logic to run after everything is configured
   }
-  
+
   setupMiddlewares(): ValueOrPromise<void> {
     // Add any custom application-wide middlewares
   }
@@ -64,9 +64,9 @@ The `Ignis` application has a well-defined lifecycle, managed primarily by the `
 
 | Method | Description |
 | :--- | :--- |
-| **`constructor(opts)`** | Initializes the application, sets up the Hono server, and detects the runtime (Bun/Node). |
-| **`start()`** | The main entry point. It calls `initialize()`, sets up middlewares, and starts the HTTP server. |
-| **`stop()`** | Stops the application server. |
+| **`constructor(opts)`** | Initializes the application, sets up the Hono server (`OpenAPIHono`), and detects the runtime (Bun/Node). The `Application` extends `Container` (IoC container). |
+| **`start()`** | The main entry point. It calls `initialize()`, sets up middlewares, mounts the root router, and starts the HTTP server. |
+| **`stop()`** | Stops the application server (calls `Bun.serve.stop()` or `node-server.close()`). |
 | **`initialize()`** | Orchestrates the entire setup process, calling the various configuration and registration methods in the correct order. |
 
 The `BaseApplication` class provides several **overridable hook methods** that allow you to customize the startup process. These are the primary places you'll write your application-specific setup code.
@@ -74,10 +74,10 @@ The `BaseApplication` class provides several **overridable hook methods** that a
 | Hook Method | Purpose |
 | :--- | :--- |
 | `getAppInfo()` | **Required.** Return application metadata, usually from `package.json`. Used for OpenAPI docs. |
-| `staticConfigure()` | Configure static file serving. |
+| `staticConfigure()` | Configure static file serving. Called before `preConfigure()`. |
 | `preConfigure()` | **Most Important Hook.** Set up application resources like components, controllers, services, and datasources. Can be skipped if using [Bootstrapping](./bootstrapping). |
-| `postConfigure()` | Perform actions *after* all resources have been configured and instantiated. |
-| `setupMiddlewares()`| Add custom application-level middlewares to the Hono instance. |
+| `postConfigure()` | Perform actions *after* all resources have been configured and instantiated. Note: do not bind new datasources, components, or controllers here -- they will not be auto-configured. |
+| `setupMiddlewares()`| Add custom application-level middlewares to the Hono instance. Called after `initialize()` completes. |
 
 ## Lifecycle Diagram
 
@@ -89,25 +89,27 @@ start()
   ▼
 initialize()
   │
-  ├─► boot()                      (if bootOptions configured)
   ├─► printStartUpInfo
   ├─► validateEnvs
-  ├─► registerDefaultMiddlewares
-  ├─► staticConfigure()           ← Override hook
-  ├─► preConfigure()              ← Override hook
-  ├─► registerDataSources
-  ├─► registerComponents
-  ├─► registerControllers
-  └─► postConfigure()             ← Override hook
+  ├─► registerDefaultMiddlewares   (error handler, contextStorage, RequestTracker, favicon)
+  ├─► staticConfigure()            ← Override hook
+  ├─► preConfigure()               ← Override hook
+  ├─► registerDataSources()        (configures all datasource bindings)
+  ├─► registerComponents()         (configures all component bindings)
+  ├─► registerControllers()        (REST + gRPC transport components)
+  └─► postConfigure()              ← Override hook
+  │
+  ▼
+setupMiddlewares()                 ← Override hook
   │
   ▼
-setupMiddlewares()                ← Override hook
+Mount Root Router (server.route(basePath, rootRouter))
   │
   ▼
-Mount Root Router
+Start HTTP Server (Bun.serve or @hono/node-server)
   │
   ▼
-Start HTTP Server
+executePostStartHooks()
 ```
 
 ## Configuration
@@ -118,17 +120,23 @@ Application configuration is passed to the `BaseApplication` constructor via an
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `host` | `string` | `'localhost'` | The host address to bind the server to. |
-| `port` | `number` | `3000` | The port to listen on. |
+| `host` | `string` | `'localhost'` | The host address. Falls back to `HOST` or `APP_ENV_SERVER_HOST` env vars. |
+| `port` | `number` | `3000` | The port to listen on. Falls back to `PORT` or `APP_ENV_SERVER_PORT` env vars. |
 | `path.base`| `string` | `'/'` | The base path for all application routes (e.g., `/api`). |
 | `path.isStrict`| `boolean`| `true` | If `true`, the router is strict about trailing slashes. |
-| `debug.showRoutes`| `boolean`| `false`| If `true`, prints all registered routes to the console on startup. |
+| `debug.shouldShowRoutes`| `boolean`| `false`| If `true`, prints all registered routes to the console on startup. |
 | `favicon` | `string` | `'🔥'` | An emoji to be used as the application's favicon. |
 | `bootOptions` | `IBootOptions` | `undefined` | Enable auto-discovery of artifacts. See [Bootstrapping](./bootstrapping). |
+| `asyncContext.enable` | `boolean` | `true` | Enable Hono's async context storage (powered by `contextStorage()`). |
+| `transports` | `TControllerTransport[]` | `['rest']` | Controller transports to enable. Add `'grpc'` for gRPC support. |
+| `error.rootKey` | `string` | `undefined` | Optional root key for error response wrapping. |
+| `strictPath` | `boolean` | `true` | Controls trailing slash strictness on the main Hono server. |
 
 ### Example Configuration
 
 ```typescript
+import { ControllerTransports } from '@venizia/ignis';
+
 export const appConfigs: IApplicationConfigs = {
   host: "0.0.0.0",
   port: 3000,
@@ -137,8 +145,9 @@ export const appConfigs: IApplicationConfigs = {
     isStrict: true,
   },
   debug: {
-    showRoutes: true,
+    shouldShowRoutes: true,
   },
+  transports: [ControllerTransports.REST, ControllerTransports.GRPC],
 };
 ```
 
@@ -146,28 +155,79 @@ export const appConfigs: IApplicationConfigs = {
 
 Register resources in `preConfigure()` to tell the DI container about your classes:
 
-| Method | Example | When to Use |
-|--------|---------|-------------|
-| `this.controller(...)` | `this.controller(UserController)` | Register API endpoints |
-| `this.service(...)` | `this.service(UserService)` | Register business logic |
-| `this.repository(...)` | `this.repository(UserRepository)` | Register data access |
-| `this.dataSource(...)` | `this.dataSource(PostgresDataSource)` | Register database connection |
-| `this.component(...)` | `this.component(AuthComponent)` | Register reusable modules |
+| Method | Example | Binding Scope | When to Use |
+|--------|---------|---------------|-------------|
+| `this.dataSource(...)` | `this.dataSource(PostgresDataSource)` | **Singleton** | Register database connection |
+| `this.component(...)` | `this.component(AuthComponent)` | **Singleton** | Register reusable modules |
+| `this.repository(...)` | `this.repository(UserRepository)` | Transient | Register data access |
+| `this.service(...)` | `this.service(UserService)` | Transient | Register business logic |
+| `this.controller(...)` | `this.controller(UserController)` | Transient | Register API endpoints |
+| `this.booter(...)` | `this.booter(CustomBooter)` | Tagged `'booter'` | Register custom booters |
+
+All registration methods accept an optional second parameter to customize the binding key:
+
+```typescript
+// Default binding (key: 'controllers.UserController')
+this.controller(UserController);
+
+// Custom binding key
+this.controller(UserController, {
+  binding: { namespace: 'controllers', key: 'CustomUserController' }
+});
+```
 
 **Registration order:**
 1. DataSources first (database connections)
 2. Repositories (depend on DataSources)
 3. Services (depend on Repositories)
 4. Controllers (depend on Services)
-5. Components last
+5. Components (can add more datasources/controllers during configuration)
 
 > **Deep Dive:** See [Dependency Injection](../dependency-injection.md) for how registration and injection work together.
 
+## Runtime Support
+
+The application detects the runtime automatically via `RuntimeModules.detect()`:
+
+```typescript
+// Bun (default) — uses Bun.serve
+Bun.serve({ port, hostname, fetch: server.fetch })
+
+// Node.js — requires @hono/node-server
+import { serve } from '@hono/node-server'
+serve({ fetch: server.fetch, port, hostname })
+```
+
+## Post-Start Hooks
+
+Register hooks that execute after the HTTP server has started:
+
+```typescript
+this.registerPostStartHook({
+  identifier: 'cache-warmup',
+  hook: async () => {
+    // Warm up caches, start background jobs, etc.
+  },
+});
+```
+
+## Static File Serving
+
+Serve static files with runtime-aware implementation:
+
+```typescript
+staticConfigure(): void {
+  this.static({ restPath: '/public/*', folderPath: './public' });
+}
+```
+
+Uses `hono/bun` `serveStatic` for Bun runtime, `@hono/node-server/serve-static` for Node.js.
+
 ## See Also
 
 - **Related Concepts:**
   - [Bootstrapping](./bootstrapping) - Auto-discovery of artifacts
-  - [Controllers](/guides/core-concepts/controllers) - Creating HTTP endpoints
+  - [REST Controllers](/guides/core-concepts/rest-controllers) | [gRPC Controllers](/guides/core-concepts/grpc-controllers) - Creating HTTP/gRPC endpoints
   - [Services](/guides/core-concepts/services) - Business logic layer
   - [Dependency Injection](/guides/core-concepts/dependency-injection) - How DI works in IGNIS
 

package/wiki/guides/core-concepts/components-guide.md

@@ -7,7 +7,7 @@ This guide walks you through creating your own components step-by-step.
 Imagine you're building multiple applications that all need the same features: authentication, health checks, file uploads. Without components, you'd copy-paste code between projects:
 
 ```typescript
-// ❌ Without Components - Copy-paste everywhere
+// Without Components - Copy-paste everywhere
 export class Application extends BaseApplication {
   preConfigure() {
     // Auth feature - copied to every project
@@ -28,7 +28,7 @@ export class Application extends BaseApplication {
 **Components solve this** by packaging related functionality into reusable, plug-and-play modules:
 
 ```typescript
-// ✅ With Components - Clean and reusable
+// With Components - Clean and reusable
 export class Application extends BaseApplication {
   preConfigure() {
     this.component(AuthenticateComponent);  // All auth features in one line
@@ -57,11 +57,11 @@ When you register a component, all of these get added to your application automa
 
 | Scenario | Use Component? | Why |
 |----------|----------------|-----|
-| Feature used in **one** project only | ❌ No | Just register services/controllers directly |
-| Feature **shared across projects** | ✅ Yes | Package once, reuse everywhere |
-| Feature with **multiple related parts** | ✅ Yes | Keep related code together |
-| Building a **library/package** | ✅ Yes | Easy distribution and installation |
-| **Configurable feature** with options | ✅ Yes | Components handle configuration elegantly |
+| Feature used in **one** project only | No | Just register services/controllers directly |
+| Feature **shared across projects** | Yes | Package once, reuse everywhere |
+| Feature with **multiple related parts** | Yes | Keep related code together |
+| Building a **library/package** | Yes | Easy distribution and installation |
+| **Configurable feature** with options | Yes | Components handle configuration elegantly |
 
 ## Creating Your First Component
 
@@ -129,7 +129,7 @@ export class NotificationService extends BaseService {
 ```typescript
 // src/components/notification/controllers/controller.ts
 import {
-  BaseController,
+  BaseRestController,
   controller,
   post,
   inject,
@@ -143,7 +143,6 @@ import { NotificationService } from '../services';
 
 const NotificationRoutes = {
   SEND: {
-    method: HTTP.Methods.POST,
     path: '/send',
     request: {
       body: jsonContent({
@@ -160,12 +159,12 @@ const NotificationRoutes = {
 } as const;
 
 @controller({ path: '/notifications' })
-export class NotificationController extends BaseController {
+export class NotificationController extends BaseRestController {
   constructor(
     @inject({ key: 'services.NotificationService' })
     private _notificationService: NotificationService,
   ) {
-    super({ scope: NotificationController.name, path: '/notifications' });
+    super({ scope: NotificationController.name });
   }
 
   @post({ configs: NotificationRoutes.SEND })
@@ -317,22 +316,25 @@ export class Application extends BaseApplication {
 Application.preConfigure()
          │
          ▼
-this.component(MyComponent)
+this.component(MyComponent)           (registers binding as SINGLETON)
+         │
+         ▼
+Application.registerComponents()      (called during initialize())
          │
          ▼
 ┌────────────────────────────────┐
 │  1. Constructor called         │
 │     - Inject application       │
 │     - Set up component scope   │
+│     - Define default bindings  │
 └────────────────────────────────┘
          │
          ▼
 ┌────────────────────────────────┐
-│  2. binding() called           │
-│     - Register services        │
-│     - Register controllers     │
-│     - Register repositories    │
-│     - Bind default options     │
+│  2. configure() called         │
+│     - initDefaultBindings()    │  (if initDefault.enable = true)
+│     - binding()                │  (register services, controllers, etc.)
+│     - isConfigured = true      │  (idempotent guard)
 └────────────────────────────────┘
          │
          ▼
@@ -491,6 +493,8 @@ export class MyComponent extends BaseComponent {
 | **Key method** | `binding()` - register all resources here |
 | **Configuration** | Use binding keys + `isBound()` check for overridable options |
 | **Registration** | `this.component(MyComponent)` in `preConfigure()` |
+| **Scope** | Components are always registered as **singletons** |
+| **Idempotent** | `configure()` only runs once, even if called multiple times |
 
 ## See Also
 
@@ -501,8 +505,8 @@ export class MyComponent extends BaseComponent {
 
 - **References:**
   - [BaseComponent API](/references/base/components) - Complete API reference
-  - [Authentication Component](/references/components/authentication/) - Real-world component example
-  - [Health Check Component](/references/components/health-check) - Simple component example
+  - [Authentication Component](/extensions/components/authentication/) - Real-world component example
+  - [Health Check Component](/extensions/components/health-check) - Simple component example
 
 - **Best Practices:**
   - [Architectural Patterns](/best-practices/architectural-patterns) - Component architecture patterns

package/wiki/guides/core-concepts/components.md

@@ -1,6 +1,6 @@
 # Components
 
-Components are reusable, pluggable modules that encapsulate a group of related features. A component acts as a powerful container for various resources—including providers, services, controllers, repositories, and even entire mini-applications—making it easy to share and integrate complex functionality across projects.
+Components are reusable, pluggable modules that encapsulate a group of related features. A component acts as a powerful container for various resources--including providers, services, controllers, repositories, and even entire mini-applications--making it easy to share and integrate complex functionality across projects.
 
 > **Deep Dive:** See [Components Reference](../../references/base/components.md) for detailed implementation patterns, directory structure, and best practices.
 
@@ -11,11 +11,30 @@ A component is a class that extends `BaseComponent` and is responsible for:
 - **Binding Dependencies**: Registering services, controllers, repositories, providers, or other resources with the application's dependency injection container.
 - **Configuring Features**: Setting up middlewares, initializing services, or performing any other setup required for the feature to work.
 
-A single component can bundle everything needed for a specific domain—for example, an "AuthComponent" might include multiple services for token management, repositories for user data, and controllers for login/signup endpoints, essentially functioning as a plug-and-play mini-application.
+A single component can bundle everything needed for a specific domain--for example, an "AuthComponent" might include multiple services for token management, repositories for user data, and controllers for login/signup endpoints, essentially functioning as a plug-and-play mini-application.
 
 ## Built-in Components
 
-Ignis includes ready-to-use components for common features like authentication, API documentation, health checks, and more. See the [**Built-in Components Reference**](../../references/components/) for the complete list with detailed documentation.
+Ignis includes ready-to-use components for common features. The following are exported from the main barrel (`@venizia/ignis`):
+
+| Component | Description |
+| :--- | :--- |
+| **Authentication** | JWT + Basic auth strategies, token services, strategy registry |
+| **Authorization** | Casbin-based RBAC, permission mapping, `authorize()` middleware |
+| **HealthCheckComponent** | `GET /health`, `/health/live`, `/health/ready` |
+| **SwaggerComponent** | Swagger UI or Scalar UI for API documentation |
+| **RequestTrackerComponent** | `x-request-id` header, request body parsing |
+
+The following components require direct subpath imports:
+
+| Component | Import From | Description |
+| :--- | :--- | :--- |
+| **MailComponent** | `@venizia/ignis/components/mail` | Nodemailer/Mailgun transporters with queue executors |
+| **SocketIOComponent** | `@venizia/ignis/components/socket-io` | Socket.IO server with Redis adapter |
+| **StaticAssetComponent** | `@venizia/ignis/components/static-asset` | File upload/download CRUD, MinIO/Disk storage |
+| **WebSocketComponent** | `@venizia/ignis/components/websocket` | Native WebSocket support |
+
+See the [**Built-in Components Reference**](../../extensions/components/) for detailed documentation.
 
 ## Creating a Simple Component
 
@@ -29,7 +48,7 @@ class NotificationService {
 
 // Define a controller
 @controller({ path: '/notifications' })
-class NotificationController extends BaseController {
+class NotificationController extends BaseRestController {
   constructor(
     @inject({ key: 'services.NotificationService' })
     private _notificationService: NotificationService
@@ -65,7 +84,10 @@ export class NotificationComponent extends BaseComponent {
 | Stage | Method | Description |
 | :--- | :--- | :--- |
 | **1. Instantiation** | `constructor()` | Component is created. Define default `bindings` here. |
-| **2. Configuration** | `binding()` | Called during startup. Register controllers and resources here. |
+| **2. Init Defaults** | `initDefaultBindings()` | If `initDefault.enable` is `true`, default bindings are registered in the container (only if not already bound). |
+| **3. Configuration** | `binding()` | Called during startup. Register controllers and additional resources here. |
+
+The `configure()` method is **idempotent** -- calling it multiple times has no effect after the first call.
 
 ## Registering a Component
 
@@ -82,6 +104,8 @@ export class Application extends BaseApplication {
 }
 ```
 
+Components are bound as **singletons** automatically when registered via `this.component()`.
+
 ## Customizing Component Options
 
 Most components accept configuration options. Override them before registration:
@@ -102,7 +126,7 @@ export class Application extends BaseApplication {
 > **Next Steps:**
 > - [Creating Components Guide](./components-guide.md) - Step-by-step tutorial for building your own components
 > - [Components Reference](../../references/base/components.md) - Directory structure, keys, types, constants patterns
-> - [Built-in Components](../../references/components/) - Detailed documentation for each component
+> - [Built-in Components](../../extensions/components/) - Detailed documentation for each component
 
 ## See Also
 
@@ -113,10 +137,10 @@ export class Application extends BaseApplication {
 
 - **References:**
   - [BaseComponent API](/references/base/components) - Complete API reference
-  - [Authentication Component](/references/components/authentication/) - JWT authentication
-  - [Health Check Component](/references/components/health-check) - Health endpoints
-  - [Swagger Component](/references/components/swagger) - API documentation
-  - [Socket.IO Component](/references/components/socket-io/) - WebSocket support
+  - [Authentication Component](/extensions/components/authentication/) - JWT authentication
+  - [Health Check Component](/extensions/components/health-check) - Health endpoints
+  - [Swagger Component](/extensions/components/swagger) - API documentation
+  - [Socket.IO Component](/extensions/components/socket-io/) - WebSocket support
 
 - **Best Practices:**
   - [Architectural Patterns](/best-practices/architectural-patterns) - Component design patterns