0
# isexe
1

2
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).
3

4
## Package Information
5

6
- **Package Name**: isexe
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install isexe`
10

11
## Core Imports
12

13
```typescript
14
import { isexe, sync, IsexeOptions } from "isexe";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { isexe, sync } = require("isexe");
21
```
22

23
Platform-specific imports:
24

25
```typescript
26
// Import specific platform implementations directly
27
import { isexe, sync } from "isexe/posix";
28
import { isexe, sync } from "isexe/win32";
29

30
// Or import platform namespaces
31
import { posix, win32 } from "isexe";
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { isexe, sync } from "isexe";
38

39
// Asynchronous check
40
const isExecutable = await isexe("some-file-name");
41
if (isExecutable) {
42
  console.log("File can be executed");
43
} else {
44
  console.log("File cannot be executed");
45
}
46

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

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

59
## Architecture
60

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

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

69
## Capabilities
70

71
### Main Executable Check
72

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

75
```typescript { .api }
76
/**
77
 * Determine whether a path is executable on the current platform.
78
 * @param path - File path to check
79
 * @param options - Configuration options
80
 * @returns Promise resolving to true if executable, false otherwise
81
 */
82
function isexe(path: string, options?: IsexeOptions): Promise<boolean>;
83

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

94
### Platform-Specific Implementations
95

96
Access to specific platform implementations when needed.
97

98
```typescript { .api }
99
// Platform namespace imports - imported as { posix, win32 } from "isexe"
100
declare namespace posix {
101
  /**
102
   * Check executability using POSIX file mode and permissions
103
   */
104
  function isexe(path: string, options?: IsexeOptions): Promise<boolean>;
105
  
106
  /**
107
   * Synchronously check executability using POSIX file mode and permissions
108
   */
109
  function sync(path: string, options?: IsexeOptions): boolean;
110
}
111

112
declare namespace win32 {
113
  /**
114
   * Check executability using Windows PATHEXT environment variable
115
   */
116
  function isexe(path: string, options?: IsexeOptions): Promise<boolean>;
117
  
118
  /**
119
   * Synchronously check executability using Windows PATHEXT environment variable
120
   */
121
  function sync(path: string, options?: IsexeOptions): boolean;
122
}
123

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

128
**Usage Examples:**
129

130
```typescript
131
import { win32, posix } from "isexe";
132

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

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

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

143
const result1 = await posixIsexe("/usr/bin/node");
144
const result2 = win32Sync("script.cmd");
145
```
146

147
## Types
148

149
```typescript { .api }
150
interface IsexeOptions {
151
  /**
152
   * Ignore errors arising from attempting to get file access status.
153
   * Note that EACCES is always ignored, because that just means
154
   * it's not executable. If this is not set, then attempting to check
155
   * the executable-ness of a nonexistent file will raise ENOENT.
156
   * @default false
157
   */
158
  ignoreErrors?: boolean;
159

160
  /**
161
   * Effective uid when checking executable mode flags on POSIX systems.
162
   * Defaults to process.getuid()
163
   */
164
  uid?: number;
165

166
  /**
167
   * Effective gid when checking executable mode flags on POSIX systems.
168
   * Defaults to process.getgid()
169
   */
170
  gid?: number;
171

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

179
  /**
180
   * The ;-delimited path extension list for Windows implementation.
181
   * Defaults to process.env.PATHEXT
182
   * @example ".COM;.EXE;.BAT;.CMD"
183
   */
184
  pathExt?: string;
185
}
186
```
187

188
## Error Handling
189

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

192
- **EACCES errors** are always treated as "not executable" rather than thrown
193
- **ignoreErrors option** treats all errors as "not executable" without throwing
194
- **Synchronous functions** throw errors directly
195
- **Asynchronous functions** return Promise rejections
196

197
```typescript
198
// Handle errors explicitly
199
try {
200
  const result = await isexe("nonexistent-file");
201
} catch (error) {
202
  if (error.code === "ENOENT") {
203
    console.log("File does not exist");
204
  }
205
}
206

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

212
## Platform Behavior
213

214
### Windows
215
- Uses the PATHEXT environment variable to determine executable extensions
216
- Checks if the file extension matches any extension in PATHEXT
217
- Common PATHEXT extensions: `.COM`, `.EXE`, `.BAT`, `.CMD`, `.VBS`, `.VBE`, `.JS`, `.JSE`, `.WSF`, `.WSH`
218
- Can override PATHEXT using the `pathExt` option
219

220
### POSIX (Linux, macOS, Unix)
221
- Uses file mode permissions and user/group ownership
222
- Checks execute bits: owner (u+x), group (g+x), or other (o+x)
223
- Considers effective user ID and group memberships
224
- Root user (uid 0) can execute files with owner or group execute permissions
225
- Can override uid/gid for permission checks using options