@trivikr-test/eventbridge-event-types

Generated, self-contained TypeScript types for the detail payloads of AWS EventBridge events, derived from the EventBridge Schema Registry (aws.events).

The package ships .d.ts only and has no dependency on aws-lambda / @types/aws-lambda. That is deliberate: it is designed so that @types/aws-lambda can import it and combine it with its own EventBridgeEvent type, without creating a circular dependency.

What it exports

// One interface per AWS detail payload, e.g.
export interface GlueJobStateChangeDetail {
  /* ... */
}
export interface CloudWatchAlarmStateChangeDetail {
  /* ... */
}

// A map from each `detail-type` string to its detail interface.
export interface EventBridgeDetailMap {
  "CloudWatch Alarm State Change": CloudWatchAlarmStateChangeDetail;
  "Glue Job State Change": GlueJobStateChangeDetail;
  // ...one entry per AWS detail-type
}

// Convenience union of every known detail-type string.
export type EventBridgeDetailType = keyof EventBridgeDetailMap;

There is intentionally no type here that references EventBridgeEvent. That wiring belongs to the consumer (see below), which keeps the dependency direction one-way: @types/aws-lambda -> this package.

How @types/aws-lambda can consume it

1. Declare the dependency

In types/aws-lambda/package.json, add the package to dependencies:

{
  "dependencies": {
    "@trivikr-test/eventbridge-event-types": "^0.1.0",
  },
}

Because this is a declaration-only package that bundles its own .d.ts, no matching @types/... entry is needed.

2. Wire the map into EventBridgeEvent

In types/aws-lambda/trigger/eventbridge.d.ts, import the map and expose typed helpers next to the existing generic EventBridgeEvent:

import { Handler } from "../handler";
import { EventBridgeDetailMap } from "@trivikr-test/eventbridge-event-types";

// Existing generic event (unchanged).
export interface EventBridgeEvent<TDetailType extends string, TDetail> {
  id: string;
  version: string;
  account: string;
  time: string;
  region: string;
  resources: string[];
  source: string;
  "detail-type": TDetailType;
  detail: TDetail;
  "replay-name"?: string;
}

// New: a fully-typed event for a known AWS detail-type.
export type TypedEventBridgeEvent<K extends keyof EventBridgeDetailMap> =
  EventBridgeEvent<K & string, EventBridgeDetailMap[K]>;

// New: a discriminated union over all known AWS events. Narrowing on
// `detail-type` narrows `detail` to the matching payload.
export type KnownEventBridgeEvent<
  K extends keyof EventBridgeDetailMap = keyof EventBridgeDetailMap,
> = { [T in K]: EventBridgeEvent<T & string, EventBridgeDetailMap[T]> }[K];

export type KnownEventBridgeHandler<
  K extends keyof EventBridgeDetailMap = keyof EventBridgeDetailMap,
> = Handler<KnownEventBridgeEvent<K>, void>;

Re-export these from the package index (types/aws-lambda/index.d.ts) the same way the other trigger types are surfaced.

3. End-user experience

Once published, consumers of @types/aws-lambda can get:

import type { KnownEventBridgeEvent, TypedEventBridgeEvent } from "aws-lambda";

// Discriminated union: detail narrows off `detail-type`.
export const handler = (event: KnownEventBridgeEvent) => {
  switch (event["detail-type"]) {
    case "Glue Job State Change":
      event.detail.jobRunId; // typed
      break;
    case "CloudWatch Alarm State Change":
      event.detail.state.value; // typed
      break;
  }
};

// Or pin a handler to a single detail-type:
export const onGlue = (
  event: TypedEventBridgeEvent<"Glue Job State Change">,
) => {
  event.detail.state; // "SUCCEEDED" | "FAILED" | ...
};

The generic EventBridgeEvent<TDetailType, TDetail> continues to work unchanged for custom (non-AWS) events.

Regenerating the types

The committed index.d.ts is generated; do not edit it by hand. See CONTRIBUTING.md for setup and regeneration instructions.

Why a separate package instead of hand-writing in DefinitelyTyped

The detail schemas already exist, machine-readable, in the EventBridge Schema Registry. Generating from them keeps the types in sync with AWS automatically. DefinitelyTyped does not run codegen in CI, so the generated catalog lives here and @types/aws-lambda consumes the published .d.ts.