@systemix/env 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -1,243 +1,234 @@
-"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);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  Config: () => Config,
-  load: () => load,
-  parseEnvFile: () => parseEnvFile
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/env/parse.ts
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+//#region src/env/parse.ts
+/**
+* Parse a string to boolean. Accepts: true/false, 1/0, yes/no, empty string.
+* @param raw - Raw string value
+* @throws When value is not a valid boolean
+*/
 function parseBoolean(raw) {
-  const lower = raw.toLowerCase().trim();
-  if (lower === "true" || lower === "1" || lower === "yes") return true;
-  if (lower === "false" || lower === "0" || lower === "no" || lower === "")
-    return false;
-  throw new Error(`Invalid boolean value: "${raw}"`);
+	const lower = raw.toLowerCase().trim();
+	if (lower === "true" || lower === "1" || lower === "yes") return true;
+	if (lower === "false" || lower === "0" || lower === "no" || lower === "") return false;
+	throw new Error(`Invalid boolean value: "${raw}"`);
 }
+/**
+* Parse a string to number. Uses Number() and checks isFinite.
+* @param raw - Raw string value
+* @throws When value is not a valid number
+*/
 function parseNumber(raw) {
-  const n = Number(raw);
-  if (!Number.isFinite(n)) {
-    throw new Error(`Invalid number value: "${raw}"`);
-  }
-  return n;
+	const n = Number(raw);
+	if (!Number.isFinite(n)) throw new Error(`Invalid number value: "${raw}"`);
+	return n;
 }
+/**
+* Parse .env file content into key-value pairs.
+* Skips comments (#) and empty lines; unquotes " and ' values.
+*
+* @param content - Raw file content
+* @returns Map of KEY -> value strings
+*/
 function parseEnvFile(content) {
-  const result = {};
-  const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eqIndex = trimmed.indexOf("=");
-    if (eqIndex === -1) continue;
-    const key = trimmed.slice(0, eqIndex).trim();
-    let value = trimmed.slice(eqIndex + 1).trim();
-    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-      value = value.slice(1, -1).replace(/\\(.)/g, "$1");
-    }
-    result[key] = value;
-  }
-  return result;
+	const result = {};
+	const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eqIndex = trimmed.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = trimmed.slice(0, eqIndex).trim();
+		let value = trimmed.slice(eqIndex + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1).replace(/\\(.)/g, "$1");
+		result[key] = value;
+	}
+	return result;
 }
-
-// src/env/file.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
+//#endregion
+//#region src/env/file.ts
+/**
+* Load env vars from a .env file. Returns {} if file does not exist.
+*
+* @param filePath - Path relative to cwd or absolute
+* @param cwd - Working directory for resolution
+* @returns Parsed key-value pairs
+*/
 function loadEnvFile(filePath, cwd) {
-  const resolved = (0, import_node_path.resolve)(cwd, filePath);
-  if (!(0, import_node_fs.existsSync)(resolved)) {
-    return {};
-  }
-  const content = (0, import_node_fs.readFileSync)(resolved, "utf-8");
-  return parseEnvFile(content);
+	const resolved = (0, node_path.resolve)(cwd, filePath);
+	if (!(0, node_fs.existsSync)(resolved)) return {};
+	return parseEnvFile((0, node_fs.readFileSync)(resolved, "utf-8"));
 }
+/** Get current working directory, or '.' if process.cwd is unavailable. */
 function getCwd() {
-  return typeof globalThis.process?.cwd === "function" ? globalThis.process.cwd() : ".";
+	return typeof globalThis.process?.cwd === "function" ? globalThis.process.cwd() : ".";
 }
+/** Merge overlay env into base. Overlay keys override base. */
 function mergeEnv(base, overlay) {
-  const merged = { ...base };
-  for (const [k, v] of Object.entries(overlay)) {
-    merged[k] = v;
-  }
-  return merged;
+	const merged = { ...base };
+	for (const [k, v] of Object.entries(overlay)) merged[k] = v;
+	return merged;
 }
+/** Get process.env as a plain object, or {} if unavailable. */
 function getEnvSource() {
-  const env = globalThis.process?.env;
-  if (env && typeof env === "object") {
-    return env;
-  }
-  return {};
+	const env = globalThis.process?.env;
+	if (env && typeof env === "object") return env;
+	return {};
 }
