@venizia/ignis-docs 0.0.2 → 0.0.4-0

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

@@ -0,0 +1,122 @@
+# 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.
+
+> **Deep Dive:** See [Components Reference](../../references/base/components.md) for detailed implementation patterns, directory structure, and best practices.
+
+## What is a Component?
+
+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.
+
+## 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.
+
+## Creating a Simple Component
+
+```typescript
+import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise, Binding } from '@venizia/ignis';
+
+// Define a service
+class NotificationService {
+  send(opts: { message: string }) { /* ... */ }
+}
+
+// Define a controller
+@controller({ path: '/notifications' })
+class NotificationController extends BaseController {
+  constructor(
+    @inject({ key: 'services.NotificationService' })
+    private _notificationService: NotificationService
+  ) {
+    super({ scope: NotificationController.name });
+  }
+}
+
+// Create the component
+export class NotificationComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE })
+    private _application: BaseApplication,
+  ) {
+    super({
+      scope: NotificationComponent.name,
+      initDefault: { enable: true, container: _application },
+      bindings: {
+        'services.NotificationService': Binding.bind({ key: 'services.NotificationService' })
+          .toClass(NotificationService),
+      },
+    });
+  }
+
+  override binding(): ValueOrPromise<void> {
+    this._application.controller(NotificationController);
+  }
+}
+```
+
+## Component Lifecycle
+
+| Stage | Method | Description |
+| :--- | :--- | :--- |
+| **1. Instantiation** | `constructor()` | Component is created. Define default `bindings` here. |
+| **2. Configuration** | `binding()` | Called during startup. Register controllers and resources here. |
+
+## Registering a Component
+
+Register components in your application's `preConfigure` method:
+
+```typescript
+// src/application.ts
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    this.component(HealthCheckComponent);
+    this.component(SwaggerComponent);
+    this.component(NotificationComponent);
+  }
+}
+```
+
+## Customizing Component Options
+
+Most components accept configuration options. Override them before registration:
+
+```typescript
+// src/application.ts
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    // Override options BEFORE registering component
+    this.bind<IHealthCheckOptions>({ key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS })
+      .toValue({ restOptions: { path: '/api/health' } });
+
+    this.component(HealthCheckComponent);
+  }
+}
+```
+
+> **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
+
+## See Also
+
+- **Related Concepts:**
+  - [Application](/guides/core-concepts/application/) - Registering components
+  - [Dependency Injection](/guides/core-concepts/dependency-injection) - Component bindings
+  - [Creating Components](./components-guide) - Build your own components
+
+- **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
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - Component design patterns

package/wiki/{get-started → guides}/core-concepts/controllers.md

