@socketsecurity/lib 5.18.2 → 5.19.0

package/dist/env/socket.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Socket Security environment variable getters.
+ */
 /**
  * SOCKET_ACCEPT_RISKS environment variable getter.
  * Whether to accept all Socket Security risks.
@@ -13,7 +16,6 @@
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketAcceptRisks(): boolean;
 /**
  * SOCKET_API_BASE_URL environment variable getter.
@@ -29,7 +31,6 @@ export declare function getSocketAcceptRisks(): boolean;
  * // e.g. 'https://api.socket.dev' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiBaseUrl(): string | undefined;
 /**
  * SOCKET_API_PROXY environment variable getter.
@@ -45,7 +46,6 @@ export declare function getSocketApiBaseUrl(): string | undefined;
  * // e.g. 'http://proxy.example.com:8080' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiProxy(): string | undefined;
 /**
  * SOCKET_API_TIMEOUT environment variable getter.
@@ -61,7 +61,6 @@ export declare function getSocketApiProxy(): string | undefined;
  * // e.g. 30000 or 0 if not set
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiTimeout(): number;
 /**
  * SOCKET_API_TOKEN environment variable getter.
@@ -77,7 +76,6 @@ export declare function getSocketApiTimeout(): number;
  * // e.g. a Socket API token string or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiToken(): string | undefined;
 /**
  * SOCKET_CACACHE_DIR environment variable getter.
@@ -87,14 +85,13 @@ export declare function getSocketApiToken(): string | undefined;
  *
  * @example
  * ```typescript
- * import { getSocketCacacheDir } from '@socketsecurity/lib/env/socket'
+ * import { getSocketCacacheDirEnv } from '@socketsecurity/lib/env/socket'
  *
- * const dir = getSocketCacacheDir()
+ * const dir = getSocketCacacheDirEnv()
  * // e.g. '/tmp/.socket-cache' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function getSocketCacacheDir(): string | undefined;
+export declare function getSocketCacacheDirEnv(): string | undefined;
 /**
  * SOCKET_CONFIG environment variable getter.
  * Socket Security configuration file path.
@@ -109,7 +106,6 @@ export declare function getSocketCacacheDir(): string | undefined;
  * // e.g. '/tmp/project/socket.yml' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketConfig(): string | undefined;
 /**
  * SOCKET_DEBUG environment variable getter.
@@ -125,7 +121,6 @@ export declare function getSocketConfig(): string | undefined;
  * // e.g. '*' or 'api' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketDebug(): string | undefined;
 /**
  * SOCKET_DLX_DIR environment variable getter.
@@ -141,7 +136,6 @@ export declare function getSocketDebug(): string | undefined;
  * // e.g. '/tmp/.socket-dlx' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketDlxDirEnv(): string | undefined;
 /**
  * SOCKET_HOME environment variable getter.
@@ -157,7 +151,6 @@ export declare function getSocketDlxDirEnv(): string | undefined;
  * // e.g. '/tmp/.socket' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketHome(): string | undefined;
 /**
  * SOCKET_NO_API_TOKEN environment variable getter.
@@ -174,7 +167,6 @@ export declare function getSocketHome(): string | undefined;
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketNoApiToken(): boolean;
 /**
  * SOCKET_NPM_REGISTRY environment variable getter.
@@ -190,7 +182,6 @@ export declare function getSocketNoApiToken(): boolean;
  * // e.g. 'https://npm.socket.dev/' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketNpmRegistry(): string | undefined;
 /**
  * SOCKET_ORG_SLUG environment variable getter.
@@ -206,7 +197,6 @@ export declare function getSocketNpmRegistry(): string | undefined;
  * // e.g. 'my-org' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketOrgSlug(): string | undefined;
 /**
  * SOCKET_REGISTRY_URL environment variable getter.
@@ -222,7 +212,6 @@ export declare function getSocketOrgSlug(): string | undefined;
  * // e.g. 'https://registry.socket.dev/' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketRegistryUrl(): string | undefined;
 /**
  * SOCKET_VIEW_ALL_RISKS environment variable getter.
@@ -239,5 +228,4 @@ export declare function getSocketRegistryUrl(): string | undefined;
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketViewAllRisks(): boolean;

package/dist/env/socket.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -24,7 +25,7 @@ __export(socket_exports, {
   getSocketApiProxy: () => getSocketApiProxy,
   getSocketApiTimeout: () => getSocketApiTimeout,
   getSocketApiToken: () => getSocketApiToken,
-  getSocketCacacheDir: () => getSocketCacacheDir,
+  getSocketCacacheDirEnv: () => getSocketCacacheDirEnv,
   getSocketConfig: () => getSocketConfig,
   getSocketDebug: () => getSocketDebug,
   getSocketDlxDirEnv: () => getSocketDlxDirEnv,
@@ -59,7 +60,7 @@ function getSocketApiToken() {
   return (0, import_rewire.getEnvValue)("SOCKET_API_TOKEN");
 }
 // @__NO_SIDE_EFFECTS__
-function getSocketCacacheDir() {
+function getSocketCacacheDirEnv() {
   return (0, import_rewire.getEnvValue)("SOCKET_CACACHE_DIR");
 }
 // @__NO_SIDE_EFFECTS__
@@ -105,7 +106,7 @@ function getSocketViewAllRisks() {
   getSocketApiProxy,
   getSocketApiTimeout,
   getSocketApiToken,
-  getSocketCacacheDir,
+  getSocketCacacheDirEnv,
   getSocketConfig,
   getSocketDebug,
   getSocketDlxDirEnv,

package/dist/env/temp-dir.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Temporary directory environment variable getters.
+ * Different platforms use different environment variables for temp directories.
+ */
 /**
  * TEMP environment variable.
  * Windows temporary directory path.
@@ -12,7 +16,6 @@
  * // e.g. 'C:\\Windows\\Temp' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getTemp(): string | undefined;
 /**
  * TMP environment variable.
@@ -28,7 +31,6 @@ export declare function getTemp(): string | undefined;
  * // e.g. '/tmp' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getTmp(): string | undefined;
 /**
  * TMPDIR environment variable.
@@ -44,5 +46,4 @@ export declare function getTmp(): string | undefined;
  * // e.g. '/tmp' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getTmpdir(): string | undefined;

package/dist/env/temp-dir.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/env/term.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview TERM environment variable getter.
+ * Exports `getTerm()`, returning the `TERM` terminal type identifier (for
+ * example `xterm-256color`) or `undefined` when unset.
+ */
 /**
  * Returns the value of the TERM environment variable.
  *
@@ -11,5 +16,4 @@
  * // e.g. 'xterm-256color' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getTerm(): string | undefined;

package/dist/env/term.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/env/test.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Test environment variable getters and detection.
+ * Provides access to test framework environment variables and utilities.
+ */
 /**
  * JEST_WORKER_ID environment variable.
  * Set when running tests with Jest.
@@ -12,7 +16,6 @@
  * // e.g. '1' when running in Jest, or ''
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getJestWorkerId(): string;
 /**
  * VITEST environment variable.
@@ -29,7 +32,6 @@ export declare function getJestWorkerId(): string;
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getVitest(): boolean;
 /**
  * Check if code is running in a test environment.
@@ -46,5 +48,4 @@ export declare function getVitest(): boolean;
  * }
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isTest(): boolean;

package/dist/env/test.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/env/windows.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Windows environment variable getters.
+ * Provides access to Windows-specific user directory paths.
+ */
 /**
  * APPDATA environment variable.
  * Points to the Application Data directory on Windows.
@@ -12,7 +16,6 @@
  * // e.g. 'C:\\Users\\Public\\AppData\\Roaming' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getAppdata(): string | undefined;
 /**
  * COMSPEC environment variable.
@@ -28,7 +31,6 @@ export declare function getAppdata(): string | undefined;
  * // e.g. 'C:\\Windows\\system32\\cmd.exe' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getComspec(): string | undefined;
 /**
  * LOCALAPPDATA environment variable.
@@ -44,7 +46,6 @@ export declare function getComspec(): string | undefined;
  * // e.g. 'C:\\Users\\Public\\AppData\\Local' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getLocalappdata(): string | undefined;
 /**
  * USERPROFILE environment variable.
@@ -60,5 +61,4 @@ export declare function getLocalappdata(): string | undefined;
  * // e.g. 'C:\\Users\\Public' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getUserprofile(): string | undefined;

package/dist/env/windows.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/env/xdg.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview XDG Base Directory Specification environment variable getters.
+ * Provides access to XDG user directories on Unix systems.
+ */
 /**
  * XDG_CACHE_HOME environment variable.
  * XDG Base Directory specification cache directory.
@@ -12,7 +16,6 @@
  * // e.g. '/tmp/.cache' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getXdgCacheHome(): string | undefined;
 /**
  * XDG_CONFIG_HOME environment variable.
@@ -28,7 +31,6 @@ export declare function getXdgCacheHome(): string | undefined;
  * // e.g. '/tmp/.config' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getXdgConfigHome(): string | undefined;
 /**
  * XDG_DATA_HOME environment variable.
@@ -44,5 +46,4 @@ export declare function getXdgConfigHome(): string | undefined;
  * // e.g. '/tmp/.local/share' or undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function getXdgDataHome(): string | undefined;

package/dist/env/xdg.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/env.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Environment variable parsing and conversion utilities.
+ * Provides type-safe conversion functions for boolean, number, and string values.
+ */
 /**
  * Create a case-insensitive environment variable Proxy for Windows compatibility.
  * On Windows, environment variables are case-insensitive (PATH vs Path vs path).
@@ -33,61 +37,117 @@
  * })
  */
 export declare function createEnvProxy(base: NodeJS.ProcessEnv, overrides?: Record<string, string | undefined>): NodeJS.ProcessEnv;
