path-treeify 1.1.0-beta.94a5d17 → 1.1.0

package/README.md

@@ -8,8 +8,8 @@
 </div>
 
 <div align="left">
-  <a href="https://www.npmjs.com/package/path-treeify">
-    <img alt="NPM Version" src="https://img.shields.io/npm/v/path-treeify">
+  <a href="https://github.com/isaaxite/path-treeify">
+    <img alt="GitHub package.json dynamic" src="https://img.shields.io/github/package-json/version/isaaxite/path-treeify?logo=github">
   </a>
   <a href="https://nodejs.org">
     <img alt="node" src="https://img.shields.io/node/v/path-treeify">
@@ -39,8 +39,7 @@
 - 🔗 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
-- ⚡ `build()` scans the entire `base` directory with zero configuration
-- 🎛️ `buildBy()` accepts either a directory name array or a filter function
+- ⚡ `build()` method scans the entire `base` directory with zero configuration
 - 📦 Ships as both ESM (`index.mjs`) and CJS (`index.cjs`) with full TypeScript types
 - 🚫 Zero runtime dependencies
 
@@ -71,11 +70,8 @@ import { PathTreeify } from 'path-treeify';
 
 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 specific directories
+const tree = treeify.buildByDirNames(['src', 'tests']);
 
 // Or scan everything under base at once
 const fullTree = treeify.build();
@@ -92,7 +88,7 @@ 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 |
+| `filter` | `FilterFunction` (see below)  | ❌        | Called for every directory found during traversal  |
 
 `base` must exist and be a directory, otherwise the constructor throws.
 
@@ -100,8 +96,6 @@ Creates a new instance.
 
 ### `FilterFunction`
 
