@venizia/ignis-docs 0.0.3 → 0.0.4-0

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,97 +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 |
-| **Mandatory Limit** | `limit: 20` | Prevent fetching massive datasets |
-| **Paginate results** | `limit: 20, offset: 0` | Prevent memory overflow |
-| **Eager load relations** | `include: [{ relation: 'creator' }]` | Solve N+1 problem |
-
-> [!TIP]
-> **Avoid Deep Nesting:** While Ignis supports deeply nested `include` filters, each level adds significant overhead to query construction and result mapping. We strongly recommend a **maximum of 2 levels** (e.g., `User -> Orders -> Items`). For more complex data fetching, consider separate queries.
-
-**Example:**
-```typescript
-await userRepository.find({
-  filter: {
-    fields: { id: true, name: true, email: true },  // ✅ Specific fields
-    where: { status: 'ACTIVE' },
-    limit: 20,                                       // ✅ Mandatory limit
-    include: [{ 
-      relation: 'orders',
-      scope: {
-        include: [{ relation: 'items' }]             // ✅ Level 2 (Recommended limit)
-      }
-    }],
-  },
-});
-```
-
-## 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