+/**
+ * Options for `envAsBoolean`.
+ */
+export interface EnvAsBooleanOptions {
+    /** Default when value is null/undefined. @default false */
+    defaultValue?: boolean | undefined;
+    /**
+     * Whether to trim whitespace from string values before matching. When
+     * `false`, `'  true  '` is NOT recognised as truthy — only exact matches.
+     * @default true
+     */
+    trim?: boolean | undefined;
+}
 /**
  * Convert an environment variable value to a boolean.
  *
+ * Back-compat overload: passing a bare boolean as the second argument is
+ * equivalent to `{ defaultValue: B }`.
+ *
  * @param value - The value to convert
- * @param defaultValue - Default when value is null/undefined (default: `false`)
- * @returns `true` if value is '1' or 'true' (case-insensitive), `false` otherwise
+ * @param defaultValueOrOptions - Default (boolean) or options object
+ * @returns `true` if value is '1', 'true', or 'yes' (case-insensitive), `false` otherwise
  *
  * @example
  * ```typescript
  * import { envAsBoolean } from '@socketsecurity/lib/env'
  *
- * envAsBoolean('true')      // true
- * envAsBoolean('1')         // true
- * envAsBoolean('false')     // false
- * envAsBoolean(undefined)   // false
+ * envAsBoolean('true')                     // true
+ * envAsBoolean('1')                        // true
+ * envAsBoolean('yes')                      // true
+ * envAsBoolean('  true  ')                 // true (trimmed)
+ * envAsBoolean('  true  ', { trim: false }) // false (strict)
+ * envAsBoolean(undefined)                  // false
+ * envAsBoolean(undefined, true)            // true (legacy positional default)
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function envAsBoolean(value: unknown, defaultValue?: boolean): boolean;
+export declare function envAsBoolean(value: unknown, defaultValueOrOptions?: boolean | EnvAsBooleanOptions | undefined): boolean;
+/**
+ * Options for `envAsNumber`.
+ */
+export interface EnvAsNumberOptions {
+    /**
+     * Whether to return `±Infinity` when input parses to infinity. When
+     * `false` (default), infinities and NaN are coerced to `defaultValue`.
+     * @default false
+     */
+    allowInfinity?: boolean | undefined;
+    /** Default when value is not a finite number. @default 0 */
+    defaultValue?: number | undefined;
+    /**
+     * Parse mode. `'int'` (default) uses `parseInt(_, 10)` — integer only.
+     * `'float'` uses `Number()` — decimals preserved.
+     * @default 'int'
+     */
+    mode?: 'int' | 'float' | undefined;
+}
 /**
  * Convert an environment variable value to a number.
  *
+ * Back-compat overload: passing a bare number as the second argument is
+ * equivalent to `{ defaultValue: N }`.
+ *
  * @param value - The value to convert
- * @param defaultValue - Default when value is not a finite number (default: `0`)
- * @returns The parsed integer, or the default value if parsing fails
+ * @param defaultValueOrOptions - Default (number) or options object
+ * @returns The parsed number, or the default value if parsing fails
  *
  * @example
  * ```typescript
  * import { envAsNumber } from '@socketsecurity/lib/env'
  *
- * envAsNumber('3000')     // 3000
- * envAsNumber('abc')      // 0
- * envAsNumber(undefined)  // 0
+ * envAsNumber('3000')              // 3000 (int mode)
+ * envAsNumber('3.14', { mode: 'float' }) // 3.14
+ * envAsNumber('abc')               // 0
+ * envAsNumber(undefined, 42)       // 42 (legacy positional default)
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function envAsNumber(value: unknown, defaultValue?: number): number;
+export declare function envAsNumber(value: unknown, defaultValueOrOptions?: number | EnvAsNumberOptions | undefined): number;
 /**
- * Convert an environment variable value to a trimmed string.
+ * Options for `envAsString`.
+ */
+export interface EnvAsStringOptions {
+    /** Default when value is null/undefined. @default '' */
+    defaultValue?: string | undefined;
+    /**
+     * Whether to trim whitespace from string values. `true` (default) trims.
+     * Set `false` to preserve whitespace (helpers.envAsString semantics).
+     * @default true
+     */
+    trim?: boolean | undefined;
+}
+/**
+ * Convert an environment variable value to a string.
+ *
+ * Back-compat overload: passing a bare string as the second argument is
+ * equivalent to `{ defaultValue: S }`.
  *
  * @param value - The value to convert
- * @param defaultValue - Default when value is null/undefined (default: `''`)
- * @returns The trimmed string value, or the default value
+ * @param defaultValueOrOptions - Default (string) or options object
+ * @returns The string value, or the default value
  *
  * @example
  * ```typescript
  * import { envAsString } from '@socketsecurity/lib/env'
  *
- * envAsString('  hello  ')  // 'hello'
- * envAsString(undefined)    // ''
- * envAsString(null, 'n/a')  // 'n/a'
+ * envAsString('  hello  ')                    // 'hello' (trimmed)
+ * envAsString('  hello  ', { trim: false })   // '  hello  '
+ * envAsString(undefined)                      // ''
+ * envAsString(null, 'n/a')                    // 'n/a' (legacy positional)
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function envAsString(value: unknown, defaultValue?: string): string;
+export declare function envAsString(value: unknown, defaultValueOrOptions?: string | EnvAsStringOptions | undefined): string;
 /**
  * Find a case-insensitive environment variable key match.
  * Searches for an environment variable key that matches the given uppercase name,