### Promise API Example

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Use the promise API for a simpler, asynchronous way to get all file entries. This method may consume more RAM and CPU compared to streams.

```javascript
import { readdirpPromise } from 'readdirp';
const files = await readdirpPromise('.');
console.log(files.map(file => file.path));
```

--------------------------------

### Install readdirp

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Install readdirp using npm or JSR.

```sh
npm install readdirp
jsr add jsr:@paulmillr/readdirp
```

--------------------------------

### Stream Example with for-await

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Use the stream API with `for await...of` for efficient file system traversal. This is suitable for Node.js 10+.

```javascript
import readdirp from 'readdirp';
for await (const entry of readdirp('.')) {
  const {path} = entry;
  console.log(`${JSON.stringify({path})}`);
}
```

--------------------------------

### readdirpPromise Usage Example

Source: https://context7.com/paulmillr/readdirp/llms.txt

This example demonstrates how to use the readdirpPromise API to read directory contents. It shows how to access entry information and how to use the `alwaysStat` option to retrieve file statistics.

```APIDOC
## readdirpPromise Usage

```js
import { readdirpPromise } from 'readdirp';

const [entry] = await readdirpPromise('.', { depth: 0 });

// Always available
console.log(entry.path);      // "README.md"
console.log(entry.fullPath);  // "/home/user/project/README.md"
console.log(entry.basename);  // "README.md"

// Default mode (dirent)
console.log(entry.dirent.isFile());        // true
console.log(entry.dirent.isDirectory());   // false

// With alwaysStat: true
const [statEntry] = await readdirpPromise('.', { depth: 0, alwaysStat: true });
console.log(statEntry.stats.size);         // e.g. 4096
console.log(statEntry.stats.mtime);        // Date object
```
```

--------------------------------

### Stream Example with Event Handlers

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Process JS files and their sizes using traditional stream event handlers. This approach allows for detailed control over data, warnings, errors, and stream completion.

```javascript
// Print out all JS files along with their size within the current folder & subfolders.
import readdirp from 'readdirp';
readdirp('.', {alwaysStat: true, fileFilter: (f) => f.basename.endsWith('.js')})
  .on('data', (entry) => {
    const {path, stats: {size}} = entry;
    console.log(`${JSON.stringify({path, size})}`);
  })
  // Optionally call stream.destroy() in `warn()` in order to abort and cause 'close' to be emitted
  .on('warn', error => console.error('non-fatal error', error))
  .on('error', error => console.error('fatal error', error))
  .on('end', () => console.log('done'));
```

--------------------------------

### File Filter: By file size using stats

Source: https://context7.com/paulmillr/readdirp/llms.txt

Filter files based on their size by enabling `alwaysStat: true` and providing a predicate function that checks `entry.stats.size`. This example filters for files larger than 10 KB.

```javascript
// Filter by file size using stats (requires alwaysStat: true)
for await (const entry of readdirp('.', {
  alwaysStat: true,
  fileFilter: (f) => f.stats.size > 1024 * 10, // files larger than 10 KB
})) {
  console.log(entry.path, entry.stats.size);
}
```

--------------------------------

### Directory Filter: Skip hidden and node_modules

Source: https://context7.com/paulmillr/readdirp/llms.txt

Filter directories to exclude hidden directories (starting with '.') and the 'node_modules' directory. This prunes entire subtrees from the traversal.

```javascript
import readdirp from 'readdirp';

// Skip hidden directories and node_modules
for await (const entry of readdirp('.', {
  directoryFilter: (d) => !d.basename.startsWith('.') && d.basename !== 'node_modules',
  type: 'files_directories',
})) {
  console.log(entry.path);
}
```

--------------------------------

### File Filter: Function predicate

Source: https://context7.com/paulmillr/readdirp/llms.txt

Filter files based on a function predicate that checks the file's basename. This example filters for files ending with '.json' using `dirent` for efficiency.

