Merge branch 'main' into fix-doc-examples

.github/workflows/on-push.yml → .github/workflows/pr_lint_and_test.yml

@@ -1,9 +1,7 @@
-name: on-push-event
+name: pr-lint-and-test
 on:
-  push:
-    branches:    
-          - '**'        # matches every branch
-          - '!main' 
+  pull_request:
+    types: [opened, synchronize]
 jobs:
   on_push:
     runs-on: ubuntu-latest
@@ -45,4 +43,4 @@ jobs:
         uses: romeovs/[email protected]
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          lcov-file: ./coverage/lcov.info
+          lcov-file: ./coverage/lcov.info

.github/workflows/run-e2e-tests.yml

@@ -28,3 +28,9 @@ jobs:
         aws-region: eu-west-1
     - name: Run integration tests
       run: npm run lerna-test:e2e
+    - name: Test packaging
+      run: | 
+        npm run lerna-package
+        cd examples/cdk
+        npm install ../../packages/**/dist/aws-lambda-powertools-*
+        npm run test

CONTRIBUTING.md

@@ -152,6 +152,29 @@ You can run the end-to-end tests automatically on your forked project by followi
 
 > :warning: **Don't automatically run end-to-end tests on branch push or PRs**. A malicious attacker can submit a pull request to attack your AWS account. Ideally, use a blank account without any important workload/data, and limit `AWS_ROLE_ARN_TO_ASSUME` permission to least minimum privilege.
 
+### Examples
+
+As part of the repo you will find an examples folder at the root. This folder contains examples (written with CDK for now) of deployable AWS Lambda functions using Powertools.
+
+To test your updates with these examples you just have to:
+
+1. Build your local version of *aws-lambda-powertools-typescript* npm packages with `npm run lerna-package`
+2. Update their references in examples
+    ```
+    cd examples/cdk
+    npm install ../../packages/**/dist/aws-lambda-powertools-*
+    ```
+3. Run cdk tests
+    ```
+    npm run test
+    ```
+4. Deploy
+    ```
+    npm run cdk deploy
+    ```
+
+Previous command will deploy AWS resources therefore you will need an AWS account and it might incur in some costs which should be covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all). If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
+
 ### Conventions
 
 Category | Convention

docs/index.md

@@ -14,7 +14,7 @@ AWS Lambda Powertools TypeScript provides a suite of utilities for AWS Lambda fu
 
 ## Tenets
 
-This project separates core utilities that will be available in other runtimes vs general utilities that might not be available across all runtimes.
+Core utilities such as Tracer, Logger, Metrics, and Event Handler will be available across all Lambda Powertools runtimes. Additional utilities are subjective to each language ecosystem and customer demand.
 
 * **AWS Lambda only**. We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
 * **Eases the adoption of best practices**. The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.

examples/cdk/README.md

@@ -4,14 +4,13 @@ This is a deployable CDK app that deploys AWS Lambda functions as part of a Clou
 
 You will need to have a valid AWS Account in order to deploy these resources. These resources may incur costs to your AWS Account. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
 
-The example functions, located in the `lib` folder, are invoked automatically, twice, when deployed using the CDK construct defined in `lib/example-function.ts`. The first invocation demonstrates the effect on logs/metrics/annotations when the Lambda function has a cold start, and the latter without a cold start.
+The example functions, located in the `src` folder, are invoked automatically, twice, when deployed using the CDK construct defined in `src/example-function.ts`. The first invocation demonstrates the effect on logs/metrics/annotations when the Lambda function has a cold start, and the latter without a cold start.
 
 ## Deploying the stack
 
- * Ensure that CDK v2 is installed globally on your machine (if not, run `npm install -g aws-cdk`)
  * Navigate to this location of the repo in your terminal (`examples/cdk`)
  * `npm install`
- * `cdk deploy --all --profile <YOUR_AWS_PROFILE>`
+ * `npm run cdk deploy --all --profile <YOUR_AWS_PROFILE>`
 
 Note: Prior to deploying you may need to run `cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` if you have not already bootstrapped your account for CDK.
 

examples/cdk/bin/cdk-app.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import 'source-map-support/register';
 import * as cdk from 'aws-cdk-lib';
-import { CdkAppStack } from '../lib/example-stack';
+import { CdkAppStack } from '../src/example-stack';
 
 const app = new cdk.App();
 new CdkAppStack(app, 'LambdaPowertoolsTypeScript-ExamplesCdkStack', {});

examples/cdk/jest.config.js

@@ -1,6 +1,6 @@
 module.exports = {
   testEnvironment: 'node',
-  roots: ['<rootDir>/test'],
+  roots: ['<rootDir>/tests'],
   testMatch: ['**/*.test.ts'],
   transform: {
     '^.+\\.tsx?$': 'ts-jest'