docs(parser): add utility readme

.github/scripts/release_patch_package_json.js

@@ -94,4 +94,4 @@ const betaPackages = [];
   } catch (err) {
     throw err;
   }
-})();
+})();

.gitignore

@@ -46,4 +46,4 @@ tmp
 
 # TS build files
 tsconfig.tsbuildinfo
-.tsbuildinfo
+.tsbuildinfo

.husky/pre-push

@@ -4,4 +4,5 @@ npm t \
   -w packages/metrics \
   -w packages/tracer \
   -w packages/idempotency \
-  -w packages/parameters
+  -w packages/parameters \
+  -w packages/parser

.npmignore

@@ -1,6 +1,5 @@
 src
 tests
-jest.config.js
 tsconfig.json
 .vscode
 .github
@@ -13,7 +12,7 @@ coverage
 tslint.json
 tsconfig.json
 MakeFile
-jest.config.js
+jest.config.cjs
 .npmignore
 .eslintignore
 .huskyrc.js

docs/index.md

@@ -61,7 +61,6 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa
     | **[Parameters (AppConfig)](./utilities/parameters.md#install)**       | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata`**{.copyMe}:clipboard:                   |                     |
     | **[Parser](./utilities/parser.md#install)**                           | **`npm i @aws-lambda-powertools/parser zod@~3`**{.copyMe}:clipboard:                                              |                     |
 
-
 === "Lambda Layer"
 
     You can add our layer both in the [AWS Lambda Console _(under `Layers`)_](https://eu-west-1.console.aws.amazon.com/lambda/home#/add/layer){target="_blank"}, or via your favorite infrastructure as code framework with the ARN value.
@@ -325,11 +324,12 @@ Core utilities such as Tracing, Logging, and Metrics will be available across al
 | [Parameters](./utilities/parameters.md)   | High-level functions to retrieve one or more parameters from AWS SSM Parameter Store, AWS Secrets Manager, AWS AppConfig, and Amazon DynamoDB                     |
 | [Idempotency](./utilities/idempotency.md) | Class method decorator, Middy middleware, and function wrapper to make your Lambda functions idempotent and prevent duplicate execution based on payload content. |
 | [Batch Processing](./utilities/batch.md)  | Utility to handle partial failures when processing batches from Amazon SQS, Amazon Kinesis Data Streams, and Amazon DynamoDB Streams.                             |
+| [Parser](./utilities/parser.md)           | Utility to parse and validate AWS Lambda event payloads using Zod, a TypeScript-first schema declaration and validation library.                                  |
 
 ## Environment variables
 
 ???+ info
-	Explicit parameters take precedence over environment variables
+    Explicit parameters take precedence over environment variables
 
 | Environment variable                         | Description                                                                                                   | Utility                                 | Default             |
 | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------- |
@@ -438,4 +438,4 @@ These are our core principles to guide our decision making.
 - __Keep it lean__. Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
 - __We strive for backwards compatibility__. New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
 - __We work backwards from the community__. We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
-- __Progressive__. Utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. They follow language idioms and their community’s common practices.
+- __Progressive__. Utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. They follow language idioms and their community’s common practices.

docs/snippets/package.json

@@ -34,10 +34,12 @@
     "@aws-sdk/client-secrets-manager": "^3.554.0",
     "@aws-sdk/client-ssm": "^3.554.0",
     "@aws-sdk/util-dynamodb": "^3.554.0",
+    "@middy/core": "^4.7.0",
     "aws-sdk": "^2.1598.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)!
+  });