chore(docs): move code snippets under examples

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

@@ -89,7 +89,7 @@ jobs:
       - name: Setup dependencies
         uses: ./.github/actions/cached-node-modules
       - name: Run linting
-        run: npm run lint -w docs/snippets
+        run: npm run lint -w examples/snippets
   check-docs:
     runs-on: ubuntu-latest
     env:

README.md

@@ -44,7 +44,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
 
 ### 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/app) directory. The application is a simple REST API that can be deployed via either AWS CDK or AWS SAM.
+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) directory. The directory contains code snippets around certain features as well as an is a simple REST API application that can be deployed via either AWS CDK or AWS SAM.
 
 Community-contributed examples:
 

docs/contributing/conventions.md

@@ -34,7 +34,7 @@ Additionally, we try to share common runtime code between utilities to reduce ma
 
 There are also a few other workspaces that are not utilities published to npm, but that still share dependencies and/or runtime code with the utilities. These workspaces are:
 
-* `docs/snippets`: contains the documentation code snippets
+* `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)
 

docs/core/logger.md

@@ -37,7 +37,7 @@ The `Logger` utility must always be instantiated outside the Lambda handler. By
 === "handler.ts"
 
     ```typescript hl_lines="1 3"
-    --8<-- "docs/snippets/logger/basicUsage.ts"
+    --8<-- "examples/snippets/logger/basicUsage.ts"
     ```
 
 ### Utility settings
@@ -60,7 +60,7 @@ Check API docs to learn more about [Logger constructor options](https://docs.pow
 === "handler.ts"
 
     ```typescript hl_lines="1 4"
-    --8<-- "docs/snippets/logger/sam.ts"
+    --8<-- "examples/snippets/logger/sam.ts"
     ```
 
 === "template.yaml"
@@ -115,7 +115,7 @@ This functionality will include the following keys in your structured logs:
         Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
 
     ```typescript hl_lines="2 14"
-    --8<-- "docs/snippets/logger/middy.ts"
+    --8<-- "examples/snippets/logger/middy.ts"
     ```
 
 === "Decorator"
@@ -128,15 +128,15 @@ This functionality will include the following keys in your structured logs:
         If this is not the desired behavior, you can call the `logger.injectLambdaContext()` method directly in your handler.
 
     ```typescript hl_lines="8"
-    --8<-- "docs/snippets/logger/decorator.ts"
+    --8<-- "examples/snippets/logger/decorator.ts"
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.
 
 === "Manual"
 
     ```typescript hl_lines="10"
-    --8<-- "docs/snippets/logger/manual.ts"
+    --8<-- "examples/snippets/logger/manual.ts"
     ```
 
 In each case, the printed log will look like this:
@@ -168,13 +168,13 @@ When debugging in non-production environments, you can instruct Logger to log th
 === "Middy Middleware"
 
     ```typescript hl_lines="15"
-    --8<-- "docs/snippets/logger/eventMiddy.ts"
+    --8<-- "examples/snippets/logger/eventMiddy.ts"
     ```
 
 === "Decorator"
 
     ```typescript hl_lines="8"
-    --8<-- "docs/snippets/logger/eventDecorator.ts"
+    --8<-- "examples/snippets/logger/eventDecorator.ts"
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.
@@ -193,7 +193,7 @@ To remove the keys you added, you can use the `removeKeys` method.
 === "handler.ts"
 
     ```typescript hl_lines="5-13 17-25 32"
-    --8<-- "docs/snippets/logger/appendKeys.ts"
+    --8<-- "examples/snippets/logger/appendKeys.ts"
     ```
 === "Example CloudWatch Logs excerpt"
 
@@ -239,13 +239,13 @@ If you want to make sure that persistent attributes added **inside the handler f
 === "Middy Middleware"
 
     ```typescript hl_lines="31"
-    --8<-- "docs/snippets/logger/clearStateMiddy.ts"
+    --8<-- "examples/snippets/logger/clearStateMiddy.ts"
     ```
 
 === "Decorator"
 
     ```typescript hl_lines="16"
-    --8<-- "docs/snippets/logger/clearStateDecorator.ts"
+    --8<-- "examples/snippets/logger/clearStateDecorator.ts"
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.
@@ -303,7 +303,7 @@ You can append additional data to a single log item by passing objects as additi
 === "handler.ts"
 
     ```typescript hl_lines="16-18 23-25 37"
-    --8<-- "docs/snippets/logger/extraData.ts"
+    --8<-- "examples/snippets/logger/extraData.ts"
     ```
 === "Example CloudWatch Logs excerpt"
 
