add safeParse

Author: am29d

docs/snippets/package.json

@@ -2,6 +2,7 @@
   "name": "docs",
   "version": "2.0.3",
   "description": "A collection code snippets for the Powertools for AWS Lambda (TypeScript) docs",
+  "type": "module",
   "author": {
     "name": "Amazon Web Services",
     "url": "https://aws.amazon.com"
@@ -33,6 +34,7 @@
     "@aws-sdk/client-secrets-manager": "^3.543.0",
     "@aws-sdk/client-ssm": "^3.540.0",
     "@aws-sdk/util-dynamodb": "^3.540.0",
+    "@middy/core": "^4.7.0",
     "aws-sdk": "^2.1589.0",
     "aws-sdk-client-mock": "^4.0.0",
     "aws-sdk-client-mock-jest": "^4.0.0",

docs/snippets/parser/decorator.ts

@@ -21,8 +21,8 @@ type Order = z.infer<typeof orderSchema>;
 class Lambda implements LambdaInterface {
   @parser({ schema: orderSchema })
   public async handler(event: Order, _context: Context): Promise<void> {
+    // event is now typed as Order
     for (const item of event.items) {
-      // item is parsed as OrderItem
       console.log(item.id);
     }
   }

docs/snippets/parser/envelopeDecorator.ts

@@ -22,8 +22,8 @@ type Order = z.infer<typeof orderSchema>;
 class Lambda implements LambdaInterface {
   @parser({ schema: orderSchema, envelope: EventBridgeEnvelope }) // (1)!
   public async handler(event: Order, _context: Context): Promise<void> {
+    // event is now typed as Order
     for (const item of event.items) {
-      // item is parsed as OrderItem
       console.log(item.id); // (2)!
     }
   }

docs/snippets/parser/extend.ts

@@ -1,4 +1,4 @@
-import { Context } from 'aws-lambda';
+import type { Context } from 'aws-lambda';
 import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { parser } from '@aws-lambda-powertools/parser';
 import { z } from 'zod';

docs/snippets/parser/manualSafeParse.ts

@@ -0,0 +1,33 @@
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+import type { EventBridgeEvent } from '@aws-lambda-powertools/parser/types';
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(
+    z.object({
+      id: z.number().positive(),
+      quantity: z.number(),
+      description: z.string(),
+    })
+  ),
+  optionalField: z.string().optional(),
+});
+
+export const handler = async (
+  event: EventBridgeEvent,
+  _context: Context
+): Promise<void> => {
+  const parsedEvent = EventBridgeSchema.safeParse(event); // (1)!
+  parsedEvent.success
+    ? console.log(parsedEvent.data)
+    : console.log(parsedEvent.error.message);
+
+  const parsedEvenlope = EventBridgeEnvelope.safeParse(event, orderSchema); // (2)!
+  parsedEvenlope.success
+    ? console.log(parsedEvenlope.data)
+    : console.log(parsedEvenlope.error.message);
+};

docs/snippets/parser/middy.ts

@@ -1,4 +1,4 @@
-import { Context } from 'aws-lambda';
+import type { Context } from 'aws-lambda';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
 import { z } from 'zod';
 import middy from '@middy/core';

docs/snippets/parser/safeParseDecorator.ts

@@ -0,0 +1,44 @@
+import type { Context } from 'aws-lambda';
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import { parser } from '@aws-lambda-powertools/parser';
+import { z } from 'zod';
+import type {
+  ParsedResult,
+  EventBridgeEvent,
+} from '@aws-lambda-powertools/parser/types';
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(
+    z.object({
+      id: z.number().positive(),
+      quantity: z.number(),
+      description: z.string(),
+    })
+  ),
+  optionalField: z.string().optional(),
+});
+
+type Order = z.infer<typeof orderSchema>;
+
+class Lambda implements LambdaInterface {
+  @parser({ schema: orderSchema, safeParse: true }) // (1)!
+  public async handler(
+    event: ParsedResult<EventBridgeEvent, Order>,
+    _context: Context
+  ): Promise<void> {
+    if (event.success) {
+      // (2)!
+      for (const item of event.data.items) {
+        console.log(item.id); // (3)!
+      }
+    } else {
+      console.error(event.error); // (4)!
+      console.log(event.originalEvent); // (5)!
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/safeParseMiddy.ts

@@ -0,0 +1,42 @@
+import type { Context } from 'aws-lambda';
+import { parser } from '@aws-lambda-powertools/parser/middleware';
+import { z } from 'zod';
+import middy from '@middy/core';
+import type {
+  ParsedResult,
+  EventBridgeEvent,
+} from '@aws-lambda-powertools/parser/types';
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(
+    z.object({
+      id: z.number().positive(),
+      quantity: z.number(),
+      description: z.string(),
+    })
+  ),
+  optionalField: z.string().optional(),
+});
+
+type Order = z.infer<typeof orderSchema>;
+
+const lambdaHandler = async (
+  event: ParsedResult<EventBridgeEvent, Order>,
+  _context: Context
+): Promise<void> => {
+  if (event.success) {
+    // (2)!
+    for (const item of event.data.items) {
+      console.log(item.id); // (3)!
+    }
+  } else {
+    console.error(event.error); // (4)!
+    console.log(event.originalEvent); // (5)!
+  }
+};
+
+export const handler = middy(lambdaHandler).use(
+  parser({ schema: orderSchema, safeParse: true }) // (1)!
+);

docs/snippets/parser/types.ts

@@ -1,4 +1,4 @@
-import { Context } from 'aws-lambda';
+import type { Context } from 'aws-lambda';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
 import { z } from 'zod';
 import middy from '@middy/core';

docs/snippets/tsconfig.json

@@ -33,7 +33,8 @@
       "@aws-lambda-powertools/jmespath": ["../../packages/jmespath/lib"],
       "@aws-lambda-powertools/jmespath/envelopes": [
         "../../packages/jmespath/lib/envelopes"
-      ]
+      ],
+      "@aws-lambda-powertools/parser": ["../../packages/parser/lib"]
     }
   }
 }

