@ooneex/routing 0.0.2 → 0.1.0

package/README.md

@@ -1,460 +1,529 @@
 # @ooneex/routing
 
-Type-safe routing system for Ooneex applications with powerful utilities for route configuration and type generation.
+A flexible HTTP routing system for TypeScript applications with decorator-based route definitions, parameter validation, permission handling, and type-safe route generation. This package provides a powerful foundation for building RESTful APIs with support for WebSocket routes.
+
+![Bun](https://img.shields.io/badge/Bun-Compatible-orange?style=flat-square&logo=bun)
+![Deno](https://img.shields.io/badge/Deno-Compatible-blue?style=flat-square&logo=deno)
+![Node.js](https://img.shields.io/badge/Node.js-Compatible-green?style=flat-square&logo=node.js)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)
+![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+
+## Features
+
+✅ **Decorator-Based Routes** - Define routes using TypeScript decorators for clean, readable code
+
+✅ **Parameter Validation** - Built-in validation for route params, query strings, and payloads
+
+✅ **Type-Safe Route Names** - Enforce `namespace.resource.action` naming convention
+
+✅ **WebSocket Support** - Define WebSocket routes alongside HTTP routes
+
+✅ **Permission System** - Role-based access control with custom permission classes
+
+✅ **Environment Filtering** - Restrict routes to specific environments
+
+✅ **IP/Host Restrictions** - Limit access by IP address or hostname
+
+✅ **Route Generation** - Type-safe URL generation with parameter interpolation
+
+✅ **Container Integration** - Automatic controller registration with DI container
 
 ## Installation
 
+### Bun
 ```bash
 bun add @ooneex/routing
 ```
 
-## Features
+### pnpm
+```bash
+pnpm add @ooneex/routing
+```
 
-- 🎯 Type-safe route definitions with path parameter extraction
-- 🔒 Compile-time route validation
-- 🚀 Decorator-based route registration
-- 🔄 Automatic type inference from ArkType schemas
-- 🛠️ Utilities for type string generation and path validation
-- 🌐 Support for HTTP methods and WebSocket routes
-- 📝 Built-in support for params, queries, payload, and response validation
+### Yarn
+```bash
+yarn add @ooneex/routing
+```
 
-## Quick Start
+### npm
+```bash
+npm install @ooneex/routing
+```
 
-```typescript
-import { Route, type ContextType } from "@ooneex/routing";
-import { Assert } from "@ooneex/validation";
+## Usage
 
-@Route.get("/users/:id", {
-  name: "api.users.show",
-  description: "Get a user by ID",
-  params: {
-    id: Assert("string"),
-  },
-  response: Assert({
-    id: "string",
-    name: "string",
-    email: "string",
-  }),
+### Basic HTTP Route
+
+```typescript
+import { Route } from '@ooneex/routing';
+import type { IController, ContextType } from '@ooneex/controller';
+import type { IResponse } from '@ooneex/http-response';
+
+@Route.http({
+  name: 'api.users.list',
+  path: '/api/users',
+  method: 'GET',
+  description: 'List all users'
 })
-export class GetUserController {
-  public async index(context: ContextType) {
-    const { id } = context.params;
-    
-    // Your logic here
+class UserListController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
     return context.response.json({
-      id,
-      name: "John Doe",
-      email: "john@example.com",
+      users: [{ id: 1, name: 'John' }]
     });
   }
 }
 ```
 
-## Route Configuration
+### Route with Parameters
 
-### Route Decorators
+```typescript
+import { Route } from '@ooneex/routing';
+import { type } from 'arktype';
+
+@Route.http({
+  name: 'api.users.show',
+  path: '/api/users/:id',
+  method: 'GET',
+  description: 'Get user by ID',
+  params: {
+    id: type('string.uuid')
+  }
+})
+class UserShowController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
+    const { id } = context.params;
+    const user = await this.userRepository.findById(id);
+    
+    return context.response.json({ user });
+  }
+}
+```
 
-The package provides decorators for all HTTP methods and WebSocket connections:
+### Route with Query Validation
 
-- `@Route.get(path, config)`
-- `@Route.post(path, config)`
-- `@Route.put(path, config)`
-- `@Route.patch(path, config)`
-- `@Route.delete(path, config)`
-- `@Route.options(path, config)`
-- `@Route.head(path, config)`
-- `@Route.socket(path, config)` - for WebSocket routes
+```typescript
+import { Route } from '@ooneex/routing';
+import { type } from 'arktype';
+
+@Route.http({
+  name: 'api.products.search',
+  path: '/api/products',
+  method: 'GET',
+  description: 'Search products',
+  queries: type({
+    q: 'string',
+    page: 'number = 1',
+    limit: 'number = 10',
+    'category?': 'string'
+  })
+})
+class ProductSearchController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
+    const { q, page, limit, category } = context.queries;
+    
+    const products = await this.search(q, { page, limit, category });
+    
+    return context.response.json({ products });
+  }
+}
+```
 
-### Route Configuration Options
+### Route with Payload Validation
 
 ```typescript
