Cache lstatSync results to avoid redundant syscalls and move exclude note in README

Stat each directory entry once and reuse cached results across sorting,
filtering, and tree building. Move the -I trailing slash documentation
to after the CLI options section and add it to the options table.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yangshun

README.md

@@ -8,7 +8,7 @@ Note: Symlinks are not followed.
 
 ## Quickstart
 
-Instantly execute the command in your current directory via `npx`:
+Instantly execute the command in your current directory via `npx` / `pnpx` / `bunx` / `yarn dlx`:
 
 ```bash
 npx tree-node-cli -I "node_modules" # ignore node_modules
@@ -89,6 +89,8 @@ Options:
   --version                 Display version number
 ```
 
+**Note:** To exclude the contents of a directory while retaining the directory itself, use a trailing slash with the `-I` option (e.g., `-I "node_modules/"`). For the Node.js API, provide a regex matching the directory contents (e.g., `/node_modules\//`). See [#33](https://github.com/yangshun/tree-node-cli/issues/33) for more details.
+
 ## Node.js API
 
 ### `tree(path, options?)`
@@ -114,10 +116,15 @@ Returns the tree as a structured `TreeJsonEntry` object (or `null` if the path i
 ```ts
 // Discriminated union — `contents` only exists on directories
 type TreeJsonEntry =
-  | { type: 'directory'; name: string; contents: TreeJsonEntry[];
-      size?: number; mode?: string; time?: string }
-  | { type: 'file'; name: string;
-      size?: number; mode?: string; time?: string }
+  | {
+      type: 'directory';
+      name: string;
+      contents: TreeJsonEntry[];
+      size?: number;
+      mode?: string;
+      time?: string;
+    }
+  | { type: 'file'; name: string; size?: number; mode?: string; time?: string };
 // size: present when `sizes: true`
 // mode: present when `permissions: true`
 // time: present when `date: true`
@@ -142,21 +149,19 @@ console.log(result);
 | `dirsFirst`     | `false`                    | `boolean`  | List directories before files.                                                                                                        |
 | `fullPath`      | `false`                    | `boolean`  | Print the full path prefix for each file.                                                                                             |
 | `noIndent`      | `false`                    | `boolean`  | Print entries without tree indentation lines.                                                                                         |
-| `permissions`   | `false`                    | `boolean`  | Show file type and permissions (e.g. `[drwxr-xr-x]`).                                                                                |
+| `permissions`   | `false`                    | `boolean`  | Show file type and permissions (e.g. `[drwxr-xr-x]`).                                                                                 |
 | `quote`         | `false`                    | `boolean`  | Quote filenames in double quotes.                                                                                                     |
 | `prune`         | `false`                    | `boolean`  | Remove empty directories from output.                                                                                                 |
 | `dirsOnly`      | `false`                    | `boolean`  | List directories only.                                                                                                                |
 | `sizes`         | `false`                    | `boolean`  | Show filesizes as well.                                                                                                               |
-| `exclude`       | `[]`                       | `RegExp[]` | An array of regex to test each filename against. Matching files will be excluded and matching directories will not be traversed into. |
+| `exclude`       | `[]`                       | `RegExp[]` | An array of regex to test each filename against. Matching files will be excluded and matching directories will not be traversed into. To exclude a directory's contents while still showing the directory itself, use a regex that matches the path with a trailing slash (e.g., `/node_modules\//`). |
 | `maxDepth`      | `Number.POSITIVE_INFINITY` | `number`   | Max display depth of the directory tree.                                                                                              |
 | `reverse`       | `false`                    | `boolean`  | Sort the output in reverse alphabetic order.                                                                                          |
 | `trailingSlash` | `false`                    | `boolean`  | Appends a trailing slash behind directories.                                                                                          |
 | `lineAscii`     | `false`                    | `boolean`  | Turn on ASCII line graphics.                                                                                                          |
 | `filesFirst`    | `false`                    | `boolean`  | List files before directories.                                                                                                        |
-| `sortBy`        | `'name'`                   | `string`   | Sort the output. Options: `'name'`, `'version'`, `'mtime'`, `'ctime'`, `'size'`.                                                     |
-| `unsorted`      | `false`                    | `boolean`  | Do not sort. List files in directory order.                                                                                            |
-
-**Note:** To exclude the contents of a directory while retaining the directory itself, use a trailing slash with the `-I` option (e.g., `-I "node_modules/"`). For the Node.js API, provide a regex matching the directory contents (e.g., `/node_modules\//`). See [#33](https://github.com/yangshun/tree-node-cli/issues/33) for more details.
+| `sortBy`        | `'name'`                   | `string`   | Sort the output. Options: `'name'`, `'version'`, `'mtime'`, `'ctime'`, `'size'`.                                                      |
+| `unsorted`      | `false`                    | `boolean`  | Do not sort. List files in directory order.                                                                                           |
 
 ## License
 

src/index.ts

@@ -99,9 +99,22 @@ function isExcluded(
   return false;
 }
 
+function statEntries(
+  dirPath: string,
+  entries: string[],
+): Map<string, fs.Stats> {
+  const stats = new Map<string, fs.Stats>();
+
+  for (const entry of entries) {
+    stats.set(entry, fs.lstatSync(nodePath.join(dirPath, entry)));
+  }
+
+  return stats;
+}
+
 function sortContents(
   contents: string[],
-  dirPath: string,
+  stats: Map<string, fs.Stats>,
   options: RequiredOptions,
 ): string[] {
   if (options.unsorted) {
@@ -118,25 +131,13 @@ function sortContents(
       );
       break;
     case 'mtime':
-      contents.sort(
-        (a, b) =>
-          fs.lstatSync(nodePath.join(dirPath, a)).mtimeMs -
-          fs.lstatSync(nodePath.join(dirPath, b)).mtimeMs,
-      );
+      contents.sort((a, b) => stats.get(a)!.mtimeMs - stats.get(b)!.mtimeMs);
       break;
     case 'ctime':
-      contents.sort(
-        (a, b) =>
-          fs.lstatSync(nodePath.join(dirPath, a)).ctimeMs -
-          fs.lstatSync(nodePath.join(dirPath, b)).ctimeMs,
-      );
+      contents.sort((a, b) => stats.get(a)!.ctimeMs - stats.get(b)!.ctimeMs);
       break;
     case 'size':
-      contents.sort(
-        (a, b) =>
-          fs.lstatSync(nodePath.join(dirPath, a)).size -
-          fs.lstatSync(nodePath.join(dirPath, b)).size,
-      );
+      contents.sort((a, b) => stats.get(a)!.size - stats.get(b)!.size);
       break;
     default:
       contents.sort();
@@ -152,7 +153,7 @@ function sortContents(
 
 function filterAndOrderContents(
   contents: string[],
-  dirPath: string,
+  stats: Map<string, fs.Stats>,
   options: RequiredOptions,
 ): string[] {
   if (!options.allFiles) {
@@ -164,9 +165,7 @@ function filterAndOrderContents(
   }
 
   const dirSet = new Set(
-    contents.filter((file) =>
-      fs.lstatSync(nodePath.join(dirPath, file)).isDirectory(),
-    ),
+    contents.filter((file) => stats.get(file)!.isDirectory()),
   );
 
   if (options.dirsOnly) {
@@ -187,10 +186,13 @@ function filterAndOrderContents(
 function getDirectoryContents(
   dirPath: string,
   options: RequiredOptions,
-): string[] {
-  const contents = fs.readdirSync(dirPath);
-  const sorted = sortContents(contents, dirPath, options);
-  return filterAndOrderContents(sorted, dirPath, options);
+): { entries: string[]; stats: Map<string, fs.Stats> } {
+  const entries = fs.readdirSync(dirPath);
+  const stats = statEntries(dirPath, entries);
+  const sorted = sortContents(entries, stats, options);
+  const filtered = filterAndOrderContents(sorted, stats, options);
+
+  return { entries: filtered, stats };
 }
 
 function computeSizes(dirPath: string, cache: Map<string, number>): number {
@@ -219,8 +221,9 @@ function buildTree(
   currentDepth: number,
   options: RequiredOptions,
   sizeCache: Map<string, number>,
+  cachedStat?: fs.Stats,
 ): TreeNode | null {
-  const stat = fs.lstatSync(path);
+  const stat = cachedStat ?? fs.lstatSync(path);
   const isDir = stat.isDirectory();
   const isFile = !isDir;
 
@@ -242,16 +245,18 @@ function buildTree(
     return node;
   }
 
-  const contents = getDirectoryContents(path, options);
+  const { entries, stats } = getDirectoryContents(path, options);
 
-  for (const entry of contents) {
+  for (const entry of entries) {
     const child = buildTree(
       entry,
       nodePath.join(path, entry),
       currentDepth + 1,
       options,
       sizeCache,
+      stats.get(entry),
     );
+
     if (child) {
       node.children.push(child);
     }
@@ -277,6 +282,7 @@ function buildTreeNode(
 
   const resolvedPath = nodePath.join(process.cwd(), path);
   const rootName = nodePath.basename(resolvedPath);
+
   return buildTree(rootName, path, 0, options, sizeCache);
 }
 
@@ -291,7 +297,10 @@ export function tree(path: string, options?: Options): string {
   return formatAsText(root, combinedOptions, path).join('\n');
 }
 
-export function treeJson(path: string, options?: Options): TreeJsonEntry | null {
+export function treeJson(
+  path: string,
+  options?: Options,
+): TreeJsonEntry | null {
   const combinedOptions: RequiredOptions = { ...DEFAULT_OPTIONS, ...options };
   const root = buildTreeNode(path, combinedOptions);