fixed line highlight

am29d · am29d · commit 55aeb063365b · 2024-04-04T15:38:57.000+02:00
diff --git a/docs/snippets/parser/decorator.ts b/docs/snippets/parser/decorator.ts
@@ -2,6 +2,9 @@ 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 { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -23,7 +26,7 @@ class Lambda implements LambdaInterface {
   public async handler(event: Order, _context: Context): Promise<void> {
     // event is now typed as Order
     for (const item of event.items) {
-      console.log(item.id);
+      logger.info('Processing item', { item });
     }
   }
 }
diff --git a/docs/snippets/parser/envelopeDecorator.ts b/docs/snippets/parser/envelopeDecorator.ts
@@ -3,6 +3,9 @@ import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { parser } from '@aws-lambda-powertools/parser';
 import { z } from 'zod';
 import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -24,7 +27,7 @@ class Lambda implements LambdaInterface {
   public async handler(event: Order, _context: Context): Promise<void> {
     // event is now typed as Order
     for (const item of event.items) {
-      console.log(item.id); // (2)!
+      logger.info('Processing item', item); // (2)!
     }
   }
 }
diff --git a/docs/snippets/parser/envelopeMiddy.ts b/docs/snippets/parser/envelopeMiddy.ts
@@ -3,6 +3,9 @@ import { parser } from '@aws-lambda-powertools/parser/middleware';
 import { z } from 'zod';
 import middy from '@middy/core';
 import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -25,7 +28,7 @@ const lambdaHandler = async (
 ): Promise<void> => {
   for (const item of event.items) {
     // item is parsed as OrderItem
-    console.log(item.id);
+    logger.info('Processing item', { item });
   }
 };
 
diff --git a/docs/snippets/parser/extend.ts b/docs/snippets/parser/extend.ts
@@ -3,6 +3,9 @@ import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { parser } from '@aws-lambda-powertools/parser';
 import { z } from 'zod';
 import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -28,7 +31,7 @@ class Lambda implements LambdaInterface {
   public async handler(event: OrderEvent, _context: Context): Promise<void> {
     for (const item of event.detail.items) {
       // process OrderItem
-      console.log(item); // (3)!
+      logger.info('Processing item', { item }); // (3)!
     }
   }
 }
diff --git a/docs/snippets/parser/manual.ts b/docs/snippets/parser/manual.ts
@@ -3,6 +3,9 @@ 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';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -23,8 +26,8 @@ export const handler = async (
   _context: Context
 ): Promise<void> => {
   const parsedEvent = EventBridgeSchema.parse(event); // (1)!
-  console.log(parsedEvent);
+  logger.info('Parsed event', parsedEvent);
 
   const orders: Order = EventBridgeEnvelope.parse(event, orderSchema); // (2)!
-  console.log(orders);
+  logger.info('Parsed orders', orders);
 };
diff --git a/docs/snippets/parser/manualSafeParse.ts b/docs/snippets/parser/manualSafeParse.ts
@@ -3,6 +3,9 @@ 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';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -23,11 +26,10 @@ export const handler = async (
 ): Promise<void> => {
   const parsedEvent = EventBridgeSchema.safeParse(event); // (1)!
   parsedEvent.success
-    ? console.log(parsedEvent.data)
-    : console.log(parsedEvent.error.message);
-
+    ? logger.info('Event parsed successfully', parsedEvent.data)
+    : logger.error('Event parsing failed', parsedEvent.error);
   const parsedEvenlope = EventBridgeEnvelope.safeParse(event, orderSchema); // (2)!
   parsedEvenlope.success
-    ? console.log(parsedEvenlope.data)
-    : console.log(parsedEvenlope.error.message);
+    ? logger.info('Event envelope parsed successfully', parsedEvenlope.data)
+    : logger.error('Event envelope parsing failed', parsedEvenlope.error);
 };
diff --git a/docs/snippets/parser/middy.ts b/docs/snippets/parser/middy.ts
@@ -2,6 +2,9 @@ import type { Context } from 'aws-lambda';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
 import { z } from 'zod';
 import middy from '@middy/core';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -24,7 +27,7 @@ const lambdaHandler = async (
 ): Promise<void> => {
   for (const item of event.items) {
     // item is parsed as OrderItem
-    console.log(item.id);
+    logger.info('Processing item', { item });
   }
 };
 
diff --git a/docs/snippets/parser/refine.ts b/docs/snippets/parser/refine.ts
@@ -11,11 +11,11 @@ export const orderSchema = z
     id: z.number().positive(),
     description: z.string(),
     items: z.array(orderItemSchema).refine((items) => items.length > 0, {
-      message: 'Order must have at least one item',
+      message: 'Order must have at least one item', // (1)!
     }),
     optionalField: z.string().optional(),
   })
   .refine((order) => order.id > 100 && order.items.length > 100, {
     message:
-      'All orders with more than 100 items must have an id greater than 100',
+      'All orders with more than 100 items must have an id greater than 100', // (2)!
   });
