yinzerflow 0.1.18 → 0.2.0

package/docs/hooks.md

@@ -1,289 +0,0 @@
-# Request Lifecycle Hooks
-
-YinzerFlow provides a powerful hooks system (traditionally called middleware in other frameworks) that allows you to intercept and modify requests and responses at various points in the request lifecycle. This document explains the core components, features, and best practices for using the hooks system.
-
-## Core Concepts
-
-In YinzerFlow, hooks are functions that can be executed at different phases of the request lifecycle:
-
-1. **Before All**: Executed before any route-specific hooks
-2. **Before Group**: Executed for routes in a specific group
-3. **Before Handler**: Executed before a specific route handler
-4. **After Handler**: Executed after a specific route handler
-
-Each hook can:
-- Modify the request or response
-- End the request early by returning a response
-- Pass control to the next hook by returning nothing
-
-## Core Components
-
-The hooks system consists of one main component:
-
-### HooksManager (MiddlewareManager)
-
-The `MiddlewareManager` class (which we recommend thinking of as a "HooksManager") is responsible for registering and executing hooks at the appropriate points in the request lifecycle.
-
-```typescript
-import { MiddlewareManager } from 'yinzerflow';
-
-const hooksManager = new MiddlewareManager();
-```
-
-#### Key Features
-
-- **Path matching**: Hooks can be applied to specific paths or path patterns
-- **Path exclusion**: Hooks can be excluded from specific paths
-- **Event-based architecture**: Emits events when hooks are added or executed
-- **Error handling**: Comprehensive error handling with proper logging and propagation
-
-## Registering Hooks
-
-### Global Hooks
-
-Global hooks are executed for all requests:
-
-```typescript
-app.beforeAll((ctx) => {
-  console.log(`Request received: ${ctx.request.method} ${ctx.request.path}`);
-});
-```
-
-### Path-Specific Hooks
-
-Hooks can be applied to specific paths:
-
-```typescript
-app.beforeAll(
-  (ctx) => {
-    // Verify API key
-    const apiKey = ctx.request.headers['x-api-key'];
-    if (!apiKey || !isValidApiKey(apiKey)) {
-      ctx.response.setStatus(401);
-      return { error: 'Invalid API key' };
-    }
-  },
-  { paths: ['/api/users', '/api/products'] }
-);
-```
-
-### Path Pattern Hooks
-
-Hooks can be applied to path patterns using wildcards:
-
-```typescript
-app.beforeAll(
-  (ctx) => {
-    // Verify API key for all API routes
-    const apiKey = ctx.request.headers['x-api-key'];
-    if (!apiKey || !isValidApiKey(apiKey)) {
-      ctx.response.setStatus(401);
-      return { error: 'Invalid API key' };
-    }
-  },
-  { paths: ['/api/*'] }
-);
-```
-
-### Excluded Paths
-
-Hooks can be excluded from specific paths:
-
-```typescript
-app.beforeAll(
-  (ctx) => {
-    // Log all requests except health checks
-    console.log(`Request received: ${ctx.request.method} ${ctx.request.path}`);
-  },
-  { paths: 'allButExcluded', excluded: ['/health'] }
-);
-```
-
-## Route-Specific Hooks
-
-In addition to global hooks, you can also specify hooks for specific routes:
-
-### Before Handler
-
-```typescript
-app.get(
-  '/users/:id',
-  handleGetUser,
-  {
-    beforeHandler: (ctx) => {
-      // Validate user ID
-      const userId = ctx.request.params.id;
-      if (!isValidUserId(userId)) {
-        ctx.response.setStatus(400);
-        return { error: 'Invalid user ID' };
-      }
-    }
-  }
-);
-```
-
-### After Handler
-
-```typescript
-app.get(
-  '/users/:id',
-  handleGetUser,
-  {
-    afterHandler: (ctx) => {
-      // Log successful user retrieval
-      console.log(`User retrieved: ${ctx.request.params.id}`);
-    }
-  }
-);
-```
-
-## Hook Execution Order
-
-Hooks are executed in the following order:
-
-1. Global "Before All" hooks (registered with `app.beforeAll()`)
-2. Group "Before Group" hooks (specified when registering route groups)
-3. Route-specific "Before Handler" hooks (specified when registering routes)
-4. Route handler
-5. Route-specific "After Handler" hooks (specified when registering routes)
-
-If any hook returns a response, the request is short-circuited and that response is sent to the client.
-
-## Response Handling and Error Management
-
-YinzerFlow provides flexible ways to handle responses and errors in your hooks and route handlers.
-
-### Setting Status Codes
-
-You can set status codes directly using the response object in the context:
-
-```typescript
-app.beforeAll((ctx) => {
-  // Check if user is authenticated
-  if (!isAuthenticated(ctx)) {
-    ctx.response.setStatus(401); // Sets status to 401 Unauthorized
-    return { message: 'Authentication required' };
-  }
-});
-```
-
-### Returning Responses
-
-Hooks and route handlers can return responses in several ways:
-
-1. **Return an object**: The object will be automatically converted to JSON
-   ```typescript
-   return { success: true, data: { id: 1, name: 'John' } };
-   ```
-
-2. **Return a primitive**: The value will be converted to a string
-   ```typescript
-   return 'Hello World';
-   ```
-
-### Error Handling
-
-For explicit error handling in hooks, use try/catch blocks:
-
-```typescript
-app.beforeAll(async (ctx) => {
-  try {
-    const result = await someAsyncOperation();
-    ctx.state.result = result;
-  } catch (error) {
-    console.error('Operation failed:', error);
-    ctx.response.setStatus(500);
-    return { error: 'Operation failed', message: error.message };
-  }
-});
-```
-
-YinzerFlow has a built-in error handling system that catches unhandled errors. For more details on error handling, refer to the [Error Handling](./error-handling.md) documentation.
-
-## Advanced Features
-
-### Hook Events
-
-The hooks system emits events when hooks are added or executed. You can listen for these events to perform additional actions:
-
-```typescript
-import { HookManagerEvent } from 'yinzerflow/constants/hooks';
-
-app.hooks.on(HookManagerEvent.HOOK_EXECUTED, (info) => {
-  console.log(`Hook executed: ${info.phase} for ${info.path}`);
-});
-```
-
-### Hook Removal
-
-You can remove all hooks using the `clear` method:
-
-```typescript
-app.hooks.clear();
-```
-
-## Best Practices
-
-### Keep Hooks Focused
-
-Each hook should have a single responsibility. For example, separate authentication, logging, and validation into different hooks.
-
-```typescript
-// Good
-app.beforeAll(logRequest);
-app.beforeAll(authenticate);
-app.beforeAll(validateInput);
-
-// Avoid
-app.beforeAll((ctx) => {
-  // Log request
-  // Authenticate user
-  // Validate input
-});
-```
-
-### Use Path Patterns Wisely
-
-Use path patterns to apply hooks to groups of routes:
-
-```typescript
-// Apply authentication to all admin routes
-app.beforeAll(authenticate, { paths: ['/admin/*'] });
-
-// Apply rate limiting to all API routes
-app.beforeAll(rateLimiter, { paths: ['/api/*'] });
-```
-
-### Error Handling
-
-Implement proper error handling in your hooks:
-
-```typescript
-app.beforeAll(async (ctx) => {
-  try {
-    // Perform some async operation
-    await someAsyncOperation();
-  } catch (error) {
-    console.error('Hook error:', error);
-    ctx.response.setStatus(500);
-    return { error: 'An error occurred' };
-  }
-});
-```
-
-### Performance Considerations
-
-- **Keep hooks lightweight**: Hooks are executed on every matching request, so keep them efficient
-- **Use path matching**: Apply hooks only to the paths that need them
-- **Cache expensive operations**: If a hook performs expensive operations, consider caching the results
-
-## Common Use Cases
-
-- **Authentication**
-- **Logging**
-- **Rate Limiting**
-
-## Conclusion
-# End of Selection
-
-The hooks system in YinzerFlow provides a flexible and powerful way to modify requests and responses at various points in the request lifecycle. By using hooks effectively, you can implement cross-cutting concerns like authentication, logging, and rate limiting in a clean and maintainable way. 

