Exists

Test whether a path exists on the filesystem.

Usage

var exists = require( '@stdlib/fs/exists' );

exists( path, clbk )

Asynchronously tests whether a path exists on the filesystem.

exists( __dirname, done );

function done( bool ) {
    if ( bool ) {
        console.log( '...path exists.' );
    } else {
        console.log( '...path does not exist.' );
    }
}

The above callback signature matches the now deprecated fs.exists() API. The function also accepts the more conventional error-first style callback signature found in most asynchronous Node APIs.

exists( __dirname, done );

function done( error, bool ) {
    if ( error ) {
        console.error( error.message );
    }
    if ( bool ) {
        console.log( '...path exists.' );
    } else {
        console.log( '...path does not exist.' );
    }
}

exists.sync( path )

Synchronously tests whether a path exists on the filesystem.

var bool = exists.sync( __dirname );
// returns <boolean>

Notes

  • The following is considered an anti-pattern:

    var path = require( 'path' );
    var readFileSync = require( '@stdlib/fs/read-file' ).sync;
    
    var file = path.join( __dirname, 'foo.js' );
    if ( exists.sync( __dirname ) ) {
        file = readFileSync( file );
    }
    

    Because time elapses between checking for existence and performing IO, at the time IO is performed, the path is no longer guaranteed to exist. In other words, a race condition exists between the process attempting to read and another process attempting to delete.

    Instead, the following pattern is preferred, where errors are handled explicitly:

    var path = require( 'path' );
    var readFileSync = require( '@stdlib/fs/read-file' ).sync;
    
    var file = path.join( __dirname, 'foo.js' );
    try {
        file = readFileSync( file );
    } catch ( error ) {
        console.log( 'unable to read file.' );
        console.error( error );
    }
    
  • Nevertheless, use cases exist where one desires to check existence without performing IO. For example,

    var path = require( 'path' );
    var writeFileSync = require( '@stdlib/fs/write-file' ).sync;
    
    var file = path.join( __dirname, 'foo.js' );
    if ( exists.sync( file ) ) {
        console.log( 'Don\'t overwrite the file!' );
    } else {
        writeFileSync( file, 'beep', {
            'encoding': 'utf8'
        });
    }
    

Examples

var exists = require( '@stdlib/fs/exists' );

/* Sync */

console.log( exists.sync( __dirname ) );
// => true

console.log( exists.sync( 'beepboop' ) );
// => false


/* Async */

exists( __dirname, done );
exists( 'beepboop', done );

function done( error, bool ) {
    if ( error ) {
        console.error( error.message );
    } else {
        console.log( bool );
    }
}

CLI

Usage

Usage: exists [options] <path>

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.

Notes

  • Relative paths are resolved relative to the current working directory.
  • Errors are written to stderr.
  • Results are written to stdout.

Examples

$ exists ./../
true || <error_message>