ancesdir

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

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

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

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

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

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

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.

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

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.

import {ancesdir} from "ancesdir";

ancesdir({force: true});

import {closesdir} from "closesdir";

closesdir({force: true});