isexe

What is isexe?

The isexe npm package is used to check if a file is executable. It provides a simple interface to determine whether a given file path points to an executable file, based on the file's permissions and metadata. This can be particularly useful in build scripts, CLI tools, or any Node.js application that needs to validate file executability before proceeding with operations like launching a subprocess.

What are isexe's main functionalities?

Check if a file is executable

This feature allows you to check asynchronously if a specific file is executable. It uses a callback function to return the result.

const isexe = require('isexe');

isexe('/path/to/file', function(err, isExecutable) {
  if (err) return console.error(err);
  console.log(isExecutable ? 'Executable' : 'Not executable');
});

Synchronous check for file executability

This feature provides a synchronous way to check if a file is executable, which can be useful in scripts where asynchronous operations are not desired.

const isexe = require('isexe');

try {
  const isExecutable = isexe.sync('/path/to/file');
  console.log(isExecutable ? 'Executable' : 'Not executable');
} catch (err) {
  console.error(err);
}

Check executability with options

This feature demonstrates how to use the `isexe` package with options to customize the behavior of the executability check. For example, specifying `pathExt` option on Windows to consider certain file extensions as executable.

const isexe = require('isexe');

const options = { pathExt: '.EXE' }; // Example option for Windows environments

isexe('/path/to/file', options, function(err, isExecutable) {
  if (err) return console.error(err);
  console.log(isExecutable ? 'Executable' : 'Not executable');
});

Other packages similar to isexe

execa

While execa is primarily focused on providing a better `child_process` experience, it indirectly deals with executables by allowing you to execute external commands. It doesn't provide direct functionality to check if a file is executable, but it's related in the context of working with executables.

fs-extra

fs-extra extends the built-in Node.js `fs` module with additional functionality. It doesn't offer a direct method to check if a file is executable, but it provides more comprehensive file system operations which, combined with Node's native capabilities, could be used to implement a custom executability check.

README

isexe

Minimal module to check if a file is executable, and a normal file.

Uses fs.stat and tests against the PATHEXT environment variable on Windows.

USAGE

import { isexe, sync } from 'isexe'
// or require() works too
// const { isexe } = require('isexe')
isexe('some-file-name').then(isExe => {
  if (isExe) {
    console.error('this thing can be run')
  } else {
    console.error('cannot be run')
  }
}, (err) => {
  console.error('probably file doesnt exist or something')
})

// same thing but synchronous, throws errors
isExe = sync('some-file-name')

// treat errors as just "not executable"
const isExe = await isexe('maybe-missing-file', { ignoreErrors: true })
const isExe = sync('maybe-missing-file', { ignoreErrors: true })

API

isexe(path, [options]) => Promise<boolean>

Check if the path is executable.

Will raise whatever errors may be raised by fs.stat, unless options.ignoreErrors is set to true.

sync(path, [options]) => boolean

Same as isexe but returns the value and throws any errors raised.

Platform Specific Implementations

If for some reason you want to use the implementation for a specific platform, you can do that.

import { win32, posix } from 'isexe'
win32.isexe(...)
win32.sync(...)
// etc

// or:
import { isexe, sync } from 'isexe/posix'

The default exported implementation will be chosen based on process.platform.

Options

import type IsexeOptions from 'isexe'

• ignoreErrors Treat all errors as "no, this is not executable", but don't raise them.
• uid Number to use as the user id on posix
• gid Number to use as the group id on posix
• pathExt List of path extensions to use instead of PATHEXT environment variable on Windows.