path-treeify 1.3.0 → 1.4.0-beta.31d8864

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>
@@ -21,7 +27,7 @@
     <img alt="GitHub Created At" src="https://img.shields.io/github/created-at/isaaxite/path-treeify">
   </a>
   <a href="https://github.com/isaaxite/path-treeify">
-    <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/isaaxite/path-treeify">
+    <img alt="NPM Unpacked Size" src="https://img.shields.io/npm/unpacked-size/path-treeify">
   </a>
   <a href="https://github.com/isaaxite/path-treeify/commits/main/">
     <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/isaaxite/path-treeify">
@@ -29,8 +35,8 @@
   <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 href='https://github.com/isaaxite/path-treeify/actions/workflows/unittests.yml'>
+    <img src='https://github.com/isaaxite/path-treeify/actions/workflows/unittests.yml/badge.svg' alt='Test CI 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' />
@@ -44,9 +50,13 @@
 - 🌲 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 applied at **every depth**, including top-level directories
+- 🏷️ Each node has a `type` field — `PathTreeNodeKind.Dir` or `PathTreeNodeKind.File`
+- 📏 Each node has a `depth` field indicating its distance from the root
+- 👁️ `fileVisible` option includes files as leaf nodes alongside directories
+- 🔍 Optional `filter` callback applied at **every depth**, including top-level entries
 - ⚡ `build()` scans the entire `base` directory with zero configuration
-- 🎛️ `buildBy()` accepts either a directory name array or a top-level filter function
+- 🎛️ `buildBy()` accepts either a path segment array or a top-level filter function
+- 🗃️ `usePathCache` option caches `getPath()` results per node for repeated access
 - 📦 Ships as both ESM (`index.mjs`) and CJS (`index.cjs`) with full TypeScript types
 - 🚫 Zero runtime dependencies
 
@@ -73,18 +83,27 @@ yarn add path-treeify
 ## Quick Start
 
 ```ts
-import { PathTreeify } from 'path-treeify';
+import { PathTreeify, PathTreeNodeKind } from 'path-treeify';
 
+// Directories only (default)
 const treeify = new PathTreeify({ base: '/your/project/root' });
+const tree = treeify.build();
 
-// Scan specific directories by name
-const tree = treeify.buildBy(['src', 'tests']);
-
-// 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();
+// Include files as leaf nodes
+const treeifyWithFiles = new PathTreeify({
+  base: '/your/project/root',
+  fileVisible: true,
+});
+const fullTree = treeifyWithFiles.build();
+
+// Check node type and depth
+for (const child of tree.children) {
+  if (child.type === PathTreeNodeKind.Dir) {
+    console.log(`dir (depth ${child.depth}):`, child.value);
+  } else if (child.type === PathTreeNodeKind.File) {
+    console.log(`file (depth ${child.depth}):`, child.value);
+  }
+}
 ```
 
 ---
@@ -95,10 +114,12 @@ 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)  | ❌        | Applied at **every depth** — top-level directories included                |
+| 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 entries included                            |
+| `fileVisible`  | `boolean`                    | ❌        | When `true`, files are included as leaf nodes. Defaults to `false`                 |
+| `usePathCache` | `boolean`                    | ❌        | When `true`, `getPath()` results are cached on each node after the first call      |
 
 `base` must exist and be a directory, otherwise the constructor throws.
 
@@ -110,14 +131,14 @@ Used as the `filter` option in the constructor. Applied at every level of the tr
 
 ```ts
 type FilterFunction = (params: {
-  name: string;    // directory name (leaf segment)
+  name: string;    // entry name (file or directory name)
   dirPath: string; // absolute path of the parent directory
 }) => boolean;
 ```
 
-Return `true` to **include** the directory and recurse into it; `false` to **skip** it entirely.
+Return `true` to **include** the entry; `false` to **skip** it entirely.
 
