tiny-readdir 2.3.0 → 2.5.0

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+import type { Callback } from './types';
+declare const NOOP_PROMISE_LIKE: {
+    then: (fn: Callback) => void;
+};
+export { NOOP_PROMISE_LIKE };

package/dist/constants.js

@@ -0,0 +1,9 @@
+/* IMPORT */
+/* MAIN */
+const NOOP_PROMISE_LIKE = {
+    then: (fn) => {
+        fn();
+    }
+};
+/* EXPORT */
+export { NOOP_PROMISE_LIKE };

package/dist/index.js

@@ -1,8 +1,10 @@
 /* IMPORT */
 import fs from 'node:fs';
 import path from 'node:path';
+import { NOOP_PROMISE_LIKE } from './constants.js';
 import { isFunction, makeCounterPromise } from './utils.js';
 /* MAIN */
+//TODO: Streamline the type of dirnmaps
 const readdir = (rootPath, options) => {
     const followSymlinks = options?.followSymlinks ?? false;
     const maxDepth = options?.depth ?? Infinity;
@@ -10,16 +12,20 @@ const readdir = (rootPath, options) => {
     const ignore = options?.ignore ?? (() => false);
     const isIgnored = isFunction(ignore) ? ignore : (targetPath) => ignore.test(targetPath);
     const signal = options?.signal ?? { aborted: false };
+    const onDirents = options?.onDirents || (() => { });
     const directories = [];
     const directoriesNames = new Set();
+    const directoriesNamesToPaths = {};
     const files = [];
     const filesNames = new Set();
+    const filesNamesToPaths = {};
     const symlinks = [];
     const symlinksNames = new Set();
+    const symlinksNamesToPaths = {};
     const map = {};
     const visited = new Set();
-    const resultEmpty = { directories: [], directoriesNames: new Set(), files: [], filesNames: new Set(), symlinks: [], symlinksNames: new Set(), map: {} };
-    const result = { directories, directoriesNames, files, filesNames, symlinks, symlinksNames, map };
+    const resultEmpty = { directories: [], directoriesNames: new Set(), directoriesNamesToPaths: {}, files: [], filesNames: new Set(), filesNamesToPaths: {}, symlinks: [], symlinksNames: new Set(), symlinksNamesToPaths: {}, map: {} };
+    const result = { directories, directoriesNames, directoriesNamesToPaths, files, filesNames, filesNamesToPaths, symlinks, symlinksNames, symlinksNamesToPaths, map };
     const { promise, increment, decrement } = makeCounterPromise();
     let foundPaths = 0;
     const handleDirectory = (dirmap, subPath, name, depth) => {
@@ -30,8 +36,12 @@ const readdir = (rootPath, options) => {
         foundPaths += 1;
         dirmap.directories.push(subPath);
         dirmap.directoriesNames.add(name);
+        // dirmap.directoriesNamesToPaths.propertyIsEnumerable(name) || ( dirmap.directoriesNamesToPaths[name] = [] );
+        // dirmap.directoriesNamesToPaths[name].push ( subPath );
         directories.push(subPath);
         directoriesNames.add(name);
+        directoriesNamesToPaths.propertyIsEnumerable(name) || (directoriesNamesToPaths[name] = []);
+        directoriesNamesToPaths[name].push(subPath);
         visited.add(subPath);
         if (depth >= maxDepth)
             return;
@@ -47,8 +57,12 @@ const readdir = (rootPath, options) => {
         foundPaths += 1;
         dirmap.files.push(subPath);
         dirmap.filesNames.add(name);
+        // dirmap.filesNamesToPaths.propertyIsEnumerable(name) ||  ( dirmap.filesNamesToPaths[name] = [] );
+        // dirmap.filesNamesToPaths[name].push ( subPath );
         files.push(subPath);
         filesNames.add(name);
+        filesNamesToPaths.propertyIsEnumerable(name) || (filesNamesToPaths[name] = []);
+        filesNamesToPaths[name].push(subPath);
         visited.add(subPath);
     };
     const handleSymlink = (dirmap, subPath, name, depth) => {
@@ -59,8 +73,12 @@ const readdir = (rootPath, options) => {
         foundPaths += 1;
         dirmap.symlinks.push(subPath);
         dirmap.symlinksNames.add(name);
+        // dirmap.symlinksNamesToPaths.propertyIsEnumerable(name) || ( dirmap.symlinksNamesToPaths[name] = [] );
+        // dirmap.symlinksNamesToPaths[name].push ( subPath );
         symlinks.push(subPath);
         symlinksNames.add(name);
+        symlinksNamesToPaths.propertyIsEnumerable(name) || (symlinksNamesToPaths[name] = []);
+        symlinksNamesToPaths[name].push(subPath);
         visited.add(subPath);
         if (!followSymlinks)
             return;
@@ -123,9 +141,12 @@ const readdir = (rootPath, options) => {
                 return decrement();
             if (!dirents.length)
                 return decrement();
-            const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set(), files: [], filesNames: new Set(), symlinks: [], symlinksNames: new Set() };
-            handleDirents(dirmap, rootPath, dirents, depth);
-            decrement();
+            const promise = onDirents(dirents) || NOOP_PROMISE_LIKE;
+            promise.then(() => {
+                const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set(), directoriesNamesToPaths: {}, files: [], filesNames: new Set(), filesNamesToPaths: {}, symlinks: [], symlinksNames: new Set(), symlinksNamesToPaths: {} };
+                handleDirents(dirmap, rootPath, dirents, depth);
+                decrement();
+            });
         });
     };
     const populateResultFromSymlink = async (rootPath, depth) => {
@@ -141,7 +162,7 @@ const readdir = (rootPath, options) => {
                 if (signal.aborted)
                     return decrement();
                 const name = path.basename(realPath);
-                const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set(), files: [], filesNames: new Set(), symlinks: [], symlinksNames: new Set() };
+                const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set(), directoriesNamesToPaths: {}, files: [], filesNames: new Set(), filesNamesToPaths: {}, symlinks: [], symlinksNames: new Set(), symlinksNamesToPaths: {} };
                 handleStat(dirmap, realPath, name, stat, depth);
                 decrement();
             });

