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

Core Parsing

Core parse() function validates data using Standard Schema compatible libraries (Zod, Valibot).

API

// Without envelope, throws on error
parse<T>(data: unknown, envelope: undefined, schema: T): InferOutput<T>

// Without envelope, safe parsing
parse<T>(data: unknown, envelope: undefined, schema: T, safeParse: true): ParsedResult<unknown, InferOutput<T>>

// With envelope, throws on error
parse<T, E>(data: unknown, envelope: E, schema: T): EnvelopeOutput<E, T>

// With envelope, safe parsing
parse<T, E>(data: unknown, envelope: E, schema: T, safeParse: true): ParsedResult<unknown, EnvelopeOutput<E, T>>

Return types:

EnvelopeOutput =
  | T                               // ObjectEnvelope
  | T[]                             // ArrayEnvelope
  | { NewImage?: T, OldImage?: T }[] // DynamoDBArrayEnvelope

Usage

Basic Validation

import { parse } from '@aws-lambda-powertools/parser';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';

// Throws on error
const event = parse(data, undefined, EventBridgeSchema);
// Returns: EventBridgeEvent

With Envelope

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

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

// Throws on error, returns single object
const order = parse(event, EventBridgeEnvelope, orderSchema);
// Returns: { id: number, description: string }

// With array envelope, returns array
const orders = parse(event, SqsEnvelope, orderSchema);
// Returns: Array<{ id: number, description: string }>

Safe Parsing

const result = parse(event, EventBridgeEnvelope, orderSchema, true);

if (result.success) {
  console.log(result.data.id);
} else {
  console.error(result.error.message);
  console.error(result.originalEvent);
}

With Valibot

import { object, string, number, pipe, toMinValue } from 'valibot';

const orderSchema = object({
  id: pipe(number(), toMinValue(1)),
  description: string(),
});

const order = parse(event, EventBridgeEnvelope, orderSchema);

Standard Schema Support

Accepts any library implementing Standard Schema v1:

type StandardSchemaV1 = {
  '~standard': {
    readonly version: 1;
    readonly vendor: string;
    readonly validate: (value: unknown) => unknown;
    readonly types?: {
      readonly input: unknown;
      readonly output: unknown;
    };
  };
};

Supported libraries: Zod, Valibot, ArkType, and others implementing Standard Schema.

Type Inference

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

// Example
const schema = z.object({ id: z.number() });
type Output = InferOutput<typeof schema>; // { id: number }

ParsedResult Type

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