Feature request: create `BaseRouter` with base methods

[dreamorosi]

Use case

As part of the Event Handler implementation (#3251) we should implement a base class that will be shared by all resolvers (API Gateway REST, HTTP, ALB, etc.) and that allows customers to register routes according to the RFC #3500.

The BaseRouter should provide the foundational interface for route registration using HTTP method decorators, establishing the core API that developers will use to define their routes.

Solution/User Experience

The implementation should follow the RFC in terms of DX and APIs while also being aligned with the implementation in the Powertools for AWS Lambda (Python) repo.

Note

The code snippets below are provided as reference only - they are not exhaustive and final implementation might vary.

Core BaseRouter Implementation

abstract class BaseRouter {
  // HTTP method registration - bare bones implementation
  get(path: string, handler: RouteHandler): void;
  post(path: string, handler: RouteHandler): void;
  put(path: string, handler: RouteHandler): void;
  patch(path: string, handler: RouteHandler): void;
  delete(path: string, handler: RouteHandler): void;
  head(path: string, handler: RouteHandler): void;
  
  // Generic route method for multiple HTTP methods or custom methods
  route(path: string, handler: RouteHandler, options: { method: string | string[] }): void;
  
  // Core resolution method (abstract - implemented by concrete resolvers)
  abstract resolve(event: unknown, context: Context): Promise<unknown>;
}

Basic Route Handler Interface

interface RouteHandler {
  (params?: Record<string, string>): unknown;
}

Usage Example

const app = new APIGatewayRestResolver();

// Basic route registration
app.get('/users', () => ({ users: [] }));
app.post('/users', () => ({ message: 'User created' }));
app.put('/users/:id', (params) => ({ id: params.id, message: 'User updated' }));
app.delete('/users/:id', (params) => ({ id: params.id, message: 'User deleted' }));

// Multiple methods
app.route('/health', () => ({ status: 'ok' }), { method: ['GET', 'HEAD'] });

export const handler = async (event, context) => app.resolve(event, context);

Implementation Details

Scope - In Scope:

• Abstract BaseRouter class with HTTP method decorators
• Basic route registration interface
• Support for dynamic routes (:param syntax)
• Generic route() method for multiple HTTP methods
• Abstract resolve() method for concrete resolver implementation
• Basic RouteHandler interface

Scope - Out of Scope (Future Issues):

• Route storage and management
• Route matching and compilation
• Route-specific configuration (CORS, compression, validation, etc.)
• Middleware integration
• OpenAPI metadata
• Response handling
• Error handling
• Context management

Design Principles:

• Minimal: Only the essential interface for route registration
• Extensible: Clean extension points for advanced features
• Type-safe: Basic TypeScript support for route parameters
• Familiar: API consistent with RFC RFC: Event Handler for REST APIs #3500 and Python implementation

Dependencies

This is a foundational issue that other Event Handler components will build upon:

• Route Management system will implement the storage mechanism
• Route Matching system will implement the path resolution logic
• Response Handling will implement the response conversion
• Concrete resolvers (APIGatewayRestResolver, etc.) will extend BaseRouter

Alternative solutions

N/A

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.