ancesdir
Version:
Find a specific ancestor/root directory given a starting location and a search parameter
171 lines (108 loc) • 6.24 kB
Markdown
# ancesdir
[](https://github.com/somewhatabstract/ancesdir/actions) [](https://codecov.io/gh/somewhatabstract/ancesdir) [](https://www.npmjs.com/package/ancesdir) [](https://img.shields.io/node/v/ancesdir/latest)
`ancesdir` provides a simple, yet versatile function to find a specific ancestor/root directory given a starting location and a search parameter
There are a few packages out there that already support finding the root directory of a project based off assumptions like that directory containing `package.json` or `node_modules`. However, this is not always the case. I needed a way to find an ancestor directory that may not always have these markers. So, this provides the means to specify a custom marker file or directory as the means to identify the ancestor that you may need.
This may be useful in a variety of situations. For example, a monorepo where you want to differentiate in development scripts between the root folder of each package, and the root folder of the entire repository.
## Getting Started
### pnpm
**`pnpm add ancesdir`**
### yarn
**`yarn add ancesdir`**
### npm
**`npm install ancesdir`**
## Usage
### `ancesdir`
This method (the default export from the package) finds the first ancestor directory that contains a file or directory called `package.json` by default, or a custom marker file or directory if specified. The search starts with the
parent of the given location.
#### Default
```typescript
import ancesdir from "ancesdir";
console.log(ancesdir());
```
Outputs the absolute path of the first parent directory to the `ancesdir` package that contains `package.json`.
In most cases, this is likely all you need.
#### From Specific Location
```typescript
import ancesdir from "ancesdir";
console.log(ancesdir(__dirname));
```
Outputs the absolute path of the first parent directory to `__dirname` that contains `package.json`.
#### Custom Target From Specific Location
```typescript
import ancesdir from "ancesdir";
console.log(ancesdir(__dirname, ".mymarkerfile");
```
Outputs the absolute path of the first parent directory that contains a file or directory called `.mymarkerfile`.
This is useful if you don't have a classic file hierarchy or you want to use this for more advanced use cases where having control over the file system item that identifies your ancestor is useful.
### `closesdir`
The `closesdir` export provides a similar function to `ancesdir`, except that
it starts the search in the starting directory, rather than its parent.
#### Default
```typescript
import {closesdir} from "closesdir";
console.log(closesdir());
```
Outputs the absolute path of the first parent directory to the `ancesdir` package that contains `package.json`. This is the same as calling `ancesdir()`.
#### From Specific Location
```typescript
import {closesdir} from "closesdir";
console.log(closesdir(__dirname));
```
Outputs the absolute path of the first directory that contains `package.json`, starting with `__dirname` and then moving up the directory tree.
#### Custom Target From Specific Location
```typescript
import {closesdir} from "closesdir";
console.log(closesdir(__dirname, ".mymarkerfile");
```
Outputs the absolute path of the first directory that contains a file or directory called `.mymarkerfile`, starting with `__dirname` and then moving up the directory tree.
This is useful if you don't have a classic file hierarchy or you want to use this for more advanced use cases where having control over the file system item that identifies your target directory is useful.
### Options
Both `ancesdir` and `closesdir` support an options object as the second argument. This allows you to customize the behavior of the search via those
options rather than individual arguments.
```typescript
type Options = {
/**
* Whether to force a full search, or to use the cache.
* If true, the search will ignore any cached results and search the
* file system for the marker, updating the cache with the results.
* Otherwise, it will use the cached results when available.
* Defaults to false.
*/
force?: boolean;
/**
* The absolute path to start the search from.
* If not provided:
* - For `ancesdir` calls, defaults to the package directory of the
* `ancesdir` module.
* - For `closesdir` calls, defaults to the parent directory of the
* `ancesdir` module.
*/
from?: string;
/**
* The marker to look for in the directory structure.
* Defaults to "package.json".
*/
marker?: string;
};
```
### Caching
All requests are cached so that subsequent calls to the same directory or any
directory checked during the search do not require a new search. This is useful if you are calling this function multiple times in a single run of your program.
However, there may be times where you want to clear the cache, or force a specific request to be made without using the cache. For this, you can use the `clearCache`, or `force` options.
#### Clear Cache
```typescript
import {clearCache} from "ancesdir";
clearCache();
```
This will clear all cached results, so that subsequent calls to `ancesdir` or `closesdir` will start to rebuild the cache from scratch based on the current state of the file system.
#### Force Request
Both `ancesdir` and `closesdir` support a call signature that takes an `options` object. One of those options is a `force` boolean. If this is set to `true`, the function will not use the cache for the request and will always instead perform a new search, updating the cache in the process for that search.
This is less impactful than clearing the cache with `clearCache`, as it only affects the specific request being made, rather than all requests.
```typescript
import {ancesdir} from "ancesdir";
ancesdir({force: true});
```
```typescript
import {closesdir} from "closesdir";
closesdir({force: true});
```