chore(examples): updated contributing & docs with SAM (#876)

* chore: updated contributing & docs with SAM

* chore: updated contributing & docs with SAM

* chore: updated contributing & docs with SAM

* chore: updated contributing & docs with SAM

* chore: updated contributing & docs with SAM

* chore: updated contributing & docs with SAM

* chore: add sam to gitpod

* chore: updated gitpod.yml

* chore: updated gitpod.yml

* chore: updated gitpod.yml

* Update CONTRIBUTING.md

Co-authored-by: ijemmy <[email protected]>

* Update .devcontainer/devcontainer.json

Co-authored-by: Florian Chazal <[email protected]>

Co-authored-by: ijemmy <[email protected]>
Co-authored-by: Florian Chazal <[email protected]>

Author: 3 people

Diff for: .devcontainer/Dockerfile

@@ -11,5 +11,10 @@ RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
 # ARG EXTRA_NODE_VERSION=10
 # RUN su node -c "umask 0002 && ./usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"
 
+RUN wget https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip \
+    && unzip aws-sam-cli-linux-x86_64.zip -d sam-installation \
+    && sudo ./sam-installation/install \
+    && rm -rf sam-installation aws-sam-cli-linux-*
+
 # Global node modules
 RUN su node -c "npm install -g npm-check-updates npm@next-8"

Diff for: .devcontainer/devcontainer.json

@@ -5,16 +5,16 @@
   "build": {
     "dockerfile": "Dockerfile",
     // Update 'VARIANT' to pick a Node version: 16, 14, 12.
-		// Append -bullseye or -buster to pin to an OS version.
-		// Use -bullseye variants on local arm64/Apple Silicon.
-    "args": { "VARIANT": "16-bullseye" }
+    // Append -bullseye or -buster to pin to an OS version.
+    // Use -bullseye variants on local arm64/Apple Silicon.
+    "args": {
+      "VARIANT": "16-bullseye"
+    }
   },
-  
   // Set *default* container specific settings.json values on container create.
   "settings": {
     "git.enableCommitSigning": true
   },
-
   // Add the IDs of extensions you want installed when the container is created.
   "extensions": [
     "dbaeumer.vscode-eslint",
@@ -25,10 +25,8 @@
     "ms-vscode.vscode-typescript-tslint-plugin",
     "ms-azuretools.vscode-docker"
   ],
-
   // Use 'postCreateCommand' to run commands after the container is created.
-  "postCreateCommand": "npm ci; npm run lerna-ci; npm run init-environment",
-
+  "postCreateCommand": "npm ci --foreground-scripts; cd examples/cdk; npm ci; cd ../sam; npm ci; cd ../../; npm run init-environment",
   // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
-	"remoteUser": "node"
+  "remoteUser": "node"
 }

Diff for: .gitpod.yml

@@ -1,5 +1,26 @@
 tasks:
-  - init: nvm install; nvm use; npm i -g npm@next-8; npm ci; npm run lerna-ci; npm run init-environment
+  - init: |
+      # Install Nodejs version specified in .nvmrc
+      nvm install
+      nvm use
+      # Install npm 8.x
+      npm i -g npm@next-8
+      # Install monorepo packages
+      npm ci --foreground-scripts
+      # Install CDK exampels dependencies
+      cd examples/cdk
+      npm ci
+      # Install SAM exampels dependencies
+      cd ../sam
+      npm ci
+      # Install AWS SAM CLI
+      wget https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip
+      unzip aws-sam-cli-linux-x86_64.zip -d sam-installation
+      sudo ./sam-installation/install
+      rm -rf sam-installation aws-sam-cli-linux-*
+      cd ../../
+      # Setup husky hooks
+      npm run init-environment
 vscode:
   extensions:
     - dbaeumer.vscode-eslint

Diff for: CONTRIBUTING.md

@@ -57,6 +57,8 @@ reported the issue. Please try to include as much information as you can. Detail
 The following steps describe how to set up the AWS Lambda Powertools for TypeScript repository on your local machine.
 The alternative is to use a Cloud IDE like [Gitpod](https://www.gitpod.io/) or [Codespaces](https://github.com/features/codespaces) for your development.
 
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/awslabs/aws-lambda-powertools-typescript)
+
 ### Setup
 
 The following tools need to be installed on your system prior to starting working on a pull request:
