ts-bus

ts-bus

A lightweight TypeScript event bus to help manage your application architecture

Example

import { EventBus, createEventDefinition } from "ts-bus";

// Define Event
export const someEvent = createEventDefinition<{ url: string }>()("SOME_EVENT");

// Create bus
const bus = new EventBus();

// Subscribe
bus.subscribe(someEvent, event => {
  alert(event.payload.url);
});

// Publish
bus.publish(someEvent({ url: "https://github.com" }));

Rationale

We want to write loosely coupled highly cohesive applications and one of the best and easiest ways to do that is to use an event bus as a management layer for our applications.

This is the kind of thing that you could use effectively in most applications.

For my purposes I wanted a system that:

• Is framework agnostic can support Vue, React or Angular.
• Could enable micro-frontends / microlithic architecture.
• Can easily use React hooks to reduce state in the case of React.
• Does not conflate eventing with state management.
• Has really good TypeScript support.

Alternatives

• Redux - conflates state management with eventing and causes complexity around async as a result. Redux has a highly invasive syntax that is difficult to remove or abstract out of an application. React comes with state management out of the box these days anyway. See my article "Life after Redux"
• RxJS - could make a great event bus but feels too heavy handed for use with many projects.
• Node events - is a little too much API for what I need here. This lib actually decorates the EventEmitter2 package. In the future I may remove it to become dependency free.

Installation

Use your favourite npm client to install ts-bus. Types are included automatically.

Npm:

npm install ts-bus

Yarn:

yarn add ts-bus

Example applications

To explore an example of ts-bs used in context pease see the KanBan example.

Usage

Create a bus

Create your EventBus globally somewhere:

// bus.ts
import { EventBus } from "ts-bus";
export const bus = new EventBus();

Declare events

Next create some Events:

// events.ts
import { createEventDefinition } from "ts-bus";

export const taskCreated = createEventDefinition<{
  id: string;
  listId: string;
  value: string;
}>()("task.created");

export const taskLabelUpdated = createEventDefinition<{
  id: string;
  label: string;
}>()("task.label.updated");

Notice createEventDefinition() will often be called with out a runtime check argument and it returns a function that accepts the event type as an argument. Whilst possibly a tiny bit awkward, this is done because it is the only way we can allow effective discriminated unions. See switching on events.

Runtime payload checking

You can also provide a predicate to do runtime payload type checking in development. This is useful as a sanity check if you are working in JavaScript:

import p from "pdsl";

// pdsl creates predicate functions
const isLabel = p`{
  id: string,
  label: string,
}`;

export const taskLabelUpdated = createEventDefinition(isLabel)(
  "task.label.updated"
);

taskLabelUpdated({ id: "abc" }); // {"id":"abc"} does not match expected payload.

These warnings are suppressed in production.

Subscribing

import { taskLabelUpdated, taskCreated } from "./event";
import { bus } from "./bus";

// You can subscribe using the event creator function
bus.subscribe(taskLabelUpdated, event => {
  const { id, label } = event.payload; // Event is typed
  doSomethingWithLabelAndId({ id, label });
});

Unsubscribing

To unsubscribe from an event use the returned unsubscribe function.

const unsubscribe = bus.subscribe(taskLabelUpdated, event => {
  // ...
});

unsubscribe(); // removes event subscription

Subscribing with a type string

You can use the event type to subscribe.

bus.subscribe("task.created", event => {
  // ...
});

Or you can use wildcards:

bus.subscribe("task.**", event => {
  // ...
});

Subscribing with a predicate function

You can also subscribe using a predicate function to filter events.

// A predicate
function isSpecialEvent(event) {
  return event.payload && event.payload.special;
}

bus.subscribe(isSpecialEvent, event => {
  // ...
});

You may find pdsl a good fit for creating predicates.

Subscription syntax

As you can see above you can subscribe to events by using the subscribe method of the bus.

const unsubscriber = bus.subscribe(<string|eventCreator|predicate>, handler);

This subscription function can accept a few different options for the first argument:

• A string that is the specific event type or a wildcard selector eg. mything.**.
• An eventCreator function returned from createEventDefinition<PayloadType>()("myEvent")
• A predicate function that will only subscribe to events that match the predicate. Note the predicate function matches the entire event object not just the payload. Eg. {type:'foo', payload:'foo'}

The returned unsubscribe() method will unsubscribe the specific event from the bus.

Publishing events

Now let's publish our events somewhere

// publisher.ts
import { taskLabelUpdated, taskCreated } from "./events";
import { bus } from "./bus";

function handleUpdateButtonClicked() {
  bus.publish(taskLabelUpdated({ id: "638", label: "This is an event" }));
}

function handleDishesButtonClicked() {
  bus.publish(
    taskCreated({ id: "123", listId: "345", value: "Do the dishes" })
  );
}

Using a plain event object

If you want to avoid the direct dependency with your event creator you can use the plain event object:

bus.publish({
  type: "kickoff.some.process",
  payload: props.data
});

Republishing events

Lets say you have received a remote event from a websocket and you need to prevent it from being automatically redispatched you can provide custom metadata with each publication of an event to prevent re-emmission of events over the socket.

