@venizia/ignis-docs 0.0.1 → 0.0.3

package/wiki/references/base/datasources.md

@@ -8,15 +8,17 @@ Technical reference for DataSource classes - managing database connections in Ig
 
 | Class/Interface | Purpose | Key Members |
 |-----------------|---------|-------------|
-| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()` |
+| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()`, `beginTransaction()` |
 | **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper` |
-| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator |
+| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator, transaction support |
+| **ITransaction** | Transaction object | `connector`, `isActive`, `commit()`, `rollback()` |
+| **IsolationLevels** | Isolation level constants | `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
 
 ## `IDataSource` Interface
 
 Contract for all datasource classes in the framework.
 
-**File:** `packages/core/src/base/datasources/types.ts`
+**File:** `packages/core/src/base/datasources/common/types.ts`
 
 ### Properties & Methods
 
@@ -24,10 +26,14 @@ Contract for all datasource classes in the framework.
 |--------|------|-------------|
 | `name` | `string` | Datasource name |
 | `settings` | `object` | Configuration object |
-| `connector` | `TDatabaseConnector` | Database connector instance (e.g., Drizzle) |
-| `getSchema()` | Method | Returns combined Drizzle schema (auto-discovered or manual) |
+| `connector` | `TNodePostgresConnector` | Database connector instance (Drizzle) |
+| `schema` | `Schema` | Combined Drizzle schema (auto-discovered or manual) |
+| `getSchema()` | Method | Returns combined Drizzle schema |
+| `getSettings()` | Method | Returns connection settings |
+| `getConnector()` | Method | Returns the Drizzle connector |
 | `configure()` | Method | Initializes the `connector` |
 | `getConnectionString()` | Method | Returns connection string |
+| `beginTransaction(opts?)` | Method | Starts a new database transaction |
 
 ## `AbstractDataSource` & `BaseDataSource`
 
@@ -264,4 +270,71 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 | `getConnector()` | Returns the Drizzle connector |
 | `hasDiscoverableModels()` | Returns `true` if there are models registered for this datasource |
 