package/docs/routing.md

@@ -1,204 +0,0 @@
-# Routing System
-
-The YinzerFlow routing system provides a flexible and efficient way to define and manage routes in your application. This document explains the core components, features, and best practices for using the routing system.
-
-## Core Components
-
-The routing system consists of two main components:
-
-1. **RouteRegistry**: Responsible for storing and managing routes
-2. **RouteFinder**: Responsible for finding and matching routes based on requests
-
-### RouteRegistry
-
-The `RouteRegistry` class manages the registration and storage of routes. It provides methods for adding, removing, and retrieving routes.
-
-```typescript
-import { RouteRegistry } from 'yinzerflow';
-
-const registry = new RouteRegistry();
-```
-
-#### Key Features
-
-- **Event-based architecture**: Emits events when routes are added, removed, or changed
-- **Path validation**: Validates route paths to ensure they follow proper formatting rules
-- **Route grouping**: Supports grouping routes with common prefixes
-- **Route removal**: Allows removing individual routes or clearing all routes
-
-### RouteFinder
-
-The `RouteFinder` class handles route lookup and matching. It uses efficient algorithms to find the appropriate route for a given request.
-
-```typescript
-import { RouteFinder } from 'yinzerflow';
-
-const finder = new RouteFinder(registry);
-```
-
-#### Key Features
-
-- **Pattern route caching**: Caches pattern routes for faster lookup
-- **Path normalization**: Handles trailing slashes and path normalization
-- **Parameter extraction**: Extracts parameters from request paths
-
-## Route Definition
-
-Routes in YinzerFlow are defined with a path, HTTP method, and handler function. You can also specify optional middleware functions to be executed before or after the main handler.
-
-```typescript
-app.get('/users', handleGetUsers);
-app.post('/users', handleCreateUser);
-app.put('/users/:id', handleUpdateUser);
-app.delete('/users/:id', handleDeleteUser);
-app.patch('/users/:id', handlePartialUpdateUser);
-```
-
-### Route Parameters
-
-You can define route parameters by prefixing a path segment with a colon (`:`). These parameters will be extracted and made available in the request context.
-
-```typescript
-app.get('/users/:id', (ctx) => {
-  const userId = ctx.request.params.id;
-  // ...
-});
-```
-
-### Route Groups
-
-You can group routes with a common prefix using the `group` method:
-
-```typescript
-const apiRoutes = [
-  app.get('/users', handleGetUsers),
-  app.post('/users', handleCreateUser),
-];
-
-app.group('/api', apiRoutes);
-```
-
-This will register the routes as `/api/users` for GET and POST methods.
-
-## Advanced Features
-
-### Route Events
-
-The routing system emits events when routes are added, removed, or changed. You can listen for these events to perform additional actions:
-
-```typescript
-import { RouteRegistryEvent } from 'yinzerflow/constants/route';
-
-app.routeRegistry.on(RouteRegistryEvent.ROUTE_ADDED, (route) => {
-  console.log(`New route added: ${route.method} ${route.path}`);
-});
-```
-
-### Route Validation
-
-The routing system validates route paths to ensure they follow proper formatting rules:
-
-- Paths must start with a slash
-- Paths cannot have consecutive slashes
-- Path parameters must have names
-
-If a path doesn't meet these requirements, an error will be thrown:
-
-```typescript
-try {
-  app.get('invalid-path', handler); // Will throw an error
-} catch (error) {
-  console.error(error.message); // "Route path must start with a slash: invalid-path"
-}
-```
-
-### Route Removal
-
-You can remove routes using the `removeRoute` method:
-
-```typescript
-app.routeRegistry.removeRoute('GET', '/users/:id');
-```
-
-Or clear all routes:
-
-```typescript
-app.routeRegistry.clearRoutes();
-```
-
-## Best Practices
-
-### Organizing Routes
-
-For larger applications, it's recommended to organize routes by feature or resource:
-
-```typescript
-// users.routes.ts
-export function registerUserRoutes(app) {
-  app.get('/users', handleGetUsers);
-  app.post('/users', handleCreateUser);
-  // ...
-}
-
-// main.ts
-registerUserRoutes(app);
-```
-
-### Route Naming Conventions
-
-Follow these conventions for route paths:
-
-- Use lowercase for paths
-- Use hyphens for multi-word resources (e.g., `/user-profiles`)
-- Use plural nouns for resource collections (e.g., `/users` instead of `/user`)
-- Use singular nouns with parameters for specific resources (e.g., `/users/:id`)
-
-### Error Handling
-
-Implement proper error handling in your route handlers:
-
-```typescript
-app.get('/users/:id', async (ctx) => {
-  try {
-    const user = await getUserById(ctx.request.params.id);
-    if (!user) {
-      ctx.response.setStatus(404);
-      return { error: 'User not found' };
-    }
-    return user;
-  } catch (error) {
-    console.error('Failed to retrieve user:', error);
-    ctx.response.setStatus(500);
-    return { error: 'Failed to retrieve user' };
-  }
-});
-```
-
-For more details on error handling, refer to the [Error Handling](./error-handling.md) documentation.
-
-## Performance Considerations
-
-The routing system is designed to be efficient, but here are some tips to maximize performance:
-
-- **Avoid excessive route parameters**: Each parameter adds overhead to route matching
-- **Use route groups**: Grouping routes with common prefixes improves organization and can slightly improve performance
-- **Order routes by specificity**: Place more specific routes before more general ones
-
-## Debugging Routes
-
-You can get information about registered routes using these methods:
-
-```typescript
-// Get all routes
-const routes = app.routeRegistry.getRoutes();
-
-// Check if a route exists
-const hasRoute = app.routeRegistry.hasRoute('GET', '/users/:id');
-
-// Get the number of registered routes
-const routeCount = app.routeRegistry.routeCount;
-```
-
-## Conclusion
-
-The YinzerFlow routing system provides a flexible and efficient way to define and manage routes in your application. By understanding its core components and features, you can build well-organized and performant web applications.