chore: create event-handler utility workspace (#2858)

Co-authored-by: Alexander Schueren <[email protected]>

.github/actions/cached-node-modules/action.yml

@@ -43,5 +43,6 @@ runs:
         npm run build -w packages/idempotency & \
         npm run build -w packages/batch & \
         npm run build -w packages/testing & \
-        npm run build -w packages/parser
+        npm run build -w packages/parser & \
+        npm run build -w packages/event-handler
       shell: bash

.github/boring-cyborg.yml

@@ -18,6 +18,9 @@ labelPRBasedOnFilePath:
   parser:
     - packages/parser/src/*
     - packages/parser/src/**/*
+  event-handler:
+    - packages/event-handler/src/*
+    - packages/event-handler/src/**/*
   validator:
     - packages/validator/src/*
     - packages/validator/src/**/*
@@ -53,6 +56,9 @@ labelPRBasedOnFilePath:
     - packages/parser/tests/*
     - packages/parser/tests/**/*
     - packages/parser/jest.config.cjs
+    - packages/event-handler/tests/*
+    - packages/event-handler/tests/**/*
+    - packages/event-handler/jest.config.cjs
     - packages/validator/tests/*
     - packages/validator/tests/**/*
     - packages/validator/jest.config.cjs
@@ -108,6 +114,8 @@ labelPRBasedOnFilePath:
     - packages/tracer/README.md
     - packages/parser/tsconfig*.json
     - packages/parser/README.md
+    - packages/event-handler/tsconfig*.json
+    - packages/event-handler/README.md
     - packages/idempotency/tsconfig*.json
     - packages/idempotency/README.md
     - packages/batch/tsconfig*.json
@@ -116,8 +124,6 @@ labelPRBasedOnFilePath:
     - packages/commons/README.md
     - packages/validator/tsconfig*.json
     - packages/validator/README.md
-    - packages/parser/tsconfig*.json
-    - packages/parser/README.md
     - layers/tsconfig*.json
     - layers/README.md
     - examples/app/tsconfig*.json
@@ -132,6 +138,7 @@ labelPRBasedOnFilePath:
     - packages/parameters/package.json
     - packages/idempotency/package.json
     - packages/parser/package.json
+    - packages/event-handler/package.json
     - packages/validator/package.json
     - packages/batch/package.json
     - layers/package.json

.github/scripts/release_patch_package_json.js

@@ -17,7 +17,9 @@ if (process.argv.length < 3) {
 }
 const basePath = resolve(process.argv[2]);
 const packageJsonPath = join(basePath, 'package.json');
-const alphaPackages = [];
+const alphaPackages = [
+  '@aws-lambda-powertools/event-handler'
+];
 const betaPackages = [];
 
 (() => {

.github/semantic.yml

@@ -22,6 +22,7 @@ scopes:
   - commons
   - parser
   - jmespath
+  - event-handler
   - validation
   - batch
   - layers

.github/workflows/reusable-run-linting-check-and-unit-tests.yml

@@ -28,9 +28,29 @@ jobs:
         with:
           nodeVersion: ${{ matrix.version }}
       - name: Run linting
-        run: npm run lint -w packages/commons -w packages/logger -w packages/tracer -w packages/metrics -w packages/parameters -w packages/idempotency -w packages/batch -w packages/jmespath -w packages/parser
+        run: |
+          npm run lint -w packages/commons \
+            -w packages/logger \
+            -w packages/tracer \
+            -w packages/metrics \
+            -w packages/parameters \
+            -w packages/idempotency \
+            -w packages/batch \
+            -w packages/jmespath \
+            -w packages/parser \
+            -w packages/event-handler
       - name: Run unit tests
-        run: npm t -w packages/commons -w packages/logger -w packages/tracer -w packages/metrics -w packages/parameters -w packages/idempotency -w packages/batch -w packages/jmespath -w packages/parser
+        run: |
+          npm t -w packages/commons \
+            -w packages/logger \
+            -w packages/tracer \
+            -w packages/metrics \
+            -w packages/parameters \
+            -w packages/idempotency \
+            -w packages/batch \
+            -w packages/jmespath \
+            -w packages/parser \
+            -w packages/event-handler
   check-examples:
     runs-on: ubuntu-latest
     env:

.husky/pre-push

@@ -6,4 +6,5 @@ npm t \
   -w packages/tracer \
   -w packages/idempotency \
   -w packages/parameters \
-  -w packages/parser
+  -w packages/parser \
+  -w packages/event-handler

docs/core/event-handler/api-gateway.md

@@ -0,0 +1,53 @@
+---
+title: REST API
+description: Core utility
+---
+
+<!-- markdownlint-disable MD013 -->
+???+ warning "Don't use in production (yet)"
+    This feature is currently under development. As such it's considered not stable and we might make significant breaking changes before going [before its release](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/17){target="_blank"}. You are welcome to [provide feedback](https://github.com/aws-powertools/powertools-lambda-typescript/issues/413){target="_blank"} and [contribute to the project](../../contributing/getting_started.md){target="_blank"}.
+
+Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), Lambda Function URLs, and VPC Lattice.
+
+## Key Features
+
+* Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs.
+* Support for CORS, binary and Gzip compression, Decimals JSON encoding and bring your own JSON serializer
+* Built-in integration with [Parser](../../utilities/parser.md){target="_blank"} for easy payload validation and parsing
+* Works with micro function (one or a few routes) and monolithic functions (all routes)
+
+## Getting started
+
+???+ tip
+    All examples shared in this documentation are available within the [project repository](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/snippets/event-handler){target="_blank"}.
+
+### Install
+
+```shell
+npm install @aws-lambda-powertools/event-handler
+```
+
+### Required resources
+
+If you're using any API Gateway integration, you must have an existing [API Gateway Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"} or [ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"} configured to invoke your Lambda function.
+
+In case of using [VPC Lattice](https://docs.aws.amazon.com/lambda/latest/dg/services-vpc-lattice.html){target="_blank"}, you must have a service network configured to invoke your Lambda function.
+
+This is the sample infrastructure for API Gateway and Lambda Function URLs we are using for the examples in this documentation.
+
+???+ info "There is no additional permissions or dependencies required to use this utility."
+
+=== "API Gateway SAM Template"
+
+    ```yaml title="AWS Serverless Application Model (SAM) example"
+    --8<-- "examples/snippets/event-handler/rest/templates/template.yaml"
+    ```
+
+=== "Lambda Function URL SAM Template"
+
+    ```yaml title="AWS Serverless Application Model (SAM) example"
+    --8<-- "examples/event_handler_lambda_function_url/sam/template.yaml"
+    ```
+
+<!-- remove line below while editing this doc & put it back until the doc has reached its first draft -->
+<!-- markdownlint-disable MD043 -->

lerna.json

@@ -10,11 +10,12 @@
     "packages/testing",
     "packages/jmespath",
     "packages/parser",
+    "packages/event-handler",
     "examples/app",
     "layers",
     "examples/snippets"
   ],
   "version": "2.6.0",
   "npmClient": "npm",
   "message": "chore(release): %s [skip ci]"
-}
+}

