@venizia/ignis-docs 0.0.4-1 → 0.0.4-2

package/wiki/best-practices/error-handling.md

@@ -0,0 +1,468 @@
+# Error Handling
+
+Comprehensive guide to handling errors gracefully in Ignis applications.
+
+## Error Handling Philosophy
+
+| Principle | Description |
+|-----------|-------------|
+| **Fail Fast** | Detect and report errors as early as possible |
+| **Don't Swallow** | Never catch errors without logging or re-throwing |
+| **User-Friendly** | Return clear, actionable messages to clients |
+| **Debuggable** | Include context for debugging in logs |
+
+## 1. Using `getError` Helper
+
+Ignis provides `getError` for creating consistent, structured errors.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis';
+
+// Basic error
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+  message: 'User not found',
+});
+
+// Error with details
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+  message: 'Invalid request',
+  details: {
+    field: 'email',
+    reason: 'Must be a valid email address',
+  },
+});
+
+// Error with context (for logging)
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+  message: '[UserService][create] Database connection failed',
+  details: { userId: requestedId },
+});
+```
+
+## 2. HTTP Status Code Reference
+
+Use the correct status code for each error type:
+
+| Code | Constant | Use When |
+|------|----------|----------|
+| 400 | `RS_4.BadRequest` | Invalid input format, missing required fields, database constraint violations (auto-handled) |
+| 401 | `RS_4.Unauthorized` | Missing or invalid authentication |
+| 403 | `RS_4.Forbidden` | Authenticated but insufficient permissions |
+| 404 | `RS_4.NotFound` | Resource does not exist |
+| 409 | `RS_4.Conflict` | Resource already exists (custom duplicate handling) |
+| 422 | `RS_4.UnprocessableEntity` | Validation failed (Zod errors) |
+| 429 | `RS_4.TooManyRequests` | Rate limit exceeded |
+| 500 | `RS_5.InternalServerError` | Unexpected server error |
+| 502 | `RS_5.BadGateway` | External service failed |
+| 503 | `RS_5.ServiceUnavailable` | Service temporarily down |
+
+:::tip Automatic Database Error Handling
+Database constraint violations (unique, foreign key, not null, check) are automatically converted to HTTP 400 by the global error middleware. You don't need to catch these errors manually.
+:::
+
+## 3. Error Handling Patterns
+
+### Service Layer Errors
+
+```typescript
+import { BaseService, getError, HTTP } from '@venizia/ignis';
+
+export class UserService extends BaseService {
+  async createUser(data: TCreateUserRequest): Promise<TUser> {
+    // Validate business rules
+    const existingUser = await this.userRepo.findOne({
+      filter: { where: { email: data.email } },
+    });
+
+    if (existingUser.data) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Conflict,
+        message: 'Email already registered',
+        details: { email: data.email },
+      });
+    }
+
+    // Handle external service errors
+    try {
+      await this.emailService.sendWelcome(data.email);
+    } catch (error) {
+      // Log but don't fail user creation
+      this.logger.error('[createUser] Failed to send welcome email | email: %s | error: %s',
+        data.email, error.message);
+    }
+
+    return this.userRepo.create({ data });
+  }
+
+  async getUserOrFail(id: string): Promise<TUser> {
+    const user = await this.userRepo.findById({ id });
+
+    if (!user.data) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.NotFound,
+        message: 'User not found',
+        details: { id },
+      });
+    }
+
+    return user.data;
+  }
+}
+```
+
+### Controller Layer Errors
+
+Controllers should delegate to services and let the global error handler catch exceptions:
+
+```typescript
+import { BaseController, controller, get, post } from '@venizia/ignis';
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+
+  @post({ configs: RouteConfigs.CREATE_USER })
+  async createUser(c: Context) {
+    const data = c.req.valid('json');
+
+    // Service throws appropriate errors
+    const user = await this.userService.createUser(data);
+
+    return c.json(user, HTTP.ResultCodes.RS_2.Created);
+  }
+
+  @get({ configs: RouteConfigs.GET_USER })
+  async getUser(c: Context) {
+    const { id } = c.req.valid('param');
+
+    // Service throws 404 if not found
+    const user = await this.userService.getUserOrFail(id);
+
+    return c.json(user, HTTP.ResultCodes.RS_2.Ok);
+  }
+}
+```
+
+### Repository Layer Errors
+
+Database constraint violations (unique, foreign key, not null, check) are **automatically handled** by the global error middleware. They return HTTP 400 with a human-readable message:
+
+```json
+{
+  "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
+  "statusCode": 400,
+  "requestId": "abc123"
+}
+```
+
+You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
+
+```typescript
+import { BaseRepository, getError, HTTP } from '@venizia/ignis';
+
+export class UserRepository extends BaseRepository<typeof User.schema> {
+  async createWithCustomError(data: TCreateUser): Promise<TCreateResult<TUser>> {
+    try {
+      return await this.create({ data });
+    } catch (error) {
+      // Custom message for specific constraint
+      if (error.cause?.code === '23505' && error.cause?.constraint === 'UQ_User_email') {
+        throw getError({
+          statusCode: HTTP.ResultCodes.RS_4.Conflict,
+          message: 'This email is already registered. Please use a different email or login.',
+        });
+      }
+      throw error; // Re-throw for automatic handling
+    }
+  }
+}
+```
+
+## 4. Global Error Handler
+
+Ignis includes a built-in error handler. Customize behavior in your application:
+
+```typescript
+import { BaseApplication, ApplicationError } from '@venizia/ignis';
+
+export class Application extends BaseApplication {
+  override setupMiddlewares(): void {
+    super.setupMiddlewares();
+
+    // Custom error handler (optional)
+    this.server.onError((error, c) => {
+      const requestId = c.get('requestId') ?? 'unknown';
+
+      // Log all errors
+      this.logger.error('[%s] Error | %s', requestId, error.message);
+
+      // Handle known application errors
+      if (error instanceof ApplicationError) {
+        return c.json({
+          statusCode: error.statusCode,
+          message: error.message,
+          details: error.details,
+          requestId,
+        }, error.statusCode as StatusCode);
+      }
+
+      // Handle Zod validation errors
+      if (error.name === 'ZodError') {
+        return c.json({
+          statusCode: 422,
+          message: 'Validation failed',
+          details: { cause: error.errors },
+          requestId,
+        }, 422);
+      }
+
+      // Unknown errors - don't expose details
+      return c.json({
+        statusCode: 500,
+        message: 'Internal server error',
+        requestId,
+      }, 500);
+    });
+  }
+}
+```
+
+## 5. Error Response Format
+
+All errors should follow a consistent format:
+
+```typescript
+interface ErrorResponse {
+  statusCode: number;
+  message: string;
+  requestId: string;
+  details?: {
+    cause?: Array<{
+      path: string;
+      message: string;
+      code: string;
+    }>;
+    [key: string]: unknown;
+  };
+}
+```
+
+**Example Responses:**
+
+```json
+// 400 Bad Request
+{
+  "statusCode": 400,
+  "message": "Invalid request body",
+  "requestId": "abc123"
+}
+
+// 404 Not Found
+{
+  "statusCode": 404,
+  "message": "User not found",
+  "requestId": "abc123",
+  "details": { "id": "user-uuid" }
+}
+
+// 422 Validation Error
+{
+  "statusCode": 422,
+  "message": "Validation failed",
+  "requestId": "abc123",
+  "details": {
+    "cause": [
+      {
+        "path": "email",
+        "message": "Invalid email format",
+        "code": "invalid_string"
+      }
+    ]
+  }
+}
+
+// 500 Internal Error (production)
+{
+  "statusCode": 500,
+  "message": "Internal server error",
+  "requestId": "abc123"
+}
+```
+
+## 6. Logging Errors
+
+### What to Log
+
+```typescript
+// ✅ Good - Context for debugging
+this.logger.error('[createOrder] Failed | userId: %s | orderId: %s | error: %s',
+  userId, orderId, error.message);
+
+// ✅ Good - Include stack trace for unexpected errors
+this.logger.error('[createOrder] Unexpected error | %s', error.stack);
+
+// ❌ Bad - No context
+this.logger.error(error.message);
+
+// ❌ Bad - Sensitive data
+this.logger.error('Login failed for user | password: %s', password);
+```
+
+### Log Levels
+
+| Level | Use For |
+|-------|---------|
+| `error` | Exceptions that need attention |
+| `warn` | Recoverable issues, deprecation warnings |
+| `info` | Important business events |
+| `debug` | Detailed debugging information |
+
+```typescript
+// Error - requires attention
+this.logger.error('[payment] Transaction failed | orderId: %s', orderId);
+
+// Warn - recovered but should investigate
+this.logger.warn('[cache] Redis unavailable, falling back to memory');
+
+// Info - business event
+this.logger.info('[order] Created | orderId: %s | userId: %s', orderId, userId);
+
+// Debug - detailed trace
+this.logger.debug('[query] Executing | sql: %s | params: %j', sql, params);
+```
+
+## 7. Async Error Handling
+
+### Promises
+
+```typescript
+// ✅ Good - Errors propagate naturally with async/await
+async function processOrder(orderId: string) {
+  const order = await orderRepo.findById({ id: orderId }); // Throws if fails
+  const payment = await paymentService.charge(order); // Throws if fails
+  return payment;
+}
+
+// ✅ Good - Explicit catch when you need to handle
+async function processOrderWithFallback(orderId: string) {
+  try {
+    return await paymentService.charge(order);
+  } catch (error) {
+    this.logger.warn('[processOrder] Primary payment failed, trying backup');
+    return await backupPaymentService.charge(order);
+  }
+}
+
+// ❌ Bad - Swallowing errors
+async function processOrder(orderId: string) {
+  try {
+    await dangerousOperation();
+  } catch (error) {
+    // Error is swallowed - no one knows it happened!
+  }
+}
+```
+
+### Fire-and-Forget with Error Handling
+
+```typescript
+// ✅ Good - Log errors from fire-and-forget operations
+this.sendNotification(userId).catch(error => {
+  this.logger.error('[notify] Failed | userId: %s | error: %s', userId, error.message);
+});
+
+// ✅ Good - Use void to indicate intentional fire-and-forget
+void this.analytics.track('order_created', { orderId });
+
+// ❌ Bad - Unhandled promise rejection
+this.sendNotification(userId); // If this rejects, crash!
+```
+
+## 8. Transaction Error Handling
+
+```typescript
+async function transferFunds(from: string, to: string, amount: number) {
+  const tx = await accountRepo.beginTransaction();
+
+  try {
+    await accountRepo.debit({ id: from, amount }, { transaction: tx });
+    await accountRepo.credit({ id: to, amount }, { transaction: tx });
+
+    await tx.commit();
+    return { success: true };
+  } catch (error) {
+    await tx.rollback();
+
+    // Re-throw with context
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[transferFunds] Transaction failed',
+      details: { from, to, amount, originalError: error.message },
+    });
+  }
+}
+```
+
+## 9. Client-Side Error Handling
+
+Guide for API consumers:
+
+```typescript
+// TypeScript client example
+async function createUser(data: CreateUserRequest): Promise<User> {
+  const response = await fetch('/api/users', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data),
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+
+    switch (response.status) {
+      case 400:
+        throw new ValidationError(error.message, error.details);
+      case 401:
+        // Redirect to login
+        window.location.href = '/login';
+        throw new AuthError('Please log in');
+      case 404:
+        throw new NotFoundError(error.message);
+      case 422:
+        // Handle field-level errors
+        const fieldErrors = error.details?.cause?.reduce((acc, e) => {
+          acc[e.path] = e.message;
+          return acc;
+        }, {});
+        throw new ValidationError('Validation failed', fieldErrors);
+      case 429:
+        throw new RateLimitError('Too many requests. Try again later.');
+      default:
+        throw new ApiError(error.message || 'Something went wrong');
+    }
+  }
+
+  return response.json();
+}
+```
+
+## Error Handling Checklist
+
+| Category | Check |
+|----------|-------|
+| **Services** | Business rule violations throw appropriate errors |
+| **Repositories** | Database errors are caught and wrapped |
+| **Controllers** | Errors propagate to global handler |
+| **Async** | All promises have error handling |
+| **Transactions** | Always rollback on error |
+| **Logging** | Errors logged with context |
+| **Responses** | Consistent error format returned |
+| **Security** | No sensitive data in error messages |
+
+## See Also
+
+- [Common Pitfalls](./common-pitfalls) - Error handling mistakes
+- [Testing Strategies](./testing-strategies) - Testing error scenarios
+- [Troubleshooting Tips](./troubleshooting-tips) - Debugging errors

package/wiki/best-practices/index.md

@@ -1,27 +1,210 @@
 # Best Practices
 
-Guidelines and recommendations for building production-ready Ignis applications.
+Production-ready patterns, security guidelines, and optimization strategies for building robust Ignis applications. These best practices are distilled from real-world experience building enterprise applications.
 
-## Overview
+<div class="guide-cards">
+
+<a href="./architectural-patterns" class="guide-card highlight">
+<span class="guide-icon">🏗️</span>
+<h3>Architecture</h3>
+<p>Layered architecture, DI, components, lifecycle hooks</p>
+</a>
+
+<a href="./code-style-standards/" class="guide-card">
+<span class="guide-icon">📝</span>
+<h3>Code Standards</h3>
+<p>Naming, types, patterns, ESLint, Prettier</p>
+</a>
+
+<a href="./security-guidelines" class="guide-card highlight">
+<span class="guide-icon">🔒</span>
+<h3>Security</h3>
+<p>Auth, validation, secrets, CORS, rate limiting</p>
+</a>
+
+<a href="./data-modeling" class="guide-card">
+<span class="guide-icon">🗄️</span>
+<h3>Data Modeling</h3>
+<p>Schemas, enrichers, relations, migrations</p>
+</a>
+
+<a href="./testing-strategies" class="guide-card">
+<span class="guide-icon">🧪</span>
+<h3>Testing</h3>
+<p>Unit tests, integration tests, mocking</p>
+</a>
+
+<a href="./performance-optimization" class="guide-card">
+<span class="guide-icon">⚡</span>
+<h3>Performance</h3>
+<p>Query optimization, caching, pooling</p>
+</a>
+
+<a href="./error-handling" class="guide-card">
+<span class="guide-icon">🚨</span>
+<h3>Error Handling</h3>
+<p>Error patterns, logging, user-friendly messages</p>
+</a>
+
+<a href="./deployment-strategies" class="guide-card">
+<span class="guide-icon">🚀</span>
+<h3>Deployment</h3>
+<p>Docker, Kubernetes, cloud platforms, CI/CD</p>
+</a>
+
+</div>
+
+## Learning Path
+
+<div class="roadmap">
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">1</span>
+<h4>Foundation</h4>
+</div>
+<p><a href="./architectural-patterns">Architecture</a> → <a href="./architecture-decisions">Decisions Guide</a> → <a href="./code-style-standards/">Code Standards</a></p>
+<span class="stage-desc">Understand patterns and establish coding conventions</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">2</span>
+<h4>Data Layer</h4>
+</div>
+<p><a href="./data-modeling">Data Modeling</a> → <a href="./api-usage-examples">API Patterns</a> → <a href="./error-handling">Error Handling</a></p>
+<span class="stage-desc">Design your data layer and handle edge cases</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">3</span>
+<h4>Quality Assurance</h4>
+</div>
+<p><a href="./testing-strategies">Testing</a> → <a href="./common-pitfalls">Avoid Pitfalls</a> → <a href="./troubleshooting-tips">Troubleshooting</a></p>
+<span class="stage-desc">Write tests and prevent common mistakes</span>
+</div>
+
+<div class="roadmap-stage">
+<div class="stage-header">
+<span class="stage-num">4</span>
+<h4>Production Ready</h4>
+</div>
+<p><a href="./security-guidelines">Security</a> → <a href="./performance-optimization">Performance</a> → <a href="./deployment-strategies">Deployment</a></p>
+<span class="stage-desc">Secure, optimize, and deploy your application</span>
+</div>
+
+</div>
+
+## Quick Reference
+
+### Essential Patterns
+
+```typescript
+// ✅ Layered Architecture
+Controller → Service → Repository → DataSource
+
+// ✅ Dependency Injection
+@inject({ key: BindingKeys.build({ namespace: BindingNamespaces.SERVICE, key: UserService.name }) })
+
+// ✅ Error Handling
+throw getError({ statusCode: 404, message: 'User not found' });
+
+// ✅ Input Validation
+request: { body: jsonContent({ schema: z.object({ email: z.string().email() }) }) }
+```
+
+### Anti-Patterns to Avoid
+
+```typescript
+// ❌ Business logic in controllers
+@get({ configs: RouteConfigs.GET_USER })
+async getUser(c: Context) {
+  const user = await this.userRepo.findById(id);
+  if (user.lastLogin < cutoff) await this.sendReminder(user); // Move to service!
+  return c.json(user);
+}
+
+// ❌ Catching all errors silently
+try { await riskyOperation(); } catch (e) { /* swallowed */ }
+
+// ❌ Using `any` type
+const data: any = await fetchData(); // Use proper types!
+```
+
+### Security Checklist
+
+| Check | Action |
+|-------|--------|
+| Secrets | Store in environment variables, never in code |
+| Input | Validate with Zod schemas at API boundaries |
+| Auth | Protect routes with `authStrategies: [Authentication.STRATEGY_JWT]` |
+| Sensitive data | Use `hiddenProperties` in model settings |
+| File uploads | Use `sanitizeFilename()` for all user-provided filenames |
+| CORS | Configure allowed origins explicitly |
+
+### Performance Checklist
+
+| Check | Action |
+|-------|--------|
+| Queries | Use `fields` to select only needed columns |
+| Pagination | Always set `limit` on find operations |
+| Relations | Limit `include` depth to 2 levels max |
+| Connection pool | Configure pool size based on load |
+| Background jobs | Offload CPU-intensive tasks to workers |
+| Caching | Cache expensive queries with Redis |
+
+## All Best Practices
+
+### Architecture & Design
+
+| Guide | Description |
+|-------|-------------|
+| [Architectural Patterns](./architectural-patterns) | Layered architecture, DI, components, mixins |
+| [Architecture Decisions](./architecture-decisions) | When to use services, repositories, components |
+
+### Development
+
+| Guide | Description |
+|-------|-------------|
+| [Code Style Standards](./code-style-standards/) | Naming conventions, types, ESLint, Prettier |
+| [Data Modeling](./data-modeling) | Schema design, enrichers, relations, migrations |
+| [API Usage Examples](./api-usage-examples) | Routing, repositories, middleware, services |
+
+### Quality
 
 | Guide | Description |
 |-------|-------------|
-| [Architectural Patterns](./architectural-patterns.md) | Layered architecture, project structure |
-| [Architecture Decisions](./architecture-decisions.md) | When to use services, repositories, components |
-| [Data Modeling](./data-modeling.md) | Database design, relations, migrations |
-| [Performance Optimization](./performance-optimization.md) | Speed up your application |
-| [Security Guidelines](./security-guidelines.md) | Protect your API and data |
-| [Code Style Standards](./code-style-standards.md) | ESLint, Prettier, naming conventions |
-| [Deployment Strategies](./deployment-strategies.md) | Docker, cloud platforms, CI/CD |
-| [Common Pitfalls](./common-pitfalls.md) | Mistakes to avoid |
-| [Troubleshooting Tips](./troubleshooting-tips.md) | Debug common issues |
-| [API Usage Examples](./api-usage-examples.md) | Real-world code patterns |
-| [Contribution Workflow](./contribution-workflow.md) | Contributing to Ignis |
-
-## Quick Tips
-
-- **Start simple** - Don't over-engineer. Add complexity only when needed.
-- **Use the layered architecture** - Controllers → Services → Repositories
-- **Validate early** - Use Zod schemas at API boundaries
-- **Type everything** - Leverage TypeScript for safety
-- **Test critical paths** - Focus on business logic and edge cases
+| [Testing Strategies](./testing-strategies) | Unit tests, integration tests, mocking, E2E |
+| [Error Handling](./error-handling) | Error patterns, structured errors, logging |
+| [Common Pitfalls](./common-pitfalls) | Mistakes to avoid and how to fix them |
+| [Troubleshooting Tips](./troubleshooting-tips) | Debug common issues quickly |
+
+### Production
+
+| Guide | Description |
+|-------|-------------|
+| [Security Guidelines](./security-guidelines) | Authentication, validation, secrets, CORS |
+| [Performance Optimization](./performance-optimization) | Query optimization, caching, connection pooling |
+| [Deployment Strategies](./deployment-strategies) | Docker, Kubernetes, cloud platforms, CI/CD |
+
+### Contributing
+
+| Guide | Description |
+|-------|-------------|
+| [Contribution Workflow](./contribution-workflow) | Git workflow, PR guidelines, code review |
+
+::: tip New to Ignis?
+Start with the [Getting Started Guide](/guides/) for tutorials, then return here for production-ready patterns.
+:::
+
+::: warning Production Deployment?
+Before deploying, review the [Security Guidelines](./security-guidelines) and [Deployment Strategies](./deployment-strategies) thoroughly.
+:::
+
+## See Also
+
+- [Getting Started](/guides/) - New to Ignis? Start here
+- [API Reference](/references/) - Detailed API documentation
+- [Core Concepts](/guides/core-concepts/application/) - Deep dive into architecture
+- [Changelogs](/changelogs/) - Version history and updates