@venizia/ignis-docs 0.0.1-9 → 0.0.1

package/wiki/changelogs/planned-transaction-support.md

@@ -0,0 +1,216 @@
+---
+title: Planned - Transaction Support
+description: Implementation plan for Loopback 4-style explicit transaction objects
+---
+
+# Planned: Transaction Support
+
+**Status:** Planned (Not Yet Implemented)
+**Priority:** Future Enhancement
+
+## Goal
+
+Implement Loopback 4-style explicit transaction objects, allowing transactions to be passed through multiple services/repositories instead of using Drizzle's callback-based approach.
+
+## Target API
+
+```typescript
+// Default isolation level (READ COMMITTED)
+const tx = await userRepo.beginTransaction();
+
+// Or with specific isolation level
+const tx = await userRepo.beginTransaction({
+  isolationLevel: 'SERIALIZABLE'
+});
+
+try {
+  await userRepo.create({ data, options: { transaction: tx } });
+  await profileRepo.create({ data, options: { transaction: tx } });
+  await tx.commit();
+} catch (err) {
+  await tx.rollback();
+  throw err;
+}
+```
+
+### Isolation Levels
+
+| Level | Description | Use Case |
+|-------|-------------|----------|
+| `READ COMMITTED` | Default. Sees only committed data at query start | General use, most common |
+| `REPEATABLE READ` | Sees snapshot from transaction start | Reports, consistent reads |
+| `SERIALIZABLE` | Strictest. Full isolation, may throw serialization errors | Financial transactions, critical data |
+
+---
+
+## Implementation Steps
+
+### Step 1: Define Transaction Types
+
+**File:** `packages/core/src/base/datasources/types.ts`
+
+```typescript
+/** PostgreSQL transaction isolation levels */
+export type TIsolationLevel = 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE';
+
+/** Options for starting a transaction */
+export interface ITransactionOptions {
+  isolationLevel?: TIsolationLevel;
+}
+
+/** Transaction object returned by beginTransaction() */
+export interface ITransaction<Connector = TNodePostgresConnector> {
+  /** Isolated Drizzle instance bound to this transaction */
+  connector: Connector;
+
+  /** Commit the transaction */
+  commit(): Promise<void>;
+
+  /** Rollback the transaction */
+  rollback(): Promise<void>;
+
+  /** Check if transaction is still active */
+  isActive: boolean;
+
+  /** The isolation level used for this transaction */
+  isolationLevel: TIsolationLevel;
+}
+```
+
+### Step 2: Add `beginTransaction()` to DataSource
+
+**File:** `packages/core/src/base/datasources/base.ts`
+
+```typescript
+async beginTransaction(
+  opts?: ITransactionOptions
+): Promise<ITransaction<Connector>> {
+  // 1. Get raw client from pool
+  const pool = this.connector.client as Pool;
+  const client = await pool.connect();
+
+  // 2. Determine isolation level (default: READ COMMITTED)
+  const isolationLevel: TIsolationLevel = opts?.isolationLevel ?? 'READ COMMITTED';
+
+  // 3. Execute BEGIN with isolation level
+  await client.query(`BEGIN TRANSACTION ISOLATION LEVEL ${isolationLevel}`);
+
+  // 4. Create isolated Drizzle instance with this client
+  const txConnector = drizzle({ client, schema: this.schema });
+
+  // 5. Return transaction object
+  let isActive = true;
+
+  return {
+    connector: txConnector as Connector,
+    isActive,
+    isolationLevel,
+
+    async commit() {
+      if (!isActive) throw new Error('Transaction already ended');
+      try {
+        await client.query('COMMIT');
+      } finally {
+        isActive = false;
+        client.release();
+      }
+    },
+
+    async rollback() {
+      if (!isActive) throw new Error('Transaction already ended');
+      try {
+        await client.query('ROLLBACK');
+      } finally {
+        isActive = false;
+        client.release();
+      }
+    },
+  };
+}
+```
+
+### Step 3: Update Repository Base
+
+**File:** `packages/core/src/base/repositories/core/base.ts`
+
+```typescript
+// Add method to start transaction (delegates to DataSource)
+async beginTransaction(opts?: ITransactionOptions): Promise<ITransaction> {
+  return this.dataSource.beginTransaction(opts);
+}
+
+// Replace this.connector with getConnector(opts)
+protected getConnector(opts?: { transaction?: ITransaction }) {
+  if (opts?.transaction) {
+    if (!opts.transaction.isActive) {
+      throw getError({ message: 'Transaction is no longer active' });
+    }
+    return opts.transaction.connector;
+  }
+  return this.dataSource.connector;
+}
+```
+
+### Step 4: Update CRUD Options Types
+
+**File:** `packages/core/src/base/repositories/common/types.ts`
+
+```typescript
+export type TTransactionOption = {
+  transaction?: ITransaction;
+};
+
+// Add to existing option types
+export type TCreateOptions = TTransactionOption & {
+  shouldReturn?: boolean;
+  log?: TRepositoryLogOptions;
+};
+```
+
+### Step 5: Update CRUD Methods
+
+**Files:** `readable.ts`, `persistable.ts`
+
+Change all methods from:
+```typescript
+this.connector.insert(...)
+```
+
+To:
+```typescript
+this.getConnector(opts.options).insert(...)
+```
+
+---
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `packages/core/src/base/datasources/types.ts` | Add `TIsolationLevel`, `ITransactionOptions`, `ITransaction` |
+| `packages/core/src/base/datasources/base.ts` | Add `beginTransaction(opts?)` method |
+| `packages/core/src/base/repositories/common/types.ts` | Add `TTransactionOption` |
+| `packages/core/src/base/repositories/core/base.ts` | Add `beginTransaction(opts?)`, `getConnector(opts)` |
+| `packages/core/src/base/repositories/core/readable.ts` | Use `getConnector(opts)` in all methods |
+| `packages/core/src/base/repositories/core/persistable.ts` | Use `getConnector(opts)` in all methods |
+
+---
+
+## Breaking Changes
+
+1. **`this.connector`** → `this.getConnector(opts)`
+   - Backward compatible when called without args
+
+2. **Options parameter** - Now includes optional `transaction` field
+   - Non-breaking: transaction is optional
+
+---
+
+## Benefits
+
+| Aspect | Current (Drizzle Callback) | After (Pass-through) |
+|--------|---------------------------|----------------------|
+| Service composition | Hard - all in one callback | Easy - pass tx anywhere |
+| Separation of concerns | Services must know each other | Services stay independent |
+| Testing | Complex mocking | Easy to mock tx object |
+| Code organization | Nested callbacks | Flat, sequential flow |

