@venizia/ignis-docs 0.0.1-9 → 0.0.2

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