path-treeify 1.2.0-beta.db6fe0b → 1.3.0

package/README.md

@@ -29,6 +29,12 @@
   <a href="https://github.com/isaaxite/path-treeify/commits/main/">
     <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/isaaxite/path-treeify">
   </a>
+  <a href='https://codecov.io/github/isaaxite/path-treeify/tests'>
+    <img src='https://github.com/isaaxite/path-treeify/actions/workflows/unittests.yml/badge.svg' alt='Coverage Status' />
+  </a>
+  <a href='https://coveralls.io/github/isaaxite/path-treeify'>
+    <img src='https://coveralls.io/repos/github/isaaxite/path-treeify/badge.svg' alt='Coverage Status' />
+  </a>
 </div>
 
 ---
@@ -38,9 +44,9 @@
 - 🌲 Builds a recursive tree from one or more directory paths
 - 🔗 Each node carries a `parent` circular reference for upward traversal
 - 📍 Each node exposes a `getPath()` method to retrieve its own paths directly
-- 🔍 Optional `filter` callback to include/exclude directories during scanning
+- 🔍 Optional `filter` callback applied at **every depth**, including top-level directories
 - ⚡ `build()` scans the entire `base` directory with zero configuration
-- 🎛️ `buildBy()` accepts either a directory name array or a filter function
+- 🎛️ `buildBy()` accepts either a directory name array or a top-level filter function
 - 📦 Ships as both ESM (`index.mjs`) and CJS (`index.cjs`) with full TypeScript types
 - 🚫 Zero runtime dependencies
 
@@ -74,8 +80,8 @@ const treeify = new PathTreeify({ base: '/your/project/root' });
 // Scan specific directories by name
 const tree = treeify.buildBy(['src', 'tests']);
 
-// Scan with a filter function over all top-level directories
-const filtered = treeify.buildBy(name => !name.startsWith('.') && name !== 'node_modules');
+// Scan with a top-level filter function
+const filtered = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
 
 // Or scan everything under base at once
 const fullTree = treeify.build();
@@ -89,10 +95,10 @@ const fullTree = treeify.build();
 
 Creates a new instance.
 
-| Option   | Type                          | Required | Description                                        |
-|----------|-------------------------------|----------|----------------------------------------------------|
-| `base`   | `string`                      | ✅        | Absolute path to the root directory to scan from  |
-| `filter` | `FilterFunction` (see below)  | ❌        | Called for every directory found during deep traversal |
+| Option   | Type                          | Required | Description                                                                 |
+|----------|-------------------------------|----------|-----------------------------------------------------------------------------|
+| `base`   | `string`                      | ✅        | Absolute path to the root directory to scan from                           |
+| `filter` | `FilterFunction` (see below)  | ❌        | Applied at **every depth** — top-level directories included                |
 
 `base` must exist and be a directory, otherwise the constructor throws.
 
@@ -100,7 +106,7 @@ Creates a new instance.
 
 ### `FilterFunction`
 
-Used as the `filter` option in the constructor. Applied recursively during deep traversal of the tree.
+Used as the `filter` option in the constructor. Applied at every level of the tree, including the immediate children of `base`.
 
 ```ts
 type FilterFunction = (params: {
@@ -109,14 +115,14 @@ type FilterFunction = (params: {
 }) => boolean;
 ```
 
-Return `true` to **include** the directory and recurse into it; `false` to **skip** it.
+Return `true` to **include** the directory and recurse into it; `false` to **skip** it entirely.
 
-**Example — skip hidden directories and `node_modules` at every level:**
+**Example — exclude `node_modules` and hidden directories at every depth:**
 
 ```ts
 const treeify = new PathTreeify({
   base: '/your/project',
-  filter: ({ name }) => !name.startsWith('.') && name !== 'node_modules',
+  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
 });
 ```
 
