@venizia/ignis-docs 0.0.2 → 0.0.4-0

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

package/wiki/get-started/best-practices/deployment-strategies.md

@@ -1,121 +0,0 @@
-# Deployment Strategies
-
-Deploy your Ignis application reliably, securely, and efficiently.
-
-## 1. Building for Production
-
-Compile TypeScript to JavaScript before deploying:
-
-```bash
-bun run build
-```
-
-**What this does:**
-1. `tsc -p tsconfig.json` - Compile TypeScript → JavaScript
-2. `tsc-alias -p tsconfig.json` - Replace path aliases (`@/*`) with relative paths
-
-**Output:** `dist/` folder with production-ready JavaScript.
-
-## 2. Environment Configuration
-
-Use environment variables for all configuration - never hard-code.
-
-**Production Environment Variables:**
-| Variable | Value | Purpose |
-|----------|-------|---------|
-| `NODE_ENV` | `production` | Enables performance optimizations |
-| `APP_ENV_APPLICATION_SECRET` | Strong random string | Application secret |
-| `APP_ENV_JWT_SECRET` | Strong random string | JWT signing key |
-| `APP_ENV_POSTGRES_*` | Production DB credentials | Database connection |
-| `APP_ENV_SERVER_HOST` | `0.0.0.0` | Accept connections from any IP |
-| `APP_ENV_SERVER_PORT` | `3000` or cloud-assigned | Server port |
-
-**Where to store:**
-- **Docker:** Use environment variables in `docker-compose.yml` or secrets
-- **Kubernetes:** ConfigMaps and Secrets
-- **Cloud Platforms:** AWS Secrets Manager, Azure Key Vault, Google Secret Manager
-
-## 3. Deployment Methods
-
-### Docker Deployment (Recommended)
-
-**Dockerfile:**
-```dockerfile
-FROM node:20-slim
-
-WORKDIR /usr/src/app
-
-# Copy dependency files
-COPY package.json bun.lockb ./
-
-# Install production dependencies
-RUN bun install --production
-
-# Copy source code
-COPY . .
-
-# Build TypeScript
-RUN bun run build
-
-# Expose port
-EXPOSE 3000
-
-# Start server
-CMD [ "bun", "run", "server:prod" ]
-```
-
-**Build and deploy:**
-```bash
-# Build image
-docker build -t my-ignis-app .
-
-# Run container
-docker run -p 3000:3000 \
-  -e NODE_ENV=production \
-  -e APP_ENV_APPLICATION_SECRET=xxx \
-  my-ignis-app
-```
-
-### Bun Single Executable (Alternative)
-
-Compile your app into a single standalone binary:
-
-```bash
-bun build --compile --minify --target=bun-linux-x64 \
-  ./src/index.ts --outfile ./dist/my-app
-```
-
-**Pros:** No dependencies needed on server, simple deployment
-**Cons:** Platform-specific, newer technology (test thoroughly)
-
-**Deploy:**
-```bash
-# Copy executable and .env to server
-scp dist/my-app .env user@server:/app/
-
-# Run
-./my-app
-```
-
-## 4. Production Best Practices
-
-**Use a process manager:**
-- **PM2** - For Node.js/Bun processes
-- **systemd** - Linux service management
-- **Docker/Kubernetes** - Built-in orchestration
-
-**Example with PM2:**
-```bash
-pm2 start dist/index.js --name my-app -i max
-pm2 save
-pm2 startup
-```
-
-**Health checks:**
-Add health check endpoint for load balancers:
-```typescript
-// In application.ts
-this.component(HealthCheckComponent);
-```
-
-Access at `/health-check` for liveness/readiness probes.

package/wiki/get-started/best-practices/performance-optimization.md

