als-readdir v4.0.0

als-readdir

The ReadDir library provides a unified interface for reading directory contents across all Node.js versions from v10 and above. It addresses inconsistencies and missing features in fs.readdir and fs.readdirSync across different Node.js versions:

Problem Statement

1. Node.js v10 - v16:
   • No support for recursive option in fs.readdir.
   • No parentPath or path fields in Dirent objects.
2. Node.js v18 - v22:
   • recursive option available in fs.readdir.
   • parentPath field added to Dirent objects.
   • path field exists but incorrectly mirrors parentPath.
3. Node.js v23+:
   • recursive option supported.
   • parentPath field present.
   • path field removed entirely.

Solution

The library:

• Adds missing fields (parentPath, path) for older Node.js versions.
• Fixes the path field for Node.js v18-v22, ensuring it correctly resolves the full path.
• Provides a consistent path property for all versions, including Node.js v23+.

Compatibility

The library has been tested on the following Node.js versions:

• v23.6.0
• v22.9.0
• v20.18.1
• v18.20.4
• v16.20.2
• v12.22.12
• v10.24.1

Installation

npm install als-readdir

Basic Usage

The ReadDir class provides methods to read directory contents both synchronously and asynchronously.

Example: Reading Directory Contents

const {readdirSync,readdir} = require('als-readdir');

// Synchronous reading
const resultSync = readdirSync('/path/to/directory', { recursive: true });
console.log(resultSync.files); // Array of file paths
console.log(resultSync.dirs);  // Array of directory paths
console.log(resultSync.errors); // Array of errors (if any)

// Asynchronous reading
(async () => {
    const result = await readdir('/path/to/directory', { recursive: true });
    console.log(result.files); // Array of file paths
    console.log(result.dirs);  // Array of directory paths
    console.log(result.errors); // Array of errors (if any)
})();

API Reference

Constructor

new ReadDir(path, options)

Parameters

• path (string): The path to the directory to read.
• options (object, optional):
  • recursive (boolean): If true, reads directories recursively. Default: false.
  • withFileTypes (boolean): If true, returns Dirent objects. Default: false.

Example

const ReadDir = require('als-readdir');
const instance = new ReadDir('/path/to/directory', { recursive: true });

Methods

readSync()

Reads the directory synchronously.

Returns

• The current instance of ReadDir.

Example

const result = ReadDir.readdirSync('/path/to/directory', { recursive: true });
console.log(result.files); // Array of file paths

read()

Reads the directory asynchronously.

Returns

• A Promise resolving to the current instance of ReadDir.

Example

const result = await ReadDir.readdir('/path/to/directory', { recursive: true });
console.log(result.dirs); // Array of directory paths

Properties

path

The directory path provided during initialization.

files

An array of file paths relative to the root directory.

dirs

An array of directory paths relative to the root directory.

errors

An array of errors encountered during directory reading.

Notes

• Errors are not thrown: Instead, they are collected in the errors property of the returned instance. This allows for graceful error handling without crashing the program.

Features

• Recursive Reading: Supports recursive directory traversal for all Node.js versions.
• Consistent Output: Ensures that path, parentPath, and other key fields are always present.
• Error Handling: Collects errors without throwing exceptions.