npm package: @shuzhong/vue-event-bus
Description: A light weight vue event bus
Author: Shu Zhong
Latest version: 1.1.3

#+TITLE: @shuzhong/vue-event-bus
#+AUTHOR: ShuZhong
#+EMAIL: zhongshuyx@sina.com

Read this in other languages: [[README.zh.org][简体中文]] [[README.org][English]]

* Feature
1. Optional =strict= mode, only accept predefined =events=
2. Auto remove event listeners (include anonymous function) in Vue beforeDestroy hook
3. Event param can be =string | string[]=, on/off/fire multiple events
4. Bind =this= to target Vue component

* Install
#+BEGIN_SRC shell-script
npm install --save @shuzhong/vue-event-bus
#+END_SRC

* Setup

*commonjs*
#+BEGIN_SRC js
var VueEventBus = require('@shuzhong/vue-event-bus')

Vue.use(VueEventBus) // default options
// or
Vue.use(VueEventBus, {
    events: ['EVENT-NAME-1', 'EVENT-NAME-2', 'EVENT-NAME-3'],
    strict: true
})
#+END_SRC

*ES2015+*
#+BEGIN_SRC js
import VueEventBus from '@shuzhong/vue-event-bus'

Vue.use(VueEventBus) // default options
// or
Vue.use(VueEventBus, {
    events: ['EVENT-NAME-1', 'EVENT-NAME-2', 'EVENT-NAME-3'],
    strict: true
})
#+END_SRC

*External*
#+BEGIN_SRC html
<script type="text/javascript" src="your-folder-path/vue-event-bus.min.js"></script>
<script type="text/javascript">
  Vue.use(VueEventBus) // default options
  // or
  Vue.use(VueEventBus, {
      events: ['EVENT-NAME-1', 'EVENT-NAME-2', 'EVENT-NAME-3'],
      strict: true
  })
</script>
#+END_SRC

* Usage

*CompOne.vue*
#+BEGIN_SRC javascript
// .............
mounted() {
    // Because this bind to CompOne, The next 4 this points to the same context
    this.$busOn('EVENT_1', () => { console.log(this, '11') }) // Bind by ES6 arrow function
    this.$busOn('EVENT_2', function() { console.log(this, '12') }) // Bind by VueEventBus
    this.$busOnce('EVENT_3', () => { console.log(this, '13') }) // Bind by ES6 arrow function
    this.$busOn('EVENT_4', this.busOnFunc1) // Bind by Vue (Vue Methods auto bind this)

    // listen multiple events
    this.$busOn(['EVENT_1', 'EVENT_2', 'EVENT_3'], function() { })
},

beforeDestroy() {
    this.$busOff('EVENT_4', this.busOnFunc1)

    // Destory multiple events (Clear all listeners for this event when the second argument is not passed)
    this.$busOff(['EVENT_1', 'EVENT_2', 'EVENT_3'])
},

methods: {
    busOnFunc1() { console.log(this, '14') }
}
// ...........
#+END_SRC

*CompTwo.vue*
#+BEGIN_SRC javascript
this.$busFire('EVENT_1', 'arg1', 'arg2', [1, 2, 3, 4])

// Trigger multiple events in sequence
this.$busFire(['EVENT_1', 'EVENT_2', 'EVENT_3', 'EVENT_4'])
this.$busFire(['EVENT_1', 'EVENT_2', 'EVENT_3', 'EVENT_4'], 'arg1', 'arg2', [1, 2, 3, 4])
#+END_SRC

* API
** Install option
#+BEGIN_SRC typescript
type Options = {
    strict: boolean
    events: string[]
}

Vue.use(VueEventBus, options?: Options = { strict: false, events: [] })
#+END_SRC

options:
+ *strict: { type: boolean, default: false }*
+ *events: { type: string[], default: [] }*

When =strict= is =true=, only event declared in =events= are legal. If an undeclared event is on/off/fire, an error is thrown.

** Listen event
#+BEGIN_SRC typescript
this.$busOn(evTag: string | string[], evFunc: Function)
this.$busOnce(evTag: string | string[], evFunc: Function)
#+END_SRC

** Remove event
#+BEGIN_SRC typescript
this.$busOff(evTag: string | string[], evFunc?: Function)
#+END_SRC

Clear all event listeners corresponding to =evTag= when the =evFunc= param is not passed.

** Fire event
#+BEGIN_SRC typescript
this.$busFire(evTag: string | string[], ...args: any[])
#+END_SRC
* License
MIT