elysia-lambda-handler 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# elysia-lambda-handler
+
+Run [Elysia](https://elysiajs.com/) apps on AWS Lambda with the **Node.js runtime**.
+
+This handler converts an API Gateway REST API (payload v1) proxy event into a Web
+standard `Request`, passes it to `app.handle()`, and converts the returned
+`Response` back into the Lambda proxy result format. No HTTP server is started
+and no Bun-specific APIs are used — only the Web APIs built into Node.js 18+.
+
+- Zero runtime dependencies (`elysia` is a peer dependency)
+- Works with `NodejsFunction` / esbuild bundling out of the box
+
+## Installation
+
+```sh
+npm install elysia-lambda-handler
+```
+
+## Usage
+
+Keep your Elysia app runtime-agnostic:
+
+```ts
+// app.ts
+import { Elysia } from "elysia";
+
+export const app = new Elysia().get("/", () => ({ hello: "lambda" }));
+```
+
+Then wrap it once at module scope in your Lambda entry:
+
+```ts
+// lambda.ts
+import { handle } from "elysia-lambda-handler";
+import { app } from "./app.js";
+
+export const handler = handle(app);
+```
+
+Deploy `lambda.ts` behind an API Gateway REST API with Lambda proxy
+integration (for example CDK's `LambdaRestApi`).
+
+## Supported event types
+
+| Event source | Status |
+| --- | --- |
+| API Gateway REST API (payload v1), proxy integration | ✅ Supported |
+| API Gateway HTTP API (payload v2) | Planned |
+| Lambda Function URL | Planned |
+
+## Binary responses
+
+When the `Response` has a non-text `content-type` (anything other than
+`text/*`, `application/json`, `+json` / `+xml` suffixes, or a type with an
+explicit `charset`), the body is returned base64-encoded with
+`isBase64Encoded: true`. Note that a REST API only decodes it back to bytes
+when the API's `binaryMediaTypes` matches the request — configure it (for
+example `*/*`) if you serve images or other binary content.
+
+Multiple `Set-Cookie` headers are returned via `multiValueHeaders`, which the
+REST API supports natively.
+
+## Cold starts
+
+On Lambda, cold-start time usually dominates. Two tips:
+
+- Call `handle(app)` at module scope (as in the example above) so the app and
+  its route compilation are initialized once per execution environment, not per
+  invocation.
+- Elysia's ahead-of-time route compilation (`aot`, enabled by default) makes
+  the *first* request in each execution environment more expensive when the app
+  has many routes. If cold-start latency matters more than steady-state
+  throughput — the common case for Lambda — try `new Elysia({ aot: false })`
+  and measure both variants for your workload.
+
+## API
+
+### `handle(app)`
+
+Takes anything with a fetch-style `handle(request: Request)` method (an Elysia
+instance) and returns an async Lambda handler
+`(event, context?) => Promise<APIGatewayProxyResult>`.
+
+The lower-level conversion helpers `eventToRequest(event)` and
+`responseToResult(response)` are also exported, along with the structural
+types `APIGatewayProxyEvent` / `APIGatewayProxyResult` (compatible with
+`@types/aws-lambda`, which is not required at runtime or compile time).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,90 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/request.ts
+const findHeader = (event, name) => {
+	for (const [key, value] of Object.entries(event.headers ?? {})) if (key.toLowerCase() === name && value !== void 0) return value;
+	for (const [key, values] of Object.entries(event.multiValueHeaders ?? {})) if (key.toLowerCase() === name && values?.length) return values[0];
+};
+const buildSearch = (event) => {
+	const params = new URLSearchParams();
+	if (event.multiValueQueryStringParameters) for (const [key, values] of Object.entries(event.multiValueQueryStringParameters)) for (const value of values ?? []) params.append(key, value);
+	else if (event.queryStringParameters) {
+		for (const [key, value] of Object.entries(event.queryStringParameters)) if (value !== void 0) params.append(key, value);
+	}
+	const search = params.toString();
+	return search ? `?${search}` : "";
+};
+const buildHeaders = (event) => {
+	const headers = new Headers();
+	if (event.multiValueHeaders) for (const [key, values] of Object.entries(event.multiValueHeaders)) for (const value of values ?? []) headers.append(key, value);
+	else if (event.headers) {
+		for (const [key, value] of Object.entries(event.headers)) if (value !== void 0) headers.append(key, value);
+	}
+	return headers;
+};
+/**
+* Convert an API Gateway REST API (payload v1) proxy event into a Web
+* standard `Request` that can be passed to `app.handle()`.
+*/
+const eventToRequest = (event) => {
+	const host = findHeader(event, "host") ?? event.requestContext?.domainName ?? "localhost";
+	const method = event.httpMethod.toUpperCase();
+	const url = `https://${host}${event.path}${buildSearch(event)}`;
+	let body;
+	if (event.body !== null && method !== "GET" && method !== "HEAD") body = Buffer.from(event.body, event.isBase64Encoded ? "base64" : "utf8");
+	return new Request(url, {
+		method,
+		headers: buildHeaders(event),
+		body
+	});
+};
+//#endregion
+//#region src/response.ts
+const TEXT_TYPE_PATTERN = /^text\/|^application\/(json|javascript|xml|x-www-form-urlencoded)\b|[+](json|xml)\b|charset=/i;
+const isTextContentType = (contentType) => contentType === null || TEXT_TYPE_PATTERN.test(contentType);
+/**
+* Convert a Web standard `Response` returned by `app.handle()` into an API
+* Gateway REST API (payload v1) proxy result. Text bodies are passed through
+* as UTF-8; anything else is base64-encoded with `isBase64Encoded: true`
+* (the REST API additionally requires matching `binaryMediaTypes` to decode
+* it on the way out).
+*/
+const responseToResult = async (response) => {
+	const multiValueHeaders = {};
+	for (const [key, value] of response.headers) {
+		if (key === "set-cookie") continue;
+		multiValueHeaders[key] = [value];
+	}
+	const setCookie = response.headers.getSetCookie();
+	if (setCookie.length > 0) multiValueHeaders["set-cookie"] = setCookie;
+	const buffer = Buffer.from(await response.arrayBuffer());
+	const isText = isTextContentType(response.headers.get("content-type"));
+	return {
+		statusCode: response.status,
+		multiValueHeaders,
+		body: buffer.toString(isText ? "utf8" : "base64"),
+		isBase64Encoded: !isText
+	};
+};
+//#endregion
+//#region src/index.ts
+/**
+* Wrap an Elysia app as an AWS Lambda handler for API Gateway REST API
+* (payload v1) proxy integration events.
+*
+* @example
+* ```ts
+* import { handle } from "elysia-lambda-handler";
+* import { app } from "./app.js";
+*
+* export const handler = handle(app);
+* ```
+*/
+const handle = (app) => {
+	return async (event) => {
+		return responseToResult(await app.handle(eventToRequest(event)));
+	};
+};
+//#endregion
+exports.eventToRequest = eventToRequest;
+exports.handle = handle;
+exports.responseToResult = responseToResult;

package/dist/index.d.cts

@@ -0,0 +1,74 @@
+//#region src/types.d.ts
+/**
+ * Structurally-compatible subset of the API Gateway REST API (payload v1)
+ * proxy event. Kept local so this package has no runtime or type
+ * dependencies — an `APIGatewayProxyEvent` from `@types/aws-lambda` is
+ * assignable to this type.
+ */
+interface APIGatewayProxyEvent {
+  httpMethod: string;
+  path: string;
+  headers: Record<string, string | undefined> | null;
+  multiValueHeaders: Record<string, string[] | undefined> | null;
+  queryStringParameters: Record<string, string | undefined> | null;
+  multiValueQueryStringParameters: Record<string, string[] | undefined> | null;
+  body: string | null;
+  isBase64Encoded: boolean;
+  requestContext: {
+    domainName?: string;
+  };
+}
+/**
+ * API Gateway REST API (payload v1) proxy result. Structurally compatible
+ * with `APIGatewayProxyResult` from `@types/aws-lambda`.
+ */
+interface APIGatewayProxyResult {
+  statusCode: number;
+  multiValueHeaders: Record<string, string[]>;
+  body: string;
+  isBase64Encoded: boolean;
+}
+/**
+ * The subset of an Elysia instance the handler relies on. Any object with a
+ * fetch-style `handle` method works, which keeps `elysia` a peer dependency
+ * used only at the type level by consumers.
+ */
+interface HandleTarget {
+  handle: (request: Request) => Response | Promise<Response>;
+}
+/** Lambda handler signature returned by {@link handle}. */
+type LambdaHandler = (event: APIGatewayProxyEvent, context?: unknown) => Promise<APIGatewayProxyResult>;
+//#endregion
+//#region src/request.d.ts
+/**
+ * Convert an API Gateway REST API (payload v1) proxy event into a Web
+ * standard `Request` that can be passed to `app.handle()`.
+ */
+declare const eventToRequest: (event: APIGatewayProxyEvent) => Request;
+//#endregion
+//#region src/response.d.ts
+/**
+ * Convert a Web standard `Response` returned by `app.handle()` into an API
+ * Gateway REST API (payload v1) proxy result. Text bodies are passed through
+ * as UTF-8; anything else is base64-encoded with `isBase64Encoded: true`
+ * (the REST API additionally requires matching `binaryMediaTypes` to decode
+ * it on the way out).
+ */
+declare const responseToResult: (response: Response) => Promise<APIGatewayProxyResult>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Wrap an Elysia app as an AWS Lambda handler for API Gateway REST API
+ * (payload v1) proxy integration events.
+ *
+ * @example
+ * ```ts
+ * import { handle } from "elysia-lambda-handler";
+ * import { app } from "./app.js";
+ *
+ * export const handler = handle(app);
+ * ```
+ */
+declare const handle: (app: HandleTarget) => LambdaHandler;
+//#endregion
+export { type APIGatewayProxyEvent, type APIGatewayProxyResult, type HandleTarget, type LambdaHandler, eventToRequest, handle, responseToResult };

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+//#region src/types.d.ts
+/**
+ * Structurally-compatible subset of the API Gateway REST API (payload v1)
+ * proxy event. Kept local so this package has no runtime or type
+ * dependencies — an `APIGatewayProxyEvent` from `@types/aws-lambda` is
+ * assignable to this type.
+ */
+interface APIGatewayProxyEvent {
+  httpMethod: string;
+  path: string;
+  headers: Record<string, string | undefined> | null;
+  multiValueHeaders: Record<string, string[] | undefined> | null;
+  queryStringParameters: Record<string, string | undefined> | null;
+  multiValueQueryStringParameters: Record<string, string[] | undefined> | null;
+  body: string | null;
+  isBase64Encoded: boolean;
+  requestContext: {
+    domainName?: string;
+  };
+}
+/**
+ * API Gateway REST API (payload v1) proxy result. Structurally compatible
+ * with `APIGatewayProxyResult` from `@types/aws-lambda`.
+ */
+interface APIGatewayProxyResult {
+  statusCode: number;
+  multiValueHeaders: Record<string, string[]>;
+  body: string;
+  isBase64Encoded: boolean;
+}
+/**
+ * The subset of an Elysia instance the handler relies on. Any object with a
+ * fetch-style `handle` method works, which keeps `elysia` a peer dependency
+ * used only at the type level by consumers.
+ */
+interface HandleTarget {
+  handle: (request: Request) => Response | Promise<Response>;
+}
+/** Lambda handler signature returned by {@link handle}. */
+type LambdaHandler = (event: APIGatewayProxyEvent, context?: unknown) => Promise<APIGatewayProxyResult>;
+//#endregion
+//#region src/request.d.ts
+/**
+ * Convert an API Gateway REST API (payload v1) proxy event into a Web
+ * standard `Request` that can be passed to `app.handle()`.
+ */
+declare const eventToRequest: (event: APIGatewayProxyEvent) => Request;
+//#endregion
+//#region src/response.d.ts
+/**
+ * Convert a Web standard `Response` returned by `app.handle()` into an API
+ * Gateway REST API (payload v1) proxy result. Text bodies are passed through
+ * as UTF-8; anything else is base64-encoded with `isBase64Encoded: true`
+ * (the REST API additionally requires matching `binaryMediaTypes` to decode
+ * it on the way out).
+ */
+declare const responseToResult: (response: Response) => Promise<APIGatewayProxyResult>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Wrap an Elysia app as an AWS Lambda handler for API Gateway REST API
+ * (payload v1) proxy integration events.
+ *
+ * @example
+ * ```ts
+ * import { handle } from "elysia-lambda-handler";
+ * import { app } from "./app.js";
+ *
+ * export const handler = handle(app);
+ * ```
+ */
+declare const handle: (app: HandleTarget) => LambdaHandler;
+//#endregion
+export { type APIGatewayProxyEvent, type APIGatewayProxyResult, type HandleTarget, type LambdaHandler, eventToRequest, handle, responseToResult };

package/dist/index.mjs

@@ -0,0 +1,87 @@
+//#region src/request.ts
+const findHeader = (event, name) => {
+	for (const [key, value] of Object.entries(event.headers ?? {})) if (key.toLowerCase() === name && value !== void 0) return value;
+	for (const [key, values] of Object.entries(event.multiValueHeaders ?? {})) if (key.toLowerCase() === name && values?.length) return values[0];
+};
+const buildSearch = (event) => {
+	const params = new URLSearchParams();
+	if (event.multiValueQueryStringParameters) for (const [key, values] of Object.entries(event.multiValueQueryStringParameters)) for (const value of values ?? []) params.append(key, value);
+	else if (event.queryStringParameters) {
+		for (const [key, value] of Object.entries(event.queryStringParameters)) if (value !== void 0) params.append(key, value);
+	}
+	const search = params.toString();
+	return search ? `?${search}` : "";
+};
+const buildHeaders = (event) => {
+	const headers = new Headers();
+	if (event.multiValueHeaders) for (const [key, values] of Object.entries(event.multiValueHeaders)) for (const value of values ?? []) headers.append(key, value);
+	else if (event.headers) {
+		for (const [key, value] of Object.entries(event.headers)) if (value !== void 0) headers.append(key, value);
+	}
+	return headers;
+};
+/**
+* Convert an API Gateway REST API (payload v1) proxy event into a Web
+* standard `Request` that can be passed to `app.handle()`.
+*/
+const eventToRequest = (event) => {
+	const host = findHeader(event, "host") ?? event.requestContext?.domainName ?? "localhost";
+	const method = event.httpMethod.toUpperCase();
+	const url = `https://${host}${event.path}${buildSearch(event)}`;
+	let body;
+	if (event.body !== null && method !== "GET" && method !== "HEAD") body = Buffer.from(event.body, event.isBase64Encoded ? "base64" : "utf8");
+	return new Request(url, {
+		method,
+		headers: buildHeaders(event),
+		body
+	});
+};
+//#endregion
+//#region src/response.ts
+const TEXT_TYPE_PATTERN = /^text\/|^application\/(json|javascript|xml|x-www-form-urlencoded)\b|[+](json|xml)\b|charset=/i;
+const isTextContentType = (contentType) => contentType === null || TEXT_TYPE_PATTERN.test(contentType);
+/**
+* Convert a Web standard `Response` returned by `app.handle()` into an API
+* Gateway REST API (payload v1) proxy result. Text bodies are passed through
+* as UTF-8; anything else is base64-encoded with `isBase64Encoded: true`
+* (the REST API additionally requires matching `binaryMediaTypes` to decode
+* it on the way out).
+*/
+const responseToResult = async (response) => {
+	const multiValueHeaders = {};
+	for (const [key, value] of response.headers) {
+		if (key === "set-cookie") continue;
+		multiValueHeaders[key] = [value];
+	}
+	const setCookie = response.headers.getSetCookie();
+	if (setCookie.length > 0) multiValueHeaders["set-cookie"] = setCookie;
+	const buffer = Buffer.from(await response.arrayBuffer());
+	const isText = isTextContentType(response.headers.get("content-type"));
+	return {
+		statusCode: response.status,
+		multiValueHeaders,
+		body: buffer.toString(isText ? "utf8" : "base64"),
+		isBase64Encoded: !isText
+	};
+};
+//#endregion
+//#region src/index.ts
+/**
+* Wrap an Elysia app as an AWS Lambda handler for API Gateway REST API
+* (payload v1) proxy integration events.
+*
+* @example
+* ```ts
+* import { handle } from "elysia-lambda-handler";
+* import { app } from "./app.js";
+*
+* export const handler = handle(app);
+* ```
+*/
+const handle = (app) => {
+	return async (event) => {
+		return responseToResult(await app.handle(eventToRequest(event)));
+	};
+};
+//#endregion
+export { eventToRequest, handle, responseToResult };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "elysia-lambda-handler",
+  "version": "0.1.0",
+  "description": "Run Elysia apps on AWS Lambda with the Node.js runtime (API Gateway REST API events)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/datakahashi/elysia-lambda-handler.git"
+  },
+  "homepage": "https://github.com/datakahashi/elysia-lambda-handler#readme",
+  "bugs": {
+    "url": "https://github.com/datakahashi/elysia-lambda-handler/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "elysia",
+    "aws",
+    "lambda",
+    "api-gateway",
+    "handler",
+    "serverless"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "elysia": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.162",
+    "@types/node": "^24.0.0",
+    "elysia": "1",
+    "tsdown": "^0.22.9",
+    "typescript": "5",
+    "vitest": "^4.1.10"
+  }
+}