docs(parser): add docs for parser utility

docs/index.md

@@ -26,7 +26,7 @@ You can use Powertools for AWS Lambda (TypeScript) in both TypeScript and JavaSc
 
 You can install Powertools for AWS Lambda (TypeScript) using one of the following options:
 
-* **Lambda Layer**: [**arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:3**](#){: .copyMe}:clipboard:
+* **Lambda Layer**: [**arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:21**](#){: .copyMe}:clipboard:
 * **npm**: [`npm install @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics @aws-lambda-powertools/logger`](#){: .copyMe}:clipboard:
 
 ### Lambda Layer

docs/snippets/package.json

@@ -2,11 +2,11 @@
   "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"
   },
-  "private": true,
   "scripts": {
     "test": "echo 'Not Applicable'",
     "test:e2e": "echo 'Not Applicable'",
@@ -34,10 +34,12 @@
     "@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",
     "axios": "^1.6.8",
-    "hashi-vault-js": "^0.4.14"
+    "hashi-vault-js": "^0.4.14",
+    "zod": "^3.22.4"
   }
 }

docs/snippets/parser/decorator.ts

@@ -0,0 +1,35 @@
+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(),
+  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 })
+  public async handler(event: Order, _context: Context): Promise<void> {
+    // event is now typed as Order
+    for (const item of event.items) {
+      logger.info('Processing item', { item });
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/envelopeDecorator.ts

@@ -0,0 +1,36 @@
+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 { 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(),
+  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, envelope: EventBridgeEnvelope }) // (1)!
+  public async handler(event: Order, _context: Context): Promise<void> {
+    // event is now typed as Order
+    for (const item of event.items) {
+      logger.info('Processing item', item); // (2)!
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/envelopeMiddy.ts

@@ -0,0 +1,37 @@
+import type { Context } from 'aws-lambda';
+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(),
+  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: 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 })
+);

docs/snippets/parser/examplePayload.json

@@ -0,0 +1,21 @@
+{
+  "version": "0",
+  "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
+  "detail-type": "OrderPurchased",
+  "source": "OrderService",
+  "account": "111122223333",
+  "time": "2020-10-22T18:43:48Z",
+  "region": "us-west-1",
+  "resources": ["some_additional"],
+  "detail": {
+    "id": 10876546789,
+    "description": "My order",
+    "items": [
+      {
+        "id": 1015938732,
+        "quantity": 1,
+        "description": "item xpto"
+      }
+    ]
+  }
+}

docs/snippets/parser/extend.ts

@@ -0,0 +1,40 @@
+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 { 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(),
+  description: z.string(),
+  items: z.array(
+    z.object({
+      id: z.number().positive(),
+      quantity: z.number(),
+      description: z.string(),
+    })
+  ),
+  optionalField: z.string().optional(),
+});
+
+const orderEventSchema = EventBridgeSchema.extend({
+  detail: orderSchema, // (1)!
+});
+
+type OrderEvent = z.infer<typeof orderEventSchema>;
+
+class Lambda implements LambdaInterface {
+  @parser({ schema: orderEventSchema }) // (2)!
+  public async handler(event: OrderEvent, _context: Context): Promise<void> {
+    for (const item of event.detail.items) {
+      // process OrderItem
+      logger.info('Processing item', { item }); // (3)!
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/manual.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';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
+
+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>;
+
+export const handler = async (
+  event: EventBridgeEvent,
+  _context: Context
+): Promise<void> => {
+  const parsedEvent = EventBridgeSchema.parse(event); // (1)!
+  logger.info('Parsed event', parsedEvent);
+
+  const orders: Order = EventBridgeEnvelope.parse(event, orderSchema); // (2)!
+  logger.info('Parsed orders', orders);
+};

docs/snippets/parser/manualSafeParse.ts

@@ -0,0 +1,35 @@
+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';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
+
+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
+    ? logger.info('Event parsed successfully', parsedEvent.data)
+    : logger.error('Event parsing failed', parsedEvent.error);
+  const parsedEvenlope = EventBridgeEnvelope.safeParse(event, orderSchema); // (2)!
+  parsedEvenlope.success
+    ? logger.info('Event envelope parsed successfully', parsedEvenlope.data)
+    : logger.error('Event envelope parsing failed', parsedEvenlope.error);
+};

docs/snippets/parser/middy.ts

@@ -0,0 +1,36 @@
+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(),
+  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: 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 })
+);

docs/snippets/parser/refine.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+export const orderSchema = z
+  .object({
+    id: z.number().positive(),
+    description: z.string(),
+    items: z.array(orderItemSchema).refine((items) => items.length > 0, {
+      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', // (2)!
+  });

docs/snippets/parser/safeParseDecorator.ts

@@ -0,0 +1,47 @@
+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';
+import { Logger } from '@aws-lambda-powertools/logger';
+
+const logger = new Logger();
+
+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) {
+        logger.info('Processing item', { item }); // (3)!
+      }
+    } else {
+      logger.error('Failed to parse event', event.error); // (4)!
+      logger.error('Original event is: ', event.originalEvent); // (5)!
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);