@composurecdk/events

EventBridge rule builder for ComposureCDK.

This package provides a fluent builder for EventBridge rules with secure, AWS-recommended defaults. It wraps the CDK Rule construct — refer to the CDK documentation for the full set of configurable properties.

Rule Builder

import { createRuleBuilder } from "@composurecdk/events";
import { Schedule } from "aws-cdk-lib/aws-events";
import { Duration } from "aws-cdk-lib";

const rule = createRuleBuilder()
  .schedule(Schedule.rate(Duration.minutes(15)))
  .description("Idle stopper")
  .build(stack, "IdleStopperSchedule");

Every RuleProps property is available as a fluent setter on the builder. The builder requires at least one of schedule or eventPattern to be set — an EventBridge rule with neither is inert.

Schedule and Match (used for event-pattern matching) are imported directly from aws-cdk-lib/aws-events — this package does not re-export them, matching the convention used elsewhere in the library (e.g. Runtime from aws-cdk-lib/aws-lambda).

Cross-component event bus

The eventBus property accepts a concrete bus or a Ref to one, so the rule can attach to a custom bus built by another component:

import { compose, ref } from "@composurecdk/core";

compose(
  {
    bus: customEventBus,
    rule: createRuleBuilder()
      .eventBus(ref("bus", (r) => r.eventBus))
      .eventPattern({ source: ["my.app"] }),
  },
  { bus: [], rule: ["bus"] },
);

When omitted, the rule attaches to the account default bus, matching CDK's RuleProps.eventBus default.

The prop's inner type is read from CDK's own RuleProps.eventBus rather than pinned to IEventBus, so it accepts whatever the aws-cdk-lib you have installed accepts — including the broader events.IEventBusRef where CDK has widened the prop.

Cross-component event pattern

The eventPattern property also accepts a Ref, so a pattern that names a sibling component's resource can be declared in the same compose map — for example, matching objects created in one particular bucket:

import { compose, ref } from "@composurecdk/core";

compose(
  {
    bucket: createBucketBuilder().eventBridgeEnabled(true),
    rule: createRuleBuilder().eventPattern(
      ref("bucket", (r) => ({
        source: ["aws.s3"],
        detailType: ["Object Created"],
        detail: { bucket: { name: [r.bucket.bucketName] } },
      })),
    ),
  },
  { bucket: [], rule: ["bucket"] },
);

The ref covers the whole pattern and is resolved at build time.

Recommended Alarms

The builder creates AWS-recommended CloudWatch alarms by default. No alarm actions are configured — access alarms from the build result, or use the alarmActionsPolicy from @composurecdk/cloudwatch to wire them to an SNS topic in one place.

| Alarm | Metric | Default threshold | Created when | | -------------------------------- | ------------------------------------------- | ----------------- | ------------------------ | | failedInvocations | FailedInvocations (Sum, 1 min) | > 0 | Always | | throttledRules | ThrottledRules (Sum, 1 min) | > 0 | Always | | invocationsSentToDlq | InvocationsSentToDlq (Sum, 1 min) | > 0 | A target has a DLQ[^dlq] | | invocationsFailedToBeSentToDlq | InvocationsFailedToBeSentToDlq (Sum, 1 min) | > 0 | A target has a DLQ[^dlq] |

[^dlq]: The DLQ metrics only emit data when at least one target on the rule has a deadLetterQueue configured and EventBridge attempts redrive, so the builder creates these two alarms only when a target added via addTarget() has one. A DLQ attached outside the builder is not seen; pass an explicit config ({} for the defaults) to create either alarm regardless. Attach a DLQ via the matching target helper's deadLetterQueue option — see Cross-component DLQ wiring below, and the EventBridge DLQ docs.

The defaults are exported as RULE_ALARM_DEFAULTS for visibility and testing:

import { RULE_ALARM_DEFAULTS } from "@composurecdk/events";

Customizing thresholds

Override individual alarm properties via recommendedAlarms. Unspecified fields keep their defaults.

const rule = createRuleBuilder()
  .eventPattern({ source: ["my.app"] })
  .recommendedAlarms({
    failedInvocations: { threshold: 5, evaluationPeriods: 3 },
  });

Disabling alarms

Disable all recommended alarms:

builder.recommendedAlarms(false);
// or
builder.recommendedAlarms({ enabled: false });

Disable individual alarms:

builder.recommendedAlarms({ throttledRules: false });

Custom alarms

Add custom alarms alongside the recommended ones via addAlarm. The callback receives an AlarmDefinitionBuilder typed to IRule, so the metric factory has access to the rule's properties. The Serverless Lens flags RetryInvocationAttempts as an early indicator of an undersized target — a good candidate for addAlarm:

import { Metric } from "aws-cdk-lib/aws-cloudwatch";
import { Duration } from "aws-cdk-lib";

createRuleBuilder()
  .eventPattern({ source: ["my.app"] })
  .addAlarm("retryAttempts", (alarm) =>
    alarm
      .metric(
        (rule) =>
          new Metric({
            namespace: "AWS/Events",
            metricName: "RetryInvocationAttempts",
            dimensionsMap: { RuleName: rule.ruleName },
            statistic: "Sum",
            period: Duration.minutes(1),
          }),
      )
      .threshold(10)
      .greaterThan()
      .description("Target is being undersized; retries are climbing."),
  );

