https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter
Official AWS Lambda HTTP adapter for Stone.js. Run your Stone.js apps on AWS Lambda with full Continuum lifecycle support.
https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter
aws aws-lambda context-aware continuum-architecture javascript official-stonejs stone-foundation stonejs stonejs-adapter typescript
Last synced: 11 months ago
JSON representation
Official AWS Lambda HTTP adapter for Stone.js. Run your Stone.js apps on AWS Lambda with full Continuum lifecycle support.
- Host: GitHub
- URL: https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter
- Owner: stone-foundation
- License: apache-2.0
- Created: 2025-01-16T04:08:13.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-14T17:52:28.000Z (about 1 year ago)
- Last Synced: 2025-06-14T18:53:10.831Z (about 1 year ago)
- Topics: aws, aws-lambda, context-aware, continuum-architecture, javascript, official-stonejs, stone-foundation, stonejs, stonejs-adapter, typescript
- Language: TypeScript
- Homepage: https://stonejs.dev
- Size: 393 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Stone.js - AWS Lambda HTTP Adapter
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter)
[](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter)
[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/main.yml)
[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/release.yml)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-http-adapter)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-http-adapter)
[](./SECURITY.md)
[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/security/code-scanning)
[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/network/updates)
[](https://conventionalcommits.org)
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
```bash
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
```ts
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 {
handle(event: IncomingEvent) {
const name = event.get('name', 'Lambda')
return { message: `Hello ${name}` }
}
}
```
### Imperative API
```ts
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('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` | 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:
```ts
interface AwsLambdaHttpAdapterContext {
rawEvent: AwsLambdaHttpEvent;
rawResponse?: RawHttpResponseOptions;
executionContext: Record;
incomingEvent?: IncomingHttpEvent;
outgoingResponse?: OutgoingHttpResponse;
incomingEventBuilder: IAdapterEventBuilder;
rawResponseBuilder: IAdapterEventBuilder>;
}
```
### AWS Lambda Event
```ts
export interface AwsLambdaHttpEvent extends Record {
path?: string
body?: unknown
rawPath?: string
encoding?: string
httpMethod?: string
isBase64Encoded?: boolean
headers: Record
queryStringParameters?: Record
requestContext?: {
identity?: {
sourceIp?: string
}
httpMethod?: string
http?: {
method?: string
sourceIp?: string
}
}
}
```
### AWS Lambda Response
```ts
export interface RawHttpResponseOptions {
body?: unknown
statusCode: number
statusMessage?: string
headers?: Record
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](https://stonejs.dev)
## API documentation
* [API](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/docs)
## Contributing
See [Contributing Guide](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/CONTRIBUTING.md)