Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jcalixte/retrobus
An event bus system that allows listener to be retroactive
https://github.com/jcalixte/retrobus
Last synced: about 2 months ago
JSON representation
An event bus system that allows listener to be retroactive
- Host: GitHub
- URL: https://github.com/jcalixte/retrobus
- Owner: jcalixte
- Created: 2020-07-26T08:54:50.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-06-26T08:56:49.000Z (7 months ago)
- Last Synced: 2024-10-30T14:18:29.779Z (2 months ago)
- Language: TypeScript
- Homepage:
- Size: 881 KB
- Stars: 9
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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:
```sh
npm install retrobus
```
yarn:
```sh
yarn add retrobus
```
pnpm:
```sh
pnpm add retrobus
```
# Usage
`Retrobus` implements 4 methods:
## Emit an event
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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:
```ts
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' })
```
```ts
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
```vue
Greetings!
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')
}
}
}
```
### React
```jsx
import { addEventBusListener, emit } from 'retrobus'
const HelloWorld = () => {
useEffect(() => {
const greetings = () => console.log('Hello World')
return addEventBusListener('log', greetings)
}, [])
return emit('log')}>Greetings!
}
```
### Angular
```ts
// 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')
}
}
```
```html
Greetings!
```
## Credits
Logo created with [Tabler Icons](https://tablericons.com/).