package/wiki/changelogs/template.md

@@ -0,0 +1,123 @@
+---
+title: [Short Title]
+description: [Brief description of the changes]
+---
+
+# Changelog - YYYY-MM-DD
+
+## [Main Title/Focus Area]
+
+[A brief, high-level summary of the changes in this release. What is the main focus?]
+
+## Overview
+
+- **[Change 1]**: Brief description
+- **[Change 2]**: Brief description
+- **[Change 3]**: Brief description
+
+## Breaking Changes
+
+> [!WARNING]
+> This section contains changes that require migration or manual updates to existing code.
+
+### 1. [Breaking Change Title]
+
+**Before:**
+```typescript
+// Code that no longer works or is deprecated
+```
+
+**After:**
+```typescript
+// New pattern
+```
+
+## New Features
+
+### [Feature Name]
+
+**File:** `packages/core/src/path/to/file.ts`
+
+**Problem:** [What problem does this solve?]
+
+**Solution:** [How does it solve it?]
+
+```typescript
+// Example usage
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+
+## Security Fixes
+
+### [Security Issue Title]
+
+**Vulnerability:** [Describe the vulnerability]
+
+**Fix:** [Describe the fix]
+
+```typescript
+// Before: vulnerable code behavior
+// After: secure code behavior
+```
+
+## Performance Improvements
+
+### [Performance Improvement Title]
+
+**File:** `packages/core/src/path/to/file.ts`
+
+**Problem:** [What was slow/inefficient?]
+
+**Solution:** [How was it optimized?]
+
+| Scenario | Improvement |
+|----------|-------------|
+| [Use case 1] | [Improvement metric] |
+| [Use case 2] | [Improvement metric] |
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/models/base.ts` | [Description of changes] |
+| `src/base/repositories/core/readable.ts` | [Description of changes] |
+
+### Helpers Package (`packages/helpers`)
+
+| File | Changes |
+|------|---------|
+| `src/utils/index.ts` | [Description of changes] |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `src/models/entities/user.model.ts` | [Description of changes] |
+
+## Migration Guide
+
+> [!NOTE]
+> Follow these steps if you're upgrading from a previous version.
+
+### Step 1: [Action Name]
+
+[Instructions]
+
+```typescript
+// Example of the change to apply
+```
+
+### Step 2: [Action Name]
+
+[Instructions]
+
+## No Breaking Changes
+
+[Use this section instead of "Breaking Changes" and "Migration Guide" if there are no breaking changes]
+
+All changes are internal optimizations. No API changes or migration required.

