@ooneex/middleware 0.0.1 → 0.4.0

package/README.md

@@ -1 +1,413 @@
 # @ooneex/middleware
+
+A middleware framework for TypeScript applications with decorators for request/response pipeline processing. This package provides interfaces and utilities for creating HTTP and WebSocket middleware that intercept and transform requests before they reach controllers.
+
+![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
+
+✅ **HTTP Middleware** - Intercept and process HTTP requests and responses
+
+✅ **WebSocket Middleware** - Handle WebSocket connection processing
+
+✅ **Decorator Support** - Register middleware with decorators for clean code
+
+✅ **Context Access** - Full access to request, response, and application context
+
+✅ **Container Integration** - Works seamlessly with dependency injection
+
+✅ **Type-Safe** - Full TypeScript support with proper type definitions
+
+## Installation
+
+### Bun
+```bash
+bun add @ooneex/middleware
+```
+
+### pnpm
+```bash
+pnpm add @ooneex/middleware
+```
+
+### Yarn
+```bash
+yarn add @ooneex/middleware
+```
+
+### npm
+```bash
+npm install @ooneex/middleware
+```
+
+## Usage
+
+### Basic HTTP Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+
+@decorator.middleware()
+class LoggingMiddleware implements IMiddleware {
+  public async handle(context: ContextType): Promise<ContextType> {
+    console.log(`${context.method} ${context.request.path}`);
+    
+    // Continue to next middleware/controller
+    return context;
+  }
+}
+```
+
+### Authentication Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+import { Jwt } from '@ooneex/jwt';
+
+@decorator.middleware()
+class AuthMiddleware implements IMiddleware {
+  private readonly jwt = new Jwt();
+
+  public async handle(context: ContextType): Promise<ContextType> {
+    const authHeader = context.header.get('Authorization');
+    
+    if (!authHeader?.startsWith('Bearer ')) {
+      context.response.exception('Missing authorization header', {
+        status: 401
+      });
+      return context;
+    }
+    
+    const token = authHeader.substring(7);
+    const isValid = await this.jwt.isValid(token);
+    
+    if (!isValid) {
+      context.response.exception('Invalid or expired token', {
+        status: 401
+      });
+      return context;
+    }
+    
+    // Set user in context
+    const payload = this.jwt.getPayload<{ userId: string; role: string }>(token);
+    context.user = { id: payload.userId, role: payload.role };
+    
+    return context;
+  }
+}
+```
+
+### WebSocket Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { ISocketMiddleware, ContextType as SocketContextType } from '@ooneex/middleware';
+
+@decorator.middleware()
+class SocketAuthMiddleware implements ISocketMiddleware {
+  public async handle(context: SocketContextType): Promise<SocketContextType> {
+    const token = context.queries.token;
+    
+    if (!token) {
+      context.response.exception('Missing authentication token', {
+        status: 401
+      });
+      return context;
+    }
+    
+    // Validate token and set user
+    context.user = await this.validateToken(token);
+    
+    return context;
+  }
+}
+```
+
+### Request Validation Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+
+@decorator.middleware()
+class ValidationMiddleware implements IMiddleware {
+  public async handle(context: ContextType): Promise<ContextType> {
+    // Validate content type for POST/PUT requests
+    if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
+      const contentType = context.header.get('Content-Type');
+      
+      if (!contentType?.includes('application/json')) {
+        context.response.exception('Content-Type must be application/json', {
+          status: 415
+        });
+        return context;
+      }
+    }
+    
+    return context;
+  }
+}
+```
+
+### Registering Middleware with App
+
+```typescript
+import { App } from '@ooneex/app';
+import { AuthMiddleware, LoggingMiddleware } from './middleware';
+
+const app = new App({
+  middlewares: [LoggingMiddleware, AuthMiddleware],
+  // ... other config
+});
+
+await app.run();
+```
+
+## API Reference
+
+### Interfaces
+
+#### `IMiddleware`
+
+Interface for HTTP middleware implementations.
+
+```typescript
+interface IMiddleware<T extends ContextConfigType = ContextConfigType> {
+  handle: (context: ContextType<T>) => Promise<ContextType<T>> | ContextType<T>;
+}
+```
+
+**Methods:**
+
+##### `handle(context: ContextType): Promise<ContextType> | ContextType`
+
+Processes the request context and returns the (potentially modified) context.
+
+**Parameters:**
+- `context` - The request context containing request, response, and app data
+
+**Returns:** The context object (modified or unchanged)
+
+**Example:**
+```typescript
+public async handle(context: ContextType): Promise<ContextType> {
+  // Pre-processing
+  console.log('Before controller');
+  
+  // Return context to continue processing
+  return context;
+}
+```
+
+---
+
+#### `ISocketMiddleware`
+
+Interface for WebSocket middleware implementations.
+
+```typescript
+interface ISocketMiddleware<T extends SocketContextConfigType = SocketContextConfigType> {
+  handle: (context: SocketContextType<T>) => Promise<SocketContextType<T>> | SocketContextType<T>;
+}
+```
+
+**Methods:**
+
+##### `handle(context: SocketContextType): Promise<SocketContextType> | SocketContextType`
+
+Processes the WebSocket context and returns the (potentially modified) context.
+
+**Parameters:**
+- `context` - The WebSocket context containing connection data and channel methods
+
+**Returns:** The context object (modified or unchanged)
+
+### Types
+
+#### `MiddlewareClassType`
+
+```typescript
+type MiddlewareClassType = new (...args: any[]) => IMiddleware;
+```
+
+#### `SocketMiddlewareClassType`
+
+```typescript
+type SocketMiddlewareClassType = new (...args: any[]) => ISocketMiddleware;
+```
+
+### Decorators
+
+#### `@decorator.middleware()`
+
+Registers a class as middleware with the dependency injection container.
+
+**Example:**
+```typescript
+@decorator.middleware()
+class MyMiddleware implements IMiddleware {
+  // Implementation
+}
+```
+
+## Advanced Usage
+
+### CORS Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+
+@decorator.middleware()
+class CorsMiddleware implements IMiddleware {
+  private readonly allowedOrigins = ['https://example.com', 'https://app.example.com'];
+
+  public async handle(context: ContextType): Promise<ContextType> {
+    const origin = context.header.get('Origin');
+    
+    if (origin && this.allowedOrigins.includes(origin)) {
+      context.response.header.set('Access-Control-Allow-Origin', origin);
+      context.response.header.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+      context.response.header.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    }
+    
+    // Handle preflight requests
+    if (context.method === 'OPTIONS') {
+      context.response.json({}, 204);
+      return context;
+    }
+    
+    return context;
+  }
+}
+```
+
+### Rate Limiting Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+import { container } from '@ooneex/container';
+import type { IRateLimiter } from '@ooneex/rate-limit';
+
+@decorator.middleware()
+class RateLimitMiddleware implements IMiddleware {
+  public async handle(context: ContextType): Promise<ContextType> {
+    const rateLimiter = container.get<IRateLimiter>('rateLimiter');
+    const clientIp = context.ip || 'unknown';
+    
+    const result = await rateLimiter.check(clientIp, 100, 60); // 100 requests per minute
+    
+    context.response.header.set('X-RateLimit-Limit', result.total.toString());
+    context.response.header.set('X-RateLimit-Remaining', result.remaining.toString());
+    context.response.header.set('X-RateLimit-Reset', result.resetAt.toISOString());
+    
+    if (result.limited) {
+      context.response.exception('Too many requests', {
+        status: 429,
+        data: { retryAfter: result.resetAt }
+      });
+    }
+    
+    return context;
+  }
+}
+```
+
+### Middleware with Dependencies
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import { injectable, inject } from '@ooneex/container';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+import type { ILogger } from '@ooneex/logger';
+
+@decorator.middleware()
+@injectable()
+class LoggingMiddleware implements IMiddleware {
+  constructor(
+    @inject('logger') private readonly logger: ILogger
+  ) {}
+
+  public async handle(context: ContextType): Promise<ContextType> {
+    const start = Date.now();
+    
+    this.logger.info('Request started', {
+      method: context.method,
+      path: context.request.path,
+      ip: context.ip
+    });
+    
+    // Store start time for response logging
+    context.request.startTime = start;
+    
+    return context;
+  }
+}
+```
+
+### Error Handling Middleware
+
+```typescript
+import { decorator } from '@ooneex/middleware';
+import type { IMiddleware, ContextType } from '@ooneex/middleware';
+import { Exception } from '@ooneex/exception';
+
+@decorator.middleware()
+class ErrorMiddleware implements IMiddleware {
+  public async handle(context: ContextType): Promise<ContextType> {
+    try {
+      return context;
+    } catch (error) {
+      if (error instanceof Exception) {
+        context.logger.error(error);
+        context.response.exception(error.message, {
+          status: error.status,
+          data: error.data
+        });
+      } else {
+        context.logger.error('Unexpected error', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        context.response.exception('Internal server error', {
+          status: 500
+        });
+      }
+      
+      return context;
+    }
+  }
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+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.
+
+### 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
+
+---
+
+Made with ❤️ by the Ooneex team

package/dist/index.d.ts

@@ -1,5 +1,15 @@
+import { EContainerScope } from "@ooneex/container";
+import { ContextConfigType, ContextType } from "@ooneex/controller";
+import { ContextConfigType as SocketContextConfigType, ContextType as SocketContextType } from "@ooneex/socket";
 type MiddlewareClassType = new (...args: any[]) => IMiddleware;
-interface IMiddleware {
-	next: () => Promise<void>;
+type SocketMiddlewareClassType = new (...args: any[]) => ISocketMiddleware;
+interface IMiddleware<T extends ContextConfigType = ContextConfigType> {
+	handle: (context: ContextType<T>) => Promise<ContextType<T>> | ContextType<T>;
 }
-export { MiddlewareClassType, IMiddleware };
+interface ISocketMiddleware<T extends SocketContextConfigType = SocketContextConfigType> {
+	handle: (context: SocketContextType<T>) => Promise<SocketContextType<T>> | SocketContextType<T>;
+}
+declare const decorator: {
+	middleware: (scope?: EContainerScope) => (target: MiddlewareClassType | SocketMiddlewareClassType) => void;
+};
+export { decorator, SocketMiddlewareClassType, MiddlewareClassType, ISocketMiddleware, IMiddleware };

package/dist/index.js

@@ -1,2 +1,3 @@
+import{container as o,EContainerScope as a}from"@ooneex/container";var d={middleware:(e=a.Singleton)=>{return(r)=>{o.add(r,e)}}};export{d as decorator};
 
-//# debugId=BC4C8D5165931A0D64756E2164756E21
+//# debugId=99D3A80723DBEBF264756E2164756E21

package/dist/index.js.map

@@ -1,9 +1,10 @@
 {
   "version": 3,
-  "sources": [],
+  "sources": ["src/decorators.ts"],
   "sourcesContent": [
+    "import { container, EContainerScope } from \"@ooneex/container\";\nimport type { MiddlewareClassType, SocketMiddlewareClassType } from \"./types\";\n\nexport const decorator = {\n  middleware: (scope: EContainerScope = EContainerScope.Singleton) => {\n    return (target: MiddlewareClassType | SocketMiddlewareClassType): void => {\n      container.add(target, scope);\n    };\n  },\n};\n"
   ],
-  "mappings": "",
-  "debugId": "BC4C8D5165931A0D64756E2164756E21",
+  "mappings": "AAAA,oBAAS,qBAAW,0BAGb,IAAM,EAAY,CACvB,WAAY,CAAC,EAAyB,EAAgB,YAAc,CAClE,MAAO,CAAC,IAAkE,CACxE,EAAU,IAAI,EAAQ,CAAK,GAGjC",
+  "debugId": "99D3A80723DBEBF264756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ooneex/middleware",
-  "description": "",
-  "version": "0.0.1",
+  "description": "Middleware framework with decorators for request/response pipeline processing in HTTP and WebSocket contexts",
+  "version": "0.4.0",
   "type": "module",
   "files": [
     "dist",
@@ -25,10 +25,23 @@
     "test": "bun test tests",
     "build": "bunup",
     "lint": "tsgo --noEmit && bunx biome lint",
-    "publish:prod": "bun publish --tolerate-republish --access public",
-    "publish:pack": "bun pm pack --destination ./dist",
-    "publish:dry": "bun publish --dry-run"
+    "npm:publish": "bun publish --tolerate-republish --access public"
   },
-  "devDependencies": {},
-  "peerDependencies": {}
+  "dependencies": {
+    "@ooneex/container": "0.0.2"
+  },
+  "devDependencies": {
+    "@ooneex/controller": "0.0.1",
+    "@ooneex/socket": "0.0.1"
+  },
+  "keywords": [
+    "bun",
+    "decorator",
+    "handler",
+    "http",
+    "middleware",
+    "ooneex",
+    "pipeline",
+    "typescript"
+  ]
 }