```javascript
import readdirp from 'readdirp';

// Function predicate — filter by extension using dirent (no stat overhead)
for await (const entry of readdirp('.', {
  fileFilter: (f) => f.basename.endsWith('.json'),
})) {
  console.log(entry.path); // only .json files
}
```

--------------------------------

### Promise API: With error handling and filters

Source: https://context7.com/paulmillr/readdirp/llms.txt

Demonstrates using `readdirpPromise` with custom filters for files and directories, and depth limitation, along with a try-catch block for error handling.

```javascript
try {
  const entries = await readdirpPromise('/project', {
    fileFilter: (f) => f.basename.endsWith('.ts'),
    directoryFilter: (d) => d.basename !== 'node_modules',
    depth: 3,
  });
  console.log(`Found ${entries.length} TypeScript files`);
  entries.forEach((e) => console.log(e.path, e.dirent.isFile()));
} catch (err) {
  console.error('traversal failed:', err);
}
```

--------------------------------

### Promise API: Basic usage

Source: https://context7.com/paulmillr/readdirp/llms.txt

Use `readdirpPromise` to collect all matching entries into an array. This is simpler for smaller directory trees but can consume significant memory for large ones.

```javascript
import { readdirpPromise } from 'readdirp';

// Basic usage — list all files recursively
const files = await readdirpPromise('.');
console.log(files.map((f) => f.path));
// [ 'src/index.ts', 'src/utils/helpers.ts', 'test/index.test.js', ... ]
```

--------------------------------

### Stream API: Iterate with for await...of

Source: https://context7.com/paulmillr/readdirp/llms.txt

Use the `for await...of` loop to iterate over directory entries. This is the recommended approach for the stream API due to its conciseness and automatic backpressure handling.

```javascript
import readdirp from 'readdirp';

// --- for-await (recommended) ---
for await (const entry of readdirp('./src')) {
  console.log(entry.path);       // e.g. "components/Button.tsx"
  console.log(entry.fullPath);   // e.g. "/home/user/project/src/components/Button.tsx"
  console.log(entry.basename);   // e.g. "Button.tsx"
  console.log(entry.dirent);     // fs.Dirent (default; use dirent.isFile(), etc.)
}
```

--------------------------------

### readdirp Promise API Usage

Source: https://context7.com/paulmillr/readdirp/llms.txt

Demonstrates how to use the readdirp promise API to read directory entries. Shows access to path, fullPath, basename, dirent, and stats properties.

```javascript
import { readdirpPromise } from 'readdirp';

const [entry] = await readdirpPromise('.', { depth: 0 });

// Always available
console.log(entry.path);      // "README.md"
console.log(entry.fullPath);  // "/home/user/project/README.md"
console.log(entry.basename);  // "README.md"

// Default mode (dirent)
console.log(entry.dirent.isFile());        // true
console.log(entry.dirent.isDirectory());   // false

// With alwaysStat: true
const [statEntry] = await readdirpPromise('.', { depth: 0, alwaysStat: true });
console.log(statEntry.stats.size);         // e.g. 4096
console.log(statEntry.stats.mtime);        // Date object
```

--------------------------------

### readdirp with Custom Options

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Configure readdirp with custom filters for files and directories, specify the entry type, and limit the recursion depth.

```javascript
import readdirp from 'readdirp';
readdirp('test', {
  fileFilter: (f) => f.basename.endsWith('.js'),
  directoryFilter: (d) => d.basename !== '.git',
  // directoryFilter: (di) => di.basename.length === 9
  type: 'files_directories',
  depth: 1
});
```

--------------------------------

### Populate `fs.Stats` with `alwaysStat` Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

Set `alwaysStat: true` to populate `entry.stats` with full `fs.Stats` objects for every entry. This incurs a performance cost, roughly doubling traversal time, so use it only when stat fields like size or mtime are required.