import p from "pdsl";

// get an event from a socket
socket.on("event-sync", (event: BusEvent<any>) => {
  bus.publish(event, { remote: true });
});

// This is a shorthand utility that creates predicate functions to match based on a given object shape.
// For more details see https://github.com/ryardley/pdsl
const isSharedAndNotRemoteFn = p`{
  type: ${/^shared\./},
  meta: {
    remote: !true
  }
}`;

// Prevent sending a event-sync if the event was remote
bus.subscribe(isSharedAndNotRemoteFn, event => {
  socket.emit("event-sync", event);
});

Switching on Events and Discriminated Unions

// This function creates foo events
const fooCreator = createEventDefinition<{
  foo: string;
}>()("shared.foo");

// This function creates bar events
const barCreator = createEventDefinition<{
  bar: string;
}>()("shared.bar");

// Create a union type to represent your app events
type AppEvent = ReturnType<typeof fooCreator> | ReturnType<typeof barCreator>;

bus.subscribe("shared.**", (event: AppEvent) => {
  switch (event.type) {
    case String(fooCreator):
      // compiler is happy about payload having a foo property
      alert(event.payload.foo.toLowerCase());
      break;
    case String(barCreator):
      // compiler is happy about payload having a bar property
      alert(event.payload.bar.toLowerCase());
      break;
    default:
  }
});

Wildcard syntax

You can namespace your events using period delimeters. For example:

"foo.*" matches "foo.bar"
"foo.*.thing" matches "foo.fing.thing"
"**" matches everything eg "foo" or "foo.bar.baz"
"*" matches everything within a single namespace eg. "foo" but not "foo.bar"

This is inherited directly from EventEmitter2 which ts-bus currently uses under the hood.

React extensions

Included with ts-bus are some React hooks and helpers that provide a bus context as well as facilitate state management within React.

BusProvider

Wrap your app using the BusProvider

import React from "react";
import App from "./App";

import { EventBus } from "ts-bus";
import { BusProvider } from "ts-bus/react";

// global bus
const bus = new EventBus();

// This wraps React Context and passes the bus to the `useBus` hook.
export default () => (
  <BusProvider value={bus}>
    <App />
  </BusProvider>
);

useBus

Access the bus instance with useBus

// Dispatch from deep in your application somewhere...
import { useBus } from "ts-bus/react";
import { kickoffSomeProcess } from "./my-events";

function ProcessButton(props) {
  // Get the bus passed in from the top of the tree
  const bus = useBus();

  const handleClick = React.useCallback(() => {
    // Fire the event
    bus.publish(kickoffSomeProcess(props.data));
  }, [bus]);

  return <Button onClick={handleClick}>Go</Button>;
}

useBusReducer

This connects state changes to bus events via a state reducer function.

Its signature is similar to useReducer except that it returns the state object instead of an array:

Example:

function init(initCount: number) {
  return { count: initCount };
}
const state = useBusReducer(reducer, initCount, init);

import { useBus, useBusReducer } from "ts-bus/react";

const initialState = { count: 0 };

function reducer(state, event) {
  switch (event.type) {
    case "counter.increment":
      return { count: state.count + 1 };
    case "counter.decrement":
      return { count: state.count - 1 };
    default:
      throw new Error();
  }
}

function Counter() {
  const bus = useBus();
  const state = useBusReducer(reducer, initialState);
  return (
    <>
      Count: {state.count}
      <button onClick={() => bus.publish({ type: "counter.increment" })}>
        +
      </button>
      <button onClick={() => bus.publish({ type: "counter.decrement" })}>
        -
      </button>
    </>
  );
}

useBusReducer configuration

You can configure useBusReducer with a subscriber passing in an options object.

// get a new useReducer function
const useReducer = useBusReducer.configure({
  subscriber: (dispatch, bus) => {
    bus.subscribe("count.**", dispatch);
  }

  /* 
  The boilerplate code can be reduced by using the reducerSubscriber function.
  subscriber: reducerSubscriber("count.**")
  */

});

const state = useReducer(/*...*/);

Available options:

Option	Description
subscriber	reducer subscriber definition

useBusState

This connects state changes to bus events via a useState equivalent function.

import { useBus, useBusState } from "ts-bus/react";

const setCountEvent = createEventDefinition<number>()("SET_COUNT");

function Counter() {
  const bus = useBus();
  const count = useBusState(0, setCountEvent);

  return (
    <>
      Count: {count}
      <button onClick={() => bus.publish(setCountEvent(count + 1))}>+</button>
      <button onClick={() => bus.publish(setCountEvent(count - 1))}>-</button>
    </>
  );
}

useBusState configuration

You can configure useBusState with a subscriber passing in an options object.

// get a new useState function
const useState = useBusState.configure({
    subscriber: (dispatch, bus) => bus.subscribe("**", (ev) => dispatch(ev.payload))
    
    /* 
    The boilerplate code can be reduced by using the stateSubscriber function.
    subscriber: stateSubscriber("**")
    */
});

const state = useState(/*...*/);

Available options:

Option	Description
subscriber	State subscriber definition