@standardserver/aws-lambda

@standardserver/aws-lambda adapts AWS Lambda events and response streams to the transport-agnostic request and response model defined by Standard Server.

Standard Server provides a unified interface for client-server communication across HTTP and message-based transports. It lets you write handlers against the same request, response, body, and streaming primitives whether the underlying transport is the Fetch API, Node.js HTTP, HTTP/2, or a peer-style message channel.

This package is the AWS Lambda adapter for that model. It converts an API Gateway proxy event — payload format version 1.0 or 2.0, the latter also used by Lambda Function URLs — into a StandardLazyRequest, and writes a StandardResponse back through the stream provided by awslambda.streamifyResponse, so streaming bodies such as server-sent events flow to the client as they are produced instead of being buffered.

Entry Point

The package exports a single entry point:

| Export | Purpose | | ---------------------------- | ---------------------------------------------------------- | | @standardserver/aws-lambda | AWS Lambda adapter helpers for events and response streams |

Package overview

The main entry point exposes these helpers:

| Group | Exports | Purpose | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Request and response | toStandardLazyRequest(), sendStandardResponse() | Adapt Lambda events and response streams to Standard Server | | Lower-level helpers | toStandardUrl(), toStandardHeaders(), getEventHeader(), toStandardBody(), toLambdaHeaders() | Convert individual pieces of an event | | Types and option shapes | APIGatewayProxyEvent, APIGatewayProxyEventV2, AnyAPIGatewayProxyEvent, HttpResponseStream, AwsLambdaGlobal, SendStandardResponseOptions | Type handler inputs and serializer options |

APIGatewayProxyEvent and APIGatewayProxyEventV2 are structural subsets of the same-named types from @types/aws-lambda, so events typed with either work; the adapter accepts both via AnyAPIGatewayProxyEvent and tells them apart by the top-level httpMethod field only payload format 1.0 carries. AwsLambdaGlobal describes the awslambda global the Lambda Node.js runtime injects — the package deliberately does not declare global, so importing it never pollutes your project's global types. Declare the global yourself where you need typed access to awslambda.streamifyResponse.

Server-side request handling

Use toStandardLazyRequest() to convert the incoming event into a StandardLazyRequest, then sendStandardResponse() to write the resulting StandardResponse back through the response stream. The handler must be wrapped with awslambda.streamifyResponse, and the function must run on the AWS Lambda Node.js runtime with response streaming enabled.

import type { AwsLambdaGlobal } from '@standardserver/aws-lambda'
import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
import { sendStandardResponse, toStandardLazyRequest } from '@standardserver/aws-lambda'

// injected by the AWS Lambda Node.js runtime when response streaming is enabled
declare const awslambda: AwsLambdaGlobal

async function handle(request: StandardLazyRequest): Promise<StandardResponse> {
  const body = await request.resolveBody()

  return {
    status: 200,
    headers: { 'content-type': 'application/json' },
    body: {
      ok: true,
      method: request.method,
      url: request.url,
      received: body,
    },
  }
}

export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => {
  const standardRequest = toStandardLazyRequest(event, responseStream)
  const standardResponse = await handle(standardRequest)

  await sendStandardResponse(responseStream, standardResponse, {/** options */})
})

sendStandardResponse() sends the status, headers, and cookies as the response stream metadata prelude via awslambda.HttpResponseStream.from(), then streams the body. It resolves once the response is fully flushed, and rejects if the stream errors.

[!TIP] When sending responses, you can pass additional options such as event-stream keep-alive.

Resolving Body

The event carries the request body as a fully buffered, optionally base64-encoded string. resolveBody(hint?) decodes it and determines how to parse it using the following priority:

1. If hint? is provided, use it as the StandardBodyHint.
2. Otherwise, if the standard-server header is present, use it as the StandardBodyHint.
3. Otherwise, if content-type is one of the common types, parse accordingly.
4. Otherwise, if content-length exists, treat the body as file; if not, treat it as octet-stream.

[!TIP] For efficient communication, set the standard-server header to explicitly hint the body type, especially for file or binary streaming. For example, if you upload a file with a common content-type such as application/json but omit the standard-server header, the server may interpret it as JSON and parse it unexpectedly.

Lambda behavior to be aware of

• Response streaming must be enabled. sendStandardResponse() relies on the awslambda global, which only exists on the AWS Lambda Node.js runtime, and on the metadata prelude of awslambda.HttpResponseStream, which the platform only interprets for streaming-enabled invocations.
• set-cookie is sent via metadata cookies. Multiple cookies survive because they are sent through the dedicated cookies metadata field; every other multi-value header is joined with , .
• Request bodies are buffered. API Gateway delivers the whole request body at once, so request-side streaming degrades to a single buffered chunk. Response-side streaming is real streaming.
• Payload format 1.0 query strings are re-encoded. API Gateway delivers them url-decoded, so the adapter re-encodes them when reconstructing the standard url. Payload format 2.0 provides the already encoded rawQueryString, which is used as-is.
• Payload format 2.0 cookies are restored. API Gateway strips the cookie header into the separate cookies field, and the adapter joins them back into a cookie header on the standard request.

Learn more

For the higher-level project overview, see the root Standard Server README.

For the Node.js primitives this adapter is built on, see the Node.js adapter documentation.

Sponsors

Like what we build over at middleapi? You can help keep it going here: GitHub Sponsors. Every bit helps! 🚀

🏆 Platinum Sponsor

🥈 Silver Sponsor

Generous Sponsors

Sponsors

Backers

Past Sponsors