package.json

@@ -15,7 +15,8 @@
     "packages/parser",
     "examples/snippets",
     "layers",
-    "examples/app"
+    "examples/app",
+    "packages/event-handler"
   ],
   "scripts": {
     "test": "npm t -ws",

packages/event-handler/README.md

@@ -0,0 +1,70 @@
+# Powertools for AWS Lambda (TypeScript) - Event Handler Utility
+
+> [!Warning]
+> This feature is currently under development. As such it's considered not stable and we might make significant breaking changes before going [before its release](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/17). You are welcome to [provide feedback](https://github.com/aws-powertools/powertools-lambda-typescript/issues/413) and [contribute to the project](https://docs.powertools.aws.dev/lambda/typescript/latest/contributing/getting_started/).
+
+Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serverless [best practices and increase developer velocity](https://docs.powertools.aws.dev/lambda/typescript/latest/#features).
+
+You can use the library in both TypeScript and JavaScript code bases.
+
+## Intro
+
+Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), Lambda Function URLs, and VPC Lattice.
+
+## Usage
+
+To get started, install the library by running:
+
+```sh
+npm i @aws-lambda-powertools/event-handler
+```
+
+> [!Note]
+> This readme is a work in progress.
+
+## Contribute
+
+If you are interested in contributing to this project, please refer to our [Contributing Guidelines](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md).
+
+## Roadmap
+
+The roadmap of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand.  
+Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/aws-powertools/powertools-lambda-typescript/issues), or [creating new ones](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), in this GitHub repository.
+
+## Connect
+
+- **Powertools for AWS Lambda on Discord**: `#typescript` - **[Invite link](https://discord.gg/B8zZKbbyET)**
+- **Email**: <[email protected]>
+
+## How to support Powertools for AWS Lambda (TypeScript)?
+
+### Becoming a reference customer
+
+Knowing which companies are using this library is important to help prioritize the project internally. If your company is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by raising a [Support Powertools for AWS Lambda (TypeScript) (become a reference)](https://s12d.com/become-reference-pt-ts) issue.
+
+The following companies, among others, use Powertools:
+
+- [Hashnode](https://hashnode.com/)
+- [Caylent](https://caylent.com/)
+- [Trek10](https://www.trek10.com/)
+- [Elva](https://elva-group.com)
+- [globaldatanet](https://globaldatanet.com/)
+- [Bailey Nelson](https://www.baileynelson.com.au)
+- [Perfect Post](https://www.perfectpost.fr)
+- [Sennder](https://sennder.com/)
+- [Certible](https://www.certible.com/)
+- [tecRacer GmbH & Co. KG](https://www.tecracer.com/)
+- [AppYourself](https://appyourself.net)
+- [Alma Media](https://www.almamedia.fi)
+
+### Sharing your work
+
+Share what you did with Powertools for AWS Lambda (TypeScript) 💞💞. Blog post, workshops, presentation, sample apps and others. Check out what the community has already shared about Powertools for AWS Lambda (TypeScript) [here](https://docs.powertools.aws.dev/lambda/typescript/latest/we_made_this).
+
+### Using Lambda Layer
+
+This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When [using Layers](https://docs.powertools.aws.dev/lambda/typescript/latest/#lambda-layer), you can add Powertools as a dev dependency to not impact the development process.
+
+## License
+
+This library is licensed under the MIT-0 License. See the LICENSE file.

packages/event-handler/jest.config.cjs

@@ -0,0 +1,29 @@
+module.exports = {
+  displayName: {
+    name: 'Powertools for AWS Lambda (TypeScript) utility: EVENT HANDLER',
+    color: 'blue',
+  },
+  runner: 'groups',
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.ts?$': 'ts-jest',
+  },
+  moduleFileExtensions: ['js', 'ts'],
+  collectCoverageFrom: ['**/src/**/*.ts', '!**/node_modules/**'],
+  testMatch: ['**/?(*.)+(spec|test).ts'],
+  roots: ['<rootDir>/src', '<rootDir>/tests'],
+  testPathIgnorePatterns: ['/node_modules/'],
+  testEnvironment: 'node',
+  coveragePathIgnorePatterns: ['/node_modules/', 'src/types/index.ts'],
+  coverageThreshold: {
+    global: {
+      statements: 100,
+      branches: 100,
+      functions: 100,
+      lines: 100,
+    },
+  },
+  coverageReporters: ['json-summary', 'text', 'lcov']
+};