docs(env): add @example blocks to env module exports (#172)

Author: jdalton

src/env.ts

@@ -175,6 +175,20 @@ export function createEnvProxy(
 
 /**
  * Convert an environment variable value to a boolean.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * import { envAsBoolean } from '@socketsecurity/lib/env'
+ *
+ * envAsBoolean('true')      // true
+ * envAsBoolean('1')         // true
+ * envAsBoolean('false')     // false
+ * envAsBoolean(undefined)   // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsBoolean(value: unknown, defaultValue = false): boolean {
@@ -190,6 +204,19 @@ export function envAsBoolean(value: unknown, defaultValue = false): boolean {
 
 /**
  * Convert an environment variable value to a number.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * import { envAsNumber } from '@socketsecurity/lib/env'
+ *
+ * envAsNumber('3000')     // 3000
+ * envAsNumber('abc')      // 0
+ * envAsNumber(undefined)  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsNumber(value: unknown, defaultValue = 0): number {
@@ -203,6 +230,19 @@ export function envAsNumber(value: unknown, defaultValue = 0): number {
 
 /**
  * Convert an environment variable value to a trimmed string.
+ *
+ * @param value - The value to convert
+ * @param defaultValue - Default when value is null/undefined (default: `''`)
+ * @returns The trimmed 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'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsString(value: unknown, defaultValue = ''): string {

src/env/ci.ts

@@ -5,6 +5,20 @@
 
 import { isInEnv } from './rewire'
 
+/**
+ * Returns whether the CI environment variable is set.
+ *
+ * @returns `true` if running in a CI environment, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getCI } from '@socketsecurity/lib/env/ci'
+ *
+ * if (getCI()) {
+ *   console.log('Running in CI')
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getCI(): boolean {
   return isInEnv('CI')

src/env/debug.ts

@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the DEBUG environment variable.
+ *
+ * @returns The debug filter string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getDebug } from '@socketsecurity/lib/env/debug'
+ *
+ * const debug = getDebug()
+ * // e.g. 'socket:*' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getDebug(): string | undefined {
   return getEnvValue('DEBUG')

src/env/github.ts

@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * GITHUB_API_URL environment variable.
  * GitHub API URL (e.g., https://api.github.com).
+ *
+ * @returns The GitHub API URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubApiUrl } from '@socketsecurity/lib/env/github'
+ *
+ * const apiUrl = getGithubApiUrl()
+ * // e.g. 'https://api.github.com' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubApiUrl(): string | undefined {
@@ -17,6 +27,16 @@ export function getGithubApiUrl(): string | undefined {
 /**
  * GITHUB_BASE_REF environment variable.
  * GitHub pull request base branch.
+ *
+ * @returns The pull request base branch name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubBaseRef } from '@socketsecurity/lib/env/github'
+ *
+ * const baseRef = getGithubBaseRef()
+ * // e.g. 'main' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubBaseRef(): string | undefined {
@@ -26,6 +46,16 @@ export function getGithubBaseRef(): string | undefined {
 /**
  * GITHUB_REF_NAME environment variable.
  * GitHub branch or tag name.
+ *
+ * @returns The branch or tag name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRefName } from '@socketsecurity/lib/env/github'
+ *
+ * const refName = getGithubRefName()
+ * // e.g. 'feature/my-branch' or 'v1.0.0'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubRefName(): string | undefined {
@@ -35,6 +65,16 @@ export function getGithubRefName(): string | undefined {
 /**
  * GITHUB_REF_TYPE environment variable.
  * GitHub ref type (branch or tag).
+ *
+ * @returns The ref type ('branch' or 'tag'), or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRefType } from '@socketsecurity/lib/env/github'
+ *
+ * const refType = getGithubRefType()
+ * // e.g. 'branch' or 'tag'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubRefType(): string | undefined {
@@ -44,6 +84,16 @@ export function getGithubRefType(): string | undefined {
 /**
  * GITHUB_REPOSITORY environment variable.
  * GitHub repository name in owner/repo format.
+ *
+ * @returns The repository name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRepository } from '@socketsecurity/lib/env/github'
+ *
+ * const repo = getGithubRepository()
+ * // e.g. 'SocketDev/socket-cli' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubRepository(): string | undefined {
@@ -53,6 +103,16 @@ export function getGithubRepository(): string | undefined {
 /**
  * GITHUB_SERVER_URL environment variable.
  * GitHub server URL (e.g., https://github.com).
+ *
+ * @returns The GitHub server URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubServerUrl } from '@socketsecurity/lib/env/github'
+ *
+ * const serverUrl = getGithubServerUrl()
+ * // e.g. 'https://github.com' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubServerUrl(): string | undefined {
@@ -62,6 +122,16 @@ export function getGithubServerUrl(): string | undefined {
 /**
  * GITHUB_TOKEN environment variable.
  * GitHub authentication token for API access.
+ *
+ * @returns The GitHub token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubToken } from '@socketsecurity/lib/env/github'
+ *
+ * const token = getGithubToken()
+ * // e.g. 'ghp_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubToken(): string | undefined {
@@ -71,6 +141,16 @@ export function getGithubToken(): string | undefined {
 /**
  * GH_TOKEN environment variable.
  * Alternative GitHub authentication token for API access (used by GitHub CLI).
+ *
+ * @returns The GH CLI token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGhToken } from '@socketsecurity/lib/env/github'
+ *
+ * const token = getGhToken()
+ * // e.g. 'gho_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGhToken(): string | undefined {

src/env/helpers.ts

@@ -2,6 +2,22 @@
  * @fileoverview Environment variable type conversion helpers.
  */
 
+/**
+ * Convert an environment variable string to a boolean.
+ *
+ * @param value - The environment variable value to convert
+ * @returns `true` if value is 'true', '1', or 'yes' (case-insensitive), `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { envAsBoolean } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsBoolean('true')      // true
+ * envAsBoolean('1')         // true
+ * envAsBoolean('yes')       // true
+ * envAsBoolean(undefined)   // false
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsBoolean(value: string | undefined): boolean {
   if (!value) {
@@ -11,6 +27,21 @@ export function envAsBoolean(value: string | undefined): boolean {
   return lower === 'true' || lower === '1' || lower === 'yes'
 }
 
+/**
+ * Convert an environment variable string to a number.
+ *
+ * @param value - The environment variable value to convert
+ * @returns The parsed number, or `0` if the value is undefined or not a valid number
+ *
+ * @example
+ * ```typescript
+ * import { envAsNumber } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsNumber('3000')     // 3000
+ * envAsNumber(undefined)  // 0
+ * envAsNumber('abc')      // 0
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsNumber(value: string | undefined): number {
   if (!value) {
@@ -20,6 +51,20 @@ export function envAsNumber(value: string | undefined): number {
   return Number.isNaN(num) ? 0 : num
 }
 
+/**
+ * Convert an environment variable value to a string.
+ *
+ * @param value - The environment variable value to convert
+ * @returns The string value, or an empty string if undefined
+ *
+ * @example
+ * ```typescript
+ * import { envAsString } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsString('hello')    // 'hello'
+ * envAsString(undefined)  // ''
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsString(value: string | undefined): string {
   return value || ''

src/env/home.ts

@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the HOME environment variable.
+ *
+ * @returns The user's home directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getHome } from '@socketsecurity/lib/env/home'
+ *
+ * const home = getHome()
+ * // e.g. '/tmp/user' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getHome(): string | undefined {
   return getEnvValue('HOME')

src/env/locale.ts

@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * LANG environment variable.
  * System locale and language settings.
+ *
+ * @returns The system locale string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLang } from '@socketsecurity/lib/env/locale'
+ *
+ * const lang = getLang()
+ * // e.g. 'en_US.UTF-8' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLang(): string | undefined {
@@ -17,6 +27,16 @@ export function getLang(): string | undefined {
 /**
  * LC_ALL environment variable.
  * Override for all locale settings.
+ *
+ * @returns The locale override string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLcAll } from '@socketsecurity/lib/env/locale'
+ *
+ * const lcAll = getLcAll()
+ * // e.g. 'C' or 'en_US.UTF-8'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLcAll(): string | undefined {
@@ -26,6 +46,16 @@ export function getLcAll(): string | undefined {
 /**
  * LC_MESSAGES environment variable.
  * Locale setting for message translations.
+ *
+ * @returns The messages locale string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLcMessages } from '@socketsecurity/lib/env/locale'
+ *
+ * const lcMessages = getLcMessages()
+ * // e.g. 'en_US.UTF-8' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLcMessages(): string | undefined {

src/env/node-auth-token.ts

@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the NODE_AUTH_TOKEN environment variable.
+ *
+ * @returns The Node.js registry auth token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNodeAuthToken } from '@socketsecurity/lib/env/node-auth-token'
+ *
+ * const token = getNodeAuthToken()
+ * // e.g. 'npm_abc123...' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNodeAuthToken(): string | undefined {
   return getEnvValue('NODE_AUTH_TOKEN')