time-to-botec/squiggle/node_modules/@stdlib/fs/exists/README.md

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>