Context.Family

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

Custom Types

@typedef {Object} FamilyInstance
@description - 家族树管理器实例

@typedef {Object} FamilyMember
@prop {string} [id = <a_random_unique_id>] - 成员唯一标识
@prop {string} [parentId = <root_member_id>] - 父级成员唯一标识
@prop {integer} [order = Infinity] - 成员在同辈中的顺序

Exception Types

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

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

@type {ExceptionInstance}
@description - 成员不存在

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

@type {ExceptionInstance}
@description - 父级成员冲突

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

@type {ExceptionInstance}
@description - 家族树自引用冲突

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

Class Methods

.create()

创建一个已包含根成员的家族树实例。

// Family.create()
// @returns {FamilyInstance}

// @example
const family = Family.create()

.isFamily()

判断入参是否是一个家族树实例。

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

// @examples
Family.isFamily(Family.create()) // true
Family.isFamily({}) // false

.isntFamily()

判断入参是否不是一个家族树实例。

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

// @examples
Family.isntFamily(Family.create()) // false
Family.isntFamily({}) // true

.mustbeFamily()

当入参不是一个家族树实例时抛出异常。

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

// @examples
Family.mustbeFamily(Family.create())
Family.mustbeFamily({}) // Throws a FAMILY_INVALID_INSTANCE exception.

Instance Methods

#add()

添加一个家族成员。

// family#add(member)
// @param {Object} [member]
// @prop {string} [member.id = <a_random_unique_id>]
// @prop {string} [member.parentId = <root_member_id>]
// @prop {integer} [params.order = Infinity]
// @returns {FamilyMember}

// @example
const parent = family.add()
const child = family.add({parentId: parent.id})

// @example
// Raises a "FAMILY_MEMBER_NOT_EXIST" exception.
family.add({parentId: 'not exist'})

// @example
// Raises a "FAMILY_MEMBER_CONFLICTED_PARENT" exception.
family.add({id: parent.id, parentId: child.id})

#ancestor()

查找成员父级成员或按亲疏顺序搜集成员祖先成员。

// family#ancestor(params, options)
// @param {Object} params
// @prop {string} params.id - 成员唯一标识
// @param {Object} [options = {}]
// @prop {boolean} [options.deep = false] - 默认只查找父级成员。为 true 时，按亲疏顺序搜集祖先成员。
// @prop {boolean} [options.self = false] - 当 deep 为 true 时有效，当设定为 true，返回结果包含成员本身。
// @returns {null | FamilyMember | FamilyMember[]}

// @example - 查找父级成员
family.ancestor({id: child.id}) // FamilyMember
family.ancestor({id: 'not exist'}) // null

// @example - 搜集祖先成员
family.ancestor({id: child.id}, {deep: true}) // FamilyMember[]
family.ancestor({id: 'not exist'}, {deep: true}) // null

#delete()

删除成员及其后代成员，根成员无法被删除，静默失败。

// family#delete(params)
// @param {Object} params
// @prop {string} params.id - 成员唯一标识
// @returns {undefined}

// @example
family.delete({id: parent.id})

#descendant()

搜集成员子成员或按亲疏顺序搜集成员后代成员。

// family#descendant(params, options)
// @param {Object} params
// @prop {string} params.id - 成员唯一标识
// @param {Object} [options = {}]
// @prop {boolean} [options.deep = false] - 默认搜集子成员，为 true 时，按亲疏顺序搜集后代成员。
// @prop {boolean} [options.self = false] - 当设定为 true 时，返回结果包含成员本身。
// @returns {null | FamilyMember[]}

// @example - 搜集子成员
family.descendant({id: parent.id}) // FamilyMember[]
family.descendant({id: leaf.id}) // null

// @example - 搜集后代成员
family.descendant({id: parent.id}, {deep: true}) // FamilyMember[]
family.descendant({id: leaf.id}, {deep: true}) // null

#has()

判断某成员是否存在于家族树中。

// family#has(params)
// @param {Object} params
// @prop {string} params.id - 成员唯一标识
// @returns {boolean}

// @example
family.has({id: parent.id})

#hasnt()

判断某成员是否不存在于家族树中。

// family#hasnt(params)
// @param {Object} params
// @prop {string} params.id - 成员唯一标识
// @returns {boolean}

// @example
family.hasnt({id: 'not exist'})

#reorder()

将某成员在同辈成员中重新排序。

// family#reorder(params)
// @param {Object} params
// @prop {string} params.id - 成员唯一标识
// @prop {integer} params.order - 成员在同辈成员中的顺序
// @returns {undefined}

// @example
family.reorder({id: childTwo.id, order: 0})

#root()

获取根成员。

// family#root()
// @returns {FamilyMember}

// @example
const root = family.root()

#sibling()

按顺序搜集成员的同辈成员。

// family.sibling(params, options)
// @param {Object} params
// @prop {string} params.id - Member id
// @param {Object} [options = {}]
// @prop {boolean} [options.self = false] - 当为 true 时，返回结果包含成员本身。
// @returns {null | FamilyMember[]}

// @example - 获取成员同辈成员
family.sibling({id: childTwo.id}) // FamilyMember[]
family.sibling({id: leaf.id}) // null