Skip to content

Commit 64115c6

Browse files
am29dam29d
authored
docs(parser): add api docs (#2685)
1 parent b3bc1f0 commit 64115c6

32 files changed

+1208
-224
lines changed

‎package-lock.json‎

Lines changed: 10 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@
7272
"ts-node": "^10.9.2",
7373
"typedoc": "^0.25.13",
7474
"typedoc-plugin-missing-exports": "^2.3.0",
75+
"typedoc-plugin-zod": "^1.1.2",
7576
"typescript": "^5.4.5"
7677
},
7778
"lint-staged": {

‎packages/parser/src/errors.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
2-
* Error thrown when a parsing error occurs. The cause of the error is included in the message, if possible.
2+
* Custom parsing error that wraps any erros thrown during schema or envelope parsing.
3+
* The cause of the error is included in the message, if possible.
34
*/
45
class ParseError extends Error {
56
/**

‎packages/parser/src/parserDecorator.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import type { ParserOptions, ParsedResult } from './types/index.js';
2222
*
2323
* class Lambda implements LambdaInterface {
2424
*
25-
* ⁣@parser({ envelope: SqsEnvelope, schema: OrderSchema })
25+
* @parser({ envelope: SqsEnvelope, schema: OrderSchema })
2626
* public async handler(event: Order, _context: Context): Promise<unknown> {
2727
* // sqs event is parsed and the payload is extracted and parsed
2828
* // apply business logic to your Order event
@@ -53,7 +53,7 @@ import type { ParserOptions, ParsedResult } from './types/index.js';
5353
*
5454
* class Lambda implements LambdaInterface {
5555
*
56-
* ⁣git@parser({ envelope: SqsEnvelope, schema: OrderSchema, safeParse: true })
56+
* @parser({ envelope: SqsEnvelope, schema: OrderSchema, safeParse: true })
5757
* public async handler(event: ParsedResult<Order>, _context: unknown): Promise<unknown> {
5858
* if (event.success) {
5959
* // event.data is the parsed event object of type Order

‎packages/parser/src/schemas/alb.ts‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,42 @@
11
import { z } from 'zod';
22

3+
/**
4+
* Zod schema for Application load balancer event
5+
*
6+
* @example
7+
* ```json
8+
* {
9+
* "requestContext": {
10+
* "elb": {
11+
* "targetGroupArn": "arn:aws:elasticloadbalancing:region:123456789012:targetgroup/my-target-group/6d0ecf831eec9f09"
12+
* }
13+
* },
14+
* "httpMethod": "GET",
15+
* "path": "/",
16+
* "queryStringParameters": {
17+
* parameters
18+
* },
19+
* "headers": {
20+
* "accept": "text/html,application/xhtml+xml",
21+
* "accept-language": "en-US,en;q=0.8",
22+
* "content-type": "text/plain",
23+
* "cookie": "cookies",
24+
* "host": "lambda-846800462-us-east-2.elb.amazonaws.com",
25+
* "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6)",
26+
* "x-amzn-trace-id": "Root=1-5bdb40ca-556d8b0c50dc66f0511bf520",
27+
* "x-forwarded-for": "72.21.198.66",
28+
* "x-forwarded-port": "443",
29+
* "x-forwarded-proto": "https"
30+
* },
31+
* "isBase64Encoded": false,
32+
* "body": "request_body"
33+
* }
34+
* ```
35+
*
36+
* @see {@link types.ALBEvent | ALBEvent}
37+
* @see {@link https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html}
38+
* @see {@link https://docs.aws.amazon.com/lambda/latest/dg/services-alb.html}
39+
*/
340
const AlbSchema = z.object({
441
httpMethod: z.string(),
542
path: z.string(),
@@ -14,6 +51,24 @@ const AlbSchema = z.object({
1451
}),
1552
});
1653

54+
/**
55+
* Zod schema for Application load balancer event with multi-value headers
56+
*
57+
* @example
58+
* ```json
59+
* {
60+
* "multiValueHeaders": {
61+
* "Set-cookie": [
62+
* "cookie-name=cookie-value;Domain=myweb.com;Secure;HttpOnly",
63+
* "cookie-name=cookie-value;Expires=May 8, 2019"
64+
* ],
65+
* "Content-Type": [
66+
* "application/json"
67+
* ]
68+
* }
69+
* }
70+
* ```
71+
*/
1772
const AlbMultiValueHeadersSchema = AlbSchema.extend({
1873
multiValueHeaders: z.record(z.string(), z.array(z.string())),
1974
multiValueQueryStringParameters: z.record(z.string(), z.array(z.string())),

‎packages/parser/src/schemas/apigw.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ const APIGatewayEventRequestContext = z
147147
* "apiId": "abcdef123"
148148
* }
149149
* ```
150+
* @see {@link types.APIGatewayProxyEvent | APIGatewayProxyEvent}
150151
*
151152
* @see {@link https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html}
152153
*/

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

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,90 @@ const CloudFormationCustomResourceBaseSchema = z.object({
1010
ResourceProperties: z.record(z.any()),
1111
});
1212

13+
/**
14+
* Zod schema for CloudFormation Custom Resource event with RequestType = 'Create'
15+
*
16+
* @example
17+
* ```json
18+
* {
19+
* "RequestType": "Create",
20+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
21+
* "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
22+
* "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
23+
* "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
24+
* "LogicalResourceId": "xxxxxxxxx",
25+
* "ResourceType": "Custom::MyType",
26+
* "ResourceProperties": {
27+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
28+
* "MyProps": "ss"
29+
* }
30+
* }
31+
* ```
32+
* @see {@link types.CloudFormationCustomResourceCreateEvent | CloudFormationCustomResourceCreateEvent}
33+
* @see {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requesttypes-create.html}
34+
*/
1335
const CloudFormationCustomResourceCreateSchema =
1436
CloudFormationCustomResourceBaseSchema.merge(
1537
z.object({
1638
RequestType: z.literal('Create'),
1739
})
1840
);
1941

42+
/**
43+
* Zod schema for CloudFormation Custom Resource event with RequestType = 'Delete'
44+
*
45+
* @example
46+
* ```json
47+
* {
48+
* "RequestType": "Delete",
49+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
50+
* "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
51+
* "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
52+
* "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
53+
* "LogicalResourceId": "xxxxxxxxx",
54+
* "ResourceType": "Custom::MyType",
55+
* "ResourceProperties": {
56+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
57+
* "MyProps": "ss"
58+
* }
59+
* }
60+
* ```
61+
* @see {@link types.CloudFormationCustomResourceDeleteEvent | CloudFormationCustomResourceDeleteEvent}
62+
* @see {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requesttypes-delete.html}
63+
*/
2064
const CloudFormationCustomResourceDeleteSchema =
2165
CloudFormationCustomResourceBaseSchema.merge(
2266
z.object({
2367
RequestType: z.literal('Delete'),
2468
})
2569
);
2670

71+
/**
72+
* Zod schema for CloudFormation Custom Resource event with RequestType = 'Update'
73+
*
74+
* @example
75+
* ```json
76+
* {
77+
* "RequestType": "Update",
78+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxx:function:xxxx-CrbuiltinfunctionidProvi-2vKAalSppmKe",
79+
* "ResponseURL": "https://cloudformation-custom-resource-response-useast1.s3.amazonaws.com/7F%7Cb1f50fdfc25f3b",
80+
* "StackId": "arn:aws:cloudformation:us-east-1:xxxx:stack/xxxx/271845b0-f2e8-11ed-90ac-0eeb25b8ae21",
81+
* "RequestId": "xxxxx-d2a0-4dfb-ab1f-xxxxxx",
82+
* "LogicalResourceId": "xxxxxxxxx",
83+
* "ResourceType": "Custom::MyType",
84+
* "ResourceProperties": {
85+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx",
86+
* "MyProps": "new"
87+
* },
88+
* "OldResourceProperties": {
89+
* "ServiceToken": "arn:aws:lambda:us-east-1:xxxxx:function:xxxxx-xxxx-xxx",
90+
* "MyProps": "old"
91+
* }
92+
* }
93+
* ```
94+
* @see {@link types.CloudFormationCustomResourceUpdateEvent | CloudFormationCustomResourceUpdateEvent}
95+
* @see {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requesttypes-update.html}
96+
*/
2797
const CloudFormationCustomResourceUpdateSchema =
2898
CloudFormationCustomResourceBaseSchema.merge(
2999
z.object({

‎packages/parser/src/schemas/cloudwatch.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,52 @@ const decompressRecordToJSON = (
2424
return CloudWatchLogsDecodeSchema.parse(JSON.parse(uncompressed));
2525
};
2626

27+
/**
28+
* Zod schema for CloudWatch Logs.
29+
*
30+
* @example
31+
* ```json
32+
* {
33+
* "awslogs": {
34+
* "data": "H4sIAAAAAAAAAHWPwQqCQBCGX0Xm7EFtK+smZBEUgXoLCdMhFtKV3akI8d0bLYmibvPPN3wz00CJxmQnTO41whwWQRIctmEcB6sQbFC3CjW3XW8kxpOpP+OC22d1Wml1qZkQGtoMsScxaczKN3plG8zlaHIta5KqWsozoTYw3/djzwhpLwivWFGHGpAFe7DL68JlBUk+l7KSN7tCOEJ4M3/qOI49vMHj+zCKdlFqLaU2ZHV2a4Ct/an0/ivdX8oYc1UVX860fQDQiMdxRQEAAA=="
35+
* }
36+
* }
37+
* ```
38+
* The `data` field compressed JSON string, once transformed the payload will look like:
39+
*
40+
* @example
41+
* ```json
42+
* {
43+
* "owner": "123456789012",
44+
* "logGroup": "CloudTrail",
45+
* "logStream": "123456789012_CloudTrail_us-east-1",
46+
* "subscriptionFilters": [
47+
* "Destination"
48+
* ],
49+
* "messageType": "DATA_MESSAGE",
50+
* "logEvents": [
51+
* {
52+
* "id": "31953106606966983378809025079804211143289615424298221568",
53+
* "timestamp": 1432826855000,
54+
* "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
55+
* },
56+
* {
57+
* "id": "31953106606966983378809025079804211143289615424298221569",
58+
* "timestamp": 1432826855000,
59+
* "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
60+
* },
61+
* {
62+
* "id": "31953106606966983378809025079804211143289615424298221570",
63+
* "timestamp": 1432826855000,
64+
* "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
65+
* }
66+
* ]
67+
* }
68+
* ```
69+
*
70+
* @see {@link types.CloudWatchLogsEvent | CloudWatchLogsEvent}
71+
* @see {@link https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html#LambdaFunctionExample}
72+
*/
2773
const CloudWatchLogsSchema = z.object({
2874
awslogs: z.object({
2975
data: z.string().transform((data) => decompressRecordToJSON(data)),

‎packages/parser/src/schemas/dynamodb.ts‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,81 @@ const DynamoDBStreamRecord = z.object({
3131
userIdentity: UserIdentity.optional(),
3232
});
3333

34+
/**
35+
* Zod schema for Amazon DynamoDB Stream event.
36+
*
37+
* @example
38+
* ```json
39+
* {
40+
* "Records": [
41+
* {
42+
* "eventID": "1",
43+
* "eventVersion": "1.0",
44+
* "dynamodb": {
45+
* "ApproximateCreationDateTime": 1693997155.0,
46+
* "Keys": {
47+
* "Id": {
48+
* "N": "101"
49+
* }
50+
* },
51+
* "NewImage": {
52+
* "Message": {
53+
* "S": "New item!"
54+
* },
55+
* "Id": {
56+
* "N": "101"
57+
* }
58+
* },
59+
* "StreamViewType": "NEW_AND_OLD_IMAGES",
60+
* "SequenceNumber": "111",
61+
* "SizeBytes": 26
62+
* },
63+
* "awsRegion": "us-west-2",
64+
* "eventName": "INSERT",
65+
* "eventSourceARN": "eventsource_arn",
66+
* "eventSource": "aws:dynamodb"
67+
* },
68+
* {
69+
* "eventID": "2",
70+
* "eventVersion": "1.0",
71+
* "dynamodb": {
72+
* "OldImage": {
73+
* "Message": {
74+
* "S": "New item!"
75+
* },
76+
* "Id": {
77+
* "N": "101"
78+
* }
79+
* },
80+
* "SequenceNumber": "222",
81+
* "Keys": {
82+
* "Id": {
83+
* "N": "101"
84+
* }
85+
* },
86+
* "SizeBytes": 59,
87+
* "NewImage": {
88+
* "Message": {
89+
* "S": "This item has changed"
90+
* },
91+
* "Id": {
92+
* "N": "101"
93+
* }
94+
* },
95+
* "StreamViewType": "NEW_AND_OLD_IMAGES"
96+
* },
97+
* "awsRegion": "us-west-2",
98+
* "eventName": "MODIFY",
99+
* "eventSourceARN": "source_arn",
100+
* "eventSource": "aws:dynamodb"
101+
* }
102+
* ]
103+
* }
104+
* ```
105+
*
106+
* @see {@link types.DynamoDBStreamEvent | DynamoDBStreamEvent}
107+
* @see {@link https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html}
108+
*/
34109
const DynamoDBStreamSchema = z.object({
35110
Records: z.array(DynamoDBStreamRecord),
36111
});

‎packages/parser/src/schemas/eventbridge.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,32 @@
11
import { z } from 'zod';
22

3+
/**
4+
* Zod schema for EventBridge event
5+
*
6+
* @example
7+
* ```json
8+
* {
9+
* "version": "0",
10+
* "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
11+
* "detail-type": "EC2 Instance State-change Notification",
12+
* "source": "aws.ec2",
13+
* "account": "111122223333",
14+
* "time": "2017-12-22T18:43:48Z",
15+
* "region": "us-west-1",
16+
* "resources": [
17+
* "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0"
18+
* ],
19+
* "detail": {
20+
* "instance_id": "i-1234567890abcdef0",
21+
* "state": "terminated"
22+
* },
23+
* "replay-name": "replay_archive"
24+
* }
25+
* ```
26+
*
27+
* @see {@link types.EventBridgeEvent | EventBridgeEvent}
28+
* @see {@link https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-events.html}
29+
*/
330
const EventBridgeSchema = z.object({
431
version: z.string(),
532
id: z.string(),

0 commit comments

Comments
 (0)