@stone-js/aws-lambda-http-adapter 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +187 -0
- package/dist/index.d.ts +640 -0
- package/dist/index.js +889 -0
- package/package.json +110 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Stone.js
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# Stone.js - AWS Lambda HTTP Adapter
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter)
|
|
5
|
+
[](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter)
|
|
6
|
+
|
|
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)
|
|
14
|
+
[](https://conventionalcommits.org)
|
|
15
|
+
|
|
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.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Introduction
|
|
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)
|
|
184
|
+
|
|
185
|
+
## Contributing
|
|
186
|
+
|
|
187
|
+
See [Contributing Guide](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/CONTRIBUTING.md)
|