docs(parser): add docs for parser utility

docs/snippets/package.json

@@ -37,6 +37,7 @@
     "aws-sdk-client-mock": "^3.0.0",
     "aws-sdk-client-mock-jest": "^3.0.0",
     "axios": "^1.5.0",
-    "hashi-vault-js": "^0.4.14"
+    "hashi-vault-js": "^0.4.14",
+    "zod": "^3.22.4"
   }
 }

docs/snippets/parser/decorator.ts

@@ -0,0 +1,32 @@
+import { Context } from 'aws-lambda';
+import { LambdaInterface } from '@aws-lambda-powertools/commons';
+import { parser } from '@aws-lambda-powertools/parser';
+import { z } from 'zod';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  optionalField: z.string().optional(),
+});
+
+type Order = z.infer<typeof orderSchema>;
+
+class Lambda extends LambdaInterface {
+  @parser({ schema: orderSchema })
+  public async handler(event: Order, _context: Context): Promise<void> {
+    for (const item of event.items) {
+      // item is parsed as OrderItem
+      console.log(item.id);
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/envelopeDecorator.ts

@@ -0,0 +1,33 @@
+import { Context } from 'aws-lambda';
+import { LambdaInterface } from '@aws-lambda-powertools/commons';
+import { parser } from '@aws-lambda-powertools/parser';
+import { z } from 'zod';
+import { eventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  optionalField: z.string().optional(),
+});
+
+type Order = z.infer<typeof orderSchema>;
+
+class Lambda extends LambdaInterface {
+  @parser({ schema: orderSchema, envelope: eventBridgeEnvelope }) // (1)!
+  public async handler(event: Order, _context: Context): Promise<void> {
+    for (const item of event.items) {
+      // item is parsed as OrderItem
+      console.log(item.id); // (2)!
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/envelopeMiddy.ts

@@ -0,0 +1,34 @@
+import { 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';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  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
+    console.log(item.id);
+  }
+};
+
+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,37 @@
+import { Context } from 'aws-lambda';
+import { LambdaInterface } from '@aws-lambda-powertools/commons';
+import { parser } from '@aws-lambda-powertools/parser';
+import { z } from 'zod';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  optionalField: z.string().optional(),
+});
+
+const orderEventSchema = EventBridgeSchema.extend({
+  detail: orderSchema, // (1)!
+});
+
+type OrderEvent = z.infer<typeof orderEventSchema>;
+
+class Lambda extends LambdaInterface {
+  @parser({ schema: orderEventSchema }) // (2)!
+  public async handler(event: OrderEvent, _context: Context): Promise<void> {
+    for (const item of event.detail.items) {
+      // process OrderItem
+      console.log(item); // (3)!
+    }
+  }
+}
+
+const myFunction = new Lambda();
+export const handler = myFunction.handler.bind(myFunction);

docs/snippets/parser/manual.ts

@@ -0,0 +1,30 @@
+import { Context, EventBridgeEvent } from 'aws-lambda';
+import { z } from 'zod';
+import { eventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  optionalField: z.string().optional(),
+});
+
+type Order = z.infer<typeof orderSchema>;
+
+export const handler = async (
+  event: EventBridgeEvent<string, unknown>,
+  _context: Context
+): Promise<void> => {
+  const parsedEvent = EventBridgeSchema.parse(event); // (1)!
+  console.log(parsedEvent);
+
+  const orders: Order = eventBridgeEnvelope(event, orderSchema); // (2)!
+  console.log(orders);
+};

docs/snippets/parser/middy.ts

@@ -0,0 +1,33 @@
+import { Context } from 'aws-lambda';
+import { parser } from '@aws-lambda-powertools/parser/middleware';
+import { z } from 'zod';
+import middy from '@middy/core';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  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
+    console.log(item.id);
+  }
+};
+
+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',
+    }),
+    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',
+  });

docs/snippets/parser/schema.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  optionalField: z.string().optional(),
+});
+
+export { orderSchema, orderItemSchema };

docs/snippets/parser/types.ts

@@ -0,0 +1,33 @@
+import { Context } from 'aws-lambda';
+import { parser } from '@aws-lambda-powertools/parser/middleware';
+import { z } from 'zod';
+import middy from '@middy/core';
+
+const orderItemSchema = z.object({
+  id: z.number().positive(),
+  quantity: z.number(),
+  description: z.string(),
+});
+
+const orderSchema = z.object({
+  id: z.number().positive(),
+  description: z.string(),
+  items: z.array(orderItemSchema),
+  optionalField: z.string().optional(),
+});
+
+type Order = z.infer<typeof orderSchema>; // (1)!
+
+const lambdaHandler = async (
+  event: Order, // (2)!
+  _context: Context
+): Promise<void> => {
+  for (const item of event.items) {
+    // item is parsed as OrderItem
+    console.log(item.id); // (3)!
+  }
+};
+
+export const handler = middy(lambdaHandler).use(
+  parser({ schema: orderSchema })
+);

docs/snippets/tsconfig.json

@@ -4,6 +4,8 @@
     "rootDir": "./",
     "baseUrl": ".",
     "noEmit": true,
+    "noUnusedLocals": false,
+    "allowUnusedLabels": true,
     "paths": {
       "@aws-lambda-powertools/parameters/ssm": [
         "../../packages/parameters/lib/ssm"