or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

core-parsing.md envelopes.md errors.md helpers.md index.md middleware.md parser-decorator.md schemas.md

tile.json

tessl/npm-aws-lambda-powertools--parser

Data validation and parsing for Standard Schema and Zod schemas with built-in support for popular AWS Lambda event sources

Workspace: tessl
Visibility: Public
Created: 3 days ago
Last updated: 3 days ago
Describes: pkg:npm/@aws-lambda-powertools/parser@2.29.x

To install, run

npx @tessl/cli install tessl/npm-aws-lambda-powertools--parser@2.29.0

AWS Lambda Powertools Parser

Data validation and parsing for AWS Lambda using Standard Schema libraries (Zod, Valibot). Validates events with built-in schemas for 20+ AWS sources and envelopes for automatic payload extraction.

Package

Name: @aws-lambda-powertools/parser
Install: npm install @aws-lambda-powertools/parser zod
Language: TypeScript/JavaScript

Core Imports

import { parse, parser } from '@aws-lambda-powertools/parser';
import { parser as parserMiddleware } from '@aws-lambda-powertools/parser/middleware';
import { EventBridgeSchema, SqsSchema } from '@aws-lambda-powertools/parser/schemas';
import { EventBridgeEnvelope, SqsEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import { JSONStringified, Base64Encoded } from '@aws-lambda-powertools/parser/helpers';
import { ParseError } from '@aws-lambda-powertools/parser/errors';

Quick Start

Decorator Usage

import { parser } from '@aws-lambda-powertools/parser';
import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import { z } from 'zod';

const orderSchema = z.object({
  id: z.number().positive(),
  items: z.array(z.object({ id: z.number(), quantity: z.number() })),
});

class Lambda {
  @parser({ schema: orderSchema, envelope: EventBridgeEnvelope })
  async handler(event: z.infer<typeof orderSchema>, _context: Context) {
    // event is validated and typed
    event.items.forEach(item => console.log(item));
  }
}

export const handler = new Lambda().handler.bind(new Lambda());

Middleware Usage

import { parser } from '@aws-lambda-powertools/parser/middleware';
import { SqsEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import middy from '@middy/core';
import { z } from 'zod';

const schema = z.object({ id: z.number(), description: z.string() });

export const handler = middy()
  .use(parser({ schema, envelope: SqsEnvelope }))
  .handler(async (event) => {
    // event is Array<typeof schema>
    event.forEach(order => console.log(order.id));
  });

Manual Parsing

import { parse } from '@aws-lambda-powertools/parser';
import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import { z } from 'zod';

const schema = z.object({ id: z.number() });

export const handler = async (event: unknown) => {
  // Throws on error
  const data = parse(event, EventBridgeEnvelope, schema);

  // Safe parse returns ParsedResult
  const result = parse(event, EventBridgeEnvelope, schema, true);
  if (result.success) {
    console.log(result.data);
  } else {
    console.error(result.error.message);
  }
};

Core API

parse()

Core Parsing

parse<T>(data: unknown, envelope: Envelope, schema: T, safeParse?: boolean)

@parser

Parser Decorator

@parser({ schema, envelope?, safeParse? })

parser (middleware)

Middy.js Middleware

parser({ schema, envelope?, safeParse? })

Built-in Schemas

Built-in Schemas - 97+ schemas for AWS event sources

API Gateway: APIGatewayProxyEventSchema, APIGatewayProxyEventV2Schema, APIGatewayProxyWebsocketEventSchema, APIGatewayRequestAuthorizerEventSchema, APIGatewayTokenAuthorizerEventSchema, APIGatewayRequestAuthorizerEventV2Schema

AppSync: AppSyncResolverSchema, AppSyncBatchResolverSchema, AppSyncEventsPublishSchema, AppSyncEventsSubscribeSchema

CloudFormation: CloudFormationCustomResourceCreateSchema, CloudFormationCustomResourceUpdateSchema, CloudFormationCustomResourceDeleteSchema

CloudWatch: CloudWatchLogsSchema

Cognito: CreateAuthChallengeTriggerSchema, CustomEmailSenderTriggerSchema, CustomMessageTriggerSchema, DefineAuthChallengeTriggerSchema, PreSignupTriggerSchema, PostAuthenticationTriggerSchema, PreTokenGenerationTriggerSchemaV1, VerifyAuthChallengeTriggerSchema

DynamoDB: DynamoDBStreamSchema, DynamoDBStreamRecord

EventBridge: EventBridgeSchema

Kafka: KafkaMskEventSchema, KafkaSelfManagedEventSchema

Kinesis: KinesisDataStreamSchema, KinesisFirehoseSchema, KinesisDynamoDBStreamSchema

S3: S3Schema, S3EventNotificationEventBridgeSchema, S3ObjectLambdaEventSchema, S3SqsEventNotificationSchema

SES: SesSchema

SNS: SnsSchema, SnsSqsNotificationSchema

SQS: SqsSchema

Others: AlbSchema, LambdaFunctionUrlSchema, TransferFamilySchema, VpcLatticeSchema, VpcLatticeV2Schema

Envelopes

Envelopes - Extract nested payloads from AWS events

Envelope	Type	Extracts From	Returns
ApiGatewayEnvelope	Object	event.body	T
ApiGatewayV2Envelope	Object	event.body	T
CloudWatchEnvelope	Array	event.awslogs.data.logEvents[].message	T[]
DynamoDBStreamEnvelope	DynamoDB	event.Records[].dynamodb.{NewImage,OldImage}	{NewImage?: T, OldImage?: T}[]
EventBridgeEnvelope	Object	event.detail	T
KafkaEnvelope	Array	event.records[topic][].value	T[]
KinesisEnvelope	Array	event.Records[].kinesis.data	T[]
KinesisFirehoseEnvelope	Array	event.records[].data	T[]
LambdaFunctionUrlEnvelope	Object	event.body	T
SnsEnvelope	Array	event.Records[].Sns.Message	T[]
SnsSqsEnvelope	Array	JSON.parse(event.Records[].body).Message	T[]
SqsEnvelope	Array	event.Records[].body	T[]
VpcLatticeEnvelope	Object	event.body	T
VpcLatticeV2Envelope	Object	event.body	T

Helpers

JSONStringified<T>(schema: ZodType<T>): ZodType<T>
Base64Encoded<T>(schema: ZodType<T>): ZodType<T>
DynamoDBMarshalled<T>(schema: ZodType<T>): ZodType<T>

Extend schemas to handle JSON strings, Base64 encoding, and DynamoDB marshalling.

Error Handling

class ParseError extends Error {
  cause?: unknown;
}

type ParsedResult<Input, Output> =
  | { success: true; data: Output }
  | { success: false; error: Error; originalEvent?: Input };

Use safeParse: true for error handling without exceptions.

Types

type InferOutput<Schema> = Schema['~standard']['types']['output'];

interface ParserOptions<TSchema, TEnvelope, TSafeParse> {
  schema: TSchema;
  envelope?: TEnvelope;
  safeParse?: TSafeParse;
}