@socketsecurity/lib 5.15.0 → 5.16.0

package/dist/env.d.ts

@@ -35,16 +35,56 @@
 export declare function createEnvProxy(base: NodeJS.ProcessEnv, overrides?: Record<string, string | undefined>): NodeJS.ProcessEnv;
 /**
  * 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 declare function envAsBoolean(value: unknown, defaultValue?: boolean): 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 declare function envAsNumber(value: unknown, defaultValue?: number): 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 declare function envAsString(value: unknown, defaultValue?: string): string;