@@ -74,8 +74,8 @@ import { BaseController, controller, get, post, HTTP, jsonContent, jsonResponse,
 import { z } from '@hono/zod-openapi';
 
 // Define route configs as const for type inference
-const TEST_ROUTES = {
-  getData: {
+const TestRoutes = {
+  GET_DATA: {
     method: HTTP.Methods.GET,
     path: '/',
     responses: jsonResponse({
@@ -83,7 +83,7 @@ const TEST_ROUTES = {
       schema: z.object({ message: z.string(), method: z.string() }),
     }),
   },
-  createItem: {
+  CREATE_ITEM: {
     method: HTTP.Methods.POST,
     path: '/',
     request: {
@@ -105,18 +105,18 @@ export class MyItemsController extends BaseController {
     super({ scope: MyItemsController.name, path: '/my-items' });
   }
 
-  @get({ configs: TEST_ROUTES.getData })
-  getData(c: TRouteContext<typeof TEST_ROUTES.getData>) { // Return type is automatically inferred
+  @get({ configs: TestRoutes.GET_DATA })
+  getData(c: TRouteContext<typeof TestRoutes.GET_DATA>) { // Return type is automatically inferred
     // 'c' is fully typed here, including c.req.valid and c.json return type
     return c.json({ message: 'Hello from decorator', method: 'GET' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
-  @post({ configs: TEST_ROUTES.createItem })
-  createItem(c: TRouteContext<typeof TEST_ROUTES.createItem>) { // Return type is automatically inferred
-    // c.req.valid('json') is automatically typed based on createItem.request.body.content['application/json'].schema
+  @post({ configs: TestRoutes.CREATE_ITEM })
+  createItem(c: TRouteContext<typeof TestRoutes.CREATE_ITEM>) { // Return type is automatically inferred
+    // c.req.valid('json') is automatically typed based on CREATE_ITEM.request.body.content['application/json'].schema
     const body = c.req.valid('json');
 
-    // Return type is automatically validated against createItem.responses[200].content['application/json'].schema
+    // Return type is automatically validated against CREATE_ITEM.responses[200].content['application/json'].schema
     return c.json(
       {
         id: 'some-uuid',
@@ -204,7 +204,7 @@ this.bindRoute({
   configs: GetUserByIdRoute,
 }).to({
   handler: (c: TRouteContext<typeof GetUserByIdRoute>) => { // Return type is automatically inferred
-    const { id } = c.req.param();
+    const { id } = c.req.valid('param');  // Use valid() for type-safe validated params
     return c.json({ id: id, name: 'John Doe' }, HTTP.ResultCodes.RS_2.Ok);
   },
 });
@@ -409,7 +409,7 @@ import { jsonContent, put, TRouteContext, HTTP } from '@venizia/ignis';
 
 // ... inside a controller class
 
-const updateUserConfig = {
+const UpdateUserConfig = {
   path: '/:id',
   method: 'put',
   request: {
@@ -422,8 +422,8 @@ const updateUserConfig = {
   // ... responses
 } as const; // Use 'as const' for strict type inference
 
-@put({ configs: updateUserConfig })
-updateUser(c: TRouteContext<typeof updateUserConfig>) {
+@put({ configs: UpdateUserConfig })
+updateUser(c: TRouteContext<typeof UpdateUserConfig>) {
   // Access validated data from the request
   const { id } = c.req.valid('param');
   const { notify } = c.req.valid('query');
@@ -439,3 +439,20 @@ updateUser(c: TRouteContext<typeof updateUserConfig>) {
 ```
 
 Using `TRouteContext` provides full type inference for `c.req.valid()`, so your editor will know that `id` is a string, `notify` is an optional string, and `userUpdateData` matches the body schema.
+
+## See Also
+
+- **Related Concepts:**
+  - [Application](/guides/core-concepts/application/) - Registering controllers
+  - [Services](/guides/core-concepts/services) - Business logic layer called by controllers
+  - [Dependency Injection](/guides/core-concepts/dependency-injection) - Injecting services into controllers
+
+- **References:**
+  - [BaseController API](/references/base/controllers) - Complete API reference
+  - [Middlewares](/references/base/middlewares) - Request interceptors
+  - [Swagger Component](/references/components/swagger) - Auto-generate API docs
+  - [Schema Utilities](/references/utilities/schema) - Request/response helpers
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Controller examples
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Advanced routing patterns

package/wiki/{get-started → guides}/core-concepts/dependency-injection.md

@@ -170,3 +170,100 @@ You would then bind this provider in your application:
 this.bind<ThirdPartyApiClient>({ key: 'services.ApiClient' })
   .toProvider(ApiClientProvider);
 ```
+
+## Standalone Containers
+
+You can create independent DI containers using the `Container` class directly. These containers are **completely separate** from the application's context and do not share any bindings.
+
+### Creating an Independent Container
+
+```typescript
+import { Container, BindingScopes } from '@venizia/ignis-inversion';
+
+// Create a standalone container
+const container = new Container({ scope: 'MyCustomContainer' });
+
+// Bind dependencies
+container.bind({ key: 'config.apiKey' }).toValue('my-secret-key');
+container.bind({ key: 'services.Logger' }).toClass(LoggerService);
+container.bind({ key: 'services.Cache' })
+  .toClass(CacheService)
+  .setScope(BindingScopes.SINGLETON);
+
+// Resolve dependencies
+const logger = container.get<LoggerService>({ key: 'services.Logger' });
+const apiKey = container.getSync<string>({ key: 'config.apiKey' });
+```
+
+### Use Cases
+
+| Use Case | Description |
+|----------|-------------|
+| **Unit Testing** | Create isolated containers with mock dependencies for each test |
+| **Isolated Modules** | Build self-contained modules with their own dependency graph |
+| **Multi-Tenancy** | Separate containers per tenant with tenant-specific configurations |
+| **Worker Threads** | Independent containers for background workers |
+| **Plugin Systems** | Each plugin gets its own container to prevent conflicts |
+
+### Example: Testing with Isolated Container
+
+```typescript
+import { Container } from '@venizia/ignis-inversion';
+import { describe, it, expect, beforeEach } from 'bun:test';
+
+describe('UserService', () => {
+  let container: Container;
+
+  beforeEach(() => {
+    // Fresh container for each test
+    container = new Container({ scope: 'TestContainer' });
+
+    // Bind mock dependencies
+    container.bind({ key: 'repositories.UserRepository' }).toValue({
+      findById: async () => ({ id: '1', name: 'Test User' }),
+    });
+
+    container.bind({ key: 'services.UserService' }).toClass(UserService);
+  });
+
+  it('should find user by id', async () => {
+    const userService = container.get<UserService>({ key: 'services.UserService' });
+    const user = await userService.findById({ id: '1' });
+
+    expect(user.name).toBe('Test User');
+  });
+});
+```
+
+### Container vs Application
+
+| Aspect | `Application` (extends Container) | Standalone `Container` |
+|--------|-----------------------------------|------------------------|
+| **Purpose** | Full HTTP server with routing, middleware | Pure dependency injection |
+| **Bindings** | Shared across entire application | Isolated, no sharing |
+| **Lifecycle** | Managed by framework | You control it |
+| **Use Case** | Main application | Testing, isolated modules, workers |
+
+::: tip
+The `Application` class extends `Container`, so all container methods (`bind`, `get`, `getSync`) are available on your application instance. Standalone containers are useful when you need isolation from the main application context.
+:::
+
+## See Also
+
+- **Related Concepts:**
+  - [Application](/guides/core-concepts/application/) - Application extends Container
+  - [Controllers](/guides/core-concepts/controllers) - Use DI for injecting services
+  - [Services](/guides/core-concepts/services) - Use DI for injecting repositories
+  - [Providers](/references/base/providers) - Factory pattern for dynamic injection
+
+- **References:**
+  - [Dependency Injection API](/references/base/dependency-injection) - Complete API reference
+  - [Inversion Helper](/references/helpers/inversion) - DI container utilities
+  - [Glossary](/guides/reference/glossary#dependency-injection-di) - DI concepts explained
+
+- **Tutorials:**
+  - [Testing](/guides/tutorials/testing) - Unit testing with mocked dependencies
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DI in practice
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns and anti-patterns

package/wiki/guides/core-concepts/persistent/datasources.md

@@ -0,0 +1,179 @@
+# DataSources
+
+A DataSource manages database connections and supports **schema auto-discovery** from repositories.
+
+::: info PostgreSQL First
+IGNIS currently focuses on **PostgreSQL** as the primary database. Support for other database systems (MySQL, SQLite, etc.) is planned for future releases.
+:::
+
+## Creating a DataSource
+
+```typescript
+// src/datasources/postgres.datasource.ts
+import {
+  BaseDataSource,
+  datasource,
+  TNodePostgresConnector,
+  ValueOrPromise,
+} from '@venizia/ignis';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+
+interface IDSConfigs {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        host: process.env.POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.POSTGRES_PORT ?? 5432),
+        database: process.env.POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.POSTGRES_USER ?? 'postgres',
+        password: process.env.POSTGRES_PASSWORD ?? '',
+      },
+      // No schema needed - auto-discovered from @repository bindings!
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    // getSchema() auto-discovers models from @repository bindings
+    const schema = this.getSchema();
+
+    this.logger.debug(
+      '[configure] Auto-discovered schema | Keys: %o',
+      Object.keys(schema),
+    );
+
+    this.pool = new Pool(this.settings);
+    this.connector = drizzle({ client: this.pool, schema });
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    const { host, port, user, password, database } = this.settings;
+    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
+  }
+}
+```
+
+**How auto-discovery works:**
+
+1. `@repository` decorators register model-datasource bindings
+2. When `configure()` is called, `getSchema()` collects all bound models
+3. Drizzle is initialized with the complete schema
+
+## Manual Schema (Optional)
+
+If you need explicit control, you can still provide schema manually:
+
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: { /* ... */ },
+      schema: {
+        User: User.schema,
+        Configuration: Configuration.schema,
+        // Add relations if using Drizzle's relational queries
+      },
+    });
+  }
+}
+```
+
+## Registering a DataSource
+
+```typescript
+// src/application.ts
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    this.dataSource(PostgresDataSource);
+  }
+}
+```
+
+## Supported Drivers
+
+| Driver | Package | Status |
+|--------|---------|--------|
+| `node-postgres` | `pg` | ✅ Supported |
+| `mysql2` | `mysql2` | 🔜 Planned |
+| `better-sqlite3` | `better-sqlite3` | 🔜 Planned |
+
+## DataSource Template
+
+```typescript
+import { BaseDataSource, datasource, TNodePostgresConnector, ValueOrPromise } from '@venizia/ignis';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+
+interface IDSConfigs {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        host: process.env.POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.POSTGRES_PORT ?? 5432),
+        database: process.env.POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.POSTGRES_USER ?? 'postgres',
+        password: process.env.POSTGRES_PASSWORD ?? '',
+      },
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    const schema = this.getSchema();
+    this.pool = new Pool(this.settings);
+    this.connector = drizzle({ client: this.pool, schema });
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    const { host, port, user, password, database } = this.settings;
+    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
+  }
+}
+```
+
+> **Deep Dive:** See [BaseDataSource Reference](../../../references/base/datasources.md) for connection pooling and advanced configuration.
+
+## See Also
+
+- **Related Concepts:**
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Use DataSources for database access
+  - [Models](/guides/core-concepts/persistent/models) - Entity schemas loaded by DataSource
+  - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation database transactions
+  - [Application](/guides/core-concepts/application/) - Registering DataSources
+
+- **References:**
+  - [BaseDataSource API](/references/base/datasources) - Complete API reference
+  - [Environment Variables](/references/configuration/environment-variables) - Configuration management
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - ORM configuration
+  - [node-postgres Documentation](https://node-postgres.com/) - Connection pooling guide
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Connection pool tuning
+  - [Security Guidelines](/best-practices/security-guidelines) - Database credential management
+
+- **Tutorials:**
+  - [Complete Installation](/guides/tutorials/complete-installation) - Database setup
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DataSource configuration

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

@@ -0,0 +1,119 @@
+# Persistent Layer
+
+The persistent layer manages data using [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access and the Repository pattern for data abstraction.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Application                          │
+├─────────────────────────────────────────────────────────┤
+│  Controllers  →  Services  →  Repositories  →  Database │
+└─────────────────────────────────────────────────────────┘
+                                     ▲
+                                     │
+                    ┌────────────────┴────────────────┐
+                    │                                 │
+              ┌─────┴─────┐                   ┌───────┴───────┐
+              │  Models   │                   │  DataSources  │
+              │ (Schema)  │                   │ (Connection)  │
+              └───────────┘                   └───────────────┘
+```
+
+## Core Components
+
+| Component | Description | Learn More |
+|-----------|-------------|------------|
+| **Models** | Define data structure with Drizzle schemas and relations | [Models Guide](./models.md) |
+| **DataSources** | Manage database connections with auto-discovery | [DataSources Guide](./datasources.md) |
+| **Repositories** | Provide type-safe CRUD operations | [Repositories Guide](./repositories.md) |
+| **Transactions** | Handle atomic multi-step operations | [Transactions Guide](./transactions.md) |
+
+## Quick Example
+
+```typescript
+// 1. Define a Model
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
+  });
+
+  static override relations = () => [];
+}
+
+// 2. Create a DataSource
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        host: process.env.POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.POSTGRES_PORT ?? 5432),
+        database: process.env.POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.POSTGRES_USER ?? 'postgres',
+        password: process.env.POSTGRES_PASSWORD ?? '',
+      },
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    const schema = this.getSchema();
+    this.pool = new Pool(this.settings);
+    this.connector = drizzle({ client: this.pool, schema });
+  }
+}
+
+// 3. Create a Repository
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  async findByEmail(opts: { email: string }) {
+    return this.findOne({ filter: { where: { email: opts.email } } });
+  }
+}
+
+// 4. Use in Application
+export class Application extends BaseApplication {
+  preConfigure() {
+    this.dataSource(PostgresDataSource);
+    this.repository(UserRepository);
+  }
+}
+```
+
+## Next Steps
+
+1. **[Models](./models.md)** - Learn how to define your data structure
+2. **[DataSources](./datasources.md)** - Configure database connections
+3. **[Repositories](./repositories.md)** - Master CRUD operations and queries
+4. **[Transactions](./transactions.md)** - Handle atomic operations
+
+> **Deep Dive:** See [Repository Reference](../../../references/base/repositories/) for advanced filtering, relations, and operators.
+
+## See Also
+
+- **Persistent Layer Topics:**
+  - [Models](./models) - Entity definitions and schemas
+  - [DataSources](./datasources) - Database connections
+  - [Repositories](./repositories) - Data access layer
+  - [Transactions](./transactions) - Atomic operations
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Use repositories for business logic
+  - [Application](/guides/core-concepts/application/) - Registering persistent resources
+
+- **References:**
+  - [Models API](/references/base/models) - Complete models reference
+  - [DataSources API](/references/base/datasources) - Complete datasources reference
+  - [Repositories API](/references/base/repositories/) - Complete repositories reference
+  - [Filter System](/references/base/filter-system/) - Query operators
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - ORM guide
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Complete persistence example
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Advanced persistence patterns