path-treeify 1.0.0 → 1.1.0

package/README.md

@@ -15,7 +15,7 @@
     <img alt="node" src="https://img.shields.io/node/v/path-treeify">
   </a>
   <a href="https://github.com/isaaxite/path-treeify/blob/main/LICENSE">
-    <img alt="license" src="https://img.shields.io/npm/l/path-treeify">
+    <img alt="GitHub License" src="https://img.shields.io/github/license/isaaxite/path-treeify">
   </a>
   <a href="https://github.com/isaaxite/path-treeify">
     <img alt="GitHub Created At" src="https://img.shields.io/github/created-at/isaaxite/path-treeify">
@@ -37,7 +37,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
+- ⚡ `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
 
@@ -68,18 +70,11 @@ import { PathTreeify } from 'path-treeify';
 
 const treeify = new PathTreeify({ base: '/your/project/root' });
 
-// Scan the whole base directory
-const tree = treeify.buildByDirPaths(['src', 'tests']);
-
-console.log(tree);
-// {
-//   parent: null,
-//   value: '',
-//   children: [
-//     { parent: [Circular], value: 'src',   children: [...] },
-//     { parent: [Circular], value: 'tests', children: [...] }
-//   ]
-// }
+// Scan specific directories
+const tree = treeify.buildByDirNames(['src', 'tests']);
+
+// Or scan everything under base at once
+const fullTree = treeify.build();
 ```
 
 ---
@@ -90,10 +85,10 @@ console.log(tree);
 
 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 traversal |
+| 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 traversal  |
 
 `base` must exist and be a directory, otherwise the constructor throws.
 
@@ -121,15 +116,25 @@ const treeify = new PathTreeify({
 
 ---
 
-### `buildByDirPaths(paths: string[]): PathTreeNode`
+### `build(): PathTreeNode`
 
-Scans the given relative directory paths (resolved against `base`) and returns a synthetic root `PathTreeNode` whose `children` are the top-level nodes you requested.
+Scans **all** subdirectories directly under `base` and returns a synthetic root `PathTreeNode`. This is the zero-configuration alternative to `buildByDirNames`.
 
 ```ts
-const root = treeify.buildByDirPaths(['src', 'docs']);
+const tree = treeify.build();
 ```
 
-- Each element of `paths` must be a valid, accessible directory relative to `base`.
+---
+
+### `buildByDirNames(dirNames: string[]): PathTreeNode`
+
+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 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 path does not exist or is not a directory.
 
@@ -137,7 +142,7 @@ const root = treeify.buildByDirPaths(['src', 'docs']);
 
 ### `getPathBy(node: PathTreeNode): { relative: string; absolute: string }`
 
-Walks a node's `parent` chain to reconstruct its full path.
+Walks a node's `parent` chain to reconstruct its full path. Equivalent to calling `node.getPath()` directly.
 
 ```ts
 const srcNode = root.children[0];
@@ -150,49 +155,57 @@ const { relative, absolute } = treeify.getPathBy(srcNode);
 
 ### `PathTreeNode`
 
+`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
-interface PathTreeNode {
+class PathTreeNode {
   parent:   PathTreeNode | null; // null only on the synthetic root
   value:    string;              // directory name for this node
   children: PathTreeNode[];
+
+  getPath(): { relative: string; absolute: string };
 }
 ```
 
+**`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.
 
 ---
 
 ## Examples
 
-### Scan an entire directory
+### Scan an entire base directory
 
 ```ts
 import { PathTreeify } from 'path-treeify';
-import { readdirSync } from 'fs';
 
-const base = '/your/project';
-const treeify = new PathTreeify({ base });
+const treeify = new PathTreeify({
+  base: '/your/project',
+  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
+});
+
+const tree = treeify.build();
+```
 
-// Collect all top-level directories
-const topLevel = readdirSync(base, { withFileTypes: true })
-  .filter(d => d.isDirectory())
-  .map(d => d.name);
+### Scan specific directories
 
-const tree = treeify.buildByDirPaths(topLevel);
+```ts
+const tree = treeify.buildByDirNames(['src', 'tests', 'docs']);
 ```
 
-### Retrieve absolute paths while walking
+### Retrieve paths via `node.getPath()`
 
 ```ts
-function printPaths(node, treeify) {
+function printPaths(node) {
   for (const child of node.children) {
-    const { absolute } = treeify.getPathBy(child);
+    const { absolute } = child.getPath();
     console.log(absolute);
-    printPaths(child, treeify);
+    printPaths(child);
   }
 }
 
-printPaths(tree, treeify);
+printPaths(tree);
 ```
 
 ### CommonJS usage
@@ -201,11 +214,11 @@ printPaths(tree, treeify);
 const { PathTreeify } = require('path-treeify');
 
 const treeify = new PathTreeify({ base: __dirname });
-const tree = treeify.buildByDirPaths(['src']);
+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,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}}}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){return{parent:t,value:"",children:[]}}buildChildren(e,i){const o=t.readdirSync(e),s=[];for(const n of o){const o=r.join(e,n);if(!t.statSync(o).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,name:n}))continue;const a=this.initNode();a.value=n,a.parent=i,a.children=this.buildChildren(o,a),s.push(a)}return s}checkRelatePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let i=0;i<t.length;i++){const o=t[i];if("string"!=typeof o)throw new Error(`Item at index ${i} is not a string, got ${typeof o}`);const s=r.resolve(this.base,o);if(!e.isValid(s))throw new Error(`Path does not exist or is not accessible: ${s} (from relative path: ${o})`);if(!e.isDirectory(s))throw new Error(`Path is not a directory: ${s} (from relative path: ${o})`)}}formatDirnames(t){return t.map(t=>t.replace(/^\/+|\/+$/g,"")).filter(t=>""!==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)}}buildByDirPaths(t){const e=this.initNode();this.checkRelatePaths(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}};
+'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 o,resolve as n,sep as a}from"path";class s{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 h{constructor({filter:t,base:r}){if(void 0!==t&&(this.validateFilter(t),this.filter=t),!r||!s.isValid(r))throw new Error(`${r} is not a valid path!`);if(!s.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){return{parent:t,value:"",children:[]}}buildChildren(e,i){const n=t(e),a=[];for(const t of n){const n=o(e,t);if(!r(n).isDirectory())continue;if(this.filter&&!this.filter({dirPath:e,name:t}))continue;const s=this.initNode();s.value=t,s.parent=i,s.children=this.buildChildren(n,s),a.push(s)}return a}checkRelatePaths(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=n(this.base,e);if(!s.isValid(i))throw new Error(`Path does not exist or is not accessible: ${i} (from relative path: ${e})`);if(!s.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)}getPathBy(t){let r="",e=t;for(;e.parent;)r=r?`${e.value}${a}${r}`:e.value,e=e.parent;return{relative:r,absolute:n(this.base,r)}}buildByDirPaths(t){const r=this.initNode();this.checkRelatePaths(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(n(this.base,t),e),r.children.push(e)}return r}}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

