Nobody Peels Mangoes

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

    1.2.3 • Public • Published

    Estacion

    CircleCI Codecov NPM

    Implementation of the event bus pattern via node EventEmitter class.

    It can be used in the browser via events module which is automatically included by the bundlers like webpack and browserify.

    How it works

    Event bus is compromised of channels, channels have topics. Events are dispatched on via channels or via topics. If you subscribe to the channel you will receive events from all the topics on the channel.

    If you subscribe to the topic, you will receive events that are emitted only via that particular topic.

    Installation

    npm install estacion

    Example

    const { EventBus } = require('estacion')
    
    // or import { EventBus } from 'estacion'
    
    // create event bus
    const bus = new EventBus()
    
    // create channels
    const usersChannel = bus.channel('users')
    const gamesChannel = bus.channel('games')
    
    // create topics for the channel (optional)
    const userAdded = usersChannel.topic('user_added')
    const userRemoved = usersChannel.topic('user_removed')
    
    // create topics for the channel (optional)
    const gameStart = gamesChannel.topic('game_start')
    const gameEnd = gamesChannel.topic('game_end')
    
    // create listener
    const listener = event => {
      console.log(event.channel)
      console.log(event.topic)
      console.log(event.payload) // custom payload from the event
    }
    
    // add listener to the channel
    usersChannel.addListener(listener)
    
    // or add listener to the channel topic
    userAdded.addListener(listener)
    
    // advanced
    // subscribe to all channels and topics (more in the docs)
    bus.mainChannel().addListener(listener)
    
    // advanced
    // subscribe to all channels but only for a particular topic
    // now you will listen to 'game_end' on any channel
    bus
      .mainChannel()
      .topic('game_end')
      .addListener(listener)
    
    // emit event on the channel
    const customPayload = {} // whatever you like
    usersChannel.emit(customPayload)
    
    // or emit event on the topic
    userAdded.emit({ name: 'Sam', lastName: 'Fisher' })

    skip to mainChannel explanation example on runkit

    Setup is really simple:

    1. EventBus holds channels.
    2. Channels hold topics.
    3. Add listeners to channels or topics.

    EventBus

    EventBus is used for creating and removing channels. You can create any number of channels.

    EventBus is not a singleton, you can create any number of EventBus instances.

    const eventBus = new EventBus()
    
    // create new channel or return existing channel with that name
    const channel = eventBus.channel('nbc')
    
    // remove channel
    // all listeners will be automatically unsubscribed
    const eventBus.removeChannel('nbc')

    Channel

    Channel can create and remove topics. You can add listeners directly to the channel or you can add listeners to the particular topic. When you add a listener to the channel directly, you will be notified for all events that are dispatched via topics for that channel, and also when the channel itself emits ( event.topic will be set to '*' ).

    // create event bus
    const eventBus = new EventBus()
    
    // create new channel or return existing channel with that name
    const channel = eventBus.channel('nbc')
    
    // create topics on the channel
    const economyTopic = channel.topic('economy')
    const sportsTopic = channel.topic('sports')
    
    // listen to all topics ( addListener directly to the channel)
    const listener = event => {
      console.log(event.channel) // 'nbc'
      console.log(event.topic) // 'economy' or 'sports' or '*'
      console.log(event.payload) // custom data from the topics
    }
    
    channel.addListener(listener)
    
    economyTopic.addListener(event => {
      console.log(event.channel) // 'nbc'
      console.log(event.topic) // 'economy'
      console.log(event.payload) // custom data from 'economy' topic
    })
    
    //remove all listeners from the channel ( including listeners on all topics)
    channel.removeAllListeners()
    // or particular listener
    channel.removeListener(listener)

    Topic

    Topic is the smallest building block of the event bus system. You can only create topics via channels.

    // create event bus
    const eventBus = new EventBus()
    
    // create new channel or return existing channel with that name
    const channel = eventBus.channel('nbc')
    
    // create topics on the channel
    const ecologyTopic = channel.topic('ecology')
    
    const listener = event => {
      console.log(event.channel) // 'nbc'
      console.log(event.topic) // 'ecology'
      console.log(event.payload.title) // 'Climate change is real'
      console.log(event.payload.content) // 'Lorem ipsum'
    }
    
    // listen to 'ecology' topic
    ecologyTopic.addListener(listener)
    
    // emit data
    ecologyTopic.emit({ title: 'Climate change is real.', content: 'Lorem ipsum' })
    
    channel.removeTopic('ecology') //all listeners will be automatically removed
    
    // or remove listener directly from the topic
    ecologyTopic.removeListener(listener)

    Subscribe

    Channel and Topic classes both inherit from the Broadcaster class, which wraps the native EventEmitter and exposes some of its methods. You can subscribe to the channel or topic via these methods:

    const listener = event => {}
    channelOrTopic.addListener(listener)
    channelOrTopic.on(listener) // alias for addListener
    channelOrTopic.prependListener(listener) // be first to be notified
    channelOrTopic.once(listener) // fire only once
    channelOrTopic.prependOnceListener(listener) // be first to be notified only once

    Listener function accepts one parameterEventPayload .

    type Listener = (event: EventPayload) => void
    /**
     * Payload interface that is emited from the events
     */
    interface EventPayload {
      /**
       * Channel name.
       *
       * @type {string}
       */
      channel: string
      /**
       * Topic name.
       *
       * @type {string}
       */
      topic: string
      /**
       * Payload - custom data to pass to the listeners
       *
       * @type {*}
       */
      readonly payload?: any | undefined
    }

    Unsubscribe

    Every one of the subscribe function variations returns a function to unsubscribe from the channel or topic

    const listener = event => {}
    const unsubscribe = channelOrTopic.addListener(listener)
    unsubscribe() // unsubscribe from the channel or topic

    Or you can use one of the methods on channel or topic

    const listener = event => {}
    channelOrTopic.removeListener(listener)
    channelOrTopic.off(listener) // alias for removeListener

    Remove all listeners from the channel or topic:

    channelOrTopic.removeAllListeners()

    Also by destroying channel or topic, all listeners will be automatically unsubscribed. When destroying channel all topics in that channel will also be destroyed.

    const eventBus = new EventBus()
    
    // create new channel or return existing channel with that name
    const channel = eventBus.channel('nbc')
    
    // create topics on the channel
    const ecologyTopic = channel.topic('ecology')
    
    channel.addListener(event => {})
    ecologyTopic.addListener(event => {})
    
    // all listeners will be removed
    channel.destroy()
    
    // no need to call for this
    ecologyTopic.destory()

    EventBus main channel

    There is a special channel on the EventBus that is created automatically with every EventBus instance. This special channel is used for listening to all other channels via just one subscribe call.

    const eventBus = new EventBus()
    
    const channelOne = eventBus.channel('one')
    const channelTwo = eventBus.channel('two')
    
    channelOne.emit({ name: 'Sam' })
    channelTwo.emit({ name: 'Jack' })
    
    const mainChannel = eventBus().mainChannel()
    
    //subcribe to all channels and all topics
    mainChannel.addListener(event => {
      console.log(event.channel) // 'one' or 'two'
      console.log(event.topic) // any topic from  channels 'one' or 'two'
      console.log(event.payload) // {name: 'Sam'} or {name: 'Jack'}
    })

    You can also subscribe to the particular topics that are emitted from any channel. In the next example, you will subscribe to the 'economy' topic on any channel and nothing else.

    const eventBus = new EventBus()
    
    const channelOne = eventBus.channel('cnn')
    const channelTwo = eventBus.channel('nbc')
    
    channelOne.topic('economy').emit()
    channelTwo.topic('economy').emit()
    
    const mainChannel = eventBus().mainChannel()
    
    //subcribe to all channels but only 'economy` topic
    mainChannel.topic('economy').addListener(event => {
      console.log(event.channel) // 'one' or 'two
      console.log(event.topic) // 'economy' from both channels
    })

    API docs

    Estacion is written in TypeScript, auto generated API docs are available.

    Author

    • Ivan Vlatković
    License

    This project is licensed under the MIT License - see the LICENSE file for details

    Acknowledgments

    Install

    npm i estacion

    DownloadsWeekly Downloads

    340

    Version

    1.2.3

    License

    MIT

    Unpacked Size

    60 kB

    Total Files

    23

    Last publish

    Collaborators

    • ivandotv