@venizia/ignis-docs 0.0.1 → 0.0.3

package/wiki/get-started/best-practices/performance-optimization.md

@@ -40,17 +40,26 @@ Prevent blocking the event loop with Worker Threads:
 |-----------|---------|--------|
 | **Select specific fields** | `fields: { id: true, name: true }` | Reduce data transfer |
 | **Use indexes** | Create indexes on WHERE/JOIN columns | 10-100x faster queries |
+| **Mandatory Limit** | `limit: 20` | Prevent fetching massive datasets |
 | **Paginate results** | `limit: 20, offset: 0` | Prevent memory overflow |
 | **Eager load relations** | `include: [{ relation: 'creator' }]` | Solve N+1 problem |
 
+> [!TIP]
+> **Avoid Deep Nesting:** While Ignis supports deeply nested `include` filters, each level adds significant overhead to query construction and result mapping. We strongly recommend a **maximum of 2 levels** (e.g., `User -> Orders -> Items`). For more complex data fetching, consider separate queries.
+
 **Example:**
 ```typescript
 await userRepository.find({
   filter: {
     fields: { id: true, name: true, email: true },  // ✅ Specific fields
     where: { status: 'ACTIVE' },
-    limit: 20,                                       // ✅ Pagination
-    include: [{ relation: 'profile' }],             // ✅ Eager load
+    limit: 20,                                       // ✅ Mandatory limit
+    include: [{ 
+      relation: 'orders',
+      scope: {
+        include: [{ relation: 'items' }]             // ✅ Level 2 (Recommended limit)
+      }
+    }],
   },
 });
 ```

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

@@ -2,7 +2,7 @@
 
 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 technical details.
+> **Deep Dive:** See [Components Reference](../../references/base/components.md) for detailed implementation patterns, directory structure, and best practices.
 
 ## What is a Component?
 
@@ -13,86 +13,103 @@ A component is a class that extends `BaseComponent` and is responsible for:
 
 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.
 
-`Ignis` comes with several built-in components, which you can explore in the [**Components Reference**](../../references/components/) section:
+## Built-in Components
 
-- **`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.
+`Ignis` comes with several built-in components, which you can explore in the [**Components Reference**](../../references/components/) section:
 
-## Creating a Component
+| Component | Description |
+|-----------|-------------|
+| `AuthenticateComponent` | JWT-based authentication with token services |
+| `SwaggerComponent` | Interactive OpenAPI documentation |
+| `HealthCheckComponent` | Health check endpoints |
+| `RequestTrackerComponent` | Request logging and tracing |
+| `SocketIOComponent` | Real-time communication with Socket.IO |
+| `StaticAssetComponent` | File upload and storage management |
 
-To create a new component, extend the `BaseComponent` class. The constructor is the ideal place to define any **default bindings** that the component provides.
+## Creating a Simple Component
 
 ```typescript
-import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise, Binding, BindingScopes } from '@venizia/ignis';
+import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise, Binding } from '@venizia/ignis';
 
-// An example service that the component will provide
-class MyFeatureService {
-  // ... business logic
+// Define a service
+class NotificationService {
+  send(message: string) { /* ... */ }
 }
 
-// A controller that depends on the service
-@controller({ path: '/my-feature' })
-class MyFeatureController {
+// Define a controller
+@controller({ path: '/notifications' })
+class NotificationController extends BaseController {
   constructor(
-    @inject({ key: 'services.MyFeatureService' })
-    private myFeatureService: MyFeatureService
-  ) { /* ... */ }
+    @inject({ key: 'services.NotificationService' })
+    private notificationService: NotificationService
+  ) {
+    super({ scope: NotificationController.name });
+  }
 }
 
-export class MyFeatureComponent extends BaseComponent {
+// Create the component
+export class NotificationComponent extends BaseComponent {
   constructor(
     @inject({ key: CoreBindings.APPLICATION_INSTANCE })
     private application: BaseApplication,
   ) {
     super({
-      scope: MyFeatureComponent.name,
-      // Enable default bindings for this component
+      scope: NotificationComponent.name,
       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
+        'services.NotificationService': Binding.bind({ key: 'services.NotificationService' })
+          .toClass(NotificationService),
       },
     });
   }
 
   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);
+    this.application.controller(NotificationController);
   }
 }
 ```
 
 ## 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. |
+| **1. Instantiation** | `constructor()` | Component is created. Define default `bindings` here. |
+| **2. Configuration** | `binding()` | Called during startup. Register controllers and resources here. |
 
 ## Registering a Component
 
-To activate a component, you must register it with the application instance, usually in the `preConfigure` method of your `Application` class.
+Register components in your application's `preConfigure` method:
 
 ```typescript