-Used as the `filter` option in the constructor. Applied recursively during deep traversal of the tree.
-
 ```ts
 type FilterFunction = (params: {
   name: string;    // directory name (leaf segment)
@@ -111,7 +105,7 @@ type FilterFunction = (params: {
 
 Return `true` to **include** the directory and recurse into it; `false` to **skip** it.
 
-**Example — skip hidden directories and `node_modules` at every level:**
+**Example — skip hidden directories and `node_modules`:**
 
 ```ts
 const treeify = new PathTreeify({
@@ -124,7 +118,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` and returns a synthetic root `PathTreeNode`. This is the zero-configuration alternative to `buildByDirNames`.
 
 ```ts
 const tree = treeify.build();
@@ -132,26 +126,17 @@ const tree = treeify.build();
 
 ---
 
-### `buildBy(dirNames: string[]): PathTreeNode`
+### `buildByDirNames(dirNames: string[]): PathTreeNode`
 
-Builds a tree from the given list of directory names (relative to `base`).
+Scans the given relative directory names (resolved against `base`) and returns a synthetic root `PathTreeNode` whose `children` are the top-level nodes you requested.
 
 ```ts
-const tree = treeify.buildBy(['src', 'docs', 'tests']);
+const root = treeify.buildByDirNames(['src', 'docs']);
 ```
 
+- Each element must be a valid, accessible directory relative to `base`.
 - Leading and trailing slashes are stripped automatically.
-- Throws if any name does not resolve to a valid directory under `base`.
-
-### `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.
-
-```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.
+- Throws if any path does not exist or is not a directory.
 
 ---
 
@@ -160,14 +145,17 @@ const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith
 Walks a node's `parent` chain to reconstruct its full path. Equivalent to calling `node.getPath()` directly.
 
 ```ts
-const { relative, absolute } = treeify.getPathBy(node);
+const srcNode = root.children[0];
+const { relative, absolute } = treeify.getPathBy(srcNode);
+// relative → 'src'
+// absolute → '/your/project/src'
 ```
 
 ---
 
 ### `PathTreeNode`
 
-`PathTreeNode` is a **class** with its own `getPath()` method, so you can retrieve a node's path without passing it back to the `PathTreeify` instance.
+`PathTreeNode` is now a **class** with its own `getPath()` method, so you can retrieve a node's path without passing it back to the `PathTreeify` instance.
 
 ```ts
 class PathTreeNode {
@@ -192,30 +180,18 @@ class PathTreeNode {
 ```ts
 import { PathTreeify } from 'path-treeify';
 
-const treeify = new PathTreeify({ base: '/your/project' });
+const treeify = new PathTreeify({
+  base: '/your/project',
+  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
+});
+
 const tree = treeify.build();
 ```
 
 ### Scan specific directories
 
 ```ts
-const tree = treeify.buildBy(['src', 'tests', 'docs']);
-```
-
-### Filter top-level directories
-
-```ts
-const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
-```
-
-### Filter at every depth via constructor
-
-```ts
-const treeify = new PathTreeify({
-  base: '/your/project',
-  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
-});
-const tree = treeify.build();
+const tree = treeify.buildByDirNames(['src', 'tests', 'docs']);
 ```
 
 ### Retrieve paths via `node.getPath()`

package/dist/index.cjs

@@ -1 +1,159 @@
-"use strict";var t=require("fs"),r=require("path");class e{static isValid(r){try{return t.accessSync(r,t.constants.F_OK),!0}catch{return!1}}static isDirectory(r){try{return t.statSync(r).isDirectory()}catch{return!1}}}class i{constructor(t){this.parent=null,this.value="",this.children=[],this.base=t}getPath(){let t="",e=this;for(;e.parent;)t=t?`${e.value}${r.sep}${t}`:e.value,e=e.parent;return{relative:t,absolute:r.resolve(this.base,t)}}}exports.PathTreeify=class{constructor({filter:t,base:r}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!r||!e.isValid(r))throw new Error(`${r} is not a valid path!`);if(!e.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 i(this.base);return t&&(r.parent=t),r}buildChildren(e,i){const s=t.readdirSync(e),a=[];for(const n of s){const s=r.join(e,n);if(!t.statSync(s).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,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=r.resolve(this.base,s);if(!e.isValid(a))throw new Error(`Path does not exist or is not accessible: ${a} (from relative path: ${s})`);if(!e.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=r.resolve(this.base,t);return e.isDirectory(i)})}buildByDirNames(t){const e=this.initNode();this.checkRelativePaths(t);const i=this.formatDirnames(t);for(const t of i){const i=this.initNode();i.value=t,i.parent=e,i.children=this.buildChildren(r.resolve(this.base,t),i),e.children.push(i)}return e}buildByFilter(t){const r=this.getAllDirNamesUnderBase();return this.buildByDirNames(r.filter(t))}getPathBy(t){let e="",i=t;for(;i.parent;)e=e?`${i.value}${r.sep}${e}`:i.value,i=i.parent;return{relative:e,absolute:r.resolve(this.base,e)}}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 fs = require('fs');
+var path = require('path');
+
+class PathValidator {
+    static isValid(path) {
+        try {
+            fs.accessSync(path, fs.constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    static isDirectory(path) {
+        try {
+            return fs.statSync(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+class PathTreeNode {
+    constructor(base) {
+        this.parent = null;
+        this.value = '';
+        this.children = [];
+        this.base = base;
+    }
+    getPath() {
+        let relative = '';
+        let current = this;
+        while (current.parent) {
+            relative = relative
+                ? `${current.value}${path.sep}${relative}`
+                : current.value;
+            current = current.parent;
+        }
+        return { relative, absolute: path.resolve(this.base, relative) };
+    }
+}
+class PathTreeify {
+    constructor({ filter, base }) {
+        if (typeof filter !== 'undefined') {
+            this.validateFilter(filter);
+            this.filter = filter;
+        }
+        if (!base || !PathValidator.isValid(base)) {
+            throw new Error(`${base} is not a valid path!`);
+        }
+        if (!PathValidator.isDirectory(base)) {
+            throw new Error(`${base} is not a dirPath!`);
+        }
+        this.base = base;
+    }
+    validateFilter(filter) {
+        if (typeof filter !== 'function') {
+            throw new TypeError('filter must be a function');
+        }
+        if (filter.length !== 1) {
+            throw new TypeError('filter must accept exactly one parameter');
+        }
+        try {
+            const testResult = filter({ name: 'test', postPath: '/test' });
+            if (typeof testResult !== 'boolean') {
+                throw new TypeError('filter must return a boolean');
+            }
+        }
+        catch (error) {
+            throw new TypeError('filter function threw an error during test: ' + error);
+        }
+    }
+    initNode(parent = null) {
+        const node = new PathTreeNode(this.base);
+        if (parent) {
+            node.parent = parent;
+        }
+        return node;
+    }
+    buildChildren(dirPath, parent) {
+        const names = fs.readdirSync(dirPath);
+        const children = [];
+        for (const name of names) {
+            const subPath = path.join(dirPath, name);
+            if (!fs.statSync(subPath).isDirectory()) {
+                continue;
+            }
+            if (this.filter && !this.filter({ dirPath, name })) {
+                continue;
+            }
+            const node = this.initNode();
+            node.value = name;
+            node.parent = parent;
+            node.children = this.buildChildren(subPath, node);
+            children.push(node);
+        }
+        return children;
+    }
+    checkRelativePaths(relativeDirNames) {
+        if (!Array.isArray(relativeDirNames)) {
+            throw new Error(`Expected array, got ${typeof relativeDirNames}`);
+        }
+        for (let i = 0; i < relativeDirNames.length; i++) {
+            const it = relativeDirNames[i];
+            if (typeof it !== 'string') {
+                throw new Error(`Item at index ${i} is not a string, got ${typeof it}`);
+            }
+            const absPath = path.resolve(this.base, it);
+            if (!PathValidator.isValid(absPath)) {
+                throw new Error(`Path does not exist or is not accessible: ${absPath} (from relative path: ${it})`);
+            }
+            if (!PathValidator.isDirectory(absPath)) {
+                throw new Error(`Path is not a directory: ${absPath} (from relative path: ${it})`);
+            }
+        }
+    }
+    formatDirnames(dirNames) {
+        return dirNames.map(dir => {
+            // Remove leading and trailing slashes
+            return dir.replace(/^\/+|\/+$/g, '');
+        }).filter(dir => dir !== ''); // Optional: filter empty strings
+    }
+    getPathBy(node) {
+        let relative = '';
+        let current = node;
+        while (current.parent) {
+            relative = relative
+                ? `${current.value}${path.sep}${relative}`
+                : current.value;
+            current = current.parent;
+        }
+        return { relative, absolute: path.resolve(this.base, relative) };
+    }
+    buildByDirNames(dirNames) {
+        const root = this.initNode();
+        this.checkRelativePaths(dirNames);
+        const dirNameArr = this.formatDirnames(dirNames);
+        for (const dirName of dirNameArr) {
+            const node = this.initNode();
+            node.value = dirName;
+            node.parent = root;
+            node.children = this.buildChildren(path.resolve(this.base, dirName), node);
+            root.children.push(node);
+        }
+        return root;
+    }
+    build() {
+        const dirNameArr = fs.readdirSync(this.base).filter(name => {
+            const abs = path.resolve(this.base, name);
+            return PathValidator.isDirectory(abs);
+        });
+        return this.buildByDirNames(dirNameArr);
+    }
+}
+
+exports.PathTreeify = PathTreeify;
+//# sourceMappingURL=index.cjs.map

package/dist/index.mjs

@@ -1 +1,157 @@
-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)})}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, statSync, accessSync, constants } from 'fs';
+import { join, resolve, sep } from 'path';
+
+class PathValidator {
+    static isValid(path) {
+        try {
+            accessSync(path, constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    static isDirectory(path) {
+        try {
+            return statSync(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+class PathTreeNode {
+    constructor(base) {
+        this.parent = null;
+        this.value = '';
+        this.children = [];
+        this.base = base;
+    }
+    getPath() {
+        let relative = '';
+        let current = this;
+        while (current.parent) {
+            relative = relative
+                ? `${current.value}${sep}${relative}`
+                : current.value;
+            current = current.parent;
+        }
+        return { relative, absolute: resolve(this.base, relative) };
+    }
+}
+class PathTreeify {
+    constructor({ filter, base }) {
+        if (typeof filter !== 'undefined') {
+            this.validateFilter(filter);
+            this.filter = filter;
+        }
+        if (!base || !PathValidator.isValid(base)) {
+            throw new Error(`${base} is not a valid path!`);
+        }
+        if (!PathValidator.isDirectory(base)) {
+            throw new Error(`${base} is not a dirPath!`);
+        }
+        this.base = base;
+    }
+    validateFilter(filter) {
+        if (typeof filter !== 'function') {
+            throw new TypeError('filter must be a function');
+        }
+        if (filter.length !== 1) {
+            throw new TypeError('filter must accept exactly one parameter');
+        }
+        try {
+            const testResult = filter({ name: 'test', postPath: '/test' });
+            if (typeof testResult !== 'boolean') {
+                throw new TypeError('filter must return a boolean');
+            }
+        }
+        catch (error) {
+            throw new TypeError('filter function threw an error during test: ' + error);
+        }
+    }
+    initNode(parent = null) {
+        const node = new PathTreeNode(this.base);
+        if (parent) {
+            node.parent = parent;
+        }
+        return node;
+    }
+    buildChildren(dirPath, parent) {
+        const names = readdirSync(dirPath);
+        const children = [];
+        for (const name of names) {
+            const subPath = join(dirPath, name);
+            if (!statSync(subPath).isDirectory()) {
+                continue;
+            }
+            if (this.filter && !this.filter({ dirPath, name })) {
+                continue;
+            }
+            const node = this.initNode();
+            node.value = name;
+            node.parent = parent;
+            node.children = this.buildChildren(subPath, node);
+            children.push(node);
+        }
+        return children;
+    }
+    checkRelativePaths(relativeDirNames) {
+        if (!Array.isArray(relativeDirNames)) {
+            throw new Error(`Expected array, got ${typeof relativeDirNames}`);
+        }
+        for (let i = 0; i < relativeDirNames.length; i++) {
+            const it = relativeDirNames[i];
+            if (typeof it !== 'string') {
+                throw new Error(`Item at index ${i} is not a string, got ${typeof it}`);
+            }
+            const absPath = resolve(this.base, it);
+            if (!PathValidator.isValid(absPath)) {
+                throw new Error(`Path does not exist or is not accessible: ${absPath} (from relative path: ${it})`);
+            }
+            if (!PathValidator.isDirectory(absPath)) {
+                throw new Error(`Path is not a directory: ${absPath} (from relative path: ${it})`);
+            }
+        }
+    }
+    formatDirnames(dirNames) {
+        return dirNames.map(dir => {
+            // Remove leading and trailing slashes
+            return dir.replace(/^\/+|\/+$/g, '');
+        }).filter(dir => dir !== ''); // Optional: filter empty strings
+    }
+    getPathBy(node) {
+        let relative = '';
+        let current = node;
+        while (current.parent) {
+            relative = relative
+                ? `${current.value}${sep}${relative}`
+                : current.value;
+            current = current.parent;
+        }
+        return { relative, absolute: resolve(this.base, relative) };
+    }
+    buildByDirNames(dirNames) {
+        const root = this.initNode();
+        this.checkRelativePaths(dirNames);
+        const dirNameArr = this.formatDirnames(dirNames);
+        for (const dirName of dirNameArr) {
+            const node = this.initNode();
+            node.value = dirName;
+            node.parent = root;
+            node.children = this.buildChildren(resolve(this.base, dirName), node);
+            root.children.push(node);
+        }
+        return root;
+    }
+    build() {
+        const dirNameArr = readdirSync(this.base).filter(name => {
+            const abs = resolve(this.base, name);
+            return PathValidator.isDirectory(abs);
+        });
+        return this.buildByDirNames(dirNameArr);
+    }
+}
+
+export { PathTreeify };
+//# sourceMappingURL=index.mjs.map

package/dist/types/index.d.ts

@@ -26,15 +26,11 @@ export declare class PathTreeify {
     private buildChildren;
     private checkRelativePaths;
     private formatDirnames;
-    private getAllDirNamesUnderBase;
-    private buildByDirNames;
-    private buildByFilter;
     getPathBy(node: PathTreeNode): {
         relative: string;
         absolute: string;
     };
-    buildBy(dirNames: string[]): PathTreeNode;
-    buildBy(filter: (dirName: string) => boolean): PathTreeNode;
+    buildByDirNames(dirNames: string[]): PathTreeNode;
     build(): PathTreeNode;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-treeify",
-  "version": "1.1.0-beta.94a5d17",
+  "version": "1.1.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",