docs/utilities/parser.md

@@ -1,53 +1,56 @@
 ---
 title: Parser (Zod)
 descrition: Utility
+status: new
 ---
 
 
 ???+ warning
     **This utility is currently released as beta developer preview** and is intended strictly for feedback and testing purposes **and not for production workloads**. The version and all future versions tagged with the `-beta` suffix should be treated as not stable. Up until before the [General Availability release](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/16) we might introduce significant breaking changes and improvements in response to customers feedback.
 
-This utility provides data validation and parsing using [zod](https://zod.dev){target="_blank"}.
+This utility provides data validation and parsing using [Zod](https://zod.dev){target="_blank"}.
 Zod is a TypeScript-first schema declaration and validation library.  
 
 ## Key features
 
-* Define data schema as zod schema, then parse, validate and extract only what you want
-* Built-in envelopes to unwrap and validate popular event sources payloads
+* Define data schema as Zod schema, then parse, validate and extract only what you want
+* Built-in envelopes to unwrap and validate popular AWS event sources payloads
 * Extend and customize envelopes to fit your needs
+* Safe parsing option to avoid throwing errors and custom error handling
 * Available for Middy.js middleware and TypeScript method decorators
 
 ## Getting started
 
 ### Install
 
 ```bash
-npm install @aws-lambda-powertools/parser zod
+npm install @aws-lambda-powertools/parser zod~3
 ```
 
-This utility supports zod v3.0.0 and above.
+This utility supports Zod v3.x and above.
 
 ## Define schema
 
-You can define your schema using zod:
+You can define your schema using Zod:
 
 ```typescript title="schema.ts"
 --8<-- "docs/snippets/parser/schema.ts"
 ```
 
-This is a schema for order and order items using zod. 
-You can create more complex schemas using zod, such as nested objects, arrays, unions, etc. see [zod documentation](https://zod.dev) for more details.
+This is a schema for `Order` object using Zod. 
+You can create complex schemas by using nested objects, arrays, unions, and other types, see [Zod documentation](https://zod.dev) for more details.
 
 ## Parse events
 
-You can parse inbound events using `parser` decorator or middy middleware. 
+You can parse inbound events using `parser` decorator or middy middleware, or [manually](#manual-parsing) using built-in envelopes and schemas.
 Both are also able to parse either an object or JSON string as an input.
 
-???+ note
-    The decorator and middleware will replace the event object with the parsed schema if successful. This means you might be careful when nesting other decorators that expect event to have a specific structure.
+???+ warning
+    The decorator and middleware will replace the event object with the parsed schema if successful. 
+    Be careful when using multiple decorators that expect event to have a specific structure, the order of evaluation for decorators is from bottom to top.
 
 === "Middy middleware"
-    ```typescript hl_lines="31"
+    ```typescript hl_lines="32"
     --8<-- "docs/snippets/parser/middy.ts"
     ```    
 
@@ -120,6 +123,11 @@ This can become difficult quite quickly. Parser simplifies the development throu
 Envelopes can be used via envelope parameter available in middy and decorator.
 Here's an example of parsing a custom schema in an event coming from EventBridge, where all you want is what's inside the detail key.
 
+=== "Middy middleware"
+    ```typescript hl_lines="5 33"
+    --8<-- "docs/snippets/parser/envelopeMiddy.ts"
+    ```
+
 === "Decorator"
     ```typescript hl_lines="5 23"
     --8<-- "docs/snippets/parser/envelopeDecorator.ts"
@@ -128,10 +136,7 @@ Here's an example of parsing a custom schema in an event coming from EventBridge
     1. Pass `eventBridgeEnvelope` to `parser` decorator
     2. `event` is parsed and replaced as `Order` object
 
-=== "Middy middleware"
-    ```typescript hl_lines="5 32"
-    --8<-- "docs/snippets/parser/envelopeMiddy.ts"
-    ```
+
 
 The envelopes are functions that take an event and the schema to parse, and return the result of the inner schema.
 Depending on the envelope it can be something simple like extracting a key. 
@@ -163,30 +168,69 @@ Parser comes with the following built-in envelopes:
 | **vpcLatticeV2Envelope**      | 1. Parses data using `VpcLatticeSchema`. <br/> 2. Parses `value` key using your schema and returns it.                                                                                                        |
 
 
+## Safe parsing
+
+If you want to parse the event without throwing an error, use the `safeParse` option. 
+The handler `event` object will be replaced with `ParsedResult<Input?, Oputput?>`, for example `ParsedResult<SqsEvent, Order>`, where `SqsEvent` is the original event and `Order` is the parsed schema. 
+
+The `ParsedResult` object will have `success`, `data`,  or `error` and `originalEvent` fields, depending on the outcome. 
+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.
+
+=== "Middy middleware"
+    ```typescript hl_lines="29 32 35 36 41"
+    --8<-- "docs/snippets/parser/safeParseMiddy.ts"
+    ```
+
+    1. Use `safeParse` option to parse the event without throwing an error
+    2. Check if the result is successful or not and handle the error accordingly
+    3. Use `data` to access the parsed event
+    4. Use `error` to handle the error message
+    5. Use `originalEvent` to get the original event and recover
+
+=== "Decorator"
+    ```typescript hl_lines="26 31 34 37 38"
+    --8<-- "docs/snippets/parser/safeParseDecorator.ts"
+    ```
+    
+    1. Use `safeParse` option to parse the event without throwing an error
+    2. Check if the result is successful or not and handle the error accordingly
+    3. Use `data` to access the parsed event
+    4. Use `error` to handle the error message
+    5. Use `originalEvent` to get the original event and recover
+
+
 ## Manual parsing
 
-You can use built-in envelopes and schemas to parse the incoming events manually: 
+You can use built-in envelopes and schemas to parse the incoming events manually, without using middy or decorator.
+
 
-=== "Manual parsing"
+=== "Manual parse"
     ```typescript hl_lines="25 28"
     --8<-- "docs/snippets/parser/manual.ts"
     ```
-    
+
     1. Use `EventBridgeSchema` to parse the event, the `details` fields will be parsed as a generic record.
     2. Use `eventBridgeEnvelope` with a combination of `orderSchema` to get `Order` object from the `details` field.
 
+=== "Manual safeParse"
+    ```typescript hl_lines="24 29"
+    --8<-- "docs/snippets/parser/manualSafeParse.ts"
+    ```
+
+    1. Use `safeParse` option to parse the event without throwing an error
+    2. `safeParse` is also available for envelopes
 
 ## Custom validation
 
-Because Parser uses zod, you can use all the features of zod to validate your data.
+Because Parser uses Zod, you can use all the features of Zod to validate your data.
 For example, you can use `refine` to validate a field or a combination of fields:
 
 === "Custom validation"
     ```typescript hl_lines="13 18"
     --8<-- "docs/snippets/parser/refine.ts"
     ```
 
-Zod provides a lot of other features and customization, see [zod documentation](https://zod.dev) for more details.
+Zod provides a lot of other features and customization, see [Zod documentation](https://zod.dev) for more details.
 
 
 ## Types
@@ -213,4 +257,4 @@ We are working on a sustainable solution to make them compatible and avoid any b
 We recommend to use the types provided by the parser utility. 
 
 ## Error handling
-We don't have any error handling in the utility and propagate all errors from zod, which are thrown as `ZodError`. 
+We don't have any error handling in the utility and propagate all errors from Zod, which are thrown as `ZodError`. 

mkdocs.yml

@@ -120,3 +120,5 @@ extra:
     - icon: fontawesome/brands/discord
       link: https://discord.gg/B8zZKbbyET
       name: Join our Discord Server!
+  status:
+    new: New Utility