yinzerflow 0.1.18 → 0.2.0

package/docs/error-handling.md

@@ -1,266 +0,0 @@
-# Error Handling in YinzerFlow
-
-YinzerFlow provides a flexible and robust error handling system that allows you to gracefully handle errors in your application. This document explains the core concepts, features, and best practices for error handling.
-
-## Core Concepts
-
-Error handling in YinzerFlow occurs at multiple levels:
-
-1. **Route and Hook Level**: Explicit error handling in your route handlers and hooks
-2. **Global Error Handler**: A centralized error handler for unhandled errors
-3. **Framework Level**: Built-in error handling for framework-level errors
-
-## Route and Hook Level Error Handling
-
-The most direct way to handle errors is within your route handlers and hooks using try/catch blocks:
-
-```typescript
-app.get('/users/:id', async ({ request, response }) => {
-  try {
-    const user = await getUserById(request.params.id);
-    if (!user) {
-      response.setStatus(404);
-      return { error: 'User not found' };
-    }
-    return user;
-  } catch (error) {
-    console.error('Failed to retrieve user:', error);
-    response.setStatus(500);
-    return { error: 'Failed to retrieve user' };
-  }
-});
-```
-
-This approach gives you fine-grained control over error handling for specific routes.
-
-### Setting Status Codes
-
-When an error occurs, you should set an appropriate HTTP status code using the `response.setStatus()` method:
-
-```typescript
-response.setStatus(400); // Bad Request
-response.setStatus(401); // Unauthorized
-response.setStatus(403); // Forbidden
-response.setStatus(404); // Not Found
-response.setStatus(500); // Internal Server Error
-```
-
-### Returning Error Responses
-
-After setting the status code, return an object with an error message:
-
-```typescript
-return { error: 'Resource not found' };
-```
-
-You can include additional information in the error response:
-
-```typescript
-return {
-  error: 'Validation failed',
-  details: [
-    { field: 'email', message: 'Invalid email format' },
-    { field: 'password', message: 'Password too short' }
-  ]
-};
-```
-
-## Global Error Handler
-
-YinzerFlow provides a global error handler that catches unhandled errors in your application. By default, it:
-
-1. Logs the error to the console
-2. Sets the response status to 500 (Internal Server Error)
-3. Returns a JSON object with an error message
-
-### Default Error Handler
-
-The default error handler is implemented as follows:
-
-```typescript
-private readonly _defaultErrorHandler: TErrorFunction = ({ response }, error): unknown => {
-  console.error('Unhandled error:', error);
-  response.setStatus(HttpStatusCode.INTERNAL_SERVER_ERROR);
-  return { error: 'Internal Server Error' };
-};
-```
-
-### Custom Error Handler
-
-You can provide your own error handler when initializing YinzerFlow:
-
-```typescript
-const app = new YinzerFlow({
-  port: 3000,
-  errorHandler: ({ response }, error) => {
-    console.error('Custom error handler:', error);
-    response.setStatus(500);
-    
-    // In development, include the stack trace
-    if (process.env.NODE_ENV === 'development') {
-      return {
-        error: error.message,
-        stack: error.stack,
-        timestamp: new Date().toISOString()
-      };
-    }
-    
-    // In production, return a generic message
-    return {
-      error: 'An unexpected error occurred',
-      timestamp: new Date().toISOString()
-    };
-  }
-});
-```
-
-## Framework Level Error Handling
-
-YinzerFlow handles framework-level errors automatically, such as:
-
-- Invalid route paths
-- Malformed request bodies
-- Unsupported content types
-
-These errors are handled internally and appropriate responses are sent to the client.
-
-## Best Practices
-
-### Use Specific Status Codes
-
-Use the most specific HTTP status code for each error situation:
-
-```typescript
-// Authentication error
-response.setStatus(401);
-return { error: 'Authentication required' };
-
-// Authorization error
-response.setStatus(403);
-return { error: 'Permission denied' };
-
-// Resource not found
-response.setStatus(404);
-return { error: 'User not found' };
-
-// Validation error
-response.setStatus(400);
-return { error: 'Invalid input' };
-
-// Server error
-response.setStatus(500);
-return { error: 'Internal server error' };
-```
-
-### Provide Helpful Error Messages
-
-Error messages should be clear and actionable:
-
-```typescript
-// Good
-return { error: 'Email format is invalid' };
-
-// Better
-return {
-  error: 'Validation failed',
-  details: [
-    { field: 'email', message: 'Email must be a valid email address' }
-  ]
-};
-
-// Avoid
-return { error: 'Error occurred' };
-```
-
-### Log Errors Appropriately
-
-Log errors with sufficient context for debugging:
-
-```typescript
-try {
-  // Operation that might fail
-} catch (error) {
-  console.error(`Failed to process order ${orderId}:`, error);
-  response.setStatus(500);
-  return { error: 'Failed to process order' };
-}
-```
-
-### Handle Async Errors
-
-Always use try/catch blocks with async operations:
-
-```typescript
-app.get('/data', async ({ response }) => {
-  try {
-    const data = await fetchDataFromDatabase();
-    return data;
-  } catch (error) {
-    console.error('Database error:', error);
-    response.setStatus(500);
-    return { error: 'Failed to fetch data' };
-  }
-});
-```
-
-## Common Error Scenarios
-
-### Authentication Errors
-
-```typescript
-app.beforeAll(({ request, response }) => {
-  const token = request.headers.authorization?.split(' ')[1];
-  if (!token) {
-    response.setStatus(401);
-    return { error: 'Authentication required' };
-  }
-  
-  try {
-    const user = verifyToken(token);
-    request.state.user = user;
-  } catch (error) {
-    response.setStatus(401);
-    return { error: 'Invalid token' };
-  }
-});
-```
-
-### Validation Errors
-
-```typescript
-app.post('/users', ({ request, response }) => {
-  const { name, email, password } = request.body;
-  const errors = [];
-  
-  if (!name) errors.push({ field: 'name', message: 'Name is required' });
-  if (!email) errors.push({ field: 'email', message: 'Email is required' });
-  if (!password) errors.push({ field: 'password', message: 'Password is required' });
-  
-  if (errors.length > 0) {
-    response.setStatus(400);
-    return { error: 'Validation failed', details: errors };
-  }
-  
-  // Process valid data...
-  return { success: true };
-});
-```
-
-### Not Found Errors
-
-```typescript
-app.get('/users/:id', ({ request, response }) => {
-  const user = findUserById(request.params.id);
-  
-  if (!user) {
-    response.setStatus(404);
-    return { error: 'User not found' };
-  }
-  
-  return user;
-});
-```
-
-## Conclusion
-
-Effective error handling is crucial for building robust and user-friendly applications. YinzerFlow provides a flexible error handling system that allows you to handle errors at multiple levels, from route-specific handling to global error management. By following the best practices outlined in this document, you can ensure that your application gracefully handles errors and provides helpful feedback to users. 

