https://github.com/nozer/self-referential
Allows a self referential collection to be converted into a nested or flat hierarchy
https://github.com/nozer/self-referential
Last synced: 5 months ago
JSON representation
Allows a self referential collection to be converted into a nested or flat hierarchy
- Host: GitHub
- URL: https://github.com/nozer/self-referential
- Owner: nozer
- Created: 2014-08-23T13:14:41.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2015-05-15T19:02:25.000Z (about 11 years ago)
- Last Synced: 2026-02-04T23:39:11.616Z (5 months ago)
- Language: JavaScript
- Size: 266 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
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