path-treeify 1.3.0-beta.45ab046 → 1.3.0-beta.56a60fd

package/README.md

@@ -1,4 +1,7 @@
-# path-treeify
+<div align="center">
+  <img alt="LOGO" width="320" src="https://assets-amu.pages.dev/path-treeify/logo.png">
+</div>
+<br/>
 
 > 📖 [中文文档 (Chinese README)](https://github.com/isaaxite/path-treeify/blob/main/docs/README.zh-CN.md)
 
@@ -14,6 +17,9 @@
   <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/CHANGELOG.md">
+    <img alt="CHANGELOG" src="https://img.shields.io/badge/changelog-maintained-brightgreen">
+  </a>
   <a href="https://github.com/isaaxite/path-treeify/blob/main/LICENSE">
     <img alt="GitHub License" src="https://img.shields.io/github/license/isaaxite/path-treeify">
   </a>
@@ -253,4 +259,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(),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)}};
+"use strict";var e,t=require("fs"),r=require("path");class i{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}}static isFile(e){try{return t.statSync(e).isFile()}catch{return!1}}}exports.PathTreeNodeType=void 0,(e=exports.PathTreeNodeType||(exports.PathTreeNodeType={})).Dir="dir",e.File="file",e.Unknown="unknown";class s{constructor(){this.parent=null,this.value="",this.children=[],this.type=exports.PathTreeNodeType.Unknown}getPath(){let e="",t=this;for(;t.parent;)e=e?`${t.value}${r.sep}${e}`:t.value,t=t.parent;return e}}exports.PathTreeNode=s,exports.PathTreeify=class{applyFilter(e,t){return!(!this.fileVisible&&!i.isDirectory(e))&&(!this.userFilter||this.userFilter({name:t,dirPath:r.dirname(e)}))}constructor({filter:e,base:t,fileVisible:r}){if(this.fileVisible=!1,"boolean"==typeof r&&r&&(this.fileVisible=r),void 0!==e&&(this.validateFilter(e),this.userFilter=e),!t||!i.isValid(t))throw new Error(`${t} is not a valid path!`);if(!i.isDirectory(t))throw new Error(`${t} is not a dirPath!`);this.base=t}validateFilter(e){if("function"!=typeof e)throw new TypeError("filter must be a function")}initNode(){return new s}buildChildren(e,s){const n=[],o=t.readdirSync(e);for(const t of o){const o=r.join(e,t);if(!this.applyFilter(o,t))continue;const l=this.initNode();l.value=t,l.parent=s,n.push(l),this.fileVisible&&i.isFile(o)?l.type=exports.PathTreeNodeType.File:(l.type=exports.PathTreeNodeType.Dir,l.children=this.buildChildren(o,l))}return n}checkRelativePaths(e){if(!Array.isArray(e))throw new Error("Expected array, got "+typeof e);for(let t=0;t<e.length;t++){const s=e[t];if("string"!=typeof s)throw new Error(`Item at index ${t} is not a string, got ${typeof s}`);const n=r.resolve(this.base,s);if(!i.isValid(n))throw new Error(`Path does not exist or is not accessible: ${n} (from relative path: ${s})`);if(!(i.isDirectory(n)||this.fileVisible&&i.isFile(n)))throw new Error(`Path is not a directory: ${n} (from relative path: ${s})`)}}formatSegments(e){return e.map(e=>e.split(/[/\\]/).filter(Boolean).join(r.sep)).filter(Boolean)}getAllEntriesUnderBase(){return t.readdirSync(this.base).filter(e=>{const t=r.resolve(this.base,e);return this.applyFilter(t,e)})}buildBySegments(e){const t=this.initNode(),s=this.formatSegments(e);this.checkRelativePaths(s);for(const e of s){const s=r.resolve(this.base,e),n=this.initNode();n.value=e,n.parent=t,t.children.push(n),this.fileVisible&&i.isFile(s)?n.type=exports.PathTreeNodeType.File:(n.type=exports.PathTreeNodeType.Dir,n.children=this.buildChildren(s,n))}return t}buildByFilter(e){const t=this.getAllEntriesUnderBase();return this.buildBySegments(t.filter(e))}getPathBy(e){const t=e.getPath();return{relative:t,absolute:r.resolve(this.base,t)}}buildBy(e){if(Array.isArray(e))return this.buildBySegments(e);if("function"==typeof e)return this.buildByFilter(e);throw new TypeError("buildBy: expected an array of strings or a filter function, but received "+typeof e)}build(){const e=this.getAllEntriesUnderBase();return this.buildBySegments(e)}};

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(),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};
+import{readdirSync as t,accessSync as i,constants as e,statSync as r}from"fs";import{sep as s,dirname as n,join as l,resolve as o}from"path";class a{static isValid(t){try{return i(t,e.F_OK),!0}catch{return!1}}static isDirectory(t){try{return r(t).isDirectory()}catch{return!1}}static isFile(t){try{return r(t).isFile()}catch{return!1}}}var h;!function(t){t.Dir="dir",t.File="file",t.Unknown="unknown"}(h||(h={}));class c{constructor(){this.parent=null,this.value="",this.children=[],this.type=h.Unknown}getPath(){let t="",i=this;for(;i.parent;)t=t?`${i.value}${s}${t}`:i.value,i=i.parent;return t}}class u{applyFilter(t,i){return!(!this.fileVisible&&!a.isDirectory(t))&&(!this.userFilter||this.userFilter({name:i,dirPath:n(t)}))}constructor({filter:t,base:i,fileVisible:e}){if(this.fileVisible=!1,"boolean"==typeof e&&e&&(this.fileVisible=e),void 0!==t&&(this.validateFilter(t),this.userFilter=t),!i||!a.isValid(i))throw new Error(`${i} is not a valid path!`);if(!a.isDirectory(i))throw new Error(`${i} is not a dirPath!`);this.base=i}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function")}initNode(){return new c}buildChildren(i,e){const r=[],s=t(i);for(const t of s){const s=l(i,t);if(!this.applyFilter(s,t))continue;const n=this.initNode();n.value=t,n.parent=e,r.push(n),this.fileVisible&&a.isFile(s)?n.type=h.File:(n.type=h.Dir,n.children=this.buildChildren(s,n))}return r}checkRelativePaths(t){if(!Array.isArray(t))throw new Error("Expected array, got "+typeof t);for(let i=0;i<t.length;i++){const e=t[i];if("string"!=typeof e)throw new Error(`Item at index ${i} is not a string, got ${typeof e}`);const r=o(this.base,e);if(!a.isValid(r))throw new Error(`Path does not exist or is not accessible: ${r} (from relative path: ${e})`);if(!(a.isDirectory(r)||this.fileVisible&&a.isFile(r)))throw new Error(`Path is not a directory: ${r} (from relative path: ${e})`)}}formatSegments(t){return t.map(t=>t.split(/[/\\]/).filter(Boolean).join(s)).filter(Boolean)}getAllEntriesUnderBase(){return t(this.base).filter(t=>{const i=o(this.base,t);return this.applyFilter(i,t)})}buildBySegments(t){const i=this.initNode(),e=this.formatSegments(t);this.checkRelativePaths(e);for(const t of e){const e=o(this.base,t),r=this.initNode();r.value=t,r.parent=i,i.children.push(r),this.fileVisible&&a.isFile(e)?r.type=h.File:(r.type=h.Dir,r.children=this.buildChildren(e,r))}return i}buildByFilter(t){const i=this.getAllEntriesUnderBase();return this.buildBySegments(i.filter(t))}getPathBy(t){const i=t.getPath();return{relative:i,absolute:o(this.base,i)}}buildBy(t){if(Array.isArray(t))return this.buildBySegments(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.getAllEntriesUnderBase();return this.buildBySegments(t)}}export{c as PathTreeNode,h as PathTreeNodeType,u as PathTreeify};

package/dist/types/index.d.ts

@@ -1,93 +1,120 @@
-/** A filter function that determines whether a directory should be included in the tree */
+/** A filter function that determines whether an entry should be included in the tree */
 type FilterFunction = (params: {
     name: string;
     dirPath: string;
 }) => boolean;
 /** Constructor options for PathTreeify */
 interface PathTreeifyProps {
+    /** The root directory to scan */
     base: string;
+    /** Optional filter applied to every entry during recursive traversal */
     filter?: FilterFunction;
+    /** When true, files are included as leaf nodes alongside directories. Defaults to false */
+    fileVisible?: boolean;
 }
-/** Represents a single node (directory) in the path tree */
-declare class PathTreeNode {
-    /** The root base path used to resolve absolute paths */
-    private base;
+/** Classification of a node in the path tree */
+export declare enum PathTreeNodeType {
+    Dir = "dir",
+    File = "file",
+    /** Assigned before the node's type has been resolved */
+    Unknown = "unknown"
+}
+/** Represents a single entry (directory or file) in the path tree */
+export declare class PathTreeNode {
     /** Reference to the parent node; null for the root node */
     parent: PathTreeNode | null;
-    /** The directory name of this node (not a full path) */
+    /** The entry name of this node (not a full path) */
     value: string;
-    /** Child nodes representing subdirectories */
+    /** Child nodes; non-empty only for directory nodes */
     children: PathTreeNode[];
-    constructor(base: string);
+    /** Whether this node is a directory, a file, or not yet resolved */
+    type: PathTreeNodeType;
     /**
-     * Walks up the parent chain to compute this node's relative and absolute paths.
-     * @returns An object containing the relative path from base and the absolute path
+     * Walks up the parent chain to compute this node's relative path from the tree root.
+     * @returns The relative path string using the platform separator
      */
-    getPath(): {
-        relative: string;
-        absolute: string;
-    };
+    getPath(): string;
 }
-/** Builds a tree of directory nodes rooted at a given base path */
+/** Builds a tree of {@link PathTreeNode} entries rooted at a given base path */
 export declare class PathTreeify {
     /** The root directory to scan */
     private base;
-    /** Optional filter applied to each directory during traversal */
-    private filter?;
-    constructor({ filter, base }: Partial<PathTreeifyProps>);
     /**
-     * Validates that the provided filter is a function, accepts one parameter,
-     * and returns a boolean. Throws a TypeError if any condition is violated.
+     * Optional user-supplied filter. When set, every entry must pass this predicate
+     * in addition to the built-in visibility check.
      */
-    private validateFilter;
+    private userFilter?;
+    /** When true, files are included as leaf nodes during traversal. Defaults to false */
+    private fileVisible;
+    /**
+     * Determines whether a given entry should be included in the tree.
+     * - If {@link fileVisible} is false, non-directory entries are always excluded.
+     * - If a {@link userFilter} is set, the entry must also satisfy it.
+     * @param absPath - Absolute path of the entry to test
+     * @param name - Entry name (filename or directory name)
+     */
+    private applyFilter;
+    constructor({ filter, base, fileVisible }: Partial<PathTreeifyProps>);
     /**
-     * Creates and optionally attaches a new PathTreeNode to a parent.
-     * @param parent - The parent node to attach to, or null for the root
+     * Asserts that the provided value is a callable {@link FilterFunction}.
+     * Throws a TypeError if the check fails.
      */
+    private validateFilter;
+    /** Creates a new unattached {@link PathTreeNode} */
     private initNode;
     /**
-     * Recursively reads a directory and builds child nodes for each subdirectory.
-     * Applies the instance-level filter if one is set.
+     * Recursively reads {@link dirPath} and builds child nodes for each entry that
+     * passes {@link applyFilter}. Directories are traversed depth-first;
+     * files (when {@link fileVisible} is true) become leaf nodes.
      * @param dirPath - Absolute path of the directory to read
-     * @param parent - The parent node to attach children to
+     * @param parent - The parent node to attach child nodes to
      */
     private buildChildren;
     /**
-     * Validates that each entry in the array is a string pointing to
-     * an accessible directory relative to the base path.
-     * @param relativeDirNames - Array of relative directory path strings to validate
+     * Validates that every entry in {@link relativeSegments} refers to an accessible
+     * path under {@link base}. When {@link fileVisible} is false, each path must be
+     * a directory; when true, regular files are also accepted.
+     * @param relativeSegments - Relative path strings to validate
      */
     private checkRelativePaths;
     /**
-     * Strips leading and trailing slashes from each directory name
-     * and removes any resulting empty strings.
+     * Normalises an array of path strings by splitting on both slash styles,
+     * dropping empty segments, and rejoining with the platform separator.
+     * Entries that reduce to an empty string (e.g. `"///"`) are removed.
+     * @param segments - Raw path strings to normalise
+     */
+    private formatSegments;
+    /**
+     * Returns the names of all immediate entries under {@link base} that pass
+     * {@link applyFilter}.
      */
-    private formatDirnames;
-    /** Returns the names of all immediate subdirectories under the base path */
-    private getAllDirNamesUnderBase;
+    private getAllEntriesUnderBase;
     /**
-     * Builds a tree rooted at base, containing only the specified subdirectories.
-     * @param dirNames - Relative directory names to include as top-level nodes
+     * Builds a subtree containing only the entries identified by {@link segments}.
+     * Paths are normalised via {@link formatSegments} and validated before use.
+     * @param segments - Relative paths to include as top-level nodes
      */
-    private buildByDirNames;
+    private buildBySegments;
     /**
-     * Builds a tree using only the subdirectories under base that pass the given filter.
-     * @param filter - A predicate applied to each top-level directory name
+     * Builds a subtree from top-level entries whose names satisfy {@link filter}.
+     * Note: this predicate only affects top-level selection, not recursive traversal.
+     * For recursive filtering use the `filter` constructor option.
+     * @param filter - Predicate applied to each top-level entry name
      */
     private buildByFilter;
     /**
-     * Computes the relative and absolute paths for a given node
-     * by walking up the parent chain.
+     * Returns the relative and absolute paths for a given node by delegating to
+     * {@link PathTreeNode.getPath} and resolving against {@link base}.
      */
     getPathBy(node: PathTreeNode): {
         relative: string;
         absolute: string;
     };
-    /** Overload: build the tree from an explicit list of relative directory names */
-    buildBy(dirNames: string[]): PathTreeNode;
-    /** Overload: build the tree from a predicate applied to top-level directory names */
-    buildBy(filter: (dirName: string) => boolean): PathTreeNode;
-    /** Builds a full tree from all immediate subdirectories under the base path */
+    /** Overload: build the tree from an explicit list of relative path segments */
+    buildBy(segments: string[]): PathTreeNode;
+    /** Overload: build the tree from a predicate applied to top-level entry names */
+    buildBy(filter: (segment: string) => boolean): PathTreeNode;
+    /** Builds a full tree from all immediate entries under the base path */
     build(): PathTreeNode;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-treeify",
-  "version": "1.3.0-beta.45ab046",
+  "version": "1.3.0-beta.56a60fd",
   "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",
@@ -95,6 +95,7 @@
     "rollup": "^4.59.0",
     "tap-xunit": "^2.4.1",
     "tslib": "^2.8.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
   "engines": {