-**Example — exclude `node_modules` and hidden directories at every depth:**
+**Example — exclude `node_modules` and hidden entries at every depth:**
 
 ```ts
 const treeify = new PathTreeify({
@@ -130,7 +151,7 @@ const treeify = new PathTreeify({
 
 ### `build(): PathTreeNode`
 
-Scans all subdirectories directly under `base` (applying the instance-level `filter` if set) and returns a synthetic root `PathTreeNode`.
+Scans all entries directly under `base` that pass the instance-level `filter` and returns a synthetic root `PathTreeNode`. When `fileVisible` is `true`, files are included as leaf nodes.
 
 ```ts
 const tree = treeify.build();
@@ -138,64 +159,73 @@ const tree = treeify.build();
 
 ---
 
-### `buildBy(dirNames: string[]): PathTreeNode`
+### `buildBy(segments: string[]): PathTreeNode`
 
-Builds a tree from the given list of directory names (relative to `base`).
+Builds a tree from the given list of relative path segments. When `fileVisible` is `true`, file paths are also accepted.
 
 ```ts
 const tree = treeify.buildBy(['src', 'docs', 'tests']);
+
+// With fileVisible: true, files can also be specified
+const treeWithFiles = new PathTreeify({ base: '/your/project', fileVisible: true });
+treeWithFiles.buildBy(['src', 'README.md']);
 ```
 
-- Leading and trailing slashes are stripped automatically.
-- Throws if any name does not resolve to a valid directory under `base`.
+- Both `/` and `\` separators are normalised automatically.
+- Leading/trailing slashes and empty segments are stripped.
+- Throws if any segment does not resolve to a valid entry under `base`.
 
-### `buildBy(filter: (dirName: string) => boolean): PathTreeNode`
+### `buildBy(filter: (segment: string) => boolean): PathTreeNode`
 
-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.
+Collects all top-level entries under `base`, applies the predicate to select which ones to include, then builds a tree. The instance-level `filter` still applies during deep traversal.
 
 ```ts
 const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
 ```
 
-> **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.
+> **Note:** the predicate passed to `buildBy(fn)` only selects which **top-level** entries to include. To filter entries at every depth, pass a `filter` to the constructor.
 
 ---
 
-### `getPathBy(node: PathTreeNode): { relative: string; absolute: string }`
+### `PathTreeNode`
 
-Walks a node's `parent` chain to reconstruct its full path. Equivalent to calling `node.getPath()` directly.
+`PathTreeNode` is an **interface** — each node exposes a `getPath()` method to retrieve its paths without needing the `PathTreeify` instance.
 
 ```ts
-const { relative, absolute } = treeify.getPathBy(node);
-// relative → e.g. 'src/components'
-// absolute → e.g. '/your/project/src/components'
+interface PathTreeNode {
+  depth:    number;               // distance from root; root is 0, its children are 1, etc.
+  parent:   PathTreeNode | null;  // null only on the synthetic root
+  value:    string;               // entry name for this node
+  children: PathTreeNode[];       // empty for file nodes
+  type:     PathTreeNodeKind;     // Dir, File, or Unknown
+
+  getPath(): { relative: string; absolute: string };
+}
 ```
 
+When `usePathCache: true` is set on the `PathTreeify` instance, the result of `getPath()` is cached on the node after the first call — subsequent calls return the same object reference without recomputing the parent chain.
+
+> ⚠️ **Circular references** — `parent` points back up the tree. Use `JSON.stringify` replacers or a library like `flatted` if you need to serialize the result.
+
 ---
 
-### `PathTreeNode`
+### `PathTreeNodeKind`
 
-`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.
+An enum classifying each node's filesystem type.
 
 ```ts
-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 };
+enum PathTreeNodeKind {
+  Dir     = 'dir',
+  File    = 'file',
+  Unknown = 'unknown', // assigned before the type is resolved
 }
 ```
 
-`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 base directory
+### Directories only (default)
 
 ```ts
 import { PathTreeify } from 'path-treeify';