@@ -1,88 +0,0 @@
-# Performance Optimization
-
-Optimize your Ignis application for speed and scalability.
-
-## 1. Measure Performance
-
-Identify bottlenecks before optimizing:
-
-```typescript
-import { executeWithPerformanceMeasure } from '@venizia/ignis';
-
-await executeWithPerformanceMeasure({
-  logger: this.logger,
-  scope: 'DataProcessing',
-  description: 'Process large dataset',
-  task: async () => {
-    await processLargeDataset();
-  },
-});
-```
-
-Logs execution time automatically.
-
-> **Deep Dive:** See [Performance Utility](../../references/utilities/performance.md) for advanced profiling.
-
-## 2. Offload CPU-Intensive Tasks
-
-Prevent blocking the event loop with Worker Threads:
-
-**Use Worker Threads for:**
-- Complex calculations or crypto operations
-- Large file/data processing
-- Any synchronous task > 5ms
-
-> **Deep Dive:** See [Worker Thread Helper](../../references/helpers/worker-thread.md) for implementation guide.
-
-## 3. Optimize Database Queries
-
-| Technique | Example | Impact |
-|-----------|---------|--------|
-| **Select specific fields** | `fields: { id: true, name: true }` | Reduce data transfer |
-| **Use indexes** | Create indexes on WHERE/JOIN columns | 10-100x faster queries |
-| **Paginate results** | `limit: 20, offset: 0` | Prevent memory overflow |
-| **Eager load relations** | `include: [{ relation: 'creator' }]` | Solve N+1 problem |
-
-**Example:**
-```typescript
-await userRepository.find({
-  filter: {
-    fields: { id: true, name: true, email: true },  // ✅ Specific fields
-    where: { status: 'ACTIVE' },
-    limit: 20,                                       // ✅ Pagination
-    include: [{ relation: 'profile' }],             // ✅ Eager load
-  },
-});
-```
-
-## 4. Implement Caching
-
-Reduce database load with caching:
-
-| Cache Type | Use Case | Implementation |
-|-----------|----------|----------------|
-| **Redis** | Distributed cache, session storage | [Redis Helper](../../references/helpers/redis.md) |
-| **In-Memory** | Single-process cache | `MemoryStorageHelper` |
-
-**Example:**
-```typescript
-// Cache expensive query results
-const cached = await redis.get('users:active');
-if (!cached) {
-  const users = await userRepository.find({ where: { active: true } });
-  await redis.set('users:active', users, 300); // 5 min TTL
-}
-```
-
-## 5. Production Settings
-
-| Setting | Value | Why |
-|---------|-------|-----|
-| `NODE_ENV` | `production` | Enables library optimizations |
-| Process Manager | PM2, systemd, Docker | Auto-restart, cluster mode |
-| Cluster Mode | CPU cores | Utilize all CPUs |
-
-**PM2 Cluster Mode:**
-```bash
-pm2 start dist/index.js -i max  # Use all CPU cores
-```

package/wiki/get-started/best-practices/security-guidelines.md

@@ -1,99 +0,0 @@
-# Security Guidelines
-
-Critical security practices to protect your Ignis application.
-
-## 1. Secret Management
-
-**Never hard-code secrets.** Use environment variables for all sensitive data.
-
-| Environment | Where to Store Secrets |
-|-------------|----------------------|
-| Development | `.env` file (add to `.gitignore`) |
-| Production | Cloud provider's secret manager (AWS Secrets Manager, Azure Key Vault, etc.) |
-
-**Example `.env`:**
-```bash
-APP_ENV_APPLICATION_SECRET=your_strong_random_secret_here
-APP_ENV_JWT_SECRET=another_strong_random_secret_here
-APP_ENV_POSTGRES_PASSWORD=database_password_here
-```
-
-**Generate strong secrets:**
-```bash
-node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
-```
-
-## 2. Input Validation
-
-**Always validate incoming data** with Zod schemas. Ignis automatically rejects invalid requests.
-
-```typescript
-import { z } from '@hono/zod-openapi';
-import { jsonContent, jsonResponse } from '@venizia/ignis';
-
-const CreateUserRoute = {
-  method: 'post',
-  path: '/users',
-  request: {
-    body: jsonContent({
-      schema: z.object({
-        email: z.string().email(),           // Valid email
-        age: z.number().int().min(18),       // Adult only
-        role: z.enum(['user', 'admin']),     // Whitelist
-      }),
-    }),
-  },
-  responses: jsonResponse({ /* ... */ }),
-} as const;
-```
-
-**Validation happens automatically** - invalid requests never reach your handler.
-
-## 3. Authentication & Authorization
-
-Protect sensitive endpoints with `AuthenticateComponent`.
-
-**Setup:**
-```typescript
-// application.ts
-this.component(AuthenticateComponent);
-```
-
-**Protect routes:**
-```typescript
-const SecureRoute = {
-  path: '/admin/users',
-  authStrategies: [Authentication.STRATEGY_JWT], // Requires JWT
-  // ...
-};
-```
-
-> **Deep Dive:** See [Authentication Component](../../references/components/authentication.md) for full setup guide.
-
-**Access user in protected routes:**
-```typescript
-import { Authentication, IJWTTokenPayload, ApplicationError, getError } from '@venizia/ignis';
-
-const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
-if (!user.roles.includes('admin')) {
-    throw getError({ statusCode: 403, message: 'Forbidden' });
-}
-```
-
-## 4. Secure Dependencies
-
-Regularly audit and update dependencies:
-
-```bash
-# Check for vulnerabilities
-bun audit
-
-# Update dependencies
-bun update
-```
-
-**Critical packages to keep updated:**
-- `hono` - Web framework
-- `jose` - JWT handling
-- `drizzle-orm` - Database ORM
-- `@venizia/ignis` - Framework core

