path-treeify 1.3.0-beta.56a60fd → 1.3.0-beta.6923d77

package/README.md

@@ -35,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' />
@@ -50,9 +50,11 @@
 - 🌲 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`
+- 👁️ `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
 - 📦 Ships as both ESM (`index.mjs`) and CJS (`index.cjs`) with full TypeScript types
 - 🚫 Zero runtime dependencies
 
@@ -79,18 +81,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
+for (const child of tree.children) {
+  if (child.type === PathTreeNodeKind.Dir) {
+    console.log('dir:', child.value);
+  } else if (child.type === PathTreeNodeKind.File) {
+    console.log('file:', child.value);
+  }
+}
 ```
 
 ---
@@ -101,10 +112,11 @@ 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`      |
 
 `base` must exist and be a directory, otherwise the constructor throws.
 
@@ -116,14 +128,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({
@@ -136,7 +148,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();
@@ -144,64 +156,70 @@ 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 {
+  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 };
+}
 ```
 
+> ⚠️ **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';
@@ -210,6 +228,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
@@ -220,13 +248,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('.'));
@@ -238,7 +266,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}] ${absolute}`);
     printPaths(child);
   }
 }
@@ -249,7 +277,7 @@ printPaths(tree);
 ### CommonJS usage
 
 ```js
-const { PathTreeify } = require('path-treeify');
+const { PathTreeify, PathTreeNodeKind } = require('path-treeify');
 
 const treeify = new PathTreeify({ base: __dirname });
 const tree = treeify.build();

package/dist/index.cjs

@@ -1 +1 @@
-"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)}};
+"use strict";var e,t=require("fs"),i=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}}static isFile(e){try{return t.statSync(e).isFile()}catch{return!1}}}exports.PathTreeNodeKind=void 0,(e=exports.PathTreeNodeKind||(exports.PathTreeNodeKind={})).Dir="dir",e.File="file",e.Unknown="unknown";class s{constructor(e){this.usePathCache=!1,this.base=e.base,"boolean"==typeof e.usePathCache&&(this.usePathCache=e.usePathCache)}getPath(){let e=this;const t=()=>{let t="",r=this;for(;r.parent;)t=t?`${r.value}${i.sep}${t}`:r.value,r=r.parent;return{relative:t,absolute:i.resolve(e.base,t)}};return e.usePathCache?(e._pathCache||(e._pathCache=t()),e._pathCache):t()}}exports.PathTreeify=class{constructor(e){this.fileVisible=!1;const{filter:t,base:i,fileVisible:n,usePathCache:a}=e;if("boolean"==typeof n&&n&&(this.fileVisible=n),void 0!==t&&(this.validateFilter(t),this.userFilter=t),!i||!r.isValid(i))throw new Error(`${i} is not a valid path!`);if(!r.isDirectory(i))throw new Error(`${i} is not a dirPath!`);this.base=i,this.pathTreeNodeShared=new s({base:i,usePathCache:a})}applyFilter(e,t){return!(!this.fileVisible&&!r.isDirectory(e))&&(!this.userFilter||this.userFilter({name:t,dirPath:i.dirname(e)}))}validateFilter(e){if("function"!=typeof e)throw new TypeError("filter must be a function")}initNode(){const e=Object.create(this.pathTreeNodeShared),t=Object.create(e);return t.parent=null,t.value="",t.children=[],t.type=exports.PathTreeNodeKind.Unknown,t.depth=-1,t}buildChildren(e,s,n){const a=[],o=n||t.readdirSync(e),h=s.depth+1;for(const t of o){const n=i.join(e,t);if(!this.applyFilter(n,t))continue;const o=this.initNode();o.depth=h,o.value=t,o.parent=s,a.push(o),this.fileVisible&&r.isFile(n)?o.type=exports.PathTreeNodeKind.File:(o.type=exports.PathTreeNodeKind.Dir,o.children=this.buildChildren(n,o))}return a}checkRelativePaths(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=i.resolve(this.base,s);if(!r.isValid(n))throw new Error(`Path does not exist or is not accessible: ${n} (from relative path: ${s})`);if(!(r.isDirectory(n)||this.fileVisible&&r.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(i.sep)).filter(Boolean)}getAllEntriesUnderBase(){return t.readdirSync(this.base).filter(e=>{const t=i.resolve(this.base,e);return this.applyFilter(t,e)})}buildBySegments(e){const t=this.initNode();return t.depth=0,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,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};
+import{readdirSync as t,accessSync as e,constants as i,statSync as r}from"fs";import{dirname as s,join as n,resolve as a,sep as h}from"path";class l{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}}static isFile(t){try{return r(t).isFile()}catch{return!1}}}var o;!function(t){t.Dir="dir",t.File="file",t.Unknown="unknown"}(o||(o={}));class c{constructor(t){this.usePathCache=!1,this.base=t.base,"boolean"==typeof t.usePathCache&&(this.usePathCache=t.usePathCache)}getPath(){let t=this;const e=()=>{let e="",i=this;for(;i.parent;)e=e?`${i.value}${h}${e}`:i.value,i=i.parent;return{relative:e,absolute:a(t.base,e)}};return t.usePathCache?(t._pathCache||(t._pathCache=e()),t._pathCache):e()}}class u{constructor(t){this.fileVisible=!1;const{filter:e,base:i,fileVisible:r,usePathCache:s}=t;if("boolean"==typeof r&&r&&(this.fileVisible=r),void 0!==e&&(this.validateFilter(e),this.userFilter=e),!i||!l.isValid(i))throw new Error(`${i} is not a valid path!`);if(!l.isDirectory(i))throw new Error(`${i} is not a dirPath!`);this.base=i,this.pathTreeNodeShared=new c({base:i,usePathCache:s})}applyFilter(t,e){return!(!this.fileVisible&&!l.isDirectory(t))&&(!this.userFilter||this.userFilter({name:e,dirPath:s(t)}))}validateFilter(t){if("function"!=typeof t)throw new TypeError("filter must be a function")}initNode(){const t=Object.create(this.pathTreeNodeShared),e=Object.create(t);return e.parent=null,e.value="",e.children=[],e.type=o.Unknown,e.depth=-1,e}buildChildren(e,i,r){const s=[],a=r||t(e),h=i.depth+1;for(const t of a){const r=n(e,t);if(!this.applyFilter(r,t))continue;const a=this.initNode();a.depth=h,a.value=t,a.parent=i,s.push(a),this.fileVisible&&l.isFile(r)?a.type=o.File:(a.type=o.Dir,a.children=this.buildChildren(r,a))}return s}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=a(this.base,i);if(!l.isValid(r))throw new Error(`Path does not exist or is not accessible: ${r} (from relative path: ${i})`);if(!(l.isDirectory(r)||this.fileVisible&&l.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(h)).filter(Boolean)}getAllEntriesUnderBase(){return t(this.base).filter(t=>{const e=a(this.base,t);return this.applyFilter(e,t)})}buildBySegments(t){const e=this.initNode();return e.depth=0,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{o as PathTreeNodeKind,u as PathTreeify};

package/dist/types/dev/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -11,16 +11,22 @@ interface PathTreeifyProps {
     filter?: FilterFunction;
     /** When true, files are included as leaf nodes alongside directories. Defaults to false */
     fileVisible?: boolean;
+    usePathCache?: boolean;
 }
 /** Classification of a node in the path tree */
-export declare enum PathTreeNodeType {
+export declare enum PathTreeNodeKind {
     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 {
+/**
+ * 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) */
@@ -28,17 +34,27 @@ export declare class PathTreeNode {
     /** Child nodes; non-empty only for directory nodes */
     children: PathTreeNode[];
     /** Whether this node is a directory, a file, or not yet resolved */
-    type: PathTreeNodeType;
+    type: PathTreeNodeKind;
     /**
-     * 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
+     * Computes this node's paths using the `parentRelative` stored on the siblings'
+     * shared prototype by {@link PathTreeify.buildChildren}.
+     * @returns `relative` — path from the tree root; `absolute` — fully resolved path on disk
      */
-    getPath(): string;
+    getPath(): {
+        relative: string;
+        absolute: string;
+    };
 }
 /** Builds a tree of {@link PathTreeNode} entries rooted at a given base path */
 export declare class PathTreeify {
     /** The root directory to scan */
     private base;
+    /**
+     * Shared prototype instance for nodes produced by this builder.
+     * All nodes created via {@link initNode} inherit `base` and `getPath` from this object,
+     * avoiding per-node storage of the base path string.
+     */
+    private pathTreeNodeShared;
     /**
      * Optional user-supplied filter. When set, every entry must pass this predicate
      * in addition to the built-in visibility check.
@@ -46,6 +62,7 @@ export declare class PathTreeify {
     private userFilter?;
     /** When true, files are included as leaf nodes during traversal. Defaults to false */
     private fileVisible;
+    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.
@@ -54,27 +71,40 @@ export declare class PathTreeify {
      * @param name - Entry name (filename or directory name)
      */
     private applyFilter;
-    constructor({ filter, base, fileVisible }: Partial<PathTreeifyProps>);
     /**
      * 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} */
+    /**
+     * Creates a new unattached {@link PathTreeNode}.
+     * The node's prototype is set to {@link pathTreeNodeShared} so that `base` and
+     * `getPath` are inherited without being stored on each instance individually.
+     * `depth` are initialised to `-1` and must be set by the caller.
+     */
     private initNode;
     /**
      * 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
+     *
+     * After assembling the sibling group, injects `parentRelative` onto a new intermediate
+     * prototype shared by `children[0]`. This allows {@link PathTreeNodeShared.getPath} to
+     * resolve paths in O(1) without walking the full parent chain on every call.
+     *
+     * @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 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
+     * @param relativeSegments - Relative path strings to validate; assumed to be a string
+     *                           array (callers are responsible for type safety at the boundary)
      */
     private checkRelativePaths;
     /**
@@ -90,29 +120,23 @@ export declare class PathTreeify {
      */
     private getAllEntriesUnderBase;
     /**
-     * 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
+     * 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 buildBySegments;
     /**
-     * Builds a subtree from top-level entries whose names satisfy {@link filter}.
-     * Note: this predicate only affects top-level selection, not recursive traversal.
+     * 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-level entry name
+     * @param filter - Predicate applied to each top-depth entry name
      */
     private buildByFilter;
-    /**
-     * 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 path segments */
     buildBy(segments: string[]): PathTreeNode;
-    /** Overload: build the tree from a predicate applied to top-level entry names */
+    /** 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-treeify",
-  "version": "1.3.0-beta.56a60fd",
+  "version": "1.3.0-beta.6923d77",
   "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",