directoriesFirst option

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
-(nothing)
+- `directoriesFirst` option - [#8]
 
 ## [v0.2.0] - 2018-11-23
 
@@ -47,6 +47,7 @@ All notable changes to this project will be documented in this file. The format
 [#4]: https://github.com/amercier/files-by-directory/pull/4
 [#5]: https://github.com/amercier/files-by-directory/pull/5
 [#7]: https://github.com/amercier/files-by-directory/pull/7
+[#8]: https://github.com/amercier/files-by-directory/pull/8
 [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

@@ -53,21 +53,21 @@ for await (const files of filesByDirectory(['level1'])) {
 
 ```
 [
-  'level1/level2/level3/file3a',
-  'level1/level2/level3/file3b'
+  'level1/file1a',
+  'level1/file1b'
 ]
 ---
 [
   'level1/level2a/file2a'
 ]
 ---
 [
-  'level1/level2b/file2b'
+  'level1/level2a/level3/file3a',
+  'level1/level2a/level3/file3b'
 ]
 ---
 [
-  'level1/file1a',
-  'level1/file1b'
+  'level1/level2b/file2b'
 ]
 ---
 ```
@@ -106,6 +106,42 @@ for await (const files of filesByDirectory(['level1'], { excludeSymlinks: true }
 // [ 'level2a/file2a', 'level2a/file2b' ]
 ```
 
+#### `options.directoriesFirst` (default: `false`)
+
+When set to `true`, proceed directories (recursively) before files.
+
+```bash
+# Directory structure:
+level1
+├── level2a
+│   ├── level3
+│   │   ├── file3a
+│   │   └── file3b
+│   └── file2a
+├── level2b
+│   └── file2b
+├── file1a
+└── file1b
+```
+
+```js
+for await (const files of filesByDirectory(['level1']/*, { directoriesFirst: false }*/} )) {
+  console.log(files);
+}
+// [ 'level1/file1a', 'level1/file1b' ]
+// [ 'level1/level2a/file2a' ]
+// [ 'level1/level2a/level3/file3a', 'level1/level2a/level3/file3b' ]
+// [ 'level1/level2b/file2b' ]
+
+for await (const files of filesByDirectory(['level1'], { directoriesFirst: true })) {
+  console.log(files);
+}
+// [ 'level1/level2a/level3/file3a', 'level1/level2a/level3/file3b' ]
+// [ 'level1/level2a/file2a' ]
+// [ 'level1/level2b/file2b' ]
+// [ 'level1/file1a', 'level1/file1b' ]
+```
+
 ## Asynchronous iteration
 
 [Asynchronous iteration] using `for-await-of` syntax requires Node 10+. For older version of NodeJS, either use:

src/__snapshots__/file.spec.js.snap

@@ -174,18 +174,6 @@ Array [
 
 exports[`File getFilesByDirectory() generates asynchronously one array of file instances per directory when file is a directory 2`] = `
 Array [
-  Array [
-    File {
-      "isDirectory": false,
-      "isSymbolicLink": false,
-      "path": "fixture/level1/level2/level3/file3a",
-    },
-    File {
-      "isDirectory": false,
-      "isSymbolicLink": false,
-      "path": "fixture/level1/level2/level3/file3b",
-    },
-  ],
   Array [
     File {
       "isDirectory": false,
@@ -213,11 +201,6 @@ Array [
       "path": "fixture/level1/level2/link-to-parent-directory",
     },
   ],
-]
-`;
-
-exports[`File getFilesByDirectory() generates asynchronously one array of file instances per directory when file is a directory 3`] = `
-Array [
   Array [
     File {
       "isDirectory": false,
@@ -230,68 +213,85 @@ Array [
       "path": "fixture/level1/level2/level3/file3b",
     },
   ],
+]
+`;
+
+exports[`File getFilesByDirectory() generates asynchronously one array of file instances per directory when file is a directory 3`] = `
+Array [
   Array [
     File {
       "isDirectory": false,
       "isSymbolicLink": false,
-      "path": "fixture/level1/level2/file2a",
+      "path": "fixture/level1/file1a",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": false,
-      "path": "fixture/level1/level2/file2b",
+      "path": "fixture/level1/file1b",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": true,
-      "path": "fixture/level1/level2/link-to-directory",
+      "path": "fixture/level1/link-to-descendant-directory",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": true,
-      "path": "fixture/level1/level2/link-to-grand-parent-directory",
+      "path": "fixture/level1/link-to-descendant-file",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": true,
-      "path": "fixture/level1/level2/link-to-parent-directory",
+      "path": "fixture/level1/link-to-sibling-directory",
+    },
+    File {
+      "isDirectory": false,
+      "isSymbolicLink": true,
+      "path": "fixture/level1/link-to-sibling-file",
+    },
+    File {
+      "isDirectory": false,
+      "isSymbolicLink": true,
+      "path": "fixture/level1/link-to-unexisting-file",
     },
   ],
   Array [
     File {
       "isDirectory": false,
       "isSymbolicLink": false,
-      "path": "fixture/level1/file1a",
+      "path": "fixture/level1/level2/file2a",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": false,
-      "path": "fixture/level1/file1b",
+      "path": "fixture/level1/level2/file2b",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": true,
-      "path": "fixture/level1/link-to-descendant-directory",
+      "path": "fixture/level1/level2/link-to-directory",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": true,
-      "path": "fixture/level1/link-to-descendant-file",
+      "path": "fixture/level1/level2/link-to-grand-parent-directory",
     },
     File {
       "isDirectory": false,
       "isSymbolicLink": true,
-      "path": "fixture/level1/link-to-sibling-directory",
+      "path": "fixture/level1/level2/link-to-parent-directory",
     },
+  ],
+  Array [
     File {
       "isDirectory": false,
-      "isSymbolicLink": true,
-      "path": "fixture/level1/link-to-sibling-file",
+      "isSymbolicLink": false,
+      "path": "fixture/level1/level2/level3/file3a",
     },
     File {
       "isDirectory": false,
-      "isSymbolicLink": true,
-      "path": "fixture/level1/link-to-unexisting-file",
+      "isSymbolicLink": false,
+      "path": "fixture/level1/level2/level3/file3b",
     },
   ],
 ]