package/docs/file-parsers.md

@@ -1,276 +0,0 @@
-# File Parsers
-
-YinzerFlow provides robust support for parsing various file formats in HTTP requests and responses. This document explains the core concepts, features, and best practices for working with different file formats.
-
-## Core Concepts
-
-In web applications, files can be uploaded in various formats, such as YAML, CSV, and more. YinzerFlow automatically detects and parses these formats based on the file extension and content type, making it easy to work with different types of files.
-
-### Parser Configuration
-
-YinzerFlow allows you to configure how files are parsed through the `parserOptions` in your server configuration. You can control whether files should be automatically parsed:
-
-```typescript
-const app = new YinzerFlow({
-  port: 5000,
-  parserOptions: {
-    yaml: {
-      raw: true,
-    },
-    json: {
-        raw: true,
-    }
-  },
-  // Other options...
-});
-```
-
-#### Raw Mode
-
-Setting `raw: true` in the parser options disables automatic parsing of files. This is useful when:
-
-- You want to handle the parsing yourself
-- You're dealing with binary files that don't need parsing
-- You need to implement custom parsing logic
-- You want to improve performance by avoiding unnecessary parsing
-
-When raw mode is enabled, file contents will be provided as Buffer objects or strings, depending on the file type.
-
-### Type Safety
-
-YinzerFlow provides TypeScript interfaces and type guards for each supported file format, allowing you to work with file contents in a type-safe manner.
-
-## Supported File Formats
-
-YinzerFlow supports the following file formats out of the box:
-
-| Format | MIME Type | Type Interface | Type Guard | Description |
-|--------|-----------|----------------|------------|-------------|
-| YAML | `text/yaml`, `application/x-yaml` | `TYamlData` | `isYamlData` | YAML data with support for complex structures |
-| CSV (Coming Soon) | `text/csv` | `TCsvData` | `isCsvData` | CSV data with headers and rows |
-| JSON (Coming Soon) | `application/json` | `TJsonData` | `isJsonData` | JSON data as a generic object |
-
-## Working with File Parsers
-
-There are two main approaches to working with parsed file contents in YinzerFlow:
-
-### Approach 1: Type Casting (Simple but Less Safe)
-
-This approach uses TypeScript's type assertion to specify the expected file format:
-
-```typescript
-import { TYamlData } from 'yinzerflow/types/parsers/fileParsers/Yaml';
-
-app.post('/upload', ({ request }) => {
-  // Use type assertion - simple but no runtime validation
-  const fileContent = request.file.content as TYamlData;
-  
-  // Access the parsed data directly
-  const config = fileContent;
-  
-  // Process the data...
-  return { success: true };
-});
-```
-
-**When to use this approach:**
-- When you're certain about the file format (e.g., an internal API with controlled clients)
-- When performance is critical and you want to avoid runtime type checking
-- In simple applications where type safety is less important
-
-### Approach 2: Type Guards (Safer and Recommended)
-
-This approach uses runtime type checking for better safety:
-
-```typescript
-import { isYamlData } from 'yinzerflow/types/parsers/fileParsers/Yaml';
-
-app.post('/upload', ({ request, response }) => {
-  // Runtime type checking
-  if (!isYamlData(request.file.content)) {
-    response.setStatus(400);
-    return { error: 'Expected YAML file' };
-  }
-  
-  // TypeScript knows request.file.content is TYamlData here
-  const config = request.file.content;
-  
-  // Process the data...
-  return { success: true };
-});
-```
-
-**When to use this approach:**
-- When handling files from external clients
-- When an endpoint might receive different file formats
-- When you want to provide clear error messages for invalid files
-- In most production applications (recommended approach)
-
-### Approach 3: Manual Parsing (When Raw Mode is Enabled)
-
-When you've configured YinzerFlow with `raw: true` in the parser options, you'll need to manually parse file contents:
-
-```typescript
-// Your own custom parser
-import { parseYaml } from 'custom/parser';
-
-app.post('/upload', ({ request, response }) => {
-  // Get the raw file content (as Buffer or string)
-  const rawContent = request.file.content;
-  
-  try {
-    // Manually parse the content
-    const parsedContent = parseYaml(rawContent.toString());
-    
-    // Process the parsed content
-    // ...
-    
-    return { success: true };
-  } catch (error) {
-    response.setStatus(400);
-    return { error: 'Failed to parse YAML file' };
-  }
-});
-```
-
-**When to use this approach:**
-- When you've disabled automatic parsing with `raw: true`
-- When you need custom parsing logic
-- When you want to handle parsing errors in a specific way
-- When working with binary files or non-standard formats
-
-## Detailed File Format Examples
-
-### YAML Files
-
-YAML is commonly used for configuration files and structured data:
-
-```typescript
-import { isYamlData } from 'yinzerflow/types/parsers/fileParsers/Yaml';
-
-app.post('/api/config', ({ request, response }) => {
-  if (!isYamlData(request.file.content)) {
-    response.setStatus(400);
-    return { error: 'Expected YAML file' };
-  }
-  
-  // Validate required fields
-  const config = request.file.content;
-  if (!config.version || !config.settings) {
-    response.setStatus(400);
-    return { error: 'Invalid YAML structure' };
-  }
-  
-  // Process the configuration
-  const processedConfig = {
-    version: config.version,
-    settings: config.settings,
-    processedAt: new Date().toISOString()
-  };
-  
-  // Save the configuration (example)
-  saveConfig(processedConfig);
-  
-  response.setStatus(201);
-  return processedConfig;
-});
-```
-
-#### Type Definition
-
-```typescript
-// The YAML data type
-type TYamlData = Array<TYamlData> | boolean | number | string | { [key: string]: TYamlData } | null;
-
-// Type guard for YAML data
-const isYamlData = (content: unknown): content is TYamlData => {
-  // Implementation details...
-};
-```
-
-### CSV Files (Coming Soon)
-
-CSV files are commonly used for data import/export:
-
-### JSON Files (Coming Soon)
-
-JSON files are commonly used for structured data:
-
-## Best Practices
-
-### 1. Always Validate File Contents
-
-Always validate the file format and structure, especially for public APIs:
-
-```typescript
-app.post('/api/import', ({ request, response }) => {
-  // Validate file format
-  if (!isYamlData(request.file.content)) {
-    response.setStatus(400);
-    return { error: 'Expected YAML file' };
-  }
-  
-  // Validate required structure
-  const data = request.file.content;
-  if (!data || typeof data !== 'object') {
-    response.setStatus(400);
-    return { error: 'Invalid YAML structure' };
-  }
-  
-  // Validate specific fields
-  const { name, version } = data;
-  if (!name || !version) {
-    response.setStatus(400);
-    return { error: 'Missing required fields' };
-  }
-  
-  // Process the data...
-});
-```
-
-### 2. Use Type Guards for Public APIs
-
-Always use type guards when handling files from external sources:
-
-```typescript
-app.post('/api/upload', ({ request, response }) => {
-  // Check file type
-  if (!request.file.contentType.startsWith('text/yaml')) {
-    response.setStatus(415);
-    return { error: 'Unsupported file type' };
-  }
-  
-  // Validate file content
-  if (!isYamlData(request.file.content)) {
-    response.setStatus(400);
-    return { error: 'Invalid YAML format' };
-  }
-  
-  // Process the file...
-});
-```
-
-### 3. Handle Large Files Efficiently
-
-When dealing with large files, consider using streams and processing data in chunks:
-
-```typescript
-app.post('/api/import', async ({ request, response }) => {
-  if (!isYamlData(request.file.content)) {
-    response.setStatus(400);
-    return { error: 'Expected YAML file' };
-  }
-  
-  // Process large files in chunks
-  const chunkSize = 1000;
-  const data = request.file.content;
-  
-  for (let i = 0; i < data.length; i += chunkSize) {
-    const chunk = data.slice(i, i + chunkSize);
-    await processChunk(chunk);
-  }
-  
-  return { success: true };
-});
-```
-