You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/features/parser.md
+47-49Lines changed: 47 additions & 49 deletions
Original file line number
Diff line number
Diff line change
@@ -1,63 +1,57 @@
1
1
---
2
-
title: Parser (Zod)
2
+
title: Parser (Standard Schema)
3
3
descrition: Utility
4
4
---
5
5
6
6
<!-- markdownlint-disable MD043 --->
7
7
8
-
This utility provides data validation and parsing using [Zod](https://zod.dev){target="_blank"}, a TypeScript-first schema declaration and validation library.
8
+
This utility provides data validation and parsing for [Standard Schema](https://github.com/standard-schema/standard-schema){target="_blank"}, together with a collection of built-in [Zod](https://zod.dev){target="_blank"} schemas and envelopes to parse and unwrap popular AWS event sources payloads.
9
9
10
10
## Key features
11
11
12
-
*Define data schema as Zod schema, then parse, validate and extract only what you want
13
-
* Built-in envelopes to unwrap and validate popular AWS event sources payloads
14
-
* Extend and customize envelopes to fit your needs
15
-
* Safe parsing option to avoid throwing errors and custom error handling
16
-
* Available for Middy.js middleware and TypeScript method decorators
12
+
*Accept a [Standard Schema](https://github.com/standard-schema/standard-schema) and parse incoming payloads
13
+
* Built-in Zod schemas and envelopes to unwrap and validate popular AWS event sources payloads
14
+
* Extend and customize built-in Zod schemas to fit your needs
15
+
* Safe parsing option to avoid throwing errors and allow custom error handling
16
+
* Available as Middy.js middleware and TypeScript class method decorator
17
17
18
18
## Getting started
19
19
20
20
```bash
21
-
npm install @aws-lambda-powertools/parser zod@~3
21
+
npm install @aws-lambda-powertools/parser zod
22
22
```
23
23
24
-
!!! warning "Zod version"
25
-
The package is compatible with Zod v3 only.<br/>
26
-
We're considering Zod v4 support and we'd love to hear your feedback. Please [leave a comment here](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3951) to let us know your thoughts.
27
-
28
-
## Define schema
29
-
30
-
You can define your schema using Zod:
31
-
32
-
```typescript title="schema.ts"
33
-
--8<--"examples/snippets/parser/schema.ts"
34
-
```
35
-
36
-
This is a schema for `Order` object using Zod.
37
-
You can create complex schemas by using nested objects, arrays, unions, and other types, see [Zod documentation](https://zod.dev) for more details.
38
-
39
24
## Parse events
40
25
41
26
You can parse inbound events using `parser` decorator, Middy.js middleware, or [manually](#manual-parsing) using built-in envelopes and schemas.
42
-
Both are also able to parse either an object or JSON string as an input.
43
27
44
-
???+ warning
45
-
The decorator and middleware will replace the event object with the parsed schema if successful.
46
-
Be cautious when using multiple decorators that expect event to have a specific structure, the order of evaluation for decorators is from bottom to top.
28
+
When using the decorator or middleware, you can specify a schema to parse the event, this can be a [built-in Zod schema](#built-in-schemas) or a custom schema you defined. Custom schemas can be defined using Zod or any other [Standard Schema compatible library](https://standardschema.dev/#what-schema-libraries-implement-the-spec){target="_blank"}.
47
29
48
-
=== "Middy middleware"
30
+
=== "Middy.js middleware with Zod schema"
49
31
```typescript hl_lines="22"
50
32
--8<-- "examples/snippets/parser/middy.ts"
51
33
```
52
34
35
+
=== "Middy.js middleware with Valibot schema"
36
+
```typescript hl_lines="30"
37
+
--8<-- "examples/snippets/parser/middyValibot.ts"
38
+
```
39
+
53
40
=== "Decorator"
41
+
!!! warning
42
+
The decorator and middleware will replace the event object with the parsed schema if successful.
43
+
Be cautious when using multiple decorators that expect an event to have a specific structure, the order of evaluation for decorators is from the inner to the outermost decorator.
44
+
54
45
```typescript hl_lines="25"
55
46
--8<-- "examples/snippets/parser/decorator.ts"
56
47
```
57
48
58
49
## Built-in schemas
59
50
60
-
**Parser** comes with the following built-in schemas:
51
+
**Parser** comes with the following built-in Zod schemas:
52
+
53
+
!!! note "Looking for other libraries?"
54
+
The built-in schemas are defined using Zod, if you would like us to support other libraries like [valibot](https://valibot.dev){target="_blank"} please [open an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=feature_request.yml){target="_blank"} and we will consider it based on the community's feedback.
@@ -221,24 +215,27 @@ We have also complex envelopes that parse the payload from a string, decode base
221
215
222
216
### Built-in envelopes
223
217
224
-
Parser comes with the following built-in envelopes:
218
+
Parser comes with the following built-in Zod envelopes:
219
+
220
+
!!! note "Looking for other libraries?"
221
+
The built-in schemas are defined using Zod, if you would like us to support other libraries like [valibot](https://valibot.dev){target="_blank"} please [open an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=feature_request.yml){target="_blank"} and we will consider it based on the community's feedback.
|**apiGatewayEnvelope**| 1. Parses data using `APIGatewayProxyEventSchema`. <br/> 2. Parses `body` key using your schema and returns it. |
229
-
|**apiGatewayV2Envelope**| 1. Parses data using `APIGatewayProxyEventV2Schema`. <br/> 2. Parses `body` key using your schema and returns it. |
230
-
|**cloudWatchEnvelope**| 1. Parses data using `CloudwatchLogsSchema` which will base64 decode and decompress it. <br/> 2. Parses records in `message` key using your schema and return them in a list. |
231
-
|**dynamoDBStreamEnvelope**| 1. Parses data using `DynamoDBStreamSchema`. <br/> 2. Parses records in `NewImage` and `OldImage` keys using your schema. <br/> 3. Returns a list with a dictionary containing `NewImage` and `OldImage` keys |
232
-
|**eventBridgeEnvelope**| 1. Parses data using `EventBridgeSchema`. <br/> 2. Parses `detail` key using your schema and returns it. |
233
-
|**kafkaEnvelope**| 1. Parses data using `KafkaRecordSchema`. <br/> 2. Parses `value` key using your schema and returns it. |
234
-
|**kinesisEnvelope**| 1. Parses data using `KinesisDataStreamSchema` which will base64 decode it. <br/> 2. Parses records in `Records` key using your schema and returns them in a list. |
235
-
|**kinesisFirehoseEnvelope**| 1. Parses data using `KinesisFirehoseSchema` which will base64 decode it. <br/> 2. Parses records in `Records` key using your schema and returns them in a list. |
236
-
|**lambdaFunctionUrlEnvelope**| 1. Parses data using `LambdaFunctionUrlSchema`. <br/> 2. Parses `body` key using your schema and returns it. |
237
-
|**snsEnvelope**| 1. Parses data using `SnsSchema`. <br/> 2. Parses records in `body` key using your schema and return them in a list. |
238
-
|**snsSqsEnvelope**| 1. Parses data using `SqsSchema`. <br/> 2. Parses SNS records in `body` key using `SnsNotificationSchema`. <br/> 3. Parses data in `Message` key using your schema and return them in a list. |
239
-
|**sqsEnvelope**| 1. Parses data using `SqsSchema`. <br/> 2. Parses records in `body` key using your schema and return them in a list. |
240
-
|**vpcLatticeEnvelope**| 1. Parses data using `VpcLatticeSchema`. <br/> 2. Parses `value` key using your schema and returns it. |
241
-
|**vpcLatticeV2Envelope**| 1. Parses data using `VpcLatticeSchema`. <br/> 2. Parses `value` key using your schema and returns it. |
225
+
|**ApiGatewayEnvelope**| 1. Parses data using `APIGatewayProxyEventSchema`. <br/> 2. Parses `body` key using your schema and returns it. |
226
+
|**ApiGatewayV2Envelope**| 1. Parses data using `APIGatewayProxyEventV2Schema`. <br/> 2. Parses `body` key using your schema and returns it. |
227
+
|**CloudWatchEnvelope**| 1. Parses data using `CloudwatchLogsSchema` which will base64 decode and decompress it. <br/> 2. Parses records in `message` key using your schema and return them in a list. |
228
+
|**DynamoDBStreamEnvelope**| 1. Parses data using `DynamoDBStreamSchema`. <br/> 2. Parses records in `NewImage` and `OldImage` keys using your schema. <br/> 3. Returns a list with a dictionary containing `NewImage` and `OldImage` keys |
229
+
|**EventBridgeEnvelope**| 1. Parses data using `EventBridgeSchema`. <br/> 2. Parses `detail` key using your schema and returns it. |
230
+
|**KafkaEnvelope**| 1. Parses data using `KafkaRecordSchema`. <br/> 2. Parses `value` key using your schema and returns it. |
231
+
|**KinesisEnvelope**| 1. Parses data using `KinesisDataStreamSchema` which will base64 decode it. <br/> 2. Parses records in `Records` key using your schema and returns them in a list. |
232
+
|**KinesisFirehoseEnvelope**| 1. Parses data using `KinesisFirehoseSchema` which will base64 decode it. <br/> 2. Parses records in `Records` key using your schema and returns them in a list. |
233
+
|**LambdaFunctionUrlEnvelope**| 1. Parses data using `LambdaFunctionUrlSchema`. <br/> 2. Parses `body` key using your schema and returns it. |
234
+
|**SnsEnvelope**| 1. Parses data using `SnsSchema`. <br/> 2. Parses records in `body` key using your schema and return them in a list. |
235
+
|**SnsSqsEnvelope**| 1. Parses data using `SqsSchema`. <br/> 2. Parses SNS records in `body` key using `SnsNotificationSchema`. <br/> 3. Parses data in `Message` key using your schema and return them in a list. |
236
+
|**SnsEnvelope**| 1. Parses data using `SqsSchema`. <br/> 2. Parses records in `body` key using your schema and return them in a list. |
237
+
|**VpcLatticeEnvelope**| 1. Parses data using `VpcLatticeSchema`. <br/> 2. Parses `value` key using your schema and returns it. |
238
+
|**VpcLatticeV2Envelope**| 1. Parses data using `VpcLatticeSchema`. <br/> 2. Parses `value` key using your schema and returns it. |
242
239
243
240
## Safe parsing
244
241
@@ -248,7 +245,7 @@ The handler `event` object will be replaced with `ParsedResult<Input?, Oputput?>
248
245
The `ParsedResult` object will have `success`, `data`, or `error` and `originalEvent` fields, depending on the outcome.
249
246
If the parsing is successful, the `data` field will contain the parsed event, otherwise you can access the `error` field and the `originalEvent` to handle the error and recover the original event.
@@ -320,10 +317,11 @@ Use `z.infer` to extract the type of the schema, so you can use types during dev
320
317
321
318
### Compatibility with `@types/aws-lambda`
322
319
323
-
The package `@types/aws-lambda` is a popular project that contains type definitions for many AWS service event invocations.
324
-
Powertools parser utility also bring AWS Lambda event types based on the built-in schema definitions.
320
+
The package `@types/aws-lambda` is a popular project that contains type definitions for many AWS service event invocations, support for these types is provided on a best effort basis.
321
+
322
+
We recommend using the types provided by the Parser utility under `@aws-powertools/parser/types` when using the built-in schemas and envelopes, as they are inferred directly from the Zod schemas and are more accurate.
325
323
326
-
We recommend to use the types provided by the parser utility. If you encounter any issues or have any feedback, please [submit an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose).
324
+
If you encounter any type compatibility issues with `@types/aws-lambda`, please [submit an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose).
0 commit comments