-type RouteConfig = {
-  name: RouteNameType;           // e.g., "api.users.list"
-  description: string;            // Route description
-  params?: Record<string, AssertType | IAssert>;  // Path parameters
-  queries?: AssertType | IAssert; // Query string validation
-  payload?: AssertType | IAssert; // Request body validation
-  response?: AssertType | IAssert; // Response validation
-  env?: Environment[];            // Allowed environments
-  ip?: string[];                  // IP whitelist
-  host?: string[];                // Host whitelist
-  roles?: ERole[];                // Required roles
-};
+import { Route } from '@ooneex/routing';
+import { type } from 'arktype';
+
+@Route.http({
+  name: 'api.users.create',
+  path: '/api/users',
+  method: 'POST',
+  description: 'Create a new user',
+  payload: type({
+    email: 'string.email',
+    name: 'string >= 2',
+    password: 'string >= 8'
+  })
+})
+class UserCreateController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
+    const { email, name, password } = context.payload;
+    
+    const user = await this.userService.create({ email, name, password });
+    
+    return context.response.json({ user }, 201);
+  }
+}
 ```
 
-### Path Parameters
-
-Routes support dynamic path parameters that are automatically extracted and validated:
+### WebSocket Route
 
 ```typescript
-@Route.delete("/users/:userId/posts/:postId", {
-  name: "api.users.posts.delete",
-  description: "Delete a user's post",
+import { Route } from '@ooneex/routing';
+import type { IController, ContextType } from '@ooneex/socket';
+
+@Route.socket({
+  name: 'api.chat.connect',
+  path: '/ws/chat/:roomId',
+  description: 'Connect to chat room',
   params: {
-    userId: Assert("string"),
-    postId: Assert("string"),
-  },
-  response: Assert({
-    success: "boolean",
-    message: "string",
-  }),
+    roomId: type('string')
+  }
 })
-export class DeleteUserPostController {
-  public async index(context: ContextType) {
-    const { userId, postId } = context.params;
-    // Delete logic here
+class ChatController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
+    const { roomId } = context.params;
+    
+    await context.channel.subscribe();
+    
+    return context.response.json({
+      connected: true,
+      room: roomId
+    });
   }
 }
 ```
 
-## Utilities
+### Route with Role-Based Access
 
-### `routeConfigToTypeString(config)`
+```typescript
+import { Route } from '@ooneex/routing';
+import { ERole } from '@ooneex/role';
+
+@Route.http({
+  name: 'admin.users.delete',
+  path: '/admin/users/:id',
+  method: 'DELETE',
+  description: 'Delete a user (admin only)',
+  roles: [ERole.ADMIN, ERole.SUPER_ADMIN]
+})
+class UserDeleteController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
+    await this.userService.delete(context.params.id);
+    
+    return context.response.json({ deleted: true });
+  }
+}
+```
 
-Convert a route configuration to a TypeScript type string representation. This is useful for code generation, documentation, and type visualization.
+### Generating URLs
 
-#### Parameters
+```typescript
+import { router } from '@ooneex/routing';
 
