docs: add intro & getting started

dreamorosi · dreamorosi · commit 1e83d51318e6 · 2025-04-08T18:03:37.000+02:00
diff --git a/docs/contributing/conventions.md b/docs/contributing/conventions.md
@@ -36,7 +36,7 @@ There are also a few other workspaces that are not utilities published to npm, b
 
 * `examples/snippets`: contains the documentation code snippets
 * `examples/app`: contains an example project that can be deployed via AWS CDK or AWS SAM
-* `layers`: contains the code used to build and publish the [Lambda layers](../index.md#lambda-layer)
+* `layers`: contains the code used to build and publish the [Lambda layers](../getting-started/lambda-layers.md)
 
 ## Testing definition
 
diff --git a/docs/features/index.md b/docs/features/index.md
@@ -5,4 +5,78 @@ description: Features of Powertools for AWS Lambda
 
 <!-- markdownlint-disable MD043 -->
 
-Stuff
+<div class="grid cards" markdown>
+
+- __Tracer__
+
+    ---
+
+    Instrument your code with minimal effort. Capture traces and metadata to understand the performance of your Lambda functions.
+
+    [:octicons-arrow-right-24: Read more](./tracer.md)
+
+- __Logger__
+
+    ---
+
+    JSON Structured logging made easier, key management, buffering, and Middy.js middleware to enrich structured logging with key Lambda context details.
+
+    [:octicons-arrow-right-24: Read more](./logger.md)
+
+- __Metrics__
+
+    ---
+
+    Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
+
+    [:octicons-arrow-right-24: Read more](./metrics.md)
+
+- __Parameters__
+
+    ---
+
+    High-level functions to retrieve one or more parameters from AWS SSM Parameter Store, AWS Secrets Manager, AWS AppConfig, and Amazon DynamoDB
+
+    [:octicons-arrow-right-24: Read more](./parameters.md)
+
+- __Idempotency__
+
+    ---
+
+    Class method decorator, Middy middleware, and function wrapper to make your Lambda functions idempotent and prevent duplicate execution based on payload content.
+
+    [:octicons-arrow-right-24: Read more](./idempotency.md)
+
+- __Batch Processing__
+
+    ---
+
+    Simplify the processing of batches of events with built-in support for SQS and DynamoDB Streams.
+
+    [:octicons-arrow-right-24: Read more](./batch.md)
+
+- __JMESPath Functions__
+
+    ---
+
+    Built-in JMESPath functions to easily deserialize common encoded JSON payloads in Lambda functions.
+
+    [:octicons-arrow-right-24: Read more](./jmespath.md)
+
+- __Parser__
+
+    ---
+
+    Utility to parse and validate AWS Lambda event payloads using Zod, a TypeScript-first schema declaration and validation library.
+
+    [:octicons-arrow-right-24: Read more](./parser.md)
+
+- __Validation__
+
+    ---
+
+    JSON Schema validation for events and responses, including JMESPath support to unwrap events before validation.
+
+    [:octicons-arrow-right-24: Read more](./validation.md)
+
+</div>
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -5,7 +5,7 @@ description: Installing Powertools for AWS Lambda
 
 <!-- markdownlint-disable MD043 -->
 
-You can use Powertools for AWS Lambda (TypeScript) by installing it with your favorite dependency management, or via [Lambda Layers](lambda-layers.md).
+You can use Powertools for AWS Lambda (TypeScript) by installing it with your favorite dependency management, or via [Lambda Layers](./lambda-layers.md).
 
 The toolkit is compatible with both TypeScript and JavaScript code bases, and supports both CommonJS and ES modules.
 
@@ -23,10 +23,10 @@ Some features use additional dependencies like the AWS SDK for JavaScript v3, wh
 
 | Feature                                                              | Install                                                                                                           | Default dependency  |
 | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- |
-| **[Tracer](./features/tracer.md)**                                   | **`npm i @aws-lambda-powertools/tracer`**{.copyMe}:clipboard:                                                     | `aws-xray-sdk-core` |
-| **[Idempotency](./features/idempotency.md)**                         | **`npm i @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb`**{.copyMe}:clipboard: |                     |
-| **[Parameters (SSM)](./features/parameters.md)**                     | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-ssm`**{.copyMe}:clipboard:                             |                     |
-| **[Parameters (Secrets Manager)](./features/parameters.md)**         | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager`**{.copyMe}:clipboard:                 |                     |
-| **[Parameters (AppConfig)](./features/parameters.md)**               | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata`**{.copyMe}:clipboard:                   |                     |
-| **[Parser](./features/parser.md)**                                   | **`npm i @aws-lambda-powertools/parser zod@~3`**{.copyMe}:clipboard:                                              |                     |
-| **[Validation](./features/validation.md)**                           | **`npm i @aws-lambda-powertools/validation`**{.copyMe}:clipboard:                                                 | `ajv`               |
+| **[Tracer](../features/tracer.md)**                                   | **`npm i @aws-lambda-powertools/tracer`**{.copyMe}:clipboard:                                                     | `aws-xray-sdk-core` |
+| **[Idempotency](../features/idempotency.md)**                         | **`npm i @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb`**{.copyMe}:clipboard: |                     |
+| **[Parameters (SSM)](../features/parameters.md)**                     | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-ssm`**{.copyMe}:clipboard:                             |                     |
+| **[Parameters (Secrets Manager)](../features/parameters.md)**         | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager`**{.copyMe}:clipboard:                 |                     |
+| **[Parameters (AppConfig)](../features/parameters.md)**               | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata`**{.copyMe}:clipboard:                   |                     |
+| **[Parser](../features/parser.md)**                                   | **`npm i @aws-lambda-powertools/parser zod@~3`**{.copyMe}:clipboard:                                              |                     |
+| **[Validation](../features/validation.md)**                           | **`npm i @aws-lambda-powertools/validation`**{.copyMe}:clipboard:                                                 | `ajv`               |
diff --git a/docs/getting-started/lambda-layers.md b/docs/getting-started/lambda-layers.md
@@ -7,10 +7,16 @@ description: Using Powertools for AWS Lambda with Lambda layers
 
 A [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a `.zip` file archive that can contain additional code, pre-packaged dependencies, data, or configuration files. We provide a Lambda Layer for Powertools for AWS Lambda (TypeScript) to help you get started quickly with the library.
 
-You can add our layer both in the [AWS Lambda Console _(under `Layers`)_](https://eu-west-1.console.aws.amazon.com/lambda/home#/add/layer){target="_blank"}, or via your favorite infrastructure as code framework with the ARN value. You can use the Lambda Layer both with CommonJS and ESM (ECMAScript modules).
+You can add our layer both in the [AWS Lambda Console _(under `Layers`)_](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html){target="_blank"}, or via your favorite infrastructure as code framework with the ARN value. You can use the Lambda Layer both with CommonJS and ESM (ECMAScript modules).
 
 ### Layer ARNs
 
+We publish the Lambda Layer for Powertools for AWS Lambda (TypeScript) in all commercial regions and AWS GovCloud (US) regions.
+
+???+ tip "Spotted a missing region?"
+
+    Open an [issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=feature_request.yml&title=Feature%20request%3A%20missing%20Lambda%20layer%20region) in our GitHub repository to request it.
+
 | Region           | Layer ARN                                                                                                            |
 | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `us-east-1`      | [arn:aws:lambda:us-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:23](#){: .copyMe}:clipboard:            |
diff --git a/docs/getting-started/navigating-the-toolkit.md b/docs/getting-started/navigating-the-toolkit.md
@@ -5,20 +5,99 @@ description: Getting to know the Powertools for AWS Lambda Toolkit
 
 <!-- markdownlint-disable MD043 -->
 
-## Instrumentation
+Powertools for AWS Lambda (TypeScript) is a collection of utilities designed to help you build serverless applications on AWS.
 
-Many of the utilities provided by Powertools for AWS Lambda (TypeScript) can be used with different programming paradigms:
+The toolkit is designed to be modular, so you can pick and choose the utilities you need for your application. Each utility is designed to be used independently, but they can also be used together to provide a complete solution for your serverless applications.
 
-- **Middy** middleware. It is the best choice if your existing code base relies on the [Middy.js](https://middy.js.org/docs/) middleware engine. Powertools for AWS Lambda (TypeScript) offers compatible Middy middleware to make this integration seamless.
-- **Method decorator**. Use [TypeScript method decorators](https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators) if you prefer writing your business logic using [TypeScript Classes](https://www.typescriptlang.org/docs/handbook/classes.html). If you aren’t using Classes, this requires the most significant refactoring.
-- **Manually**. It provides the most granular control. It’s the most verbose approach, with the added benefit of no additional dependency and no refactoring to TypeScript Classes.
+## Patterns
 
-The examples in this documentation will feature all the approaches described above wherever applicable.
+Many of the utilities provided can be used with different patterns, depending on your preferences and the structure of your code.
 
-## Examples
+### Class Method Decorator
 
-You can find examples of how to use Powertools for AWS Lambda (TypeScript) in the [examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/app){target="_blank"} directory. The application is a simple REST API that can be deployed via either AWS CDK or AWS SAM.
+If you prefer writing your business logic using Object-Oriented Programming (OOP) and TypeScript Classes, the Class Method decorator pattern is a good fit. This approach lets you decorate class methods with Powertools utilities, applying their functionality with minimal code changes.
 
-If instead you want to see Powertools for AWS Lambda (TypeScript) in slightly different use cases, check the [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) or the [AWS Lambda performance tuning](https://github.com/aws-samples/optimizations-for-lambda-functions) repository.
+This pattern works well when you want to integrate Powertools for AWS Lambda (TypeScript) into an existing codebase without significant refactoring and with no additional runtime dependencies. Note that this approach relies on TypeScript's experimental decorator feature.
 
-Both demos use Powertools for AWS Lambda (TypeScript) as well as demonstrating other common techniques for Lambda functions written in TypeScript.
+```ts
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import type { Context } from 'aws-lambda';
+
+const logger = new Logger();
+const tracer = new Tracer();
+const metrics = new Metrics();
+
+class Lambda implements LambdaInterface {
+  @tracer.captureLambdaHandler()
+  @logger.injectLambdaContext()
+  @metrics.logMetrics()
+  async handler(event: unknown, context: Context) {
+    // Your business logic here
+  }
+}
+const lambda = new Lambda();
+export const handler = lambda.handler.bind(lambda);
+```
+
+### Middy.js Middleware
+
+If your existing codebase relies on the [Middy.js](https://middy.js.org/docs/) middleware engine, you can use the Powertools for AWS Lambda (TypeScript) middleware to integrate with your existing code. This approach is similar to the Class Method decorator pattern but uses the Middy.js middleware engine to apply Powertools utilities.
+
+```ts
+import { Logger } from '@aws-lambda-powertools/logger';
+import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
+import middy from '@middy/core';
+
+const logger = new Logger();
+const tracer = new Tracer();
+const metrics = new Metrics();
+
+export const handler = middy()
+  .use(captureLambdaHandler(tracer))
+  .use(injectLambdaContext(logger))
+  .use(logMetrics(metrics))
+  .handler(async (event: unknown) => {
+    // Your business logic here
+  });
+```
+
+### Functional Approach
+
+If you prefer a more functional programming style, you can use the Powertools for AWS Lambda (TypeScript) utilities directly in your code without decorators or middleware. This approach is more verbose but provides the most control over how the utilities are applied.
+
+```ts
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import type { Context } from 'aws-lambda';
+
+const logger = new Logger();
+const tracer = new Tracer();
+const metrics = new Metrics();
+
+export const handler = async (event: unknown, context: Context) => {
+  logger.addContext(context);
+  logger.logEventIfEnabled(event);
+
+  const subsegment = tracer
+    .getSegment()
+    ?.addNewSubsegment('#### handler');
+
+  try {
+    // Your business logic here
+  } catch (error) {
+    logger.error('Error occurred', { error });
+    tracer.addErrorAsMetadata(error);
+  } finally {
+    subsegment?.close();
+    metrics.publishStoredMetrics();
+  }
+};
+```
diff --git a/docs/getting-started/typescript-settings.md b/docs/getting-started/typescript-settings.md
@@ -5,4 +5,44 @@ description: Configuration settings for using Powertools with TypeScript
 
 <!-- markdownlint-disable MD043 -->
 
-Stuff
+While you can use the toolkit with JavaScript, using TypeScript is recommended.
+
+The toolkit is written in TypeScript, and the type definitions are included in the package. This means you can take advantage of TypeScript's static typing and other features when using it.
+
+We officially support TypeScript 5.0 and later, and our development is done using the latest version of TypeScript. We recommend using the latest version of TypeScript to take advantage of the latest features and improvements.
+
+## TypeScript Configuration
+
+The toolkit should work with most TypeScript configurations. The only requirement is that `experimentalDecorators` is set to `true` if you are using class method decorators. This is because we only support the legacy decorator proposal for now. We will support the new decorator proposal in the next major version of Powertools for AWS Lambda (TypeScript).
+
+If you are looking for a starting point, the following `tsconfig.json` file is a good place to start. It includes the recommended settings along with some modern TypeScript features.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "es2022"
+    ],
+    "declaration": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": false,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strictPropertyInitialization": false
+  },
+  "exclude": [
+    "node_modules"
+  ]
+}
+```
diff --git a/docs/index.md b/docs/index.md
@@ -52,6 +52,12 @@ Powertools for AWS Lambda (TypeScript) is built as a modular toolkit, so you can
 | [Parser](./features/parser.md)               | Utility to parse and validate AWS Lambda event payloads using Zod, a TypeScript-first schema declaration and validation library.                                  |
 | [Validation](./features/validation.md)       | JSON Schema validation for events and responses, including JMESPath support to unwrap events before validation.                                                   |
 
+## Examples
+
+You can find examples of how to use Powertools for AWS Lambda (TypeScript) in the [examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples){target="_blank"} directory, which contains both code snippets for specific use cases, as well as a full example application.
+
+If instead you want to see Powertools for AWS Lambda (TypeScript) in a more involved context, check the [Powertools for AWS workshop](https://github.com/aws-samples/powertools-for-aws-lambda-workshop/tree/main/functions/typescript) where we demonstrate how to use toolkit in a more complex application.
+
 ## Support Powertools for AWS
 
 There are many ways you can help us gain future investments to improve everyone's experience:
diff --git a/docs/upgrade.md b/docs/upgrade.md
@@ -32,7 +32,7 @@ V2 is focused on official support for ESM (ECMAScript modules). We've made other
 Before you start, we suggest making a copy of your current working project or create a new git branch.
 
 1. Upgrade Node.js to v18 or higher, Node.js v20 is recommended.
-2. Ensure that you have the latest Powertools for AWS Lambda (TypeScript) version via [Lambda Layer](./index.md#lambda-layer) or npm.
+2. Ensure that you have the latest Powertools for AWS Lambda (TypeScript) version via [Lambda Layer](./getting-started/lambda-layers.md) or npm.
 3. Review the following sections to confirm whether they apply to your codebase.
 
 ## ESM support
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -33,7 +33,6 @@ nav:
   - Homepage:
       - index.md
       - Getting Started:
-          - getting-started/index.md
           - Navigating the toolkit: getting-started/navigating-the-toolkit.md
           - Installation: getting-started/installation.md
           - TypeScript settings: getting-started/typescript-settings.md