@@ -6,10 +6,16 @@ interface PathTreeifyProps {
     base: string;
     filter?: FilterFunction;
 }
-interface PathTreeNode {
+declare class PathTreeNode {
+    private base;
     parent: PathTreeNode | null;
     value: string;
     children: PathTreeNode[];
+    constructor(base: string);
+    getPath(): {
+        relative: string;
+        absolute: string;
+    };
 }
 export declare class PathTreeify {
     private base;
@@ -18,12 +24,13 @@ export declare class PathTreeify {
     private validateFilter;
     private initNode;
     private buildChildren;
-    private checkRelatePaths;
+    private checkRelativePaths;
     private formatDirnames;
     getPathBy(node: PathTreeNode): {
         relative: string;
         absolute: string;
     };
-    buildByDirPaths(nameOfDirs: string[]): PathTreeNode;
+    buildByDirNames(dirNames: string[]): PathTreeNode;
+    build(): PathTreeNode;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-treeify",
-  "version": "1.0.0",
+  "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",
@@ -21,10 +21,7 @@
   "files": [
     "dist/index.cjs",
     "dist/index.mjs",
-    "dist/**/*.d.ts",
-    "README.md",
-    "!README.zh-CN.md",
-    "LICENSE"
+    "dist/**/*.d.ts"
   ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -32,9 +29,10 @@
     "build": "npm run clean && rollup -c",
     "build:dev": "NODE_ENV=development npm run build",
     "build:prod": "NODE_ENV=production npm run build",
-    "build:watch": "nodemon --watch src -e ts --exec \"npm run build:dev\"",
+    "build:watch": "nodemon --watch index.ts -e ts --exec \"npm run build:dev\"",
     "check-publish": "npm pack --dry-run",
-    "publish": "npm publish"
+    "publish:beta": "npm publish --tag beta --access public",
+    "publish:latest": "npm publish --tag latest --access public"
   },
   "repository": {
     "type": "git",