-
-// src/env/load.ts
-var MASK = "***";
+//#endregion
+//#region src/env/load.ts
+const MASK = "***";
+/**
+* Load and validate environment variables from a schema.
+* Parses strings, numbers, and booleans; validates min/max, regex, oneOf.
+* Returns a typed object with toSafeLog() for safe logging (masks secrets).
+*
+* @param schema - Map of var names to schema definitions
+* @param options - Source override, fromFile, or strict mode. Legacy: plain object as source.
+* @returns Typed env object with toSafeLog()
+* @throws When required vars are missing or validation fails
+*
+* @example
+* const env = load(
+*   { PORT: { type: 'number', default: 3000 }, API_KEY: { type: 'string', required: true } },
+*   { source: process.env }
+* );
+*/
 function load(schema, options) {
-  const opts = options ?? {};
-  const isLegacySource = opts && typeof opts === "object" && !Array.isArray(opts) && !("source" in opts) && !("fromFile" in opts) && !("strict" in opts);
-  const normalized = isLegacySource ? { source: opts } : opts;
-  const { source, fromFile, strict = false } = normalized;
-  let env = source ?? getEnvSource();
-  if (fromFile) {
-    const cwd = getCwd();
-    const files = Array.isArray(fromFile) ? fromFile : [fromFile];
-    for (const f of files) {
-      const loaded = loadEnvFile(f, cwd);
-      env = mergeEnv(env, loaded);
-    }
-  }
-  if (strict) {
-    const schemaKeys2 = new Set(Object.keys(schema));
-    const filtered = {};
-    for (const [k, v] of Object.entries(env)) {
-      if (schemaKeys2.has(k)) filtered[k] = v;
-    }
-    env = filtered;
-  }
-  const schemaKeys = Object.keys(schema);
-  const errors = [];
-  const result = {};
-  for (const key of schemaKeys) {
-    const def = schema[key];
-    const raw = env[key];
-    const { type, required = false, default: defaultValue } = def;
-    if (raw === void 0 || raw === "") {
-      if (required && defaultValue === void 0) {
-        errors.push(`Missing required env var: ${key}`);
-        continue;
-      }
-      result[key] = defaultValue ?? void 0;
-      continue;
-    }
-    try {
-      let value;
-      if (def.transform) {
-        value = def.transform(raw);
-      } else {
-        switch (type) {
-          case "string":
-            value = raw;
-            break;
-          case "number":
-            value = parseNumber(raw);
-            break;
-          case "boolean":
-            value = parseBoolean(raw);
-            break;
-          default:
-            value = raw;
-        }
-      }
-      if (type === "number" && typeof value === "number") {
-        if (def.min !== void 0 && value < def.min) {
-          errors.push(`${key}: must be >= ${def.min}`);
-          continue;
-        }
-        if (def.max !== void 0 && value > def.max) {
-          errors.push(`${key}: must be <= ${def.max}`);
-          continue;
-        }
-      }
-      if (type === "string" && typeof value === "string") {
-        if (def.regex && !def.regex.test(value)) {
-          errors.push(`${key}: must match ${def.regex}`);
-          continue;
-        }
-        if (def.oneOf && !def.oneOf.includes(value)) {
-          errors.push(`${key}: must be one of [${def.oneOf.join(", ")}]`);
-          continue;
-        }
-      }
-      result[key] = value;
-    } catch (err) {
-      errors.push(
-        `${key}: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  }
-  if (errors.length > 0) {
-    throw new Error(
-      `Env validation failed:
-${errors.map((e) => `  - ${e}`).join("\n")}`
-    );
-  }
-  const toSafeLog = () => {
-    const safe = {};
-    for (const key of schemaKeys) {
-      const def = schema[key];
-      const val = result[key];
-      safe[key] = def.secret && val !== void 0 ? MASK : val;
-    }
-    return safe;
-  };
-  return Object.assign(result, { toSafeLog });
+	const opts = options ?? {};
+	const { source, fromFile, strict = false } = opts && typeof opts === "object" && !Array.isArray(opts) && !("source" in opts) && !("fromFile" in opts) && !("strict" in opts) ? { source: opts } : opts;
+	let env = source ?? getEnvSource();
+	if (fromFile) {
+		const cwd = getCwd();
+		const files = Array.isArray(fromFile) ? fromFile : [fromFile];
+		for (const f of files) {
+			const loaded = loadEnvFile(f, cwd);
+			env = mergeEnv(env, loaded);
+		}
+	}
+	if (strict) {
+		const schemaKeys = new Set(Object.keys(schema));
+		const filtered = {};
+		for (const [k, v] of Object.entries(env)) if (schemaKeys.has(k)) filtered[k] = v;
+		env = filtered;
+	}
+	const schemaKeys = Object.keys(schema);
+	const errors = [];
+	const result = {};
+	for (const key of schemaKeys) {
+		const def = schema[key];
+		const raw = env[key];
+		const { type, required = false, default: defaultValue } = def;
+		if (raw === void 0 || raw === "") {
+			if (required && defaultValue === void 0) {
+				errors.push(`Missing required env var: ${key}`);
+				continue;
+			}
+			result[key] = defaultValue ?? void 0;
+			continue;
+		}
+		try {
+			let value;
+			if (def.transform) value = def.transform(raw);
+			else switch (type) {
+				case "string":
+					value = raw;
+					break;
+				case "number":
+					value = parseNumber(raw);
+					break;
+				case "boolean":
+					value = parseBoolean(raw);
+					break;
+				default: value = raw;
+			}
+			if (type === "number" && typeof value === "number") {
+				if (def.min !== void 0 && value < def.min) {
+					errors.push(`${key}: must be >= ${def.min}`);
+					continue;
+				}
+				if (def.max !== void 0 && value > def.max) {
+					errors.push(`${key}: must be <= ${def.max}`);
+					continue;
+				}
+			}
+			if (type === "string" && typeof value === "string") {
+				if (def.regex && !def.regex.test(value)) {
+					errors.push(`${key}: must match ${def.regex}`);
+					continue;
+				}
+				if (def.oneOf && !def.oneOf.includes(value)) {
+					errors.push(`${key}: must be one of [${def.oneOf.join(", ")}]`);
+					continue;
+				}
+			}
+			result[key] = value;
+		} catch (err) {
+			errors.push(`${key}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	if (errors.length > 0) throw new Error(`Env validation failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+	const toSafeLog = () => {
+		const safe = {};
+		for (const key of schemaKeys) {
+			const def = schema[key];
+			const val = result[key];
+			safe[key] = def.secret && val !== void 0 ? MASK : val;
+		}
+		return safe;
+	};
+	return Object.assign(result, { toSafeLog });
 }
-
-// src/config.ts
-var Config = class _Config {
-  constructor(config) {
-    this.config = config;
-  }
-  /**
-   * Create Config from a schema and env source.
-   * @param schema - Env variable definitions
-   * @param options - Source, fromFile, or strict. Legacy: plain object as source.
-   */
-  static fromEnv(schema, options) {
-    const config = load(schema, options);
-    return new _Config(config);
-  }
-  /** Create Config from an existing load() result. */
-  static from(config) {
-    return new _Config(config);
-  }
-  get(key, defaultValue) {
-    const val = this.config[key];
-    if (defaultValue !== void 0 && val === void 0) return defaultValue;
-    return val;
-  }
-  /** Get value by key, or throw if not set. */
-  getOrThrow(key) {
-    const val = this.config[key];
-    if (val === void 0) {
-      throw new Error(`Config key "${String(key)}" is not set`);
-    }
-    return val;
-  }
-  /** Check if key is set. */
-  has(key) {
-    return this.config[key] !== void 0;
-  }
-  /** Return a copy with secret values masked as '***'. */
-  toSafeLog() {
-    return this.config.toSafeLog();
-  }
-  /** Get the raw env result (no masking). */
-  getRaw() {
-    return this.config;
-  }
+//#endregion
+//#region src/config.ts
+/**
+* Typed configuration container built from env vars.
+* Use fromEnv() to load from schema, or from() to wrap an existing result.
+*
+* @template T - Schema type (keys and value types)
+*/
+var Config = class Config {
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Create Config from a schema and env source.
+	* @param schema - Env variable definitions
+	* @param options - Source, fromFile, or strict. Legacy: plain object as source.
+	*/
+	static fromEnv(schema, options) {
+		const config = load(schema, options);
+		return new Config(config);
+	}
+	/** Create Config from an existing load() result. */
+	static from(config) {
+		return new Config(config);
+	}
+	get(key, defaultValue) {
+		const val = this.config[key];
+		if (defaultValue !== void 0 && val === void 0) return defaultValue;
+		return val;
+	}
+	/** Get value by key, or throw if not set. */
+	getOrThrow(key) {
+		const val = this.config[key];
+		if (val === void 0) throw new Error(`Config key "${String(key)}" is not set`);
+		return val;
+	}
+	/** Check if key is set. */
+	has(key) {
+		return this.config[key] !== void 0;
+	}
+	/** Return a copy with secret values masked as '***'. */
+	toSafeLog() {
+		return this.config.toSafeLog();
+	}
+	/** Get the raw env result (no masking). */
+	getRaw() {
+		return this.config;
+	}
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Config,
-  load,
-  parseEnvFile
-});
+//#endregion
+exports.Config = Config;
+exports.load = load;
+exports.parseEnvFile = parseEnvFile;

package/dist/index.d.cts

@@ -1,43 +1,45 @@
+//#region src/types/env.d.ts
 type EnvVarType = 'string' | 'number' | 'boolean';
 interface EnvVarSchema<T extends EnvVarType = EnvVarType> {
-    type: T;
-    required?: boolean;
-    default?: T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : never;
-    min?: number;
-    max?: number;
-    regex?: RegExp;
-    oneOf?: readonly string[];
-    transform?: (raw: string) => string | number | boolean;
-    secret?: boolean;
+  type: T;
+  required?: boolean;
+  default?: T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : never;
+  min?: number;
+  max?: number;
+  regex?: RegExp;
+  oneOf?: readonly string[];
+  transform?: (raw: string) => string | number | boolean;
+  secret?: boolean;
 }
 type EnvSchema = Record<string, EnvVarSchema<'string' | 'number' | 'boolean'>>;
 type EnvValueFor<S extends EnvVarSchema<EnvVarType>> = S['type'] extends 'string' ? string : S['type'] extends 'number' ? number : S['type'] extends 'boolean' ? boolean : never;
-type EnvResult<T extends EnvSchema> = {
-    [K in keyof T]: T[K]['required'] extends true ? EnvValueFor<T[K]> : T[K]['default'] extends EnvValueFor<T[K]> ? EnvValueFor<T[K]> : EnvValueFor<T[K]> | undefined;
-} & {
-    toSafeLog(): Record<string, string | number | boolean | undefined>;
+type EnvResult<T extends EnvSchema> = { [K in keyof T]: T[K]['required'] extends true ? EnvValueFor<T[K]> : T[K]['default'] extends EnvValueFor<T[K]> ? EnvValueFor<T[K]> : EnvValueFor<T[K]> | undefined; } & {
+  toSafeLog(): Record<string, string | number | boolean | undefined>;
 };
 interface LoadOptions {
-    source?: Record<string, string | undefined>;
-    fromFile?: string | string[];
-    strict?: boolean;
+  source?: Record<string, string | undefined>;
+  fromFile?: string | string[];
+  strict?: boolean;
 }
-
-declare function parseEnvFile(content: string): Record<string, string>;
-
-declare function load<T extends EnvSchema>(schema: T, options?: LoadOptions | Record<string, string | undefined>): EnvResult<T>;
-
-declare class Config<T extends EnvSchema> {
-    private readonly config;
-    private constructor();
-    static fromEnv<S extends EnvSchema>(schema: S, options?: LoadOptions | Record<string, string | undefined>): Config<S>;
-    static from<S extends EnvSchema>(config: EnvResult<S>): Config<S>;
-    get<K extends keyof T>(key: K): EnvResult<T>[K] | undefined;
-    get<K extends keyof T>(key: K, defaultValue: EnvResult<T>[K]): EnvResult<T>[K];
-    getOrThrow<K extends keyof T>(key: K): EnvResult<T>[K];
-    has(key: keyof T): boolean;
-    toSafeLog(): Record<string, string | number | boolean | undefined>;
-    getRaw(): EnvResult<T>;
+//#endregion
+//#region src/env/parse.d.ts
+export declare function parseEnvFile(content: string): Record<string, string>;
+//#endregion
+//#region src/env/load.d.ts
+export declare function load<T extends EnvSchema>(schema: T, options?: LoadOptions | Record<string, string | undefined>): EnvResult<T>;
+//#endregion
+//#region src/config.d.ts
+export declare class Config<T extends EnvSchema> {
+  private readonly config;
+  private constructor();
+  static fromEnv<S extends EnvSchema>(schema: S, options?: LoadOptions | Record<string, string | undefined>): Config<S>;
+  static from<S extends EnvSchema>(config: EnvResult<S>): Config<S>;
+  get<K extends keyof T>(key: K): EnvResult<T>[K] | undefined;
+  get<K extends keyof T>(key: K, defaultValue: EnvResult<T>[K]): EnvResult<T>[K];
+  getOrThrow<K extends keyof T>(key: K): EnvResult<T>[K];
+  has(key: keyof T): boolean;
+  toSafeLog(): Record<string, string | number | boolean | undefined>;
+  getRaw(): EnvResult<T>;
 }
-
-export { Config, type EnvResult, type EnvSchema, type EnvVarSchema, type EnvVarType, type LoadOptions, load, parseEnvFile };
+//#endregion
+export type { EnvResult, EnvSchema, EnvVarSchema, EnvVarType, LoadOptions };

package/dist/index.d.ts

@@ -1,43 +1,45 @@
+//#region src/types/env.d.ts
 type EnvVarType = 'string' | 'number' | 'boolean';
 interface EnvVarSchema<T extends EnvVarType = EnvVarType> {
-    type: T;
-    required?: boolean;
-    default?: T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : never;
-    min?: number;
-    max?: number;
-    regex?: RegExp;
-    oneOf?: readonly string[];
-    transform?: (raw: string) => string | number | boolean;
-    secret?: boolean;
+  type: T;
+  required?: boolean;
+  default?: T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : never;
+  min?: number;
+  max?: number;
+  regex?: RegExp;
+  oneOf?: readonly string[];
+  transform?: (raw: string) => string | number | boolean;
+  secret?: boolean;
 }
 type EnvSchema = Record<string, EnvVarSchema<'string' | 'number' | 'boolean'>>;
 type EnvValueFor<S extends EnvVarSchema<EnvVarType>> = S['type'] extends 'string' ? string : S['type'] extends 'number' ? number : S['type'] extends 'boolean' ? boolean : never;
-type EnvResult<T extends EnvSchema> = {
-    [K in keyof T]: T[K]['required'] extends true ? EnvValueFor<T[K]> : T[K]['default'] extends EnvValueFor<T[K]> ? EnvValueFor<T[K]> : EnvValueFor<T[K]> | undefined;
-} & {
-    toSafeLog(): Record<string, string | number | boolean | undefined>;
+type EnvResult<T extends EnvSchema> = { [K in keyof T]: T[K]['required'] extends true ? EnvValueFor<T[K]> : T[K]['default'] extends EnvValueFor<T[K]> ? EnvValueFor<T[K]> : EnvValueFor<T[K]> | undefined; } & {
+  toSafeLog(): Record<string, string | number | boolean | undefined>;
 };
 interface LoadOptions {
-    source?: Record<string, string | undefined>;
-    fromFile?: string | string[];
-    strict?: boolean;
+  source?: Record<string, string | undefined>;
+  fromFile?: string | string[];
+  strict?: boolean;
 }
-
-declare function parseEnvFile(content: string): Record<string, string>;
-
-declare function load<T extends EnvSchema>(schema: T, options?: LoadOptions | Record<string, string | undefined>): EnvResult<T>;
-
-declare class Config<T extends EnvSchema> {
-    private readonly config;
-    private constructor();
-    static fromEnv<S extends EnvSchema>(schema: S, options?: LoadOptions | Record<string, string | undefined>): Config<S>;
-    static from<S extends EnvSchema>(config: EnvResult<S>): Config<S>;
-    get<K extends keyof T>(key: K): EnvResult<T>[K] | undefined;
-    get<K extends keyof T>(key: K, defaultValue: EnvResult<T>[K]): EnvResult<T>[K];
-    getOrThrow<K extends keyof T>(key: K): EnvResult<T>[K];
-    has(key: keyof T): boolean;
-    toSafeLog(): Record<string, string | number | boolean | undefined>;
-    getRaw(): EnvResult<T>;
+//#endregion
+//#region src/env/parse.d.ts
+export declare function parseEnvFile(content: string): Record<string, string>;
+//#endregion
+//#region src/env/load.d.ts
+export declare function load<T extends EnvSchema>(schema: T, options?: LoadOptions | Record<string, string | undefined>): EnvResult<T>;
+//#endregion
+//#region src/config.d.ts
+export declare class Config<T extends EnvSchema> {
+  private readonly config;
+  private constructor();
+  static fromEnv<S extends EnvSchema>(schema: S, options?: LoadOptions | Record<string, string | undefined>): Config<S>;
+  static from<S extends EnvSchema>(config: EnvResult<S>): Config<S>;
+  get<K extends keyof T>(key: K): EnvResult<T>[K] | undefined;
+  get<K extends keyof T>(key: K, defaultValue: EnvResult<T>[K]): EnvResult<T>[K];
+  getOrThrow<K extends keyof T>(key: K): EnvResult<T>[K];
+  has(key: keyof T): boolean;
+  toSafeLog(): Record<string, string | number | boolean | undefined>;
+  getRaw(): EnvResult<T>;
 }
-
-export { Config, type EnvResult, type EnvSchema, type EnvVarSchema, type EnvVarType, type LoadOptions, load, parseEnvFile };
+//#endregion
+export type { EnvResult, EnvSchema, EnvVarSchema, EnvVarType, LoadOptions };

package/dist/index.js

@@ -1,214 +1,231 @@
-// src/env/parse.ts
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/env/parse.ts
+/**
+* Parse a string to boolean. Accepts: true/false, 1/0, yes/no, empty string.
+* @param raw - Raw string value
+* @throws When value is not a valid boolean
+*/
 function parseBoolean(raw) {
-  const lower = raw.toLowerCase().trim();
-  if (lower === "true" || lower === "1" || lower === "yes") return true;
-  if (lower === "false" || lower === "0" || lower === "no" || lower === "")
-    return false;
-  throw new Error(`Invalid boolean value: "${raw}"`);
+	const lower = raw.toLowerCase().trim();
+	if (lower === "true" || lower === "1" || lower === "yes") return true;
+	if (lower === "false" || lower === "0" || lower === "no" || lower === "") return false;
+	throw new Error(`Invalid boolean value: "${raw}"`);
 }
+/**
+* Parse a string to number. Uses Number() and checks isFinite.
+* @param raw - Raw string value
+* @throws When value is not a valid number
+*/
 function parseNumber(raw) {
-  const n = Number(raw);
-  if (!Number.isFinite(n)) {
-    throw new Error(`Invalid number value: "${raw}"`);
-  }
-  return n;
+	const n = Number(raw);
+	if (!Number.isFinite(n)) throw new Error(`Invalid number value: "${raw}"`);
+	return n;
 }
+/**
+* Parse .env file content into key-value pairs.
+* Skips comments (#) and empty lines; unquotes " and ' values.
+*
+* @param content - Raw file content
+* @returns Map of KEY -> value strings
+*/
 function parseEnvFile(content) {
-  const result = {};
-  const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eqIndex = trimmed.indexOf("=");
-    if (eqIndex === -1) continue;
-    const key = trimmed.slice(0, eqIndex).trim();
-    let value = trimmed.slice(eqIndex + 1).trim();
-    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-      value = value.slice(1, -1).replace(/\\(.)/g, "$1");
-    }
-    result[key] = value;
-  }
-  return result;
+	const result = {};
+	const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eqIndex = trimmed.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = trimmed.slice(0, eqIndex).trim();
+		let value = trimmed.slice(eqIndex + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1).replace(/\\(.)/g, "$1");
+		result[key] = value;
+	}
+	return result;
 }
-
-// src/env/file.ts
-import { readFileSync, existsSync } from "fs";
-import { resolve } from "path";
+//#endregion
+//#region src/env/file.ts
+/**
+* Load env vars from a .env file. Returns {} if file does not exist.
+*
+* @param filePath - Path relative to cwd or absolute
+* @param cwd - Working directory for resolution
+* @returns Parsed key-value pairs
+*/
 function loadEnvFile(filePath, cwd) {
-  const resolved = resolve(cwd, filePath);
-  if (!existsSync(resolved)) {
-    return {};
-  }
-  const content = readFileSync(resolved, "utf-8");
-  return parseEnvFile(content);
+	const resolved = resolve(cwd, filePath);
+	if (!existsSync(resolved)) return {};
+	return parseEnvFile(readFileSync(resolved, "utf-8"));
 }
+/** Get current working directory, or '.' if process.cwd is unavailable. */
 function getCwd() {
-  return typeof globalThis.process?.cwd === "function" ? globalThis.process.cwd() : ".";
+	return typeof globalThis.process?.cwd === "function" ? globalThis.process.cwd() : ".";
 }
+/** Merge overlay env into base. Overlay keys override base. */
 function mergeEnv(base, overlay) {
-  const merged = { ...base };
-  for (const [k, v] of Object.entries(overlay)) {
-    merged[k] = v;
-  }
-  return merged;
+	const merged = { ...base };
+	for (const [k, v] of Object.entries(overlay)) merged[k] = v;
+	return merged;
 }
+/** Get process.env as a plain object, or {} if unavailable. */
 function getEnvSource() {
-  const env = globalThis.process?.env;
-  if (env && typeof env === "object") {
-    return env;
-  }
-  return {};
+	const env = globalThis.process?.env;
+	if (env && typeof env === "object") return env;
+	return {};
 }
-
-// src/env/load.ts
-var MASK = "***";
+//#endregion
+//#region src/env/load.ts
+const MASK = "***";
+/**
+* Load and validate environment variables from a schema.
+* Parses strings, numbers, and booleans; validates min/max, regex, oneOf.
+* Returns a typed object with toSafeLog() for safe logging (masks secrets).
+*
+* @param schema - Map of var names to schema definitions
+* @param options - Source override, fromFile, or strict mode. Legacy: plain object as source.
+* @returns Typed env object with toSafeLog()
+* @throws When required vars are missing or validation fails
+*
+* @example
+* const env = load(
+*   { PORT: { type: 'number', default: 3000 }, API_KEY: { type: 'string', required: true } },
+*   { source: process.env }
+* );
+*/
 function load(schema, options) {
-  const opts = options ?? {};
-  const isLegacySource = opts && typeof opts === "object" && !Array.isArray(opts) && !("source" in opts) && !("fromFile" in opts) && !("strict" in opts);
-  const normalized = isLegacySource ? { source: opts } : opts;
-  const { source, fromFile, strict = false } = normalized;
-  let env = source ?? getEnvSource();
-  if (fromFile) {
-    const cwd = getCwd();
-    const files = Array.isArray(fromFile) ? fromFile : [fromFile];
-    for (const f of files) {
-      const loaded = loadEnvFile(f, cwd);
-      env = mergeEnv(env, loaded);
-    }
-  }
-  if (strict) {
-    const schemaKeys2 = new Set(Object.keys(schema));
-    const filtered = {};
-    for (const [k, v] of Object.entries(env)) {
-      if (schemaKeys2.has(k)) filtered[k] = v;
-    }
-    env = filtered;
-  }
-  const schemaKeys = Object.keys(schema);
-  const errors = [];
-  const result = {};
-  for (const key of schemaKeys) {
-    const def = schema[key];
-    const raw = env[key];
-    const { type, required = false, default: defaultValue } = def;
-    if (raw === void 0 || raw === "") {
-      if (required && defaultValue === void 0) {
-        errors.push(`Missing required env var: ${key}`);
-        continue;
-      }
-      result[key] = defaultValue ?? void 0;
-      continue;
-    }
-    try {
-      let value;
-      if (def.transform) {
-        value = def.transform(raw);
-      } else {
-        switch (type) {
-          case "string":
-            value = raw;
-            break;
-          case "number":
-            value = parseNumber(raw);
-            break;
-          case "boolean":
-            value = parseBoolean(raw);
-            break;
-          default:
-            value = raw;
-        }
-      }
-      if (type === "number" && typeof value === "number") {
-        if (def.min !== void 0 && value < def.min) {
-          errors.push(`${key}: must be >= ${def.min}`);
-          continue;
-        }
-        if (def.max !== void 0 && value > def.max) {
-          errors.push(`${key}: must be <= ${def.max}`);
-          continue;
-        }
-      }
-      if (type === "string" && typeof value === "string") {
-        if (def.regex && !def.regex.test(value)) {
-          errors.push(`${key}: must match ${def.regex}`);
-          continue;
-        }
-        if (def.oneOf && !def.oneOf.includes(value)) {
-          errors.push(`${key}: must be one of [${def.oneOf.join(", ")}]`);
-          continue;
-        }
-      }
-      result[key] = value;
-    } catch (err) {
-      errors.push(
-        `${key}: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  }
-  if (errors.length > 0) {
-    throw new Error(
-      `Env validation failed:
-${errors.map((e) => `  - ${e}`).join("\n")}`
-    );
-  }
-  const toSafeLog = () => {
-    const safe = {};
-    for (const key of schemaKeys) {
-      const def = schema[key];
-      const val = result[key];
-      safe[key] = def.secret && val !== void 0 ? MASK : val;
-    }
-    return safe;
-  };
-  return Object.assign(result, { toSafeLog });
+	const opts = options ?? {};
+	const { source, fromFile, strict = false } = opts && typeof opts === "object" && !Array.isArray(opts) && !("source" in opts) && !("fromFile" in opts) && !("strict" in opts) ? { source: opts } : opts;
+	let env = source ?? getEnvSource();
+	if (fromFile) {
+		const cwd = getCwd();
+		const files = Array.isArray(fromFile) ? fromFile : [fromFile];
+		for (const f of files) {
+			const loaded = loadEnvFile(f, cwd);
+			env = mergeEnv(env, loaded);
+		}
+	}
+	if (strict) {
+		const schemaKeys = new Set(Object.keys(schema));
+		const filtered = {};
+		for (const [k, v] of Object.entries(env)) if (schemaKeys.has(k)) filtered[k] = v;
+		env = filtered;
+	}
+	const schemaKeys = Object.keys(schema);
+	const errors = [];
+	const result = {};
+	for (const key of schemaKeys) {
+		const def = schema[key];
+		const raw = env[key];
+		const { type, required = false, default: defaultValue } = def;
+		if (raw === void 0 || raw === "") {
+			if (required && defaultValue === void 0) {
+				errors.push(`Missing required env var: ${key}`);
+				continue;
+			}
+			result[key] = defaultValue ?? void 0;
+			continue;
+		}
+		try {
+			let value;
+			if (def.transform) value = def.transform(raw);
+			else switch (type) {
+				case "string":
+					value = raw;
+					break;
+				case "number":
+					value = parseNumber(raw);
+					break;
+				case "boolean":
+					value = parseBoolean(raw);
+					break;
+				default: value = raw;
+			}
+			if (type === "number" && typeof value === "number") {
+				if (def.min !== void 0 && value < def.min) {
+					errors.push(`${key}: must be >= ${def.min}`);
+					continue;
+				}
+				if (def.max !== void 0 && value > def.max) {
+					errors.push(`${key}: must be <= ${def.max}`);
+					continue;
+				}
+			}
+			if (type === "string" && typeof value === "string") {
+				if (def.regex && !def.regex.test(value)) {
+					errors.push(`${key}: must match ${def.regex}`);
+					continue;
+				}
+				if (def.oneOf && !def.oneOf.includes(value)) {
+					errors.push(`${key}: must be one of [${def.oneOf.join(", ")}]`);
+					continue;
+				}
+			}
+			result[key] = value;
+		} catch (err) {
+			errors.push(`${key}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	if (errors.length > 0) throw new Error(`Env validation failed:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+	const toSafeLog = () => {
+		const safe = {};
+		for (const key of schemaKeys) {
+			const def = schema[key];
+			const val = result[key];
+			safe[key] = def.secret && val !== void 0 ? MASK : val;
+		}
+		return safe;
+	};
+	return Object.assign(result, { toSafeLog });
 }
-
-// src/config.ts
-var Config = class _Config {
-  constructor(config) {
-    this.config = config;
-  }
-  /**
-   * Create Config from a schema and env source.
-   * @param schema - Env variable definitions
-   * @param options - Source, fromFile, or strict. Legacy: plain object as source.
-   */
-  static fromEnv(schema, options) {
-    const config = load(schema, options);
-    return new _Config(config);
-  }
-  /** Create Config from an existing load() result. */
-  static from(config) {
-    return new _Config(config);
-  }
-  get(key, defaultValue) {
-    const val = this.config[key];
-    if (defaultValue !== void 0 && val === void 0) return defaultValue;
-    return val;
-  }
-  /** Get value by key, or throw if not set. */
-  getOrThrow(key) {
-    const val = this.config[key];
-    if (val === void 0) {
-      throw new Error(`Config key "${String(key)}" is not set`);
-    }
-    return val;
-  }
-  /** Check if key is set. */
-  has(key) {
-    return this.config[key] !== void 0;
-  }
-  /** Return a copy with secret values masked as '***'. */
-  toSafeLog() {
-    return this.config.toSafeLog();
-  }
-  /** Get the raw env result (no masking). */
-  getRaw() {
-    return this.config;
-  }
-};
-export {
-  Config,
-  load,
-  parseEnvFile
+//#endregion
+//#region src/config.ts
+/**
+* Typed configuration container built from env vars.
+* Use fromEnv() to load from schema, or from() to wrap an existing result.
+*
+* @template T - Schema type (keys and value types)
+*/
+var Config = class Config {
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Create Config from a schema and env source.
+	* @param schema - Env variable definitions
+	* @param options - Source, fromFile, or strict. Legacy: plain object as source.
+	*/
+	static fromEnv(schema, options) {
+		const config = load(schema, options);
+		return new Config(config);
+	}
+	/** Create Config from an existing load() result. */
+	static from(config) {
+		return new Config(config);
+	}
+	get(key, defaultValue) {
+		const val = this.config[key];
+		if (defaultValue !== void 0 && val === void 0) return defaultValue;
+		return val;
+	}
+	/** Get value by key, or throw if not set. */
+	getOrThrow(key) {
+		const val = this.config[key];
+		if (val === void 0) throw new Error(`Config key "${String(key)}" is not set`);
+		return val;
+	}
+	/** Check if key is set. */
+	has(key) {
+		return this.config[key] !== void 0;
+	}
+	/** Return a copy with secret values masked as '***'. */
+	toSafeLog() {
+		return this.config.toSafeLog();
+	}
+	/** Get the raw env result (no masking). */
+	getRaw() {
+		return this.config;
+	}
 };
+//#endregion
+export { Config, load, parseEnvFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@systemix/env",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "publishConfig": {
     "access": "public"
   },
@@ -22,6 +22,18 @@
     "directory": "packages/env"
   },
   "homepage": "https://github.com/shahadathhs/systemix/tree/main/packages/env#readme",
+  "scripts": {
+    "build": "tsdown",
+    "test": "node tests/run.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint . --type-aware",
+    "lint:fix": "oxlint . --type-aware --fix",
+    "format": "prettier --check . --ignore-path .prettierignore",
+    "format:fix": "prettier --write . --ignore-path .prettierignore",
+    "clean": "rimraf dist node_modules",
+    "clean:turbo": "rimraf .turbo dist node_modules",
+    "prepublishOnly": "pnpm build"
+  },
   "keywords": [
     "systemix",
     "env",
@@ -37,13 +49,14 @@
   "license": "MIT",
   "description": "Typed environment variable loading and validation. Part of the Systemix toolkit.",
   "devDependencies": {
-    "@types/node": "^25.3.5",
-    "eslint": "^10.0.3",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "@systemix/eslint": "0.5.0",
-    "@systemix/runner": "0.3.0",
-    "@systemix/typescript": "0.5.0"
+    "@systemix/runner": "workspace:*",
+    "@systemix/typescript": "workspace:*",
+    "@types/node": "catalog:",
+    "eslint": "catalog:",
+    "oxlint": "catalog:",
+    "oxlint-tsgolint": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:"
   },
   "directories": {
     "test": "tests"
@@ -58,15 +71,5 @@
     "LICENSE",
     "package.json"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "test": "pnpm build && node tests/run.mjs",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --check . --ignore-path .prettierignore",
-    "format:fix": "prettier --write . --ignore-path .prettierignore",
-    "clean": "rimraf dist node_modules",
-    "clean:turbo": "rimraf .turbo dist node_modules"
-  }
-}
+  "tsconfig": null
+}