```javascript
import readdirp from 'readdirp';

for await (const entry of readdirp('.', { alwaysStat: true })) {
  const { path, stats } = entry;
  console.log(path, `${(stats.size / 1024).toFixed(1)} KB`, stats.mtime.toISOString());
}
```

--------------------------------

### Stream API: readdirp(root, options)

Source: https://context7.com/paulmillr/readdirp/llms.txt

Returns a Node.js Readable stream that emits EntryInfo objects as the directory tree is traversed. Backpressure is respected, keeping memory usage near-constant. Can be consumed with `for await...of` or event listeners.

```APIDOC
## Stream API: readdirp(root, options)

Returns a `ReaddirpStream` (a Node.js `Readable` in object mode) that emits `EntryInfo` objects as the directory tree is traversed. Backpressure is respected automatically, making memory usage near-constant regardless of directory size. The stream can also be consumed with `for await...of`.

### Usage Examples:

#### for-await (recommended)
```js
import readdirp from 'readdirp';

for await (const entry of readdirp('./src')) {
  console.log(entry.path);
  console.log(entry.fullPath);
  console.log(entry.basename);
  console.log(entry.dirent);
}
```

#### event-based streaming
```js
readdirp('.', { alwaysStat: true, fileFilter: (f) => f.basename.endsWith('.js') })
  .on('data', (entry) => {
    const { path, stats: { size } } = entry;
    console.log(JSON.stringify({ path, size }));
  })
  .on('warn', (err) => console.error('non-fatal:', err))
  .on('error', (err) => console.error('fatal:', err))
  .on('end', () => console.log('done'));
```

#### manual abort via stream.destroy()
```js
const stream = readdirp('/large/directory');
stream.on('data', (entry) => {
  if (entry.basename === 'target.txt') {
    stream.destroy(); // triggers 'close', no more events emitted
  }
});
```
```

--------------------------------

### Handle Symbolic Links with `lstat` Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

Set `lstat: true` to use `fs.lstat` and include symbolic links as entries themselves, rather than following them. This is useful for inspecting symlinks directly.

```javascript
import { readdirpPromise } from 'readdirp';

// Expose symlinks as their own entries
const entries = await readdirpPromise('.', { lstat: true, alwaysStat: true });
entries.forEach((e) => {
  if (e.stats.isSymbolicLink()) {
    console.log('symlink:', e.path);
  }
});
```

--------------------------------

### Type Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

The `type` option controls which filesystem entry types are emitted. Valid values include 'files' (default), 'directories', 'files_directories', and 'all' (includes sockets, pipes, devices, etc.).

```APIDOC
## `type` Option

Controls which filesystem entry types are emitted. Valid values: `'files'` (default), `'directories'`, `'files_directories'`, `'all'` (includes sockets, pipes, devices, etc.).

```js
import { readdirpPromise } from 'readdirp';

// List only subdirectories (e.g. to build a directory tree)
const dirs = await readdirpPromise('.', { type: 'directories' });
dirs.forEach((d) => console.log(d.path));

// List both files and directories
const all = await readdirpPromise('.', { type: 'files_directories' });

// Include every filesystem entry (sockets, named pipes, etc.)
for await (const entry of readdirp('.', { type: 'all' })) {
  console.log(entry.basename, entry.dirent.isSymbolicLink());
}
```
```

--------------------------------

### EntryInfo Object

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Details about each file or directory entry found during the traversal. This object contains path information, basename, and optionally file system stats or Dirent objects.

```APIDOC
## EntryInfo Object

Has the following properties:

- `path`: path to the file/directory (relative to given root)
- `fullPath`: full path to the file/directory found
- `basename`: name of the file/directory
- `dirent`: built-in `fs.Dirent` object - only available when `alwaysStat` is `false`.
- `stats`: built-in `fs.Stats` object - only available when `alwaysStat` is `true`.
```

--------------------------------

### Promise API: readdirpPromise(root, options)

Source: https://context7.com/paulmillr/readdirp/llms.txt