package/wiki/get-started/core-concepts/components.md

@@ -1,98 +0,0 @@
-# Components
-
-Components are reusable, pluggable modules that encapsulate a group of related features. A component acts as a powerful container for various resources—including providers, services, controllers, repositories, and even entire mini-applications—making it easy to share and integrate complex functionality across projects.
-
-> **Deep Dive:** See [Components Reference](../../references/base/components.md) for technical details.
-
-## What is a Component?
-
-A component is a class that extends `BaseComponent` and is responsible for:
-
-- **Binding Dependencies**: Registering services, controllers, repositories, providers, or other resources with the application's dependency injection container.
-- **Configuring Features**: Setting up middlewares, initializing services, or performing any other setup required for the feature to work.
-
-A single component can bundle everything needed for a specific domain—for example, an "AuthComponent" might include multiple services for token management, repositories for user data, and controllers for login/signup endpoints, essentially functioning as a plug-and-play mini-application.
-
-`Ignis` comes with several built-in components, which you can explore in the [**Components Reference**](../../references/components/) section:
-
-- **`AuthenticateComponent`**: Sets up JWT-based authentication.
-- **`SwaggerComponent`**: Generates interactive OpenAPI documentation.
-- **`HealthCheckComponent`**: Adds a health check endpoint.
-- **`RequestTrackerComponent`**: Adds request logging and tracing.
-- **`SocketIOComponent`**: Integrates Socket.IO for real-time communication.
-
-## Creating a Component
-
-To create a new component, extend the `BaseComponent` class. The constructor is the ideal place to define any **default bindings** that the component provides.
-
-```typescript
-import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise, Binding, BindingScopes } from '@venizia/ignis';
-
-// An example service that the component will provide
-class MyFeatureService {
-  // ... business logic
-}
-
-// A controller that depends on the service
-@controller({ path: '/my-feature' })
-class MyFeatureController {
-  constructor(
-    @inject({ key: 'services.MyFeatureService' })
-    private myFeatureService: MyFeatureService
-  ) { /* ... */ }
-}
-
-export class MyFeatureComponent extends BaseComponent {
-  constructor(
-    @inject({ key: CoreBindings.APPLICATION_INSTANCE })
-    private application: BaseApplication,
-  ) {
-    super({
-      scope: MyFeatureComponent.name,
-      // Enable default bindings for this component
-      initDefault: { enable: true, container: application },
-      // Define the default bindings this component provides
-      bindings: {
-        'services.MyFeatureService': Binding.bind({ key: 'services.MyFeatureService' })
-          .toClass(MyFeatureService)
-          .setScope(BindingScopes.SINGLETON), // Make it a singleton
-      },
-    });
-  }
-
-  override binding(): ValueOrPromise<void> {
-    // This is where you configure logic that USES the bindings.
-    // Here, we register a controller that depends on the service
-    // we just bound in the constructor.
-    this.application.controller(MyFeatureController);
-  }
-}
-```
-
-## Component Lifecycle
-
-Components have a simple, two-stage lifecycle managed by the application.
-
-| Stage | Method | Description |
-| :--- | :--- | :--- |
-| **1. Instantiation** | `constructor()` | The component is created by the DI container. This is where you call `super()` and define the component's `bindings`. If `initDefault` is enabled, these bindings are registered with the application container immediately. |
-| **2. Configuration**| `binding()` | Called by the application during the `registerComponents` startup phase. This is where you should set up resources (like controllers) that *depend* on the bindings you defined in the constructor. |
-
-## Registering a Component
-
-To activate a component, you must register it with the application instance, usually in the `preConfigure` method of your `Application` class.
-
-```typescript
-// in src/application.ts
-import { MyFeatureComponent } from './components/my-feature.component';
-
-// ... inside your Application class
-
-  preConfigure(): ValueOrPromise<void> {
-    // ...
-    this.component(MyFeatureComponent);
-    // ...
-  }
-```
-
-When the application starts, it will find the `MyFeatureComponent` binding, instantiate it, and then call its `binding()` method at the appropriate time. This modular approach keeps your main application class clean and makes it easy to toggle features on and off.