@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/env/case-insensitive.js

@@ -1,42 +1,57 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var case_insensitive_exports = {};
-__export(case_insensitive_exports, {
-  findCaseInsensitiveEnvKey: () => findCaseInsensitiveEnvKey
-});
-module.exports = __toCommonJS(case_insensitive_exports);
-var import_object = require("../primordials/object");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_object = require('../primordials/object.js');
+
+//#region src/env/case-insensitive.ts
+/**
+* @file Case-insensitive environment-variable key lookup —
+*   `findCaseInsensitiveEnvKey` walks `Object.keys(env)` with an O(1)
+*   length-prefilter before the (expensive) `toUpperCase` comparison. Used by
+*   `createEnvProxy` for Windows-style PATH/Path/path access.
+*/
+/**
+* Find a case-insensitive environment variable key match. Searches for an
+* environment variable key that matches the given uppercase name, using
+* optimized fast-path checks to minimize expensive toUpperCase() calls.
+*
+* **Use Cases:**
+*
+* - Finding PATH when env object has "Path" or "path"
+* - Cross-platform env var access where case may vary
+* - Custom case-insensitive env lookups
+*
+* **Performance:**
+*
+* - Fast path: Checks length first (O(1)) before toUpperCase (expensive)
+* - Only converts to uppercase when length matches
+* - Early exit on first match
+*
+* @example
+*   // Find PATH regardless of case
+*   const envObj = { Path: 'C:\\Windows', NODE_ENV: 'test' }
+*   const key = findCaseInsensitiveEnvKey(envObj, 'PATH')
+*   console.log(key) // 'Path'
+*   console.log(envObj[key]) // 'C:\\Windows'
+*
+* @example
+*   // Not found returns undefined
+*   const key = findCaseInsensitiveEnvKey({}, 'MISSING')
+*   console.log(key) // undefined
+*
+* @param env - Environment object or env-like record to search.
+* @param upperEnvVarName - Uppercase environment variable name to find (e.g.,
+*   'PATH')
+*
+* @returns The actual key from env that matches (e.g., 'Path'), or undefined
+*/
 function findCaseInsensitiveEnvKey(env, upperEnvVarName) {
-  const targetLength = upperEnvVarName.length;
-  for (const key of (0, import_object.ObjectKeys)(env)) {
-    if (key.length !== targetLength) {
-      continue;
-    }
-    if (key.toUpperCase() === upperEnvVarName) {
-      return key;
-    }
-  }
-  return void 0;
+	const targetLength = upperEnvVarName.length;
+	for (const key of require_primordials_object.ObjectKeys(env)) {
+		if (key.length !== targetLength) continue;
+		if (key.toUpperCase() === upperEnvVarName) return key;
+	}
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  findCaseInsensitiveEnvKey
-});
+
+//#endregion
+exports.findCaseInsensitiveEnvKey = findCaseInsensitiveEnvKey;

package/dist/env/ci.js