@@ -356,7 +356,7 @@ The error will be logged with default key name `error`, but you can also pass yo
 === "handler.ts"
 
     ```typescript hl_lines="13 20-22"
-    --8<-- "docs/snippets/logger/logError.ts"
+    --8<-- "examples/snippets/logger/logError.ts"
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -414,7 +414,7 @@ We support the following log levels:
 You can access the current log level by using the `getLevelName()` method. This method returns the name of the current log level as a string. If you want to change the log level at runtime, you can use the `setLogLevel()` method. This method accepts a string value that represents the log level you want to set, both lower and upper case values are supported.
 
 ```typescript
---8<-- "docs/snippets/logger/logLevel.ts"
+--8<-- "examples/snippets/logger/logLevel.ts"
 ```
 
 If you want to access the numeric value of the current log level, you can use the `level` property. For example, if the current log level is `INFO`, `logger.level` property will return `12`.
@@ -480,7 +480,7 @@ Once a child logger is created, the logger and its parent will act as separate i
 === "handler.ts"
 
     ```typescript hl_lines="16-18"
-    --8<-- "docs/snippets/logger/createChild.ts"
+    --8<-- "examples/snippets/logger/createChild.ts"
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -534,7 +534,7 @@ Sampling decision happens at the Logger initialization. This means sampling may
 === "handler.ts"
 
     ```typescript hl_lines="6"
-    --8<-- "docs/snippets/logger/logSampling.ts"
+    --8<-- "examples/snippets/logger/logSampling.ts"
     ```
 
 === "Example CloudWatch Logs excerpt - Invocation #1"
@@ -644,15 +644,15 @@ You can customize the structure (keys and values) of your log items by passing a
 === "handler.ts"
 
     ```typescript hl_lines="2 6"
-    --8<-- "docs/snippets/logger/bringYourOwnFormatterHandler.ts"
+    --8<-- "examples/snippets/logger/bringYourOwnFormatterHandler.ts"
     ```
 
 This is how the `MyCompanyLogFormatter` (dummy name) would look like:
 
 === "utils/formatters/MyCompanyLogFormatter.ts"
 
     ```typescript
-    --8<-- "docs/snippets/logger/bringYourOwnFormatterClass.ts"
+    --8<-- "examples/snippets/logger/bringYourOwnFormatterClass.ts"
     ```
 
 This is how the printed log would look:
@@ -701,7 +701,7 @@ This is a Jest sample that provides the minimum information necessary for Logger
 === "handler.test.ts"
 
     ```typescript
-    --8<-- "docs/snippets/logger/unitTesting.ts"
+    --8<-- "examples/snippets/logger/unitTesting.ts"
     ```
 
 ### Suppress logs with Jest

docs/core/metrics.md

@@ -59,7 +59,7 @@ The `Metrics` utility must always be instantiated outside of the Lambda handler.
 === "handler.ts"
 
     ```typescript hl_lines="1 3-6"
-    --8<-- "docs/snippets/metrics/basicUsage.ts"
+    --8<-- "examples/snippets/metrics/basicUsage.ts"
     ```
 
 ### Utility settings
@@ -83,7 +83,7 @@ The `Metrics` utility is instantiated outside of the Lambda handler. In doing th
 === "handler.ts"
 
     ```typescript hl_lines="1 4"
-    --8<-- "docs/snippets/metrics/sam.ts"
+    --8<-- "examples/snippets/metrics/sam.ts"
     ```
 
 === "template.yml"
@@ -109,13 +109,13 @@ You can create metrics using the `addMetric` method, and you can create dimensio
 === "Metrics"
 
     ```typescript hl_lines="12"
-    --8<-- "docs/snippets/metrics/createMetrics.ts"
+    --8<-- "examples/snippets/metrics/createMetrics.ts"
     ```
 
 === "Metrics with custom dimensions"
 
     ```typescript hl_lines="12-13"
-    --8<-- "docs/snippets/metrics/customDimensions.ts"
+    --8<-- "examples/snippets/metrics/customDimensions.ts"
     ```
 
 !!! tip "Autocomplete Metric Units"
