Dispatcher

// @namespace Context.Dispatcher
import { Context } from 'rcfm'
const Dispatcher = Context.Dispatcher

@typedef {Object} DispatcherInstance
@description - 订阅器实例

@typedef {Object} DispatcherEvent
@description - 订阅器事件

@prop {string} type - 事件类型
@prop {*} target - 触发目标
@prop {*} detail - 事件携带的数据

// Dispatcher.create(options)
// @param {Object} [options = {}]
// @prop {Function} [options.target = function(id) { return id }] - 一个用于查找触发目标的自定义函数
// @returns {DispatcherInstance}

// @example
const dispatcher = Dispatcher.create()

// dispatcher#abort(isAborted)
// @param {boolean} [isAborted = true] - true 代表禁用，false 代表启用
// @returns {boolean} - 返回当前订阅触发状态是否为禁用

// @examples
dispatcher.abort()
dispatcher.abort(false)

// dispatcher#add(params, handler)
// @param {Object} params
// @prop {string} params.id - 订阅目标唯一标识
// @prop {string} params.event - 订阅事件名称
// @param {Function} handler - 订阅处理函数，当订阅目标上触发事件时被调用，入参为一个 DispatcherEvent。
// 返回 false 会导致 #trigger 方法调用结果也为 false, 但不影响订阅同一目标和事件的其它函数被调用。
// @returns {Function} - 返回一个用于解除订阅的函数

// @example
// 创建一个订阅器实例
const dispatcher = Dispatcher.create()
// 向目标添加订阅函数
const unsub = dispatcher.add({
  id: "1", event: "onMutate"
}, function(event) {
  let {type, target, detail} = event
  console.log(type === "onMutate") // true
  console.log(target === "1") // true
  console.log(detail)
})
dispatcher.add({
  id: "1", event: "onMutate"
}, function(event) {
  if (event.detail === "Bye") { return false }
})
// 触发指定目标的订阅函数
dispatcher.trigger({id: "1", event: "onMutate", detail: "Hello"}) // true
dispatcher.trigger({id: "1", event: "onMutate", detail: "Bye"}) // false
// 取消订阅
unsub()

// dispatcher#delete(params, handler)
// @param {Object} params
// @prop {string} params.id - 目标唯一标识
// @prop {string} [params.event] - 事件名称，如不指定，会移除目标上所有订阅函数
// @param {Function} [handler] - 订阅函数，如不指定，会移除目标事件上所有订阅函数
// @returns {undefined}

// @example
// 添加订阅
const handler = function(event) { console.log(event) }
dispatcher.add({id: "1", event: "onMutate"}, handler)
// 移除目标上所有 onMutate 事件的订阅函数
dispatcher.delete({id: "1", event: "onMutate"})

// dispatcher#trigger(params)
// @param {Object} params
// @prop {string} params.id - 目标唯一标识
// @prop {string} params.event - 事件名称
// @prop {*} [params.detail] - 自定义事件数据
// @returns {boolean} - 如果任一订阅函数返回 false，返回 false，否则返回 true。

// @example
// 创建一个订阅器实例
const dispatcher = Dispatcher.create()
// 向目标添加订阅函数
const unsub = dispatcher.add({
  id: "1", event: "onMutate"
}, function(event) {
  let {type, target, detail} = event
  console.log(type === "onMutate") // true
  console.log(target === "1") // true
  console.log(detail)
})
dispatcher.add({
  id: "1", event: "onMutate"
}, function(event) {
  if (event.detail === "Bye") { return false }
})
// 触发指定目标的订阅函数
dispatcher.trigger({id: "1", event: "onMutate", detail: "Hello"}) // true
dispatcher.trigger({id: "1", event: "onMutate", detail: "Bye"}) // false
// 取消订阅
unsub()