@venizia/ignis-docs 0.0.3 → 0.0.4-1

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(...);
-  }
-}
-```

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

@@ -1,177 +0,0 @@
-# Data Modeling
-
-Ignis streamlines data modeling with Drizzle ORM by providing powerful helpers and "enrichers" that reduce boilerplate code for common schema patterns.
-
-## 1. Base Entity
-
-All entity models should extend `BaseEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
-
-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, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
-import { pgTable } from 'drizzle-orm/pg-core';
-
-@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' }),
-  });
-
-  // 2. Define relations as a static method (return empty array if none)
-  static override relations = () => [];
-}
-```
-
-## 2. Schema Enrichers
-
-Instead of manually defining common columns like primary keys, timestamps, or audit fields in every table, use Ignis "enrichers".
-
-**Available Enrichers:**
-
-| Enricher | Description | Columns Added |
-|----------|-------------|---------------|
-| `generateIdColumnDefs` | Adds a Primary Key | `id` (string/UUID or number/Serial) |
-| `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. |
-| `extraUserColumns` | Comprehensive user fields | Combines audit, timestamps, status, and type fields |
-
-**Usage Example:**
-
-```typescript
-import {
-  generateIdColumnDefs,
-  generateTzColumnDefs,
-  generateUserAuditColumnDefs,
-} from '@venizia/ignis';
-import { pgTable, text } from 'drizzle-orm/pg-core';
-
-export const configurationTable = pgTable(
-  'Configuration',
-  {
-    // 1. Auto-generate UUID Primary Key
-    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-
-    // 2. Auto-generate createdAt / modifiedAt
-    ...generateTzColumnDefs(),
-
-    // 3. Auto-generate createdBy / modifiedBy
-    ...generateUserAuditColumnDefs({
-      created: { dataType: 'string', columnName: 'created_by' },
-      modified: { dataType: 'string', columnName: 'modified_by' },
-    }),
-
-    // 4. Your custom columns
-    code: text('code').notNull(),
-    description: text('description'),
-    group: text('group').notNull(),
-  },
-  (table) => [
-    // Define indexes/constraints here
-    unique('UQ_code').on(table.code),
-  ]
-);
-```
-
-## 3. Defining Relations
-
-Relations are defined using the `TRelationConfig` structure within the static `relations` method of your model.
-
-**Example (`src/models/entities/configuration.model.ts`):**
-
-```typescript
-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 ...
-
-  // Define relations
-  static override relations = (): TRelationConfig[] => [
-    {
-      name: 'creator',
-      type: RelationTypes.ONE,
-      schema: User.schema,
-      metadata: {
-        fields: [Configuration.schema.createdBy],
-        references: [User.schema.id],
-      },
-    },
-  ];
-}
-```
-
-## 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
-// 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)**
-
-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!
-}
-```
-
-**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 } } });
-  }
-}
-```