dannyfranca/radarjs

Modern and Robust Event Emitter, with tagging, emitting and broadcasting. Internally uses Promises and RxJS Subjects.

Install

Module

Download

npm i radarjs

Import

import { Radar } from '@dannyfranca/radarjs'

const radar = new Radar()

CDN

<script src="unpkg.com/radarjs"></script>

<!-- Specific Version -->
<script src="unpkg.com/radarjs@0.3.0/lib/radar.umd.js"></script>

Usage

Listen for Events

const state = {
  count: 0,
  lastNotificationType: ''
}

radar.on('notify', () => state.count++)

// receive any number off values as arguments
radar.on('notify', ({ type }, ...data) => {
  state.lastNotificationType = type)
  console.log(data)
}

// can use namespaces
radar.on('notify.namespace1.namespace2', (...data) => {/*...*/})

Unsubscribe from Events

// by event name
radar.off('notify')

// by namespace
radar.off('.namespace1')

// by Subscription
const subscribeThenUnsubscribe = async () => {
  const subscription = await radar.on('event', (...data) => {/*...*/})
  subscription.unsubscribe()
}

subscribeThenUnsubscribe()

// by Subscription (sync)
const subscription = await radar.onSync('event', (...data) => {/*...*/})
subscription.unsubscribe()

Trigger Events

// pass any data to an event trigger
radar.trigger('notify', {
  type: 'info',
  message: 'Just an ordinary notification'
})

// pass any number of data
radar.trigger('notify', notification, ...data)

MultiLevel Events

// set child event
radar.link('grandparent', 'parent')
radar.link('parent', 'child')

// destroy link
radar.unlink('parent', 'child')

// broadcast events down to the whole tree just like trigger
// will trigger grandparent, parent and child
radar.broadcast('grandparent', ...data)

// will trigger parent and child
radar.broadcast('parent', ...data)

// emit events up to the whole tree just like trigger
// will trigger child, parent and grandparent
radar.emit('child', ...data)

// will trigger only grandparent
radar.emit('grandparent', ...data)

Sync Variants

Every public methods returns Promises, but each one has a sync variant, with same syntax.

radar.on('event', ...data) // returns Promise<Subscription>
radar.onSync('event', ...data) // returns Subscription
radar.trigger('event', ...data) // returns Promise<void>
radar.triggerSync('event', ...data) // returns void
// and so on...

MultiTriggering

To trigger/emit/broadcast many events with same data, you can use arrays of strings or a single string with event names separated by dots. Each event name is resolved by a glob pattern (powered by micromatch)!

// will trigger "foo" and "bar", sending same datas
radar.trigger('foo.bar', ...data)
// same as
radar.trigger(['foo', 'bar'], ...data)


// with micromatch
radar.on('foo', () => {/*...*/})
radar.on('bar', () => {/*...*/})
radar.on('baz', () => {/*...*/})
radar.on('boom', () => {/*...*/})

// will trigger "bar" and "baz"
radar.trigger('ba*', ...data) 
// will trigger "boom"
radar.trigger('b*m', ...data)

// many micromatches allowed!
// will trigger "bar", "baz" and  "boom"
radar.triggerMany('ba*.bo*', ...data)
radar.triggerMany(['ba*', 'bo*'], ...data)

See all glob possibilities in micromatch

Auto Link

You can autolink with ":" character

radar.on('event:frag1:frag2', () => {/*...*/})

// will fire "event", "event:frag1" and "event:frag1:frag2" events
radar.broadcast('event', ...data)

// will fire "event:frag1" and "event" events
radar.emit('event:frag1', ...data)

// ATTENTION: will fire just frag1.
// frag1 and frag2 is not supposed to be events,
// just words appended to eventNames
radar.broadcast('frag1', ...data)

Native Events

Native events has reserved names starting with $. Until now, the only native event available is $error.

$error event

// listening to $error
radar.on('$error', (error: Error) => {/*...*/})

Radarjs default error handler is:

(error: Error) => { throw error }

You can set yout own:

// set your error handler
radar.setErrorHandler((error: Error) => {/*...*/})

License

MIT