docs(parser): add api docs (#2685)

Author: am29d

package-lock.json

@@ -72,6 +72,7 @@
     "ts-node": "^10.9.2",
     "typedoc": "^0.25.13",
     "typedoc-plugin-missing-exports": "^2.3.0",
+    "typedoc-plugin-zod": "^1.1.2",
     "typescript": "^5.4.5"
   },
   "lint-staged": {

package.json

@@ -1,5 +1,6 @@
 /**
- * Error thrown when a parsing error occurs. The cause of the error is included in the message, if possible.
+ * Custom parsing error that wraps any erros thrown during schema or envelope parsing.
+ * The cause of the error is included in the message, if possible.
  */
 class ParseError extends Error {
   /**

packages/parser/src/errors.ts

@@ -22,7 +22,7 @@ import type { ParserOptions, ParsedResult } from './types/index.js';
  *
  * class Lambda implements LambdaInterface {
  *
- *   ⁣@parser({ envelope: SqsEnvelope, schema: OrderSchema })
+ *   @parser({ envelope: SqsEnvelope, schema: OrderSchema })
  *   public async handler(event: Order, _context: Context): Promise<unknown> {
  *   // sqs event is parsed and the payload is extracted and parsed
  *   // apply business logic to your Order event
@@ -53,7 +53,7 @@ import type { ParserOptions, ParsedResult } from './types/index.js';
  *
  * class Lambda implements LambdaInterface {
  *
- *   ⁣git@parser({ envelope: SqsEnvelope, schema: OrderSchema,  safeParse: true })
+ *   @parser({ envelope: SqsEnvelope, schema: OrderSchema,  safeParse: true })
  *   public async handler(event: ParsedResult<Order>, _context: unknown): Promise<unknown> {
  *     if (event.success) {
  *      // event.data is the parsed event object of type Order

packages/parser/src/parserDecorator.ts

@@ -1,5 +1,42 @@
 import { z } from 'zod';
 
+/**
+ * Zod schema for Application load balancer event
+ *
+ * @example
+ * ```json
+ * {
+ *   "requestContext": {
+ *     "elb": {
+ *       "targetGroupArn": "arn:aws:elasticloadbalancing:region:123456789012:targetgroup/my-target-group/6d0ecf831eec9f09"
+ *     }
+ *   },
+ *   "httpMethod": "GET",
+ *   "path": "/",
+ *   "queryStringParameters": {
+ *     parameters
+ *   },
+ *   "headers": {
+ *     "accept": "text/html,application/xhtml+xml",
+ *     "accept-language": "en-US,en;q=0.8",
+ *     "content-type": "text/plain",
+ *     "cookie": "cookies",
+ *     "host": "lambda-846800462-us-east-2.elb.amazonaws.com",
+ *     "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6)",
+ *     "x-amzn-trace-id": "Root=1-5bdb40ca-556d8b0c50dc66f0511bf520",
+ *     "x-forwarded-for": "72.21.198.66",
+ *     "x-forwarded-port": "443",
+ *     "x-forwarded-proto": "https"
+ *   },
+ *   "isBase64Encoded": false,
+ *   "body": "request_body"
+ * }
+ * ```
+ *
+ * @see {@link types.ALBEvent | ALBEvent}
+ * @see {@link https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html}
+ * @see {@link https://docs.aws.amazon.com/lambda/latest/dg/services-alb.html}
+ */
 const AlbSchema = z.object({
   httpMethod: z.string(),
   path: z.string(),
@@ -14,6 +51,24 @@ const AlbSchema = z.object({
   }),
 });
 
+/**
+ * Zod schema for Application load balancer event with multi-value headers
+ *
+ * @example
+ * ```json
+ * {
+ *   "multiValueHeaders": {
+ *     "Set-cookie": [
+ *       "cookie-name=cookie-value;Domain=myweb.com;Secure;HttpOnly",
+ *       "cookie-name=cookie-value;Expires=May 8, 2019"
+ *     ],
+ *     "Content-Type": [
+ *       "application/json"
+ *     ]
+ *   }
+ * }
+ * ```
+ */
 const AlbMultiValueHeadersSchema = AlbSchema.extend({
   multiValueHeaders: z.record(z.string(), z.array(z.string())),
   multiValueQueryStringParameters: z.record(z.string(), z.array(z.string())),

packages/parser/src/schemas/alb.ts

@@ -147,6 +147,7 @@ const APIGatewayEventRequestContext = z
  *   "apiId": "abcdef123"
  * }
  * ```
+ * @see {@link types.APIGatewayProxyEvent | APIGatewayProxyEvent}
  *
  * @see {@link https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html}
  */

packages/parser/src/schemas/apigw.ts

@@ -10,20 +10,90 @@ const CloudFormationCustomResourceBaseSchema = z.object({
   ResourceProperties: z.record(z.any()),
 });
 
+/**
+ * Zod schema for CloudFormation Custom Resource event with RequestType = 'Create'
+ *
+ * @example
+ * ```json
+ * {
+ *   "RequestType": "Create",
+ *   "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
+ *   "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
+ *   "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
+ *   "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
+ *   "LogicalResourceId": "xxxxxxxxx",
+ *   "ResourceType": "Custom::MyType",
+ *   "ResourceProperties": {
+ *     "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+ *     "MyProps": "ss"
+ *   }
+ * }
+ * ```
+ * @see {@link types.CloudFormationCustomResourceCreateEvent | CloudFormationCustomResourceCreateEvent}
+ * @see {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requesttypes-create.html}
+ */
 const CloudFormationCustomResourceCreateSchema =
   CloudFormationCustomResourceBaseSchema.merge(
     z.object({
       RequestType: z.literal('Create'),
     })
   );
 
+/**
+ * Zod schema for CloudFormation Custom Resource event with RequestType = 'Delete'
+ *
+ * @example
+ * ```json
+ * {
+ *   "RequestType": "Delete",
+ *   "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
+ *   "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
+ *   "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
+ *   "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
+ *   "LogicalResourceId": "xxxxxxxxx",
+ *   "ResourceType": "Custom::MyType",
+ *   "ResourceProperties": {
+ *     "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+ *     "MyProps": "ss"
+ *   }
+ * }
+ * ```
+ * @see {@link types.CloudFormationCustomResourceDeleteEvent | CloudFormationCustomResourceDeleteEvent}
+ * @see {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requesttypes-delete.html}
+ */
 const CloudFormationCustomResourceDeleteSchema =
   CloudFormationCustomResourceBaseSchema.merge(
     z.object({
       RequestType: z.literal('Delete'),
     })
   );
 
+/**
+ * Zod schema for CloudFormation Custom Resource event with RequestType = 'Update'
+ *
+ * @example
+ * ```json
+ * {
+ *   "RequestType": "Update",
+ *   "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
+ *   "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
+ *   "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
+ *   "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
+ *   "LogicalResourceId": "xxxxxxxxx",
+ *   "ResourceType": "Custom::MyType",
+ *   "ResourceProperties": {
+ *     "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
+ *     "MyProps": "new"
+ *   },
+ *   "OldResourceProperties": {
+ *     "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx-xxxx-xxx",
+ *     "MyProps": "old"
+ *   }
+ * }
+ * ```
+ * @see {@link types.CloudFormationCustomResourceUpdateEvent | CloudFormationCustomResourceUpdateEvent}
+ * @see {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requesttypes-update.html}
+ */
 const CloudFormationCustomResourceUpdateSchema =
   CloudFormationCustomResourceBaseSchema.merge(
     z.object({

packages/parser/src/schemas/cloudformation-custom-resource.ts

@@ -24,6 +24,52 @@ const decompressRecordToJSON = (
   return CloudWatchLogsDecodeSchema.parse(JSON.parse(uncompressed));
 };
 
+/**
+ * Zod schema for CloudWatch Logs.
+ *
+ * @example
+ * ```json
+ * {
+ *   "awslogs": {
+ *     "data": "H4sIAAAAAAAAAHWPwQqCQBCGX0Xm7EFtK+smZBEUgXoLCdMhFtKV3akI8d0bLYmibvPPN3wz00CJxmQnTO41whwWQRIctmEcB6sQbFC3CjW3XW8kxpOpP+OC22d1Wml1qZkQGtoMsScxaczKN3plG8zlaHIta5KqWsozoTYw3/djzwhpLwivWFGHGpAFe7DL68JlBUk+l7KSN7tCOEJ4M3/qOI49vMHj+zCKdlFqLaU2ZHV2a4Ct/an0/ivdX8oYc1UVX860fQDQiMdxRQEAAA=="
+ *   }
+ * }
+ * ```
+ * The `data` field compressed JSON string, once transformed the payload will look like:
+ *
+ * @example
+ * ```json
+ * {
+ *   "owner": "123456789012",
+ *   "logGroup": "CloudTrail",
+ *   "logStream": "123456789012_CloudTrail_us-east-1",
+ *   "subscriptionFilters": [
+ *     "Destination"
+ *   ],
+ *   "messageType": "DATA_MESSAGE",
+ *   "logEvents": [
+ *     {
+ *       "id": "31953106606966983378809025079804211143289615424298221568",
+ *       "timestamp": 1432826855000,
+ *       "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
+ *     },
+ *     {
+ *       "id": "31953106606966983378809025079804211143289615424298221569",
+ *       "timestamp": 1432826855000,
+ *       "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
+ *     },
+ *     {
+ *       "id": "31953106606966983378809025079804211143289615424298221570",
+ *       "timestamp": 1432826855000,
+ *       "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @see {@link types.CloudWatchLogsEvent | CloudWatchLogsEvent}
+ * @see {@link https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html#LambdaFunctionExample}
+ */
 const CloudWatchLogsSchema = z.object({
   awslogs: z.object({
     data: z.string().transform((data) => decompressRecordToJSON(data)),

packages/parser/src/schemas/cloudwatch.ts

@@ -31,6 +31,81 @@ const DynamoDBStreamRecord = z.object({
   userIdentity: UserIdentity.optional(),
 });
 
+/**
+ * Zod schema for Amazon DynamoDB Stream event.
+ *
+ * @example
+ * ```json
+ * {
+ *   "Records": [
+ *     {
+ *       "eventID": "1",
+ *       "eventVersion": "1.0",
+ *       "dynamodb": {
+ *         "ApproximateCreationDateTime": 1693997155.0,
+ *         "Keys": {
+ *           "Id": {
+ *             "N": "101"
+ *           }
+ *         },
+ *         "NewImage": {
+ *           "Message": {
+ *             "S": "New item!"
+ *           },
+ *           "Id": {
+ *             "N": "101"
+ *           }
+ *         },
+ *         "StreamViewType": "NEW_AND_OLD_IMAGES",
+ *         "SequenceNumber": "111",
+ *         "SizeBytes": 26
+ *       },
+ *       "awsRegion": "us-west-2",
+ *       "eventName": "INSERT",
+ *       "eventSourceARN": "eventsource_arn",
+ *       "eventSource": "aws:dynamodb"
+ *     },
+ *     {
+ *       "eventID": "2",
+ *       "eventVersion": "1.0",
+ *       "dynamodb": {
+ *         "OldImage": {
+ *           "Message": {
+ *             "S": "New item!"
+ *           },
+ *           "Id": {
+ *             "N": "101"
+ *           }
+ *         },
+ *         "SequenceNumber": "222",
+ *         "Keys": {
+ *           "Id": {
+ *             "N": "101"
+ *           }
+ *         },
+ *         "SizeBytes": 59,
+ *         "NewImage": {
+ *           "Message": {
+ *             "S": "This item has changed"
+ *           },
+ *           "Id": {
+ *             "N": "101"
+ *           }
+ *         },
+ *         "StreamViewType": "NEW_AND_OLD_IMAGES"
+ *       },
+ *       "awsRegion": "us-west-2",
+ *       "eventName": "MODIFY",
+ *       "eventSourceARN": "source_arn",
+ *       "eventSource": "aws:dynamodb"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @see {@link types.DynamoDBStreamEvent | DynamoDBStreamEvent}
+ * @see {@link https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html}
+ */
 const DynamoDBStreamSchema = z.object({
   Records: z.array(DynamoDBStreamRecord),
 });

packages/parser/src/schemas/dynamodb.ts

@@ -1,5 +1,32 @@
 import { z } from 'zod';
 
+/**
+ * Zod schema for EventBridge event
+ *
+ * @example
+ * ```json
+ * {
+ *   "version": "0",
+ *   "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
+ *   "detail-type": "EC2 Instance State-change Notification",
+ *   "source": "aws.ec2",
+ *   "account": "111122223333",
+ *   "time": "2017-12-22T18:43:48Z",
+ *   "region": "us-west-1",
+ *   "resources": [
+ *     "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0"
+ *   ],
+ *   "detail": {
+ *     "instance_id": "i-1234567890abcdef0",
+ *     "state": "terminated"
+ *   },
+ *   "replay-name": "replay_archive"
+ * }
+ * ```
+ *
+ * @see {@link types.EventBridgeEvent | EventBridgeEvent}
+ * @see {@link https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-events.html}
+ */
 const EventBridgeSchema = z.object({
   version: z.string(),
   id: z.string(),