+## Transaction Support
+
+DataSources provide built-in transaction management through the `beginTransaction()` method. This allows you to perform atomic operations across multiple repositories.
+
+### Transaction Types
+
+**File:** `packages/core/src/base/datasources/common/types.ts`
+
+| Type | Description |
+|------|-------------|
+| `ITransaction<Schema>` | Transaction object with `commit()`, `rollback()`, and `connector` |
+| `ITransactionOptions` | Options for starting a transaction (e.g., `isolationLevel`) |
+| `TIsolationLevel` | Union type: `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
+| `IsolationLevels` | Static class with isolation level constants and validation |
+
+### ITransaction Interface
+
+```typescript
+interface ITransaction<Schema> {
+  connector: TNodePostgresTransactionConnector<Schema>;
+  isActive: boolean;
+  isolationLevel: TIsolationLevel;
+
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+```
+
+### Isolation Levels
+
+Use the `IsolationLevels` static class for type-safe isolation level constants:
+
+```typescript
+import { IsolationLevels } from '@venizia/ignis';
+
+// Available levels
+IsolationLevels.READ_COMMITTED   // Default - prevents dirty reads
+IsolationLevels.REPEATABLE_READ  // Consistent reads within transaction
+IsolationLevels.SERIALIZABLE     // Strictest isolation
+
+// Validation
+IsolationLevels.isValid('READ COMMITTED'); // true
+IsolationLevels.isValid('INVALID');        // false
+```
+
+### Usage Example
+
+```typescript
+// Start transaction from datasource or repository
+const tx = await dataSource.beginTransaction({
+  isolationLevel: IsolationLevels.SERIALIZABLE
+});
+
+try {
+  // Use tx.connector for operations
+  await tx.connector.insert(userTable).values({ name: 'Alice' });
+  await tx.connector.insert(profileTable).values({ userId: '...', bio: 'Hello' });
+
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error;
+}
+```
+
+> **Note:** For most use cases, prefer using `repository.beginTransaction()` which provides a higher-level API. See [Repositories Reference](./repositories.md#transactions) for details.
+
 This architecture ensures that datasources are configured consistently and that the fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.

package/wiki/references/base/repositories.md

@@ -321,9 +321,86 @@ const results = await repo.createAll({
 // Type: Promise<TCount & { data: User[] }>
 ```
 
+### Generic Return Types
+
+For queries involving relations (`include`) or custom mapped types, you can override the return type of repository methods. This provides stronger type safety at the application layer without losing the convenience of the repository pattern.
+
+```typescript
+// Define custom return type with relations
+type ProductWithChannels = Product & {
+  saleChannelProducts: (SaleChannelProduct & {
+    saleChannel: SaleChannel
+  })[]
+};
+
+// Use generic override
+const product = await productRepo.findOne<ProductWithChannels>({
+  filter: {
+    where: { id: '...' },
+    include: [{
+      relation: 'saleChannelProducts',
+      scope: { include: [{ relation: 'saleChannel' }] }
+    }]
+  }
+});
+
+// TypeScript knows the structure!
+if (product) {
+  console.log(product.saleChannelProducts[0].saleChannel.name);
+}
+```
+
+**Supported Methods:**
+- `find<R>()`
+- `findOne<R>()`
+- `findById<R>()`
+- `create<R>()`, `createAll<R>()`
+- `updateById<R>()`, `updateAll<R>()`
+- `deleteById<R>()`, `deleteAll<R>()`
+
+### Transactions
+
+Repositories provide direct access to transaction management via the `beginTransaction()` method. This allows you to orchestrate atomic operations across multiple repositories or services.
+
+```typescript
+// Start a transaction
+const tx = await repo.beginTransaction();
+
+try {
+  // Perform operations within the transaction
+  const user = await userRepo.create({
+    data: { name: 'Alice' },
+    options: { transaction: tx } // Pass the transaction object
+  });
+
+  const profile = await profileRepo.create({
+    data: { userId: user.id, bio: 'Hello' },
+    options: { transaction: tx } // Use the same transaction
+  });
+
+  // Commit changes
+  await tx.commit();
+} catch (error) {
+  // Rollback on error
+  await tx.rollback();
+  throw error;
+}
+```
+
+**Isolation Levels:**
+You can specify the isolation level when starting a transaction:
+```typescript
+const tx = await repo.beginTransaction({
+  isolationLevel: 'SERIALIZABLE' // 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE'
+});
+```
+
 ### Relations Auto-Resolution
 
-Relations are now automatically resolved from the entity's static `relations` property:
+Relations are automatically resolved from the entity's static `relations` property. This resolution is **recursive**, allowing for deeply nested `include` queries across multiple levels of the entity graph.
+
+> [!WARNING]
+> **Performance Recommendation:** Each nested `include` adds significant overhead to SQL generation and result mapping. We strongly recommend a **maximum of 2 levels** (e.g., `Product -> Junction -> SaleChannel`). For deeper relationships, fetching data in multiple smaller queries is often more performant.
 
 ```typescript
 // Define entity with static relations
@@ -339,11 +416,17 @@ export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
   // No need to pass relations in constructor - auto-resolved!
 }
 
-// Relations are available for include queries
-const users = await repo.find({
+// Nested inclusion (Product -> Junction -> SaleChannel)
+const product = await repo.findOne({
   filter: {
-    where: { status: 'active' },
-    include: [{ relation: 'posts' }], // Works automatically
+    include: [
+      {
+        relation: 'saleChannelProducts', // Level 1
+        scope: {
+          include: [{ relation: 'saleChannel' }] // Level 2 (Nested)
+        }
+      }
+    ]
   }
 });
 ```
@@ -363,6 +446,9 @@ The `getQueryInterface()` method validates that the entity's schema is properly
 
 The `ReadableRepository` automatically optimizes flat queries (no relations, no field selection) using Drizzle's Core API instead of Query API. This provides ~15-20% performance improvement for simple queries.
 
+> [!IMPORTANT]
+> **Always use `limit`:** To ensure consistent performance and prevent memory exhaustion, always provide a `limit` in your filter options, especially for public-facing endpoints.
+
 **Automatic Optimization:**
 
 ```typescript
@@ -370,7 +456,7 @@ The `ReadableRepository` automatically optimizes flat queries (no relations, no
 const users = await repo.find({
   filter: {
     where: { status: 'active' },
-    limit: 10,
+    limit: 10,                       // ✅ Mandatory limit for performance
     order: ['createdAt DESC'],
   }
 });

package/wiki/references/helpers/index.md

@@ -6,6 +6,7 @@ Reusable classes and functions providing common functionality - designed for eas
 
 | Helper | Purpose | Key Features |
 |--------|---------|--------------|
+| [Common Types](./types.md) | Utility types | Nullable, resolvers, class types |
 | [Cron](./cron.md) | Job scheduling | Cron expressions, task management |
 | [Crypto](./crypto.md) | Cryptographic operations | Hashing, AES/RSA encryption/decryption |
 | [Environment](./env.md) | Environment variables | Centralized config access |

package/wiki/references/helpers/types.md

@@ -0,0 +1,151 @@
+# Common Types
+
+Utility types and helper functions for common TypeScript patterns.
+
+## Value Resolution Types
+
+Types for lazy/deferred value resolution patterns.
+
+### TResolver / TAsyncResolver
+
+```typescript
+type TResolver<T> = (...args: any[]) => T;
+type TAsyncResolver<T> = (...args: any[]) => T | Promise<T>;
+```
+
+Function types that resolve to a value. `TAsyncResolver` supports async functions.
+
+### TValueOrResolver / TValueOrAsyncResolver
+
+```typescript
+type TValueOrResolver<T> = T | TResolver<T>;
+type TValueOrAsyncResolver<T> = T | TAsyncResolver<T>;
+```
+
+Union types allowing either a direct value or a resolver function.
+
+**Usage:**
+
+```typescript
+import { TValueOrAsyncResolver, resolveValueAsync } from '@venizia/ignis-helpers';
+
+interface DatabaseConfig {
+  host: string;
+  port: number;
+}
+
+type ConfigOption = TValueOrAsyncResolver<DatabaseConfig>;
+
+// Direct value
+const config1: ConfigOption = { host: 'localhost', port: 5432 };
+
+// Sync resolver
+const config2: ConfigOption = () => ({ host: 'localhost', port: 5432 });
+
+// Async resolver
+const config3: ConfigOption = async () => {
+  const config = await fetchConfigFromVault();
+  return config;
+};
+
+// Resolve any of the above
+const resolved = await resolveValueAsync(config3);
+```
+
+### resolveValue / resolveValueAsync
+
+```typescript
+const resolveValue: <T>(valueOrResolver: TValueOrResolver<T>) => T;
+const resolveValueAsync: <T>(valueOrResolver: TValueOrAsyncResolver<T>) => Promise<T>;
+```
+
+Helper functions to resolve lazy values. They handle:
+- **Direct values**: returned as-is
+- **Class constructors**: returned as-is (not invoked)
+- **Resolver functions**: invoked and result returned
+
+## Nullable Types
+
+### TNullable
+
+```typescript
+type TNullable<T> = T | undefined | null;
+```
+
+Makes a type nullable (can be `undefined` or `null`).
+
+### ValueOrPromise
+
+```typescript
+type ValueOrPromise<T> = T | Promise<T>;
+```
+
+A value that may or may not be wrapped in a Promise.
+
+## Class Types
+
+### TConstructor / TAbstractConstructor
+
+```typescript
+type TConstructor<T> = new (...args: any[]) => T;
+type TAbstractConstructor<T> = abstract new (...args: any[]) => T;
+```
+
+Types representing class constructors.
+
+### TClass / TAbstractClass
+
+```typescript
+type TClass<T> = TConstructor<T> & { [property: string]: any };
+type TAbstractClass<T> = TAbstractConstructor<T> & { [property: string]: any };
+```
+
+Class types with static properties.
+
+### TMixinTarget / TAbstractMixinTarget
+
+```typescript
+type TMixinTarget<T> = TConstructor<{ [P in keyof T]: T[P] }>;
+type TAbstractMixinTarget<T> = TAbstractConstructor<{ [P in keyof T]: T[P] }>;
+```
+
+Types for mixin pattern targets.
+
+## Object Utility Types
+
+### ValueOf
+
+```typescript
+type ValueOf<T> = T[keyof T];
+```
+
+Extracts the value types from an object type.
+
+### ValueOptional / ValueOptionalExcept
+
+```typescript
+type ValueOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type ValueOptionalExcept<T, K extends keyof T> = Pick<T, K> & Partial<Omit<T, K>>;
+```
+
+Make specific keys optional while keeping others required, or vice versa.
+
+### TPrettify
+
+```typescript
+type TPrettify<T> = { [K in keyof T]: T[K] } & {};
+```
+
+Flattens intersection types for better IDE display.
+
+## Const Value Types
+
+### TStringConstValue / TNumberConstValue / TConstValue
+
+```typescript
+type TStringConstValue<T extends TClass<any>> = Extract<ValueOf<T>, string>;
+type TNumberConstValue<T extends TClass<any>> = Extract<ValueOf<T>, number>;
+type TConstValue<T extends TClass<any>> = Extract<ValueOf<T>, string | number>;
+```
+
+Extract constant value types from a class.

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

@@ -1,216 +0,0 @@
----
-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 |