diff --git a/docs/snippets/parser/safeParseDecorator.ts b/docs/snippets/parser/safeParseDecorator.ts
@@ -6,6 +6,9 @@ import type {
   ParsedResult,
   EventBridgeEvent,
 } from '@aws-lambda-powertools/parser/types';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -31,11 +34,11 @@ class Lambda implements LambdaInterface {
     if (event.success) {
       // (2)!
       for (const item of event.data.items) {
-        console.log(item.id); // (3)!
+        logger.info('Processing item', { item }); // (3)!
       }
     } else {
-      console.error(event.error); // (4)!
-      console.log(event.originalEvent); // (5)!
+      logger.error('Failed to parse event', event.error); // (4)!
+      logger.error('Original event is: ', event.originalEvent); // (5)!
     }
   }
 }
diff --git a/docs/snippets/parser/safeParseMiddy.ts b/docs/snippets/parser/safeParseMiddy.ts
@@ -6,6 +6,9 @@ import type {
   ParsedResult,
   EventBridgeEvent,
 } from '@aws-lambda-powertools/parser/types';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -29,11 +32,11 @@ const lambdaHandler = async (
   if (event.success) {
     // (2)!
     for (const item of event.data.items) {
-      console.log(item.id); // (3)!
+      logger.info('Processing item', { item }); // (3)!
     }
   } else {
-    console.error(event.error); // (4)!
-    console.log(event.originalEvent); // (5)!
+    logger.error('Error parsing event', { event: event.error }); // (4)!
+    logger.error('Original event', { event: event.originalEvent }); // (5)!
   }
 };
 
diff --git a/docs/snippets/parser/types.ts b/docs/snippets/parser/types.ts
@@ -2,6 +2,9 @@ import type { Context } from 'aws-lambda';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
 import { z } from 'zod';
 import middy from '@middy/core';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
 
 const orderSchema = z.object({
   id: z.number().positive(),
@@ -24,7 +27,7 @@ const lambdaHandler = async (
 ): Promise<void> => {
   for (const item of event.items) {
     // item is parsed as OrderItem
-    console.log(item.id); // (3)!
+    logger.info('Processing item', { item }); // (3)!
   }
 };
 
diff --git a/docs/snippets/tsconfig.json b/docs/snippets/tsconfig.json
@@ -34,7 +34,8 @@
       "@aws-lambda-powertools/jmespath/envelopes": [
         "../../packages/jmespath/lib/envelopes"
       ],
-      "@aws-lambda-powertools/parser": ["../../packages/parser/lib"]
+      "@aws-lambda-powertools/parser": ["../../packages/parser/lib"],
+      "@aws-lambda-powertools/logger": ["../../packages/logger/lib"]
     }
   }
 }
diff --git a/docs/utilities/parser.md b/docs/utilities/parser.md
@@ -47,15 +47,15 @@ Both are also able to parse either an object or JSON string as an input.
 
 ???+ 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.
+    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.
 
 === "Middy middleware"
-    ```typescript hl_lines="32"
+    ```typescript hl_lines="34"
     --8<-- "docs/snippets/parser/middy.ts"
     ```    
 
 === "Decorator" 
-    ```typescript hl_lines="22"
+    ```typescript hl_lines="25"
     --8<-- "docs/snippets/parser/decorator.ts"
     ```
 
@@ -96,7 +96,7 @@ Parser comes with the following built-in schemas:
 You can extend every built-in schema to include your own schema, and yet have all other known fields parsed along the way.
 
 === "handler.ts"
-    ```typescript hl_lines="20-22 27 30"
+    ```typescript hl_lines="23-25 30 34"
     --8<-- "docs/snippets/parser/extend.ts"
     ```
 
@@ -124,12 +124,12 @@ 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"
+    ```typescript hl_lines="5 36"
     --8<-- "docs/snippets/parser/envelopeMiddy.ts"
     ```
 
 === "Decorator"
-    ```typescript hl_lines="5 23"
+    ```typescript hl_lines="5 26 30"
     --8<-- "docs/snippets/parser/envelopeDecorator.ts"
     ```
 
@@ -177,7 +177,7 @@ The `ParsedResult` object will have `success`, `data`,  or `error` and `original
 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"
+    ```typescript hl_lines="32 35 38 39 44"
     --8<-- "docs/snippets/parser/safeParseMiddy.ts"
     ```
 
@@ -188,7 +188,7 @@ If the parsing is successful, the `data` field will contain the parsed event, ot
     5. Use `originalEvent` to get the original event and recover
 
 === "Decorator"
-    ```typescript hl_lines="26 31 34 37 38"
+    ```typescript hl_lines="29 35 37 40 41"
     --8<-- "docs/snippets/parser/safeParseDecorator.ts"
     ```
     
@@ -205,15 +205,15 @@ You can use built-in envelopes and schemas to parse the incoming events manually
 
 
 === "Manual parse"
-    ```typescript hl_lines="25 28"
+    ```typescript hl_lines="28 31"
     --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"
+    ```typescript hl_lines="27 31"
     --8<-- "docs/snippets/parser/manualSafeParse.ts"
     ```
 