@@ -124,7 +130,7 @@ const treeify = new PathTreeify({
 
 ### `build(): PathTreeNode`
 
-Scans **all** subdirectories directly under `base` and returns a synthetic root `PathTreeNode`. This is the zero-configuration shorthand.
+Scans all subdirectories directly under `base` (applying the instance-level `filter` if set) and returns a synthetic root `PathTreeNode`.
 
 ```ts
 const tree = treeify.build();
@@ -145,13 +151,13 @@ const tree = treeify.buildBy(['src', 'docs', 'tests']);
 
 ### `buildBy(filter: (dirName: string) => boolean): PathTreeNode`
 
-Collects all top-level subdirectories under `base`, applies the given filter function, then builds a tree from the matching names.
+Collects all top-level subdirectories under `base`, applies the given predicate to select which ones to include, then builds a tree from the matching names. The instance-level `filter` still applies during deep traversal.
 
 ```ts
 const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
 ```
 
-> Note: this `filter` operates only on the **top-level** directory names under `base`. For filtering at every depth, pass a `filter` to the constructor instead.
+> **Note:** the predicate passed to `buildBy(fn)` only selects which **top-level** directories to include. To filter directories at every depth, pass a `filter` to the constructor.
 
 ---
 
@@ -161,6 +167,8 @@ Walks a node's `parent` chain to reconstruct its full path. Equivalent to callin
 
 ```ts
 const { relative, absolute } = treeify.getPathBy(node);
+// relative → e.g. 'src/components'
+// absolute → e.g. '/your/project/src/components'
 ```
 
 ---
@@ -179,7 +187,7 @@ class PathTreeNode {
 }
 ```
 
-**`node.getPath()`** returns the same result as `treeify.getPathBy(node)` — both are available for convenience.
+`node.getPath()` returns the same result as `treeify.getPathBy(node)` — both are available for convenience.
 
 > ⚠️ **Circular references** — `parent` points back up the tree. Use `JSON.stringify` replacers or a library like `flatted` if you need to serialize the result.
 
@@ -196,26 +204,26 @@ const treeify = new PathTreeify({ base: '/your/project' });
 const tree = treeify.build();
 ```
 
-### Scan specific directories
+### Exclude directories at every depth via constructor filter
 
 ```ts
-const tree = treeify.buildBy(['src', 'tests', 'docs']);
+const treeify = new PathTreeify({
+  base: '/your/project',
+  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
+});
+const tree = treeify.build();
 ```
 
-### Filter top-level directories
+### Scan specific directories
 
 ```ts
-const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
+const tree = treeify.buildBy(['src', 'tests', 'docs']);
 ```
 
-### Filter at every depth via constructor
+### Select top-level directories with a predicate
 
 ```ts
-const treeify = new PathTreeify({
-  base: '/your/project',
-  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
-});
-const tree = treeify.build();
+const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
 ```
 
 ### Retrieve paths via `node.getPath()`
@@ -245,4 +253,4 @@ const tree = treeify.build();
 
 ## License
 
-[MIT](https://github.com/isaaxite/path-treeify/blob/main/LICENSE) © [isaaxite](https://github.com/isaaxite)
+[MIT](https://github.com/isaaxite/path-treeify/blob/main/LICENSE) © [isaaxite](https://github.com/isaaxite)

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var t=require("fs"),e=require("path");class r{static isValid(e){try{return t.accessSync(e,t.constants.F_OK),!0}catch{return!1}}static isDirectory(e){try{return t.statSync(e).isDirectory()}catch{return!1}}}class i{constructor(t){this.parent=null,this.value="",this.children=[],this.base=t}getPath(){let t="",r=this;for(;r.parent;)t=t?`${r.value}${e.sep}${t}`:r.value,r=r.parent;return{relative:t,absolute:e.resolve(this.base,t)}}}exports.PathTreeify=class{constructor({filter:t,base:e}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!e||!r.isValid(e))throw new Error(`${e} is not a valid path!`);if(!r.isDirectory(e))throw new Error(`${e} is not a dirPath!`);this.base=e}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function");if(1!==t.length)throw new TypeError("filter must accept exactly one parameter");try{if("boolean"!=typeof t({name:"test",postPath:"/test"}))throw new TypeError("filter must return a boolean")}catch(t){throw new TypeError("filter function threw an error during test: "+t)}}initNode(t=null){const e=new i(this.base);return t&&(e.parent=t),e}buildChildren(r,i){const s=t.readdirSync(r),a=[];for(const n of s){const s=e.join(r,n);if(!t.statSync(s).isDirectory())continue;if(this.filter&&!this.filter({dirPath:r,name:n}))continue;const o=this.initNode();o.value=n,o.parent=i,o.children=this.buildChildren(s,o),a.push(o)}return a}checkRelativePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let i=0;i<t.length;i++){const s=t[i];if("string"!=typeof s)throw new Error(`Item at index ${i} is not a string, got ${typeof s}`);const a=e.resolve(this.base,s);if(!r.isValid(a))throw new Error(`Path does not exist or is not accessible: ${a} (from relative path: ${s})`);if(!r.isDirectory(a))throw new Error(`Path is not a directory: ${a} (from relative path: ${s})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==t)}getAllDirNamesUnderBase(){return t.readdirSync(this.base).filter(t=>{const i=e.resolve(this.base,t);return!!r.isDirectory(i)&&!(this.filter&&!this.filter({name:t,dirPath:this.base}))})}buildByDirNames(t){const r=this.initNode();this.checkRelativePaths(t);const i=this.formatDirnames(t);for(const t of i){const i=this.initNode();i.value=t,i.parent=r,i.children=this.buildChildren(e.resolve(this.base,t),i),r.children.push(i)}return r}buildByFilter(t){const e=this.getAllDirNamesUnderBase();return this.buildByDirNames(e.filter(t))}getPathBy(t){let r="",i=t;for(;i.parent;)r=r?`${i.value}${e.sep}${r}`:i.value,i=i.parent;return{relative:r,absolute:e.resolve(this.base,r)}}buildBy(t){if(Array.isArray(t))return this.buildByDirNames(t);if("function"==typeof t)return this.buildByFilter(t);throw new TypeError("buildBy: expected an array of strings or a filter function, but received "+typeof t)}build(){const t=this.getAllDirNamesUnderBase();return this.buildByDirNames(t)}};
+"use strict";var t=require("fs"),e=require("path");class r{static isValid(e){try{return t.accessSync(e,t.constants.F_OK),!0}catch{return!1}}static isDirectory(e){try{return t.statSync(e).isDirectory()}catch{return!1}}}class i{constructor(t){this.parent=null,this.value="",this.children=[],this.base=t}getPath(){let t="",r=this;for(;r.parent;)t=t?`${r.value}${e.sep}${t}`:r.value,r=r.parent;return{relative:t,absolute:e.resolve(this.base,t)}}}exports.PathTreeify=class{constructor({filter:t,base:e}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!e||!r.isValid(e))throw new Error(`${e} is not a valid path!`);if(!r.isDirectory(e))throw new Error(`${e} is not a dirPath!`);this.base=e}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function");if(1!==t.length)throw new TypeError("filter must accept exactly one parameter");try{if("boolean"!=typeof t({name:"test",postPath:"/test"}))throw new TypeError("filter must return a boolean")}catch(t){throw new TypeError("filter function threw an error during test: "+t)}}initNode(t=null){const e=new i(this.base);return t&&(e.parent=t),e}buildChildren(r,i){const s=t.readdirSync(r),a=[];for(const n of s){const s=e.join(r,n);if(!t.statSync(s).isDirectory())continue;if(this.filter&&!this.filter({dirPath:r,name:n}))continue;const o=this.initNode();o.value=n,o.parent=i,o.children=this.buildChildren(s,o),a.push(o)}return a}checkRelativePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let i=0;i<t.length;i++){const s=t[i];if("string"!=typeof s)throw new Error(`Item at index ${i} is not a string, got ${typeof s}`);const a=e.resolve(this.base,s);if(!r.isValid(a))throw new Error(`Path does not exist or is not accessible: ${a} (from relative path: ${s})`);if(!r.isDirectory(a))throw new Error(`Path is not a directory: ${a} (from relative path: ${s})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==t)}getAllDirNamesUnderBase(){return t.readdirSync(this.base).filter(t=>{const i=e.resolve(this.base,t);return!!r.isDirectory(i)&&!(this.filter&&!this.filter({name:t,dirPath:this.base}))})}buildByDirNames(t){const r=this.initNode(),i=this.formatDirnames(t);this.checkRelativePaths(i);for(const t of i){const i=this.initNode();i.value=t,i.parent=r,i.children=this.buildChildren(e.resolve(this.base,t),i),r.children.push(i)}return r}buildByFilter(t){const e=this.getAllDirNamesUnderBase();return this.buildByDirNames(e.filter(t))}getPathBy(t){let r="",i=t;for(;i.parent;)r=r?`${i.value}${e.sep}${r}`:i.value,i=i.parent;return{relative:r,absolute:e.resolve(this.base,r)}}buildBy(t){if(Array.isArray(t))return this.buildByDirNames(t);if("function"==typeof t)return this.buildByFilter(t);throw new TypeError("buildBy: expected an array of strings or a filter function, but received "+typeof t)}build(){const t=this.getAllDirNamesUnderBase();return this.buildByDirNames(t)}};

