|
1 | | -# Stone.js: AWS Lambda Adapters |
| 1 | +# Stone.js - AWS Lambda HTTP Adapter |
2 | 2 |
|
3 | | -[](https://opensource.org/licenses/MIT) |
| 3 | +[](https://opensource.org/licenses/MIT) |
4 | 4 | [](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter) |
5 | 5 | [](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter) |
6 | 6 |  |
7 | | -[](https://github.com/stonemjs/aws-lambda-http-adapter/actions/workflows/release.yml) |
8 | | -[](https://github.com/stonemjs/aws-lambda-http-adapter/network/updates) |
| 7 | +[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/main.yml) |
| 8 | +[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/release.yml) |
| 9 | +[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-http-adapter) |
| 10 | +[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-http-adapter) |
| 11 | +[](./SECURITY.md) |
| 12 | +[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/security/code-scanning) |
| 13 | +[](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/network/updates) |
9 | 14 | [](https://conventionalcommits.org) |
10 | 15 |
|
11 | | -Stone.js AWS Lambda HTTP Adapters with typings. |
| 16 | +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. |
12 | 17 |
|
13 | 18 | --- |
14 | 19 |
|
15 | | -Get started with the [documentation](https://stonejs.com/docs/architecture/adapter.html). |
| 20 | +## Introduction |
16 | 21 |
|
| 22 | +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. |
| 23 | + |
| 24 | +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. |
| 25 | + |
| 26 | +## Installation |
| 27 | + |
| 28 | +```bash |
| 29 | +npm install @stone-js/aws-lambda-http-adapter |
| 30 | +```` |
| 31 | + |
| 32 | +> This package is **pure ESM**. Make sure your project uses ESM (`"type": "module"` in `package.json`) or configure your tooling accordingly. |
| 33 | + |
| 34 | +## Usage |
| 35 | + |
| 36 | +You can integrate the adapter either declaratively with a decorator or imperatively using the `awsLambdaHttpAdapterBlueprint`. |
| 37 | + |
| 38 | +### Declarative API |
| 39 | + |
| 40 | +```ts |
| 41 | +import { AwsLambdaHttp } from '@stone-js/aws-lambda-http-adapter' |
| 42 | +import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core' |
| 43 | +
|
| 44 | +@StoneApp() |
| 45 | +@AwsLambdaHttp({ default: true }) |
| 46 | +export class Application implements IEventHandler<IncomingEvent> { |
| 47 | + handle(event: IncomingEvent) { |
| 48 | + const name = event.get<string>('name', 'Lambda') |
| 49 | + return { message: `Hello ${name}` } |
| 50 | + } |
| 51 | +} |
| 52 | +``` |
| 53 | +
|
| 54 | +### Imperative API |
| 55 | +
|
| 56 | +```ts |
| 57 | +import { defineStoneApp, IncomingEvent, defineConfig, IBlueprint } from '@stone-js/core' |
| 58 | +import { awsLambdaHttpAdapterBlueprint, AWS_LAMBDA_HTTP_PLATFORM } from '@stone-js/aws-lambda-http-adapter' |
| 59 | +
|
| 60 | +const handler = (event: IncomingEvent) => { |
| 61 | + const name = event.get<string>('name', 'Lambda') |
| 62 | + return { message: `Hi ${name}` } |
| 63 | +} |
| 64 | +
|
| 65 | +export const App = defineStoneApp(handler, {}, [awsLambdaHttpAdapterBlueprint]) |
| 66 | +
|
| 67 | +export const AppConfig = defineConfig({ |
| 68 | + afterConfigure(blueprint: IBlueprint) { |
| 69 | + if (blueprint.is('stone.adapter.platform', AWS_LAMBDA_HTTP_PLATFORM)) { |
| 70 | + blueprint.set('stone.adapter.default', true) |
| 71 | + } |
| 72 | + } |
| 73 | +}) |
| 74 | +``` |
| 75 | +
|
| 76 | +## What It Enables |
| 77 | +
|
| 78 | +* **Serverless by Design** |
| 79 | + Build modern HTTP APIs or websites running entirely on AWS Lambda behind API Gateway or ALB. |
| 80 | +
|
| 81 | +* **Clean Separation of Concerns** |
| 82 | + Your app never sees AWS-specific payloads. All requests and responses are fully normalized by the adapter. |
| 83 | +
|
| 84 | +* **Full Continuum Integration** |
| 85 | + Request becomes `IncomingEvent`, response becomes `OutgoingResponse`. Lambda is just another execution environment. |
| 86 | +
|
| 87 | +* **Small, Fast, Efficient** |
| 88 | + No cold start bloat. No Express or frameworks. Just your logic and the lightweight Stone.js runtime. |
| 89 | +
|
| 90 | +* **Lifecycle Support** |
| 91 | + Includes support for `onStart`, `onStop`, error hooks, and adapter middleware. |
| 92 | +
|
| 93 | +* **Typed Event Context** |
| 94 | + Access query, body, headers, cookies, IPs and more with full TypeScript support. |
| 95 | +
|
| 96 | +* **Zero Glue Code** |
| 97 | + No need to write `handler(event, context)` boilerplate. Stone.js manages that for you. |
| 98 | +
|
| 99 | +* **Multi-platform Ready** |
| 100 | + The same app can run locally with Node, in the browser, or in the cloud, just change the adapter. |
| 101 | +
|
| 102 | +## Configuration Options |
| 103 | +
|
| 104 | +Unlike Node, this adapter inherits all standard options from the core `AdapterConfig`: |
| 105 | +
|
| 106 | +| Option | Type | Description | |
| 107 | +| --------------- | ----------------------------------------- | ------------------------------------------------ | |
| 108 | +| `default` | `boolean` | Set as the default adapter for your app | |
| 109 | +| `alias` | `string` | Optional name to reference this adapter | |
| 110 | +| `current` | `boolean` | Marks this adapter as active at runtime | |
| 111 | +| `middleware[]` | `AdapterMixedPipeType[]` | Middleware executed during the adapter lifecycle | |
| 112 | +| `errorHandlers` | `Record<string, MetaAdapterErrorHandler>` | Customize error response formatting or behavior | |
| 113 | +
|
| 114 | +> Note: AWS Lambda automatically injects its execution context and raw event. This adapter handles both without manual plumbing. |
| 115 | +
|
| 116 | +## Adapter Context Shape |
| 117 | +
|
| 118 | +When middleware or hooks execute, the AWS Lambda adapter provides this normalized context: |
| 119 | +
|
| 120 | +```ts |
| 121 | +interface AwsLambdaHttpAdapterContext { |
| 122 | + rawEvent: AwsLambdaHttpEvent; |
| 123 | + rawResponse?: RawHttpResponseOptions; |
| 124 | + executionContext: Record<string, unknown>; |
| 125 | + incomingEvent?: IncomingHttpEvent; |
| 126 | + outgoingResponse?: OutgoingHttpResponse; |
| 127 | + incomingEventBuilder: IAdapterEventBuilder<IncomingHttpEventOptions, IncomingHttpEvent>; |
| 128 | + rawResponseBuilder: IAdapterEventBuilder<RawHttpResponseOptions, IRawResponseWrapper<RawHttpResponseOptions>>; |
| 129 | +} |
| 130 | +``` |
| 131 | +
|
| 132 | +### AWS Lambda Event |
| 133 | +
|
| 134 | +```ts |
| 135 | +export interface AwsLambdaHttpEvent extends Record<string, unknown> { |
| 136 | + path?: string |
| 137 | + body?: unknown |
| 138 | + rawPath?: string |
| 139 | + encoding?: string |
| 140 | + httpMethod?: string |
| 141 | + isBase64Encoded?: boolean |
| 142 | + headers: Record<string, string> |
| 143 | + queryStringParameters?: Record<string, string> |
| 144 | + requestContext?: { |
| 145 | + identity?: { |
| 146 | + sourceIp?: string |
| 147 | + } |
| 148 | + httpMethod?: string |
| 149 | + http?: { |
| 150 | + method?: string |
| 151 | + sourceIp?: string |
| 152 | + } |
| 153 | + } |
| 154 | +} |
| 155 | +``` |
| 156 | +
|
| 157 | +### AWS Lambda Response |
| 158 | +
|
| 159 | +```ts |
| 160 | +export interface RawHttpResponseOptions { |
| 161 | + body?: unknown |
| 162 | + statusCode: number |
| 163 | + statusMessage?: string |
| 164 | + headers?: Record<string, string> |
| 165 | + isBase64Encoded?: boolean |
| 166 | +} |
| 167 | +``` |
| 168 | +
|
| 169 | +This context ensures complete control over request handling and response shaping, even in a FaaS environment. |
| 170 | +
|
| 171 | +## Summary |
| 172 | +
|
| 173 | +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. |
| 174 | +
|
| 175 | +## Learn More |
| 176 | +
|
| 177 | +This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture. |
| 178 | +
|
| 179 | +Explore the full documentation: [https://stonejs.dev](https://stonejs.dev) |
| 180 | +
|
| 181 | +## API documentation |
| 182 | +
|
| 183 | +* [API](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/docs) |
17 | 184 |
|
18 | 185 | ## Contributing |
19 | 186 |
|
20 | | -See [Contributing Guide](https://github.com/stonemjs/aws-lambda-http-adapter/blob/main/CONTRIBUTING.md). |
| 187 | +See [Contributing Guide](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/CONTRIBUTING.md) |
0 commit comments