Add builder pattern support for event response types

Add derived builders to events.
Builders are conditionally compiled with the "builders" feature flag.

Author: FullyTyped

lambda-events/Cargo.toml

@@ -20,6 +20,7 @@ edition = "2021"
 base64 = { workspace = true }
 bytes = { workspace = true, features = ["serde"], optional = true }
 chrono = { workspace = true, optional = true }
+derive_builder = { version = "0.20", optional = true }
 flate2 = { version = "1.0.24", optional = true }
 http = { workspace = true, optional = true }
 http-body = { workspace = true, optional = true }
@@ -126,6 +127,7 @@ documentdb = []
 eventbridge = ["chrono", "serde_with"]
 
 catch-all-fields = []
+builders = ["derive_builder"]
 
 [package.metadata.docs.rs]
 all-features = true

lambda-events/examples/comprehensive-builders.rs

@@ -0,0 +1,59 @@
+// Example demonstrating builder pattern usage for AWS Lambda events
+#[cfg(feature = "builders")]
+use aws_lambda_events::event::{
+    dynamodb::EventBuilder as DynamoDbEventBuilder,
+    kinesis::KinesisEventBuilder,
+    s3::S3EventBuilder,
+    secretsmanager::SecretsManagerSecretRotationEventBuilder,
+    sns::SnsEventBuilder,
+    sqs::SqsEventBuilder,
+};
+
+#[cfg(feature = "builders")]
+fn main() {
+    
+    // S3 Event - Object storage notifications
+    let s3_event = S3EventBuilder::default()
+        .records(vec![])
+        .build()
+        .unwrap();
+
+    // Kinesis Event - Stream processing
+    let kinesis_event = KinesisEventBuilder::default()
+        .records(vec![])
+        .build()
+        .unwrap();
+
+    // DynamoDB Event - Database change streams
+    let dynamodb_event = DynamoDbEventBuilder::default()
+        .records(vec![])
+        .build()
+        .unwrap();
+
+    // SNS Event - Pub/sub messaging
+    let sns_event = SnsEventBuilder::default()
+        .records(vec![])
+        .build()
+        .unwrap();
+
+    // SQS Event - Queue messaging
+    let sqs_event = SqsEventBuilder::default()
+        .records(vec![])
+        .build()
+        .unwrap();
+
+    // Secrets Manager Event - Secret rotation
+    let secrets_event = SecretsManagerSecretRotationEventBuilder::default()
+        .step("createSecret")
+        .secret_id("test-secret")
+        .client_request_token("token-123")
+        .build()
+        .unwrap();
+
+}
+
+#[cfg(not(feature = "builders"))]
+fn main() {
+    println!("This example requires the 'builders' feature to be enabled.");
+    println!("Run with: cargo run --example comprehensive-builders --all-features");
+}

lambda-events/examples/lambda-runtime-authorizer-builder.rs