Collects all matching entries into an array and resolves when traversal is complete. This API is simpler but holds all results in memory, so it should be avoided for very large directory trees.

```APIDOC
## Promise API: readdirpPromise(root, options)

Collects all matching entries into an array and resolves when traversal is complete. Simpler to use than the stream API but holds all results in memory simultaneously — avoid for very large directory trees.

### Usage Examples:

#### Basic usage — list all files recursively
```js
import { readdirpPromise } from 'readdirp';

const files = await readdirpPromise('.');
console.log(files.map((f) => f.path));
// [ 'src/index.ts', 'src/utils/helpers.ts', 'test/index.test.js', ... ]
```

#### With error handling
```js
try {
  const entries = await readdirpPromise('/project', {
    fileFilter: (f) => f.basename.endsWith('.ts'),
    directoryFilter: (d) => d.basename !== 'node_modules',
    depth: 3,
  });
  console.log(`Found ${entries.length} TypeScript files`);
  entries.forEach((e) => console.log(e.path, e.dirent.isFile()));
} catch (err) {
  console.error('traversal failed:', err);
}
```
```

--------------------------------

### EntryInfo Interface

Source: https://context7.com/paulmillr/readdirp/llms.txt

The EntryInfo interface defines the structure of objects returned by readdirp. Each object contains information about a file or directory, including its path, full path, basename, and optionally its dirent or stats.

```APIDOC
## EntryInfo Interface

Every object emitted by the stream or collected by the promise API conforms to this shape.

```ts
interface EntryInfo {
  path: string;      // relative path from root, e.g. "src/utils/helpers.ts"
  fullPath: string;  // absolute path, e.g. "/home/user/project/src/utils/helpers.ts"
  basename: string;  // filename only, e.g. "helpers.ts"
  dirent?: Dirent;   // present when alwaysStat: false (default)
  stats?: Stats;     // present when alwaysStat: true
}
```
```

--------------------------------

### Option: fileFilter

Source: https://context7.com/paulmillr/readdirp/llms.txt

Controls which files are emitted. It can be a function `(EntryInfo) => boolean`, a single filename string, or an array of filename strings. This filter does not affect directory traversal.

```APIDOC
## `fileFilter` Option

Accepts a function `(EntryInfo) => boolean`, a single filename string, or an array of filename strings. Controls which files are emitted. Does not affect directory traversal (use `directoryFilter` for that).

### Usage Examples:

#### Function predicate — filter by extension using dirent (no stat overhead)
```js
import readdirp from 'readdirp';

for await (const entry of readdirp('.', {
  fileFilter: (f) => f.basename.endsWith('.json'),
})) {
  console.log(entry.path); // only .json files
}
```

#### Array of exact basenames
```js
for await (const entry of readdirp('.', {
  fileFilter: ['package.json', 'tsconfig.json'],
})) {
  console.log(entry.path);
}
```

#### Filter by file size using stats (requires alwaysStat: true)
```js
for await (const entry of readdirp('.', {
  alwaysStat: true,
  fileFilter: (f) => f.stats.size > 1024 * 10, // files larger than 10 KB
})) {
  console.log(entry.path, entry.stats.size);
}
```
```

--------------------------------

### AlwaysStat Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

Setting `alwaysStat: true` calls `fs.stat` for every entry, populating `entry.stats` with a full `fs.Stats` object. This is useful when size, mtime, or other stat fields are needed, but it roughly doubles traversal time compared to the default `fs.Dirent` objects.

```APIDOC
## `alwaysStat` Option

By default readdirp returns `fs.Dirent` objects (fast, no extra I/O). Setting `alwaysStat: true` calls `fs.stat` for every entry, populating `entry.stats` with a full `fs.Stats` object. Use only when size, mtime, or other stat fields are needed — it roughly doubles traversal time.

```js
import readdirp from 'readdirp';

for await (const entry of readdirp('.', { alwaysStat: true })) {
  const { path, stats } = entry;
  console.log(path, `${(stats.size / 1024).toFixed(1)} KB`, stats.mtime.toISOString());
}
```
```

