CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-isexe

Minimal module to check if a file is executable across different platforms

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

isexe

isexe is a minimal, cross-platform module for checking if a file is executable on the current system. It provides both asynchronous and synchronous APIs with platform-specific implementations for Windows (using PATHEXT) and POSIX systems (using file permissions).

Package Information

  • Package Name: isexe
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install isexe

Core Imports

import { isexe, sync, IsexeOptions } from "isexe";

For CommonJS:

const { isexe, sync } = require("isexe");

Platform-specific imports:

// Import specific platform implementations directly
import { isexe, sync } from "isexe/posix";
import { isexe, sync } from "isexe/win32";

// Or import platform namespaces
import { posix, win32 } from "isexe";

Basic Usage

import { isexe, sync } from "isexe";

// Asynchronous check
const isExecutable = await isexe("some-file-name");
if (isExecutable) {
  console.log("File can be executed");
} else {
  console.log("File cannot be executed");
}

// Synchronous check
try {
  const isExecutable = sync("some-file-name");
  console.log(isExecutable ? "Executable" : "Not executable");
} catch (error) {
  console.error("Error checking file:", error.message);
}

// With error handling options
const isExecutable = await isexe("maybe-missing-file", { ignoreErrors: true });

Architecture

isexe uses platform-specific detection to automatically choose the appropriate implementation:

  • Cross-platform Interface: Main functions (isexe, sync) automatically detect the platform
  • Platform-specific Implementations: Separate implementations for Windows and POSIX systems
  • Windows Implementation: Uses file extensions and the PATHEXT environment variable
  • POSIX Implementation: Uses file mode bits and user/group permissions
  • Options Interface: Unified configuration options for both implementations

Capabilities

Main Executable Check

Core functionality for checking file executability using the platform-appropriate method.

/**
 * Determine whether a path is executable on the current platform.
 * @param path - File path to check
 * @param options - Configuration options
 * @returns Promise resolving to true if executable, false otherwise
 */
function isexe(path: string, options?: IsexeOptions): Promise<boolean>;

/**
 * Synchronously determine whether a path is executable on the current platform.
 * @param path - File path to check  
 * @param options - Configuration options
 * @returns true if executable, false otherwise
 * @throws Error if file access fails and ignoreErrors is false
 */
function sync(path: string, options?: IsexeOptions): boolean;

Platform-Specific Implementations

Access to specific platform implementations when needed.

// Platform namespace imports - imported as { posix, win32 } from "isexe"
declare namespace posix {
  /**
   * Check executability using POSIX file mode and permissions
   */
  function isexe(path: string, options?: IsexeOptions): Promise<boolean>;
  
  /**
   * Synchronously check executability using POSIX file mode and permissions
   */
  function sync(path: string, options?: IsexeOptions): boolean;
}

declare namespace win32 {
  /**
   * Check executability using Windows PATHEXT environment variable
   */
  function isexe(path: string, options?: IsexeOptions): Promise<boolean>;
  
  /**
   * Synchronously check executability using Windows PATHEXT environment variable
   */
  function sync(path: string, options?: IsexeOptions): boolean;
}

// Direct platform-specific imports - import { isexe, sync } from "isexe/posix" or "isexe/win32"
// These provide the same functions as above but imported directly from specific modules

Usage Examples:

import { win32, posix } from "isexe";

// Force use of Windows implementation via namespace
const isExeWin32 = await win32.isexe("script.bat");

// Force use of POSIX implementation via namespace
const isExePosix = await posix.isexe("/usr/bin/node");

// Or import directly from specific modules
import { isexe as posixIsexe } from "isexe/posix";
import { sync as win32Sync } from "isexe/win32";

const result1 = await posixIsexe("/usr/bin/node");
const result2 = win32Sync("script.cmd");

Types

interface IsexeOptions {
  /**
   * Ignore errors arising from attempting to get file access status.
   * Note that EACCES is always ignored, because that just means
   * it's not executable. If this is not set, then attempting to check
   * the executable-ness of a nonexistent file will raise ENOENT.
   * @default false
   */
  ignoreErrors?: boolean;

  /**
   * Effective uid when checking executable mode flags on POSIX systems.
   * Defaults to process.getuid()
   */
  uid?: number;

  /**
   * Effective gid when checking executable mode flags on POSIX systems.
   * Defaults to process.getgid()
   */
  gid?: number;

  /**
   * Effective group ID list to use when checking executable mode flags
   * on POSIX systems.
   * Defaults to process.getgroups()
   */
  groups?: number[];

  /**
   * The ;-delimited path extension list for Windows implementation.
   * Defaults to process.env.PATHEXT
   * @example ".COM;.EXE;.BAT;.CMD"
   */
  pathExt?: string;
}

Error Handling

By default, isexe functions will throw filesystem errors (like ENOENT for missing files). However:

  • EACCES errors are always treated as "not executable" rather than thrown
  • ignoreErrors option treats all errors as "not executable" without throwing
  • Synchronous functions throw errors directly
  • Asynchronous functions return Promise rejections
// Handle errors explicitly
try {
  const result = await isexe("nonexistent-file");
} catch (error) {
  if (error.code === "ENOENT") {
    console.log("File does not exist");
  }
}

// Ignore all errors
const result = await isexe("maybe-missing-file", { ignoreErrors: true });
// result will be false for any error, including missing files

Platform Behavior

Windows

  • Uses the PATHEXT environment variable to determine executable extensions
  • Checks if the file extension matches any extension in PATHEXT
  • Common PATHEXT extensions: .COM, .EXE, .BAT, .CMD, .VBS, .VBE, .JS, .JSE, .WSF, .WSH
  • Can override PATHEXT using the pathExt option

POSIX (Linux, macOS, Unix)

  • Uses file mode permissions and user/group ownership
  • Checks execute bits: owner (u+x), group (g+x), or other (o+x)
  • Considers effective user ID and group memberships
  • Root user (uid 0) can execute files with owner or group execute permissions
  • Can override uid/gid for permission checks using options

docs

index.md

tile.json