path-treeify 1.0.0 → 1.1.0-beta.94a5d17

package/README.md

@@ -8,14 +8,14 @@
 </div>
 
 <div align="left">
-  <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 href="https://www.npmjs.com/package/path-treeify">
+    <img alt="NPM Version" src="https://img.shields.io/npm/v/path-treeify">
   </a>
   <a href="https://nodejs.org">
     <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,10 @@
 
 - 🌲 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()` scans the entire `base` directory with zero configuration
+- 🎛️ `buildBy()` accepts either a directory name array or a filter function
 - 📦 Ships as both ESM (`index.mjs`) and CJS (`index.cjs`) with full TypeScript types
 - 🚫 Zero runtime dependencies
 
@@ -68,18 +71,14 @@ import { PathTreeify } from 'path-treeify';
 
 const treeify = new PathTreeify({ base: '/your/project/root' });
 
-// Scan the whole base directory
-const tree = treeify.buildByDirPaths(['src', 'tests']);
+// 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');
 
-console.log(tree);
-// {
-//   parent: null,
-//   value: '',
-//   children: [
-//     { parent: [Circular], value: 'src',   children: [...] },
-//     { parent: [Circular], value: 'tests', children: [...] }
-//   ]
-// }
+// Or scan everything under base at once
+const fullTree = treeify.build();
 ```
 
 ---
@@ -90,10 +89,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 deep traversal |
 
 `base` must exist and be a directory, otherwise the constructor throws.
 
@@ -101,6 +100,8 @@ 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)
@@ -110,7 +111,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`:**
+**Example — skip hidden directories and `node_modules` at every level:**
 
 ```ts
 const treeify = new PathTreeify({
@@ -121,78 +122,114 @@ const treeify = new PathTreeify({
 
 ---
 
-### `buildByDirPaths(paths: string[]): PathTreeNode`
+### `build(): PathTreeNode`
+
+Scans **all** subdirectories directly under `base` and returns a synthetic root `PathTreeNode`. This is the zero-configuration shorthand.
+
+```ts
+const tree = treeify.build();
+```
+
+---
+
+### `buildBy(dirNames: string[]): 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.
+Builds a tree from the given list of directory names (relative to `base`).
 
 ```ts
-const root = treeify.buildByDirPaths(['src', 'docs']);
+const tree = treeify.buildBy(['src', 'docs', 'tests']);
 ```
 
-- Each element of `paths` 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.
+- 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.
 
 ---
 
 ### `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];
-const { relative, absolute } = treeify.getPathBy(srcNode);
-// relative → 'src'
-// absolute → '/your/project/src'
+const { relative, absolute } = treeify.getPathBy(node);
 ```
 
 ---
 
 ### `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.
+
 ```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' });
+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('.'));
+```
 
-// Collect all top-level directories
-const topLevel = readdirSync(base, { withFileTypes: true })
-  .filter(d => d.isDirectory())
-  .map(d => d.name);
+### Filter at every depth via constructor
 
-const tree = treeify.buildByDirPaths(topLevel);
+```ts
+const treeify = new PathTreeify({
+  base: '/your/project',
+  filter: ({ name }) => name !== 'node_modules' && !name.startsWith('.'),
+});
+const tree = treeify.build();
 ```
 
-### 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 +238,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 @@
-"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 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)}};

package/dist/index.mjs

@@ -1 +1 @@
-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 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};

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,17 @@ export declare class PathTreeify {
     private validateFilter;
     private initNode;
     private buildChildren;
-    private checkRelatePaths;
+    private checkRelativePaths;
     private formatDirnames;
+    private getAllDirNamesUnderBase;
+    private buildByDirNames;
+    private buildByFilter;
     getPathBy(node: PathTreeNode): {
         relative: string;
         absolute: string;
     };
-    buildByDirPaths(nameOfDirs: string[]): PathTreeNode;
+    buildBy(dirNames: string[]): PathTreeNode;
+    buildBy(filter: (dirName: string) => boolean): PathTreeNode;
+    build(): PathTreeNode;
 }
 export {};

package/package.json

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