@@ -0,0 +1,149 @@
+// Example showing how builders solve the Default trait requirement problem
+// when using lambda_runtime with API Gateway custom authorizers
+//
+// ❌ OLD WAY (with Default requirement):
+//    #[derive(Default)]
+//    struct MyContext {
+//        // Had to use Option just for Default
+//        some_thing: Option<ThirdPartyThing>,
+//    }
+//
+//    let mut output = Response::default();
+//    output.is_authorized = true;
+//    output.context = MyContext {
+//        some_thing: Some(thing), // ❌ Unnecessary Some()
+//    };
+//
+// ✅ NEW WAY (with Builder pattern):
+//    struct MyContext {
+//        // No Option needed!
+//        some_thing: ThirdPartyThing,
+//    }
+//
+//    let output = ResponseBuilder::default()
+//        .is_authorized(true)
+//        .context(context)
+//        .build()?;
+//
+// Benefits:
+// • No Option<T> wrapper for fields that always exist
+// • Type-safe construction
+// • Works seamlessly with lambda_runtime::LambdaEvent
+// • Cleaner, more idiomatic Rust code
+
+#[cfg(feature = "builders")]
+use aws_lambda_events::event::apigw::{
+    ApiGatewayV2CustomAuthorizerSimpleResponse,
+    ApiGatewayV2CustomAuthorizerSimpleResponseBuilder,
+    ApiGatewayV2CustomAuthorizerV2Request,
+};
+#[cfg(feature = "builders")]
+use lambda_runtime::{Error, LambdaEvent};
+#[cfg(feature = "builders")]
+use serde::{Deserialize, Serialize};
+
+#[cfg(feature = "builders")]
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SomeThirdPartyThingWithoutDefaultValue {
+    pub api_key: String,
+    pub endpoint: String,
+    pub timeout_ms: u64,
+}
+
+// ❌ OLD WAY: Had to use Option to satisfy Default requirement
+#[cfg(feature = "builders")]
+#[derive(Debug, Default, Serialize, Deserialize)]
+pub struct MyContextOldWay {
+    // NOT IDEAL: Need to wrap with Option just for Default
+    some_thing_always_exists: Option<SomeThirdPartyThingWithoutDefaultValue>,
+}
+
+// ✅ NEW WAY: No Option needed with builder pattern!
+#[cfg(feature = "builders")]
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MyContext {
+    // IDEAL: Can use the actual type directly!
+    some_thing_always_exists: SomeThirdPartyThingWithoutDefaultValue,
+    user_id: String,
+    permissions: Vec<String>,
+}
+
+// ❌ OLD IMPLEMENTATION: Using Default
+#[cfg(feature = "builders")]
+pub async fn function_handler_old_way(
+    _event: LambdaEvent<ApiGatewayV2CustomAuthorizerV2Request>,
+) -> Result<ApiGatewayV2CustomAuthorizerSimpleResponse<MyContextOldWay>, Error> {
+    let mut output: ApiGatewayV2CustomAuthorizerSimpleResponse<MyContextOldWay> =
+        ApiGatewayV2CustomAuthorizerSimpleResponse::default();
+
+    output.is_authorized = true;
+    output.context = MyContextOldWay {
+        // ❌ Had to wrap in Some() even though it always exists
+        some_thing_always_exists: Some(SomeThirdPartyThingWithoutDefaultValue {
+            api_key: "secret-key-123".to_string(),
+            endpoint: "https://api.example.com".to_string(),
+            timeout_ms: 5000,
+        }),
+    };
+
+    Ok(output)
+}
+
+// ✅ NEW IMPLEMENTATION: Using Builder
+#[cfg(feature = "builders")]
+pub async fn function_handler(
+    _event: LambdaEvent<ApiGatewayV2CustomAuthorizerV2Request>,
+) -> Result<ApiGatewayV2CustomAuthorizerSimpleResponse<MyContext>, Error> {
+    let context = MyContext {
+        // ✅ No Option wrapper needed!
+        some_thing_always_exists: SomeThirdPartyThingWithoutDefaultValue {
+            api_key: "secret-key-123".to_string(),
+            endpoint: "https://api.example.com".to_string(),
+            timeout_ms: 5000,
+        },
+        user_id: "user-123".to_string(),
+        permissions: vec!["read".to_string(), "write".to_string()],
+    };
+
+    // ✅ Clean builder pattern - no Default required!
+    let output = ApiGatewayV2CustomAuthorizerSimpleResponseBuilder::default()
+        .is_authorized(true)
+        .context(context)
+        .build()
+        .map_err(|e| format!("Failed to build response: {}", e))?;
+
+    Ok(output)
+}
+
+#[cfg(feature = "builders")]
+fn main() {
+    let context = MyContext {
+        some_thing_always_exists: SomeThirdPartyThingWithoutDefaultValue {
+            api_key: "secret-key-123".to_string(),
+            endpoint: "https://api.example.com".to_string(),
+            timeout_ms: 5000,
+        },
+        user_id: "user-123".to_string(),
+        permissions: vec!["read".to_string(), "write".to_string()],
+    };
+
+    let response = ApiGatewayV2CustomAuthorizerSimpleResponseBuilder::<MyContext>::default()
+        .is_authorized(true)
+        .context(context)
+        .build()
+        .unwrap();
+
+    println!("✅ Built authorizer response for user: {}", response.context.user_id);
+    println!("   Authorized: {}", response.is_authorized);
+    println!("   Permissions: {:?}", response.context.permissions);
+    println!(
+        "   Third-party endpoint: {}",
+        response.context.some_thing_always_exists.endpoint
+    );
+}
+
+#[cfg(not(feature = "builders"))]
+fn main() {
+    println!("This example requires the 'builders' feature to be enabled.");
+    println!("Run with: cargo run --example lambda-runtime-authorizer-builder --features builders");
+}

lambda-events/examples/lambda-runtime-sqs-batch-builder.rs

