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