@venizia/ignis-docs 0.0.1-8 → 0.0.1

package/wiki/references/src-details/boot.md

@@ -0,0 +1,379 @@
+# @venizia/ignis-boot
+
+> **Package**: `@venizia/ignis-boot`  
+> **Purpose**: Application bootstrapping system with artifact auto-discovery  
+> **Version**: 0.0.0
+
+## Overview
+
+The `@venizia/ignis-boot` package provides a powerful bootstrapping system that automatically discovers and loads application artifacts (controllers, services, repositories, datasources) during application startup. It eliminates the need for manual registration of each artifact, making application setup cleaner and more maintainable.
+
+## Key Concepts
+
+### Boot Phases
+
+The boot process consists of three phases executed in order:
+
+1. **Configure** - Booters configure their discovery patterns
+2. **Discover** - Booters scan filesystem for matching artifacts
+3. **Load** - Booters load classes and bind them to the application container
+
+### Artifacts
+
+An artifact is any application component that can be auto-discovered:
+- **Controllers** - REST/API endpoint handlers
+- **Services** - Business logic layer
+- **Repositories** - Data access layer
+- **Datasources** - Database connections
+
+### Booters
+
+Booters are specialized classes that handle discovery and loading of specific artifact types. Each booter:
+- Defines default discovery patterns (directories, file extensions)
+- Scans filesystem for matching files
+- Loads classes from discovered files
+- Binds loaded classes to application container
+
+## Core Components
+
+### Bootstrapper
+
+Orchestrates the entire boot process.
+
+| Feature | Description |
+|---------|-------------|
+| **Phase Execution** | Runs configure → discover → load phases |
+| **Booter Discovery** | Automatically finds all registered booters |
+| **Error Handling** | Catches and reports errors during boot |
+| **Performance Tracking** | Measures time taken for each phase |
+
+**Usage:**
+
+```typescript
+import { Bootstrapper, IBootExecutionOptions } from '@venizia/ignis-boot';
+
+const bootstrapper = app.get<Bootstrapper>({ key: 'bootstrapper' });
+await bootstrapper.boot({
+  phases: ['configure', 'discover', 'load'], // optional, default: all phases
+  booters: ['ControllerBooter', 'ServiceBooter'], // optional, default: all booters
+});
+```
+
+### BaseArtifactBooter
+
+Abstract base class for creating custom booters.
+
+| Method | Phase | Description |
+|--------|-------|-------------|
+| `configure()` | Configure | Sets up discovery patterns |
+| `discover()` | Discover | Scans filesystem for artifacts |
+| `load()` | Load | Loads classes and binds to container |
+| `getPattern()` | - | Generates glob pattern for file discovery |
+| `bind()` | - | Abstract method - implement to bind loaded classes |
+
+**Custom Booter Example:**
+
+```typescript
+import { BaseArtifactBooter, IBooterOptions } from '@venizia/ignis-boot';
+import { inject } from '@venizia/ignis-inversion';
+
+export class CustomBooter extends BaseArtifactBooter {
+  constructor(
+    @inject({ key: '@app/project_root' }) root: string,
+    @inject({ key: '@app/instance' }) private app: IApplication,
+    @inject({ key: '@app/boot-options' }) bootOptions: IBootOptions,
+  ) {
+    super({ 
+      scope: CustomBooter.name, 
+      root, 
+      artifactOptions: bootOptions.custom ?? {} 
+    });
+  }
+
+  protected getDefaultDirs(): string[] {
+    return ['custom'];
+  }
+
+  protected getDefaultExtensions(): string[] {
+    return ['.custom.js'];
+  }
+
+  protected async bind(): Promise<void> {
+    for (const cls of this.loadedClasses) {
+      this.app.bind({ key: `custom.${cls.name}` }).toClass(cls);
+    }
+  }
+}
+```
+
+### Built-in Booters
+
+#### ControllerBooter
+
+Auto-discovers and registers controllers.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['controllers']` |
+| **Extensions** | `['.controller.js']` |
+| **Binding Pattern** | `controllers.{ClassName}` |
+
+#### ServiceBooter
+
+Auto-discovers and registers services.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['services']` |
+| **Extensions** | `['.service.js']` |
+| **Binding Pattern** | `services.{ClassName}` |
+
+#### RepositoryBooter
+
+Auto-discovers and registers repositories.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['repositories']` |
+| **Extensions** | `['.repository.js']` |
+| **Binding Pattern** | `repositories.{ClassName}` |
+
+#### DatasourceBooter
+
+Auto-discovers and registers datasources.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['datasources']` |
+| **Extensions** | `['.datasource.js']` |
+| **Binding Pattern** | `datasources.{ClassName}` |
+
+### BootMixin
+
+Mixin that adds bootable capability to any application.
+
+**Features:**
+- Automatically binds default booters
+- Exposes `boot()` method
+- Configurable via `bootOptions`
+
+**Usage:**
+
+```typescript
+import { BootMixin } from '@venizia/ignis-boot';
+import { Container } from '@venizia/ignis-inversion';
+
+class MyApp extends BootMixin(Container) {
+  bootOptions = {
+    controllers: { 
+      dirs: ['private-controllers', 'public-controllers'],
+      extensions: ['.controller.js', '.controller.ts']
+    },
+    services: { 
+      isNested: true // scan subdirectories
+    }
+  };
+}
+
+const app = new MyApp();
+await app.boot();
+```
+
+## Boot Options
+
+Configure artifact discovery per artifact type.
+
+### IArtifactOptions
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `dirs` | `string[]` | Varies | Directories to scan |
+| `extensions` | `string[]` | Varies | File extensions to match |
+| `isNested` | `boolean` | `true` | Scan subdirectories |
+| `glob` | `string` | - | Custom glob pattern (overrides dirs/extensions) |
+
+### IBootOptions
+
+```typescript
+interface IBootOptions {
+  controllers?: IArtifactOptions;
+  services?: IArtifactOptions;
+  repositories?: IArtifactOptions;
+  datasources?: IArtifactOptions;
+  [artifactType: string]: IArtifactOptions | undefined;
+}
+```
+
+**Example Configuration:**
+
+```typescript
+const bootOptions: IBootOptions = {
+  controllers: {
+    dirs: ['controllers/private', 'controllers/public'],
+    extensions: ['.controller.js'],
+    isNested: true
+  },
+  repositories: {
+    glob: 'data-access/**/*.repository.js' // custom pattern
+  },
+  services: {
+    dirs: ['services'],
+    extensions: ['.service.js', '.service.ts'],
+    isNested: false // only scan root level
+  }
+};
+```
+
+## Integration with Core
+
+### BaseApplication Integration
+
+Boot system is integrated into `BaseApplication` via `IBootableApplication` interface:
+
+```typescript
+export abstract class BaseApplication 
+  extends AbstractApplication 
+  implements IRestApplication, IBootableApplication {
+  
+  bootOptions?: IBootOptions;
+  
+  boot(): Promise<IBootReport> {
+    const bootstrapper = this.get<Bootstrapper>({ key: 'bootstrapper' });
+    return bootstrapper.boot({});
+  }
+}
+```
+
+### Automatic Initialization
+
+If `bootOptions` is defined in application config, boot runs automatically during `initialize()`:
+
+```typescript
+override async initialize() {
+  if (this.configs.bootOptions) {
+    // Bind boot infrastructure
+    this.bind({ key: '@app/boot-options' }).toValue(this.bootOptions ?? {});
+    this.bind({ key: 'bootstrapper' }).toClass(Bootstrapper);
+    
+    // Register default booters
+    this.booter(DatasourceBooter);
+    this.booter(RepositoryBooter);
+    this.booter(ServiceBooter);
+    this.booter(ControllerBooter);
+    
+    // Execute boot
+    await this.boot();
+  }
+  
+  // ... rest of initialization
+}
+```
+
+## Utilities
+
+### discoverFiles
+
+Discovers files matching a glob pattern.
+
+```typescript
+const files = await discoverFiles({ 
+  pattern: 'controllers/**/*.controller.js',
+  root: '/path/to/project'
+});
+// Returns: ['/path/to/project/controllers/user.controller.js', ...]
+```
+
+### loadClasses
+
+Loads class constructors from files.
+
+```typescript
+const classes = await loadClasses({ 
+  files: ['/path/to/file1.js', '/path/to/file2.js'],
+  root: '/path/to/project'
+});
+// Returns: [UserController, ProductController, ...]
+```
+
+### isClass
+
+Type guard to check if value is a class constructor.
+
+```typescript
+if (isClass(exported)) {
+  // exported is TClass<any>
+}
+```
+
+## Complete Example
+
+```typescript
+import { BaseApplication, IApplicationConfigs } from '@venizia/ignis';
+import { IBootOptions } from '@venizia/ignis-boot';
+
+export const appConfigs: IApplicationConfigs = {
+  name: 'MyApp',
+  bootOptions: {
+    controllers: {
+      dirs: ['controllers'],
+      extensions: ['.controller.js'],
+      isNested: true
+    },
+    services: {
+      dirs: ['services'],
+      extensions: ['.service.js'],
+      isNested: true
+    },
+    repositories: {
+      dirs: ['repositories'],
+      extensions: ['.repository.js']
+    },
+    datasources: {
+      dirs: ['datasources'],
+      extensions: ['.datasource.js']
+    }
+  }
+};
+
+export class MyApp extends BaseApplication {
+  constructor() {
+    super(appConfigs);
+  }
+}
+
+// Boot runs automatically during initialize()
+const app = new MyApp();
+await app.start(); // Calls initialize() which triggers boot
+```
+
+## Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **Auto-discovery** | No manual registration of controllers/services/repositories |
+| **Convention-based** | Follow naming conventions, framework handles the rest |
+| **Flexible** | Customize discovery patterns per artifact type |
+| **Extensible** | Create custom booters for new artifact types |
+| **Performance** | Track boot time per phase |
+| **Developer Experience** | Focus on writing code, not wiring infrastructure |
+
+## When to Use
+
+✅ **Use Boot System When:**
+- Building applications with many controllers/services/repositories
+- Want convention-over-configuration approach
+- Need consistent artifact registration across projects
+- Building modular applications with clear folder structure
+
+❌ **Manual Registration When:**
+- Very small applications (< 5 artifacts)
+- Need fine-grained control over registration order
+- Dynamic artifact registration based on runtime conditions
+- Artifacts don't follow file naming conventions
+
+## Related Documentation
+
+- [Bootstrapping Concepts](/get-started/core-concepts/bootstrapping.md)
+- [Application Guide](/get-started/core-concepts/application.md)
+- [Dependency Injection](/references/base/dependency-injection.md)
+- [Core Package](/references/src-details/core.md)

