0
# Path Key
1

2
Path Key provides a cross-platform utility function for getting the correct PATH environment variable key. It handles platform-specific differences where PATH is typically uppercase on Unix-like systems but can have various casings on Windows (PATH, Path, path).
3

4
## Package Information
5

6
- **Package Name**: path-key
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install path-key`
10

11
## Core Imports
12

13
```typescript
14
import pathKey from "path-key";
15
```
16

17
**Note**: This package is a pure ES module and does not support CommonJS require().
18

19
## Basic Usage
20

21
```typescript
22
import pathKey from "path-key";
23

24
// Get the correct PATH key for current environment
25
const key = pathKey();
26
console.log(key); // "PATH" on Unix, "Path" or "PATH" on Windows
27

28
// Access the PATH variable
29
const pathValue = process.env[key];
30
console.log(pathValue); // "/usr/local/bin:/usr/bin:/bin" or similar
31

32
// Use with custom environment or platform
33
const windowsKey = pathKey({ platform: "win32" });
34
const customKey = pathKey({ env: { Path: "/custom/path" }, platform: "win32" });
35
```
36

37
## Capabilities
38

39
### Path Key Detection
40

41
Returns the correct PATH environment variable key for the specified or current platform.
42

43
```typescript { .api }
44
/**
45
 * Get the PATH environment variable key cross-platform
46
 * @param options - Configuration options for environment and platform
47
 * @returns The correct PATH environment variable key
48
 */
49
function pathKey(options?: Options): string;
50

51
interface Options {
52
  /**
53
   * Use a custom environment variables object.
54
   * Default: process.env
55
   */
56
  readonly env?: Record<string, string | undefined>;
57
  
58
  /**
59
   * Get the PATH key for a specific platform.
60
   * Default: process.platform
61
   */
62
  readonly platform?: NodeJS.Platform;
63
}
64
```
65

66
**Platform Behavior:**
67

68
- **Non-Windows platforms** (Linux, macOS, etc.): Always returns `"PATH"`
69
- **Windows platform**: Searches the environment object for case-insensitive PATH matches and returns the last found key, or defaults to `"Path"` if none found
70

71
**Usage Examples:**
72

73
```typescript
74
import pathKey from "path-key";
75

76
// Basic usage - uses current environment and platform
77
const key = pathKey();
78

79
// Specify platform explicitly
80
const unixKey = pathKey({ platform: "darwin" }); // Always "PATH"
81
const windowsKey = pathKey({ platform: "win32" }); // Searches env for PATH variants
82

83
// Use custom environment object
84
const customEnv = { Path: "/custom/path", OTHER_VAR: "value" };
85
const customKey = pathKey({ env: customEnv, platform: "win32" }); // Returns "Path"
86

87
// Handle multiple PATH variants on Windows
88
const multiEnv = { PATH: "/path1", Path: "/path2", path: "/path3" };
89
const resultKey = pathKey({ env: multiEnv, platform: "win32" }); // Returns "path" (last found)
90

91
// Empty environment on Windows defaults to "Path"
92
const emptyKey = pathKey({ env: {}, platform: "win32" }); // Returns "Path"
93
```
94

95
## Types
96

97
```typescript { .api }
98
interface Options {
99
  readonly env?: Record<string, string | undefined>;
100
  readonly platform?: NodeJS.Platform;
101
}
102
```
103

104
The `NodeJS.Platform` type includes: `"aix"`, `"darwin"`, `"freebsd"`, `"linux"`, `"openbsd"`, `"sunos"`, `"win32"`.
105

106
## Error Handling
107

108
The `pathKey` function does not throw exceptions under normal usage. It will:
109

110
- Return `"PATH"` for all non-Windows platforms regardless of environment contents
111
- Return `"Path"` as a fallback when no PATH variants are found in a Windows environment
112
- Handle undefined or malformed environment objects gracefully