@@ -204,6 +234,16 @@ const treeify = new PathTreeify({ base: '/your/project' });
 const tree = treeify.build();
 ```
 
+### Include files as leaf nodes
+
+```ts
+const treeify = new PathTreeify({
+  base: '/your/project',
+  fileVisible: true,
+});
+const tree = treeify.build();
+```
+
 ### Exclude directories at every depth via constructor filter
 
 ```ts
@@ -214,13 +254,13 @@ const treeify = new PathTreeify({
 const tree = treeify.build();
 ```
 
-### Scan specific directories
+### Scan specific paths
 
 ```ts
 const tree = treeify.buildBy(['src', 'tests', 'docs']);
 ```
 
-### Select top-level directories with a predicate
+### Select top-level entries with a predicate
 
 ```ts
 const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith('.'));
@@ -232,7 +272,7 @@ const tree = treeify.buildBy(name => name !== 'node_modules' && !name.startsWith
 function printPaths(node) {
   for (const child of node.children) {
     const { absolute } = child.getPath();
-    console.log(absolute);
+    console.log(`[${child.type}] depth=${child.depth} ${absolute}`);
     printPaths(child);
   }
 }
@@ -240,10 +280,26 @@ function printPaths(node) {
 printPaths(tree);
 ```
 
+### Cache `getPath()` results for repeated traversal
+
+```ts
+const treeify = new PathTreeify({
+  base: '/your/project',
+  usePathCache: true,
+});
+const tree = treeify.build();
+
+// First call walks the parent chain and caches the result
+const pathA = tree.children[0].getPath();
+// Subsequent calls return the cached object directly
+const pathB = tree.children[0].getPath();
+console.log(pathA === pathB); // true
+```
+
 ### CommonJS usage
 
 ```js
-const { PathTreeify } = require('path-treeify');
+const { PathTreeify, PathTreeNodeKind } = require('path-treeify');
 
 const treeify = new PathTreeify({ base: __dirname });
 const tree = treeify.build();
@@ -253,4 +309,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");function i(e,t){for(const r in t)Object.defineProperty(e,r,{value:t[r],writable:!1,configurable:!1,enumerable:!1})}function s(e){try{return function(e){try{const r=t.statSync(e);return r.isDirectory()?exports.PathTreeNodeKind.Dir:r.isFile()?exports.PathTreeNodeKind.File:exports.PathTreeNodeKind.Other}catch(e){if("ENOENT"!==e.code)throw e}try{return t.lstatSync(e).isSymbolicLink()?exports.PathTreeNodeKind.BrokenSymlink:exports.PathTreeNodeKind.Other}catch(e){if("ENOENT"!==e.code)throw e}return exports.PathTreeNodeKind.NotFound}(e)}catch(e){return exports.PathTreeNodeKind.Error}}exports.PathTreeNodeKind=void 0,(e=exports.PathTreeNodeKind||(exports.PathTreeNodeKind={})).Dir="dir",e.File="file",e.Unknown="unknown",e.BrokenSymlink="broken_symlink",e.Other="other",e.NotFound="not_found",e.Error="error";class n{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}}}class o{constructor(e){this.depth=-1,this.parent=null,this.value="",this.children=[],this.type=exports.PathTreeNodeKind.Unknown,i(this,{_usePathCache:e.usePathCache})}getPath(){let e=this,t="";const s=()=>{let e="",i=this;for(;;){if(null===i.parent){t=i.value;break}e=e?`${i.value}${r.sep}${e}`:i.value,i=i.parent}return{relative:e,absolute:r.resolve(t,e)}};return e._usePathCache?(e._pathCache||i(this,{_pathCache:s()}),e._pathCache):s()}}exports.PathTreeify=class{constructor(e){this._base="",this._fileVisible=!1,this._usePathCache=!1;const{filter:t,base:r,fileVisible:s,usePathCache:o}=e;if(void 0!==t&&(this.validateFilter(t),i(this,{_userFilter:t})),!r||!n.isValid(r))throw new Error(`${r} is not a valid path!`);if(!n.isDirectory(r))throw new Error(`${r} is not a dirPath!`);i(this,{_usePathCache:Boolean(o),_base:r,_fileVisible:!("boolean"!=typeof s||!s)&&s})}applyFilter(e,t){return!(!this._fileVisible&&!n.isDirectory(e))&&(!this._userFilter||this._userFilter({name:t,dirPath:r.dirname(e)}))}validateFilter(e){if("function"!=typeof e)throw new TypeError("filter must be a function")}initNode(){return new o({usePathCache:this._usePathCache})}buildChildren(e,i,n){const o=[],a=i.depth+1,h=n||t.readdirSync(e);for(const t of h){const n=r.join(e,t);if(!this.applyFilter(n,t))continue;const h=s(n),l=this.initNode();l.depth=a,l.value=t,l.parent=i,o.push(l),this._fileVisible&&h===exports.PathTreeNodeKind.File?l.type=h:h===exports.PathTreeNodeKind.Dir?(l.type=h,l.children=this.buildChildren(n,l)):l.type=h}return o}checkRelativePaths(e){for(let t=0;t<e.length;t++){const i=e[t];if("string"!=typeof i)throw new Error(`Item at index ${t} is not a string, got ${typeof i}`);const s=r.resolve(this._base,i);if(!n.isValid(s))throw new Error(`Path does not exist or is not accessible: ${s} (from relative path: ${i})`);if(!(n.isDirectory(s)||this._fileVisible&&n.isFile(s)))throw new Error(`Path is not a directory: ${s} (from relative path: ${i})`)}}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();return t.depth=0,t.value=this._base,t.type=exports.PathTreeNodeKind.Dir,t.children=this.buildChildren(this._base,t,e),t}buildByFilter(e){const t=this.getAllEntriesUnderBase();return this.buildBySegments(t.filter(e))}buildBy(e){if(Array.isArray(e)){const t=this.formatSegments(e);return this.checkRelativePaths(t),this.buildBySegments(t)}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{accessSync as t,constants as e,statSync as i,lstatSync as r,readdirSync as s}from"fs";import{sep as n,resolve as o,dirname as a,join as l}from"path";var h;function c(t,e){for(const i in e)Object.defineProperty(t,i,{value:e[i],writable:!1,configurable:!1,enumerable:!1})}function u(t){try{return function(t){try{const e=i(t);return e.isDirectory()?h.Dir:e.isFile()?h.File:h.Other}catch(t){if("ENOENT"!==t.code)throw t}try{return r(t).isSymbolicLink()?h.BrokenSymlink:h.Other}catch(t){if("ENOENT"!==t.code)throw t}return h.NotFound}(t)}catch(t){return h.Error}}!function(t){t.Dir="dir",t.File="file",t.Unknown="unknown",t.BrokenSymlink="broken_symlink",t.Other="other",t.NotFound="not_found",t.Error="error"}(h||(h={}));class f{static isValid(i){try{return t(i,e.F_OK),!0}catch{return!1}}static isDirectory(t){try{return i(t).isDirectory()}catch{return!1}}static isFile(t){try{return i(t).isFile()}catch{return!1}}}class d{constructor(t){this.depth=-1,this.parent=null,this.value="",this.children=[],this.type=h.Unknown,c(this,{_usePathCache:t.usePathCache})}getPath(){let t=this,e="";const i=()=>{let t="",i=this;for(;;){if(null===i.parent){e=i.value;break}t=t?`${i.value}${n}${t}`:i.value,i=i.parent}return{relative:t,absolute:o(e,t)}};return t._usePathCache?(t._pathCache||c(this,{_pathCache:i()}),t._pathCache):i()}}class y{constructor(t){this._base="",this._fileVisible=!1,this._usePathCache=!1;const{filter:e,base:i,fileVisible:r,usePathCache:s}=t;if(void 0!==e&&(this.validateFilter(e),c(this,{_userFilter:e})),!i||!f.isValid(i))throw new Error(`${i} is not a valid path!`);if(!f.isDirectory(i))throw new Error(`${i} is not a dirPath!`);c(this,{_usePathCache:Boolean(s),_base:i,_fileVisible:!("boolean"!=typeof r||!r)&&r})}applyFilter(t,e){return!(!this._fileVisible&&!f.isDirectory(t))&&(!this._userFilter||this._userFilter({name:e,dirPath:a(t)}))}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function")}initNode(){return new d({usePathCache:this._usePathCache})}buildChildren(t,e,i){const r=[],n=e.depth+1,o=i||s(t);for(const i of o){const s=l(t,i);if(!this.applyFilter(s,i))continue;const o=u(s),a=this.initNode();a.depth=n,a.value=i,a.parent=e,r.push(a),this._fileVisible&&o===h.File?a.type=o:o===h.Dir?(a.type=o,a.children=this.buildChildren(s,a)):a.type=o}return r}checkRelativePaths(t){for(let e=0;e<t.length;e++){const i=t[e];if("string"!=typeof i)throw new Error(`Item at index ${e} is not a string, got ${typeof i}`);const r=o(this._base,i);if(!f.isValid(r))throw new Error(`Path does not exist or is not accessible: ${r} (from relative path: ${i})`);if(!(f.isDirectory(r)||this._fileVisible&&f.isFile(r)))throw new Error(`Path is not a directory: ${r} (from relative path: ${i})`)}}formatSegments(t){return t.map(t=>t.split(/[/\\]/).filter(Boolean).join(n)).filter(Boolean)}getAllEntriesUnderBase(){return s(this._base).filter(t=>{const e=o(this._base,t);return this.applyFilter(e,t)})}buildBySegments(t){const e=this.initNode();return e.depth=0,e.value=this._base,e.type=h.Dir,e.children=this.buildChildren(this._base,e,t),e}buildByFilter(t){const e=this.getAllEntriesUnderBase();return this.buildBySegments(e.filter(t))}buildBy(t){if(Array.isArray(t)){const e=this.formatSegments(t);return this.checkRelativePaths(e),this.buildBySegments(e)}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{h as PathTreeNodeKind,y as PathTreeify};

package/dist/types/index.d.ts

@@ -1,93 +1,93 @@
-/** A filter function that determines whether a directory should be included in the tree */
-type FilterFunction = (params: {
-    name: string;
-    dirPath: string;
-}) => boolean;
-/** Constructor options for PathTreeify */
-interface PathTreeifyProps {
-    base: string;
-    filter?: FilterFunction;
-}
-/** Represents a single node (directory) in the path tree */
-declare class PathTreeNode {
-    /** The root base path used to resolve absolute paths */
-    private base;
-    /** Reference to the parent node; null for the root node */
-    parent: PathTreeNode | null;
-    /** The directory name of this node (not a full path) */
-    value: string;
-    /** Child nodes representing subdirectories */
-    children: PathTreeNode[];
-    constructor(base: string);
-    /**
-     * 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
-     */
-    getPath(): {
-        relative: string;
-        absolute: string;
-    };
-}
-/** Builds a tree of directory nodes rooted at a given base path */
+import { PathTreeifyProps, PathTreeNode } from './src/types';
+export { PathTreeifyProps, PathTreeNodeKind, PathTreeNode } from './src/types';
+/** 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>);
+    private _base;
+    /** When true, files are included as leaf nodes during traversal. Defaults to false */
+    private _fileVisible;
+    /** When true, absolute paths are cached on each node after the first retrieval to speed up subsequent `getPath` calls at the cost of higher memory usage. Defaults to false */
+    private _usePathCache;
+    /**
+     * Optional user-supplied filter. When set, every entry must pass this predicate
+     * in addition to the built-in visibility check.
+     */
+    private _userFilter?;
+    constructor(props: Partial<PathTreeifyProps>);
+    /**
+     * 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;
     /**
-     * Validates that the provided filter is a function, accepts one parameter,
-     * and returns a boolean. Throws a TypeError if any condition is violated.
+     * Asserts that the provided value is a callable {@link FilterFunction}.
+     * Throws a TypeError if the check fails.
      */
     private validateFilter;
     /**
-     * Creates and optionally attaches a new PathTreeNode to a parent.
-     * @param parent - The parent node to attach to, or null for the root
+     * Creates a new unattached {@link PathTreeNode}.
+     * The node is created with a two-layer prototype chain:
+     * `node → cache → pathTreeNodeShared`. The intermediate `cache` layer is a
+     * per-node object that holds `_pathCache` when `usePathCache` is enabled,
+     * keeping the cached value isolated to each node while still inheriting `base`
+     * and `getPath` from `pathTreeNodeShared`.
+     * `depth` is initialised to `-1` and must be set by the caller.
      */
     private initNode;
     /**
-     * Recursively reads a directory and builds child nodes for each subdirectory.
-     * Applies the instance-level filter if one is set.
-     * @param dirPath - Absolute path of the directory to read
-     * @param parent - The parent node to attach children to
+     * 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 child nodes to
+     * @param segments - Optional explicit list of entry names to use instead of reading the
+     *                   directory from disk; used by {@link buildBySegments} to skip a
+     *                   redundant `readdirSync` when the segment list is already known
      */
     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; assumed to be a string
+     *                           array (callers are responsible for type safety at the boundary)
      */
     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 formatDirnames;
-    /** Returns the names of all immediate subdirectories under the base path */
-    private getAllDirNamesUnderBase;
+    private formatSegments;
     /**
-     * Builds a tree rooted at base, containing only the specified subdirectories.
-     * @param dirNames - Relative directory names to include as top-level nodes
+     * Returns the names of all immediate entries under {@link base} that pass
+     * {@link applyFilter}.
      */
-    private buildByDirNames;
+    private getAllEntriesUnderBase;
     /**
-     * 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 whose top-depth children correspond to {@link segments}.
+     * The root node is created at depth 0; children are built by delegating to
+     * {@link buildChildren}, passing {@link segments} directly to avoid a redundant
+     * `readdirSync` of the base directory.
+     * @param segments - Normalised and validated relative path segments
      */
-    private buildByFilter;
+    private buildBySegments;
     /**
-     * Computes the relative and absolute paths for a given node
-     * by walking up the parent chain.
+     * Builds a subtree from top-depth entries whose names satisfy {@link filter}.
+     * Note: this predicate only affects top-depth selection, not recursive traversal.
+     * For recursive filtering use the `filter` constructor option.
+     * @param filter - Predicate applied to each top-depth entry name
      */
-    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 */
+    private buildByFilter;
+    /** 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-depth entry names */
+    buildBy(filter: (segment: string) => boolean): PathTreeNode;
+    /** Builds a full tree from all immediate entries under the base path */
     build(): PathTreeNode;
 }
-export {};

package/dist/types/src/types.d.ts

@@ -0,0 +1,59 @@
+/** A filter function that determines whether an entry should be included in the tree */
+export type FilterFunction = (params: {
+    name: string;
+    dirPath: string;
+}) => boolean;
+/** Constructor options for PathTreeify */
+export 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;
+    /**
+     * When true, the result of {@link PathTreeNode.getPath} is memoised on each node
+     * after the first call. Subsequent calls return the same object reference without
+     * re-walking the parent chain. Useful when nodes are accessed repeatedly.
+     * Defaults to false.
+     */
+    usePathCache?: boolean;
+}
+/** Classification of a node in the path tree */
+export declare enum PathTreeNodeKind {
+    Dir = "dir",
+    File = "file",
+    /** Assigned before the node's type has been resolved */
+    Unknown = "unknown",
+    BrokenSymlink = "broken_symlink",
+    Other = "other",
+    NotFound = "not_found",
+    Error = "error"
+}
+/**
+ * Public interface for a node in the path tree.
+ * Consumers receive this type; the internal implementation class is not exported.
+ */
+export interface PathTreeNode {
+    /** Distance from the root node; root itself is 0, its direct children are 1, and so on */
+    depth: number;
+    /** Reference to the parent node; null for the root node */
+    parent: PathTreeNode | null;
+    /** The entry name of this node (not a full path) */
+    value: string;
+    /** Child nodes; non-empty only for directory nodes */
+    children: PathTreeNode[];
+    /** Whether this node is a directory, a file, or not yet resolved */
+    type: PathTreeNodeKind;
+    /**
+     * Walks up the parent chain to compute this node's relative and absolute paths.
+     * When the owning {@link PathTreeify} instance was created with `usePathCache: true`,
+     * the result is memoised after the first call and the same object is returned on
+     * every subsequent call.
+     * @returns `relative` — path from the tree root; `absolute` — fully resolved path on disk
+     */
+    getPath(): {
+        relative: string;
+        absolute: string;
+    };
+}

