or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-path-key

Get the PATH environment variable key cross-platform

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/path-key@4.0.x

To install, run

npx @tessl/cli install tessl/npm-path-key@4.0.0

index.mddocs/

Path Key

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

Package Information

  • Package Name: path-key
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: npm install path-key

Core Imports

import pathKey from "path-key";

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

Basic Usage

import pathKey from "path-key";

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

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

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

Capabilities

Path Key Detection

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

/**
 * Get the PATH environment variable key cross-platform
 * @param options - Configuration options for environment and platform
 * @returns The correct PATH environment variable key
 */
function pathKey(options?: Options): string;

interface Options {
  /**
   * Use a custom environment variables object.
   * Default: process.env
   */
  readonly env?: Record<string, string | undefined>;
  
  /**
   * Get the PATH key for a specific platform.
   * Default: process.platform
   */
  readonly platform?: NodeJS.Platform;
}

Platform Behavior:

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

Usage Examples:

import pathKey from "path-key";

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

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

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

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

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

Types

interface Options {
  readonly env?: Record<string, string | undefined>;
  readonly platform?: NodeJS.Platform;
}

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

Error Handling

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

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