Latcher

A TypeScript framework for routing AWS Lambda events. You define matchers for the AWS services you care about - SQS, API Gateway, DynamoDB Streams, S3 and more - and the framework matches your handlers with each event.

This is useful when you want a single Lambda (or a set of Lambdas with shared code) to handle events from multiple sources. Instead of writing your own event detection logic, you declare filters and handlers and let the matcher do the matching.

The full documentation is at pyepye.github.io/latcher.

import { Latcher } from '@latcher/base'
import { apiGatewayMatcher } from './api'
import { sqsMatcher } from './sqs'
import { dynamoDBMatcher } from './dynamo'
import { s3Matcher } from './s3'

const latcher = new Latcher({
  matchers: [apiGatewayMatcher, sqsMatcher, dynamoDBMatcher, s3Matcher]
})

export const handler = latcher.handler()

Features

• Multi-source routing - Combine matchers from different AWS services in a single Lambda handler
• Type-safe - Full TypeScript support with handler types inferred from the schemas and filters on the route
• Declarative filters - Route events by service-specific data - ARN, eventType, topic, bucket, event name, detail type and custom filter functions. Where two routes overlap, the more specific one is tried first, whatever order you registered them in
• Native support for 25 AWS services - Includes dedicated matchers for SQS, SNS, EventBridge, DynamoDB Streams, S3, API Gateway, and more. Any service that emits Lambda events is supported out of the box.
• Works with any AWS service - Even services without native Lambda support can be integrated using CloudTrail and EventBridge using the EventBridgeMatcher.
• Schema validation - Built-in validation for request bodies, message attributes, path params and more. Works with any Standard Schema library
• Well tested - Clear tests covering most code branches for each event type

This framework isn't the right fit in every situation. See When not to use it for more details.

Packages / Supported AWS services

Below is an overview of the packages and matchers included. Each package can be installed individually.

For usage details, check the individual READMEs linked in the table.

Service	Feature / Event Source	Package	Matcher	Link
Amazon API Gateway	REST API	@latcher/apigateway	APIGatewayMatcher	README
Amazon API Gateway	HTTP API	@latcher/apigateway	APIGatewayMatcher	README
Amazon API Gateway	WebSocket	@latcher/apigateway	WebSocketMatcher	README
Amazon API Gateway	Lambda Authorizer	@latcher/apigateway	LambdaAuthorizerMatcher	README
Elastic Load Balancing	Application Load Balancer	@latcher/alb	ALBMatcher	README
Amazon VPC Lattice	VPC Lattice	@latcher/vpclattice	VPCLatticeMatcher	README
Amazon SQS	Queue	@latcher/sqs	SQSMatcher	README
Amazon SNS	Topic notification	@latcher/sns	SNSMatcher	README
Amazon DynamoDB	Streams	@latcher/dynamodb	DynamoDBMatcher	README
Amazon Kinesis	Data Streams	@latcher/kinesis	KinesisMatcher	README
Amazon Data Firehose	Transformation	@latcher/firehose	FirehoseMatcher	README
Amazon MSK / Self-managed	Kafka	@latcher/kafka	KafkaMatcher	README
Amazon MQ	ActiveMQ	@latcher/mq	ActiveMQMatcher	README
Amazon MQ	RabbitMQ	@latcher/mq	RabbitMQMatcher	README
Amazon DocumentDB	Change Streams	@latcher/documentdb	DocumentDBMatcher	README
Amazon EventBridge	Rule	@latcher/eventbridge	EventBridgeMatcher	README
Amazon EventBridge	Pipe	@latcher/eventbridge	EventBridgeMatcher	README
Amazon EventBridge	Bus	@latcher/eventbridge	EventBridgeMatcher	README
Amazon EventBridge	Scheduler	@latcher/base	EventMatcher	README
Amazon S3	Object notification	@latcher/s3	S3Matcher	README
Amazon S3	Batch Operations	@latcher/s3	S3BatchMatcher	README
Amazon CloudWatch	Logs subscription filter	@latcher/cloudwatch	CloudWatchLogsMatcher	README
AWS Step Functions	Task	@latcher/stepfunctions	StepFunctionsMatcher	README
AWS CodePipeline	Job	@latcher/codepipeline	CodePipelineMatcher	README
Amazon Cognito	User Pool triggers	@latcher/cognito	CognitoMatcher	README
AWS AppSync	Resolver	@latcher/appsync	AppSyncMatcher	README
AWS AppSync	Authorizer	@latcher/appsync	AppSyncAuthorizerMatcher	README
AWS AppSync	Events	@latcher/appsync	AppSyncEventsMatcher	README
Amazon SES	Email receipt	@latcher/ses	SESMatcher	README
Amazon Connect	Contact flow	@latcher/connect	ConnectMatcher	README
Amazon Lex	Bot (v2)	@latcher/lex	LexMatcher	README
AWS Secrets Manager	Rotation	@latcher/secretsmanager	SecretsManagerMatcher	README
AWS Config	Custom Rule	@latcher/config	ConfigMatcher	README
AWS Config	Scheduled Rule	@latcher/config	ConfigScheduledMatcher	README
AWS CodeCommit	Repository trigger	@latcher/codecommit	CodeCommitMatcher	README
AWS CloudFormation	Custom Resource	@latcher/cloudformation	CloudFormationMatcher	README
AWS IoT Core	Rules Engine action	@latcher/iot	IoTMatcher	README