@@ -137,7 +137,7 @@ You can create [high-resolution metrics](https://aws.amazon.com/about-aws/whats-
 === "Metrics with high resolution"
 
     ```typescript hl_lines="4 20"
-    --8<-- "docs/snippets/metrics/addHighResolutionMetric.ts"
+    --8<-- "examples/snippets/metrics/addHighResolutionMetric.ts"
     ```
 
 !!! tip "Autocomplete Metric Resolutions"
@@ -150,7 +150,7 @@ You can call `addMetric()` with the same name multiple times. The values will be
 === "addMetric() with the same name"
 
     ```typescript hl_lines="12 14"
-    --8<-- "docs/snippets/metrics/multiValueMetrics.ts"
+    --8<-- "examples/snippets/metrics/multiValueMetrics.ts"
     ```
 === "Example CloudWatch Logs excerpt"
 
@@ -195,7 +195,7 @@ You can add default dimensions to your metrics by passing them as parameters in
 === "constructor"
 
     ```typescript hl_lines="6"
-    --8<-- "docs/snippets/metrics/defaultDimensions.ts"
+    --8<-- "examples/snippets/metrics/defaultDimensions.ts"
     ```
 
 === "Middy middleware"
@@ -205,13 +205,13 @@ You can add default dimensions to your metrics by passing them as parameters in
         Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
 
     ```typescript hl_lines="24-26"
-    --8<-- "docs/snippets/metrics/defaultDimensionsMiddy.ts"
+    --8<-- "examples/snippets/metrics/defaultDimensionsMiddy.ts"
     ```
 
 === "setDefaultDimensions method"
 
     ```typescript hl_lines="7"
-    --8<-- "docs/snippets/metrics/setDefaultDimensions.ts"
+    --8<-- "examples/snippets/metrics/setDefaultDimensions.ts"
     ```
 
 === "with logMetrics decorator"
@@ -224,7 +224,7 @@ You can add default dimensions to your metrics by passing them as parameters in
         If this is not the desired behavior, you can use the `logMetrics` middleware instead.
 
     ```typescript hl_lines="12"
-    --8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts"
+    --8<-- "examples/snippets/metrics/defaultDimensionsDecorator.ts"
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.
@@ -258,7 +258,7 @@ See below an example of how to automatically flush metrics with the Middy-compat
 === "handler.ts"
 
     ```typescript hl_lines="2 17"
-    --8<-- "docs/snippets/metrics/middy.ts"
+    --8<-- "examples/snippets/metrics/middy.ts"
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -297,7 +297,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h
 === "handler.ts"
 
     ```typescript hl_lines="10"
-    --8<-- "docs/snippets/metrics/decorator.ts"
+    --8<-- "examples/snippets/metrics/decorator.ts"
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.
@@ -334,7 +334,7 @@ You can manually flush the metrics with `publishStoredMetrics` as follows:
 === "handler.ts"
 
     ```typescript hl_lines="13"
-    --8<-- "docs/snippets/metrics/manual.ts"
+    --8<-- "examples/snippets/metrics/manual.ts"
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -366,7 +366,7 @@ If you want to ensure that at least one metric is emitted before you flush them,
 === "handler.ts"
 
     ```typescript hl_lines="21"
-    --8<-- "docs/snippets/metrics/throwOnEmptyMetrics.ts"
+    --8<-- "examples/snippets/metrics/throwOnEmptyMetrics.ts"
     ```
 
 ### Capturing a cold start invocation as metric
@@ -376,13 +376,13 @@ You can optionally capture cold start metrics with the `logMetrics` middleware o
 === "Middy Middleware"
 
     ```typescript hl_lines="18"
-    --8<-- "docs/snippets/metrics/captureColdStartMetricMiddy.ts"
+    --8<-- "examples/snippets/metrics/captureColdStartMetricMiddy.ts"
     ```
 
 === "logMetrics decorator"
 
     ```typescript hl_lines="10"
-    --8<-- "docs/snippets/metrics/captureColdStartMetricDecorator.ts"
+    --8<-- "examples/snippets/metrics/captureColdStartMetricDecorator.ts"
     ```
 
 If it's a cold start invocation, this feature will:
@@ -406,7 +406,7 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad
 === "handler.ts"
 
     ```typescript hl_lines="15"
-    --8<-- "docs/snippets/metrics/addMetadata.ts"
+    --8<-- "examples/snippets/metrics/addMetadata.ts"
     ```
 
 === "Example CloudWatch Logs excerpt"
@@ -450,13 +450,13 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `singleMetr
 === "Middy Middleware"
 
     ```typescript hl_lines="21 23-24"
-    --8<-- "docs/snippets/metrics/singleMetricDifferentDimsMiddy.ts"
+    --8<-- "examples/snippets/metrics/singleMetricDifferentDimsMiddy.ts"
     ```
 
 === "logMetrics decorator"
 
     ```typescript hl_lines="16 18-19"
-    --8<-- "docs/snippets/metrics/singleMetricDifferentDimsDecorator.ts"
+    --8<-- "examples/snippets/metrics/singleMetricDifferentDimsDecorator.ts"
     ```
 
     1. Binding your handler method allows your handler to access `this` within the class methods.