https://github.com/stone-foundation/stone-js-aws-lambda-adapter
General-purpose AWS Lambda adapter for Stone.js, run any app in serverless environments, beyond HTTP. Supports queues, events, schedulers, and background jobs.
https://github.com/stone-foundation/stone-js-aws-lambda-adapter
aws-lambda context-aware continuum-architecture javascript official-stonejs stone-foundation stonejs stonejs-adapter typescript
Last synced: 5 months ago
JSON representation
General-purpose AWS Lambda adapter for Stone.js, run any app in serverless environments, beyond HTTP. Supports queues, events, schedulers, and background jobs.
- Host: GitHub
- URL: https://github.com/stone-foundation/stone-js-aws-lambda-adapter
- Owner: stone-foundation
- License: mit
- Created: 2024-04-20T12:10:43.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-14T19:56:49.000Z (about 1 year ago)
- Last Synced: 2025-06-14T20:12:52.861Z (about 1 year ago)
- Topics: aws-lambda, context-aware, continuum-architecture, javascript, official-stonejs, stone-foundation, stonejs, stonejs-adapter, typescript
- Language: TypeScript
- Homepage: https://stonejs.dev
- Size: 305 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Stone.js - AWS Lambda Adapter
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@stone-js/aws-lambda-adapter)
[](https://www.npmjs.com/package/@stone-js/aws-lambda-adapter)
[](https://github.com/stone-foundation/stone-js-aws-lambda-adapter/actions/workflows/main.yml)
[](https://github.com/stone-foundation/stone-js-aws-lambda-adapter/actions/workflows/release.yml)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-adapter)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-adapter)
[](./SECURITY.md)
[](https://github.com/stone-foundation/stone-js-aws-lambda-adapter/security/code-scanning)
[](https://github.com/stone-foundation/stone-js-aws-lambda-adapter/network/updates)
[](https://conventionalcommits.org)
The **AWS Lambda Adapter** allows you to deploy any Stone.js application as a general-purpose Lambda function, not tied to HTTP. Whether you're building background jobs, event processors, queue consumers, or cron-based automation, this adapter brings the full power of Continuum Architecture to the serverless world.
---
## Introduction
In Stone.js, **adapters** connect your app to the outside world. The AWS Lambda Adapter enables your logic to run in any AWS Lambda context, triggered by SQS, EventBridge, CloudWatch, or even a custom invocation.
This adapter captures the Lambda `event` and `context`, wraps them in a consistent `IncomingEvent`, and allows you to produce a clean `OutgoingResponse`, or nothing at all, if your function is fire-and-forget.
The result? One system, one lifecycle, one architectural model, everywhere.
## Installation
```bash
npm install @stone-js/aws-lambda-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 register the adapter via class decorators or programmatically using the blueprint.
### Declarative API
```ts
import { AwsLambda } from '@stone-js/aws-lambda-adapter'
import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'
@StoneApp()
@AwsLambda()
export class LambdaHandler implements IEventHandler {
async handle(event: IncomingEvent) {
const payload = event.get('payload')
// Process message or do background work
return { success: true, received: payload }
}
}
```
### Imperative API
```ts
import { defineStoneApp, IncomingEvent } from '@stone-js/core'
import { awsLambdaAdapterBlueprint } from '@stone-js/aws-lambda-adapter'
const handler = async (event: IncomingEvent) => {
const task = event.get('task')
console.log(`Processing task: ${task}`)
}
export const App = defineStoneApp(handler, {}, [awsLambdaAdapterBlueprint])
```
## What It Enables
* **General-Purpose Lambda Support**
Process any AWS Lambda invocation, from SQS to EventBridge, without HTTP assumptions.
* **Full Continuum Integration**
The raw Lambda event and context become cleanly wrapped in a Stone `IncomingEvent`.
* **Minimal Setup, Max Power**
Start with a single function, scale to a complex pipeline, no boilerplate required.
* **No Vendor Lock-in**
The logic is decoupled from Lambda. You can reuse and test it outside of AWS with zero changes.
* **Flexible Output Handling**
Return an `OutgoingResponse`, throw errors, or simply return `void`, your flow, your rules.
* **Lifecycle Hooks**
Define `onStart`, `onStop`, and hook into adapter middleware.
* **First-Class TypeScript Support**
All context and behavior are typed and autocompleted out of the box.
## Configuration Options
The AWS Lambda Adapter inherits the base Stone.js `AdapterConfig` type. It does not define custom options, but you can configure:
| 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 |
## Adapter Context Shape
During execution, adapter middleware and hooks receive a full context object:
```ts
interface AwsLambdaAdapterContext {
rawEvent: unknown; // The raw AWS Lambda event input
rawResponse?: unknown; // Optionally the return response (if expected)
executionContext: LambdaContext; // AWS Lambda context object
incomingEvent?: IncomingEvent;
outgoingResponse?: OutgoingResponse;
incomingEventBuilder: IAdapterEventBuilder;
rawResponseBuilder: IAdapterEventBuilder;
}
```
This allows for full introspection and control at all stages of execution, including advanced transformation and diagnostics.
## Summary
The `@stone-js/aws-lambda-adapter` bridges your system with AWS Lambda, but without compromising your architecture. Whether you're building automation scripts, stream processors, or serverless services, this adapter keeps your code structured, composable, and future-proof.
Build it once. Deploy it anywhere.
## Learn More
This package is part of the Stone.js ecosystem, a JavaScript framework for cloud-native applications built on 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-adapter/blob/main/docs)
## Contributing
See [Contributing Guide](https://github.com/stone-foundation/stone-js-aws-lambda-adapter/blob/main/CONTRIBUTING.md)