package/dist/types.d.ts

@@ -1,4 +1,16 @@
 type Callback = () => void;
+type PromiseMaybe<T> = Promise<T> | T;
+type Dirent = {
+    isFile: () => boolean;
+    isDirectory: () => boolean;
+    isBlockDevice: () => boolean;
+    isCharacterDevice: () => boolean;
+    isSymbolicLink: () => boolean;
+    isFIFO: () => boolean;
+    isSocket: () => boolean;
+    name: string;
+    path: string;
+};
 type Options = {
     depth?: number;
     limit?: number;
@@ -7,14 +19,18 @@ type Options = {
     signal?: {
         aborted: boolean;
     };
+    onDirents?: (dirents: Dirent[]) => PromiseMaybe<undefined>;
 };
 type ResultDirectory = {
     directories: string[];
     directoriesNames: Set<string>;
+    directoriesNamesToPaths: Record<string, string[]>;
     files: string[];
     filesNames: Set<string>;
+    filesNamesToPaths: Record<string, string[]>;
     symlinks: string[];
     symlinksNames: Set<string>;
+    symlinksNamesToPaths: Record<string, string[]>;
 };
 type ResultDirectories = {
     [path: string]: ResultDirectory;
@@ -22,4 +38,4 @@ type ResultDirectories = {
 type Result = ResultDirectory & {
     map: ResultDirectories;
 };
-export type { Callback, Options, ResultDirectory, ResultDirectories, Result };
+export type { Callback, PromiseMaybe, Dirent, Options, ResultDirectory, ResultDirectories, Result };

package/package.json

@@ -2,7 +2,7 @@
   "name": "tiny-readdir",
   "repository": "github:fabiospampinato/tiny-readdir",
   "description": "A simple promisified recursive readdir function.",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "main": "dist/index.js",
   "exports": "./dist/index.js",

package/readme.md

@@ -20,7 +20,8 @@ const result = await readdir ( '/foo/bar', {
   limit: 1_000_000, // Maximum number of files explored, useful as a stop gap in some edge cases
   followSymlinks: true, // Whether to follow symlinks or not
   ignore: targetPath => /node_modules/.test ( targetPath ), // Function that if returns true will ignore this particular file or a directory and its descendants
-  signal: aborter.signal // Optional abort signal, useful for aborting potentially expensive operations
+  signal: aborter.signal, // Optional abort signal, useful for aborting potentially expensive operations
+  onDirents: dirents => console.log ( dirents ) // Optional callback that will be called as soon as new dirents are available, useful for example for discovering ".gitignore" files while searching
 });
 
 console.log ( result.directories ); // => Array of absolute paths pointing to directories
@@ -31,6 +32,10 @@ console.log ( result.directoriesNames ); // => Set of directories names found
 console.log ( result.filesNames ); // => Set of files name found
 console.log ( result.symlinksNames ); // => Set of symlinks names found
 
+console.log ( result.directoriesNamesToPaths ); // => Record of directories names found to their paths
+console.log ( result.filesNamesToPaths ); // => Record of files names found to their paths
+console.log ( result.symlinksNamesToPaths ); // => Record of symlinks names found to their paths
+
 setTimeout ( () => aborter.abort (), 10000 ); // Aborting if it's going to take longer than 10s
 ```
 

package/src/constants.ts

@@ -0,0 +1,16 @@
+
+/* IMPORT */
+
+import type {Callback} from './types';
+
+/* MAIN */
+
+const NOOP_PROMISE_LIKE = {
+  then: ( fn: Callback ) => {
+    fn ();
+  }
+};
+
+/* EXPORT */
+
+export {NOOP_PROMISE_LIKE};

package/src/index.ts

@@ -3,11 +3,14 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import {NOOP_PROMISE_LIKE} from './constants';
 import {isFunction, makeCounterPromise} from './utils';
 import type {Options, ResultDirectory, ResultDirectories, Result} from './types';
 
 /* MAIN */
 
+//TODO: Streamline the type of dirnmaps
+
 const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
 
   const followSymlinks = options?.followSymlinks ?? false;
@@ -16,16 +19,20 @@ const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
   const ignore = options?.ignore ?? (() => false);
   const isIgnored = isFunction ( ignore ) ? ignore : ( targetPath: string ) => ignore.test ( targetPath );
   const signal = options?.signal ?? { aborted: false };
+  const onDirents = options?.onDirents || (() => {});
   const directories: string[] = [];
   const directoriesNames: Set<string> = new Set ();
+  const directoriesNamesToPaths: Record<string, string[]> = {};
   const files: string[] = [];
   const filesNames: Set<string> = new Set ();
+  const filesNamesToPaths: Record<string, string[]> = {};
   const symlinks: string[] = [];
   const symlinksNames: Set<string> = new Set ();
+  const symlinksNamesToPaths: Record<string, string[]> = {};
   const map: ResultDirectories = {};
   const visited = new Set<string> ();
-  const resultEmpty: Result = { directories: [], directoriesNames: new Set (), files: [], filesNames: new Set (), symlinks: [], symlinksNames: new Set (), map: {} };
-  const result: Result = { directories, directoriesNames, files, filesNames, symlinks, symlinksNames, map };
+  const resultEmpty: Result = { directories: [], directoriesNames: new Set (), directoriesNamesToPaths: {}, files: [], filesNames: new Set (), filesNamesToPaths: {}, symlinks: [], symlinksNames: new Set (), symlinksNamesToPaths: {}, map: {} };
+  const result: Result = { directories, directoriesNames, directoriesNamesToPaths, files, filesNames, filesNamesToPaths, symlinks, symlinksNames, symlinksNamesToPaths, map };
   const {promise, increment, decrement} = makeCounterPromise ();
 
   let foundPaths = 0;
@@ -39,8 +46,12 @@ const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
     foundPaths += 1;
     dirmap.directories.push ( subPath );
     dirmap.directoriesNames.add ( name );
+    // dirmap.directoriesNamesToPaths.propertyIsEnumerable(name) || ( dirmap.directoriesNamesToPaths[name] = [] );
+    // dirmap.directoriesNamesToPaths[name].push ( subPath );
     directories.push ( subPath );
     directoriesNames.add ( name );
+    directoriesNamesToPaths.propertyIsEnumerable(name) || ( directoriesNamesToPaths[name] = [] );
+    directoriesNamesToPaths[name].push ( subPath );
     visited.add ( subPath );
 
     if ( depth >= maxDepth ) return;
@@ -60,8 +71,12 @@ const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
     foundPaths += 1;
     dirmap.files.push ( subPath );
     dirmap.filesNames.add ( name );
+    // dirmap.filesNamesToPaths.propertyIsEnumerable(name) ||  ( dirmap.filesNamesToPaths[name] = [] );
+    // dirmap.filesNamesToPaths[name].push ( subPath );
     files.push ( subPath );
     filesNames.add ( name );
+    filesNamesToPaths.propertyIsEnumerable(name) || ( filesNamesToPaths[name] = [] );
+    filesNamesToPaths[name].push ( subPath );
     visited.add ( subPath );
 
   };
@@ -75,8 +90,12 @@ const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
     foundPaths += 1;
     dirmap.symlinks.push ( subPath );
     dirmap.symlinksNames.add ( name );
+    // dirmap.symlinksNamesToPaths.propertyIsEnumerable(name) || ( dirmap.symlinksNamesToPaths[name] = [] );
+    // dirmap.symlinksNamesToPaths[name].push ( subPath );
     symlinks.push ( subPath );
     symlinksNames.add ( name );
+    symlinksNamesToPaths.propertyIsEnumerable(name) || ( symlinksNamesToPaths[name] = [] );
+    symlinksNamesToPaths[name].push ( subPath );
     visited.add ( subPath );
 
     if ( !followSymlinks ) return;
@@ -165,11 +184,17 @@ const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
 
       if ( !dirents.length ) return decrement ();
 
-      const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set (), files: [], filesNames: new Set (), symlinks: [], symlinksNames: new Set () };
+      const promise = onDirents ( dirents ) || NOOP_PROMISE_LIKE;
+
+      promise.then ( () => {
+
+        const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set (), directoriesNamesToPaths: {}, files: [], filesNames: new Set (), filesNamesToPaths: {}, symlinks: [], symlinksNames: new Set (), symlinksNamesToPaths: {} };
 
-      handleDirents ( dirmap, rootPath, dirents, depth );
+        handleDirents ( dirmap, rootPath, dirents, depth );
 
-      decrement ();
+        decrement ();
+
+      });
 
     });
 
@@ -192,7 +217,7 @@ const readdir = ( rootPath: string, options?: Options ): Promise<Result> => {
         if ( signal.aborted ) return decrement ();
 
         const name = path.basename ( realPath );
-        const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set (), files: [], filesNames: new Set (), symlinks: [], symlinksNames: new Set () };
+        const dirmap = map[rootPath] = { directories: [], directoriesNames: new Set (), directoriesNamesToPaths: {}, files: [], filesNames: new Set (), filesNamesToPaths: {}, symlinks: [], symlinksNames: new Set (), symlinksNamesToPaths: {} };
 
         handleStat ( dirmap, realPath, name, stat, depth );
 

package/src/types.ts

@@ -3,23 +3,41 @@
 
 type Callback = () => void;
 
+type PromiseMaybe<T> = Promise<T> | T;
+
 /* MAIN */
 
+type Dirent = {
+  isFile: () => boolean,
+  isDirectory: () => boolean,
+  isBlockDevice: () => boolean,
+  isCharacterDevice: () => boolean,
+  isSymbolicLink: () => boolean,
+  isFIFO: () => boolean,
+  isSocket: () => boolean,
+  name: string,
+  path: string
+};
+
 type Options = {
   depth?: number,
   limit?: number,
   followSymlinks?: boolean,
   ignore?: (( targetPath: string ) => boolean) | RegExp,
-  signal?: { aborted: boolean }
+  signal?: { aborted: boolean },
+  onDirents?: ( dirents: Dirent[] ) => PromiseMaybe<undefined>
 };
 
 type ResultDirectory = {
   directories: string[],
   directoriesNames: Set<string>,
+  directoriesNamesToPaths: Record<string, string[]>,
   files: string[],
   filesNames: Set<string>,
+  filesNamesToPaths: Record<string, string[]>,
   symlinks: string[],
-  symlinksNames: Set<string>
+  symlinksNames: Set<string>,
+  symlinksNamesToPaths: Record<string, string[]>
 };
 
 type ResultDirectories = {
@@ -32,4 +50,4 @@ type Result = ResultDirectory & {
 
 /* EXPORT */
 
-export type {Callback, Options, ResultDirectory, ResultDirectories, Result};
+export type {Callback, PromiseMaybe, Dirent, Options, ResultDirectory, ResultDirectories, Result};

package/test/index.js

@@ -46,66 +46,90 @@ describe ( 'Tiny Readdir', it => {
     const expected = {
       directories: [folder1Path, folder2Path, folder1DeepPath, root2Path],
       directoriesNames: new Set ( [folder1Path, folder2Path, folder1DeepPath, root2Path].map ( toBasename ) ),
+      directoriesNamesToPaths: { folder1: [folder1Path], folder2: [folder2Path], deep: [folder1DeepPath], root2: [root2Path] },
       files: [file1aPath, file1bPath, file2Path, fileDeep1Path],
       filesNames: new Set ( [file1aPath, file1bPath, file2Path, fileDeep1Path].map ( toBasename ) ),
+      filesNamesToPaths: { 'file1a.txt': [file1aPath], 'file1b.txt': [file1bPath], 'file2.txt': [file2Path], 'file1.txt': [fileDeep1Path] },
       symlinks: [symlink1FromPath, symlink2FromPath],
       symlinksNames: new Set ( [symlink1FromPath, symlink2FromPath].map ( toBasename ) ),
+      symlinksNamesToPaths: { symlink: [symlink1FromPath, symlink2FromPath] },
       map: {
         [root1Path]: {
           directories: [folder1Path, folder2Path],
           directoriesNames: new Set ( [folder1Path, folder2Path].map ( toBasename ) ),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [symlink1FromPath],
-          symlinksNames: new Set ( [symlink1FromPath].map ( toBasename ) )
+          symlinksNames: new Set ( [symlink1FromPath].map ( toBasename ) ),
+          symlinksNamesToPaths: {}
         },
         [root2Path]: {
           directories: [],
           directoriesNames: new Set (),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [symlink2FromPath],
-          symlinksNames: new Set ( [symlink2FromPath].map ( toBasename ) )
+          symlinksNames: new Set ( [symlink2FromPath].map ( toBasename ) ),
+          symlinksNamesToPaths: {}
         },
         [folder1Path]: {
           directories: [folder1DeepPath],
           directoriesNames: new Set ( [folder1DeepPath].map ( toBasename ) ),
+          directoriesNamesToPaths: {},
           files: [file1aPath, file1bPath],
           filesNames: new Set ( [file1aPath, file1bPath].map ( toBasename ) ),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         },
         [folder2Path]: {
           directories: [],
           directoriesNames: new Set (),
+          directoriesNamesToPaths: {},
           files: [file2Path],
           filesNames: new Set ( [file2Path].map ( toBasename ) ),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         },
         [folder1DeepPath]: {
           directories: [],
           directoriesNames: new Set (),
+          directoriesNamesToPaths: {},
           files: [fileDeep1Path],
           filesNames: new Set ( [fileDeep1Path].map ( toBasename ) ),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         },
         [symlink1FromPath]: {
           directories: [root2Path],
           directoriesNames: new Set ( [root2Path].map ( toBasename ) ),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         },
         [symlink2FromPath]: {
           directories: [],
           directoriesNames: new Set (),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         }
       }
     };
@@ -157,34 +181,46 @@ describe ( 'Tiny Readdir', it => {
     const expected = {
       directories: [folder1Path, folder2Path],
       directoriesNames: new Set ( [folder1Path, folder2Path].map ( toBasename ) ),
+      directoriesNamesToPaths: { folder1: [folder1Path], folder2: [folder2Path] },
       files: [],
       filesNames: new Set (),
+      filesNamesToPaths: {},
       symlinks: [symlink1FromPath],
       symlinksNames: new Set ( [symlink1FromPath].map ( toBasename ) ),
+      symlinksNamesToPaths: { symlink: [symlink1FromPath] },
       map: {
         [root1Path]: {
           directories: [folder1Path, folder2Path],
           directoriesNames: new Set ( [folder1Path, folder2Path].map ( toBasename ) ),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [symlink1FromPath],
-          symlinksNames: new Set ( [symlink1FromPath].map ( toBasename ) )
+          symlinksNames: new Set ( [symlink1FromPath].map ( toBasename ) ),
+          symlinksNamesToPaths: {}
         },
         [folder1Path]: {
           directories: [],
           directoriesNames: new Set (),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         },
         [folder2Path]: {
           directories: [],
           directoriesNames: new Set (),
+          directoriesNamesToPaths: {},
           files: [],
           filesNames: new Set (),
+          filesNamesToPaths: {},
           symlinks: [],
-          symlinksNames: new Set ()
+          symlinksNames: new Set (),
+          symlinksNamesToPaths: {}
         }
       }
     };