@socketsecurity/lib 5.15.0 → 5.16.0

package/dist/packages/operations.d.ts

@@ -1,31 +1,65 @@
 import type { ExtractOptions, NormalizeOptions, PackageJson, PacoteOptions, ReadPackageJsonOptions } from '../packages';
 /**
  * Extract a package to a destination directory.
+ *
+ * @example
+ * ```typescript
+ * await extractPackage('lodash@4.17.21', { dest: '/tmp/lodash' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function extractPackage(pkgNameOrId: string, options?: ExtractOptions, callback?: (destPath: string) => Promise<unknown>): Promise<void>;
 /**
  * Find package extensions for a given package.
+ *
+ * @example
+ * ```typescript
+ * const extensions = findPackageExtensions('my-pkg', '1.0.0')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function findPackageExtensions(pkgName: string, pkgVer: string): unknown;
 /**
  * Get the release tag for a version.
+ *
+ * @example
+ * ```typescript
+ * getReleaseTag('lodash@latest')    // 'latest'
+ * getReleaseTag('@scope/pkg@beta')  // 'beta'
+ * getReleaseTag('lodash')           // ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getReleaseTag(spec: string): string;
 /**
  * Pack a package tarball using pacote.
+ *
+ * @example
+ * ```typescript
+ * const tarball = await packPackage('lodash@4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function packPackage(spec: string, options?: PacoteOptions): Promise<unknown>;
 /**
  * Read and parse a package.json file asynchronously.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = await readPackageJson('/tmp/my-project')
+ * console.log(pkgJson?.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function readPackageJson(filepath: string, options?: ReadPackageJsonOptions): Promise<PackageJson | undefined>;
 /**
  * Read and parse package.json from a file path synchronously.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = readPackageJsonSync('/tmp/my-project')
+ * console.log(pkgJson?.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function readPackageJsonSync(filepath: string, options?: NormalizeOptions & {
@@ -34,11 +68,22 @@ export declare function readPackageJsonSync(filepath: string, options?: Normaliz
 }): PackageJson | undefined;
 /**
  * Resolve GitHub tarball URL for a package specifier.
+ *
+ * @example
+ * ```typescript
+ * const url = await resolveGitHubTgzUrl('my-pkg@1.0.0', '/tmp/my-project')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolveGitHubTgzUrl(pkgNameOrId: string, where?: unknown): Promise<string>;
 /**
  * Resolve full package name from a PURL object with custom delimiter.
+ *
+ * @example
+ * ```typescript
+ * resolvePackageName({ name: 'core', namespace: '@babel' })  // '@babel/core'
+ * resolvePackageName({ name: 'lodash' })                     // 'lodash'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolvePackageName(purlObj: {
@@ -47,6 +92,12 @@ export declare function resolvePackageName(purlObj: {
 }, delimiter?: string): string;
 /**
  * Convert npm package name to Socket registry format with delimiter.
+ *
+ * @example
+ * ```typescript
+ * resolveRegistryPackageName('@babel/core') // 'babel__core'
+ * resolveRegistryPackageName('lodash')      // 'lodash'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolveRegistryPackageName(pkgName: string): string;

package/dist/packages/provenance.d.ts

@@ -1,10 +1,21 @@
 import type { ProvenanceOptions } from '../packages';
 /**
  * Convert raw attestation data to user-friendly provenance details.
+ *
+ * @example
+ * ```typescript
+ * const details = getProvenanceDetails(attestationData)
+ * // { level: 'trusted', repository: '...', commitSha: '...' }
+ * ```
  */
 export declare function getProvenanceDetails(attestationData: unknown): unknown;
 /**
  * Fetch package provenance information from npm registry.
+ *
+ * @example
+ * ```typescript
+ * const provenance = await fetchPackageProvenance('lodash', '4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function fetchPackageProvenance(pkgName: string, pkgVersion: string, options?: ProvenanceOptions): Promise<unknown>;

package/dist/packages/specs.d.ts

@@ -1,5 +1,11 @@
 /**
  * Extract user and project from GitHub repository URL.
+ *
+ * @example
+ * ```typescript
+ * getRepoUrlDetails('https://github.com/lodash/lodash.git')
+ * // { user: 'lodash', project: 'lodash' }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getRepoUrlDetails(repoUrl?: string): {
@@ -8,21 +14,45 @@ export declare function getRepoUrlDetails(repoUrl?: string): {
 };
 /**
  * Generate GitHub API URL for a tag reference.
+ *
+ * @example
+ * ```typescript
+ * gitHubTagRefUrl('lodash', 'lodash', 'v4.17.21')
+ * // 'https://api.github.com/repos/lodash/lodash/git/ref/tags/v4.17.21'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function gitHubTagRefUrl(user: string, project: string, tag: string): string;
 /**
  * Generate GitHub tarball download URL for a commit SHA.
+ *
+ * @example
+ * ```typescript
+ * gitHubTgzUrl('lodash', 'lodash', 'abc123')
+ * // 'https://github.com/lodash/lodash/archive/abc123.tar.gz'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function gitHubTgzUrl(user: string, project: string, sha: string): string;
 /**
  * Check if a package specifier is a GitHub tarball URL.
+ *
+ * @example
+ * ```typescript
+ * isGitHubTgzSpec('https://github.com/user/repo/archive/abc123.tar.gz') // true
+ * isGitHubTgzSpec('lodash@4.17.21')                                     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isGitHubTgzSpec(spec: unknown, where?: string): boolean;
 /**
  * Check if a package specifier is a GitHub URL with committish.
+ *
+ * @example
+ * ```typescript
+ * isGitHubUrlSpec('github:user/repo#v1.0.0') // true
+ * isGitHubUrlSpec('lodash@4.17.21')           // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isGitHubUrlSpec(spec: unknown, where?: string): boolean;

package/dist/packages/validation.d.ts

@@ -1,15 +1,33 @@
 /**
  * Check if package name is a blessed Socket.dev package.
+ *
+ * @example
+ * ```typescript
+ * isBlessedPackageName('@socketregistry/is-number') // true
+ * isBlessedPackageName('lodash')                    // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isBlessedPackageName(name: unknown): boolean;
 /**
  * Check if a type string represents a registry fetcher type.
+ *
+ * @example
+ * ```typescript
+ * isRegistryFetcherType('range')   // true
+ * isRegistryFetcherType('git')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isRegistryFetcherType(type: string): boolean;
 /**
  * Check if a package name is valid according to npm naming rules.
+ *
+ * @example
+ * ```typescript
+ * isValidPackageName('my-package')   // true
+ * isValidPackageName('.invalid')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isValidPackageName(name: string): boolean;

package/dist/paths/normalize.d.ts

@@ -141,6 +141,48 @@ export declare function isPath(pathLike: string | Buffer | URL): boolean;
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isRelative(pathLike: string | Buffer | URL): boolean;
+/**
+ * Convert Unix-style POSIX paths (MSYS/Git Bash format) back to native Windows paths.
+ *
+ * This is the inverse of {@link toUnixPath}. MSYS-style paths use `/c/` notation
+ * for drive letters, which PowerShell and cmd.exe cannot resolve. This function
+ * converts them back to native Windows format.
+ *
+ * Conversion rules:
+ * - On Windows: Converts Unix drive notation to Windows drive letters
+ *   - `/c/path/to/file` becomes `C:/path/to/file`
+ *   - `/d/projects/app` becomes `D:/projects/app`
+ *   - Drive letters are always uppercase in the output
+ * - On Unix: Returns the path unchanged (passes through normalization)
+ *
+ * This is particularly important for:
+ * - GitHub Actions runners where `command -v` returns MSYS paths
+ * - Tools like sfw that need to resolve real binary paths on Windows
+ * - Scripts that receive paths from Git Bash but need to pass them to native Windows tools
+ *
+ * @param {string | Buffer | URL} pathLike - The MSYS/Unix-style path to convert
+ * @returns {string} Native Windows path (e.g., `C:/path/to/file`) or normalized Unix path
+ *
+ * @example
+ * ```typescript
+ * // MSYS drive letter paths
+ * fromUnixPath('/c/projects/app/file.txt')    // 'C:/projects/app/file.txt'
+ * fromUnixPath('/d/projects/foo/bar')         // 'D:/projects/foo/bar'
+ *
+ * // Non-drive Unix paths (unchanged)
+ * fromUnixPath('/tmp/build/output')           // '/tmp/build/output'
+ * fromUnixPath('/usr/local/bin')              // '/usr/local/bin'
+ *
+ * // Already Windows paths (unchanged)
+ * fromUnixPath('C:/Windows/System32')         // 'C:/Windows/System32'
+ *
+ * // Edge cases
+ * fromUnixPath('/c')                          // 'C:/'
+ * fromUnixPath('')                            // '.'
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function fromUnixPath(pathLike: string | Buffer | URL): string;
 /**
  * Normalize a path by converting backslashes to forward slashes and collapsing segments.
  *
@@ -348,21 +390,23 @@ export declare function trimLeadingDotSlash(pathLike: string | Buffer | URL): st
 /*@__NO_SIDE_EFFECTS__*/
 export declare function relativeResolve(from: string, to: string): string;
 /**
- * Convert Windows paths to Unix-style POSIX paths for Git Bash tools.
+ * Convert Windows paths to MSYS/Unix-style POSIX paths for Git Bash tools.
  *
- * Git for Windows tools (like tar, git, etc.) expect POSIX-style paths with
- * forward slashes and Unix drive letter notation (/c/ instead of C:\).
+ * Git for Windows and MSYS2 tools (like tar, git, etc.) expect POSIX-style
+ * paths with forward slashes and Unix drive letter notation (/c/ instead of C:\).
  * This function handles the conversion for cross-platform compatibility.
  *
+ * This is the inverse of {@link fromUnixPath}.
+ *
  * Conversion rules:
  * - On Windows: Normalizes separators and converts drive letters
  *   - `C:\path\to\file` becomes `/c/path/to/file`
- *   - `D:/Users/name` becomes `/d/Users/name`
+ *   - `D:/projects/app` becomes `/d/projects/app`
  *   - Drive letters are always lowercase in the output
  * - On Unix: Returns the path unchanged (passes through normalization)
  *
  * This is particularly important for:
- * - Git Bash tools that interpret `D:\` as a remote hostname
+ * - MSYS2/Git Bash tools that interpret `D:\` as a remote hostname
  * - Cross-platform build scripts using tar, git archive, etc.
  * - CI/CD environments where Git for Windows is used
  *

package/dist/paths/normalize.js

@@ -19,6 +19,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var normalize_exports = {};
 __export(normalize_exports, {
+  fromUnixPath: () => fromUnixPath,
   isAbsolute: () => isAbsolute,
   isNodeModules: () => isNodeModules,
   isPath: () => isPath,
@@ -130,6 +131,17 @@ function isRelative(pathLike) {
   return !/* @__PURE__ */ isAbsolute(filepath);
 }
 // @__NO_SIDE_EFFECTS__