Quick start

Install the base package and the service matcher you need:

npm install @latcher/base @latcher/[package]

For example, to install matchers for apigateway and sqs

npm install @latcher/base @latcher/apigateway @latcher/sqs

Basic usage

Here's a quick look at how you define handlers. For the full details on each matcher, check their individual READMEs.

// main handler
import { Latcher } from '@latcher/base'
import { apiMatcher } from './api'
import { sqsMatcher } from './sqs'

const latcher = new Latcher({
  matchers: [apiMatcher, sqsMatcher]
})

export const handler = latcher.handler()

// api.ts
import { createAPIGatewayMatcher } from '@latcher/apigateway'

const apiMatcher = createAPIGatewayMatcher()

apiMatcher.route({
  filters: {
    method: 'POST',
    path: '/order/:id/',
  },
  handler: createOrder // Puts message on an SQS queue with a message attribute of ProcessOrder (string)
})

// sqs.ts
import { createSQSMatcher } from '@latcher/sqs'
import { processOrder } from './order/process'
import { refundOrder } from './order/refund'

const sqsMatcher = createSQSMatcher()

sqsMatcher.route({
  filters: {
    messageAttributes: {
      Type: 'ProcessOrder',
    }
  },
  handler: processOrder
})

sqsMatcher.route({
  filters: {
    messageAttributes: {
      Type: 'RefundOrder',
    }
  },
  handler: refundOrder
})

Testing

@latcher/testing builds AWS events for your tests, with a Vitest fixture for every supported service. See the testing docs for the builders, mock context and mock schemas.

Examples

The service-examples directory has one deployable app per AWS service. Each one has a README with the deploy steps, a script that triggers it and a walk through the logs it produces.

The full-examples directory has apps that chain several AWS services through a single flow.

When not to use it

If your Lambda handles a single event source in a single way, you probably don't need this. Here are some cases where it isn't the right fit:

• Single event source with no filtering - Your Lambda receives events from one source and processes them all the same way. A plain handler function is simpler
• Single-purpose Lambdas - Your Lambda does exactly one thing. Routing and filtering add indirection with no upside
• HTTP-only Lambdas - Dedicated HTTP frameworks like Express, Hono and Fastify have richer ecosystems for middleware, auth and templating
• Performance-critical Lambdas with simple logic - The matcher iterates through registered matchers via canHandleEvent checks and applies middleware chains. For ultra-simple Lambdas where every millisecond counts, a direct handler avoids this overhead
• One Lambda per event source - If you intentionally map one Lambda to one event source for isolated scaling, permissions or deployment, there's nothing to route between