README.md

Retro Bus

Retrobus is a simple event bus for your JavaScript/TypeScript application.

Features

• Trigger callback even if the listener is added after the event was first emitted with the property retro,
• JavaScript / TypeScript,
• Framework agnostic,
• 0 dependencies.

Installation

npm:

npm install retrobus

yarn:

yarn add retrobus

pnpm:

pnpm add retrobus

Usage

Retrobus implements 4 methods:

Emit an event

import { emit } from 'retrobus'

emit('authenticated', {
  isUserAuthenticated: true
})

emit takes any additionnal parameters after the name. Theses parameters will be passed to the listener callbacks.

Listen to an event

import { addEventBusListener } from 'retrobus'

const fetchUserProfile = ({ isUserAuthenticated }) => {
  if (isUserAuthenticated) {
    console.log('user is authenticated!')
  }
}

addEventBusListener('authenticated', fetchUserProfile, {
  once: true,
  retro: true
})

addEventBusListener has multiple options that allow you to configure the listener's behavior:

name	type	default	description
retro	boolean	false	call retroactively the callback if the event was emitted before the listener
retroStrategy	'last-one' | 'all'	'last-one'	Define the strategy when calling previous emitted events. If retroStrategy is set to all, every emitted events will be called, from oldest to newest. If retroStrategy is set to last-one, only the last emitted event will be retractively called. Default to last-one. Ignored if retro is false.
once	boolean	false	remove the callback right after beeing called. If retro is true and if the event was previously emitted, the callback is directly called then removed.
unique	boolean	false	make sure the callback is only added once

addEventBusListener returns a callback to directly unsubscribe the listener added.

Remove a listener

import { addEventBusListener, removeEventBusListener } from 'retrobus'

const fetchUserProfile = ({ isUserAuthenticated }) => {
  if (isUserAuthenticated) {
    console.log('user is authenticated!')
  }
}

addEventBusListener('authenticated', fetchUserProfile, {
  once: true,
  retro: true,
  unique: true
})

removeEventBusListener('authenticated', fetchUserProfile)

Clear listeners

import { addEventBusListener, clearEventBusListeners } from 'retrobus'

const fetchUserProfile = ({ isUserAuthenticated }) => {
  if (isUserAuthenticated) {
    console.log('user is authenticated!')
  }
}

addEventBusListener('authenticated', fetchUserProfile, {
  once: true,
  retro: true
})

clearEventBusListeners('authenticated')
clearEventBusListeners() // clear all event listeners

Clear emitted events

With clearEmittedEvents(name), you can clear all the events from a specific key already emitted. If there is no parameter when calling the function, then all the emitted events are cleared.

Create an event bus

import { createEventBus } from 'retrobus'

const eventBus = createEventBus<{ a: string; b: string }>('authentication')

eventBus.addEventBusListener((payload) => {
  console.log(payload.a, payload.b)
})

eventBus.emit({ a: 'Hello', b: 'World' })

event name can be defined with strings or Symbols

These 2 implementations work:

import { createEventBus } from 'retrobus'

const eventBus = createEventBus<{ a: string; b: string }>() // default to Symbol()

eventBus.addEventBusListener((payload) => {
  console.log(payload.a, payload.b)
})

eventBus.emit({ a: 'Hello', b: 'World' })

import { createEventBus } from 'retrobus'

const eventName = Symbol('authentication')

const eventBus = createEventBus<{ a: string; b: string }>(eventName)

eventBus.addEventBusListener((payload) => {
  console.log(payload.a, payload.b)
})

eventBus.emit({ a: 'Hello', b: 'World' })

Add event listener examples with framework

VueJS

<template>
  <button @click="log">Greetings!</button>
</template>

<script>
import { addEventBusListener, emit, removeEventBusListener } from 'retrobus'

export default {
  name: 'HelloWorld',
  mounted() {
    addEventBusListener('log', this.greetings)
  },
  beforeDestroy() {
    removeEventBusListener('log', this.greetings)
  },
  methods: {
    greetings() {
      console.log('Hello world!')
    },
    log() {
      emit('log')
    }
  }
}
</script>

React

import { addEventBusListener, emit } from 'retrobus'

const HelloWorld = () => {
  useEffect(() => {
    const greetings = () => console.log('Hello World')

    return addEventBusListener('log', greetings)
  }, [])

  return <button onClick={() => emit('log')}>Greetings!</button>
}

Angular

// content.component.ts
import { Component, OnDestroy } from '@angular/core'
import { addEventBusListener, emit, removeEventBusListener } from 'retrobus'

@Component({
  selector: 'app-content',
  templateUrl: 'content.component.html',
  styleUrls: ['content.component.scss']
})
export class ContentComponent implements OnDestroy {
  constructor() {
    addEventBusListener('log', this.greetings)
  }

  ngOnDestroy() {
    removeEventBusListener('log', this.greetings)
  }

  greetings() {
    console.log('Hello World')
  }

  log() {
    emit('log')
  }
}

<!-- content.component.html -->
<button (click)="log()">Greetings!</button>

Credits

Logo created with Tabler Icons.