@socketsecurity/lib 5.15.0 → 5.17.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.17.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.17.0) - 2026-04-14
+
+### Added — paths
+
+- `isUnixPath()` — detect MSYS/Git Bash drive letter notation (`/c/...`)
+
+### Changed — paths
+
+- `normalizePath()` now converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
+- `fromUnixPath()` now produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
+
+## [5.16.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.16.0) - 2026-04-14
+
+### Added — paths
+
+- `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
+
+### Fixed — dlx
+
+- Normalize dlx directory path in `isInSocketDlx` for Windows compatibility
+
 ## [5.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
 
 ### Added — http-request

package/README.md

@@ -2,7 +2,7 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
 [![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-84.10%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-81%25-brightgreen)
 
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
@@ -141,7 +141,7 @@ Helpers for arrays, objects, strings, promises, sorting, and more.
 - **Cross-platform** - Works on Windows, macOS, and Linux
 - **TypeScript-first** - Full type safety with .d.ts files
 - **Zero dependencies** (for core HTTP - uses Node.js native modules)
-- **Well-tested** - 84% coverage with comprehensive test suite
+- **Well-tested** - 6600+ tests across 145 test files
 - **Security-focused** - Safe defaults, command injection protection
 - **CommonJS output** - Compatible with Node.js tooling
 

package/dist/abort.d.ts

@@ -3,9 +3,22 @@
  */
 /**
  * Create a composite AbortSignal from multiple signals.
+ *
+ * @example
+ * ```typescript
+ * const ac1 = new AbortController()
+ * const ac2 = new AbortController()
+ * const signal = createCompositeAbortSignal(ac1.signal, ac2.signal)
+ * ```
  */
 export declare function createCompositeAbortSignal(...signals: Array<AbortSignal | null | undefined>): AbortSignal;
 /**
  * Create an AbortSignal that triggers after a timeout.
+ *
+ * @example
+ * ```typescript
+ * const signal = createTimeoutSignal(5000) // aborts after 5 seconds
+ * fetch('https://example.com', { signal })
+ * ```
  */
 export declare function createTimeoutSignal(ms: number): AbortSignal;

package/dist/agent.d.ts

@@ -4,6 +4,12 @@ import type { SpawnOptions } from './spawn';
  *
  * SECURITY: Uses array-based arguments to prevent command injection. All elements
  * in the args array are properly escaped by Node.js when passed to spawn().
+ *
+ * @example
+ * ```typescript
+ * await execNpm(['install', '--save', 'lodash'])
+ * await execNpm(['run', 'build'], { cwd: '/tmp/project' })
+ * ```
  */
 export declare function execNpm(args: string[], options?: SpawnOptions | undefined): import("./spawn").PromiseSpawnResult;
 export interface PnpmOptions extends SpawnOptions {
@@ -14,6 +20,12 @@ export interface PnpmOptions extends SpawnOptions {
  *
  * SECURITY: Uses array-based arguments to prevent command injection. All elements
  * in the args array are properly escaped by Node.js when passed to execBin().
+ *
+ * @example
+ * ```typescript
+ * await execPnpm(['install'])
+ * await execPnpm(['add', 'lodash'], { allowLockfileUpdate: true })
+ * ```
  */
 export declare function execPnpm(args: string[], options?: PnpmOptions | undefined): Promise<{
     cmd: string;
@@ -28,6 +40,12 @@ export declare function execPnpm(args: string[], options?: PnpmOptions | undefin
  *
  * SECURITY: Uses array-based arguments to prevent command injection. All elements
  * in the args array are properly escaped by Node.js when passed to execBin().
+ *
+ * @example
+ * ```typescript
+ * await execYarn(['install'])
+ * await execYarn(['add', 'lodash'], { cwd: '/tmp/project' })
+ * ```
  */
 export declare function execYarn(args: string[], options?: import('./spawn').SpawnOptions): Promise<{
     cmd: string;
@@ -39,41 +57,98 @@ export declare function execYarn(args: string[], options?: import('./spawn').Spa
 }>;
 /**
  * Check if a command argument is an npm audit flag.
+ *
+ * @example
+ * ```typescript
+ * isNpmAuditFlag('--no-audit')  // true
+ * isNpmAuditFlag('--audit')     // true
+ * isNpmAuditFlag('--save')      // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmAuditFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm fund flag.
+ *
+ * @example
+ * ```typescript
+ * isNpmFundFlag('--no-fund')  // true
+ * isNpmFundFlag('--fund')     // true
+ * isNpmFundFlag('--save')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmFundFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm loglevel flag.
+ *
+ * @example
+ * ```typescript
+ * isNpmLoglevelFlag('--loglevel')  // true
+ * isNpmLoglevelFlag('--silent')    // true
+ * isNpmLoglevelFlag('-s')          // true
+ * isNpmLoglevelFlag('--save')      // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmLoglevelFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm node-options flag.
+ *
+ * @example
+ * ```typescript
+ * isNpmNodeOptionsFlag('--node-options')                            // true
+ * isNpmNodeOptionsFlag('--node-options=--max-old-space-size=4096')  // true
+ * isNpmNodeOptionsFlag('--save')                                   // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmNodeOptionsFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm progress flag.
+ *
+ * @example
+ * ```typescript
+ * isNpmProgressFlag('--no-progress')  // true
+ * isNpmProgressFlag('--progress')     // true
+ * isNpmProgressFlag('--save')         // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmProgressFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is a pnpm ignore-scripts flag.
+ *
+ * @example
+ * ```typescript
+ * isPnpmIgnoreScriptsFlag('--ignore-scripts')     // true
+ * isPnpmIgnoreScriptsFlag('--no-ignore-scripts')  // true
+ * isPnpmIgnoreScriptsFlag('--save')               // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is a pnpm frozen-lockfile flag.
+ *
+ * @example
+ * ```typescript
+ * isPnpmFrozenLockfileFlag('--frozen-lockfile')     // true
+ * isPnpmFrozenLockfileFlag('--no-frozen-lockfile')  // true
+ * isPnpmFrozenLockfileFlag('--save')                // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isPnpmFrozenLockfileFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is a pnpm install command.
+ *
+ * @example
+ * ```typescript
+ * isPnpmInstallCommand('install')  // true
+ * isPnpmInstallCommand('i')        // true
+ * isPnpmInstallCommand('run')      // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isPnpmInstallCommand(cmdArg: string): boolean;
@@ -84,6 +159,12 @@ export declare const isPnpmLoglevelFlag: typeof isNpmLoglevelFlag;
 /**
  * Execute a package.json script using the appropriate package manager.
  * Automatically detects pnpm, yarn, or npm based on lockfiles.
+ *
+ * @example
+ * ```typescript
+ * await execScript('build')
+ * await execScript('test', ['--coverage'], { cwd: '/tmp/project' })
+ * ```
  */
 export interface ExecScriptOptions extends SpawnOptions {
     prepost?: boolean | undefined;

package/dist/ansi.d.ts

@@ -16,6 +16,13 @@ export declare const ANSI_STRIKETHROUGH = "\u001B[9m";
  * https://socket.dev/npm/package/ansi-regexp/overview/6.2.2
  * MIT License
  * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+ *
+ * @example
+ * ```typescript
+ * const regex = ansiRegex()
+ * '\u001b[31mHello\u001b[0m'.match(regex)  // ['\u001b[31m', '\u001b[0m']
+ * ansiRegex({ onlyFirst: true })           // matches only the first code
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function ansiRegex(options?: {
@@ -24,6 +31,12 @@ export declare function ansiRegex(options?: {
 /**
  * Strip ANSI escape codes from text.
  * Uses the inlined ansi-regex for matching.
+ *
+ * @example
+ * ```typescript
+ * stripAnsi('\u001b[31mError\u001b[0m')  // 'Error'
+ * stripAnsi('\u001b[1mBold\u001b[0m')    // 'Bold'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function stripAnsi(text: string): string;

package/dist/archives.d.ts

@@ -22,6 +22,13 @@ export interface ExtractOptions {
  *
  * @param filePath - Path to archive file
  * @returns Archive format or null if unknown
+ *
+ * @example
+ * ```typescript
+ * detectArchiveFormat('package.tar.gz')  // 'tar.gz'
+ * detectArchiveFormat('archive.zip')     // 'zip'
+ * detectArchiveFormat('data.csv')        // null
+ * ```
  */
 export declare function detectArchiveFormat(filePath: string): ArchiveFormat | null;
 /**
@@ -30,6 +37,12 @@ export declare function detectArchiveFormat(filePath: string): ArchiveFormat | n
  * @param archivePath - Path to tar file
  * @param outputDir - Directory to extract to
  * @param options - Extraction options
+ *
+ * @example
+ * ```typescript
+ * await extractTar('/tmp/archive.tar', '/tmp/output')
+ * await extractTar('/tmp/archive.tar', '/tmp/output', { strip: 1 })
+ * ```
  */
 export declare function extractTar(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
 /**
@@ -38,6 +51,12 @@ export declare function extractTar(archivePath: string, outputDir: string, optio
  * @param archivePath - Path to tar.gz or tgz file
  * @param outputDir - Directory to extract to
  * @param options - Extraction options
+ *
+ * @example
+ * ```typescript
+ * await extractTarGz('/tmp/archive.tar.gz', '/tmp/output')
+ * await extractTarGz('/tmp/archive.tgz', '/tmp/output', { strip: 1 })
+ * ```
  */
 export declare function extractTarGz(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
 /**
@@ -46,6 +65,12 @@ export declare function extractTarGz(archivePath: string, outputDir: string, opt
  * @param archivePath - Path to zip file
  * @param outputDir - Directory to extract to
  * @param options - Extraction options
+ *
+ * @example
+ * ```typescript
+ * await extractZip('/tmp/archive.zip', '/tmp/output')
+ * await extractZip('/tmp/archive.zip', '/tmp/output', { strip: 1 })
+ * ```
  */
 export declare function extractZip(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
 /**
@@ -56,5 +81,11 @@ export declare function extractZip(archivePath: string, outputDir: string, optio
  * @param outputDir - Directory to extract to
  * @param options - Extraction options
  * @throws Error if archive format is not supported
+ *
+ * @example
+ * ```typescript
+ * await extractArchive('/tmp/package.tar.gz', '/tmp/output')
+ * await extractArchive('/tmp/release.zip', '/tmp/output', { strip: 1 })
+ * ```
  */
 export declare function extractArchive(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;

package/dist/argv/flags.d.ts

@@ -26,77 +26,168 @@ export type FlagInput = FlagValues | string[] | readonly string[] | undefined;
  * Get the appropriate log level based on flags.
  * Returns 'silent', 'error', 'warn', 'info', 'verbose', or 'debug'.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * getLogLevel()  // 'info' (default)
+ * getLogLevel({ quiet: true })  // 'silent'
+ * getLogLevel(['--debug'])  // 'debug'
+ * ```
  */
 export declare function getLogLevel(input?: FlagInput): string;
 /**
  * Check if all flag is set.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isAll({ all: true })  // true
+ * isAll(['--all'])  // true
+ * ```
  */
 export declare function isAll(input?: FlagInput): boolean;
 /**
  * Check if changed files mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isChanged({ changed: true })  // true
+ * isChanged(['--changed'])  // true
+ * ```
  */
 export declare function isChanged(input?: FlagInput): boolean;
 /**
  * Check if coverage mode is enabled.
  * Checks both 'coverage' and 'cover' flags.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isCoverage({ coverage: true })  // true
+ * isCoverage(['--cover'])  // true
+ * ```
  */
 export declare function isCoverage(input?: FlagInput): boolean;
 /**
  * Check if debug mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isDebug({ debug: true })  // true
+ * isDebug(['--debug'])  // true
+ * ```
  */
 export declare function isDebug(input?: FlagInput): boolean;
 /**
  * Check if dry-run mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isDryRun({ 'dry-run': true })  // true
+ * isDryRun(['--dry-run'])  // true
+ * ```
  */
 export declare function isDryRun(input?: FlagInput): boolean;
 /**
  * Check if fix/autofix mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isFix({ fix: true })  // true
+ * isFix(['--fix'])  // true
+ * ```
  */
 export declare function isFix(input?: FlagInput): boolean;
 /**
  * Check if force mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isForce({ force: true })  // true
+ * isForce(['--force'])  // true
+ * ```
  */
 export declare function isForce(input?: FlagInput): boolean;
 /**
  * Check if help flag is set.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isHelp({ help: true })  // true
+ * isHelp(['-h'])  // true
+ * ```
  */
 export declare function isHelp(input?: FlagInput): boolean;
 /**
  * Check if JSON output is requested.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isJson({ json: true })  // true
+ * isJson(['--json'])  // true
+ * ```
  */
 export declare function isJson(input?: FlagInput): boolean;
 /**
  * Check if quiet/silent mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isQuiet({ quiet: true })  // true
+ * isQuiet(['--silent'])  // true
+ * ```
  */
 export declare function isQuiet(input?: FlagInput): boolean;
 /**
  * Check if staged files mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isStaged({ staged: true })  // true
+ * isStaged(['--staged'])  // true
+ * ```
  */
 export declare function isStaged(input?: FlagInput): boolean;
 /**
  * Check if update mode is enabled (for snapshots, dependencies, etc).
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isUpdate({ update: true })  // true
+ * isUpdate(['-u'])  // true
+ * ```
  */
 export declare function isUpdate(input?: FlagInput): boolean;
 /**
  * Check if verbose mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isVerbose({ verbose: true })  // true
+ * isVerbose(['--verbose'])  // true
+ * ```
  */
 export declare function isVerbose(input?: FlagInput): boolean;
 /**
  * Check if watch mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isWatch({ watch: true })  // true
+ * isWatch(['-w'])  // true
+ * ```
  */
 export declare function isWatch(input?: FlagInput): boolean;
 /**

package/dist/argv/parse.d.ts

@@ -53,11 +53,30 @@ export interface ParsedArgs<T = Record<string, unknown>> {
 /**
  * Parse command-line arguments with a Node.js parseArgs-compatible API.
  * Uses yargs-parser internally for robust argument parsing.
+ *
+ * @example
+ * ```typescript
+ * const { values, positionals } = parseArgs({
+ *   args: ['--force', '--quiet', 'file.ts'],
+ *   options: {
+ *     force: { type: 'boolean' },
+ *     quiet: { type: 'boolean', short: 'q' },
+ *   },
+ * })
+ * ```
  */
 export declare function parseArgs<T = Record<string, unknown>>(config?: ParseArgsConfig): ParsedArgs<T>;
 /**
  * Parse command-line arguments with Socket defaults.
  * Provides sensible defaults for Socket CLI applications.
+ *
+ * @example
+ * ```typescript
+ * const { values, positionals } = parseArgsWithDefaults({
+ *   args: ['--force', 'file.ts'],
+ *   options: { force: { type: 'boolean' } },
+ * })
+ * ```
  */
 export declare function parseArgsWithDefaults<T = Record<string, unknown>>(config?: ParseArgsConfig): ParsedArgs<T>;
 /**
@@ -67,10 +86,22 @@ export declare const commonParseArgsConfig: ParseArgsConfig;
 /**
  * Extract positional arguments from process.argv.
  * Useful for commands that accept file paths or other positional parameters.
+ *
+ * @example
+ * ```typescript
+ * // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
+ * getPositionalArgs()  // ["src", "lib"]
+ * ```
  */
 export declare function getPositionalArgs(startIndex?: number): string[];
 /**
  * Check if a specific flag is present in argv.
+ *
+ * @example
+ * ```typescript
+ * hasFlag('verbose')  // true if --verbose is in process.argv
+ * hasFlag('force', ['--force', '--quiet'])  // true
+ * ```
  */
 export declare function hasFlag(flag: string, argv?: string[]): boolean;
 export {};

package/dist/bin.d.ts

@@ -17,6 +17,12 @@ export interface WhichOptions {
 }
 /**
  * Execute a binary with the given arguments.
+ *
+ * @example
+ * ```typescript
+ * await execBin('pnpm', ['install'])
+ * await execBin('/usr/local/bin/node', ['script.js'], { cwd: '/tmp' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function execBin(binPath: string, args?: string[], options?: import('./spawn').SpawnOptions): Promise<{
@@ -29,28 +35,64 @@ export declare function execBin(binPath: string, args?: string[], options?: impo
 }>;
 /**
  * Find the real executable for a binary, bypassing shadow bins.
+ *
+ * @example
+ * ```typescript
+ * const npmPath = findRealBin('npm', ['/usr/local/bin/npm'])
+ * const gitPath = findRealBin('git')
+ * ```
  */
 export declare function findRealBin(binName: string, commonPaths?: string[]): string | undefined;
 /**
  * Find the real npm executable, bypassing any aliases and shadow bins.
+ *
+ * @example
+ * ```typescript
+ * const npmPath = findRealNpm()
+ * // e.g. '/usr/local/bin/npm'
+ * ```
  */
 export declare function findRealNpm(): string;
 /**
  * Find the real pnpm executable, bypassing any aliases and shadow bins.
+ *
+ * @example
+ * ```typescript
+ * const pnpmPath = findRealPnpm()
+ * // e.g. '/usr/local/bin/pnpm'
+ * ```
  */
 export declare function findRealPnpm(): string;
 /**
  * Find the real yarn executable, bypassing any aliases and shadow bins.
+ *
+ * @example
+ * ```typescript
+ * const yarnPath = findRealYarn()
+ * // e.g. '/usr/local/bin/yarn'
+ * ```
  */
 export declare function findRealYarn(): string;
 /**
  * Check if a directory path contains any shadow bin patterns.
+ *
+ * @example
+ * ```typescript
+ * isShadowBinPath('/tmp/project/node_modules/.bin')  // true
+ * isShadowBinPath('/usr/local/bin')                   // false
+ * ```
  */
 export declare function isShadowBinPath(dirPath: string | undefined): boolean;
 /*@__NO_SIDE_EFFECTS__*/
 /**
  * Resolve a binary path to the real underlying script file.
  * Handles Windows .cmd wrappers and Unix shell scripts, resolving them to the actual .js files they execute.
+ *
+ * @example
+ * ```typescript
+ * const realPath = resolveRealBinSync('/usr/local/bin/npm')
+ * // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
+ * ```
  */
 export declare function resolveRealBinSync(binPath: string): string;
 /**
@@ -86,12 +128,24 @@ export declare function which(binName: string, options?: WhichOptions): Promise<
  * Find a binary in the system PATH and resolve to the real underlying script asynchronously.
  * Resolves wrapper scripts (.cmd, .ps1, shell scripts) to the actual .js files they execute.
  * @throws {Error} If the binary is not found and nothrow is false.
+ *
+ * @example
+ * ```typescript
+ * const npmPath = await whichReal('npm')
+ * // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
+ * ```
  */
 export declare function whichReal(binName: string, options?: WhichOptions): Promise<string | string[] | undefined>;
 /**
  * Find a binary in the system PATH and resolve to the real underlying script synchronously.
  * Resolves wrapper scripts (.cmd, .ps1, shell scripts) to the actual .js files they execute.
  * @throws {Error} If the binary is not found and nothrow is false.
+ *
+ * @example
+ * ```typescript
+ * const npmPath = whichRealSync('npm')
+ * // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
+ * ```
  */
 export declare function whichRealSync(binName: string, options?: WhichOptions): string | string[] | undefined;
 /**