package/wiki/get-started/best-practices/api-usage-examples.md

@@ -264,5 +264,3 @@ export class PageController extends BaseController {
   }
 }
 ```
-
-```

package/wiki/get-started/best-practices/architectural-patterns.md

@@ -90,7 +90,7 @@ export class ConfigurationController extends _Controller {
     // an instance of ConfigurationRepository here.
     @inject({
       key: BindingKeys.build({
-        namespace: BindingNames...REPOSITORY,
+        namespace: BindingNamespaces.REPOSITORY,
         key: ConfigurationRepository.name,
       }),
     })
@@ -103,7 +103,7 @@ export class ConfigurationController extends _Controller {
 
 ## 3. Component-Based Modularity
 
-Components bundle related features into self-contained, pluggable modules.
+Components bundle a group of related, reusable, and pluggable features into self-contained modules. A single component can encapsulate multiple providers, services, controllers, and repositories, essentially functioning as a mini-application that can be easily "plugged in" to any Ignis project.
 
 **Built-in Components:**
 - `AuthenticateComponent` - JWT authentication

package/wiki/get-started/best-practices/common-pitfalls.md

@@ -66,6 +66,8 @@ export class Application extends BaseApplication {
 
 -   **Bad:**
     ```typescript
+    import { ApplicationError, getError } from '@venizia/ignis';
+
     // In a Controller
     async createUser(c: Context) {
         const { name, email, companyName } = c.req.valid('json');
@@ -73,7 +75,7 @@ export class Application extends BaseApplication {
         // Complex logic inside the controller
         const existingUser = await this.userRepository.findByEmail(email);
         if (existingUser) {
-            throw new ApplicationError({ message: 'Email already exists' });
+            throw getError({ message: 'Email already exists' });
         }
         
         const company = await this.companyRepository.findOrCreate(companyName);
@@ -101,7 +103,7 @@ export class Application extends BaseApplication {
     }
     ```
 
-### 4. Missing Environment Variables
+## 4. Missing Environment Variables
 
 **Pitfall:** The application fails to start or behaves unexpectedly because required environment variables are not defined in your `.env` file. The framework validates variables prefixed with `APP_ENV_` by default.
 
@@ -121,7 +123,7 @@ APP_ENV_POSTGRES_PASSWORD=password
 APP_ENV_POSTGRES_DATABASE=db
 ```
 
-### 5. Not Using `as const` for Route Definitions
+## 5. Not Using `as const` for Route Definitions
 
 **Pitfall:** When using the decorator-based routing with a shared `ROUTE_CONFIGS` object, you forget to add `as const` to the object definition. TypeScript will infer the types too broadly, and you will lose the benefits of type-safe contexts (`TRouteContext`).
 

package/wiki/get-started/best-practices/contribution-workflow.md

@@ -56,6 +56,7 @@ The project uses a Makefile for common development tasks:
 **Individual package builds:**
 ```bash
 make core          # Build @venizia/ignis (after dependencies)
+make boot          # Build @venizia/ignis-boot
 make helpers       # Build @venizia/ignis-helpers
 make inversion     # Build @venizia/ignis-inversion
 make dev-configs   # Build @venizia/dev-configs
@@ -65,6 +66,7 @@ make docs          # Build documentation
 **Force update individual packages:**
 ```bash
 make update-core
+make update-boot
 make update-helpers
 make update-inversion
 make update-dev-configs

package/wiki/get-started/best-practices/data-modeling.md

@@ -6,26 +6,24 @@ Ignis streamlines data modeling with Drizzle ORM by providing powerful helpers a
 
 All entity models should extend `BaseEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
 
-**Example (`src/models/entities/configuration.model.ts`):**
+The recommended pattern is to define the schema and relations as **static properties** on the class. This keeps the definition self-contained and enables powerful type inference.
+
+**Example (`src/models/entities/user.model.ts`):**
 
 ```typescript
-import {
-  BaseEntity,
-  model,
-  TTableObject,
-} from '@venizia/ignis';
-import { configurationTable, configurationRelations } from './schema'; // Your Drizzle schema
+import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
+import { pgTable } from 'drizzle-orm/pg-core';
 
-// Define types for TypeScript inference
-export type TConfigurationSchema = typeof configurationTable;
-export type TConfiguration = TTableObject<TConfigurationSchema>;
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  // 1. Define schema as a static property
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...extraUserColumns({ idType: 'string' }),
+  });
 
-@model({ type: 'entity', skipMigrate: false })
-export class Configuration extends BaseEntity<typeof Configuration.schema> {
-  // Use static properties (recommended pattern)
-  static override schema = configurationTable;
-  static override relations = () => configurationRelations.definitions;
-  static override TABLE_NAME = 'Configuration';
+  // 2. Define relations as a static method (return empty array if none)
+  static override relations = () => [];
 }
 ```
 
@@ -41,7 +39,7 @@ Instead of manually defining common columns like primary keys, timestamps, or au
 | `generateTzColumnDefs` | Adds timestamps | `createdAt`, `modifiedAt` (auto-updating) |
 | `generateUserAuditColumnDefs` | Adds audit fields | `createdBy`, `modifiedBy` |
 | `generateDataTypeColumnDefs` | Adds generic value fields | `nValue` (number), `tValue` (text), `jValue` (json), etc. |
-| `generatePrincipalColumnDefs` | Adds polymorphic relation fields | `principalType`, `principalId` |
+| `extraUserColumns` | Comprehensive user fields | Combines audit, timestamps, status, and type fields |
 
 **Usage Example:**
 
@@ -82,39 +80,98 @@ export const configurationTable = pgTable(
 
 ## 3. Defining Relations
 
-Use the `createRelations` helper to define relationships cleanly. This abstracts the Drizzle `relations` function and makes it easy to bind to repositories.
+Relations are defined using the `TRelationConfig` structure within the static `relations` method of your model.
 
-**Example:**
+**Example (`src/models/entities/configuration.model.ts`):**
 
 ```typescript
-import { createRelations, RelationTypes } from '@venizia/ignis';
-import { userTable } from './user.model';
+import {
+  BaseEntity,
+  model,
+  RelationTypes,
+  TRelationConfig,
+} from '@venizia/ignis';
+import { User } from './user.model';
+
+@model({ type: 'entity' })
+export class Configuration extends BaseEntity<typeof Configuration.schema> {
+  // ... schema definition ...
 
-export const configurationRelations = createRelations({
-  source: configurationTable,
-  relations: [
+  // Define relations
+  static override relations = (): TRelationConfig[] => [
     {
       name: 'creator',
       type: RelationTypes.ONE,
-      schema: userTable,
+      schema: User.schema,
       metadata: {
-        fields: [configurationTable.createdBy],
-        references: [userTable.id],
+        fields: [Configuration.schema.createdBy],
+        references: [User.schema.id],
       },
     },
-  ],
-});
+  ];
+}
 ```
 
-This configuration is automatically used when you define your Repository with the `@repository` decorator:
+## 4. Repositories and Auto-Discovery
+
+Ignis simplifies the connection between models, repositories, and datasources.
+
+### DataSource Auto-Discovery
+
+DataSources automatically discover their schema from the repositories that bind to them. You **do not** need to manually register schemas in the DataSource constructor.
 
 ```typescript
-import { PostgresDataSource } from '@/datasources';
+// src/datasources/postgres.datasource.ts
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: { /* connection config */ },
+      // NO schema property needed - auto-discovered!
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    // This method automatically collects all schemas from bound repositories
+    const schema = this.getSchema();
+    this.connector = drizzle({ client: new Pool(this.settings), schema });
+  }
+}
+```
+
+### Repository Binding
+
+Repositories use the `@repository` decorator to bind a **Model** to a **DataSource**. This binding is what powers the auto-discovery mechanism.
+
+**Pattern 1: Zero Boilerplate (Recommended)**
 
-// Both 'model' and 'dataSource' are required for schema auto-discovery
+For most repositories, you don't need a constructor. The DataSource is automatically injected.
+
+```typescript
 @repository({ model: Configuration, dataSource: PostgresDataSource })
 export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {
-  // No constructor needed! DataSource and relations are auto-resolved
-  // from the @repository decorator and entity's static properties
+  // No constructor needed!
 }
 ```
+
+**Pattern 2: Explicit Injection (Advanced)**
+
+If you need to perform custom initialization or inject additional dependencies, you can define a constructor. **Important:** The first parameter must be the DataSource.
+
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends ReadableRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: PostgresDataSource,
+  ) {
+    super(dataSource);
+  }
+
+  // Custom methods
+  async findByRealm(realm: string) {
+    return this.findOne({ filter: { where: { realm } } });
+  }
+}
+```

package/wiki/get-started/best-practices/security-guidelines.md

@@ -72,9 +72,11 @@ const SecureRoute = {
 
 **Access user in protected routes:**
 ```typescript
+import { Authentication, IJWTTokenPayload, ApplicationError, getError } from '@venizia/ignis';
+
 const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
 if (!user.roles.includes('admin')) {
-    throw new ApplicationError({ statusCode: 403, message: 'Forbidden' });
+    throw getError({ statusCode: 403, message: 'Forbidden' });
 }
 ```
 

package/wiki/get-started/building-a-crud-api.md

@@ -645,7 +645,7 @@ For complex validation or business rules, create a Service layer:
 
 ```typescript
 // src/services/todo.service.ts
-import { BaseService, inject } from '@venizia/ignis';
+import { BaseService, inject, getError } from '@venizia/ignis';
 import { TodoRepository } from '@/repositories/todo.repository';
 
 export class TodoService extends BaseService {
@@ -659,7 +659,7 @@ export class TodoService extends BaseService {
   async createTodo(data: any) {
     // Business logic validation
     if (data.title.length < 3) {
-      throw new Error('Title too short');
+      throw getError({ message: 'Title too short' });
     }
 
     // Check for duplicates
@@ -667,7 +667,7 @@ export class TodoService extends BaseService {
       filter: { where: { title: data.title } },
     });
     if (existing) {
-      throw new Error('Todo already exists');
+      throw getError({ message: 'Todo already exists' });
     }
 
     return this.todoRepository.create({ data });