lambda-adapter-kit

Framework-agnostic AWS Lambda event and web request/response conversion utilities

Convert between AWS Lambda events and standard Web API requests/responses for any framework.

Inspiration: This package is heavily inspired by the Hono.js AWS Lambda adapter, reimagined as a framework-agnostic utility library.

Installation

npm install @foladayo/lambda-adapter-kit
# or
pnpm add @foladayo/lambda-adapter-kit
# or
yarn add @foladayo/lambda-adapter-kit

Quick Start

Basic Event Conversion

import {
  convertLambdaEventToWebRequest,
  convertWebResponseToLambdaEvent,
} from "@foladayo/lambda-adapter-kit";

export const handler = async (event, context) => {
  // Convert Lambda event → Web Request
  const request = convertLambdaEventToWebRequest(event);

  // Your app logic here
  const response = new Response("Hello World", {
    status: 200,
    headers: { "Content-Type": "text/plain" },
  });

  // Convert Web Response → Lambda response
  return await convertWebResponseToLambdaEvent(response);
};

Framework Handler

import { createLambdaHandler } from "@foladayo/lambda-adapter-kit";

// Works with any framework that has a fetch method
const app = {
  fetch: async (request) => {
    return new Response(`Hello ${new URL(request.url).pathname}`);
  },
};

export const handler = createLambdaHandler(app, {
  binaryMediaTypes: ["image/*"],
});

What's Included

• 🔄 Event Converters - Lambda ↔ Web API conversion
• 🛠️ Handler Utilities - Framework-agnostic Lambda handlers
• 🎯 TypeScript Ready - Full type safety
• ⚡ Zero Dependencies - Lightweight and fast
• 🔧 Framework Agnostic - Works with any fetch-based framework

Core Functions

convertLambdaEventToWebRequest(event)

Converts an AWS Lambda event to a standard Web API Request object.

import { convertLambdaEventToWebRequest } from "@foladayo/lambda-adapter-kit";

// Supports: API Gateway v1/v2, ALB, Lambda Function URLs
const request = convertLambdaEventToWebRequest(event);

// Now you can use standard Web API methods
const url = new URL(request.url);
const method = request.method;
const body = await request.text();
const headers = request.headers;

convertWebResponseToLambdaEvent(response, options?)

Converts a standard Web API Response object to AWS Lambda event response format.

import { convertWebResponseToLambdaEvent } from "@foladayo/lambda-adapter-kit";

const response = new Response(JSON.stringify({ message: "Hello World" }), {
  status: 200,
  headers: {
    "Content-Type": "application/json",
    "Set-Cookie": "session=abc123; HttpOnly",
  },
});

const lambdaResponse = await convertWebResponseToLambdaEvent(response, {
  binaryMediaTypes: ["image/*", "application/pdf"],
  multiValueHeaders: false, // Set to true for ALB events
});

// Returns: { statusCode: 200, headers: {...}, body: "...", isBase64Encoded: false }

createLambdaHandler(app, options?)

Create a Lambda handler for any framework that implements the fetch interface:

import { createLambdaHandler } from "@foladayo/lambda-adapter-kit";

// For any framework with a fetch method
const app = {
  fetch: async (request) => {
    // Your application logic
    return new Response("Hello World");
  },
};

// Create Lambda handler
export const handler = createLambdaHandler(app, {
  binaryMediaTypes: ["image/*"],
  multiValueHeaders: false, // Set to true for ALB events
});

Utility Functions

Additional framework-agnostic utilities:

import {
  normalizeHeaders,
  parseMultiValueHeaders,
  isValidHttpMethod,
  sanitizePath,
} from "@foladayo/lambda-adapter-kit";

// Normalize headers for consistent format
const headers = normalizeHeaders(rawHeaders);

// Parse comma-separated header values
const multiHeaders = parseMultiValueHeaders(headers);

// Validate HTTP method
if (isValidHttpMethod("POST")) {
  // Process request
}

// Clean and normalize URL paths
const cleanPath = sanitizePath("/api//users///123"); // → '/api/users/123'

Supported Lambda Events

Event Type	Support	Notes
API Gateway v1	✅	REST API format
API Gateway v2	✅	HTTP API format
ALB (Application Load Balancer)	✅	Multi-value headers
Lambda Function URLs	✅	Direct invocation

Features

• 🔄 Automatic Binary Detection - Content-type based base64 encoding
• 🍪 Cookie Handling - Proper Set-Cookie header support
• 📦 Multi-Value Headers - ALB and API Gateway compatibility
• 🗜️ Compression Support - Gzip, deflate, brotli detection
• 🛡️ Type Safety - Complete TypeScript definitions
• 🔧 Framework Agnostic - Works with any fetch-based framework
• ⚡ Zero Dependencies - Lightweight and fast

TypeScript Support

All functions and types are fully typed:

import type {
  LambdaEvent, // Union of all Lambda event types
  ResponseConversionOptions, // Response conversion options
  FetchApp, // App interface for handlers
  LambdaHandlerOptions, // Handler configuration
} from "@foladayo/lambda-adapter-kit";

// LambdaEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2 | ALBEvent
function handleLambdaEvent(event: LambdaEvent) {
  return convertLambdaEventToWebRequest(event);
}

Framework Integrations

SvelteKit

For SvelteKit applications, use the dedicated adapter:

npm install @foladayo/sveltekit-adapter-lambda

// svelte.config.js
import adapter from "@foladayo/sveltekit-adapter-lambda";

export default {
  kit: {
    adapter: adapter(),
  },
};

Requirements

• Node.js: 20+ (AWS Lambda nodejs20.x runtime)

Contributing

git clone https://github.com/oladayo21/lambda-adapter-kit
cd lambda-adapter-kit
pnpm install
pnpm test

License

MIT © Foladayo