fast-tree-builder 0.1.3 → 0.1.4

package/README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://github.com/lionel87/fast-tree-builder/actions/workflows/build.yaml/badge.svg)](https://github.com/lionel87/fast-tree-builder/actions/workflows/build.yaml)
 [![Coverage Status](https://coveralls.io/repos/github/lionel87/fast-tree-builder/badge.svg?branch=master)](https://coveralls.io/github/lionel87/fast-tree-builder?branch=master)
 ![npms.io (quality)](https://img.shields.io/npms-io/quality-score/fast-tree-builder?label=quality)
-![Maintenance](https://img.shields.io/maintenance/yes/2023)
+![Maintenance](https://img.shields.io/maintenance/yes/2024)
 
 `fast-tree-builder` is an npm package that allows you to efficiently build trees from iterable data structures. With its optimized algorithm, strong TypeScript typings, and customizable node structure, it provides a reliable solution for organizing and manipulating hierarchical data.
 
@@ -15,23 +15,23 @@
 
 ## Features
 
-- **Efficient Tree Building**: The package utilizes an optimized algorithm to construct trees efficiently in `O(n)` time, ensuring good performance even with large datasets.
+- **Efficient Tree Building**: The package utilizes an optimized algorithm to construct trees efficiently in `O(n)` time, while maintaining good performance.
 
 - **Bi-Directional Tree Traversal**: Traverse the built tree in both directions, enabling easy navigation between parent and child nodes.
 
-- **Strong TypeScript Typings**: Enjoy the benefits of type safety with comprehensive TypeScript typings. The package provides detailed type definitions to enhance your development experience.
+- **Robust TypeScript Type Definitions**: Leverage type safety through extensive TypeScript type definitions. The package includes precise type annotations to improve code reliability and developer workflow.
 
 - **Fully Customizable Node Structure**: Tailor the structure of the nodes in the built tree to meet your specific requirements. You have the freedom to define data, parent, and children key names according to your application's needs. To avoid circular references parent links can be turned off which helps generating JSON data.
 
-- **Works on Any Iterable Data Structure**: Whether you have an array, set, or any other iterable data structure, `fast-tree-builder` can process it seamlessly, making it compatible with a wide range of use cases.
+- **Works on Any Iterable Data**: Designed to handle arrays, sets, and other iterable data structures efficiently, ensuring broad applicability.
 
-- **No Sorting Required**: The package does not require your input data to be sorted, saving you preprocessing time and effort.
+- **No Sorting Required**: The algorithm does not require your input data to be sorted, saving you preprocessing time and effort.
 
-- **Flexible Key and Parent Key Types**: You can use any JavaScript value for identifying items. Relations checked with `key === parentKey` comparison.
+- **Flexible Key and Parent Key Types**: You can use any JavaScript value for identifying items. Relations checked with strict (`key === parentKey`) comparison.
 
-- **Map of Nodes**: Beside the root nodes you can retrieve a `Map` object containing the nodes of the built tree, enabling easy entry on any point of the tree.
+- **Multiple Root Nodes**: Can efficiently construct trees with multiple root nodes, accommodating scenarios that necessitate distinct, separate tree structures within the same dataset.
 
-- **Support for Multiple Root Nodes**: The package supports building trees with multiple root nodes.
+- **Map of Nodes**: Beside the root nodes you can retrieve a `Map` object containing the nodes of the built tree, enabling easy entry on any point of the tree.
 
 - **Support for Parent Key Validation**: Enables you to validate parent keys while building the tree. When a node missing its parent, an error will be thrown.
 
@@ -225,7 +225,7 @@ Parameters
 	- `nodeParentKey`: (Optional) The key used to store the parent node in each node. It can be a string, number, symbol, or false if the parent node should not be included. Defaults to `'parent'`.
 	- `nodeChildrenKey`: (Optional) The key used to store the children nodes in each node. It can be a string, number, symbol. Defaults to `'children'`.
 	- `mapNodeData`: (Optional) A function that maps an item to its corresponding node data. It allows transforming the item before assigning it to the node. Defaults to `undefined`.
-	- `validateParentKeys`: (Optional) An iterable containing keys that should be validated as existing parent keys. If provided, any item with a parent key not present in this iterable will cause an error to be thrown. Defaults to `undefined`.
+	- `validateParentKeys`: (Optional) An iterable containing parent key values that can be accepted as root nodes. If provided, any item with a parent key not present in this iterable will cause an error to be thrown. Defaults to `undefined`.
   - `validateTree`: (Optional) A boolean flag that determines whether to validate the resulting data structure. If the structure is a cyclic graph, an `Error` will be thrown. Requires additional `O(n)` time to compute. Defaults to `false`.
 
 Returns
@@ -243,11 +243,9 @@ Throws `Error` when:
 
 ## Comparison with other tree building libraries
 
-The package aims to be feature complete and highly customizable, which usually opposes with performance. There are other packages that may be more `performant` but lacks features that I really needed in my daily coding. In standard scenarios this package should be more than enough.
-
-I can imagine extreme cases with huge trees where this package can be slower, but you should write your own tree building implementation optimized for that exact case anyway.
+The package aims to be feature complete and highly customizable, which usually opposes with performance. There are other packages that may be more *performant* but lacks features that I really needed in my daily coding. In standard scenarios this package should perform more than enough and nearly as good as other packages.
 
-Hey, its not more than:
+For scenarios where performance is critical, consider implementing a tailored, optimized algorithm. It could be as simple as:
 ```js
 const roots = [];
 const nodes = new Map();

package/{cjs/index.js → index.cjs}

@@ -1,12 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 function buildTree(items, options = {}) {
-    var _a;
     const { key = 'id', parentKey = 'parent', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validateParentKeys, validateTree = false, } = options;
     const nodes = new Map();
     const danglingNodes = new Map();
     for (const item of items) {
-        // @ts-ignore
         const keyOfNode = typeof key === 'function' ? key(item) : item[key];
         if (nodes.has(keyOfNode)) {
             throw new Error(`Duplicate identifier detected for "${keyOfNode}"`);
@@ -29,9 +27,8 @@ function buildTree(items, options = {}) {
             Object.assign(node, nodeData);
         }
         // Link this node to its parent
-        // @ts-ignore
         const keyOfParentNode = typeof parentKey === 'function' ? parentKey(item) : item[parentKey];
-        let parent = (_a = nodes.get(keyOfParentNode)) !== null && _a !== void 0 ? _a : danglingNodes.get(keyOfParentNode);
+        let parent = nodes.get(keyOfParentNode) ?? danglingNodes.get(keyOfParentNode);
         if (!parent) {
             // No parent node exists yet, create as dangling node
             parent = {};

package/{cjs/index.d.ts → index.d.ts}

@@ -15,13 +15,10 @@ type TreeNode<T, D extends string | number | symbol | false, P extends string |
 } & {
     [k in C]?: TreeNode<T, D, P, C>[];
 }));
-declare function buildTree<T extends (D extends false ? object : unknown), M extends (D extends false ? object : unknown) = T, K extends unknown = unknown, D extends string | number | symbol | false = 'data', P extends string | number | symbol | false = 'parent', C extends string | number | symbol = 'children'>(items: Iterable<T>, options?: {
-    key?: string | number | symbol | {
-        (item: T): K;
-    };
-    parentKey?: string | number | symbol | {
-        (item: T): K;
-    };
+type KeyReturnType<T, P extends keyof T | ((item: T) => any)> = P extends ((item: T) => infer R) ? R : P extends keyof T ? T[P] : never;
+declare function buildTree<T extends (D extends false ? object : unknown), K extends keyof T | ((item: T) => any), M extends (D extends false ? object : unknown) = T, D extends string | number | symbol | false = 'data', P extends string | number | symbol | false = 'parent', C extends string | number | symbol = 'children'>(items: Iterable<T>, options?: {
+    key?: K;
+    parentKey?: keyof T | ((item: T) => KeyReturnType<T, K>);
     nodeDataKey?: D;
     nodeParentKey?: P;
     nodeChildrenKey?: C;
@@ -32,6 +29,6 @@ declare function buildTree<T extends (D extends false ? object : unknown), M ext
     validateTree?: boolean;
 }): {
     roots: TreeNode<M extends undefined ? T : M, D, P, C>[];
-    nodes: Map<K, TreeNode<M extends undefined ? T : M, D, P, C>>;
+    nodes: Map<KeyReturnType<T, K>, TreeNode<M extends undefined ? T : M, D, P, C>>;
 };
 export default buildTree;

package/{esm/index.js → index.js}

@@ -1,10 +1,8 @@
 function buildTree(items, options = {}) {
-    var _a;
     const { key = 'id', parentKey = 'parent', nodeDataKey = 'data', nodeParentKey = 'parent', nodeChildrenKey = 'children', mapNodeData, validateParentKeys, validateTree = false, } = options;
     const nodes = new Map();
     const danglingNodes = new Map();
     for (const item of items) {
-        // @ts-ignore
         const keyOfNode = typeof key === 'function' ? key(item) : item[key];
         if (nodes.has(keyOfNode)) {
             throw new Error(`Duplicate identifier detected for "${keyOfNode}"`);
@@ -27,9 +25,8 @@ function buildTree(items, options = {}) {
             Object.assign(node, nodeData);
         }
         // Link this node to its parent
-        // @ts-ignore
         const keyOfParentNode = typeof parentKey === 'function' ? parentKey(item) : item[parentKey];
-        let parent = (_a = nodes.get(keyOfParentNode)) !== null && _a !== void 0 ? _a : danglingNodes.get(keyOfParentNode);
+        let parent = nodes.get(keyOfParentNode) ?? danglingNodes.get(keyOfParentNode);
         if (!parent) {
             // No parent node exists yet, create as dangling node
             parent = {};

package/package.json

@@ -1,33 +1,44 @@
 {
   "name": "fast-tree-builder",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Efficiently construct highly customizable bi-directional tree structures from iterable data.",
   "type": "module",
-  "main": "cjs/index.js",
-  "module": "esm/index.js",
-  "types": "esm/index.d.ts",
+  "module": "./index.js",
+  "main": "./index.cjs",
+  "types": "./index.d.ts",
   "exports": {
     ".": {
-      "require": "./cjs/index.js",
-      "default": "./esm/index.js"
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
     }
   },
   "scripts": {
     "prepack": "npm run build && npm run test",
     "postversion": "git push && git push --tags",
-    "clean": "rimraf esm cjs coverage",
-    "build": "npm run build:esm && npm run build:cjs",
-    "build:esm": "tsc",
-    "watch:esm": "tsc --watch",
-    "build:cjs": "tsc --outDir cjs --module commonjs && echo { \"type\": \"commonjs\" }>cjs/package.json",
-    "watch:cjs": "npm run build:cjs && tsc --outDir cjs --module commonjs --watch",
+    "clean": "rimraf --glob \"!(.*).{d.ts,js,cjs,mjs}\" build coverage",
+    "build": "node scripts/build-esm.js && node scripts/build-cjs.js",
+    "watch": "node scripts/watch.js",
     "test": "mocha",
-    "coverage": "c8 -r text -r text-summary -r lcov npm test"
+    "coverage": "c8 -r text -r text-summary -r lcov --include \"*.js\" npm test"
   },
+  "devDependencies": {
+    "c8": "^8.0.0",
+    "chokidar": "^3.5.3",
+    "mocha": "^10.2.0",
+    "rimraf": "^5.0.1",
+    "typescript": "^5.1.3"
+  },
+  "homepage": "https://github.com/lionel87/fast-tree-builder#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lionel87/fast-tree-builder.git"
   },
+  "bugs": {
+    "url": "https://github.com/lionel87/fast-tree-builder/issues"
+  },
+  "author": "László BULIK",
+  "license": "MIT",
   "keywords": [
     "tree builder",
     "tree structure",
@@ -50,17 +61,5 @@
     "nested",
     "list",
     "validation"
-  ],
-  "author": "László BULIK",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/lionel87/fast-tree-builder/issues"
-  },
-  "homepage": "https://github.com/lionel87/fast-tree-builder#readme",
-  "devDependencies": {
-    "c8": "^8.0.0",
-    "mocha": "^10.2.0",
-    "rimraf": "^5.0.1",
-    "typescript": "^5.1.3"
-  }
+  ]
 }

package/cjs/package.json

@@ -1 +0,0 @@
-{ "type": "commonjs" }

package/esm/index.d.ts

@@ -1,37 +0,0 @@
-type TreeNode<T, D extends string | number | symbol | false, P extends string | number | symbol | false, C extends string | number | symbol> = (D extends false ? (P extends false ? T & {
-    [k in C]?: TreeNode<T, D, P, C>[];
-} : T & {
-    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
-} & {
-    [k in C]?: TreeNode<T, D, P, C>[];
-}) : (P extends false ? {
-    [k in Exclude<D, false>]: T;
-} & {
-    [k in C]?: TreeNode<T, D, P, C>[];
-} : {
-    [k in Exclude<D, false>]: T;
-} & {
-    [k in Exclude<P, false>]?: TreeNode<T, D, P, C>;
-} & {
-    [k in C]?: TreeNode<T, D, P, C>[];
-}));
-declare function buildTree<T extends (D extends false ? object : unknown), M extends (D extends false ? object : unknown) = T, K extends unknown = unknown, D extends string | number | symbol | false = 'data', P extends string | number | symbol | false = 'parent', C extends string | number | symbol = 'children'>(items: Iterable<T>, options?: {
-    key?: string | number | symbol | {
-        (item: T): K;
-    };
-    parentKey?: string | number | symbol | {
-        (item: T): K;
-    };
-    nodeDataKey?: D;
-    nodeParentKey?: P;
-    nodeChildrenKey?: C;
-    mapNodeData?: {
-        (item: T): M;
-    };
-    validateParentKeys?: Iterable<unknown>;
-    validateTree?: boolean;
-}): {
-    roots: TreeNode<M extends undefined ? T : M, D, P, C>[];
-    nodes: Map<K, TreeNode<M extends undefined ? T : M, D, P, C>>;
-};
-export default buildTree;