@@ -1,34 +1,32 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var ci_exports = {};
-__export(ci_exports, {
-  getCI: () => getCI
-});
-module.exports = __toCommonJS(ci_exports);
-var import_rewire = require("./rewire");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_rewire = require('./rewire.js');
+
+//#region src/env/ci.ts
+/**
+* @file CI environment variable getter. Exports `getCI()`, which returns
+*   whether the `CI` environment variable is present (using the rewire helper
+*   so tests can override without touching `process.env`).
+*/
+/**
+* Returns whether the CI environment variable is set.
+*
+* @example
+*   ;```typescript
+*   import { getCI } from '@socketsecurity/lib/env/ci'
+*
+*   if (getCI()) {
+*     console.log('Running in CI')
+*   }
+*   ```
+*
+* @returns `true` if running in a CI environment, `false` otherwise
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getCI() {
-  return (0, import_rewire.isInEnv)("CI");
+	return require_env_rewire.isInEnv("CI");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getCI
-});
+
+//#endregion
+exports.getCI = getCI;

package/dist/env/debug.js

@@ -1,34 +1,31 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var debug_exports = {};
-__export(debug_exports, {
-  getDebug: () => getDebug
-});
-module.exports = __toCommonJS(debug_exports);
-var import_rewire = require("./rewire");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_rewire = require('./rewire.js');
+
+//#region src/env/debug.ts
+/**
+* @file DEBUG environment variable getter. Exports `getDebug()`, which returns
+*   the raw `DEBUG` filter string used by the `debug` package (or `undefined`
+*   when unset).
+*/
+/**
+* Returns the value of the DEBUG environment variable.
+*
+* @example
+*   ;```typescript
+*   import { getDebug } from '@socketsecurity/lib/env/debug'
+*
+*   const debug = getDebug()
+*   // e.g. 'socket:*' or undefined
+*   ```
+*
+* @returns The debug filter string, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getDebug() {
-  return (0, import_rewire.getEnvValue)("DEBUG");
+	return require_env_rewire.getEnvValue("DEBUG");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getDebug
-});
+
+//#endregion
+exports.getDebug = getDebug;

package/dist/env/github.js

@@ -1,76 +1,161 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var github_exports = {};
-__export(github_exports, {
-  getGhToken: () => getGhToken,
-  getGithubApiUrl: () => getGithubApiUrl,
-  getGithubBaseRef: () => getGithubBaseRef,
-  getGithubRefName: () => getGithubRefName,
-  getGithubRefType: () => getGithubRefType,
-  getGithubRepository: () => getGithubRepository,
-  getGithubServerUrl: () => getGithubServerUrl,
-  getGithubToken: () => getGithubToken
-});
-module.exports = __toCommonJS(github_exports);
-var import_rewire = require("./rewire");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_rewire = require('./rewire.js');
+
+//#region src/env/github.ts
+/**
+* @file GitHub Actions environment variable getters. Provides access to GitHub
+*   Actions CI/CD environment variables.
+*/
+/**
+* GH_TOKEN environment variable. Alternative GitHub authentication token for
+* API access (used by GitHub CLI).
+*
+* @example
+*   ;```typescript
+*   import { getGhToken } from '@socketsecurity/lib/env/github'
+*
+*   const token = getGhToken()
+*   // e.g. 'gho_abc123...' or undefined
+*   ```
+*
+* @returns The GH CLI token, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGhToken() {
-  return (0, import_rewire.getEnvValue)("GH_TOKEN");
+	return require_env_rewire.getEnvValue("GH_TOKEN");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_API_URL environment variable. GitHub API URL (e.g.,
+* https://api.github.com).
+*
+* @example
+*   ;```typescript
+*   import { getGithubApiUrl } from '@socketsecurity/lib/env/github'
+*
+*   const apiUrl = getGithubApiUrl()
+*   // e.g. 'https://api.github.com' or undefined
+*   ```
+*
+* @returns The GitHub API URL, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubApiUrl() {
-  return (0, import_rewire.getEnvValue)("GITHUB_API_URL");
+	return require_env_rewire.getEnvValue("GITHUB_API_URL");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_BASE_REF environment variable. GitHub pull request base branch.
+*
+* @example
+*   ;```typescript
+*   import { getGithubBaseRef } from '@socketsecurity/lib/env/github'
+*
+*   const baseRef = getGithubBaseRef()
+*   // e.g. 'main' or undefined
+*   ```
+*
+* @returns The pull request base branch name, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubBaseRef() {
-  return (0, import_rewire.getEnvValue)("GITHUB_BASE_REF");
+	return require_env_rewire.getEnvValue("GITHUB_BASE_REF");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_REF_NAME environment variable. GitHub branch or tag name.
+*
+* @example
+*   ;```typescript
+*   import { getGithubRefName } from '@socketsecurity/lib/env/github'
+*
+*   const refName = getGithubRefName()
+*   // e.g. 'feature/my-branch' or 'v1.0.0'
+*   ```
+*
+* @returns The branch or tag name, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubRefName() {
-  return (0, import_rewire.getEnvValue)("GITHUB_REF_NAME");
+	return require_env_rewire.getEnvValue("GITHUB_REF_NAME");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_REF_TYPE environment variable. GitHub ref type (branch or tag).
+*
+* @example
+*   ;```typescript
+*   import { getGithubRefType } from '@socketsecurity/lib/env/github'
+*
+*   const refType = getGithubRefType()
+*   // e.g. 'branch' or 'tag'
+*   ```
+*
+* @returns The ref type ('branch' or 'tag'), or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubRefType() {
-  return (0, import_rewire.getEnvValue)("GITHUB_REF_TYPE");
+	return require_env_rewire.getEnvValue("GITHUB_REF_TYPE");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_REPOSITORY environment variable. GitHub repository name in owner/repo
+* format.
+*
+* @example
+*   ;```typescript
+*   import { getGithubRepository } from '@socketsecurity/lib/env/github'
+*
+*   const repo = getGithubRepository()
+*   // e.g. 'SocketDev/socket-cli' or undefined
+*   ```
+*
+* @returns The repository name, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubRepository() {
-  return (0, import_rewire.getEnvValue)("GITHUB_REPOSITORY");
+	return require_env_rewire.getEnvValue("GITHUB_REPOSITORY");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_SERVER_URL environment variable. GitHub server URL (e.g.,
+* https://github.com).
+*
+* @example
+*   ;```typescript
+*   import { getGithubServerUrl } from '@socketsecurity/lib/env/github'
+*
+*   const serverUrl = getGithubServerUrl()
+*   // e.g. 'https://github.com' or undefined
+*   ```
+*
+* @returns The GitHub server URL, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubServerUrl() {
-  return (0, import_rewire.getEnvValue)("GITHUB_SERVER_URL");
+	return require_env_rewire.getEnvValue("GITHUB_SERVER_URL");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* GITHUB_TOKEN environment variable. GitHub authentication token for API
+* access.
+*
+* @example
+*   ;```typescript
+*   import { getGithubToken } from '@socketsecurity/lib/env/github'
+*
+*   const token = getGithubToken()
+*   // e.g. 'ghp_abc123...' or undefined
+*   ```
+*
+* @returns The GitHub token, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getGithubToken() {
-  return (0, import_rewire.getEnvValue)("GITHUB_TOKEN");
+	return require_env_rewire.getEnvValue("GITHUB_TOKEN");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getGhToken,
-  getGithubApiUrl,
-  getGithubBaseRef,
-  getGithubRefName,
-  getGithubRefType,
-  getGithubRepository,
-  getGithubServerUrl,
-  getGithubToken
-});
+
+//#endregion
+exports.getGhToken = getGhToken;
+exports.getGithubApiUrl = getGithubApiUrl;
+exports.getGithubBaseRef = getGithubBaseRef;
+exports.getGithubRefName = getGithubRefName;
+exports.getGithubRefType = getGithubRefType;
+exports.getGithubRepository = getGithubRepository;
+exports.getGithubServerUrl = getGithubServerUrl;
+exports.getGithubToken = getGithubToken;

package/dist/env/home.js

@@ -1,34 +1,41 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var home_exports = {};
-__export(home_exports, {
-  getHome: () => getHome
-});
-module.exports = __toCommonJS(home_exports);
-var import_rewire = require("./rewire");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_rewire = require('./rewire.js');
+
+//#region src/env/home.ts
+/**
+* @file HOME environment variable getter with Windows fallback. Returns the
+*   user's home directory. On Windows, HOME is typically unset — fall back to
+*   USERPROFILE before giving up, matching the resolution order used by npm,
+*   git, and Node's os.homedir().
+*/
+/**
+* Returns the user's home directory path.
+*
+* Resolution order:
+*
+* 1. `$HOME` (POSIX, and sometimes set on Windows by shells like Git Bash)
+* 2. `$USERPROFILE` (Windows default, e.g. `C:\Users\alice`)
+*
+* Returns `undefined` only when neither is set, which on modern systems is
+* exceedingly rare outside of sandboxed or minimal-env test harnesses.
+*
+* @example
+*   ;```typescript
+*   import { getHome } from '@socketsecurity/lib/env/home'
+*
+*   const home = getHome()
+*   // POSIX: '/Users/alice'
+*   // Windows: 'C:\\Users\\alice'
+*   ```
+*
+* @returns The user's home directory path, or `undefined` if not resolvable
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getHome() {
-  return (0, import_rewire.getEnvValue)("HOME") ?? (0, import_rewire.getEnvValue)("USERPROFILE");
+	return require_env_rewire.getEnvValue("HOME") ?? require_env_rewire.getEnvValue("USERPROFILE");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getHome
-});
+
+//#endregion
+exports.getHome = getHome;

package/dist/env/locale.js

@@ -1,46 +1,66 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var locale_exports = {};
-__export(locale_exports, {
-  getLang: () => getLang,
-  getLcAll: () => getLcAll,
-  getLcMessages: () => getLcMessages
-});
-module.exports = __toCommonJS(locale_exports);
-var import_rewire = require("./rewire");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_rewire = require('./rewire.js');
+
+//#region src/env/locale.ts
+/**
+* @file Locale and language environment variable getters. Provides access to
+*   system locale settings.
+*/
+/**
+* LANG environment variable. System locale and language settings.
+*
+* @example
+*   ;```typescript
+*   import { getLang } from '@socketsecurity/lib/env/locale'
+*
+*   const lang = getLang()
+*   // e.g. 'en_US.UTF-8' or undefined
+*   ```
+*
+* @returns The system locale string, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getLang() {
-  return (0, import_rewire.getEnvValue)("LANG");
+	return require_env_rewire.getEnvValue("LANG");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* LC_ALL environment variable. Override for all locale settings.
+*
+* @example
+*   ;```typescript
+*   import { getLcAll } from '@socketsecurity/lib/env/locale'
+*
+*   const lcAll = getLcAll()
+*   // e.g. 'C' or 'en_US.UTF-8'
+*   ```
+*
+* @returns The locale override string, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getLcAll() {
-  return (0, import_rewire.getEnvValue)("LC_ALL");
+	return require_env_rewire.getEnvValue("LC_ALL");
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* LC_MESSAGES environment variable. Locale setting for message translations.
+*
+* @example
+*   ;```typescript
+*   import { getLcMessages } from '@socketsecurity/lib/env/locale'
+*
+*   const lcMessages = getLcMessages()
+*   // e.g. 'en_US.UTF-8' or undefined
+*   ```
+*
+* @returns The messages locale string, or `undefined` if not set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getLcMessages() {
-  return (0, import_rewire.getEnvValue)("LC_MESSAGES");
+	return require_env_rewire.getEnvValue("LC_MESSAGES");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getLang,
-  getLcAll,
-  getLcMessages
-});
+
+//#endregion
+exports.getLang = getLang;
+exports.getLcAll = getLcAll;
+exports.getLcMessages = getLcMessages;