retrobus
TypeScript icon, indicating that this package has built-in type declarations

1.9.3 • Public • Published

logo

npm npm

npm bundle size

travis coveralls

BCH compliance

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.

Package Sidebar

Install

npm i retrobus

Weekly Downloads

407

Version

1.9.3

License

MIT

Unpacked Size

44.9 kB

Total Files

15

Last publish

Collaborators

  • julienc6