@venizia/ignis-docs 0.0.1-1

package/wiki/get-started/core-concepts/application.md

@@ -0,0 +1,168 @@
+# The Application Class
+
+The Application class orchestrates your application's configuration, lifecycle, and resource registration (components, controllers, services).
+
+> **Deep Dive:** See [Application Reference](../../references/base/application.md) for technical details.
+
+## Creating an Application
+
+Extend `BaseApplication` and implement the hook methods:
+
+```typescript
+// src/application.ts
+import {
+  BaseApplication,
+  IApplicationConfigs,
+  IApplicationInfo,
+  ValueOrPromise,
+} from "@venizia/ignis";
+import packageJson from "./../package.json";
+
+// Application configurations
+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,
+    isStrict: true,
+  },
+  debug: {
+    showRoutes: process.env.NODE_ENV !== "production",
+  },
+};
+
+// Main Application class
+export class Application extends BaseApplication {
+  override getAppInfo(): ValueOrPromise<IApplicationInfo> {
+    return packageJson;
+  }
+
+  staticConfigure(): void {
+    // e.g., this.static({ folderPath: './public' })
+  }
+  
+  preConfigure(): ValueOrPromise<void> {
+    // Register all your resources here
+    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
+  }
+}
+```
+
+## Application Lifecycle
+
+The `Ignis` application has a well-defined lifecycle, managed primarily by the `start()` and `initialize()` methods.
+
+| 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. |
+| **`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.
+
+| Hook Method | Purpose |
+| :--- | :--- |
+| `getAppInfo()` | **Required.** Return application metadata, usually from `package.json`. Used for OpenAPI docs. |
+| `staticConfigure()` | Configure static file serving. |
+| `preConfigure()` | **Most Important Hook.** Set up application resources like components, controllers, services, and datasources. |
+| `postConfigure()` | Perform actions *after* all resources have been configured and instantiated. |
+| `setupMiddlewares()`| Add custom application-level middlewares to the Hono instance. |
+
+## Lifecycle Diagram
+
+This diagram shows the sequence of operations during application startup. The methods you can override are highlighted.
+
+```mermaid
+%%{init: { "flowchart": { "useMaxWidth": true } } }%%
+graph TD
+    A["start()"] --> B["initialize()"];
+    
+    subgraph "initialize() Sequence"
+        direction TB
+        B --> B1["printStartUpInfo"];
+        B1 --> B2["validateEnvs"];
+        B2 --> B3["registerDefaultMiddlewares"];
+        B3 --> B4["staticConfigure()"];
+        B4 --> B5["preConfigure()"];
+        B5 --> B6["registerDataSources"];
+        B6 --> B7["registerComponents"];
+        B7 --> B8["registerControllers"];
+        B8 --> B9["postConfigure()"];
+    end
+
+    B9 --> C["setupMiddlewares()"];
+    C --> D["Mount Root Router"];
+    D --> E["Start HTTP Server"];
+
+    subgraph "Overridable Hooks"
+      style B4 fill:#ffc0cb,stroke:#333
+      style B5 fill:#ffc0cb,stroke:#333
+      style B9 fill:#ffc0cb,stroke:#333
+      style C fill:#ffc0cb,stroke:#333
+    end
+
+    classDef default fill:#fff,stroke:#333,stroke-width:2px;
+```
+
+## Configuration
+
+Application configuration is passed to the `BaseApplication` constructor via an `IApplicationConfigs` object.
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `host` | `string` | `'localhost'` | The host address to bind the server to. |
+| `port` | `number` | `3000` | The port to listen on. |
+| `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. |
+| `favicon` | `string` | `'🔥'` | An emoji to be used as the application's favicon. |
+
+### Example Configuration
+
+```typescript
+export const appConfigs: IApplicationConfigs = {
+  host: "0.0.0.0",
+  port: 3000,
+  path: {
+    base: "/api",
+    isStrict: true,
+  },
+  debug: {
+    showRoutes: true,
+  },
+};
+```
+
+## Registering Resources
+
+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 |
+
+**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
+
+> **Deep Dive:** See [Dependency Injection](./dependency-injection.md) for how registration and injection work together.

package/wiki/get-started/core-concepts/components.md

@@ -0,0 +1,96 @@
+# Components
+
+Components are reusable, pluggable modules that encapsulate features like authentication, logging, or API documentation.
+
+> **Deep Dive:** See [Components Reference](../../references/base/components.md) for technical details.
+
+## What is a Component?
+
+A component is a class that extends `BaseComponent` and is responsible for:
+
+- **Binding Dependencies**: Registering services, controllers, 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.
+
+`Ignis` comes with several built-in components, which you can explore in the [**Components Reference**](../../references/components/) section:
+
+- **`AuthenticateComponent`**: Sets up JWT-based authentication.
+- **`SwaggerComponent`**: Generates interactive OpenAPI documentation.
+- **`HealthCheckComponent`**: Adds a health check endpoint.
+- **`RequestTrackerComponent`**: Adds request logging and tracing.
+- **`SocketIOComponent`**: Integrates Socket.IO for real-time communication.
+
+## Creating a Component
+
+To create a new component, extend the `BaseComponent` class. The constructor is the ideal place to define any **default bindings** that the component provides.
+
+```typescript
+import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise, Binding, BindingScopes } from '@venizia/ignis';
+
+// An example service that the component will provide
+class MyFeatureService {
+  // ... business logic
+}
+
+// A controller that depends on the service
+@controller({ path: '/my-feature' })
+class MyFeatureController {
+  constructor(
+    @inject({ key: 'services.MyFeatureService' })
+    private myFeatureService: MyFeatureService
+  ) { /* ... */ }
+}
+
+export class MyFeatureComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE })
+    private application: BaseApplication,
+  ) {
+    super({
+      scope: MyFeatureComponent.name,
+      // Enable default bindings for this component
+      initDefault: { enable: true, container: application },
+      // Define the default bindings this component provides
+      bindings: {
+        'services.MyFeatureService': Binding.bind({ key: 'services.MyFeatureService' })
+          .toClass(MyFeatureService)
+          .setScope(BindingScopes.SINGLETON), // Make it a singleton
+      },
+    });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    // This is where you configure logic that USES the bindings.
+    // Here, we register a controller that depends on the service
+    // we just bound in the constructor.
+    this.application.controller(MyFeatureController);
+  }
+}
+```
+
+## Component Lifecycle
+
+Components have a simple, two-stage lifecycle managed by the application.
+
+| Stage | Method | Description |
+| :--- | :--- | :--- |
+| **1. Instantiation** | `constructor()` | The component is created by the DI container. This is where you call `super()` and define the component's `bindings`. If `initDefault` is enabled, these bindings are registered with the application container immediately. |
+| **2. Configuration**| `binding()` | Called by the application during the `registerComponents` startup phase. This is where you should set up resources (like controllers) that *depend* on the bindings you defined in the constructor. |
+
+## Registering a Component
+
+To activate a component, you must register it with the application instance, usually in the `preConfigure` method of your `Application` class.
+
+```typescript
+// in src/application.ts
+import { MyFeatureComponent } from './components/my-feature.component';
+
+// ... inside your Application class
+
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.component(MyFeatureComponent);
+    // ...
+  }
+```
+
+When the application starts, it will find the `MyFeatureComponent` binding, instantiate it, and then call its `binding()` method at the appropriate time. This modular approach keeps your main application class clean and makes it easy to toggle features on and off.