aws-lambda-events-cr

Typed Crystal structs for the JSON payloads AWS Lambda delivers from each event source. Pairs naturally with Crowbar, but the structs are plain JSON::Serializable types and work standalone too.

Installation

Add the dependency to your shard.yml:

dependencies:
  aws-lambda-events-cr:
    github: gabriel-ss/aws-lambda-events-cr

Then shards install.

The shard has no top-level entry point — require only the service module you actually use:

require "aws-lambda-events-cr/s3"
require "aws-lambda-events-cr/sqs"
# etc.

Usage

Every service module lives under the AWSLambdaEvents::<Service> namespace, exposes its types as JSON::Serializable structs, and — where applicable — defines Event and Response aliases pointing at the canonical inbound and outbound types:

require "crowbar"
require "aws-lambda-events-cr/sqs"

Crowbar.handle_events of_type: AWSLambdaEvents::SQS::Event do |event, context|
  failed = event.records.reject { |msg| process(msg) }
  AWSLambdaEvents::SQS::Response.new(
    failed.map { |msg| AWSLambdaEvents::SQS::BatchItemFailure.new(msg.message_id) }
  )
end

For services where the inbound or outbound type isn't ambiguous, ::Event and ::Response are uniform entry points. For services with multiple distinct triggers (Cognito User Pools, IoT, ECR, CodePipeline, API Gateway custom authorizers) no alias is defined and the descriptive type name is the entry point — e.g. AWSLambdaEvents::Cognito::UserPoolsPreSignup, AWSLambdaEvents::IoT::ButtonEvent.

Conventions

• Field names are snake_case Crystal idiom; JSON keys are remapped via @[JSON::Field(key: "...")] when they differ.
• Bytes fields auto-decode from base64 via a converter (Kinesis::Record#data, SQS::MessageAttribute#binary_value, etc.).
• Timestamps parse RFC 3339 by default; sources that use other formats ship dedicated converters (fractional-epoch for Kinesis/DynamoDB, custom string formats for CodeBuild and CodeCommit, millisecond epoch for Firehose).
• Polymorphic shapes (DynamoDB AttributeValue, EventBridge detail) are modelled with tagged unions / generics so callers can pattern-match with full type safety.
• CloudWatch Logs payloads are base64+gzip — call Event#decode to inflate to the typed Data shape.
• EventBridge events are generic: EventBridgeEvent(T) lets you plug in your own detail shape; EventBridgeEvent(JSON::Any) works for ad-hoc inspection.

Services covered

activemq, alb, apigateway_v1, apigateway_v2, apigateway_authorizer, apigateway_websocket, appsync, autoscaling, chime_bot, clientvpn, cloudwatch_events (EventBridge), cloudwatch_logs, codebuild, codecommit, codedeploy, codepipeline, cognito, config, connect, dynamodb, ecr, ecs, firehose, iot, kafka, kinesis, kinesis_analytics, lambda_url, lex, rabbitmq, s3, s3_batch, s3_object_lambda, secrets_manager, ses, sns, sqs.

Development

shards install
crystal spec

The specs round-trip JSON fixtures vendored from aws/aws-lambda-go (Apache 2.0); see spec/fixtures/README.md for attribution.

The type definitions themselves were ported by hand from the same project's events/ package, which is the de-facto reference catalogue maintained by AWS for Lambda event payloads.

Contributing

1. Fork it (https://github.com/gabriel-ss/aws-lambda-events-cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Gabriel Silveira - creator and maintainer