self-referential

self-referential
================

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:
hierPos: string:
depth: int:
childCount: int:
}
...
]
`
`
[
{
"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