{"id":40928194,"url":"https://github.com/riyanimam/typescript-lambda-template","last_synced_at":"2026-01-22T04:01:33.237Z","repository":{"id":333786061,"uuid":"1082165382","full_name":"riyanimam/typescript-lambda-template","owner":"riyanimam","description":"⚡ A production-ready AWS Lambda boilerplate using TypeScript, featuring streamlined deployment, local debugging, and optimized build configurations.","archived":false,"fork":false,"pushed_at":"2026-01-21T02:12:56.000Z","size":317,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-21T12:54:18.667Z","etag":null,"topics":["automation","aws-cdk","aws-lambda","backend","boilerplate","cloud-native","infrastructure-as-code","lambda-function","serverless","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/riyanimam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-10-23T20:39:55.000Z","updated_at":"2026-01-21T02:16:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/riyanimam/typescript-lambda-template","commit_stats":null,"previous_names":["riyanimam/typescript-lambda-example"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/riyanimam/typescript-lambda-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riyanimam%2Ftypescript-lambda-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riyanimam%2Ftypescript-lambda-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riyanimam%2Ftypescript-lambda-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riyanimam%2Ftypescript-lambda-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riyanimam","download_url":"https://codeload.github.com/riyanimam/typescript-lambda-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riyanimam%2Ftypescript-lambda-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28653626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"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":["automation","aws-cdk","aws-lambda","backend","boilerplate","cloud-native","infrastructure-as-code","lambda-function","serverless","typescript"],"created_at":"2026-01-22T04:01:32.516Z","updated_at":"2026-01-22T04:01:33.226Z","avatar_url":"https://github.com/riyanimam.png","language":"TypeScript","readme":"# TypeScript ESM Lambda Example\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-20+-green?logo=node.js)](https://nodejs.org/)\n[![AWS Lambda](https://img.shields.io/badge/AWS-Lambda-orange?logo=amazon-aws)](https://aws.amazon.com/lambda/)\n[![Biome](https://img.shields.io/badge/Biome-2.3-60a5fa?logo=biome)](https://biomejs.dev/)\n[![Vitest](https://img.shields.io/badge/Vitest-4.0-6E9F18?logo=vitest)](https://vitest.dev/)\n[![Code Style](https://img.shields.io/badge/code_style-biome-60a5fa)](https://biomejs.dev/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\nA production-ready AWS Lambda template using TypeScript with ECMAScript Modules (ESM), featuring\nS3-to-PostgreSQL CSV processing, comprehensive testing, and automated code quality workflows.\n\n## Features\n\n- **TypeScript with ESM**: Native ES modules using `.mts` extension and `NodeNext` module resolution\n- **AWS SDK v3**: Modern AWS integrations with S3, SQS event handling\n- **PostgreSQL Integration**: Batch CSV ingestion from S3 to PostgreSQL\n- **Production-Ready**: Error handling, retries, configurable batch processing\n- **Code Quality**: Biome for linting/formatting, Lefthook for git hooks, automated CI/CD\n- **Type Safety**: Full TypeScript types with AWS Lambda event definitions\n- **Testing**: Vitest with native ESM support and AWS SDK mocking\n\n## Prerequisites\n\n- **Node.js** \u003e= 20 (Lambda runtime: `nodejs20.x` or `nodejs22.x`)\n- **pnpm** \u003e= 10 (fast, disk-efficient package manager)\n- **PostgreSQL** (for local development and testing)\n- **AWS Account** (for deployment)\n\n## Quick Start\n\n### Install Dependencies\n\n```bash\npnpm install\n```\n\n### Build\n\nCompile TypeScript to JavaScript in the `dist/` directory:\n\n```bash\npnpm run build\n```\n\n### Run Tests\n\n```bash\npnpm test\n\n# Watch mode for development\npnpm run test:watch\n```\n\n### Lint and Format\n\n```bash\n# Check code with Biome\npnpm run lint\n\n# Auto-fix issues\npnpm run lint:fix\n\n# Format code\npnpm run format\n```\n\n## Project Structure\n\n```text\ntypescript-lambda-example/\n├── src/\n│   ├── handler.mts          # Main Lambda handler for SQS/S3 events\n│   └── s3-to-mssql.mts      # S3 CSV to PostgreSQL pipeline\n├── tests/\n│   └── handler.test.mts     # Jest tests with AWS SDK mocks\n├── .github/workflows/       # CI/CD automation\n├── dist/                    # Compiled JavaScript output\n├── tsconfig.json            # TypeScript ESM configuration\n├── jest.config.cjs          # Jest configuration for ESM\n├── .eslintrc.json           # ESLint rules\n├── .prettierrc              # Prettier formatting\n└── package.json             # Dependencies and scripts\n```\n\n## Lambda Handler\n\nThe main handler (`src/handler.mts`) processes SQS events where each message contains S3 event\nnotifications. It:\n\n1. Parses SQS messages and extracts S3 event details\n2. Fetches CSV files from S3\n3. Streams and parses CSV data\n4. Batch inserts rows into PostgreSQL\n5. Handles errors with configurable retry logic\n\n### Environment Variables\n\nConfigure these in your Lambda function:\n\n- `PGHOST` — PostgreSQL host\n- `PGPORT` — PostgreSQL port (default: 5432)\n- `PGDATABASE` — Database name\n- `PGUSER` — Database user\n- `PGPASSWORD` — Database password\n- `TABLE_NAME` — Target table (default: `csv_raw_rows`)\n- `BATCH_SIZE` — Insert batch size (default: 100)\n- `THROW_ON_ERROR` — Throw on DB errors for SQS retry (default: `true`)\n\n### Example S3 Event Structure\n\n```json\n{\n  \"Records\": [\n    {\n      \"eventVersion\": \"2.1\",\n      \"eventSource\": \"aws:s3\",\n      \"s3\": {\n        \"bucket\": { \"name\": \"my-bucket\" },\n        \"object\": { \"key\": \"data/file.csv\" }\n      }\n    }\n  ]\n}\n```\n\n## TypeScript and ESM\n\nThis project uses **ECMAScript Modules** with TypeScript:\n\n- Source files use `.mts` extension\n- `package.json` sets `\"type\": \"module\"`\n- `tsconfig.json` uses `\"module\": \"NodeNext\"` and `\"moduleResolution\": \"NodeNext\"`\n- Local imports require explicit `.mjs` extensions\n\n### Example Import\n\n```typescript\nimport type { SQSEvent } from \"aws-lambda\";\nimport { S3Client } from \"@aws-sdk/client-s3\";\nimport { myFunction } from \"./utils.mjs\"; // Note .mjs extension\n```\n\n## Development Workflow\n\n### Git Hooks with Lefthook\n\nGit hooks are automatically installed when you run `pnpm install`. They will:\n\n**Pre-commit:**\n\n- Run Biome linter and formatter on staged files\n- Lint markdown files\n- Remove trailing whitespace\n\n**Pre-push:**\n\n- Run tests\n- Build the project\n\nManual hook execution:\n\n```bash\nManual hook execution:\n\n```bash\n# Run pre-commit checks\nnpx lefthook run pre-commit\n\n# Run pre-push checks\nnpx lefthook run pre-push\n\n## Deployment\n\n### Package for Lambda\n\nCreate a deployment package with compiled code and dependencies:\n\n```bash\npnpm run build\nzip -r lambda-package.zip dist node_modules package.json\n```\n\n**Windows PowerShell:**\n\n```powershell\npnpm run build\nCompress-Archive -Path dist, node_modules, package.json `\n  -DestinationPath lambda-package.zip\n```\n\n### Lambda Configuration\n\n- **Runtime**: `nodejs20.x`\n- **Handler**: `dist/handler.handler`\n- **Architecture**: `x86_64` or `arm64`\n- **Memory**: 512 MB (adjust based on CSV size)\n- **Timeout**: 300 seconds (adjust for large files)\n- **Environment**: Set PostgreSQL and processing variables\n\n### Terraform Example\n\n```hcl\nresource \"aws_lambda_function\" \"csv_processor\" {\n  filename         = \"lambda-package.zip\"\n  function_name    = \"s3-csv-to-postgres\"\n  role            = aws_iam_role.lambda_role.arn\n  handler         = \"dist/handler.handler\"\n  runtime         = \"nodejs20.x\"\n  timeout         = 300\n  memory_size     = 512\n\n  environment {\n    variables = {\n      PGHOST         = var.db_host\n      PGDATABASE     = var.db_name\n      TABLE_NAME     = \"csv_data\"\n      BATCH_SIZE     = \"100\"\n    }\n  }\n}\n```\n\n## CI/CD\n\nGitHub Actions workflows automate quality checks:\n\n- **CI**: Build, test, lint on every push/PR\n- **Code Quality**: ESLint, Prettier, TypeScript type checking\n- **Security**: CodeQL analysis, dependency audits\n- **Semantic Release**: Automated versioning and changelogs\n\n## Contributing\n\n1. Create a feature branch\n2. Make changes with semantic commit messages (e.g., `feat:`, `fix:`)\n3. Ensure tests pass: `pnpm test`\n4. Ensure linting passes: `pnpm run lint`\n5. Submit pull request\n\n## Resources\n\n- [Development Guide](./DEVELOPMENT.md)\n- [Changelog](./CHANGELOG.md)\n- [AWS Lambda TypeScript](https://docs.aws.amazon.com/lambda/latest/dg/lambda-typescript.html)\n- [TypeScript ESM](https://www.typescriptlang.org/docs/handbook/esm-node.html)\n- [AWS SDK for JavaScript v3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)\n\n## License\n\nSee [LICENSE](./LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friyanimam%2Ftypescript-lambda-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friyanimam%2Ftypescript-lambda-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friyanimam%2Ftypescript-lambda-template/lists"}