-- `config`: Object containing route configuration with `params`, `queries`, `payload`, and/or `response` fields
+// Generate URL for a named route
+const userUrl = router.generate('api.users.show', { id: '123' });
+console.log(userUrl); // "/api/users/123"
 
-#### Returns
+// Generate URL with multiple parameters
+const orderUrl = router.generate('api.users.orders.show', {
+  userId: '123',
+  orderId: '456'
+});
+console.log(orderUrl); // "/api/users/123/orders/456"
+```
 
-A formatted string representing the TypeScript type definition.
+## API Reference
 
-#### Example
+### Decorators
 
-```typescript
-import { routeConfigToTypeString } from "@ooneex/routing";
-import { type } from "arktype";
+#### `@Route.http(config: RouteConfigType)`
 
-const config = {
-  params: {
-    id: type("string"),
-    emailId: type("string"),
-  },
-  payload: type({
-    name: "string",
-    email: "string",
-  }),
-  queries: type({
-    limit: "number",
-    offset: "number",
-  }),
-  response: type({
-    success: "boolean",
-    message: "string",
-    data: {
-      id: "string",
-      name: "string",
-    },
-  }),
-};
+Decorator for defining HTTP routes.
 
-const typeString = routeConfigToTypeString(config);
-console.log(typeString);
-```
+**Parameters:**
+- `config.name` - Route name in `namespace.resource.action` format
+- `config.path` - URL path with optional parameters (e.g., `/users/:id`)
+- `config.method` - HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)
+- `config.description` - Human-readable description
+- `config.params` - Parameter validation schema (optional)
+- `config.queries` - Query string validation schema (optional)
+- `config.payload` - Request body validation schema (optional)
+- `config.response` - Response validation schema (optional)
+- `config.roles` - Required roles for access (optional)
+- `config.permission` - Custom permission class (optional)
+- `config.env` - Allowed environments (optional)
+- `config.ip` - Allowed IP addresses (optional)
+- `config.host` - Allowed hostnames (optional)
+- `config.cache` - Enable caching (optional)
+- `config.generate` - Code generation options (optional)
 
-**Output:**
+**Example:**
 ```typescript
-{
-  response: { success: boolean; message: string; data: { id: string; name: string } };
-  params: { id: string; emailId: string };
-  payload: { name: string; email: string };
-  queries: { limit: number; offset: number };
-}
+@Route.http({
+  name: 'api.products.update',
+  path: '/api/products/:id',
+  method: 'PUT',
+  description: 'Update a product',
+  params: { id: type('string.uuid') },
+  payload: type({ name: 'string', price: 'number' }),
+  roles: [ERole.ADMIN]
+})
 ```
 
-#### Use Cases
+#### `@Route.socket(config: RouteConfigType)`
 
-**1. Type Definition Generation**
+Decorator for defining WebSocket routes.
 
-```typescript
-const typeName = "DeleteUserRouteConfig";
-const typeDefinition = `export type ${typeName} = ${routeConfigToTypeString(config)}`;
-
-// Generates:
-// export type DeleteUserRouteConfig = {
-//   response: { success: boolean; message: string };
-//   params: { id: string; emailId: string };
-//   payload: { name: string };
-//   queries: { limit: number };
-// }
-```
+**Parameters:**
+Same as `@Route.http`, but `method` is ignored and `isSocket` is set to `true`.
 
-**2. API Client Generation**
+---
 
-```typescript
-// Generate typed API client methods
-const routeConfig = {
-  params: { userId: type("string") },
-  response: type({ id: "string", name: "string" }),
-};
+### Classes
 
-const clientMethod = `
-public async getUser(userId: string): Promise<{ id: string; name: string }> {
-  return this.fetch("/users/" + userId);
-}
-`;
-```
+#### `Router`
 
-**3. Documentation Generation**
+Main router class for managing routes.
 
-```typescript
-// Generate API documentation with type information
-const docString = `
-## GET /users/:id
-
-**Type Definition:**
-\`\`\`typescript
-${routeConfigToTypeString(userRouteConfig)}
-\`\`\`
-`;
-```
+**Methods:**
 
-### `isValidRoutePath(path)`
+##### `addRoute(route: RouteConfigType): this`
 
-Validates a route path at runtime.
+Manually add a route to the router.
 
-```typescript
-import { isValidRoutePath } from "@ooneex/routing";
+**Parameters:**
+- `route` - The route configuration
 