+function fromUnixPath(pathLike) {
+  const normalized = /* @__PURE__ */ normalizePath(pathLike);
+  if (import_platform.WIN32) {
+    return normalized.replace(
+      /^\/([a-zA-Z])(\/|$)/,
+      (_, letter, sep) => `${letter.toUpperCase()}:${sep || "/"}`
+    );
+  }
+  return normalized;
+}
+// @__NO_SIDE_EFFECTS__
 function normalizePath(pathLike) {
   const filepath = /* @__PURE__ */ pathLikeToString(pathLike);
   const { length } = filepath;
@@ -448,6 +460,7 @@ function toUnixPath(pathLike) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  fromUnixPath,
   isAbsolute,
   isNodeModules,
   isPath,

package/dist/paths/rewire.js

@@ -28,9 +28,18 @@ __export(rewire_exports, {
   setPath: () => setPath
 });
 module.exports = __toCommonJS(rewire_exports);
-const testOverrides = /* @__PURE__ */ new Map();
-const valueCache = /* @__PURE__ */ new Map();
-const cacheInvalidationCallbacks = [];
+const stateSymbol = Symbol.for("@socketsecurity/lib/paths/rewire/state");
+if (!globalThis[stateSymbol]) {
+  globalThis[stateSymbol] = {
+    testOverrides: /* @__PURE__ */ new Map(),
+    valueCache: /* @__PURE__ */ new Map(),
+    cacheInvalidationCallbacks: []
+  };
+}
+const sharedState = globalThis[stateSymbol];
+const testOverrides = sharedState.testOverrides;
+const valueCache = sharedState.valueCache;
+const cacheInvalidationCallbacks = sharedState.cacheInvalidationCallbacks;
 function clearPath(key) {
   testOverrides.delete(key);
   invalidateCaches();

package/dist/regexps.d.ts

@@ -8,6 +8,13 @@
 // Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
 /**
  * Escape special characters in a string for use in a regular expression.
+ *
+ * @example
+ * ```typescript
+ * escapeRegExp('foo.bar')     // 'foo\\.bar'
+ * escapeRegExp('a+b*c?')     // 'a\\+b\\*c\\?'
+ * new RegExp(escapeRegExp('[test]'))  // /\[test\]/
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function escapeRegExp(str: string): string;

package/dist/releases/github.d.ts

@@ -75,6 +75,13 @@ export declare const SOCKET_BTM_REPO: {
  *
  * @param pattern - Pattern to match (string glob, prefix/suffix object, or RegExp)
  * @returns Function that tests if a string matches the pattern
+ *
+ * @example
+ * ```typescript
+ * const isMatch = createAssetMatcher('tool-*-linux-x64')
+ * isMatch('tool-v1.0-linux-x64')  // true
+ * isMatch('tool-v1.0-darwin-arm64')  // false
+ * ```
  */
 export declare function createAssetMatcher(pattern: string | {
     prefix: string;
@@ -85,6 +92,16 @@ export declare function createAssetMatcher(pattern: string | {
  *
  * @param config - Download configuration
  * @returns Path to the downloaded binary
+ *
+ * @example
+ * ```typescript
+ * const binaryPath = await downloadGitHubRelease({
+ *   owner: 'SocketDev', repo: 'socket-btm',
+ *   toolName: 'lief', toolPrefix: 'lief-',
+ *   assetName: 'lief-linux-x64', binaryName: 'lief',
+ *   platformArch: 'linux-x64',
+ * })
+ * ```
  */
 export declare function downloadGitHubRelease(config: DownloadGitHubReleaseConfig): Promise<string>;
 /**
@@ -96,6 +113,14 @@ export declare function downloadGitHubRelease(config: DownloadGitHubReleaseConfi
  * @param outputPath - Path to write the downloaded file
  * @param repoConfig - Repository configuration (owner/repo)
  * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * await downloadReleaseAsset(
+ *   'v1.0.0', 'tool-linux-x64', '/tmp/tool',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function downloadReleaseAsset(tag: string, assetPattern: string | AssetPattern, outputPath: string, repoConfig: RepoConfig, options?: {
     quiet?: boolean;
@@ -105,6 +130,12 @@ export declare function downloadReleaseAsset(tag: string, assetPattern: string |
  * Checks GH_TOKEN or GITHUB_TOKEN environment variables.
  *
  * @returns Headers object with Authorization header if token exists.
+ *
+ * @example
+ * ```typescript
+ * const headers = getAuthHeaders()
+ * // { Accept: 'application/vnd.github+json', Authorization: 'Bearer ...' }
+ * ```
  */
 export declare function getAuthHeaders(): Record<string, string>;
 /**
@@ -116,6 +147,14 @@ export declare function getAuthHeaders(): Record<string, string>;
  * @param options - Additional options
  * @param options.assetPattern - Optional pattern to filter releases by matching asset
  * @returns Latest release tag or null if not found
+ *
+ * @example
+ * ```typescript
+ * const tag = await getLatestRelease('lief-', {
+ *   owner: 'SocketDev', repo: 'socket-btm',
+ * })
+ * console.log(tag) // 'lief-2025-01-15-abc1234'
+ * ```
  */
 export declare function getLatestRelease(toolPrefix: string, repoConfig: RepoConfig, options?: {
     assetPattern?: AssetPattern;
@@ -130,6 +169,14 @@ export declare function getLatestRelease(toolPrefix: string, repoConfig: RepoCon
  * @param repoConfig - Repository configuration (owner/repo)
  * @param options - Additional options
  * @returns Browser download URL for the asset
+ *
+ * @example
+ * ```typescript
+ * const url = await getReleaseAssetUrl(
+ *   'v1.0.0', 'tool-linux-x64',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function getReleaseAssetUrl(tag: string, assetPattern: string | AssetPattern, repoConfig: RepoConfig, options?: {
     quiet?: boolean;
@@ -146,6 +193,14 @@ export declare function getReleaseAssetUrl(tag: string, assetPattern: string | A
  * @param options.quiet - Suppress log messages
  * @param options.cleanup - Remove downloaded zip file after extraction (default: true)
  * @returns Path to the extraction directory
+ *
+ * @example
+ * ```typescript
+ * const outputDir = await downloadAndExtractZip(
+ *   'v1.0.0', 'models-*.zip', '/tmp/models',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function downloadAndExtractZip(tag: string, assetPattern: string | AssetPattern, outputDir: string, repoConfig: RepoConfig, options?: {
     cleanup?: boolean;
@@ -166,6 +221,14 @@ export declare function downloadAndExtractZip(tag: string, assetPattern: string
  * @param options.strip - Strip leading path components (like tar --strip-components)
  * @param options.format - Archive format (auto-detected if not specified)
  * @returns Path to the extraction directory
+ *
+ * @example
+ * ```typescript
+ * const outputDir = await downloadAndExtractArchive(
+ *   'v1.0.0', 'data-*.tar.gz', '/tmp/data',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function downloadAndExtractArchive(tag: string, assetPattern: string | AssetPattern, outputDir: string, repoConfig: RepoConfig, options?: {
     cleanup?: boolean;

package/dist/releases/socket-btm.d.ts

@@ -65,6 +65,12 @@ export type SocketBtmReleaseConfig = SocketBtmBinaryConfig | SocketBtmAssetConfi
  * Returns undefined for non-Linux platforms.
  *
  * @returns 'musl', 'glibc', or undefined (for non-Linux)
+ *
+ * @example
+ * ```typescript
+ * const libc = detectLibc()
+ * console.log(libc) // 'glibc', 'musl', or undefined
+ * ```
  */
 export declare function detectLibc(): Libc | undefined;
 /**
@@ -73,6 +79,13 @@ export declare function detectLibc(): Libc | undefined;
  * @param tool - Tool/package name for release matching (e.g., 'lief', 'curl')
  * @param options - Download configuration
  * @returns Path to the downloaded file
+ *
+ * @example
+ * ```typescript
+ * const binPath = await downloadSocketBtmRelease('lief', {
+ *   downloadDir: '/tmp/build/downloaded',
+ * })
+ * ```
  */
 export declare function downloadSocketBtmRelease(tool: string, options: SocketBtmReleaseConfig | undefined): Promise<string>;
 /**
@@ -83,6 +96,12 @@ export declare function downloadSocketBtmRelease(tool: string, options: SocketBt
  * @param arch - Target architecture
  * @param libc - Linux libc variant (optional)
  * @returns Asset name (e.g., 'binject-darwin-arm64', 'node-linux-x64-musl')
+ *
+ * @example
+ * ```typescript
+ * getBinaryAssetName('lief', 'linux', 'x64', 'musl')
+ * // 'lief-linux-x64-musl'
+ * ```
  */
 export declare function getBinaryAssetName(binaryBaseName: string, platform: Platform, arch: Arch, libc?: Libc | undefined): string;
 /**
@@ -91,6 +110,12 @@ export declare function getBinaryAssetName(binaryBaseName: string, platform: Pla
  * @param binaryBaseName - Binary basename (e.g., 'node', 'binject')
  * @param platform - Target platform
  * @returns Binary filename (e.g., 'node', 'node.exe')
+ *
+ * @example
+ * ```typescript
+ * getBinaryName('node', 'win32')  // 'node.exe'
+ * getBinaryName('node', 'linux')  // 'node'
+ * ```
  */
 export declare function getBinaryName(binaryBaseName: string, platform: Platform): string;
 /**
@@ -101,5 +126,11 @@ export declare function getBinaryName(binaryBaseName: string, platform: Platform
  * @param arch - Target architecture
  * @param libc - Linux libc variant (optional)
  * @returns Platform-arch identifier (e.g., 'darwin-arm64', 'linux-x64-musl', 'win-x64')
+ *
+ * @example
+ * ```typescript
+ * getPlatformArch('linux', 'x64', 'musl')  // 'linux-x64-musl'
+ * getPlatformArch('darwin', 'arm64')  // 'darwin-arm64'
+ * ```
  */
 export declare function getPlatformArch(platform: Platform, arch: Arch, libc?: Libc | undefined): string;

package/dist/sea.d.ts

@@ -1,10 +1,25 @@
 /**
  * Get the current SEA binary path.
  * Only valid when running as a SEA binary.
+ *
+ * @example
+ * ```typescript
+ * const binPath = getSeaBinaryPath()
+ * if (binPath) {
+ *   console.log(`Running as SEA binary: ${binPath}`)
+ * }
+ * ```
  */
 export declare function getSeaBinaryPath(): string | undefined;
 /**
  * Detect if the current process is running as a SEA binary.
  * Uses Node.js 24+ native API with caching for performance.
+ *
+ * @example
+ * ```typescript
+ * if (isSeaBinary()) {
+ *   console.log('Running as a Single Executable Application')
+ * }
+ * ```
  */
 export declare function isSeaBinary(): boolean;

package/dist/shadow.d.ts

@@ -13,5 +13,12 @@ export interface ShadowInstallationOptions {
  * @param options.cwd - Current working directory path to check
  * @param options.win32 - Whether running on Windows
  * @returns true if shadow installation should be skipped
+ *
+ * @example
+ * ```typescript
+ * if (shouldSkipShadow(binPath, { cwd: process.cwd() })) {
+ *   console.log('Skipping shadow binary installation')
+ * }
+ * ```
  */
 export declare function shouldSkipShadow(binPath: string, options?: ShadowInstallationOptions | undefined): boolean;

package/dist/signal-exit.d.ts

@@ -1,5 +1,11 @@
 /**
  * Load signal handlers and hook into process exit events.
+ *
+ * @example
+ * ```typescript
+ * load()
+ * // Signal handlers are now active
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function load(): void;
@@ -8,16 +14,37 @@ export interface OnExitOptions {
 }
 /**
  * Register a callback to run on process exit or signal.
+ *
+ * @example
+ * ```typescript
+ * const remove = onExit((code, signal) => {
+ *   console.log(`Exiting with code ${code}, signal ${signal}`)
+ * })
+ * // Later, to unregister:
+ * remove()
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function onExit(cb: (code: number | null, signal: string | null) => void, options?: OnExitOptions | undefined): () => void;
 /**
  * Get the list of signals that are currently being monitored.
+ *
+ * @example
+ * ```typescript
+ * const sigs = signals()
+ * console.log(sigs) // ['SIGABRT', 'SIGALRM', 'SIGHUP', ...]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function signals(): string[];
 /**
  * Unload signal handlers and restore original process behavior.
+ *
+ * @example
+ * ```typescript
+ * unload()
+ * // Signal handlers are now removed
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function unload(): void;