@@ -0,0 +1,141 @@
+// Example showing how builders simplify SQS batch response construction
+// when handling partial batch failures
+//
+// ❌ OLD WAY (with Default):
+//    for record in event.payload.records {
+//        match process_record(&record).await {
+//            Err(_) => {
+//                let mut item = BatchItemFailure::default();
+//                item.item_identifier = record.message_id.unwrap();
+//                batch_item_failures.push(item)
+//            }
+//        }
+//    }
+//    let mut response = SqsBatchResponse::default();
+//    response.batch_item_failures = batch_item_failures;
+//
+// ✅ NEW WAY (with Builder):
+//    for record in event.payload.records {
+//        match process_record(&record).await {
+//            Err(_) => {
+//                let item = BatchItemFailureBuilder::default()
+//                    .item_identifier(record.message_id.unwrap())
+//                    .build()?;
+//                batch_item_failures.push(item)
+//            }
+//        }
+//    }
+//    let response = SqsBatchResponseBuilder::default()
+//        .batch_item_failures(batch_item_failures)
+//        .build()?;
+//
+// Benefits:
+// • Immutable construction (no mut needed)
+// • Cleaner, more functional style
+// • Type-safe field assignment
+// • Works seamlessly with lambda_runtime::LambdaEvent
+
+#[cfg(feature = "builders")]
+use aws_lambda_events::event::sqs::{
+    BatchItemFailure, BatchItemFailureBuilder, SqsBatchResponse, SqsBatchResponseBuilder, SqsEvent,
+};
+#[cfg(feature = "builders")]
+use lambda_runtime::{Error, LambdaEvent};
+
+// Simulate processing a record
+#[cfg(feature = "builders")]
+#[allow(dead_code)]
+async fn process_record(record: &aws_lambda_events::event::sqs::SqsMessage) -> Result<(), String> {
+    // Simulate some processing logic
+    if let Some(body) = &record.body {
+        if body.contains("error") {
+            return Err(format!("Failed to process message: {}", body));
+        }
+    }
+    Ok(())
+}
+
+// ❌ OLD WAY: Using Default and manual field assignment
+#[cfg(feature = "builders")]
+#[allow(dead_code)]
+async fn function_handler_old_way(event: LambdaEvent<SqsEvent>) -> Result<SqsBatchResponse, Error> {
+    let mut batch_item_failures = Vec::new();
+    
+    for record in event.payload.records {
+        match process_record(&record).await {
+            Ok(_) => (),
+            Err(_) => {
+                let mut item = BatchItemFailure::default();
+                item.item_identifier = record.message_id.unwrap();
+                
+                batch_item_failures.push(item)
+            }
+        }
+    }
+    
+    let mut response = SqsBatchResponse::default();
+    response.batch_item_failures = batch_item_failures;
+    
+    Ok(response)
+}
+
+// ✅ NEW WAY: Using Builder pattern
+#[cfg(feature = "builders")]
+#[allow(dead_code)]
+async fn function_handler(event: LambdaEvent<SqsEvent>) -> Result<SqsBatchResponse, Error> {
+    let mut batch_item_failures = Vec::new();
+    
+    for record in event.payload.records {
+        match process_record(&record).await {
+            Ok(_) => (),
+            Err(_) => {
+                // ✅ Clean builder construction
+                let item = BatchItemFailureBuilder::default()
+                    .item_identifier(record.message_id.unwrap())
+                    .build()
+                    .unwrap();
+                
+                batch_item_failures.push(item)
+            }
+        }
+    }
+    
+    // ✅ Clean response construction with builder
+    let response = SqsBatchResponseBuilder::default()
+        .batch_item_failures(batch_item_failures)
+        .build()
+        .map_err(|e| format!("Failed to build response: {}", e))?;
+    
+    Ok(response)
+}
+
+#[cfg(feature = "builders")]
+fn main() {
+    // Demonstrate builder usage with sample data
+    let failures = vec![
+        BatchItemFailureBuilder::default()
+            .item_identifier("msg-123".to_string())
+            .build()
+            .unwrap(),
+        BatchItemFailureBuilder::default()
+            .item_identifier("msg-456".to_string())
+            .build()
+            .unwrap(),
+    ];
+
+    let response = SqsBatchResponseBuilder::default()
+        .batch_item_failures(failures)
+        .build()
+        .unwrap();
+
+    println!("✅ Built SQS batch response with {} failed items", response.batch_item_failures.len());
+    for failure in &response.batch_item_failures {
+        println!("   Failed message: {}", failure.item_identifier);
+    }
+}
+
+#[cfg(not(feature = "builders"))]
+fn main() {
+    println!("This example requires the 'builders' feature to be enabled.");
+    println!("Run with: cargo run --example lambda-runtime-sqs-batch-builder --features builders");
+}