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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

AWS Lambda Powertools Parser

Name: tessl/npm-aws-lambda-powertools--parser
Author: tessl

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;
}

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 2 months ago
Describes: pkg:npm/@aws-lambda-powertools/parser@2.29.x
Publish Source: CLI
Badge