Context.Dependency

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

@typedef {Object} DependencyInstance
@description - 依赖关系管理器实例

@typedef {Object} DependencyProvider
@description - 被依赖者

@prop {string} id - 唯一标识
@prop {string} prop - 属性名称

@typedef {Object} DependencyRelier
@description - 依赖者

@prop {string} id - 唯一标识
@prop {string} prop - 属性名称

@typedef {Object} DependencyAssociation
@description - 依赖关系

@prop {DependencyProvider} provider
@prop {DependencyRelier} relier

@type {ExceptionInstance}
@description - 不合规实例

@prop {string} type = "DEPENDENCY_INVALID_INSTANCE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 循环依赖

@prop {string} type = "DEPENDENCY_CIRCLE_REFERENCE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

// Dependency.create()
// @returns {DependencyInstance}

// @example
const dependency = Dependency.create()

// Dependency.isDependency(arg)
// @param {*} arg - 任意参数
// @returns {boolean} - 当入参是 DependencyInstance 时返回 true，否则返回 false

// @examples
Dependency.isDependency(Dependency.create()) // true
Dependency.isDependency({}) // false

// Dependency.isntDependency(arg)
// @param {*} arg - 任意参数
// @returns {boolean} - 当入参是 DependencyInstance 时返回 false，否则返回 true

// @examples
Dependency.isntDependency(Dependency.create()) // false
Dependency.isntDependency({}) // true

// Dependency.mustbeDependency(arg, message)
// @param {*} arg - 任意参数
// @param {string} [message] - 自定义异常对象消息
// @returns {undefined}

// @examples
Dependency.mustbeDependency(Dependency.create())
Dependency.mustbeDependency({}) // Throws a DEPENDENCY_INVALID_INSTANCE exception.

// dependency#add(associations, options)
// @param {DependencyAssociation | DependencyAssociation[]}
// @param {Object} [options]
// @prop {string} [options.group] - 依赖者分组
// 用于按不同目的划分依赖者，可在删除时进行过滤以删除该分组下的依赖关系。
// @returns {undefined}

// @example - 添加一组依赖关系
dependency.add({
  provider: {id: '1', prop: 'age'},
  relier: {id: '2', prop: 'age'}
})

// @example - 添加多组依赖关系
dependency.add([{
  provider: {id: '1', prop: 'age'},
  relier: {id: '3', prop: 'age'}
}, {
  provider: {id: '1', prop: 'age'},
  relier: {id: '4', prop: 'age'}
}])

// @example - 产生循环依赖，因为前例中已添加过相反的依赖关系
dependency.add({
  provider: {id: '2', prop: 'age'},
  relier: {id: '1', prop: 'age'}
}) // DEPENDENCY_CIRCLE_REFERENCE exception

// @example - 按依赖者分组添加依赖关系
dependency.add([{
  provider: {id: '1', prop: 'age'},
  relier: {id: '3', prop: 'age'}
}, {
  provider: {id: '1', prop: 'age'},
  relier: {id: '4', prop: 'age'}
}], { group: 'myRelierGroup' })

// dependency#delete(target, options)
// @param {DependencyProvider | DependencyRelier} target - 如不指定 prop，则删除含有目标的所有依赖关系。
// @param {Object} [options = {}]
// @prop {string} [options.only] - 当被设定为 "relier" 则只删除目标是依赖者的依赖关系
// @prop {string} [options.group] - 只当 only 被设定为 "relier" 时有效。
// 当 group 设定时，只删除目标是依赖者且在分组下的依赖关系，否则删除所有目标是依赖者的依赖关系。
// @returns {undefined}

// @example - 删除指定目标 age 属性的所有依赖关系
dependency.delete({id: '2', prop: 'age'})

// @example - 删除指定目标的所有依赖关系
dependency.delete({id: '2'})

// @example - 删除所有指定目标是依赖者且含有 age 属性的依赖关系
dependency.delete({id: '2', prop: 'age'}, {only: 'relier'})

// @example - 删除所有指定目标是依赖者的依赖关系
dependency.delete({id: '2'}, {only: 'relier'})

// @example - 删除所有指定目标是依赖者且在 "myRelierGroup" 分组下的依赖关系
dependency.delete({id: '2'}, {only: 'relier', group: 'myRelierGroup'})

// dependency#reliers(provider, options)
// @param {DependencyProvider | DependencyProvider[]}
// @param {Object} [options = {}]
// @prop {boolean} [options.reload = false] - 当设定为 true，会清空之前的查询结果缓存，重新查询后再次写入缓存。
// @prop {boolean} [options.deep = true] - 当设定为 true，只返回直接依赖者数组。
// @prop {boolean} [options.self = true] - 当设定为 true，返回数组中不包括 id 与 provider 相同的依赖者。
// @prop {group} [options.group] - 当设定时，只返回分组下的依赖者。
// @returns {null | DependencyRelier[]}

// @example - 添加依赖关系
const dependency = Dependency.create()
dependency.add([{
  provider: {id: '2', prop: 'age'},
  relier: {id: '3', prop: 'age'}
}, {
  provider: {id: '1', prop: 'age'},
  relier: {id: '2', prop: 'age'}
}, {
  provider: {id: '1', prop: 'age'},
  relier: {id: '3', prop: 'age'}
}])
dependency.add({
  provider: {id: '3', prop: 'gender'},
  relier: {id: '1', prop: 'gender'}
})
dependency.add({
  provider: {id: '1', prop: 'gender'},
  relier: {id: '1', prop: 'age'}
})
dependency.add({
  provider: {id: '3', prop: 'hobbit'},
  relier: {id: '4', prop: 'hobbit'}
})

// @example Returns ->
// [
//   {id:"1", prop:"gender"},
//   {id:"4", prop:"hobbit"},
//   {id:"1", prop:"age"},
//   {id:"2", prop:"age"},
//   {id:"3", prop:"age"}
// ]
dependency.reliers({id: '3'})

// @example Returns ->
// [
//   {id:"1", prop:"gender"},
//   {id:"1", prop:"age"},
//   {id:"2", prop:"age"},
//   {id:"3", prop:"age"}
// ]
dependency.reliers({id: '3', prop: 'gender'})