bull-bus

🚀

Bull Bus

Event Bus for Node.JS using Bull Queues

Table of Contents

• Installation
• How to Use It
• Playground
• Preparing environment to contribute
• Building
• Testing
• Linting
• Contributing

Installation

npm install bull-bus

How to Use It

Bull Bus library offers two main functionalities. The bull bus and the bull event bus.

Bull Bus

This class is a Bus Implementation using Bull, works with primitives data and does not know anything about the domain. It may be useful in case we want to build our own domain event logic.

import { BullBus } from "bull-bus";

const bullBus = new BullBus({
    redisUrl: "redis://127.0.0.1:6379",
});

const accountCreatedTopicName = "account-created";
const userCreatedTopicName = "user-created";

bullBus.addSubscribers([
    {
        topicName: accountCreatedTopicName,
        handleMessage: async (payload: unknown) => {
            console.log("Handle Message Topic A, Handler 1 ", payload);
        },
        subscriberName: "send-email",
    },
    {
        topicName: accountCreatedTopicName,
        handleMessage: async (payload: unknown) => {
            console.log("Handle Message Topic A, Handler 2 ", payload);
        },
        subscriberName: "send-slack",
    },
    {
        topicName: userCreatedTopicName,
        handleMessage: async (payload: unknown) => {
            console.log("payload handler B: ", payload);
        },
        subscriberName: "send-push-notification",
    },
]);

await bullBus.publish(accountCreatedTopicName, {
    accountId: "2",
});

await bullBus.publish(userCreatedTopicName, {
    userId: "1",
});

Bull Event Bus

Bull Event Bus is very similar to the Bull Bus with the difference that gives us some default classes to create domain events and subscriptions. Its useful when we are working with OOP.

  class UserRegistered extends DomainEvent {
    static EVENT_NAME = "user-registered";

    constructor(userName: string) {
        super({
            eventName: UserRegistered.EVENT_NAME,
            attributes: {
                userName,
            },
        });
    }
}

class UserFormCompleted extends DomainEvent {
    static EVENT_NAME = "user-form-completed";

    constructor(value: string) {
        super({
            eventName: UserFormCompleted.EVENT_NAME,
            attributes: {
                value,
            },
        });
    }
}

class SendSlackOnUserOrFormCompleted
    implements DomainEventSubscriber<UserRegistered | UserFormCompleted>
{
    subscribedTo() {
        return [UserRegistered, UserFormCompleted];
    }

    subscriptionName(): string {
        return "send-slack";
    }

    async on(event: UserRegistered | UserFormCompleted) {
        switch (event.eventName) {
            case UserRegistered.EVENT_NAME:
                console.log("Simulating send slack...", event.attributes.userName);
                break;
            case UserFormCompleted.EVENT_NAME:
                console.log("Simulating send slack...", event.attributes.value);
                break;
        }
    }
}

class SendEmailOnUserRegistered
    implements DomainEventSubscriber<UserRegistered>
{
    subscribedTo() {
        return [UserRegistered];
    }

    subscriptionName(): string {
        return "send-email";
    }

    async on(event: UserRegistered) {
        console.log("Simulating send email...", event.attributes.userName);
    }
}

const eventBus = new BullEventBus({
    redisUrl: "redis://127.0.0.1:6379",
});

eventBus.addSubscribers([
    new SendSlackOnUserOrFormCompleted(),
    new SendEmailOnUserRegistered(),
]);

await eventBus.publish([new UserRegistered("gabriel")]);
await eventBus.publish([new UserFormCompleted("3208")]);

Visualization

When we are working with event bus, we normally have 1 event that can be consumed by N subscribers. When we are building the subscribers we need to provide topicName and subscriptionName, in this way when the buses are getting the queue instance will use both attributes as unique identifier. In this way, if we use some Bull UI like taskforce, will show all the subscriptions we have for every topic.

Playground

This library offers a playground where we can play with the functions that we are developing

docker-compose up -d redis
npm run playground

Preparing environment to contribute

This library has been designed to work with node v16 and npm 8. In order to configure your local environment you can run:

nvm install 16.0.0
nvm use
npm install npm@8.3.0 -g
npm install

Building

npm run build

Testing

Jest with Testing Library

npm run test

Linting

Run the linter

npm run lint

Fix lint issues automatically

npm run lint:fix

Contributing

Contributions welcome! See the Contributing Guide.