package/dist/index.mjs

@@ -1 +1 @@
-import{readdirSync as t,statSync as r,accessSync as e,constants as i}from"fs";import{join as s,resolve as a,sep as n}from"path";class o{static isValid(t){try{return e(t,i.F_OK),!0}catch{return!1}}static isDirectory(t){try{return r(t).isDirectory()}catch{return!1}}}class l{constructor(t){this.parent=null,this.value="",this.children=[],this.base=t}getPath(){let t="",r=this;for(;r.parent;)t=t?`${r.value}${n}${t}`:r.value,r=r.parent;return{relative:t,absolute:a(this.base,t)}}}class h{constructor({filter:t,base:r}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!r||!o.isValid(r))throw new Error(`${r} is not a valid path!`);if(!o.isDirectory(r))throw new Error(`${r} is not a dirPath!`);this.base=r}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function");if(1!==t.length)throw new TypeError("filter must accept exactly one parameter");try{if("boolean"!=typeof t({name:"test",postPath:"/test"}))throw new TypeError("filter must return a boolean")}catch(t){throw new TypeError("filter function threw an error during test: "+t)}}initNode(t=null){const r=new l(this.base);return t&&(r.parent=t),r}buildChildren(e,i){const a=t(e),n=[];for(const t of a){const a=s(e,t);if(!r(a).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,name:t}))continue;const o=this.initNode();o.value=t,o.parent=i,o.children=this.buildChildren(a,o),n.push(o)}return n}checkRelativePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let r=0;r<t.length;r++){const e=t[r];if("string"!=typeof e)throw new Error(`Item at index ${r} is not a string, got ${typeof e}`);const i=a(this.base,e);if(!o.isValid(i))throw new Error(`Path does not exist or is not accessible: ${i} (from relative path: ${e})`);if(!o.isDirectory(i))throw new Error(`Path is not a directory: ${i} (from relative path: ${e})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==t)}getAllDirNamesUnderBase(){return t(this.base).filter(t=>{const r=a(this.base,t);return!!o.isDirectory(r)&&!(this.filter&&!this.filter({name:t,dirPath:this.base}))})}buildByDirNames(t){const r=this.initNode();this.checkRelativePaths(t);const e=this.formatDirnames(t);for(const t of e){const e=this.initNode();e.value=t,e.parent=r,e.children=this.buildChildren(a(this.base,t),e),r.children.push(e)}return r}buildByFilter(t){const r=this.getAllDirNamesUnderBase();return this.buildByDirNames(r.filter(t))}getPathBy(t){let r="",e=t;for(;e.parent;)r=r?`${e.value}${n}${r}`:e.value,e=e.parent;return{relative:r,absolute:a(this.base,r)}}buildBy(t){if(Array.isArray(t))return this.buildByDirNames(t);if("function"==typeof t)return this.buildByFilter(t);throw new TypeError("buildBy: expected an array of strings or a filter function, but received "+typeof t)}build(){const t=this.getAllDirNamesUnderBase();return this.buildByDirNames(t)}}export{h as PathTreeify};
+import{readdirSync as t,statSync as r,accessSync as e,constants as i}from"fs";import{join as s,resolve as a,sep as n}from"path";class o{static isValid(t){try{return e(t,i.F_OK),!0}catch{return!1}}static isDirectory(t){try{return r(t).isDirectory()}catch{return!1}}}class l{constructor(t){this.parent=null,this.value="",this.children=[],this.base=t}getPath(){let t="",r=this;for(;r.parent;)t=t?`${r.value}${n}${t}`:r.value,r=r.parent;return{relative:t,absolute:a(this.base,t)}}}class h{constructor({filter:t,base:r}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!r||!o.isValid(r))throw new Error(`${r} is not a valid path!`);if(!o.isDirectory(r))throw new Error(`${r} is not a dirPath!`);this.base=r}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function");if(1!==t.length)throw new TypeError("filter must accept exactly one parameter");try{if("boolean"!=typeof t({name:"test",postPath:"/test"}))throw new TypeError("filter must return a boolean")}catch(t){throw new TypeError("filter function threw an error during test: "+t)}}initNode(t=null){const r=new l(this.base);return t&&(r.parent=t),r}buildChildren(e,i){const a=t(e),n=[];for(const t of a){const a=s(e,t);if(!r(a).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,name:t}))continue;const o=this.initNode();o.value=t,o.parent=i,o.children=this.buildChildren(a,o),n.push(o)}return n}checkRelativePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let r=0;r<t.length;r++){const e=t[r];if("string"!=typeof e)throw new Error(`Item at index ${r} is not a string, got ${typeof e}`);const i=a(this.base,e);if(!o.isValid(i))throw new Error(`Path does not exist or is not accessible: ${i} (from relative path: ${e})`);if(!o.isDirectory(i))throw new Error(`Path is not a directory: ${i} (from relative path: ${e})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==t)}getAllDirNamesUnderBase(){return t(this.base).filter(t=>{const r=a(this.base,t);return!!o.isDirectory(r)&&!(this.filter&&!this.filter({name:t,dirPath:this.base}))})}buildByDirNames(t){const r=this.initNode(),e=this.formatDirnames(t);this.checkRelativePaths(e);for(const t of e){const e=this.initNode();e.value=t,e.parent=r,e.children=this.buildChildren(a(this.base,t),e),r.children.push(e)}return r}buildByFilter(t){const r=this.getAllDirNamesUnderBase();return this.buildByDirNames(r.filter(t))}getPathBy(t){let r="",e=t;for(;e.parent;)r=r?`${e.value}${n}${r}`:e.value,e=e.parent;return{relative:r,absolute:a(this.base,r)}}buildBy(t){if(Array.isArray(t))return this.buildByDirNames(t);if("function"==typeof t)return this.buildByFilter(t);throw new TypeError("buildBy: expected an array of strings or a filter function, but received "+typeof t)}build(){const t=this.getAllDirNamesUnderBase();return this.buildByDirNames(t)}}export{h as PathTreeify};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-treeify",
-  "version": "1.2.0-beta.db6fe0b",
+  "version": "1.3.0",
   "description": "Convert a path or an array of paths into a tree-structured JavaScript object, where each node has a `parent` property that holds a circular reference to its parent node.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -25,8 +25,10 @@
   ],
   "scripts": {
     "test": "ava",
-    "test:watch": "ava --watch",
-    "clean": "rimraf ./dist",
+    "test:coverage": "c8 ava",
+    "test:junit": "mkdir -p reports && ava --tap | tap-xunit > reports/junit.xml",
+    "test:report": "rimraf reports && npm run test:coverage && npm run test:junit",
+    "clean": "rimraf dist",
     "build": "npm run clean && rollup -c",
     "build:dev": "NODE_ENV=development npm run build",
     "build:prod": "NODE_ENV=production npm run build",
@@ -43,6 +45,21 @@
       "--experimental-vm-modules"
     ]
   },
+  "c8": {
+    "reports-dir": "reports/coverage",
+    "reporter": [
+      "html",
+      "lcov"
+    ],
+    "exclude": [
+      "tests/**",
+      "node_modules/**"
+    ],
+    "lines": 80,
+    "statements": 80,
+    "functions": 80,
+    "branches": 75
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/isaaxite/path-treeify.git"
@@ -72,9 +89,11 @@
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/node": "^25.5.0",
     "ava": "^7.0.0",
+    "c8": "^11.0.0",
     "nodemon": "^3.1.14",
     "rimraf": "^6.1.3",
     "rollup": "^4.59.0",
+    "tap-xunit": "^2.4.1",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3"
   },