aleios-cloud/eventbridge-toolbox

eventbridge-toolbox

Eventbridge Toolbox is a lightweight eventbridge adapter that can help you enforce good practices in your event-driven architectures.

Eventbridge Contracts

Within event-driven architectures, events facilitate communication between loosely connected services in an application. EventBridge is AWS's tool for implementing asynchronous event-driven workflows.

Event emitters are responsible for broadcasting events to event channels, while event consumers are responsible for executing business logic whenever they encounter a relevant event.

EventBridge contracts ensure a stable and reliable interaction between emitters and consumers. These contracts act as a guiding agreement that guarantees that emitters' published events will consistently trigger the corresponding business logic on the consumer side.

Creating an EventBridge contract

To create an EventBridge Contract, define a type for your contract. Your contract type must extend the interface Contract, with Contract being importable from the eventbridge-toolbox package. This typing will force you to add an event version to your contract. If you ever alter your contract (for instance, to add a new field), please create a copy of the contract in a new file, and give it a version number higher than the previous version of your contract. The detail-type field stays consistent and allows you to link together all versions of your contract.

Create a Contract type:

export interface PersonRegisteredContractV1 extends Contract {
  detail-type: "PersonRegisteredContract";
  detail: {
    'detail-version': 1;
    data: {
      firstName: string;
      lastName: string;
    };
  };
}

As 'detail-version' and detail-type are set as constants in the type, when we create an object of type PersonRegisteredContractV1, the 'detail-version' and detail-type must match what is defined here otherwise you will see an error.

Create a Contract type:

const ourEvent: PersonRegisteredContractV1 = {
  'detail-type': "PersonRegisteredContract";
  detail: {
    'detail-version': 1;
    data: {
      firstName: 'testFirstName';
      lastName: 'testLastName';
    };
  };
}

Creating an Event

The Event class bakes in a lot of best practices. To instantiate an eventbridge-toolbox event, create a new Event and pass in your event detail and event detail type.

You can see an example below:

import Event from "@eventbridge-toolbox";

const loggedInData: LoggedInContractV1 = {
  'detail-type': "LoggedInContract";
  detail: {
    'detail-version': 1;
    data: {
      firstName: "Lucy",
      lastName: "Example",
      timeLoggedIn: "2023-01-01T13:00:00.000Z",
    };
  };
}


const myEvent = new Event(loggedInData);

//equal to the 'loggedInData' object
const myEventDetail = myEvent.getData();

//equal to 'loggedIn'
const myEventDetailType = myEvent.getDetailType():

You can then publish your event by calling the publish function, passing in the ARN of the EventBus which you want to publish your event to and your event source.

You can see an example below for the scenario where the event source is a lambda:

const EVENT_BUS_ARN = getEnvVariable("EVENT_BUS_ARN");

await myEvent.publish(EVENT_BUS_ARN, "lambda.amazonaws.com");

Key Features

• An event construct
• Contracts to enforce types between producers and consumers
• Event versioning

Getting Started

Prerequisites

Installation

With npm:

npm install --save-dev @aleios-cloud/eventbridge-toolbox

With yarn:

yarn add -D @aleios-cloud/eventbridge-toolbox

With pnpm:

pnpm add -D @aleios-cloud/eventbridge-toolbox

Future Improvements

• Integration with

Contributors

Aiden Walton

Luke Yianni

April Bates

Ryan Schuller

eventbridge-toolbox's Issues

🐛 Can't run npx schema-generator due to missing types which should be exported by eventbridge-toolbox

Description
When using eventbridge-toolbox-schema-generator's npx schema-generator command, I receive an error indicating that the types module from eventbridge-toolbox cannot be found.

Expected Behaviour
Schemas generated and added to the event catalog successfully

Current Behaviour
Throw's the following error:

Found testContract1. ts
/Users/solomonparker/wizzair/platform-demo/node_modules/.pnpm/[email protected]/node_modules/ts-json-schema-generator/dist/factory/program…js:89
throw new DiagnosticError_1.DiagnosticError (diagnostics);
DiagnosticError: Cannot find module 'src/classes/types'
or its corresponding
type declarations.
at createProgram (/Users/solomonparker/wizzair/platform-demo/node_modules/_pnpm/[email protected]/node_modules/ts-json-schema-generator/dist/f
actory/program. js:89:19)
at createGenerator (/Users/solomonparker/wizzair/platform-demo/node_modules/_pnpm/[email protected]/node_modules/ts-json-schema-generator/dist /factory/generator.js:9:49)
at file:///Users/solomonparker/wizzair/platform-demo/node_modules/_pnpm/@[email protected]/node_modules/@aleios-cloud
/eventbridge-toolbox-schema-generator/dist/generate-docs-js:47:28
at Array.forEach (<anonymous>)
at file:///Users/solomonparker/wizzair/platform-demo/node_modules/_pnpm/@[email protected]/node_modules/@aleios-cloud
/eventbridge-toolbox-schema-generator/dist/generate-docs-js:20:14
at FReqCallback.oncomplete (node: fs:200:23)

Reproduction Steps

1. Install eventbridge toolbox and eventbridge toolbox schema generator as project dependencies (also had to install ts-json-schema-generator which should be a dependency in eventbridge-toolbox-scehma-generator)
2. Create a directory containing .ts files which export contracts (interfaces extending the Contract type from eventbridge-toolbox)
3. Run npx @eventcatalog/create-eventcatalog@latest demo-event-catalog
4. Remove the example events from the events folder, as well as everything in the services and domains folders
5. Run npx schema-generator <path from root to your event contracts> <path from root to event catalog events>

Possible Solution
Amend the tsconfig in eventbridge-toolbox to ensure that types are packaged correctly. This may be easier if the example-architecture was in a separate repo or if the eventbridge-toolbox repo was restructured as a monorepo; this would also have helped catch this issue earlier.

Additional Context
Contracts used when the issue was encountered:

import { Contract } from "@aleios-cloud/eventbridge-toolbox";

export interface testContract extends Contract {
  detail: {
    "detail-version": 1;
    data: { message: string; name: string };
  };
  "detail-type": "testContractDetail";
}

import { Contract } from "@aleios-cloud/eventbridge-toolbox";

export interface testContract extends Contract {
  detail: {
    "detail-version": 2;
    data: { message: string; name: string };
  };
  "detail-type": "testContractDetail";
}