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

Co-authored-by: Alexander Schueren <sha@amazon.com>

Author: dreamorosi

.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-lock.json

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