Allows a self referential collection (array of objects) to be converted into a nested or flat hierarchy
###Install & Require
npm install self-referential
var selfref = require('self-referential');
###Examples
Imagine a table named categories like below where parentId foreign key refers to a record in the same categories table.
| id | title | parentId |
|---|---|---|
| 1 | Colors | null |
| 2 | Fruits | null |
| 3 | Meats | null |
| 4 | Warm Colors | 1 |
| 5 | Cold Colors | 1 |
| 6 | Red | 4 |
| 7 | Orange | 4 |
| 8 | Apple | 2 |
We can represent this table as an array of objects as shown below:
var categories = [
{
id: 1,
title: 'Colors',
parentId: null
},
{
id: 2,
title: 'Fruits',
parentId: null
},
{
id: 3,
title: 'Meats',
parentId: null
},
{
id: 4,
title: 'Warm Colors',
parentId: 1
},
{
id: 5,
title: 'Cold Colors',
parentId: 1
},
{
id: 6,
title: 'Red',
parentId: 4
},
{
id: 7,
title: 'Orange',
parentId: 4
},
{
id: 8,
title: 'Apple',
parentId: 2
}
];
####To Nested Hierarchy To convert this to a nested hierarchy, we do:
var cfg = {
selfKey: 'id',
parentKey: 'parentId',
childrenKey: 'children'
// Optional properties
// rootParentValues: see way below for explanation
// rootSelfValues : see way below for explanation
};
var cats_hierarchy = selfref.toHier(cfg, categories);
cats_hierarchy has the following structure
[
{
"id": 1,
"title": "Colors",
"parentId": null,
"children": [
{
"id": 4,
"title": "Warm Colors",
"parentId": 1,
"children": [
{
"id": 6,
"title": "Red",
"parentId": 4,
"children": []
},
{
"id": 7,
"title": "Orange",
"parentId": 4,
"children": []
}
]
},
{
"id": 5,
"title": "Cold Colors",
"parentId": 1,
"children": []
}
]
},
{
"id": 2,
"title": "Fruits",
"parentId": null,
"children": [
{
"id": 8,
"title": "Apple",
"parentId": 2,
"children": []
}
]
},
{
"id": 3,
"title": "Meats",
"parentId": null,
"children": []
}
]
####To Flat Hierarchy To convert the above hierarchy into a flat collection, but in the same order as it would be in the hierarchy, we do:
var flat_but_in_hierarchical_order_cats = selfref.toFlatHier({childrenKey: 'children'}, cats_hierarchy);
flat_but_in_hierarchical_order_cats now has the following structure:
[
{
item: object: <your original item>
hierPos: string: <position of item in a hierarchy such as 1.1 or 1.2.1 as in a table of contents in a book>
depth: int: <depth of item in hierarchy, root has the value of zero>
childCount: int: <number of children>
}
...
]
[
{
"item": {
"id": 1,
"title": "Colors",
"parentId": null
},
"hierPos": "1",
"depth": 0,
"childCount": 2
},
{
"item": {
"id": 4,
"title": "Warm Colors",
"parentId": 1
},
"hierPos": "1.1",
"depth": 1,
"childCount": 2
},
{
"item": {
"id": 6,
"title": "Red",
"parentId": 4
},
"hierPos": "1.1.1",
"depth": 2,
"childCount": 0
},
{
"item": {
"id": 7,
"title": "Orange",
"parentId": 4
},
"hierPos": "1.1.2",
"depth": 2,
"childCount": 0
},
{
"item": {
"id": 5,
"title": "Cold Colors",
"parentId": 1
},
"hierPos": "1.2",
"depth": 1,
"childCount": 0
},
{
"item": {
"id": 2,
"title": "Fruits",
"parentId": null
},
"hierPos": "2",
"depth": 0,
"childCount": 1
},
{
"item": {
"id": 8,
"title": "Apple",
"parentId": 2
},
"hierPos": "2.1",
"depth": 1,
"childCount": 0
},
{
"item": {
"id": 3,
"title": "Meats",
"parentId": null
},
"hierPos": "3",
"depth": 0,
"childCount": 0
}
]
####Root Elements Finally, to get only the root elements of our collection, we do:
var root_cats = selfref.rootItems({selfKey: 'id', parentKey:'parentId'}, categories);
root_cats now has the following data:
[
{
"id": 1,
"title": "Colors",
"parentId": null
},
{
"id": 2,
"title": "Fruits",
"parentId": null
},
{
"id": 3,
"title": "Meats",
"parentId": null
}
]
###Config Parameters & Usage Configuration parameter cfg can have the following properties:
selfKey: name of property that is uniquely identifies this record
parentKey: name of property that whose value refers to its parent's unique id
childrenKey: name of the property that the children of this model should be set to
rootParentValues: null|string|number|array
Sets nodes whose parentKey values you are specifying as the root nodes in hierarchy and goes from there
rootSelfValues: null|string|number|array
Sets nodes whose selfKey values you are specifying as the root nodes in hierarchy and goes from there
if any of those rootXValues are omitted, all of items with no matching parents will be picked as root items and then hierarchy will be generated with them and their children.
You cannot specify both rootParentValues and rootSelfValues at the same time
selfref.toHier(cfg, collectionData); cfg must have all of the above properties (except rootParentValues)
selfref.toFlatHier(cfg, hierarchyCollection); cfg must have childrenKey property only
selfref.rootItems(cfg, collectionData); cfg must have selfKey and parentKey properties
selfref.getAncestors(cfg, collectionData, selfKeyValue) returns ancestors of the item having the selfKey property value of selfKeyValue.
cfg must have selfKey and parentKey properties
selfref.getChildren(cfg, collectionData, selfKeyValue) returns children of the item having the selfKey property value of selfKeyValue.
cfg must have selfKey and parentKey properties