Skip to content

chore: update snippets & event-handler docs #3864

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 26, 2025
Merged

chore: update snippets & event-handler docs #3864

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63ca402
chore: update snippets
dreamorosi Apr 26, 2025
03bfac8
Update appsync-events.md
dreamorosi Apr 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions .github/scripts/release_patch_package_json.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,7 @@ if (process.argv.length < 3) {
}
const basePath = resolve(process.argv[2]);
const packageJsonPath = join(basePath, 'package.json');
const alphaPackages = [
'@aws-lambda-powertools/event-handler'
];
const alphaPackages = [];
const betaPackages = [];

(() => {
Expand Down
14 changes: 7 additions & 7 deletions docs/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@ Each Utility page provides information on example values and allowed values.

## Dev Mode

Whether you're prototyping locally or against a non-production environment, you can use `POWERTOOLS_DEV` to increase verbosity across multiple utilities.
Whether you're prototyping locally or against a non-production environment, you can use `POWERTOOLS_DEV` to increase verbosity across multiple utilities or disable certain features.

When `POWERTOOLS_DEV` is set to a truthy value (`1`, `true`), it'll have the following effects:
When `POWERTOOLS_DEV` is set to a truthy value (`1`, `true`, `on`), it'll have the following effects:

| Utility | Effect |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Logger** | Increase JSON indentation to 4 and uses global `console` to emit logs to ease testing and local debugging when running functions locally. However, Amazon CloudWatch Logs view will degrade as each new line is treated as a new message |
| **Tracer** | Disables tracing operations in non-Lambda environments. This already happens automatically in the Tracer utility |
| **Metrics** | Disables emitting metrics to stdout. Can be overridden by explicitly setting `POWERTOOLS_METRICS_DISABLED` to `false` |
| Utility | Effect |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Logger** | Increase JSON indentation to 4, uses global `console` to emit logs, and format stack traces |
| **Tracer** | Disable tracing operations. This already happens automatically when running in non-Lambda environments |
| **Metrics** | Disable emitting metrics to stdout. Can be overridden by explicitly setting `POWERTOOLS_METRICS_DISABLED` to `false` |
6 changes: 4 additions & 2 deletions docs/features/event-handler/appsync-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ stateDiagram-v2
* Easily handle publish and subscribe events with dedicated handler methods
* Automatic routing based on namespace and channel patterns
* Support for wildcard patterns to create catch-all handlers
* Process events in parallel corontrol aggregation for batch processing
* Process events in parallel and control aggregation for batch processing
* Graceful error handling for individual events

## Terminology
Expand All @@ -59,6 +59,8 @@ It handles connection management, message broadcasting, authentication, and moni

You must have an existing AppSync Events API with real-time capabilities enabled and IAM permissions to invoke your AWS Lambda function. That said, there are no additional permissions required to use Event Handler as routing requires no dependency.

Additionally, if you want the result of your handler to be used by AppSync you must set the integration type to `REQUEST_RESPONSE`.

=== "template.yaml"

```yaml
Expand Down Expand Up @@ -245,7 +247,7 @@ You can access to the original Lambda event or context for additional informatio

=== "Access event and context"

```typescript hl_lines="6"
```typescript hl_lines="10"
--8<-- "examples/snippets/event-handler/appsync-events/accessEventAndContext.ts"
```

Expand Down
72 changes: 36 additions & 36 deletions docs/getting-started/lambda-layers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,42 +17,42 @@ We publish the Lambda Layer for Powertools for AWS Lambda in all commercial regi

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:24](#){: .copyMe} |
| `us-east-2` | [arn:aws:lambda:us-east-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `us-west-1` | [arn:aws:lambda:us-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `us-west-2` | [arn:aws:lambda:us-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-south-1` | [arn:aws:lambda:ap-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-south-2` | [arn:aws:lambda:ap-south-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-east-1` | [arn:aws:lambda:ap-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-northeast-1` | [arn:aws:lambda:ap-northeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-northeast-2` | [arn:aws:lambda:ap-northeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-northeast-3` | [arn:aws:lambda:ap-northeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-southeast-1` | [arn:aws:lambda:ap-southeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-southeast-2` | [arn:aws:lambda:ap-southeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-southeast-3` | [arn:aws:lambda:ap-southeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-southeast-4` | [arn:aws:lambda:ap-southeast-4:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-southeast-5` | [arn:aws:lambda:ap-southeast-5:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ap-southeast-7` | [arn:aws:lambda:ap-southeast-7:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-central-1` | [arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-central-2` | [arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-west-1` | [arn:aws:lambda:eu-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-west-2` | [arn:aws:lambda:eu-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-west-3` | [arn:aws:lambda:eu-west-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-north-1` | [arn:aws:lambda:eu-north-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-south-1` | [arn:aws:lambda:eu-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `eu-south-2` | [arn:aws:lambda:eu-south-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ca-central-1` | [arn:aws:lambda:ca-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `ca-west-1` | [arn:aws:lambda:ca-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `sa-east-1` | [arn:aws:lambda:sa-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `af-south-1` | [arn:aws:lambda:af-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `me-south-1` | [arn:aws:lambda:me-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `me-central-1` | [arn:aws:lambda:me-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `il-central-1` | [arn:aws:lambda:il-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `mx-central-1` | [arn:aws:lambda:mx-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `us-gov-west-1` | [arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| `us-gov-east-1` | [arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsTypeScriptV2:24](#){: .copyMe} |
| Region | Layer ARN |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| `us-east-1` | [arn:aws:lambda:us-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `us-east-2` | [arn:aws:lambda:us-east-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `us-west-1` | [arn:aws:lambda:us-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `us-west-2` | [arn:aws:lambda:us-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-south-1` | [arn:aws:lambda:ap-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-south-2` | [arn:aws:lambda:ap-south-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-east-1` | [arn:aws:lambda:ap-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-northeast-1` | [arn:aws:lambda:ap-northeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-northeast-2` | [arn:aws:lambda:ap-northeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-northeast-3` | [arn:aws:lambda:ap-northeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-southeast-1` | [arn:aws:lambda:ap-southeast-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-southeast-2` | [arn:aws:lambda:ap-southeast-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-southeast-3` | [arn:aws:lambda:ap-southeast-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-southeast-4` | [arn:aws:lambda:ap-southeast-4:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-southeast-5` | [arn:aws:lambda:ap-southeast-5:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ap-southeast-7` | [arn:aws:lambda:ap-southeast-7:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-central-1` | [arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-central-2` | [arn:aws:lambda:eu-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-west-1` | [arn:aws:lambda:eu-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-west-2` | [arn:aws:lambda:eu-west-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-west-3` | [arn:aws:lambda:eu-west-3:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-north-1` | [arn:aws:lambda:eu-north-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-south-1` | [arn:aws:lambda:eu-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `eu-south-2` | [arn:aws:lambda:eu-south-2:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ca-central-1` | [arn:aws:lambda:ca-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `ca-west-1` | [arn:aws:lambda:ca-west-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `sa-east-1` | [arn:aws:lambda:sa-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `af-south-1` | [arn:aws:lambda:af-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `me-south-1` | [arn:aws:lambda:me-south-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `me-central-1` | [arn:aws:lambda:me-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `il-central-1` | [arn:aws:lambda:il-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `mx-central-1` | [arn:aws:lambda:mx-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `us-gov-west-1` | [arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |
| `us-gov-east-1` | [arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsTypeScriptV2:25](#){: .copyMe} |

### Lookup Layer ARN via AWS SSM Parameter Store

Expand Down
7 changes: 6 additions & 1 deletion examples/snippets/event-handler/appsync-events/accessEventAndContext.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,21 @@
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';
import { Logger } from '@aws-lambda-powertools/logger';
import type { Context } from 'aws-lambda';

const logger = new Logger({
serviceName: 'serverlessAirline',
});
const app = new AppSyncEventsResolver();

app.onPublish('/*', (payload, event, context) => {
const { headers } = event.request; // (1)!
const { awsRequestId } = context;
logger.info('headers', { headers, awsRequestId });

// your business logic here

return payload;
});

export const handler = async (event: unknown, context: Context) =>
await app.resolve(event, context);
app.resolve(event, context);
2 changes: 1 addition & 1 deletion examples/snippets/event-handler/appsync-events/debugLogging.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ app.onPublish('/default/foo', (payload) => {
});

export const handler = async (event: unknown, context: Context) =>
await app.resolve(event, context);
app.resolve(event, context);
99 changes: 80 additions & 19 deletions examples/snippets/event-handler/appsync-events/templates/gettingStarted.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,88 @@
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
Function:
Timeout: 5
MemorySize: 256
Runtime: nodejs22.x
Tracing: Active
Environment:
Variables:
POWERTOOLS_LOG_LEVEL: INFO
POWERTOOLS_SERVICE_NAME: hello

Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
CodeUri: hello_world

WebsocketAPI:
Type: AWS::AppSync::Api
Properties:
EventConfig:
AuthProviders:
- AuthType: API_KEY
ConnectionAuthModes:
- AuthType: API_KEY
DefaultPublishAuthModes:
- AuthType: API_KEY
DefaultSubscribeAuthModes:
- AuthType: API_KEY
Name: RealTimeEventAPI
Type: AWS::AppSync::Api
Properties:
EventConfig:
AuthProviders:
- AuthType: API_KEY
ConnectionAuthModes:
- AuthType: API_KEY
DefaultPublishAuthModes:
- AuthType: API_KEY
DefaultSubscribeAuthModes:
- AuthType: API_KEY
Name: RealTimeEventAPI

WebasocketApiKey:
Type: AWS::AppSync::ApiKey
Properties:
ApiId: !GetAtt WebsocketAPI.ApiId
Description: "API KEY"
Expires: 90
WebsocketApiKey:
Type: AWS::AppSync::ApiKey
Properties:
ApiId: !GetAtt WebsocketAPI.ApiId

WebsocketAPINamespace:
Type: AWS::AppSync::ChannelNamespace
Properties:
ApiId: !GetAtt WebsocketAPI.ApiId
Name: powertools
Name: powertools
HandlerConfigs:
OnPublish:
Behavior: DIRECT
Integration:
DataSourceName: powertools_lambda
LambdaConfig:
InvokeType: REQUEST_RESPONSE
OnSubscribe:
Behavior: DIRECT
Integration:
DataSourceName: powertools_lambda
LambdaConfig:
InvokeType: REQUEST_RESPONSE

DataSourceIAMRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: appsync.amazonaws.com
Action: sts:AssumeRole
Policies:
- PolicyName: LambdaInvokePolicy
PolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Action:
- lambda:InvokeFunction
Resource: !GetAtt HelloWorldFunction.Arn

NameSpaceDataSource:
Type: AWS::AppSync::DataSource
Properties:
ApiId: !GetAtt WebsocketAPI.ApiId
LambdaConfig:
LambdaFunctionArn: !GetAtt HelloWorldFunction.Arn
Name: powertools_lambda
ServiceRoleArn: !GetAtt DataSourceIAMRole.Arn
Type: AWS_LAMBDA
1 change: 1 addition & 0 deletions examples/snippets/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
"homepage": "https://github.com/aws-powertools/powertools-lambda-typescript#readme",
"devDependencies": {
"@aws-lambda-powertools/batch": "^2.19.0",
"@aws-lambda-powertools/event-handler": "^2.19.0",
"@aws-lambda-powertools/idempotency": "^2.19.0",
"@aws-lambda-powertools/jmespath": "^2.19.0",
"@aws-lambda-powertools/logger": "^2.19.0",
Expand Down
1 change: 1 addition & 0 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.