-isValidRoutePath("/users/:id");              // true
-isValidRoutePath("/users/:id/posts/:postId"); // true
-isValidRoutePath("users");                    // false (must start with /)
-isValidRoutePath("/users//posts");            // false (no double slashes)
-isValidRoutePath("/users/:");                 // false (parameter needs name)
-```
+**Returns:** The router instance for chaining
 
-### `extractParameterNames(path)`
+**Throws:** `RouterException` if route name or path/method already exists
 
-Extract parameter names from a route path.
+##### `findRouteByPath(path: string): RouteConfigType[] | null`
 
-```typescript
-import { extractParameterNames } from "@ooneex/routing";
+Find all routes registered for a specific path.
 
-extractParameterNames("/users/:id");
-// ["id"]
+**Parameters:**
+- `path` - The URL path
 
-extractParameterNames("/users/:userId/posts/:postId");
-// ["userId", "postId"]
+**Returns:** Array of route configurations or null
 
-extractParameterNames("/static/path");
-// []
-```
+##### `findRouteByName(name: RouteNameType): RouteConfigType | null`
 
-## Type System
+Find a route by its unique name.
 
-### Route Path Types
+**Parameters:**
+- `name` - The route name
 
-The package provides compile-time validation for route paths:
+**Returns:** Route configuration or null
 
-```typescript
-import type { RoutePathType, ExtractParameters } from "@ooneex/routing";
+##### `getRoutes(): Map<string, RouteConfigType[]>`
 
-// Valid paths
-type ValidPath = RoutePathType<"/users/:id">;
-type MultiParam = RoutePathType<"/users/:userId/posts/:postId">;
+Get all registered routes.
 
-// Extract parameters
-type UserParams = ExtractParameters<"/users/:id">;
-// Result: "id"
+**Returns:** Map of path to route configurations
 
-type PostParams = ExtractParameters<"/users/:userId/posts/:postId">;
-// Result: "userId" | "postId"
-```
+##### `getHttpRoutes(): Map<string, RouteConfigType[]>`
 
-### Route Name Types
+Get only HTTP routes (excludes WebSocket routes).
 
-Route names follow a strict pattern: `namespace.resource.action`
+**Returns:** Map of path to HTTP route configurations
 
-```typescript
-import type { RouteNameType } from "@ooneex/routing";
+##### `getSocketRoutes(): Map<string, RouteConfigType>`
 
-// Valid route names
-type ApiUserList = "api.users.list";
-type ApiUserShow = "api.users.show";
-type WebPostCreate = "client.posts.create";
-type AdminSettingsUpdate = "admin.settings.update";
-```
+Get only WebSocket routes.
+
+**Returns:** Map of path to WebSocket route configuration
+
+##### `generate<P>(name: RouteNameType, params?: P): string`
+
+Generate a URL for a named route.
+
+**Parameters:**
+- `name` - The route name
+- `params` - Parameter values to interpolate
 
-## Router API
+**Returns:** The generated URL path
 
-### Adding Routes
+**Throws:** `RouterException` if route not found or missing required parameters
 
+**Example:**
 ```typescript
-import { router } from "@ooneex/routing";
-
-router.addRoute({
-  name: "api.users.list",
-  path: "/users",
-  method: "GET",
-  controller: UserListController,
-  description: "List all users",
-  isSocket: false,
-});
+const url = router.generate('api.users.show', { id: '123' });
 ```
 
-### Finding Routes
+### Types
+
+#### `RouteNameType`
+
+Route name following the `namespace.resource.action` pattern.
 
 ```typescript
