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

Helpers

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

JSONStringified

Parses and validates JSON stringified fields.

function JSONStringified<T extends ZodType>(schema: T): ZodType;

Use for: API Gateway body, SQS message body, SNS message

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

const messageSchema = z.object({
  userId: z.string(),
  action: z.string(),
});

// SQS body is JSON string, parse it
const messages = SqsEnvelope.parse(event, JSONStringified(messageSchema));

// Extend API Gateway schema
const apiEventSchema = APIGatewayProxyEventSchema.extend({
  body: JSONStringified(z.object({
    orderId: z.string(),
    items: z.array(z.string()),
  })),
});

const apiEvent = apiEventSchema.parse(event);
// apiEvent.body is now typed as Order

Base64Encoded

Decodes Base64 fields, auto-decompresses gzip, auto-parses JSON.

function Base64Encoded<T extends ZodType>(schema: T): ZodType;

Use for: Kinesis data, Firehose data, CloudWatch logs

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

const payloadSchema = z.object({
  test: z.string(),
  value: z.number(),
});

// Kinesis data is base64-encoded
const records = KinesisEnvelope.parse(event, Base64Encoded(payloadSchema));

// Combine with JSONStringified for base64-encoded JSON
const clicks = KinesisEnvelope.parse(
  event,
  Base64Encoded(JSONStringified(clickStreamSchema))
);

DynamoDBMarshalled

Unmarshalls DynamoDB attribute values to JavaScript objects.

function DynamoDBMarshalled<T>(schema: ZodType<T>): ZodType;

Use for: DynamoDB Streams NewImage/OldImage

import { DynamoDBMarshalled } from '@aws-lambda-powertools/parser/helpers/dynamodb';
import { DynamoDBStreamEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import { z } from 'zod';

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

const records = DynamoDBStreamEnvelope.parse(
  event,
  DynamoDBMarshalled(userSchema)
);

records.forEach(record => {
  if (record.NewImage) console.log('New user:', record.NewImage.name);
  if (record.OldImage) console.log('Old user:', record.OldImage.name);
});

// Extend DynamoDB record schema
const extendedRecordSchema = DynamoDBStreamRecord.extend({
  dynamodb: z.object({
    NewImage: DynamoDBMarshalled(productSchema).optional(),
    OldImage: DynamoDBMarshalled(productSchema).optional(),
  }).passthrough(),
});

Combining Helpers

// Base64 -> JSON parsing
Base64Encoded(JSONStringified(schema))

// JSON -> DynamoDB unmarshalling (rare)
JSONStringified(DynamoDBMarshalled(schema))

Attribute Value Format

DynamoDB uses marshalled format:

{
  "id": { "S": "123" },
  "name": { "S": "Product" },
  "price": { "N": "99.99" },
  "inStock": { "BOOL": true },
  "tags": { "SS": ["electronics", "sale"] }
}

DynamoDBMarshalled converts to:

{
  "id": "123",
  "name": "Product",
  "price": 99.99,
  "inStock": true,
  "tags": ["electronics", "sale"]
}