Feature request: Implement Response Handling Architecture for Event Handler

[dreamorosi]

Important

This issue is dependent on #3971, #4139, and #4140 - as such it's on hold until they're merged.

Use case

As part of the Event Handler implementation for TypeScript Powertools (#3251), we need a comprehensive response handling system that can:

1. Support multiple response formats: Standard Web API Response, plain objects, and custom response types
2. Handle AWS Lambda proxy format conversion: Transform responses to the specific format required by different AWS services (API Gateway, ALB, Lambda Function URLs, etc.)
3. Manage AWS-specific features: Base64 encoding for binary responses, cookie handling, compression, and CORS headers
4. Provide developer flexibility: Allow developers to use familiar web standards while optimizing for AWS Lambda

The current foundational issue (#3971) focuses only on route registration but doesn't address how responses are handled, which is critical for a complete Event Handler implementation.

Solution/User Experience

Note

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

Implement a hybrid response architecture that supports multiple input types while optimizing for AWS Lambda:

Support Multiple Response Types

// Standard Web API Response (familiar to developers)
app.get('/standard', () => {
  return new Response(JSON.stringify({message: 'OK'}), {
    status: 200,
    headers: {'Content-Type': 'application/json'}
  });
});

// Plain object (auto-serialization like Python version)
app.get('/simple', () => {
  return {message: 'OK'}; // Auto-serialized to JSON
});

Internal Response Architecture

// Internal PowertoolsResponse class (not exposed to developers)
class PowertoolsResponse {
  constructor(
    public statusCode: number,
    public body: string | null,
    public headers: Record<string, string>,
    public cookies: string[] = [],
    public isBase64Encoded: boolean = false
  ) {}

  static fromWebResponse(response: Response): PowertoolsResponse
  static fromObject(obj: any): PowertoolsResponse
  toLambdaProxy(): LambdaProxyResponse
}

// ResponseBuilder handles conversion and AWS-specific features
class ResponseBuilder {
  build(result: Response | object | tuple, route?: Route): LambdaProxyResponse {
    // Convert any input type to PowertoolsResponse
    // Apply route-specific configurations (CORS, compression, etc.)
    // Handle AWS Lambda proxy format conversion
  }
}

AWS Lambda Optimizations

• Base64 encoding: Automatic handling for binary responses
• Cookie management: Convert to Lambda proxy format (cookies: string[])
• Content-Type detection: Smart content-type handling
• CORS integration: Inject CORS headers based on configuration (to be added when adding CORS support)
• Compression: Gzip compression with proper headers (to be added when adding compression support)

Integration with BaseRouter:

abstract class BaseRouter {
  // ... existing route registration methods
  
  protected buildResponse(result: any, route?: Route): LambdaProxyResponse {
    return this.responseBuilder.build(result, route);
  }
}

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.