-// Find by path
-const routes = router.findRouteByPath("/users/:id");
+type RouteNameType = `${RouteNamespace}.${string}.${RouteAction}`;
+// Example: "api.users.list", "admin.products.create"
+```
 
-// Find by name
-const route = router.findRouteByName("api.users.show");
+**Valid Namespaces:**
+- `api`, `client`, `admin`, `public`, `auth`, `webhook`, `internal`, `external`, `system`, `health`, `metrics`, `docs`
 
-// Get all routes
-const allRoutes = router.getRoutes();
+**Valid Actions:**
+- `list`, `show`, `create`, `update`, `delete`, `search`, `export`, `import`, and 200+ more
 
-// Get only HTTP routes
-const httpRoutes = router.getHttpRoutes();
+#### `RouteConfigType`
 
-// Get only WebSocket routes
-const socketRoutes = router.getSocketRoutes();
+```typescript
+type RouteConfigType = {
+  name: RouteNameType;
+  path: `/${string}`;
+  method: HttpMethodType;
+  params?: Record<string, AssertType | IAssert>;
+  queries?: AssertType | IAssert;
+  payload?: AssertType | IAssert;
+  response?: AssertType | IAssert;
+  controller: ControllerClassType;
+  description: string;
+  env?: Environment[];
+  ip?: string[];
+  host?: string[];
+  roles?: ERole[];
+  permission?: PermissionClassType;
+  cache?: boolean;
+  isSocket: boolean;
+  generate?: {
+    doc?: boolean;
+    fetcher?: boolean;
+    queryHook?: boolean;
+  };
+};
 ```
 
-### Generating URLs
+#### `ExtractParameters<T>`
+
+Utility type to extract parameter names from a route path.
 
 ```typescript
-// Generate URL from route name
-const url = router.generate("api.users.show", { id: "123" });
-// Result: "/users/123"
+type Params = ExtractParameters<'/users/:id/orders/:orderId'>;
+// Result: "id" | "orderId"
+```
 
-const complexUrl = router.generate("api.users.posts.show", {
-  userId: "123",
-  postId: "456",
-});
-// Result: "/users/123/posts/456"
+#### `RouteParameters<T>`
+
+Utility type to create a typed record from route parameters.
+
+```typescript
+type Params = RouteParameters<'/users/:id'>;
+// Result: { id: string }
 ```
 
-## Advanced Examples
+## Advanced Usage
 
-### Complex Route with All Options
+### Environment-Specific Routes
 
 ```typescript
