{"id":29436874,"url":"https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter","last_synced_at":"2025-07-13T05:06:56.766Z","repository":{"id":272700440,"uuid":"917478871","full_name":"stone-foundation/stone-js-aws-lambda-http-adapter","owner":"stone-foundation","description":"Official AWS Lambda HTTP adapter for Stone.js. Run your Stone.js apps on AWS Lambda with full Continuum lifecycle support.","archived":false,"fork":false,"pushed_at":"2025-06-14T17:52:28.000Z","size":402,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-14T18:53:10.831Z","etag":null,"topics":["aws","aws-lambda","context-aware","continuum-architecture","javascript","official-stonejs","stone-foundation","stonejs","stonejs-adapter","typescript"],"latest_commit_sha":null,"homepage":"https://stonejs.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stone-foundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-16T04:08:13.000Z","updated_at":"2025-06-14T17:53:37.000Z","dependencies_parsed_at":"2025-03-01T01:21:51.037Z","dependency_job_id":"dd4863d3-5f2b-4069-b6a4-e924d84e3248","html_url":"https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter","commit_stats":null,"previous_names":["stonemjs/aws-lambda-http-adapter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stone-foundation/stone-js-aws-lambda-http-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-aws-lambda-http-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-aws-lambda-http-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-aws-lambda-http-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-aws-lambda-http-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stone-foundation","download_url":"https://codeload.github.com/stone-foundation/stone-js-aws-lambda-http-adapter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-aws-lambda-http-adapter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265091734,"owners_count":23710033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","context-aware","continuum-architecture","javascript","official-stonejs","stone-foundation","stonejs","stonejs-adapter","typescript"],"created_at":"2025-07-13T05:06:55.355Z","updated_at":"2025-07-13T05:06:56.754Z","avatar_url":"https://github.com/stone-foundation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stone.js - AWS Lambda HTTP Adapter\n\n[![npm](https://img.shields.io/npm/l/@stone-js/aws-lambda-http-adapter)](https://opensource.org/licenses/MIT)\n[![npm](https://img.shields.io/npm/v/@stone-js/aws-lambda-http-adapter)](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter)\n[![npm](https://img.shields.io/npm/dm/@stone-js/aws-lambda-http-adapter)](https://www.npmjs.com/package/@stone-js/aws-lambda-http-adapter)\n![Maintenance](https://img.shields.io/maintenance/yes/2025)\n[![Build Status](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/main.yml/badge.svg)](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/main.yml)\n[![Publish Package to npmjs](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/release.yml/badge.svg)](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/release.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-aws-lambda-http-adapter\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-http-adapter)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-aws-lambda-http-adapter\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-aws-lambda-http-adapter)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](./SECURITY.md)\n[![CodeQL](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/security/code-scanning)\n[![Dependabot Status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/network/updates)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\nThe **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.\n\n---\n\n## Introduction\n\nIn 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.\n\nThis 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.\n\n## Installation\n\n```bash\nnpm install @stone-js/aws-lambda-http-adapter\n````\n\n\u003e This package is **pure ESM**. Make sure your project uses ESM (`\"type\": \"module\"` in `package.json`) or configure your tooling accordingly.\n\n## Usage\n\nYou can integrate the adapter either declaratively with a decorator or imperatively using the `awsLambdaHttpAdapterBlueprint`.\n\n### Declarative API\n\n```ts\nimport { AwsLambdaHttp } from '@stone-js/aws-lambda-http-adapter'\nimport { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'\n\n@StoneApp()\n@AwsLambdaHttp({ default: true })\nexport class Application implements IEventHandler\u003cIncomingEvent\u003e {\n  handle(event: IncomingEvent) {\n    const name = event.get\u003cstring\u003e('name', 'Lambda')\n    return { message: `Hello ${name}` }\n  }\n}\n```\n\n### Imperative API\n\n```ts\nimport { defineStoneApp, IncomingEvent, defineConfig, IBlueprint } from '@stone-js/core'\nimport { awsLambdaHttpAdapterBlueprint, AWS_LAMBDA_HTTP_PLATFORM } from '@stone-js/aws-lambda-http-adapter'\n\nconst handler = (event: IncomingEvent) =\u003e {\n  const name = event.get\u003cstring\u003e('name', 'Lambda')\n  return { message: `Hi ${name}` }\n}\n\nexport const App = defineStoneApp(handler, {}, [awsLambdaHttpAdapterBlueprint])\n\nexport const AppConfig = defineConfig({\n  afterConfigure(blueprint: IBlueprint) {\n    if (blueprint.is('stone.adapter.platform', AWS_LAMBDA_HTTP_PLATFORM)) {\n      blueprint.set('stone.adapter.default', true)\n    }\n  }\n})\n```\n\n## What It Enables\n\n* **Serverless by Design**\n  Build modern HTTP APIs or websites running entirely on AWS Lambda behind API Gateway or ALB.\n\n* **Clean Separation of Concerns**\n  Your app never sees AWS-specific payloads. All requests and responses are fully normalized by the adapter.\n\n* **Full Continuum Integration**\n  Request becomes `IncomingEvent`, response becomes `OutgoingResponse`. Lambda is just another execution environment.\n\n* **Small, Fast, Efficient**\n  No cold start bloat. No Express or frameworks. Just your logic and the lightweight Stone.js runtime.\n\n* **Lifecycle Support**\n  Includes support for `onStart`, `onStop`, error hooks, and adapter middleware.\n\n* **Typed Event Context**\n  Access query, body, headers, cookies, IPs and more with full TypeScript support.\n\n* **Zero Glue Code**\n  No need to write `handler(event, context)` boilerplate. Stone.js manages that for you.\n\n* **Multi-platform Ready**\n  The same app can run locally with Node, in the browser, or in the cloud, just change the adapter.\n\n## Configuration Options\n\nUnlike Node, this adapter inherits all standard options from the core `AdapterConfig`:\n\n| Option          | Type                                      | Description                                      |\n| --------------- | ----------------------------------------- | ------------------------------------------------ |\n| `default`       | `boolean`                                 | Set as the default adapter for your app          |\n| `alias`         | `string`                                  | Optional name to reference this adapter          |\n| `current`       | `boolean`                                 | Marks this adapter as active at runtime          |\n| `middleware[]`  | `AdapterMixedPipeType[]`                  | Middleware executed during the adapter lifecycle |\n| `errorHandlers` | `Record\u003cstring, MetaAdapterErrorHandler\u003e` | Customize error response formatting or behavior  |\n\n\u003e Note: AWS Lambda automatically injects its execution context and raw event. This adapter handles both without manual plumbing.\n\n## Adapter Context Shape\n\nWhen middleware or hooks execute, the AWS Lambda adapter provides this normalized context:\n\n```ts\ninterface AwsLambdaHttpAdapterContext {\n  rawEvent: AwsLambdaHttpEvent;\n  rawResponse?: RawHttpResponseOptions;\n  executionContext: Record\u003cstring, unknown\u003e;\n  incomingEvent?: IncomingHttpEvent;\n  outgoingResponse?: OutgoingHttpResponse;\n  incomingEventBuilder: IAdapterEventBuilder\u003cIncomingHttpEventOptions, IncomingHttpEvent\u003e;\n  rawResponseBuilder: IAdapterEventBuilder\u003cRawHttpResponseOptions, IRawResponseWrapper\u003cRawHttpResponseOptions\u003e\u003e;\n}\n```\n\n### AWS Lambda Event\n\n```ts\nexport interface AwsLambdaHttpEvent extends Record\u003cstring, unknown\u003e {\n  path?: string\n  body?: unknown\n  rawPath?: string\n  encoding?: string\n  httpMethod?: string\n  isBase64Encoded?: boolean\n  headers: Record\u003cstring, string\u003e\n  queryStringParameters?: Record\u003cstring, string\u003e\n  requestContext?: {\n    identity?: {\n      sourceIp?: string\n    }\n    httpMethod?: string\n    http?: {\n      method?: string\n      sourceIp?: string\n    }\n  }\n}\n```\n\n### AWS Lambda Response\n\n```ts\nexport interface RawHttpResponseOptions {\n  body?: unknown\n  statusCode: number\n  statusMessage?: string\n  headers?: Record\u003cstring, string\u003e\n  isBase64Encoded?: boolean\n}\n```\n\nThis context ensures complete control over request handling and response shaping, even in a FaaS environment.\n\n## Summary\n\nThe `@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.\n\n## Learn More\n\nThis package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.\n\nExplore the full documentation: [https://stonejs.dev](https://stonejs.dev)\n\n## API documentation\n\n* [API](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/docs)\n\n## Contributing\n\nSee [Contributing Guide](https://github.com/stone-foundation/stone-js-aws-lambda-http-adapter/blob/main/CONTRIBUTING.md)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstone-foundation%2Fstone-js-aws-lambda-http-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstone-foundation%2Fstone-js-aws-lambda-http-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstone-foundation%2Fstone-js-aws-lambda-http-adapter/lists"}