package/wiki/references/src-details/core.md

@@ -12,7 +12,7 @@ Detailed breakdown of the core framework directory structure.
 |-----------|---------------|----------------|
 | **`base`** | Core architecture | Applications, Controllers, Repositories, Services, Models |
 | **`components`** | Pluggable features | Auth, Swagger, HealthCheck, SocketIO |
-| **`helpers`** | Utilities | Re-exports from `@venizia/ignis-helpers` |
+| **`helpers`** | Utilities | DI (extended), Re-exports from `@venizia/ignis-helpers` |
 | **`common`** | Shared code | Constants, bindings, types, environments |
 | **`utilities`** | Pure functions | Crypto, date, parse, performance, schema |
 | **`__tests__`** | Tests | Integration and E2E tests |
@@ -27,7 +27,7 @@ Top-level breakdown of the `src` directory:
 | **`base`**       | The core building blocks and abstract classes of the framework. This is where the fundamental architecture is defined. |
 | **`common`**     | A directory for code that is shared and used across the entire framework.                                              |
 | **`components`** | A collection of ready-to-use, high-level components that can be plugged into an Ignis application.                     |
-| **`helpers`**    | Re-exports all modules from the dedicated `@venizia/ignis-helpers` package.                                                |
+| **`helpers`**    | Contains core extensions (like Inversion) and re-exports from `@venizia/ignis-helpers`.                                    |
 | **`utilities`**  | A collection of pure, standalone utility functions.                                                                    |
 
 ---
