# als-readdir

> Enhances Node.js fs.readdir and fs.readdirSync by adding a 'path' property to Dirent objects in versions where it's not included by default.

Latest version **4.0.0** (published 2025-01-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install als-readdir
pnpm add als-readdir
yarn add als-readdir
bun add als-readdir
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-01-17 |
| First published | 2023-12-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Alex Sorkin |
| Maintainers | alexsorkin |
| Keywords | recursive, nodejs, filesystem, readdir, fs, dirent, path, enhancement |

## Links

- npm: https://www.npmjs.com/package/als-readdir
- npm.io page: https://npm.io/package/als-readdir

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 4.0.0 (latest) — 2025-01-17
- 3.0.0 — 2025-01-11
- 2.2.0 — 2024-09-23
- 2.1.0 — 2024-03-10
- 2.0.0 — 2024-03-10
- 1.2.0 — 2024-02-24
- 1.1.0 — 2023-12-25
- 1.0.1 — 2023-12-23
- 1.0.0 — 2023-12-23

## README

# 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
```bash
npm install als-readdir
```

## Basic Usage
The `ReadDir` class provides methods to read directory contents both synchronously and asynchronously.

### Example: Reading Directory Contents
```js
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
```js
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
```js
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
```js
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
```js
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.

---
_Source: https://npm.io/package/als-readdir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._