-// in src/application.ts
-import { MyFeatureComponent } from './components/my-feature.component';
+// src/application.ts
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    this.component(HealthCheckComponent);
+    this.component(SwaggerComponent);
+    this.component(NotificationComponent);
+  }
+}
+```
 
-// ... inside your Application class
+## Customizing Component Options
 
+Most components accept configuration options. Override them before registration:
+
+```typescript
+// src/application.ts
+export class Application extends BaseApplication {
   preConfigure(): ValueOrPromise<void> {
-    // ...
-    this.component(MyFeatureComponent);
-    // ...
+    // Override options BEFORE registering component
+    this.bind<IHealthCheckOptions>({ key: HealthCheckBindingKeys.HEALTH_CHECK_OPTIONS })
+      .toValue({ restOptions: { path: '/api/health' } });
+
+    this.component(HealthCheckComponent);
   }
+}
 ```
 
-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.
+---
+
+> **Next Steps:**
+> - [Components Reference](../../references/base/components.md) - Directory structure, keys, types, constants patterns
+> - [Built-in Components](../../references/components/) - Detailed documentation for each component

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

@@ -418,21 +418,6 @@ export class Application extends BaseApplication {
 
 Ignis automatically optimizes "flat" queries (no relations, no field selection) by using Drizzle's Core API. This provides **~15-20% faster** queries for simple reads.
 
-### Transactions (Current)
-
-Currently, use Drizzle's callback-based `connector.transaction` for atomic operations:
-
-```typescript
-const ds = this.get<PostgresDataSource>({ key: 'datasources.PostgresDataSource' });
-
-await ds.connector.transaction(async (tx) => {
-  await tx.insert(User.schema).values({ /* ... */ });
-  await tx.insert(Configuration.schema).values({ /* ... */ });
-});
-```
-
-> **Note:** This callback-based approach requires all transaction logic to be in one callback. See [Section 5](#5-transactions-planned) for the planned improvement.
-
 ### Modular Persistence with Components
 
 Bundle related persistence resources into Components for better organization:
@@ -449,39 +434,41 @@ export class UserManagementComponent extends BaseComponent {
 
 ---
 
-## 5. Transactions (Planned)
-
-> **Status:** Planned - Not yet implemented. See [full plan](../../changelogs/planned-transaction-support).
-
-### The Problem
+## 5. Transactions
 
-Drizzle's callback-based transactions make it hard to pass transactions across services:
-
-```typescript
-// Current: Everything must be inside the callback
-await ds.connector.transaction(async (tx) => {
-  // Can't easily call other services with this tx
-});
-```
+Ignis supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
 
-### Planned Solution
+### Using Transactions
 
-Loopback 4-style explicit transaction objects that can be passed anywhere:
+To use transactions, start one from a repository or datasource, and then pass it to subsequent operations via the `options` parameter.
 
 ```typescript
-// Start transaction from repository
+// 1. Start a transaction
 const tx = await userRepo.beginTransaction({
-  isolationLevel: 'SERIALIZABLE'  // Optional, defaults to 'READ COMMITTED'
+  isolationLevel: 'SERIALIZABLE' // Optional, defaults to 'READ COMMITTED'
 });
 
 try {
-  // Pass tx to multiple services/repositories
-  const user = await userRepo.create({ data, options: { transaction: tx } });
-  await profileRepo.create({ data: { userId: user.id }, options: { transaction: tx } });
+  // 2. Pass transaction to operations
+  // Create user
+  const user = await userRepo.create({ 
+    data: userData, 
+    options: { transaction: tx } 
+  });
+
+  // Create profile (using same transaction)
+  await profileRepo.create({ 
+    data: { userId: user.id, ...profileData }, 
+    options: { transaction: tx } 
+  });
+
+  // Call a service method (passing the transaction)
   await orderService.createInitialOrder(user.id, { transaction: tx });
 
+  // 3. Commit the transaction
   await tx.commit();
 } catch (err) {
+  // 4. Rollback on error
   await tx.rollback();
   throw err;
 }
@@ -489,20 +476,29 @@ try {
 
 ### Isolation Levels
 
+Ignis supports standard PostgreSQL isolation levels:
+
 | Level | Description | Use Case |
 |-------|-------------|----------|
-| `READ COMMITTED` | Default. Sees only committed data | General use |
-| `REPEATABLE READ` | Snapshot from transaction start | Reports, consistent reads |
-| `SERIALIZABLE` | Full isolation, may throw errors | Financial, critical data |
-
-### Benefits
-
-| Aspect | Current (Callback) | Planned (Pass-through) |
-|--------|-------------------|------------------------|
-| Service composition | Hard | Easy - pass tx anywhere |
-| Separation of concerns | Services coupled | Services independent |
-| Testing | Complex mocking | Easy to mock tx |
-| Code organization | Nested callbacks | Flat, sequential |
+| `READ COMMITTED` | (Default) Queries see only data committed before the query began. | General use, prevents dirty reads. |
+| `REPEATABLE READ` | Queries see a snapshot as of the start of the transaction. | Reports, consistent reads across multiple queries. |
+| `SERIALIZABLE` | Strictest level. Emulates serial execution. | Financial transactions, critical data integrity. |
+
+### Best Practices
+
+1.  **Always use `try...catch...finally`**: Ensure `rollback()` is called on error to release the connection.
+2.  **Keep it short**: Long-running transactions hold database locks and connections.
+3.  **Pass explicit options**: When calling other services inside a transaction, ensure they accept and use the `transaction` option.
+
+```typescript
+// Service method supporting transactions
+async createInitialOrder(userId: string, opts?: { transaction?: ITransaction }) {
+  return this.orderRepository.create({
+    data: { userId, status: 'PENDING' },
+    options: { transaction: opts?.transaction } // Forward the transaction
+  });
+}
+```
 
 ---