@@ -52,8 +52,8 @@ This is the foundational layer of Ignis, defining the core architecture and abst
 | File/Folder   | Purpose/Key Details                                                                                                                                                                                                                                                                                       |
 | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `abstract.ts` | Defines `AbstractApplication`, the base class for Ignis applications. Handles core server setup (Hono instance, runtime detection for Bun/Node.js), environment validation, and route inspection. Mandates abstract methods for middleware setup and configuration.                                       |
-| `base.ts`     | Extends `AbstractApplication` to provide `BaseApplication`, implementing common functionalities like component, controller, service, repository, and datasource registration. Includes default middleware registration (e.g., error handling, favicon, request tracking) and startup information logging. |
-| `types.ts`    | Contains interfaces for application configurations (`IApplicationConfigs`), application information (`IApplicationInfo`), and various middleware options (e.g., `ICORSOptions`, `ICSRFOptions`).                                                                                                          |
+| `base.ts`     | Extends `AbstractApplication` to provide `BaseApplication`, implementing common functionalities like component, controller, service, repository, and datasource registration. Includes default middleware registration (e.g., error handling, favicon, request tracking) and startup information logging. Integrates with `@venizia/ignis-boot` for automatic artifact discovery when `bootOptions` is configured. |
+| `types.ts`    | Contains interfaces for application configurations (`IApplicationConfigs`), application information (`IApplicationInfo`), and various middleware options (e.g., `ICORSOptions`, `ICSRFOptions`). Now includes `IBootableApplication` interface for boot system integration. |
 
 #### `base/components`
 
