webreflection/broadcast

Notification channel for the past, the present, and the future.

broadcast

Previously known as notify-js, broadcast is a private or public notification chanel inspired by standards.

Useful for loaders, components bootstrap, geo position updates, and all other asynchronous or on demand user granted privileges operations, broadcast works on every browser and every platform, it's 100% tests covered, and it weights about 0.3K.

V4 Release

• Breaking
  • removed new method; the export now is broadcast and the Broadcast class
  • changed when signature; it now always returns a Promise
  • no transpilation anymore, usable by ES2015+ compatible engines
• New
  • smaller
  • faster
  • better
  • stronger

API

• .all(type:any, callback:Function):void to be notified every time a specific type changes (i.e. each .that(type, value) call in the future).
• .drop(type:any[, callback:Function]):void remove a specific callback from all future changes. If the callback is omitted, it removes type from the internal Map (drop all callbacks and value).
• .that(type:any[, value:any]):Function|void broadcast to all callbacks and resolves all promises with value. If omitted, it returns a callback that will broadcast, once invoked, the received value (i.e. thing.addListener(any, broadcast.that(type))).
• .when(type:any):Promise returns a Promise that will resolve once type is known.

Examples

import {broadcast} from 'broadcast';

// as Promise,
//  inspired by customRegistry.whenDefined(...).then(...)
// will you ever ask for a geo position or
// have you asked for it already ?
broadcast.when('geo:position').then(info => {
  showOnMap(info.coords);
});

// as one-off Event (Promise or Callback)
broadcast
  .when('dom:DOMContentLoaded')
  .then(boostrapMyApp);

It doesn't matter if a channel was resolved, updated, or never asked for, whenever that happens, broadcasts will follow.

// that position? only once asked for it
navigator.geolocation.getCurrentPosition(info => {
  // manual broadcast
  broadcast.that('geo:position', info);
});

// update the position each change? same
navigator.geolocation.watchPosition(
  // implicit broadcast once executed
  broadcast.that('geo:position')
);

// the file? You got it.
fs.readFile(
  'README.md',
  // will broadcast once executed
  (err, data) => broadcast.that('fs:README.md', err || data)
);

// top of the page
document.addEventListener(
  'DOMContentLoaded',
  broadcast.that('dom:DOMContentLoaded')
);

one broadcast VS all broadcasts

A broadcast happens only once asked for it, and it will receive the latest resolution.

If you'd like to listen to all broadcasted changes, you can use broadcast.all(type, callback), and eventually stop listening to it via broadcast.drop(type, callback).

let watchId;

function updatePosition(info) {
  mapTracker.setCoords(info.coords);
}

button.addEventListener('click', e => {
  if (watchId) {
    navigator.geolocation.clearWatch(watcher);
    watchId = 0;
    broadcast.drop('geo:position', updatePosition);
  } else {
    watchId = navigator.geolocation.watchPosition(
      // updates the latest position info on each call
      broadcast.that('geo:position')
    );
    broadcast.all('geo:position', updatePosition);
  }
});

private broadcasts

There are two different ways to have a private broadcasts:

• using a secret type as channel, like in broadcast.when(privateSymbol)
• create an instance a part via import {Broadcast} from 'broadcast'; and const bc = new Broadcast;

The first way enables shared, yet private, resolutions while the second one would be unreachable outside its scope.