Stone.js - AWS Lambda HTTP Adapter

The AWS Lambda HTTP Adapter allows your Stone.js application to run as a fully event-driven Lambda function behind API Gateway or any Lambda-compatible HTTP environment. It seamlessly transforms API Gateway events into IncomingEvent and returns OutgoingResponse, adhering to the Continuum Architecture.

Introduction

In Stone.js, adapters serve as bridges between raw platform input and structured internal events. The AWS Lambda HTTP Adapter processes API Gateway-style HTTP events and turns them into normalized IncomingEvent objects. It also formats your system’s OutgoingResponse into a valid Lambda HTTP response payload.

This adapter empowers you to write cloud-native functions that stay decoupled from AWS specifics while preserving the full Stone.js lifecycle, type safety, and cross-platform consistency.

Installation

npm install @stone-js/aws-lambda-http-adapter

This package is pure ESM. Make sure your project uses ESM ("type": "module" in package.json) or configure your tooling accordingly.

Usage

You can integrate the adapter either declaratively with a decorator or imperatively using the awsLambdaHttpAdapterBlueprint.

Declarative API

import { AwsLambdaHttp } from '@stone-js/aws-lambda-http-adapter'
import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'

@StoneApp()
@AwsLambdaHttp({ default: true })
export class Application implements IEventHandler<IncomingEvent> {
  handle(event: IncomingEvent) {
    const name = event.get<string>('name', 'Lambda')
    return { message: `Hello ${name}` }
  }
}

Imperative API

import { defineStoneApp, IncomingEvent, defineConfig, IBlueprint } from '@stone-js/core'
import { awsLambdaHttpAdapterBlueprint, AWS_LAMBDA_HTTP_PLATFORM } from '@stone-js/aws-lambda-http-adapter'

const handler = (event: IncomingEvent) => {
  const name = event.get<string>('name', 'Lambda')
  return { message: `Hi ${name}` }
}

export const App = defineStoneApp(handler, {}, [awsLambdaHttpAdapterBlueprint])

export const AppConfig = defineConfig({
  afterConfigure(blueprint: IBlueprint) {
    if (blueprint.is('stone.adapter.platform', AWS_LAMBDA_HTTP_PLATFORM)) {
      blueprint.set('stone.adapter.default', true)
    }
  }
})

What It Enables

• Serverless by Design Build modern HTTP APIs or websites running entirely on AWS Lambda behind API Gateway or ALB.

• Clean Separation of Concerns Your app never sees AWS-specific payloads. All requests and responses are fully normalized by the adapter.

• Full Continuum Integration Request becomes IncomingEvent, response becomes OutgoingResponse. Lambda is just another execution environment.

• Small, Fast, Efficient No cold start bloat. No Express or frameworks. Just your logic and the lightweight Stone.js runtime.

• Lifecycle Support Includes support for onStart, onStop, error hooks, and adapter middleware.

• Typed Event Context Access query, body, headers, cookies, IPs and more with full TypeScript support.

• Zero Glue Code No need to write handler(event, context) boilerplate. Stone.js manages that for you.

• Multi-platform Ready The same app can run locally with Node, in the browser, or in the cloud, just change the adapter.

Configuration Options

Unlike Node, this adapter inherits all standard options from the core AdapterConfig:

| Option | Type | Description | | --------------- | ----------------------------------------- | ------------------------------------------------ | | default | boolean | Set as the default adapter for your app | | alias | string | Optional name to reference this adapter | | current | boolean | Marks this adapter as active at runtime | | middleware[] | AdapterMixedPipeType[] | Middleware executed during the adapter lifecycle | | errorHandlers | Record<string, MetaAdapterErrorHandler> | Customize error response formatting or behavior |

Note: AWS Lambda automatically injects its execution context and raw event. This adapter handles both without manual plumbing.

Adapter Context Shape

When middleware or hooks execute, the AWS Lambda adapter provides this normalized context:

interface AwsLambdaHttpAdapterContext {
  rawEvent: AwsLambdaHttpEvent;
  rawResponse?: RawHttpResponseOptions;
  executionContext: Record<string, unknown>;
  incomingEvent?: IncomingHttpEvent;
  outgoingResponse?: OutgoingHttpResponse;
  incomingEventBuilder: IAdapterEventBuilder<IncomingHttpEventOptions, IncomingHttpEvent>;
  rawResponseBuilder: IAdapterEventBuilder<RawHttpResponseOptions, IRawResponseWrapper<RawHttpResponseOptions>>;
}

AWS Lambda Event

export interface AwsLambdaHttpEvent extends Record<string, unknown> {
  path?: string
  body?: unknown
  rawPath?: string
  encoding?: string
  httpMethod?: string
  isBase64Encoded?: boolean
  headers: Record<string, string>
  queryStringParameters?: Record<string, string>
  requestContext?: {
    identity?: {
      sourceIp?: string
    }
    httpMethod?: string
    http?: {
      method?: string
      sourceIp?: string
    }
  }
}

AWS Lambda Response

export interface RawHttpResponseOptions {
  body?: unknown
  statusCode: number
  statusMessage?: string
  headers?: Record<string, string>
  isBase64Encoded?: boolean
}

This context ensures complete control over request handling and response shaping, even in a FaaS environment.

Summary

The @stone-js/aws-lambda-http-adapter makes your Stone.js app cloud-native, cost-efficient, and Lambda-ready. Embrace the event-driven cloud with minimal effort and maximum architectural clarity.

Learn More

This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.

Explore the full documentation: https://stonejs.dev

API documentation

• API

Contributing

See Contributing Guide