-import { Route } from "@ooneex/routing";
-import { Assert } from "@ooneex/validation";
-import { Environment } from "@ooneex/app-env";
-import { ERole } from "@ooneex/role";
-
-@Route.post("/admin/users/:userId/permissions", {
-  name: "admin.users.permissions.update",
-  description: "Update user permissions (admin only)",
-  params: {
-    userId: Assert("string"),
-  },
-  payload: Assert({
-    permissions: "string[]",
-    expiresAt: "string.date.parse",
-  }),
-  queries: Assert({
-    "notify?": "boolean",
-  }),
-  response: Assert({
-    success: "boolean",
-    message: "string",
-    permissions: "string[]",
-  }),
-  env: [Environment.PRODUCTION, Environment.STAGING],
-  roles: [ERole.ADMIN, ERole.SUPER_ADMIN],
+import { Route } from '@ooneex/routing';
+import { Environment } from '@ooneex/app-env';
+
+@Route.http({
+  name: 'api.debug.info',
+  path: '/api/debug',
+  method: 'GET',
+  description: 'Debug information (dev only)',
+  env: [Environment.LOCAL, Environment.DEVELOPMENT]
 })
-export class UpdateUserPermissionsController {
-  public async index(context: ContextType) {
-    // Implementation
+class DebugController implements IController {
+  public async index(context: ContextType): Promise<IResponse> {
+    return context.response.json({
+      environment: context.app.env.env,
+      timestamp: new Date().toISOString()
+    });
   }
 }
 ```
 
-### WebSocket Route
+### Custom Permission Classes
 
 ```typescript
-@Route.socket("/chat/:roomId", {
-  name: "client.chat.room",
-  description: "WebSocket chat room connection",
-  params: {
-    roomId: Assert("string"),
-  },
-  queries: Assert({
-    token: "string",
-  }),
-})
-export class ChatRoomSocketController {
-  public async index(context: ContextType) {
-    // WebSocket handling
+import { Route } from '@ooneex/routing';
+import { Permission } from '@ooneex/permission';
+import type { IUser } from '@ooneex/user';
+
+class CanEditOwnProfile extends Permission {
+  public can(user: IUser | null, context: ContextType): boolean {
+    if (!user) return false;
+    return user.id === context.params.id;
   }
 }
+
+@Route.http({
+  name: 'api.users.update',
+  path: '/api/users/:id',
+  method: 'PUT',
+  description: 'Update user profile',
+  permission: CanEditOwnProfile
+})
+class UserUpdateController implements IController {
+  // Only the user themselves can update their profile
+}
 ```
 
-### Optional Properties
+### IP Address Restrictions
 
 ```typescript
-@Route.patch("/users/:id", {
-  name: "api.users.update",
-  description: "Update user profile",
-  params: {
-    id: Assert("string"),
-  },
-  payload: Assert({
-    "name?": "string",
-    "email?": "string.email",
-    "age?": "number >= 18",
-    "bio?": "string",
-  }),
-  response: Assert({
-    success: "boolean",
-    updated: "boolean",
-  }),
+@Route.http({
+  name: 'internal.health.check',
+  path: '/internal/health',
+  method: 'GET',
+  description: 'Internal health check',
+  ip: ['127.0.0.1', '10.0.0.0/8', '192.168.1.0/24']
 })
-export class UpdateUserController {
-  public async index(context: ContextType) {
-    // Update logic
-  }
+class HealthCheckController implements IController {
+  // Only accessible from specified IP ranges
 }
 ```
 
-## Testing
+### Code Generation Options
 
 ```typescript
-import { describe, expect, test } from "bun:test";
-import { routeConfigToTypeString, extractParameterNames } from "@ooneex/routing";
-import { type } from "arktype";
-
-describe("Route utilities", () => {
-  test("converts route config to type string", () => {
-    const config = {
-      params: { id: type("string") },
-      response: type({ success: "boolean" }),
-    };
-    
-    const result = routeConfigToTypeString(config);
-    
-    expect(result).toContain("params:");
-    expect(result).toContain("id: string");
-    expect(result).toContain("response:");
-    expect(result).toContain("success: boolean");
-  });
-
-  test("extracts parameter names", () => {
-    const params = extractParameterNames("/users/:id/posts/:postId");
-    expect(params).toEqual(["id", "postId"]);
-  });
-});
+@Route.http({
+  name: 'api.users.list',
+  path: '/api/users',
+  method: 'GET',
+  description: 'List all users',
+  response: type({ users: 'User[]' }),
+  generate: {
+    doc: true,        // Generate API documentation
+    fetcher: true,    // Generate fetch client function
+    queryHook: true   // Generate React Query hook
+  }
+})
 ```
 
-## Best Practices
+### Error Handling
 
-1. **Use descriptive route names** following the `namespace.resource.action` pattern
-2. **Validate all inputs** using ArkType assertions for params, queries, and payload
-3. **Document routes** with clear descriptions
-4. **Type your responses** to ensure API consistency
-5. **Use environment restrictions** for sensitive endpoints
-6. **Leverage path parameter extraction** for type-safe access to URL parameters
-7. **Generate types** using `routeConfigToTypeString` for API clients and documentation
+```typescript
+import { router, RouterException } from '@ooneex/routing';
+
+try {
+  const url = router.generate('api.nonexistent.route', { id: '123' });
+} catch (error) {
+  if (error instanceof RouterException) {
+    console.error('Route error:', error.message);
+  }
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
 
 ## Contributing
 
-Contributions are welcome! Please follow the project's coding standards and ensure all tests pass.
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
 
-## License
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `bun install`
+3. Run tests: `bun run test`
+4. Build the project: `bun run build`
+
+### Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Update documentation for API changes
+- Ensure all tests pass before submitting PR
+
+---
 
-MIT
+Made with ❤️ by the Ooneex team