@@ -66,6 +68,8 @@ The following tools need to be installed on your system prior to starting workin
   - If you use [nvm](https://github.com/nvm-sh/nvm#nvmrc) or [fnm](https://github.com/Schniz/fnm) you can install the latest LTS version with `nvm use` or `fnm use` respectively. Both will use the `.nvmrc` file in the project's root.
 - [npm 8.x](https://www.npmjs.com/)
   - After installing Node.js, you can install `npm` with `npm install -g npm@next-8` 
+- [AWS SAM CLI >= 1.49.0](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+  - AWS SAM CLI is a command line interface for AWS Serverless Application Model (SAM), it's used in one of the examples, and it's part of the pre-push hook.
 - [Docker](https://docs.docker.com/get-docker/)
   - If you are not planning on making changes to the documentation, you can skip this step.
 
@@ -74,9 +78,10 @@ First, [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the
 ```console
 git clone https://github.com/{your-account}/aws-lambda-powertools-typescript.git
 cd aws-lambda-powertools-typescript
-npm ci;
+npm ci --foreground-scripts;
 cd examples/cdk; npm ci
 cd ../..
+cd examples/sam; npm ci
 npm run init-environment
 ```
 
@@ -195,26 +200,34 @@ You can run the end-to-end tests automatically on your forked project by followi
 
 ### 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.
+As part of the repo you will find an examples folder at the root. This folder contains examples (written with CDK and SAM) 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
+1. Build your local version of *aws-lambda-powertools-typescript* npm packages with `npm run lerna-package` while in the root folder
+2. Move to the examples folder of your choice
+    ```sh
+    cd packages/examples/cdk
+    # or
+    cd packages/examples/sam
     ```
-    cd examples/cdk
+3. Update their references in examples
+    ```sh   
     npm install ../../packages/**/dist/aws-lambda-powertools-*
     ```
-3. Run cdk tests
-    ```
+4. Run cdk tests
+    ```sh
     npm run test
     ```
-4. Deploy
-    ```
+5. Deploy
+    ```sh
     npm run cdk deploy
+    # or
+    sam build  --beta-features
+    sam deploy --guided
     ```
 
-The last command will deploy AWS resources, therefore, you will need an AWS account, and it might incur 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/).
+The last step will deploy AWS resources, therefore, you will need an AWS account, and it might incur 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/).
 
 ### Local documentation
 

Diff for: README.md

@@ -6,7 +6,7 @@
 
 A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and  AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
 
 > **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | [email protected]**
 
@@ -44,6 +44,7 @@ Each TypeScript utility is installed as standalone NPM package.
 ### Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
+* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 * [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk/src)
 * [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples)
 * [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples)

Diff for: docs/index.md

@@ -63,6 +63,7 @@ Each TypeScript utility is installed as standalone NPM package.
 ## Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk){target="_blank"}
+* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam){target="_blank"}
 * [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk/lib){target="_blank"}
 * [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples){target="_blank"}
 * [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples){target="_blank"}

Diff for: packages/commons/README.md

@@ -7,7 +7,7 @@
 
 A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
 
 > **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | [email protected]**
 
@@ -35,6 +35,7 @@ Each TypeScript utility is installed as standalone NPM package.
 ### Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
+* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 * [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/tracing/examples)
 * [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples)
 * [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples)

Diff for: packages/logger/README.md

@@ -7,7 +7,7 @@
 
 A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
 
 > **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | [email protected]**
 
@@ -36,6 +36,7 @@ Each TypeScript utility is installed as standalone NPM package.
 ### Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
+* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 * [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/tracing/examples)
 * [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples)
 * [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples)

Diff for: packages/metrics/README.md

@@ -7,7 +7,7 @@
 
 A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
 
 > **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | [email protected]**
 
@@ -35,6 +35,7 @@ Each TypeScript utility is installed as standalone NPM package.
 ### Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
+* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 * [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/tracing/examples)
 * [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples)
 * [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples)

Diff for: packages/tracer/README.md

@@ -7,7 +7,7 @@
 
 A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
 
 > **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | [email protected]**
 
@@ -35,6 +35,7 @@ Each TypeScript utility is installed as standalone NPM package.
 ### Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
+* [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 * [Tracer](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/tracing/examples)
 * [Logger](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/logger/examples)
 * [Metrics](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/packages/metrics/examples)