1.0.3 • Public • Published


    Build Status

    Create a list of possible file locations based on user defined arguments and extract the first valid path


    npm install find-a-file


    npm install -g find-a-file

    Then import the module into your program:

    var FindAFile = require('find-a-file')


    Note - This module uses StringTrees Objects as inputs and Resolution Objects as outputs.

    The module exports a function which will create a Finder based in the current directory.

    You can then synchronously find a file path relative to the location stored within that Finder based on provided parameters.

    The parameters are as follows:

    • Base - (StringTree) - The StringTree representation of the Base directories to use to search for Files
      • Default - '$CURRENT'
    • Format - (StringTree) - The StringTree representation of the file paths to search
      • Default - ['$BASE','$DIR','$NAME$EXT']
      • Note - All elements within this StringTree will be automatically joined with a slash (/)
    • Extension - (String) - The extension to use to create a file path if one was not provided
      • Default - '.js'
    • Encoding - (String) - The encoding to use when loading a file
      • Default - 'utf8'

    All StringTrees will map the following values:

    • $BASE - The provided Base parameter
    • $INITIAL - The directory from which the Finder was created
    • $CURRENT - The directory of which the file in this Finder resides
    • $DIR - The directory as provided to the Finder.find() method
    • $NAME - The name as provided to the Finder.find() method
    • $EXT - The extension as provided to the Finder.find() method (or the default)

    The default values can be overwritten with the following method:

    FindAFile.defineSettings( opts )

    • opts (Object) - The options to change (see above for parameters)

    Note - This method returns the exports object, so it can be immediately invoked upon importing

    var FindAFile = require('find-a-file').defineSettings({ ... })

    Creating a Finder

    A Finder can be created by invoking the module as a method:

    FindAFile( opts )

    • opts (Object) - The options to apply specific to this Finder (see above for parameters)
      • Optional - If not provided, the default options will be used

    This will create a Finder based in the current directory with the provided Options

    Note - Not the directory the script is stored in, but the directory the script was called from

    Finding a File

    First, create a Finder

    var finder = FindAFile()

    To find a file, use:

    .find( filepath )

    • filepath (String) - The input to use to find a valid file path

    Using the built-in path module, the provided filepath will be separated into 3 parameters:

    • dir - The directory in which the will reside
      • Optional - If not provided, then it will not look for the file within any subdirectories
    • name - The name of the file to load
      • Required
    • ext - The extension of the file to look for
      • Optional - If not provided, then it will use the extension stored within the Finder
    var file = finder.find('index')

    Since only the default parameters were used, the program will look for a file at the following locations:


    It returns a Resolution object, which is either resolved to another Finder or rejected with an Error

    It will be resolved if a valid file path was found based on the given parameters

    if( file.resolved ){
        finder = file.value;
        throw file.value;

    The new Finder object will copy the parameters from the Initial Finder object with the exception of the following:

    • $CURRENT will be updated to the directory in which the found file resides
    • $EXT will be the extension of the found file

    Here is another example in which the found file is in a different directory:

    file = finder.find('data\names.txt')
    Will check the following locations:
    finder = file.value
    file = finder.find('index')
    Since we are using the new 'finder', it will check the following locations:
    where '$CURRENT' is now '<previous $CURRENT>\data\'
    //To get the desired file from the new finder:
    file = finder.find('..\index.js')

    Loading a File

    A file can be loaded either synchronously or asynchronously:

    .load( callback )

    • Will run fs.readFile( <filepath>, <encoding>, <callback> )


    • Will return the result of fs.readFileSync( <filepath>, <encoding> )

    Adding Bases

    You can set the Base directories to use to find a file:

    var finder = FindAFile({
      Base : [[
    Will check the following locations:

    Using a Different Format

    You can set the Format to use to find a file:

    var finder = FindAFile({
      Format : [
    Will check the following locations:

    You can insert a ^ anywhere within the the filepath to check all parent directories as well

    It will stop searching when there is no parent directory or the parent directory has already been searched

    var finder = FindAFile({
      Format : [
    Will check the following locations:




    npm i find-a-file

    DownloadsWeekly Downloads






    Last publish


    • avatar