Applying alarm actions

Alarms are returned in the build result as Record<string, Alarm>:

const result = rule.build(stack, "MyRule");

for (const alarm of Object.values(result.alarms)) {
  alarm.addAlarmAction(new SnsAction(alertTopic));
}

Or apply them stack-wide via alarmActionsPolicy(stack, { defaults: { alarmActions: [new SnsAction(alertTopic)] } }) from @composurecdk/cloudwatch — same pattern used by the rest of the library, so a single SNS topic can fan out to function and rule alarms together.

Adding Targets

Targets are registered via addTarget(key, target), where target is a CDK IRuleTarget (or a Resolvable<IRuleTarget> for cross-component wiring). Each target is exposed on result.targets under its key.

import { createRuleBuilder } from "@composurecdk/events";
import { LambdaFunction } from "aws-cdk-lib/aws-events-targets";

const result = createRuleBuilder()
  .schedule(Schedule.rate(Duration.minutes(15)))
  .addTarget("stopper", new LambdaFunction(idleStopperFn))
  .build(stack, "IdleStopperSchedule");

result.targets.stopper; // IRuleTarget

For cross-component wiring inside a compose system, pass a ref and use the matching target helper from this package (see Target Helpers below):

import { compose, ref } from "@composurecdk/core";
import { createRuleBuilder, lambdaTarget } from "@composurecdk/events";
import { createFunctionBuilder, type FunctionBuilderResult } from "@composurecdk/lambda";

const system = compose(
  {
    stopper: createFunctionBuilder()./* ... */,
    idleStopperSchedule: createRuleBuilder()
      .schedule(Schedule.rate(Duration.minutes(15)))
      .addTarget(
        "stopper",
        lambdaTarget(ref("stopper", (r: FunctionBuilderResult) => r.function)),
      ),
  },
  { stopper: [], idleStopperSchedule: ["stopper"] },
);

Target Helpers

This package ships small free-function helpers that wrap the corresponding aws-events-targets constructs and accept a Resolvable of the underlying resource. Use them inside addTarget instead of constructing the CDK target classes directly — they make cross-component wiring with ref(...) work without an afterBuild hook.

| Helper | Wraps | Underlying resource | | -------------------------- | -------------------- | ---------------------------- | | lambdaTarget | LambdaFunction | Lambda function | | sqsTarget | SqsQueue | SQS queue | | snsTarget | SnsTopic | SNS topic | | sfnStateMachineTarget | SfnStateMachine | Step Functions state machine | | eventBusTarget | EventBus | EventBridge bus | | cloudWatchLogGroupTarget | CloudWatchLogGroup | CloudWatch log group |

The resource parameter is not spelled out per helper on purpose: each one is read from the constructor of the CDK target it wraps, so it accepts exactly what that target accepts on the aws-cdk-lib you have installed. CDK is migrating those constructors to the broader *Ref interfaces one target at a time, so where a target has not moved yet, a resource that is only a *Ref reaches the matching builder prop but not the target. The CDK target's own signature is the answer for the version you are on.

The second argument is the matching CDK target props type (LambdaFunctionProps, SqsQueueProps, …) — refer to the CDK docs for available options. Common ones include deadLetterQueue (concrete IQueue), retryAttempts, maxEventAge, and target-specific input transforms (event / input / message).

Other CDK target types (API Gateway, ECS task, Batch job, Kinesis, Firehose, AppSync, …) are not yet wrapped — pass them inline as a regular IRuleTarget until a wrapper helper lands.

import { compose, ref } from "@composurecdk/core";
import {
  createRuleBuilder,
  lambdaTarget,
  sqsTarget,
} from "@composurecdk/events";
import {
  createFunctionBuilder,
  type FunctionBuilderResult,
} from "@composurecdk/lambda";

compose(
  {
    handler: createFunctionBuilder()./* ... */,
    rule: createRuleBuilder()
      .eventPattern({ source: ["aws.s3"], detailType: ["Object Created"] })
      .addTarget(
        "primary",
        lambdaTarget(ref("handler", (r: FunctionBuilderResult) => r.function), {
          retryAttempts: 2,
        }),
      ),
  },
  { handler: [], rule: ["handler"] },
);

Cross-component DLQ wiring

Each helper takes a single Resolvable for its primary resource. Secondary props such as deadLetterQueue accept the concrete CDK type (IQueue for most targets). When the DLQ is also a sibling-component output, construct the helper inside ref().map() and have the dependency component expose both the resource and the queue:

.addTarget(
  "stopper",
  ref<{ fn: IFunction; dlq: IQueue }>(
    "stopperBundle",
    (b) => lambdaTarget(b.fn, { deadLetterQueue: b.dlq }),
  ),
)

A dedicated DLQ component (createQueueBuilder-style) — and helpers that accept Resolvable<IQueue> for the DLQ directly — are out of scope for this PR; track as a follow-up if a use case emerges.