npm package: @foundit/broadcasterjs
Description: A simple yet powerful pub/sub pattern javascript event bus
Author: Nicolas Hervy
Latest version: 1.2.0

# broadcasterjs

#### A simple yet powerful pub/sub javascript event bus

- easy to use
- framework agnostic
- minimal footprint
- optimised for SPA applications
- unintrusive as a dependency
- no own dependencies

- Here you can [report issues or contribute](https://github.com/nicatspark/broadcasterjs)
- [Demo app available](http://broadcasterjs.hervy.se)
- [Source code of the demo app](https://github.com/nicatspark/broadcasterjs-demo-app)

---

### Usage

No need to initialize separately. Import the 'broadcast' factory function and use to your hearts content.

`npm install @foundit/broadcasterjs`

`import { broadcast } from '@foundit/broadcasterjs'`

##### START A SUBSCRIPTION IN A REACT COMPONENT

```typescript
useEffect(() => {
  return broadcast.on(['MYBROADCAST-ID', myFlagEmittedCallbackFunction])
}, [myFlagEmittedCallbackFunction])
```

`broadcast.on()` returns a unsubscribe function which comes in handy when you want to cleanup on component unmount. If your listener handler function does not depend on the React component it is instanciated, in you can of course omit the `return` to make it persist.

##### START SUBSCRIPTION VANILLA JS

`.on` - start a subscription.

```typescript
const off() = broadcast.on([
  'MYBROADCAST-ID',
  ({ detail }) => {
    document.body.append(detail + ' ')
  },
])
```

`.once` - start a subscription but cancel subscription after first emission.

```typescript
const off() = broadcast.once([
  'MYBROADCAST-ID',
  ({ detail }) => {
    document.body.append(detail + ' ')
  },
])
```

##### END SUBSCRIPTION

Call the return function to cancel a subscription.

```typescript
off() // Use the subscribers return function.
```

##### PUBLISH IN REACT & VANILLLA JS (place anywhere)

Publish (emit) an event with a string payload.

```typescript
broadcast.emit('MYBROADCAST-ID', 'Hello world')
```

##### TO VISUALLY INSPECT

- Click elements tab i chrome devtools,
- Select event-listeners tab in second pane.
- Active listeners begin with 'broadcast-' + flag name in uppercase. Expand each listener to see each unique subscriber.

##### TO DEBUG

Add `?debug=broadcasterjs` to your url and open your devtools console. Normally it shold be enough with inspecting comment node as described above.

##### ADVANCED

The broadcaster functions `on`,`once` takes an optional third value and `emit` takes an optional third argument in the form of a settings object.

```typescript
{
  debug: boolean (false)
  debugGlobal: boolean (false)
  allowDoublettesSubscribers: boolean (false)
  useLatestSubscriberScope?: boolean (false) // <- internal use
  suppresDebug?: boolean (false) // <- internal use
}
```

---

##### Change log

**v 1.1.2** The common js version was not previously updated and did not return the unsubscribe function. It would then still behave as pre v1.1.0.
**v 1.1.1**
**v 1.1.0** The subscribe functions 'on' and 'once' now return a unsubscribe function (no arguments) that is much more user friendly than the previous off function. 'off' is still available but removed from the documentation.

##### Commands

Develop: `yarn start`
Compile typescript: `tsc`
Build out esm/cjs dist: `npm run build`
Publish to npm: `npm publish --access=public`