package/dist/types/src/utils.d.ts

@@ -0,0 +1,38 @@
+import { PathTreeNode, PathTreeNodeKind } from "./types";
+/** Defines read-only properties on an object. Each property is set to the corresponding value in the props object, and is non-writable, non-configurable, and non-enumerable.
+ * @param obj - The target object on which to define the properties
+ * @param props - An object where keys are property names and values are the corresponding property values to set
+ */
+export declare function defineReadOnlyProps(obj: any, props: {
+    [key: string]: any;
+}): void;
+/** Determines the type of a given path, classifying it as a directory, file, symbolic link, or other. If the path does not exist, it is classified as NotFound. If any unexpected error occurs during the stat/lstat operations, it will be thrown to the caller.
+ * @param p - The path to classify
+ * @returns A PathTreeNodeKind value indicating the type of the path
+ */
+export declare function getPathType(p: string): PathTreeNodeKind;
+export declare function getSafePathType(p: string): PathTreeNodeKind;
+/** Utility class for validating file system paths */
+export declare class PathValidator {
+    /** Returns true if the path exists and is accessible */
+    static isValid(path: string): boolean;
+    /** Returns true if the path points to a directory */
+    static isDirectory(path: string): boolean;
+    /** Returns true if the path points to a regular file */
+    static isFile(path: string): boolean;
+}
+export declare class PathTreeNodeImp implements PathTreeNode {
+    depth: number;
+    parent: PathTreeNode | null;
+    value: string;
+    children: PathTreeNode[];
+    type: PathTreeNodeKind;
+    constructor(props: {
+        usePathCache: boolean;
+    });
+    /** Retrieves the absolute and relative path represented by this node. If path caching is enabled, the result will be cached after the first retrieval to optimize subsequent calls. */
+    getPath(): {
+        relative: string;
+        absolute: string;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-treeify",
-  "version": "1.3.0",
+  "version": "1.4.0-beta.31d8864",
   "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",
@@ -26,13 +26,13 @@
   "scripts": {
     "test": "ava",
     "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",
+    "test:md": "mkdir -p reports && ava --tap | tap-json | node ./.github/scripts/generate-report.js --title \"${npm_config_title:-AVA Test Results}\" > reports/ava-test.md",
+    "test:report": "rimraf reports && npm run test:coverage && npm run test:md",
     "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",
-    "build:watch": "nodemon --watch index.ts -e ts --exec \"npm run build:dev\"",
+    "dev": "nodemon --watch index.ts -e ts --exec \"npm run build:dev\"",
     "check-publish": "npm pack --dry-run",
     "publish:beta": "npm publish --tag beta --access public",
     "publish:latest": "npm publish --tag latest --access public"
@@ -93,8 +93,9 @@
     "nodemon": "^3.1.14",
     "rimraf": "^6.1.3",
     "rollup": "^4.59.0",
-    "tap-xunit": "^2.4.1",
+    "tap-json": "^1.0.0",
     "tslib": "^2.8.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
   "engines": {