--------------------------------

### Filter Entry Types with `type` Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

The `type` option filters filesystem entries. Use 'directories' to list only subdirectories, 'files_directories' for both, or 'all' to include all entry types like sockets and pipes.

```javascript
import { readdirpPromise } from 'readdirp';

// List only subdirectories (e.g. to build a directory tree)
const dirs = await readdirpPromise('.', { type: 'directories' });
dirs.forEach((d) => console.log(d.path));

// List both files and directories
const all = await readdirpPromise('.', { type: 'files_directories' });

// Include every filesystem entry (sockets, named pipes, etc.)
for await (const entry of readdirp('.', { type: 'all' })) {
  console.log(entry.basename, entry.dirent.isSymbolicLink());
}
```

--------------------------------

### Option: directoryFilter

Source: https://context7.com/paulmillr/readdirp/llms.txt

Similar to `fileFilter` but applied to directories. Directories that fail this filter are neither emitted nor recursed into, effectively pruning entire subtrees.

```APIDOC
## `directoryFilter` Option

Same signature as `fileFilter` but applied to directories. Directories that fail the filter are neither emitted nor recursed into, pruning entire subtrees.

### Usage Example:

#### Skip hidden directories and node_modules
```js
import readdirp from 'readdirp';

for await (const entry of readdirp('.', {
  directoryFilter: (d) => !d.basename.startsWith('.') && d.basename !== 'node_modules',
  type: 'files_directories',
})) {
  console.log(entry.path);
}
```
```

--------------------------------

### readdirp Promise API

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Provides an asynchronous function to recursively read directory contents and return a promise that resolves to a list of entry information objects. This API is generally more RAM and CPU intensive than the stream API.

```APIDOC
## readdirp Promise API

`const entries = await readdirp.promise(root[, options])`

### Description
Recursively reads the given root directory and returns a promise that resolves to a list of [entry infos](#entryinfo).

### Parameters
- `root`: The path in which to start reading and recursing into subdirectories.

### Options
- `fileFilter`: filter to include or exclude files
    - **Function**: a function that takes an entry info as a parameter and returns true to include or false to exclude the entry
- `directoryFilter`: filter to include/exclude directories found and to recurse into. Directories that do not pass a filter will not be recursed into.
- `depth`: depth at which to stop recursing even if more subdirectories are found
- `type`: determines if data events on the stream should be emitted for `'files'` (default), `'directories'`, `'files_directories'`, or `'all'`.
- `alwaysStat`: always return `stats` property for every file. Default is `false`, readdirp will return `Dirent` entries. Setting it to `true` can double readdir execution time - use it only when you need file `size`, `mtime` etc. Cannot be enabled on node <10.10.0.
- `lstat`: include symlink entries in the stream along with files. When `true`, `fs.lstat` would be used instead of `fs.stat`
```

--------------------------------

### readdirp Stream API

Source: https://github.com/paulmillr/readdirp/blob/master/README.md

Reads the given root directory recursively and returns a stream of entry information. This API is designed for low memory and CPU usage. It can be used with `for await...of` loops or traditional stream event listeners.

