{"id":50318343,"url":"https://github.com/severinglion/spec2lambda","last_synced_at":"2026-05-29T01:32:36.897Z","repository":{"id":325487096,"uuid":"1100759001","full_name":"severinglion/spec2lambda","owner":"severinglion","description":"spec2lambda is a spec-driven codegen tool for building scalable AWS Lambda APIs in TypeScript. It automates type-safe handler scaffolding and project structure from your OpenAPI spec—add endpoints by updating your spec, run codegen, and implement handler stubs. Fast, maintainable, and opinionated.","archived":false,"fork":false,"pushed_at":"2025-12-02T23:18:19.000Z","size":496,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-17T20:59:33.184Z","etag":null,"topics":["aws-lambda","developer-tools","nodejs","openapi","serverless","spec-driven-development","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/severinglion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T18:03:10.000Z","updated_at":"2025-12-02T23:43:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/severinglion/spec2lambda","commit_stats":null,"previous_names":["severinglion/spec2lambda"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/severinglion/spec2lambda","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severinglion%2Fspec2lambda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severinglion%2Fspec2lambda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severinglion%2Fspec2lambda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severinglion%2Fspec2lambda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/severinglion","download_url":"https://codeload.github.com/severinglion/spec2lambda/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/severinglion%2Fspec2lambda/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33633468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-lambda","developer-tools","nodejs","openapi","serverless","spec-driven-development","typescript"],"created_at":"2026-05-29T01:32:35.886Z","updated_at":"2026-05-29T01:32:36.860Z","avatar_url":"https://github.com/severinglion.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [spec2lambda](https://www.npmjs.com/package/spec2lambda)\n\n[![npm version](https://img.shields.io/npm/v/spec2lambda)](https://www.npmjs.com/package/spec2lambda)\n[![npm downloads](https://img.shields.io/npm/dm/spec2lambda)](https://www.npmjs.com/package/spec2lambda)\n[![GitHub Repo](https://img.shields.io/badge/GitHub-Repository-blue)](https://github.com/severinglion/spec2lambda)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\n**spec2lambda** is an opinionated, spec-driven code generation tool for building scalable AWS Lambda APIs in TypeScript. It enforces a clear project structure and automates type-safe handler scaffolding, all powered by your OpenAPI spec.\n\n---\n\n## Features\n- **Spec-first**: The OpenAPI document is the single source of truth for routes, types, and contracts.\n- **Type-safe**: Request/response types and schemas are generated from the spec and used everywhere.\n- **Separation of concerns**: Presentation (HTTP/Lambda), business logic, and infrastructure are clearly separated.\n- **Repeatable pattern**: Adding a new endpoint is always spec → generate → implement handler.\n\n---\n\n## Project Structure\nSee [`docs/project-structure.md`](./docs/project-structure.md) for a full breakdown.\n\n- `api/` — Your OpenAPI spec (`openapi.yml`).\n- `src/generated/` — All code generated from the spec (types, schemas, router config). **Generated. Always overwritten. Never edit directly.**\n- `src/handlers/` — Grouped Lambda handler implementations (e.g., `users.ts` for all user operations).\n- `src/presentation/` — Adapters, response helpers, and HTTP presentation logic.\n- `tests/` — Unit and integration tests.\n- `local-dev/` — Local development server setup and entrypoint.\n\n---\n\n## Getting Started\n\n### 1. Initialize a New Project\n\n```sh\nnpx spec2lambda init \u003cproject-name\u003e\n```\n\nThis scaffolds a new project with the opinionated structure, a starter OpenAPI spec, and all required scripts. The generated `package.json` includes a `generate` script for codegen.\n\n### 2. Edit Your OpenAPI Spec\n\nEdit `api/openapi.yml` to define or update endpoints. Each operation **must** have a unique `operationId`.\n\n### 3. Generate Code\n\n```sh\ncd \u003cproject-name\u003e\nnpm run generate\n```\n\nThis runs `spec2lambda generate` under the hood, updating all generated types, schemas, router config, and handler stubs (grouped by resource, e.g., `users.ts`).\n\n### 4. Implement Handlers\n\nFill in handler stubs in `src/handlers/`. Use adapters and responses from `src/presentation/`.\n\n### 5. Test and Iterate\n\nAdd or update tests in `tests/`. Use the local dev server for manual testing.\n\n---\n\n## CLI Command Reference\n\nAll commands are available via `npx spec2lambda ...` or, in generated projects, via npm scripts.\n\n### `init`\n\nScaffold a new Lambda service project in a new folder.\n\n**Usage:**\n\n```sh\nnpx spec2lambda init \u003cproject-name\u003e\n```\n\n**Behavior:**\n- Creates a new directory named `\u003cproject-name\u003e`.\n- Copies the opinionated starter structure and template files into the new directory.\n- Generates a `package.json` with the project name, a `generate` script, and `spec2lambda` as a dev dependency.\n- Fails if the target directory already exists.\n\n### `generate`\n\nRun codegen based on the OpenAPI spec. In generated projects, use:\n\n```sh\nnpm run generate\n```\n\n**Behavior:**\n- Parses the OpenAPI spec and generates types, schemas, routes, and handler stubs.\n- Overwrites all files in `src/generated/` and updates handler stubs as needed.\n\n### `help`\n\nShow usage information for the CLI.\n\n**Usage:**\n\n```sh\nnpx spec2lambda --help\nnpx spec2lambda -h\n```\n\n### `version`\n\nShow the current version of the CLI.\n\n**Usage:**\n\n```sh\nnpx spec2lambda --version\nnpx spec2lambda -v\n```\n\n---\n\n## Typical Workflow\n1. **Initialize the project**\n   - Run: `npx spec2lambda init \u003cproject-name\u003e`\n   - Navigate into the project: `cd \u003cproject-name\u003e`\n   - Install dependencies: `npm install`\n2. **Edit the OpenAPI spec**\n   - Edit `api/openapi.yml` to add or update endpoints.\n   - Set a unique `operationId` for each operation.\n3. **Generate code**\n   - Run: `npm run codegen`\n   - Updates all generated types, schemas, router config, and handler stubs (grouped by resource, e.g., `users.ts`).\n4. **Implement business logic**\n   - Fill in handler stubs in `src/handlers/`.\n   - Use adapters and responses from `src/presentation/`.\n\n---\n\n## Architecture Overview\n\nSee [`docs/project-structure.md`](./docs/project-structure.md) for directory roles and regeneration safety.\n\n### Presentation Layer (`src/presentation/`)\n- Adapts AWS Lambda events and local dev server requests to a common abstraction.\n- Converts internal responses to Lambda/Express responses.\n- Provides adapters and helpers for consistent HTTP output.\n\n### Domain Layer (`src/domain/`)\n- Core business logic and use cases.\n- Pure functions where possible.\n- No direct knowledge of HTTP, Lambda, or AWS-specific APIs.\n\n### (Optional) Infra Layer (`src/infra/`)\n- Implementation of repositories and clients (e.g., DynamoDB, S3, external APIs).\n- Configuration loading and service wiring.\n\n---\n\n## Guidelines for Coding Agents\n\u003e This section is for tools like ChatGPT, Copilot, Cody, etc.\n\n1. **Do not edit generated files**\n   - Never modify anything under `src/generated/` directly.\n   - Instead, change the OpenAPI spec (`api/openapi.yml`) and run `npm run generate`.\n2. **Follow the layering rules**\n   - HTTP/Lambda-specific logic: `src/presentation/`\n   - Business logic: `src/domain/`\n   - (Optional) AWS SDK/external system calls: `src/infra/`\n3. **When adding endpoints**\n   - Always update the OpenAPI spec first.\n   - Use `operationId` as the source of truth for handler grouping and mapping.\n   - Handlers are grouped by resource (e.g., all user operations in `users.ts`).\n4. **Type usage**\n   - Prefer using generated request/response types over custom ones.\n   - If types are missing or incorrect, update the spec and re-run codegen.\n5. **Safe places to refactor**\n   - `src/handlers/`, `src/domain/`, `tests/`.\n6. **Avoid breaking changes**\n   - Do not change public handler signatures or contract types without updating the OpenAPI spec and related tests.\n\n---\n\n## License\nMIT – see `LICENSE` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseveringlion%2Fspec2lambda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseveringlion%2Fspec2lambda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseveringlion%2Fspec2lambda/lists"}