# self-referential > Convert self referential collection to nested or flat hierarchy Latest version **1.1.3** (published 2019-10-27) · BSD-2-Clause license · 0 weekly downloads ## Install ```sh npm install self-referential pnpm add self-referential yarn add self-referential bun add self-referential ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.1.3 | | Published | 2019-10-27 | | First published | 2014-08-23 | | Weekly downloads | 0 | | License | BSD-2-Clause | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Unpacked size | 15.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 2 | | Author | Nihat Ozer | | Maintainers | nihat | | Keywords | hierarchy, self-referential, nested | ## Links - npm: https://www.npmjs.com/package/self-referential - Repository: https://github.com/nozer/self-referential - Issues: https://github.com/nozer/self-referential/issues - npm.io page: https://npm.io/package/self-referential ## Alternatives - [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads - [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads - [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads - [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads - [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads ## Recent versions - 1.1.3 (latest) — 2019-10-27 - 1.1.1 — 2015-05-13 - 1.1.0 — 2015-02-03 - 1.0.42 — 2014-08-26 - 1.0.41 — 2014-08-26 - 1.0.4 — 2014-08-26 - 1.0.33 — 2014-08-26 - 1.0.32 — 2014-08-26 - 1.0.31 — 2014-08-23 - 1.0.3 — 2014-08-23 - 1.0.2 — 2014-08-23 - 1.0.1 — 2014-08-23 - 1.0.0 — 2014-08-23 ## 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 --- _Source: https://npm.io/package/self-referential · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._