seniority/find-up

import { findUpMultipleSync, findUpMultiple, findUpSync, … } from 'seniority/find-up';

function findDown(name: Name, options?: FindDownOptions): Promise<string | undefined>;

function findDownSync(name: Name, options?: FindDownOptions): string | undefined;

function findUp(name: Name | Matcher<MatcherResult | Promise<MatcherResult>>, options?: Options): Promise<string | undefined>;

function findUpMultiple(name: Name | Matcher<MatcherResult | Promise<MatcherResult>>, options?: Options): Promise<string[]>;

function findUpMultipleSync(name: Name | Matcher<MatcherResult>, options?: Options): string[];

function findUpSync(name: Name | Matcher<MatcherResult>, options?: Options): string | undefined;

const findUpStop: unique symbol;

interface FindDownOptions {
    /** Where to start. Defaults to the process's working directory. */
    readonly cwd?: URL | string;
    /** How many directories below `cwd` to look. `0` is `cwd` alone; defaults to `1`. */
    readonly depth?: number;
    /** Nearest level first (`'breadth'`, the default) or each branch to the bottom first (`'depth'`). */
    readonly strategy?: 'breadth' | 'depth';
    readonly type?: 'file' | 'directory' | 'both';
    readonly allowSymlinks?: boolean;
}

interface Options {
    /** Where to start. Defaults to the process's working directory. */
    readonly cwd?: URL | string;
    /** The highest directory to look in, inclusive. Defaults to the filesystem root. */
    readonly stopAt?: URL | string;
    /** What a name must be to match. Defaults to `'file'`. */
    readonly type?: 'file' | 'directory' | 'both';
    /** Follow a symbolic link to what it points at. Defaults to `true`. */
    readonly allowSymlinks?: boolean;
    /** How many matches `findUpMultiple` collects at most. Defaults to `Infinity`. */
    readonly limit?: number;
}

type Match = string | typeof findUpStop | undefined;