fix(parser): ddb base schema + other exports (#3741)

Co-authored-by: Alexander Schueren <[email protected]>

Author: dreamorosi

Diff for: docs/utilities/parser.md

@@ -44,7 +44,7 @@ Both are also able to parse either an object or JSON string as an input.
     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="34"
+    ```typescript hl_lines="22"
     --8<-- "examples/snippets/parser/middy.ts"
     ```
 
@@ -157,7 +157,7 @@ If you want to extend a schema and transform a JSON stringified payload to an ob
 If you want to parse a DynamoDB stream event with unmarshalling, you can use the helper function `DynamoDBMarshalled`:
 
 === "DynamoDBStreamSchema with DynamoDBMarshalled"
-    ```typescript hl_lines="17"
+    ```typescript hl_lines="18"
     --8<-- "examples/snippets/parser/extendDynamoDBStreamSchema.ts"
     ```
 
@@ -180,12 +180,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 36"
+    ```typescript hl_lines="23"
     --8<-- "examples/snippets/parser/envelopeMiddy.ts"
     ```
 
 === "Decorator"
-    ```typescript hl_lines="5 26 30"
+    ```typescript hl_lines="26"
     --8<-- "examples/snippets/parser/envelopeDecorator.ts"
     ```
 
@@ -230,26 +230,24 @@ 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="32 35 38 39 44"
+    ```typescript hl_lines="23 28 32-33"
     --8<-- "examples/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
+    2. Use `data` to access the parsed event when successful
+    3. Use `error` to handle the error message
+    4. Use `originalEvent` to get the original event and recover
 
 === "Decorator"
-    ```typescript hl_lines="29 35 37 40 41"
+    ```typescript hl_lines="33 41 45-46"
     --8<-- "examples/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
+    2. Use `data` to access the parsed event when successful
+    3. Use `error` to handle the error message
+    4. Use `originalEvent` to get the original event and recover
 
 ## Manual parsing
 
@@ -316,7 +314,7 @@ If you are you use middy middleware, you don't need to do this.
 
 === "handlerDecorator.test.ts"
 
-    ```typescript hl_lines="26"
+    ```typescript hl_lines="27"
     --8<-- "examples/snippets/parser/unitTestDecorator.ts"
     ```
 
@@ -338,7 +336,7 @@ This also works when using `safeParse` option.
 
 === "handlerSafeParse.test.ts"
 
-    ```typescript hl_lines="21-29 35 45"
+    ```typescript hl_lines="21-30 36 46"
     --8<-- "examples/snippets/parser/unitTestSafeParse.ts"
     ```
 

Diff for: examples/snippets/parser/envelopeDecorator.ts

@@ -1,7 +1,7 @@
 import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { Logger } from '@aws-lambda-powertools/logger';
 import { parser } from '@aws-lambda-powertools/parser';
-import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes/eventbridge';
 import type { Context } from 'aws-lambda';
 import { z } from 'zod';
 

Diff for: examples/snippets/parser/envelopeMiddy.ts

@@ -1,8 +1,7 @@
 import { Logger } from '@aws-lambda-powertools/logger';
-import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes/eventbridge';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
 import middy from '@middy/core';
-import type { Context } from 'aws-lambda';
 import { z } from 'zod';
 
 const logger = new Logger();
@@ -20,18 +19,11 @@ const orderSchema = z.object({
   optionalField: z.string().optional(),
 });
 
-type Order = z.infer<typeof orderSchema>;
-
-const lambdaHandler = async (
-  event: Order,
-  _context: Context
-): Promise<void> => {
-  for (const item of event.items) {
-    // item is parsed as OrderItem
-    logger.info('Processing item', { item });
-  }
-};
-
-export const handler = middy(lambdaHandler).use(
-  parser({ schema: orderSchema, envelope: EventBridgeEnvelope })
-);
+export const handler = middy()
+  .use(parser({ schema: orderSchema, envelope: EventBridgeEnvelope }))
+  .handler(async (event): Promise<void> => {
+    for (const item of event.items) {
+      // item is parsed as OrderItem
+      logger.info('Processing item', { item });
+    }
+  });

Diff for: examples/snippets/parser/extend.ts

@@ -1,7 +1,7 @@
 import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { Logger } from '@aws-lambda-powertools/logger';
 import { parser } from '@aws-lambda-powertools/parser';
-import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas/eventbridge';
 import type { Context } from 'aws-lambda';
 import { z } from 'zod';
 

Diff for: examples/snippets/parser/extendDynamoDBStreamSchema.ts

@@ -1,5 +1,6 @@
 import { DynamoDBMarshalled } from '@aws-lambda-powertools/parser/helpers/dynamodb';
 import {
+  DynamoDBStreamChangeRecordBase,
   DynamoDBStreamRecord,
   DynamoDBStreamSchema,
 } from '@aws-lambda-powertools/parser/schemas/dynamodb';
@@ -13,7 +14,7 @@ const customSchema = z.object({
 const extendedSchema = DynamoDBStreamSchema.extend({
   Records: z.array(
     DynamoDBStreamRecord.extend({
-      dynamodb: z.object({
+      dynamodb: DynamoDBStreamChangeRecordBase.extend({
         NewImage: DynamoDBMarshalled(customSchema).optional(),
       }),
     })

Diff for: examples/snippets/parser/handlerSafeParseDecorator.ts

@@ -1,7 +1,7 @@
 import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { Logger } from '@aws-lambda-powertools/logger';
 import { parser } from '@aws-lambda-powertools/parser';
-import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes/eventbridge';
 import type {
   EventBridgeEvent,
   ParsedResult,

Diff for: examples/snippets/parser/manual.ts

@@ -1,6 +1,6 @@
 import { Logger } from '@aws-lambda-powertools/logger';
-import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
-import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes/eventbridge';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas/eventbridge';
 import type { EventBridgeEvent } from '@aws-lambda-powertools/parser/types';
 import type { Context } from 'aws-lambda';
 import { z } from 'zod';

Diff for: examples/snippets/parser/manualSafeParse.ts

@@ -1,6 +1,6 @@
 import { Logger } from '@aws-lambda-powertools/logger';
-import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
-import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes/eventbridge';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas/eventbridge';
 import type { EventBridgeEvent } from '@aws-lambda-powertools/parser/types';
 import type { Context } from 'aws-lambda';
 import { z } from 'zod';

Diff for: examples/snippets/parser/middy.ts

@@ -1,7 +1,6 @@
 import { Logger } from '@aws-lambda-powertools/logger';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
 import middy from '@middy/core';
-import type { Context } from 'aws-lambda';
 import { z } from 'zod';
 
 const logger = new Logger();
@@ -19,18 +18,11 @@ const orderSchema = z.object({
   optionalField: z.string().optional(),
 });
 
-type Order = z.infer<typeof orderSchema>;
-
-const lambdaHandler = async (
-  event: Order,
-  _context: Context
-): Promise<void> => {
-  for (const item of event.items) {
-    // item is parsed as OrderItem
-    logger.info('Processing item', { item });
-  }
-};
-
-export const handler = middy(lambdaHandler).use(
-  parser({ schema: orderSchema })
-);
+export const handler = middy()
+  .use(parser({ schema: orderSchema }))
+  .handler(async (event): Promise<void> => {
+    for (const item of event.items) {
+      // item is parsed as OrderItem
+      logger.info('Processing item', { item });
+    }
+  });

Diff for: examples/snippets/parser/safeParseDecorator.ts

@@ -1,7 +1,7 @@
 import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
 import { Logger } from '@aws-lambda-powertools/logger';
 import { parser } from '@aws-lambda-powertools/parser';
-import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes/eventbridge';
 import type {
   EventBridgeEvent,
   ParsedResult,
@@ -30,20 +30,19 @@ class Lambda implements LambdaInterface {
   @parser({
     schema: orderSchema,
     envelope: EventBridgeEnvelope,
-    safeParse: true,
-  }) // (1)!
+    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) {
-        logger.info('Processing item', { item }); // (3)!
+        logger.info('Processing item', { item }); // (2)!
       }
     } else {
-      logger.error('Failed to parse event', event.error); // (4)!
-      logger.error('Original event is: ', event.originalEvent); // (5)!
+      logger.error('Failed to parse event', { error: event.error }); // (3)!
+      logger.error('Original event is ', { original: event.originalEvent }); // (4)!
     }
   }
 }

Diff for: examples/snippets/parser/safeParseMiddy.ts

@@ -1,11 +1,6 @@
 import { Logger } from '@aws-lambda-powertools/logger';
 import { parser } from '@aws-lambda-powertools/parser/middleware';
-import type {
-  EventBridgeEvent,
-  ParsedResult,
-} from '@aws-lambda-powertools/parser/types';
 import middy from '@middy/core';
-import type { Context } from 'aws-lambda';
 import { z } from 'zod';
 
 const logger = new Logger();
@@ -23,23 +18,17 @@ const orderSchema = z.object({
   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) {
-      logger.info('Processing item', { item }); // (3)!
+export const handler = middy()
+  .use(
+    parser({ schema: orderSchema, safeParse: true }) // (1)!
+  )
+  .handler(async (event): Promise<void> => {
+    if (event.success) {
+      for (const item of event.data.items) {
+        logger.info('Processing item', { item }); // (2)!
+      }
+    } else {
+      logger.error('Error parsing event', { event: event.error }); // (3)!
+      logger.error('Original event', { event: event.originalEvent }); // (4)!
     }
-  } else {
-    logger.error('Error parsing event', { event: event.error }); // (4)!
-    logger.error('Original event', { event: event.originalEvent }); // (5)!
-  }
-};
-
-export const handler = middy(lambdaHandler).use(
-  parser({ schema: orderSchema, safeParse: true }) // (1)!
-);
+  });

Diff for: examples/snippets/parser/unitTestDecorator.ts

@@ -1,4 +1,5 @@
 import type { Context } from 'aws-lambda';
+import { describe, expect, it } from 'vitest';
 import { handler } from './decorator.js';
 import type { Order } from './schema.js';
 

Diff for: examples/snippets/parser/unitTestSafeParse.ts

@@ -3,6 +3,7 @@ import type {
   ParsedResult,
 } from '@aws-lambda-powertools/parser/types';
 import type { Context } from 'aws-lambda';
+import { describe, expect, it } from 'vitest';
 import { handler } from './safeParseDecorator.js';
 import type { Order } from './schema.js';