@@ -230,31 +230,29 @@ For example, you can use `refine` to validate a field or a combination of fields
     --8<-- "docs/snippets/parser/refine.ts"
     ```
 
+    1. validate a single field
+    2. validate an object with multiple fields
+
 Zod provides a lot of other features and customization, see [Zod documentation](https://zod.dev) for more details.
 
 
 ## Types
 
 ### Schema and Type inference
-Zod provides a way to extract the type of schema, so you can use it in your handler:
+Use `z.infer` to extract the type of the schema, so you can use types during development and avoid type errors.
 
 === "Types"
-    ```typescript hl_lines="19 22 27"
+    ```typescript hl_lines="22 25 30"
     --8<-- "docs/snippets/parser/types.ts"
     ```
     
-    1. Use `z.infer` to extract the type of the schema
-    2. `event` is typed as `Order` object
-    3. we can infer deeply nested types, here `Order` and `OrderItem` are inferred
+    1. Use `z.infer` to extract the type of the schema, also works for nested schemas
+    2. `event` is of type `Order`
+    3. infer types from deeply nested schemas 
 
 ### Compatibility with @types/aws-lambda
 
-The package `@types/aws-lambda` contains type definitions for AWS service event invocations. 
-Powertools parser utility also bring AWS Lambda event types based on the built-in schema definitions. 
-Both libraries try to provide types for the same event structure, but they might not be compatible with each other yet. 
-We are working on a sustainable solution to make them compatible and avoid any breaking changes in the future. 
-
-We recommend to use the types provided by the parser utility. 
+The package `@types/aws-lambda` is a popular project that contains type definitions for many AWS service event invocations. 
+Powertools parser utility also bring AWS Lambda event types based on the built-in schema definitions.
 
-## Error handling
-We don't have any error handling in the utility and propagate all errors from Zod, which are thrown as `ZodError`. 
+We recommend to use the types provided by the parser utilit. If you encounter any issues or have any feedback, please [submit an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose). 

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,9 @@ import type { Context } from 'aws-lambda';`
`2`	`2`	`import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';`
`3`	`3`	`import { parser } from '@aws-lambda-powertools/parser';`
`4`	`4`	`import { z } from 'zod';`
	`5`	`+import { Logger } from '@aws-lambda-powertools/logger';`
	`6`	`+`
	`7`	`+const logger = new Logger();`
`5`	`8`
`6`	`9`	`const orderSchema = z.object({`
`7`	`10`	`id: z.number().positive(),`
`@@ -23,7 +26,7 @@ class Lambda implements LambdaInterface {`
`23`	`26`	`public async handler(event: Order, _context: Context): Promise<void> {`
`24`	`27`	`// event is now typed as Order`
`25`	`28`	`for (const item of event.items) {`
`26`		`- console.log(item.id);`
	`29`	`+ logger.info('Processing item', { item });`
`27`	`30`	`}`
`28`	`31`	`}`
`29`	`32`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,9 @@ import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';`
`3`	`3`	`import { parser } from '@aws-lambda-powertools/parser';`
`4`	`4`	`import { z } from 'zod';`
`5`	`5`	`import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';`
	`6`	`+import { Logger } from '@aws-lambda-powertools/logger';`
	`7`	`+`
	`8`	`+const logger = new Logger();`
`6`	`9`
`7`	`10`	`const orderSchema = z.object({`
`8`	`11`	`id: z.number().positive(),`
`@@ -24,7 +27,7 @@ class Lambda implements LambdaInterface {`
`24`	`27`	`public async handler(event: Order, _context: Context): Promise<void> {`
`25`	`28`	`// event is now typed as Order`
`26`	`29`	`for (const item of event.items) {`
`27`		`- console.log(item.id); // (2)!`
	`30`	`+ logger.info('Processing item', item); // (2)!`
`28`	`31`	`}`
`29`	`32`	`}`
`30`	`33`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,9 @@ import type {`
`6`	`6`	`ParsedResult,`
`7`	`7`	`EventBridgeEvent,`
`8`	`8`	`} from '@aws-lambda-powertools/parser/types';`
	`9`	`+import { Logger } from '@aws-lambda-powertools/logger';`
	`10`	`+`
	`11`	`+const logger = new Logger();`
`9`	`12`
`10`	`13`	`const orderSchema = z.object({`
`11`	`14`	`id: z.number().positive(),`
`@@ -31,11 +34,11 @@ class Lambda implements LambdaInterface {`
`31`	`34`	`if (event.success) {`
`32`	`35`	`// (2)!`
`33`	`36`	`for (const item of event.data.items) {`
`34`		`- console.log(item.id); // (3)!`
	`37`	`+ logger.info('Processing item', { item }); // (3)!`
`35`	`38`	`}`
`36`	`39`	`} else {`
`37`		`- console.error(event.error); // (4)!`
`38`		`- console.log(event.originalEvent); // (5)!`
	`40`	`+ logger.error('Failed to parse event', event.error); // (4)!`
	`41`	`+ logger.error('Original event is: ', event.originalEvent); // (5)!`
`39`	`42`	`}`
`40`	`43`	`}`
`41`	`44`	`}`