```APIDOC
## readdirp Stream API

`const stream = readdirp(root[, options])`

### Description
Reads given root recursively and returns a `stream` of [entry infos](#entryinfo).
Optionally can be used like `for await (const entry of stream)` with node.js 10+ (`asyncIterator`).

### Events
- `on('data', (entry) => {})`: Emits an [entry info](#entryinfo) for every file or directory.
- `on('warn', (error) => {})`: Emits a non-fatal `Error` that prevents a file or directory from being processed (e.g., permission denied).
- `on('error', (error) => {})`: Emits a fatal `Error` which also ends the stream (e.g., illegal options were passed).
- `on('end')`: Emitted when all entries have been found and no more will be emitted.
- `on('close')`: Emitted when the stream is destroyed via `stream.destroy()`. This indicates the stream is no longer readable and no more events will be emitted.

### Options
- `fileFilter`: A function that takes an entry info and returns `true` to include or `false` to exclude files.
- `directoryFilter`: A function that takes an entry info and returns `true` to include or `false` to exclude directories. Directories that do not pass this filter will not be recursed into.
- `depth`: The maximum depth to recurse into subdirectories.
- `type`: Determines the type of entries to emit: `'files'` (default), `'directories'`, `'files_directories'`, or `'all'`.
- `alwaysStat`: If `true`, `stats` property will always be returned for every file. Default is `false`, returning `Dirent` entries. Enabling this can increase execution time.
- `lstat`: If `true`, `fs.lstat` is used instead of `fs.stat`, including symlink entries.
```

--------------------------------

### File Filter: Array of basenames

Source: https://context7.com/paulmillr/readdirp/llms.txt

Filter files by providing an array of exact basename strings. Only files matching any of the names in the array will be emitted.

```javascript
for await (const entry of readdirp('.', {
  fileFilter: ['package.json', 'tsconfig.json'],
})) {
  console.log(entry.path);
}
```

--------------------------------

### Stream API: Event-based streaming

Source: https://context7.com/paulmillr/readdirp/llms.txt

Consume the stream using event listeners for 'data', 'warn', 'error', and 'end'. This approach allows for more granular control and handling of stream events.

```javascript
readdirp('.', { alwaysStat: true, fileFilter: (f) => f.basename.endsWith('.js') })
  .on('data', (entry) => {
    const { path, stats: { size } } = entry;
    console.log(JSON.stringify({ path, size }));
  })
  .on('warn', (err) => console.error('non-fatal:', err))   // inaccessible entry
  .on('error', (err) => console.error('fatal:', err))       // unrecoverable error
  .on('end', () => console.log('done'));
```

--------------------------------

### Lstat Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

When `lstat` is set to `true`, the function uses `fs.lstat` instead of `fs.stat`. This means symbolic links themselves are included as entries in the stream rather than being transparently followed. Circular symlinks are always detected and reported as warnings.

```APIDOC
## `lstat` Option

When `true`, uses `fs.lstat` instead of `fs.stat`, so symbolic links themselves are included as entries in the stream rather than being transparently followed. Circular symlinks are always detected and reported as warnings regardless of this setting.

```js
import { readdirpPromise } from 'readdirp';

// Expose symlinks as their own entries
const entries = await readdirpPromise('.', { lstat: true, alwaysStat: true });
entries.forEach((e) => {
  if (e.stats.isSymbolicLink()) {
    console.log('symlink:', e.path);
  }
});
```
```

--------------------------------

### Use `ReaddirpStream` for Stream Pipelines

Source: https://context7.com/paulmillr/readdirp/llms.txt

The `readdirp()` function returns a `ReaddirpStream` instance, which extends `node:stream.Readable`. This allows it to be used in standard Node.js stream pipelines for processing directory entries.

```javascript
import { pipeline } from 'node:stream/promises';
import { createWriteStream } from 'node:fs';
import { Transform } from 'node:stream';
import { readdirp, ReaddirpStream } from 'readdirp';

const stream = readdirp('./src');
console.log(stream instanceof ReaddirpStream); // true

// Pipe into a transform that serialises paths as newline-delimited text
const toText = new Transform({
  objectMode: true,
  transform(entry, _enc, cb) { cb(null, entry.path + '\n'); },
});

await pipeline(stream, toText, createWriteStream('file-list.txt'));
```

--------------------------------

### Depth Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

The `depth` option limits how many levels deep the recursion goes. `depth: 0` lists only direct children of the root; `depth: 1` includes one level of subdirectories, and so on.

```APIDOC
## `depth` Option

Limits how many levels deep the recursion goes. `depth: 0` lists only direct children of root; `depth: 1` includes one level of subdirectories, etc.

```js
import { readdirpPromise } from 'readdirp';

