directory-tree 3.5.2 → 3.6.0

package/.github/workflows/node.js.yml

@@ -16,16 +16,15 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x, 16.x]
+        node-version: [22.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
     - uses: actions/checkout@v2
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v2
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
-        cache: 'npm'
     - run: npm ci
     - run: npm run build --if-present
     - run: npm test

package/README.md

@@ -2,7 +2,7 @@
 
 Creates a JavaScript object representing a directory tree.
 
-This library gets [~100k downloads per week](http://npm-stats.org/#/directory-tree). If you find it useful, feel free to <a href="https://www.buymeacoffee.com/pXhXnSXSbN"><img src="https://img.buymeacoffee.com/button-api/?text=Buy me a coffee.&emoji=&slug=pXhXnSXSbN&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" /></a>
+This library gets [~100k downloads per week](http://npm-stats.org/#/directory-tree). If you find it useful, feel free to <a href="https://www.buymeacoffee.com/pxhxnsxsbn"><img height="40" src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" /></a> .
 
 ## Install
 
@@ -81,9 +81,9 @@ const tree = dirTree('./test/test_data', {extensions:/\.txt$/}, null, (item, PAT
 
 `attributes` : `string[]` - Array of [FS.stats](https://nodejs.org/api/fs.html#fs_class_fs_stats) attributes.
 
-`normalizePath` : `Boolean` - If true, windows style paths will be normalized to unix style pathes (/ instead of \\).
+`normalizePath` : `Boolean` - If true, Windows style paths will be normalized to UNIX style paths (/ instead of \\).
 
-`depth` : `number` - If presented, reads so many nested dirs as specified in argument. Usage of size attribute with depth option is prohibited.
+`depth` : `number` - Limits directory traversal to the specified depth level. When combined with `size`, directories at the depth limit have `size: undefined` (see "Using size with depth" below).
 
 ## Result
 
@@ -166,6 +166,68 @@ photos
 }
 ```
 
+## Using size with depth
+
+The `size` attribute can be used together with the `depth` option, but with an important caveat:
+
+**When depth limiting is active:**
+- **Files** always have accurate sizes
+- **Directories at the depth limit** (whose children are not traversed) will have `size: undefined`
+- **Parent directories** containing depth-limited directories will also have `size: undefined`
+
+This is because directory sizes are calculated by recursively summing all child sizes. When depth limits prevent full traversal, the size would be incomplete and potentially misleading, so `undefined` is returned instead.
+
+**Example:**
+
+```js
+const dirTree = require('directory-tree');
+const tree = dirTree('/some/path', {
+  depth: 1,
+  attributes: ['size', 'type']
+});
+```
+
+Given this structure:
+```
+folder/
+├── file1.txt (100 bytes)
+├── file2.txt (200 bytes)
+└── subfolder/
+    └── file3.txt (300 bytes)
+```
+
+The result will be:
+```js
+{
+  "path": "folder",
+  "name": "folder",
+  "size": undefined,
+  "type": "directory",
+  "children": [
+    {
+      "path": "folder/file1.txt",
+      "name": "file1.txt",
+      "size": 100,
+      "type": "file"
+    },
+    {
+      "path": "folder/file2.txt",
+      "name": "file2.txt",
+      "size": 200,
+      "type": "file"
+    },
+    {
+      "path": "folder/subfolder",
+      "name": "subfolder",
+      "size": undefined,
+      "type": "directory"
+    }
+  ]
+}
+```
+
+**Note:** When serializing to JSON (e.g., `JSON.stringify(tree)`), `undefined` values are omitted. Properties with `undefined` will not appear in the JSON string.
+
 ## Adding custom fields
 You can easily extend a `DirectoryTree` object with custom fields by adding them to the custom field.
 For example add an `id` based on the path of a `DirectoryTree` object for each directory and file like so:
@@ -211,11 +273,6 @@ $ npm test
 
 Make sure you have the dev dependencies installed (e.g. `npm install .`)
 
-## Node version
-
-This project requires at least Node v4.2.
-Check out version `0.1.1` if you need support for older versions of Node.
-
 ## CLI usage
 
 You can use script directly from command line for generating json data.
@@ -231,6 +288,6 @@ $ npx directory-tree --path /Users/user/target --attributes type,extension --pre
 -p, --path string      🗂 The input folder to process. Required.                                     
 -e, --exclude string   🐒 Exclude some folders from processing by regexp string. Ex -e "test_data/some_dir$|js|.DS_Store"                                            
 -o, --output string    📝 Put result into file provided by this options. Overwrites if exists.       
--d, --depth number     ☞ Reads dirs in deep as specified. Usage of size attribute with depth option is prohibited.                                                                
---attributes string    ℹ️ Grab file attributes. Example: --attributes size,type,extension. Usage of size attribute with depth option is prohibited                                
+-d, --depth number     ☞ Limits directory traversal to specified depth. Combined with size, directories at depth limit have size: undefined.
+--attributes string    ℹ️ Grab file attributes. Example: --attributes size,type,extension. With depth, directories at limit have size: undefined.                                
 --pretty               💎 Json pretty print

package/bin/index.js

@@ -30,12 +30,12 @@ const optionList = [
         name: 'depth',
         alias: 'd',
         type: Number,
-        description: '☞ Reads dirs in deep as specified. Usage of size attribute with depth option is prohibited.'
+        description: '☞ Limits directory traversal to specified depth. Combined with size, directories at depth limit have size: undefined.'
     },
     {
         name: 'attributes',
         type: String,
-        description: 'ℹ️ Grab file attributes. Example: --attributes size,type,extension. Usage of size attribute with depth option is prohibited'
+        description: 'ℹ️ Grab file attributes. Example: --attributes size,type,extension. With depth, directories at limit have size: undefined.'
     },
     {
         name: 'pretty',

package/index.d.ts

@@ -17,12 +17,12 @@ declare namespace directoryTree {
   export interface DirectoryTree<C extends Record<string, any> = Record<string, any>> {
     path: string;
     name: string;
-    size: number;
+    size?: number;
     type: "directory" | "file";
     children?: DirectoryTree<C>[];
     extension?: string;
     isSymbolicLink?: boolean;
-    custom: C;
+    custom?: C;
   }
 
   export interface DirectoryTreeOptions {

package/lib/directory-tree.js

@@ -22,7 +22,7 @@ function safeReadDirSync (path) {
 }
 
 /**
- * Normalizes windows style paths by replacing double backslahes with single forward slahes (unix style).
+ * Normalizes Windows style paths by replacing double backslashes with single forward slashes (UNIX style).
  * @param  {string} path
  * @return {string}
  */
@@ -51,10 +51,6 @@ function isRegExp(regExp) {
 function directoryTree (path, options, onEachFile, onEachDirectory, currentDepth = 0) {
   options = options || {};
 
-  if (options.depth !== undefined && options.attributes && options.attributes.indexOf('size') !== -1) {
-    throw new Error('usage of size attribute with depth option is prohibited');
-  }
-
   const name = PATH.basename(path);
   path = options.normalizePath ? normalizePath(path) : path;
   const item = { path, name };
@@ -134,7 +130,15 @@ function directoryTree (path, options, onEachFile, onEachDirectory, currentDepth
       options.attributes.forEach((attribute) => {
         switch (attribute) {
           case 'size':
-            item.size = item.children.reduce((prev, cur) => prev + cur.size, 0);
+            // If children don't exist (depth limit reached), set to undefined
+            if (!item.children) {
+              item.size = undefined;
+            } else {
+              // If any child has undefined size, parent size is also undefined
+              // Otherwise, calculate recursive size
+              const hasUndefinedSize = item.children.some(child => child.size === undefined);
+              item.size = hasUndefinedSize ? undefined : item.children.reduce((prev, cur) => prev + cur.size, 0);
+            }
             break;
           case 'type':
             item.type = constants.DIRECTORY;
@@ -145,7 +149,7 @@ function directoryTree (path, options, onEachFile, onEachDirectory, currentDepth
             item[attribute] = stats[attribute];
             break;
         }
-        
+
       });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "directory-tree",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Convert a directory tree to a JS object.",
   "repository": {
     "type": "git",