ARCHITECTURE.md
# Architecture
This document describes the high-level architecture of `fdir`. If you want to familiarize yourself with the code base, you are in the right place!
---
On the highest level, `fdir` is a library that accepts a path to a directory as input and outputs all the file paths in that directory recrusively.
More specifically, input data consists of a path to a directory (`rootDirectory`) and different flags and filters to control the walking process. To increase performance, `fdir` builds internal functions conditionally based on the passed flags. Since these "conditional" functions are tiny, they are inlined by the Javascript Engine reducing branching & allocations.
## Entry Points
`index.js` exports the main `fdir` class and it is the main entry point. However, there is nothing of importance in this file aside from the export.
`src/builder/index.js` contains the main API of `fdir` exposed via a `Builder` class. This is where all the flags & filters are built and passed (as an `options` Object) onto the core of `fdir`.
## Code Map
This section talks briefly about all the directories and what each file in each directory does.
### `src/api`
This is the core of `fdir`.
**`walker.js`:** This contains the `Walker` class which is responsible for controlling and maintaining the state of the directory walker. It builds the conditional functions, processes the `Dirents` and delegates the actual filesystem directory reading to sync/async APIs.
**`async.js`** This contains the asynchronous (`fs.readdir`) logic. This is the starting point of the async crawling process.
**`queue.js`** This contains a tiny `Queue` class to make sure `fdir` doesn't early exit during walking. It increments a counter for each "walk" queued and decrements it when it finishes. Once the counter hits 0, it calls the callback which returns the output to the user.
**`sync.js`** This contains the synchronous (`fs.readdirSync`) logic. This is the starting point of the sync crawling process.
**`fns.js`** This contains the implementations of all the conditional functions.
### `src/builder`
This is what gets exposed to the developer and contains 2 builders that aid in building an `options` object to control various aspects of the walker.
### `src/compat`
Since `fdir` supports Node <= 10.0, this directory contains the compatibility code to bridge the newer (v10.0) filesystem API with the older (v8.0) filesystem API.