// Only direct children
const shallow = await readdirpPromise('/project', { depth: 0 });

// Up to 2 levels deep
const twoLevels = await readdirpPromise('/project', { depth: 2 });
console.log(twoLevels.map((e) => e.path));
// [ 'src/index.ts', 'src/utils/helpers.ts' ]   — NOT 'src/utils/nested/deep.ts'
```
```

--------------------------------

### Limit Recursion Depth with `depth` Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

Use the `depth` option to control how many levels deep the recursion goes. `depth: 0` lists only direct children, while higher values include subdirectories.

```javascript
import { readdirpPromise } from 'readdirp';

// Only direct children
const shallow = await readdirpPromise('/project', { depth: 0 });

// Up to 2 levels deep
const twoLevels = await readdirpPromise('/project', { depth: 2 });
console.log(twoLevels.map((e) => e.path));
// [ 'src/index.ts', 'src/utils/helpers.ts' ]   — NOT 'src/utils/utils/deep.ts'
```

--------------------------------

### Tune Backpressure with `highWaterMark` Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

Adjust the `highWaterMark` option to control the Node.js `Readable` stream's backpressure. Lower values reduce peak memory usage, while higher values may improve throughput. The default is 4096.

```javascript
import readdirp from 'readdirp';

// Low memory footprint for very large trees
const stream = readdirp('/data', { highWaterMark: 16, type: 'all' });
stream.on('data', (entry) => process.stdout.write(entry.path + '\n'));
stream.on('end', () => console.log('complete'));
```

--------------------------------

### ReaddirpStream Class

Source: https://context7.com/paulmillr/readdirp/llms.txt

The `ReaddirpStream` class is returned by the `readdirp()` function. It extends `node:stream.Readable` in object mode and can be used in any context that accepts a Node.js readable stream, such as pipe chains or `stream.pipeline`.

```APIDOC
## `ReaddirpStream` Class

The class returned by `readdirp()`. Extends `node:stream.Readable` in object mode. Can be used anywhere a Node.js readable stream is accepted (pipe chains, `stream.pipeline`, etc.).

```js
import { pipeline } from 'node:stream/promises';
import { createWriteStream } from 'node:fs';
import { Transform } from 'node:stream';
import { readdirp, ReaddirpStream } from 'readdirp';

const stream = readdirp('./src');
console.log(stream instanceof ReaddirpStream); // true

// Pipe into a transform that serialises paths as newline-delimited text
const toText = new Transform({
  objectMode: true,
  transform(entry, _enc, cb) { cb(null, entry.path + '\n'); },
});

await pipeline(stream, toText, createWriteStream('file-list.txt'));
```
```

--------------------------------

### HighWaterMark Option

Source: https://context7.com/paulmillr/readdirp/llms.txt

The `highWaterMark` option is passed directly to the underlying Node.js `Readable` stream to tune backpressure. Lower values reduce peak memory usage, while higher values may improve throughput. The default value is `4096`.

```APIDOC
## `highWaterMark` Option

Passed directly to the underlying Node.js `Readable` stream to tune backpressure. Lower values reduce peak memory; higher values may improve throughput. Default is `4096`.

```js
import readdirp from 'readdirp';

// Low memory footprint for very large trees
const stream = readdirp('/data', { highWaterMark: 16, type: 'all' });
stream.on('data', (entry) => process.stdout.write(entry.path + '\n'));
stream.on('end', () => console.log('complete'));
```
```

--------------------------------

### Stream API: Manual abort

Source: https://context7.com/paulmillr/readdirp/llms.txt

Manually destroy the stream using `stream.destroy()` to stop traversal early. This is useful when a specific condition is met and further processing is unnecessary.

```javascript
const stream = readdirp('/large/directory');
stream.on('data', (entry) => {
  if (entry.basename === 'target.txt') {
    stream.destroy(); // triggers 'close', no more events emitted
  }
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.