@@ -237,11 +237,12 @@ Generates interactive OpenAPI documentation.
 
 ### `helpers`
 
-The `helpers` directory has been refactored into its own dedicated package, `@venizia/ignis-helpers`, to improve modularity. The `src/helpers` directory within the core framework now simply re-exports all modules from this new package.
+Contains framework extensions and utilities.
 
 | File/Folder | Purpose/Key Details                                                                                                                                        |
 | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.ts`  | Re-exports all helpers from the `@venizia/ignis-helpers` package, making them available through the core framework for backward compatibility and convenience. |
+| `inversion/`| **Framework DI Extension**: Extends `@venizia/ignis-inversion` to provide application-aware dependency injection with logging and enhanced metadata support. |
+| `index.ts`  | Re-exports extensions and utilities from `@venizia/ignis-helpers`. |
 
 ### `utilities`
 
@@ -260,4 +261,4 @@ This directory contains pure, standalone utility functions that perform common,
 
 ---
 
-This detailed breakdown illustrates the modular and layered design of the Ignis framework, emphasizing its extensibility and adherence to robust architectural patterns.
+This detailed breakdown illustrates the modular and layered design of the Ignis framework, emphasizing its extensibility and adherence to robust architectural patterns.

package/wiki/references/src-details/inversion.md

@@ -309,22 +309,22 @@ if (cache) {
 
 ---
 
-## Relationship with @venizia/ignis-helpers
+## Integration with Framework
 
-The `@venizia/ignis-helpers` package extends this base inversion package with:
+The core `@venizia/ignis` package extends this base inversion package with:
 
 - **ApplicationLogger integration**: Container with structured logging
 - **Framework-specific metadata**: Controllers, models, repositories, data sources
 - **Decorator implementations**: `@inject`, `@controller`, `@service`, etc.
 
-For framework usage, import from `@venizia/ignis-helpers` or `@venizia/ignis`. For standalone DI container usage, import directly from `@venizia/ignis-inversion`.
+For framework usage, import from `@venizia/ignis`. For standalone DI container usage, import directly from `@venizia/ignis-inversion`.
 
 ```typescript
 // Standalone usage
 import { Container, Binding } from '@venizia/ignis-inversion';
 
 // Framework usage (includes logging and framework metadata)
-import { Container, inject, service } from '@venizia/ignis-helpers';
+import { Container, inject, service } from '@venizia/ignis';
 ```
 
 ---

package/wiki/references/utilities/request.md

@@ -31,7 +31,7 @@ The function returns a `Promise` that resolves to an array of `IParsedFile` obje
 Here is an example of how to use `parseMultipartBody` in a controller to handle a file upload.
 
 ```typescript
-import { BaseController, controller, ... } from '@venizia/ignis';
+import { BaseController, controller, HTTP } from '@venizia/ignis';
 import { parseMultipartBody } from '@venizia/ignis';
 
 @controller({ path: '/files' })
@@ -55,9 +55,15 @@ export class FileController extends BaseController {
 
           console.log('Uploaded files:', files);
 
-          return c.json({ message: `${files.length} file(s) uploaded successfully.` });
+          return c.json(
+            { message: `${files.length} file(s) uploaded successfully.` },
+            HTTP.ResultCodes.RS_2.Ok,
+          );
         } catch (error) {
-          return c.json({ message: 'Failed to upload files', error: error.message }, 500);
+          return c.json(
+            { message: 'Failed to upload files', error: error.message },
+            HTTP.ResultCodes.RS_5.InternalServerError,
+          );
         }
       },
     });
@@ -180,10 +186,13 @@ export class FileController extends BaseController {
           uploadDir: './uploads',
         });
 
-        return ctx.json({
-          message: 'Files uploaded successfully',
-          files: files.map(f => ({ name: f.originalname, size: f.size })),
-        });
+        return ctx.json(
+          {
+            message: 'Files uploaded successfully',
+            files: files.map(f => ({ name: f.originalname, size: f.size })),
+          },
+          HTTP.ResultCodes.RS_2.Ok,
+        );
       },
     });