@venizia/ignis-docs 0.0.2 → 0.0.4-0

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 |

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

@@ -1,266 +0,0 @@
-# API Usage Examples
-
-Practical examples for defining endpoints and working with data in Ignis applications.
-
-## Routing Patterns
-
-### Decorator-Based Routing (Recommended)
-
-Use `@get`, `@post` decorators with `as const` route configs for full type safety:
-
-**`src/controllers/test/definitions.ts`**
-```typescript
-import { z } from '@hono/zod-openapi';
-import { Authentication, HTTP, jsonContent, jsonResponse } from '@venizia/ignis';
-
-// Define route configs as const for type inference
-export const ROUTE_CONFIGS = {
-  // ... (other routes)
-  ['/4']: {
-    method: HTTP.Methods.GET,
-    path: '/4',
-    responses: jsonResponse({
-      description: 'Test decorator GET endpoint',
-      schema: z.object({ message: z.string(), method: z.string() }),
-    }),
-  },
-  ['/5']: {
-    method: HTTP.Methods.POST,
-    path: '/5',
-    authStrategies: [Authentication.STRATEGY_JWT], // Secure this endpoint
-    request: {
-      body: jsonContent({
-        description: 'Request body for POST',
-        schema: z.object({ name: z.string(), age: z.number().int().positive() }),
-      }),
-    },
-    responses: jsonResponse({
-      description: 'Test decorator POST endpoint',
-      schema: z.object({ id: z.string(), name: z.string(), age: z.number() }),
-    }),
-  },
-} as const;
-```
-
-Then, use the decorators in your controller class. The `TRouteContext` type provides a fully typed context, including request parameters, body, and response types.
-
-**`src/controllers/test/controller.ts`**
-```typescript
-import {
-  BaseController,
-  controller,
-  get,
-  post,
-  TRouteContext,
-  HTTP,
-} from '@venizia/ignis';
-import { ROUTE_CONFIGS } from './definitions';
-
-@controller({ path: '/test' })
-export class TestController extends BaseController {
-  // ...
-
-  @get({ configs: ROUTE_CONFIGS['/4'] })
-  getWithDecorator(context: TRouteContext<(typeof ROUTE_CONFIGS)['/4']>) {
-    // context is fully typed!
-    return context.json({ message: 'Hello from decorator', method: 'GET' }, HTTP.ResultCodes.RS_2.Ok);
-  }
-
-  @post({ configs: ROUTE_CONFIGS['/5'] })
-  createWithDecorator(context: TRouteContext<(typeof ROUTE_CONFIGS)['/5']>) {
-    // context.req.valid('json') is automatically typed as { name: string, age: number }
-    const body = context.req.valid('json');
-
-    // The response is validated against the schema
-    return context.json(
-      {
-        id: crypto.randomUUID(),
-        name: body.name,
-        age: body.age,
-      },
-      HTTP.ResultCodes.RS_2.Ok,
-    );
-  }
-}
-```
-
-### Example 2: Manual Route Definition in `binding()`
-
-You can also define routes manually within the controller's `binding()` method using `defineRoute` or `bindRoute`. This is useful for more complex scenarios or for developers who prefer a non-decorator syntax.
-
-**`src/controllers/test/controller.ts`**
-```typescript
-import { BaseController, controller, HTTP, ValueOrPromise } from '@venizia/ignis';
-import { ROUTE_CONFIGS } from './definitions';
-
-@controller({ path: '/test' })
-export class TestController extends BaseController {
-  // ...
-  override binding(): ValueOrPromise<void> {
-    // Using 'defineRoute'
-    this.defineRoute({
-      configs: ROUTE_CONFIGS['/1'],
-      handler: context => {
-        return context.json({ message: 'Hello' }, HTTP.ResultCodes.RS_2.Ok);
-      },
-    });
-
-    // Using 'bindRoute' for a fluent API
-    this.bindRoute({
-      configs: ROUTE_CONFIGS['/3'],
-    }).to({
-      handler: context => {
-        return context.json({ message: 'Hello 3' }, HTTP.ResultCodes.RS_2.Ok);
-      },
-    });
-  }
-  // ...
-}
-```
-
-### Example 3: Auto-Generated CRUD Controller
-
-For standard database entities, you can use `ControllerFactory.defineCrudController` to instantly generate a controller with a full set of CRUD endpoints.
-
-**`src/controllers/configuration.controller.ts`**
-```typescript
-import { Configuration } from '@/models';
-import { ConfigurationRepository } from '@/repositories';
-import {
-  BindingKeys,
-  BindingNamespaces,
-  controller,
-  ControllerFactory,
-  inject,
-} from '@venizia/ignis';
-
-const BASE_PATH = '/configurations';
-
-// 1. The factory generates a controller class with all CRUD routes
-const _Controller = ControllerFactory.defineCrudController({
-  repository: { name: ConfigurationRepository.name },
-  controller: {
-    name: 'ConfigurationController',
-    basePath: BASE_PATH,
-  },
-  entity: () => Configuration, // The entity is used to generate OpenAPI schemas
-});
-
-// 2. Extend the generated controller to inject the repository
-@controller({ path: BASE_PATH })
-export class ConfigurationController extends _Controller {
-  constructor(
-    @inject({
-      key: BindingKeys.build({
-        namespace: BindingNamespaces.REPOSITORY,
-        key: ConfigurationRepository.name,
-      }),
-    })
-    repository: ConfigurationRepository,
-  ) {
-    super(repository);
-  }
-}
-```
-This automatically creates endpoints like `GET /configurations`, `POST /configurations`, `GET /configurations/:id`, etc.
-
-## Repository (Data Access) Usage
-
-Repositories are used to interact with your database. The `DefaultCRUDRepository` provides a rich set of methods for data manipulation. Here are examples from the `postConfigure` method in `src/application.ts`, which demonstrates how to use an injected repository.
-
-```typescript
-// In src/application.ts
-
-// Get the repository instance from the DI container
-const configurationRepository = this.get<ConfigurationRepository>({
-  key: BindingKeys.build({
-    namespace: BindingNamespaces.REPOSITORY,
-    key: ConfigurationRepository.name,
-  }),
-});
-
-// --- Find One Record ---
-const record = await configurationRepository.findOne({
-  filter: { where: { code: 'CODE_1' } },
-});
-
-// --- Find Multiple Records with Relations ---
-const records = await configurationRepository.find({
-  filter: {
-    where: { code: 'CODE_2' },
-    fields: { id: true, code: true, createdBy: true },
-    limit: 100,
-    include: [{ relation: 'creator' }], // Eager load the 'creator' relation
-  },
-});
-
-// --- Create a Single Record ---
-const newRecord = await configurationRepository.create({
-  data: {
-    code: 'NEW_CODE',
-    group: 'SYSTEM',
-    dataType: 'TEXT',
-    tValue: 'some value',
-  },
-});
-
-// --- Create Multiple Records ---
-const newRecords = await configurationRepository.createAll({
-  data: [
-    { code: 'CODE_A', group: 'SYSTEM' },
-    { code: 'CODE_B', group: 'SYSTEM' },
-  ],
-});
-
-// --- Update a Record by ID ---
-const updated = await configurationRepository.updateById({
-  id: 'some-uuid',
-  data: { tValue: 'new value' },
-});
-
-// --- Delete a Record by ID ---
-const deleted = await configurationRepository.deleteById({
-  id: newRecord.data!.id,
-  options: { shouldReturn: true }, // Option to return the deleted record
-});
-
-## Server-Side Rendering (JSX)
-
-Ignis supports server-side rendering using Hono's JSX middleware. This is useful for returning HTML content, such as landing pages or simple admin views.
-
-**Usage:**
-
-Use `defineJSXRoute` in your controller and `htmlResponse` for documentation.
-
-```typescript
-import { BaseController, controller, htmlResponse } from '@venizia/ignis';
-
-@controller({ path: '/pages' })
-export class PageController extends BaseController {
-  
-  override binding(): void {
-    this.defineJSXRoute({
-      configs: {
-        method: 'get',
-        path: '/welcome',
-        description: 'Welcome Page',
-        responses: htmlResponse({ description: 'HTML Welcome Page' }),
-      },
-      handler: (c) => {
-        const title = 'Welcome to Ignis';
-        
-        // Return JSX directly
-        return c.html(
-          <html>
-            <head><title>{title}</title></head>
-            <body>
-              <h1>{title}</h1>
-              <p>Server-side rendered content.</p>
-            </body>
-          </html>
-        );
-      },
-    });
-  }
-}
-```

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

@@ -1,170 +0,0 @@
-# Architectural Patterns
-
-Ignis promotes separation of concerns, dependency injection, and modularity for scalable, maintainable applications.
-
-> **Deep Dive:** See [Core Framework Reference](../../references/src-details/core.md) for implementation details.
-
-## 1. Layered Architecture
-
-Each layer has a single responsibility. Ignis supports **two architectural approaches**:
-
-```mermaid
-graph TD
-    Client[Client/API Consumer]
-
-    Client -->|HTTP Request| Controller[Controllers]
-
-    Controller -->|Simple CRUD| Repo[Repositories]
-    Controller -->|Complex Logic| Service[Services]
-
-    Service --> Repo
-
-    Repo --> DataSource[DataSources]
-    DataSource --> DB[(Database)]
-
-    style Service fill:#e1f5ff
-    style Repo fill:#fff4e1
-    style Controller fill:#ffe1f5
-```
-
-| Layer | Responsibility | Example |
-|-------|---------------|---------|
-| **Controllers** | Handle HTTP - parse requests, validate, format responses | `ConfigurationController` (uses `ControllerFactory`) |
-| **Services** | Business logic - orchestrate operations | `AuthenticationService` (auth logic) |
-| **Repositories** | Data access - CRUD operations | `ConfigurationRepository` (extends `DefaultCRUDRepository`) |
-| **DataSources** | Database connections | `PostgresDataSource` (connects to PostgreSQL) |
-| **Models** | Data structure - Drizzle schemas + Entity classes | `Configuration`, `User` models |
-
-**Key Principle - Two Approaches:**
-
-```
-Simple CRUD (no business logic):
-┌────────────┐
-│ Controller │──────────────┐
-└────────────┘              │
-                            ▼
-                    ┌──────────────┐
-                    │  Repository  │
-                    └──────────────┘
-                            │
-                            ▼
-                        Database
-
-Complex Logic (validation, orchestration):
-┌────────────┐
-│ Controller │────┐
-└────────────┘    │
-                  ▼
-            ┌─────────┐
-            │ Service │
-            └─────────┘
-                  │
-                  ▼
-          ┌──────────────┐
-          │  Repository  │
-          └──────────────┘
-                  │
-                  ▼
-              Database
-```
-
-**When to use each:**
-- **Controller → Repository** - Simple CRUD (list, get by ID, create, update, delete)
-- **Controller → Service → Repository** - Business logic, validation, orchestrating multiple repositories
-
-## 2. Dependency Injection (DI)
-
-Classes declare dependencies in their constructor - the framework automatically provides them at runtime.
-
-**Benefits:**
-- Loosely coupled code
-- Easy to test (mock dependencies)
-- Easy to swap implementations
-
-**Example:**
-```typescript
-@controller({ path: BASE_PATH })
-export class ConfigurationController extends _Controller {
-  constructor(
-    // The @inject decorator tells the container to provide
-    // an instance of ConfigurationRepository here.
-    @inject({
-      key: BindingKeys.build({
-        namespace: BindingNamespaces.REPOSITORY,
-        key: ConfigurationRepository.name,
-      }),
-    })
-    repository: ConfigurationRepository,
-  ) {
-    super(repository);
-  }
-}
-```
-
-## 3. Component-Based Modularity
-
-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
-- `SwaggerComponent` - OpenAPI documentation
-- `HealthCheckComponent` - Health check endpoint
-- `RequestTrackerComponent` - Request logging
-
-**Example:**
-```typescript
-// src/application.ts
-
-export class Application extends BaseApplication {
-  // ...
-  preConfigure(): ValueOrPromise<void> {
-    // ...
-    // Registering components plugs their functionality into the application.
-    this.component(HealthCheckComponent);
-    this.component(SwaggerComponent);
-    // ...
-  }
-}
-```
-This architecture keeps the main `Application` class clean and focused on high-level assembly, while the details of each feature are neatly encapsulated within their respective components.
-
-## 4. Custom Components
-
-You can encapsulate your own logic or third-party integrations (like Socket.IO, Redis, specific Cron jobs) into reusable Components.
-
-**Structure of a Component:**
-1.  Extend `BaseComponent`.
-2.  Define default `bindings` (optional configuration/options).
-3.  Implement `binding()` to register services, providers, or attach logic to the application.
-
-**Example (`SocketIOComponent`):**
-
-```typescript
-import { BaseComponent, inject, CoreBindings, Binding } from '@venizia/ignis';
-
-export class MySocketComponent extends BaseComponent {
-  constructor(
-    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
-  ) {
-    super({
-      scope: MySocketComponent.name,
-      // Automatically register bindings when component is loaded
-      initDefault: { enable: true, container: application },
-      bindings: {
-        // Define default configuration binding
-        'my.socket.options': Binding.bind({ key: 'my.socket.options' }).toValue({ port: 8080 }),
-      },
-    });
-  }
-
-  // The binding method is called during application startup (preConfigure)
-  override binding(): void {
-    const options = this.application.get({ key: 'my.socket.options' });
-    
-    this.logger.info('Initializing Socket.IO with options: %j', options);
-    
-    // Perform setup logic, register other services, etc.
-    // this.application.bind(...).toValue(...);
-  }
-}
-```