@venizia/ignis-docs 0.0.1-1

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

@@ -0,0 +1,222 @@
+# 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,
+} 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' });
+  }
+
+  @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,
+    });
+  }
+}
+```
+
+### 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' });
+      },
+    });
+
+    // Using 'bindRoute' for a fluent API
+    this.bindRoute({
+      configs: ROUTE_CONFIGS['/3'],
+    }).to({
+      handler: context => {
+        return context.json({ message: 'Hello 3' });
+      },
+    });
+  }
+  // ...
+}
+```
+
+### 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
+});
+```

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

@@ -0,0 +1,129 @@
+# 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: BindingNames...REPOSITORY,
+        key: ConfigurationRepository.name,
+      }),
+    })
+    repository: ConfigurationRepository,
+  ) {
+    super(repository);
+  }
+}
+```
+
+## 3. Component-Based Modularity
+
+Components bundle related features into self-contained, pluggable modules.
+
+**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.

package/wiki/get-started/best-practices/code-style-standards.md

@@ -0,0 +1,122 @@
+# Code Style Standards
+
+Maintain consistent code style using **Prettier** (formatting) and **ESLint** (code quality). Ignis provides centralized configurations via the `@venizia/dev-configs` package.
+
+## Using @venizia/dev-configs
+
+Install the centralized development configurations:
+
+```bash
+bun add -d @venizia/dev-configs
+```
+
+This package provides:
+- **ESLint rules** - Pre-configured for Node.js/TypeScript projects
+- **Prettier settings** - Consistent formatting across all Ignis projects
+- **TypeScript configs** - Shared base and common configurations
+
+## Prettier Configuration
+
+Automatic code formatting eliminates style debates.
+
+**`.prettierrc.mjs`:**
+```javascript
+import { prettierConfigs } from '@venizia/dev-configs';
+
+export default prettierConfigs;
+```
+
+**Default Settings:**
+- `bracketSpacing: true` - `{ foo: bar }`
+- `singleQuote: false` - `"string"` (double quotes)
+- `printWidth: 100` - Maximum line length
+- `trailingComma: 'all'` - `[1, 2, 3,]`
+- `arrowParens: 'avoid'` - `x => x` not `(x) => x`
+- `semi: true` - Semicolons required
+
+**Customization:**
+```javascript
+import { prettierConfigs } from '@venizia/dev-configs';
+
+export default {
+  ...prettierConfigs,
+  printWidth: 120,  // Override specific settings
+};
+```
+
+**Usage:**
+```bash
+bun run prettier:cli      # Check formatting
+bun run prettier:fix      # Auto-fix
+```
+
+**IDE Integration:** Configure your editor to format on save.
+
+## ESLint Configuration
+
+Prevents common errors and enforces best practices.
+
+**`eslint.config.mjs`:**
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+export default eslintConfigs;
+```
+
+**Includes:**
+- Pre-configured rules for Node.js/TypeScript (via `@minimaltech/eslint-node`)
+- Disables `@typescript-eslint/no-explicit-any` by default
+
+**Customization:**
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+export default [
+  ...eslintConfigs,
+  {
+    rules: {
+      'no-console': 'warn',  // Add project-specific rules
+    },
+  },
+];
+```
+
+**Usage:**
+```bash
+bun run eslint           # Check for issues
+bun run eslint --fix     # Auto-fix issues
+bun run lint:fix         # Run both ESLint + Prettier
+```
+
+**Pre-commit Hook:** Add ESLint to your pre-commit hooks to catch issues before committing.
+
+## TypeScript Configuration
+
+Use the centralized TypeScript configs:
+
+**`tsconfig.json`:**
+```json
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "@venizia/dev-configs/tsconfig.common.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": "src",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**What's Included:**
+- `target: ES2022` - Modern JavaScript features
+- `experimentalDecorators: true` - Required for Ignis decorators
+- `emitDecoratorMetadata: true` - Metadata reflection for DI
+- `strict: true` - Strict type checking with selective relaxations
+- `skipLibCheck: true` - Faster compilation
+
+See [`@venizia/dev-configs` documentation](../../references/src-details/dev-configs.md) for full details.

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

@@ -0,0 +1,136 @@
+# Common Pitfalls
+
+Avoid these common mistakes when building Ignis applications.
+
+## 1. Forgetting to Register Resources
+
+**Problem:** Created a Controller/Service/Repository but getting `Binding not found` errors.
+
+**Solution:** Register in `application.ts` → `preConfigure()`:
+
+**Example (`src/application.ts`):**
+```typescript
+// ...
+import { MyNewController } from './controllers';
+import { MyNewService } from './services';
+// ...
+
+export class Application extends BaseApplication {
+  // ...
+  preConfigure(): ValueOrPromise<void> {
+    // DataSources
+    this.dataSource(PostgresDataSource);
+
+    // Repositories
+    this.repository(ConfigurationRepository);
+
+    // Services
+    this.service(MyNewService); // <-- Don't forget this line
+    this.registerAuth();
+
+    // Controllers
+    this.controller(TestController);
+    this.controller(MyNewController); // <-- Or this line
+
+    // Components
+    this.component(HealthCheckComponent);
+  }
+  // ...
+}
+```
+
+## 2. Incorrect Injection Keys
+
+**Problem:** `Binding not found` when using `@inject`.
+
+**Solution:** Use `BindingKeys.build()` helper:
+
+```typescript
+// ✅ GOOD
+@inject({
+  key: BindingKeys.build({
+    namespace: BindingNamespaces.REPOSITORY,
+    key: ConfigurationRepository.name,
+  }),
+})
+
+// ❌ BAD - typo in string
+@inject({ key: 'repositories.ConfigurationRepositry' })
+```
+
+## 3. Business Logic in Controllers
+
+**Problem:** Complex logic in controller methods makes them hard to test and maintain.
+
+**Solution:** Move business logic to Services. Controllers should only handle HTTP.
+
+-   **Bad:**
+    ```typescript
+    // In a Controller
+    async createUser(c: Context) {
+        const { name, email, companyName } = c.req.valid('json');
+        
+        // Complex logic inside the controller
+        const existingUser = await this.userRepository.findByEmail(email);
+        if (existingUser) {
+            throw new ApplicationError({ message: 'Email already exists' });
+        }
+        
+        const company = await this.companyRepository.findOrCreate(companyName);
+        const user = await this.userRepository.create({ name, email, companyId: company.id });
+        
+        return c.json(user);
+    }
+    ```
+-   **Good:**
+    ```typescript
+    // In a Controller
+    async createUser(c: Context) {
+        const userData = c.req.valid('json');
+        // Delegate to the service
+        const newUser = await this.userService.createUser(userData);
+        return c.json(newUser);
+    }
+    
+    // In UserService
+    async createUser(data) {
+        // All the complex logic now resides in the service
+        const existingUser = await this.userRepository.findByEmail(data.email);
+        // ...
+        return await this.userRepository.create(...);
+    }
+    ```
+
+### 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.
+
+**Solution:** Always create a `.env` file for your local development by copying `.env.example`. Ensure all required variables, especially secrets and database connection details, are filled in.
+
+**Example (`.env.example`):**
+```
+# Ensure these have strong, unique values in your .env file
+APP_ENV_APPLICATION_SECRET=
+APP_ENV_JWT_SECRET=
+
+# Ensure these point to your local database
+APP_ENV_POSTGRES_HOST=0.0.0.0
+APP_ENV_POSTGRES_PORT=5432
+APP_ENV_POSTGRES_USERNAME=postgres
+APP_ENV_POSTGRES_PASSWORD=password
+APP_ENV_POSTGRES_DATABASE=db
+```
+
+### 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`).
+
+**Solution:** Always use `as const` when exporting a shared route configuration object.
+
+**Example (`src/controllers/test/definitions.ts`):**
+```typescript
+export const ROUTE_CONFIGS = {
+  // ... your route definitions
+} as const; // <-- This is crucial!
+```
+This ensures that `TRouteContext<typeof ROUTE_CONFIGS['/path']>` has the precise types for request body, params, and response.