Merge pull request #12 from amercier/skip-empty-directories

skipEmptyDirectories option

Author: amercier

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
-(nothing)
+- `skipEmptyDirectories` option - [#12]
 
 ## [v0.3.0] - 2018-12-02
 
@@ -56,6 +56,7 @@ All notable changes to this project will be documented in this file. The format
 [#8]: https://github.com/amercier/files-by-directory/pull/8
 [#9]: https://github.com/amercier/files-by-directory/pull/9
 [#11]: https://github.com/amercier/files-by-directory/pull/11
+[#12]: https://github.com/amercier/files-by-directory/pull/12
 [v0.1.0]: https://github.com/amercier/files-by-directory/compare/v0.0.0...v0.1.0
 [v0.1.1]: https://github.com/amercier/files-by-directory/compare/v0.1.0...v0.1.1
 [v0.1.2]: https://github.com/amercier/files-by-directory/compare/v0.1.1...v0.1.2

README.md

@@ -218,6 +218,53 @@ for await (const [directory, ...files] of filesByDirectory(['level1'], { showDir
 
 </details>
 
+<details>
+  <summary><code>options.skipEmptyDirectories</code> (default: <code>true</code>)</summary>
+
+When set to `false`, includes empty files lists.
+
+```bash
+# Directory structure:
+level1
+├── level2a (only directories)
+│   └── level3
+│       └── file3a
+├── level2b
+│   └── (empty)
+└── file1a
+```
+
+```js
+for await (const files of filesByDirectory(['level1']/*, { skipEmptyDirectories: true }*/} )) {
+  console.log(files);
+}
+// [ 'level1/file1a' ]
+// [ 'level1/level2a/level3/file3a' ]
+
+for await (const files of filesByDirectory(['level1'], { skipEmptyDirectories: false } )) {
+  console.log(files);
+}
+// [ 'level1/file1a' ]
+// []
+// [ 'level1/level2a/level3/file3a' ]
+// []
+```
+
+**Note:** this can be useful when combined with `showDirectories` option:
+
+```js
+const options = { skipEmptyDirectories: false, showDirectories: true };
+for await (const [directory, ...files] of filesByDirectory(['level1'], options)) {
+  console.log(directory, files);
+}
+// level1 [ 'level1/file1a' ]
+// level1/level2a []
+// level1/level2a/level3 [ 'level1/level2a/level3/file3a' ]
+// level1/empty-directory []
+```
+
+</details>
+
 ## Asynchronous iteration
 
 [Asynchronous iteration] using `for-await-of` syntax requires Node 10+. For older version of NodeJS, either use:

fixture/index.js

@@ -1,3 +1,4 @@
+import { existsSync, mkdirSync } from 'fs';
 import { join, relative } from 'path';
 
 const cwd = process.cwd();
@@ -24,3 +25,10 @@ export const level1 = fixture('level1');
 export const file1a = fixture('level1/file1a');
 export const unexistingFile = fixture('level1/unexisting-file');
 export const linkToUnexistingFile = fixture('level1/link-to-unexisting-file');
+
+export const emptyDirectory = fixture('empty-directory');
+
+// Must create `emptyDirectory` on-the-fly because Git doesn't allow empty directories
+if (!existsSync(emptyDirectory)) {
+  mkdirSync(emptyDirectory);
+}

src/__snapshots__/files-by-directory.spec.js.snap

@@ -598,3 +598,22 @@ Array [
   ],
 ]
 `;
+
+exports[`filesByDirectory options skipEmptyDirectories includes empty directories when skipEmptyDirectories is false 1`] = `
+Array [
+  Array [],
+  Array [
+    "fixture/level1/level2/level3/file3a",
+    "fixture/level1/level2/level3/file3b",
+  ],
+]
+`;
+
+exports[`filesByDirectory options skipEmptyDirectories skips empty directories when skipEmptyDirectories is true 1`] = `
+Array [
+  Array [
+    "fixture/level1/level2/level3/file3a",
+    "fixture/level1/level2/level3/file3b",
+  ],
+]
+`;

src/files-by-directory.spec.js

@@ -2,7 +2,15 @@ import '@babel/polyfill'; // Required for NodeJS < 10
 import { values } from './async';
 import getFilesByDirectory from './files-by-directory';
 import defaults from './options';
-import { file1a, level1, level2, level2Files, level3, level3Files } from '../fixture';
+import {
+  file1a,
+  level1,
+  level2,
+  level2Files,
+  level3,
+  level3Files,
+  emptyDirectory,
+} from '../fixture';
 
 /** @test {filesByDirectory} */
 describe('filesByDirectory', () => {
@@ -123,5 +131,31 @@ describe('filesByDirectory', () => {
         ).toMatchSnapshot();
       });
     });
+
+    describe('skipEmptyDirectories', () => {
+      it('is true by default', () => {
+        expect(defaults.skipEmptyDirectories).toBe(true);
+      });
+
+      it('skips empty directories when skipEmptyDirectories is true', async () => {
+        expect(
+          await values(
+            getFilesByDirectory([emptyDirectory, level3], {
+              skipEmptyDirectories: true,
+            }),
+          ),
+        ).toMatchSnapshot();
+      });
+
+      it('includes empty directories when skipEmptyDirectories is false', async () => {
+        expect(
+          await values(
+            getFilesByDirectory([emptyDirectory, level3], {
+              skipEmptyDirectories: false,
+            }),
+          ),
+        ).toMatchSnapshot();
+      });
+    });
   });
 });

src/options.js

@@ -6,13 +6,15 @@
  * @property {boolean} directoriesFirst Whether to list directories before files.
  * @property {boolean} showDirectories Whether to include directories as the first entry of the
  * @property {boolean} followSymlinks Whether to follow symbolic links or not.
+ * @property {boolean} skipEmptyDirectories Whether to skip empty directories, or include them.
  * result arrays.
  */
 const defaults = {
   excludeSymlinks: false,
   directoriesFirst: false,
   showDirectories: false,
   followSymlinks: false,
+  skipEmptyDirectories: true,
 };
 
 export default defaults;

src/walker.js

@@ -75,7 +75,7 @@ export default class Walker {
     }
 
     // Process regular files, if any
-    if (regularFiles.length > 0) {
+    if (regularFiles.length > 0 || !this.skipEmptyDirectories) {
       yield* filesCallback(regularFiles);
     }