or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

custom-functions.md envelopes.md errors.md index.md

tile.json

Envelope Extraction

Extract data from AWS Lambda event envelopes using JMESPath. AWS services wrap application data in event structures - envelopes provide expressions to extract the actual data.

API

function extractDataFromEnvelope<T>(
  data: JSONObject,
  envelope: string,
  options?: { customFunctions?: Functions }
): T;

By default, PowertoolsFunctions are enabled for JSON parsing, base64 decoding, and decompression.

Envelope Constants

All built-in envelope constants and their JMESPath expressions:

API Gateway

API_GATEWAY_REST: 'powertools_json(body)'
API_GATEWAY_HTTP: 'powertools_json(body)'

import { extractDataFromEnvelope, API_GATEWAY_REST } from '@aws-lambda-powertools/jmespath/envelopes';
import type { APIGatewayProxyEvent } from 'aws-lambda';

type RequestBody = { username: string; email: string };

const body = extractDataFromEnvelope<RequestBody>(event, API_GATEWAY_REST);

SQS

SQS: 'Records[*].powertools_json(body)'

Extracts and parses message bodies from all records.

import { extractDataFromEnvelope, SQS } from '@aws-lambda-powertools/jmespath/envelopes';
import type { SQSEvent } from 'aws-lambda';

type OrderMessage = { orderId: string; amount: number };

const orders = extractDataFromEnvelope<Array<OrderMessage>>(event, SQS);
for (const order of orders) {
  console.log(`Order ${order.orderId}: $${order.amount}`);
}

SNS

SNS: 'Records[0].Sns.Message | powertools_json(@)'

Extracts and parses message from first SNS record.

import { extractDataFromEnvelope, SNS } from '@aws-lambda-powertools/jmespath/envelopes';
import type { SNSEvent } from 'aws-lambda';

type NotificationMessage = { notificationId: string; message: string };

const notification = extractDataFromEnvelope<NotificationMessage>(event, SNS);

EventBridge

EVENTBRIDGE: 'detail'
CLOUDWATCH_EVENTS_SCHEDULED: 'detail'

Extracts detail field from EventBridge/CloudWatch Events.

import { extractDataFromEnvelope, EVENTBRIDGE } from '@aws-lambda-powertools/jmespath/envelopes';
import type { EventBridgeEvent } from 'aws-lambda';

type OrderDetail = { orderId: string; status: string };

const detail = extractDataFromEnvelope<OrderDetail>(event, EVENTBRIDGE);

Kinesis

KINESIS_DATA_STREAM: 'Records[*].kinesis.powertools_json(powertools_base64(data))'

Extracts, decodes base64, and parses Kinesis records.

import { extractDataFromEnvelope, KINESIS_DATA_STREAM } from '@aws-lambda-powertools/jmespath/envelopes';
import type { KinesisStreamEvent } from 'aws-lambda';

type StreamRecord = { eventType: string; eventData: Record<string, unknown> };

const records = extractDataFromEnvelope<Array<StreamRecord>>(event, KINESIS_DATA_STREAM);

CloudWatch Logs

CLOUDWATCH_LOGS: 'awslogs.powertools_base64_gzip(data) | powertools_json(@).logEvents[*]'

Extracts, decodes base64, decompresses gzip, and parses log events.

import { extractDataFromEnvelope, CLOUDWATCH_LOGS } from '@aws-lambda-powertools/jmespath/envelopes';
import type { CloudWatchLogsEvent } from 'aws-lambda';

type LogEvent = { id: string; message: string; timestamp: number };

const logEvents = extractDataFromEnvelope<Array<LogEvent>>(event, CLOUDWATCH_LOGS);

S3 Event Combinations

S3_SQS: 'Records[*].powertools_json(body).Records[0]'
S3_SNS_SQS: 'Records[*].powertools_json(body).powertools_json(Message).Records[0]'
S3_KINESIS_FIREHOSE: 'records[*].powertools_json(powertools_base64(data)).Records[0]'
S3_SNS_KINESIS_FIREHOSE: 'records[*].powertools_json(powertools_base64(data)).powertools_json(Message).Records[0]'
S3_EVENTBRIDGE_SQS: 'Records[*].powertools_json(body).detail'

Example for S3 via SQS:

import { extractDataFromEnvelope, S3_SQS } from '@aws-lambda-powertools/jmespath/envelopes';
import type { SQSEvent } from 'aws-lambda';

type S3EventRecord = {
  s3: {
    bucket: { name: string };
    object: { key: string };
  };
};

const s3Records = extractDataFromEnvelope<Array<S3EventRecord>>(event, S3_SQS);
for (const record of s3Records) {
  console.log(`Bucket: ${record.s3.bucket.name}, Key: ${record.s3.object.key}`);
}

Custom Envelopes

Create custom envelope expressions for non-standard event structures:

// Basic custom envelope
const body = extractDataFromEnvelope(event, 'powertools_json(body)');

// Chaining functions
extractDataFromEnvelope(
  event,
  'powertools_json(powertools_base64(payload))'
);

// Complex extraction with flattening
const data = extractDataFromEnvelope<number[]>(
  event,
  'deeplyNested[*].someData[]'
);

Types

type JMESPathParsingOptions = {
  customFunctions?: Functions;
};

type JSONObject = JSONArray | JSONValue | object;