@meltstudio/config-loader 3.7.0 → 4.0.3

package/dist/index.mjs

@@ -0,0 +1,1579 @@
+// src/settings.ts
+import { Command } from "commander";
+
+// src/errors.ts
+var ConfigLoadError = class extends Error {
+  /** All validation errors that caused the load to fail. */
+  errors;
+  /** Non-fatal warnings collected during loading. */
+  warnings;
+  constructor(errors, warnings) {
+    const count = errors.length;
+    const summary = `Configuration loading failed with ${count} error${count === 1 ? "" : "s"}`;
+    const details = errors.slice(0, 10).map((e, i) => `  ${i + 1}. ${e.message}`).join("\n");
+    const message = count > 0 ? `${summary}:
+${details}` : (
+      /* istanbul ignore next */
+      summary
+    );
+    super(message);
+    this.name = "ConfigLoadError";
+    this.errors = errors;
+    this.warnings = warnings;
+  }
+};
+var ConfigFileError = class extends ConfigLoadError {
+  constructor(message) {
+    super([{ message, kind: "file_validation" }], []);
+    this.name = "ConfigFileError";
+    this.message = message;
+  }
+};
+
+// src/nodes/configNode.ts
+var ConfigNode = class {
+  value;
+  path;
+  sourceType;
+  file;
+  variableName;
+  argName;
+  line;
+  column;
+  sensitive;
+  constructor(value, path2, sourceType, file, variableName, argName, line = null, column = null, sensitive = false) {
+    this.value = value;
+    this.path = path2;
+    this.sourceType = sourceType;
+    this.file = file;
+    this.variableName = variableName;
+    this.argName = argName;
+    this.line = line;
+    this.column = column;
+    this.sensitive = sensitive;
+  }
+};
+var configNode_default = ConfigNode;
+
+// src/nodes/configNodeArray.ts
+var ConfigNodeArray = class {
+  arrayValues;
+  constructor(arrayValues) {
+    this.arrayValues = arrayValues;
+  }
+};
+var configNodeArray_default = ConfigNodeArray;
+
+// src/types.ts
+var InvalidValue = class {
+};
+
+// src/option/arrayOption.ts
+var ArrayValueContainer = class {
+  val;
+  item;
+  constructor(item, val) {
+    this.val = val;
+    this.item = item;
+  }
+};
+var arrayOption_default = ArrayValueContainer;
+
+// src/fileLoader.ts
+import * as fs from "fs";
+import yaml from "js-yaml";
+import SourceMap from "js-yaml-source-map";
+import * as path from "path";
+import { parse as parseToml } from "smol-toml";
+var fileCache = /* @__PURE__ */ new Map();
+var JsonSourceMap = class {
+  locations = /* @__PURE__ */ new Map();
+  constructor(content) {
+    this.buildMap(content);
+  }
+  buildMap(content, prefix = []) {
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const keyRegex = /^(\s*)"([^"]+)"\s*:/g;
+      let match;
+      while ((match = keyRegex.exec(line)) !== null) {
+        const key = match[2];
+        const column = match[1].length + 1;
+        this.locations.set(key, {
+          line: i + 1,
+          column,
+          position: 0
+        });
+      }
+    }
+    try {
+      const data = JSON.parse(content);
+      this.walkObject(data, prefix, lines);
+    } catch {
+    }
+  }
+  walkObject(obj, prefix, lines) {
+    for (const key of Object.keys(obj)) {
+      const fullPath = [...prefix, key].join(".");
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const keyPattern = `"${key}"`;
+        const idx = line.indexOf(keyPattern);
+        if (idx !== -1) {
+          const afterKey = line.slice(idx + keyPattern.length).trim();
+          if (afterKey.startsWith(":")) {
+            this.locations.set(fullPath, {
+              line: i + 1,
+              column: idx + 1,
+              position: 0
+            });
+            break;
+          }
+        }
+      }
+      const val = obj[key];
+      if (val && typeof val === "object" && !Array.isArray(val)) {
+        this.walkObject(
+          val,
+          [...prefix, key],
+          lines
+        );
+      }
+    }
+  }
+  lookup(path2) {
+    const key = Array.isArray(path2) ? path2.join(".") : path2;
+    return this.locations.get(key);
+  }
+};
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function walkTomlObject(obj, prefix, lines, locations) {
+  for (const key of Object.keys(obj)) {
+    const fullPath = [...prefix, key].join(".");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const keyPattern = new RegExp(`^\\s*${escapeRegex(key)}\\s*=`);
+      if (keyPattern.test(line)) {
+        const idx = line.indexOf(key);
+        locations.set(fullPath, {
+          line: i + 1,
+          column: idx + 1,
+          position: 0
+        });
+        break;
+      }
+    }
+    const val = obj[key];
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      walkTomlObject(
+        val,
+        [...prefix, key],
+        lines,
+        locations
+      );
+    }
+  }
+}
+function buildTomlSourceMap(content, data) {
+  const locations = /* @__PURE__ */ new Map();
+  const lines = content.split("\n");
+  walkTomlObject(data, [], lines, locations);
+  return {
+    lookup(lookupPath) {
+      const key = Array.isArray(lookupPath) ? lookupPath.join(".") : lookupPath;
+      return locations.get(key);
+    }
+  };
+}
+function loadConfigFile(filePath) {
+  const cached = fileCache.get(filePath);
+  if (cached) return cached;
+  const content = fs.readFileSync(filePath, "utf-8");
+  const ext = path.extname(filePath).toLowerCase();
+  try {
+    if (ext === ".json") {
+      const result2 = {
+        data: JSON.parse(content),
+        sourceMap: new JsonSourceMap(content)
+      };
+      fileCache.set(filePath, result2);
+      return result2;
+    }
+    if (ext === ".toml") {
+      const data2 = parseToml(content);
+      const result2 = {
+        data: data2,
+        sourceMap: buildTomlSourceMap(content, data2)
+      };
+      fileCache.set(filePath, result2);
+      return result2;
+    }
+    const sourceMap = new SourceMap();
+    const data = yaml.load(content, { listener: sourceMap.listen() });
+    const result = { data, sourceMap };
+    fileCache.set(filePath, result);
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown parsing error";
+    throw new ConfigFileError(
+      `Failed to parse config file '${filePath}': ${message}`
+    );
+  }
+}
+function clearFileCache() {
+  fileCache.clear();
+}
+
+// src/utils.ts
+function valueIsInvalid(val) {
+  return val instanceof InvalidValue || val === null || val === void 0;
+}
+
+// src/option/base.ts
+function valueToString(val) {
+  if (typeof val === "object" && val !== null) {
+    return JSON.stringify(val);
+  }
+  return String(val);
+}
+function lookupLocation(sourceMap, path2) {
+  if (!sourceMap) return null;
+  const loc = sourceMap.lookup(path2.map(String));
+  if (!loc) return null;
+  return { line: loc.line, column: loc.column };
+}
+function findEnvFileSource(envKey, currentValue, envFileResults) {
+  if (!envFileResults) return null;
+  for (let i = envFileResults.length - 1; i >= 0; i--) {
+    const result = envFileResults[i];
+    const entry = result.entries.get(envKey);
+    if (entry && entry.value === currentValue) {
+      return {
+        filePath: result.filePath,
+        line: entry.line,
+        column: entry.column
+      };
+    }
+  }
+  return null;
+}
+function checkNumberType(val, pathStr, sourceOfVal, errors) {
+  if (typeof val === "string") {
+    const parseVal = parseInt(val, 10);
+    if (Number.isNaN(parseVal)) {
+      errors?.errors.push({
+        message: `Cannot convert value '${val}' for '${pathStr}' to number in ${sourceOfVal}.`,
+        path: pathStr,
+        source: sourceOfVal,
+        kind: "type_conversion"
+      });
+      return new InvalidValue();
+    }
+    errors?.warnings.push(
+      `The option ${pathStr} is stated as a number but is provided as a string`
+    );
+    return parseVal;
+  }
+  errors?.errors.push({
+    message: `Invalid state. Invalid kind in ${sourceOfVal}`,
+    source: sourceOfVal,
+    kind: "invalid_state"
+  });
+  return new InvalidValue();
+}
+function formatFileLocation(file, loc) {
+  if (!loc) return file;
+  return `${file}:${loc.line}:${loc.column}`;
+}
+var OptionBase = class {
+  params;
+  constructor(params) {
+    this.params = params;
+  }
+  getValue(sourceFile, env, args, path2, defaultValues, objectFromArray, envFileResults, errors) {
+    const resolved = this.resolveValue(
+      sourceFile,
+      env,
+      args,
+      path2,
+      defaultValues,
+      objectFromArray,
+      envFileResults,
+      errors
+    );
+    if (resolved && this.params.sensitive) {
+      resolved.sensitive = true;
+    }
+    if (resolved && this.params.oneOf) {
+      const passed = this.runOneOfCheck(resolved, path2, errors);
+      if (!passed) return resolved;
+    }
+    if (resolved && this.params.validate) {
+      this.runValidation(resolved, path2, errors);
+    }
+    return resolved;
+  }
+  resolveValue(sourceFile, env, args, path2, defaultValues, objectFromArray, envFileResults, errors) {
+    const ident = path2.join(".");
+    if (this.params.cli && args) {
+      if (ident in args) {
+        return new configNode_default(
+          this.checkType(args[ident], path2, `CLI argument --${ident}`, errors),
+          ident,
+          "args",
+          null,
+          null,
+          ident
+        );
+      }
+    }
+    if (this.params.env && env) {
+      if (this.params.env in env) {
+        const val = env[this.params.env];
+        if (val !== void 0) {
+          const envFileSource = findEnvFileSource(
+            this.params.env,
+            val,
+            envFileResults
+          );
+          if (envFileSource) {
+            return new configNode_default(
+              this.checkType(
+                val,
+                path2,
+                `env file ${envFileSource.filePath} (${this.params.env})`,
+                errors
+              ),
+              ident,
+              "envFile",
+              envFileSource.filePath,
+              this.params.env,
+              null,
+              envFileSource.line,
+              envFileSource.column
+            );
+          }
+          return new configNode_default(
+            this.checkType(
+              val,
+              path2,
+              `environment variable ${this.params.env}`,
+              errors
+            ),
+            ident,
+            "env",
+            null,
+            this.params.env,
+            null
+          );
+        }
+      }
+    }
+    if (typeof sourceFile === "string") {
+      const { data, sourceMap } = loadConfigFile(sourceFile);
+      const node = this.resolveFromFileData(
+        data || {},
+        sourceFile,
+        sourceMap,
+        path2,
+        ident,
+        errors
+      );
+      if (node) return node;
+    }
+    if (Array.isArray(sourceFile)) {
+      for (let index = 0; index < sourceFile.length; index += 1) {
+        const file = sourceFile[index];
+        const { data, sourceMap } = loadConfigFile(file);
+        const node = this.resolveFromFileData(
+          data || {},
+          file,
+          sourceMap,
+          path2,
+          ident,
+          errors
+        );
+        if (node) return node;
+      }
+    }
+    if (objectFromArray) {
+      const node = this.resolveFromFileData(
+        objectFromArray.value,
+        objectFromArray.file,
+        objectFromArray.sourceMap ?? null,
+        path2,
+        ident,
+        errors
+      );
+      if (node) return node;
+    }
+    if (defaultValues) {
+      const val = this.findInObject(
+        defaultValues,
+        path2,
+        errors
+      );
+      if (val instanceof arrayOption_default) {
+        return new configNode_default(
+          this.checkType(val, path2, "default", errors),
+          ident,
+          "default",
+          null,
+          null,
+          null
+        );
+      }
+      if (!valueIsInvalid(val)) {
+        return new configNode_default(
+          this.checkType(val, path2, "default", errors),
+          ident,
+          "default",
+          null,
+          null,
+          null
+        );
+      }
+    }
+    if (this.params.defaultValue !== void 0) {
+      let defaultValue;
+      const rawDefault = this.params.defaultValue;
+      if (typeof rawDefault === "function") {
+        defaultValue = rawDefault();
+      } else {
+        defaultValue = rawDefault;
+      }
+      if (this.params.kind === "array" && Array.isArray(defaultValue)) {
+        defaultValue = this.buildArrayOption(defaultValue, errors);
+      }
+      if (!valueIsInvalid(defaultValue)) {
+        return new configNode_default(
+          this.checkType(defaultValue, path2, "default", errors),
+          ident,
+          "default",
+          null,
+          null,
+          null
+        );
+      }
+    }
+    if (this.params.required) {
+      const hints = [];
+      if (this.params.env)
+        hints.push(`environment variable ${this.params.env}`);
+      if (this.params.cli) hints.push(`CLI argument --${ident}`);
+      hints.push(`config file key: ${ident}`);
+      const hint = hints.join(", ");
+      errors?.errors.push({
+        message: `Required option '${ident}' is missing. Set it via ${hint}.`,
+        path: ident,
+        kind: "required"
+      });
+    }
+    return null;
+  }
+  runOneOfCheck(node, path2, errors) {
+    const allowed = this.params.oneOf;
+    if (!allowed) return true;
+    const value = node.value;
+    if (valueIsInvalid(value)) return true;
+    if (!allowed.includes(value)) {
+      const ident = path2.join(".");
+      const source = node.file ?? node.variableName ?? node.argName ?? node.sourceType;
+      const allowedStr = allowed.map((v) => `'${String(v)}'`).join(", ");
+      errors?.errors.push({
+        message: `Value '${typeof value === "object" ? JSON.stringify(value) : String(value)}' for '${ident}' is not one of: ${allowedStr}.`,
+        path: ident,
+        source,
+        kind: "validation",
+        line: node.line ?? void 0,
+        column: node.column ?? void 0
+      });
+      return false;
+    }
+    return true;
+  }
+  runValidation(node, path2, errors) {
+    const validator = this.params.validate;
+    if (!validator) return;
+    const value = node.value;
+    if (valueIsInvalid(value)) return;
+    const result = validator["~standard"].validate(value);
+    if (result instanceof Promise) {
+      throw new Error(
+        "Async validators are not supported. The validate function must return a synchronous result."
+      );
+    }
+    if ("issues" in result && result.issues) {
+      const ident = path2.join(".");
+      const source = node.file ?? node.variableName ?? node.argName ?? node.sourceType;
+      for (const issue of result.issues) {
+        const sourceLabel = source !== node.sourceType ? ` (source: ${source})` : "";
+        errors?.errors.push({
+          message: `Validation failed for '${ident}'${sourceLabel}: ${issue.message}`,
+          path: ident,
+          source,
+          kind: "validation",
+          line: node.line ?? void 0,
+          column: node.column ?? void 0
+        });
+      }
+    }
+  }
+  resolveFromFileData(data, file, sourceMap, path2, ident, errors) {
+    const val = this.findInObject(data, path2, errors);
+    const loc = lookupLocation(sourceMap, path2);
+    if (val instanceof arrayOption_default || !valueIsInvalid(val)) {
+      return new configNode_default(
+        this.checkType(val, path2, formatFileLocation(file, loc), errors),
+        ident,
+        "file",
+        file,
+        null,
+        null,
+        loc?.line ?? null,
+        loc?.column ?? null
+      );
+    }
+    return null;
+  }
+  checkType(val, path2, sourceOfVal, errors) {
+    const ident = path2.join(".");
+    if (valueIsInvalid(val)) {
+      errors?.errors.push({
+        message: `Invalid state. Invalid kind in ${sourceOfVal}`,
+        source: sourceOfVal,
+        kind: "invalid_state"
+      });
+      return val;
+    }
+    if (typeof val === this.params.kind) {
+      return val;
+    }
+    if (this.params.kind === "string") {
+      if (typeof val === "number") {
+        errors?.warnings.push(
+          `The option ${ident} is stated as a string but is provided as a number`
+        );
+        return val.toString();
+      }
+      if (typeof val === "boolean") {
+        errors?.warnings.push(
+          `The option ${ident} is stated as a string but is provided as a boolean`
+        );
+        return val.toString();
+      }
+      errors?.errors.push({
+        message: `Cannot convert value '${valueToString(
+          val
+        )}' for '${ident}' to string in ${sourceOfVal}.`,
+        path: ident,
+        source: sourceOfVal,
+        kind: "type_conversion"
+      });
+      return new InvalidValue();
+    }
+    if (this.params.kind === "boolean") {
+      if (typeof val !== "boolean" && typeof val !== "object") {
+        const normalized = typeof val === "string" ? val.toLowerCase() : val;
+        if ([1, "1", "true", "yes"].includes(normalized)) {
+          return true;
+        }
+        if ([0, "0", "false", "no"].includes(normalized)) {
+          return false;
+        }
+      }
+      errors?.errors.push({
+        message: `Cannot convert value '${valueToString(
+          val
+        )}' for '${ident}' to boolean in ${sourceOfVal}.`,
+        path: ident,
+        source: sourceOfVal,
+        kind: "type_conversion"
+      });
+      return new InvalidValue();
+    }
+    if (this.params.kind === "number") {
+      return checkNumberType(val, ident, sourceOfVal, errors);
+    }
+    errors?.errors.push({
+      message: `Invalid state. Invalid kind in ${sourceOfVal}`,
+      source: sourceOfVal,
+      kind: "invalid_state"
+    });
+    throw new Error(
+      "Invalid kind. Must be 'string', 'number', 'boolean' or 'array'"
+    );
+  }
+  findInObject(obj, path2, errors) {
+    if (path2.length > 1) {
+      const [child, ...rest] = path2;
+      const val = obj[child];
+      if (typeof val === "string") {
+        errors?.errors.push({
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found a string '${val}'`,
+          kind: "invalid_path"
+        });
+        return new InvalidValue();
+      }
+      if (typeof val === "number") {
+        errors?.errors.push({
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found a number '${val}'`,
+          kind: "invalid_path"
+        });
+        return new InvalidValue();
+      }
+      if (typeof val === "boolean") {
+        errors?.errors.push({
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found a boolean '${val.toString()}'`,
+          kind: "invalid_path"
+        });
+        return new InvalidValue();
+      }
+      if (Array.isArray(val)) {
+        errors?.errors.push({
+          message: `Cannot traverse into '${path2.join(".")}': expected an object but found an array '${valueToString(val)}'`,
+          kind: "invalid_path"
+        });
+        return new InvalidValue();
+      }
+      if (val === void 0) {
+        return new InvalidValue();
+      }
+      if (val === null) {
+        errors?.errors.push({
+          message: `Option '${path2.join(".")}' is null \u2014 expected an object to traverse into`,
+          kind: "null_value"
+        });
+        return new InvalidValue();
+      }
+      return this.findInObject(val, rest, errors);
+    }
+    if (path2.length === 1) {
+      const val = obj[path2[0]];
+      if (val === null) {
+        if (this.params.required) {
+          errors?.errors.push({
+            message: `Option '${path2.join(".")}' is null \u2014 expected a ${this.params.kind}`,
+            kind: "null_value"
+          });
+        } else {
+          errors?.warnings.push(
+            `Option '${path2.join(".")}' is null and will be treated as unset`
+          );
+        }
+        return new InvalidValue();
+      }
+      if (!Array.isArray(val) && typeof val === "object" && val || typeof val === "string" || typeof val === "number" || typeof val === "boolean" || typeof val === "undefined") {
+        return val;
+      }
+      if (Array.isArray(val)) {
+        return this.buildArrayOption(val, errors);
+      }
+      errors?.errors.push({
+        message: `Invalid path '${path2.join(".")}': ${typeof val}`,
+        kind: "invalid_path"
+      });
+      return new InvalidValue();
+    }
+    errors?.errors.push({
+      message: `Invalid path '${path2.join()}'`,
+      kind: "invalid_path"
+    });
+    return new InvalidValue();
+  }
+  // eslint-disable-next-line class-methods-use-this
+  buildArrayOption(_val, _errors) {
+    return new InvalidValue();
+  }
+};
+
+// src/option/object.ts
+var ObjectOption = class extends OptionBase {
+  item;
+  constructor(params) {
+    if (!params.item) {
+      const hasOptionValues = Object.values(params).some(
+        (v) => v instanceof OptionBase
+      );
+      if (hasOptionValues) {
+        throw new Error(
+          "Invalid c.object() call: schema fields were passed directly instead of wrapped in { item: { ... } }. Use c.object({ item: { host: c.string() } }) instead of c.object({ host: c.string() })."
+        );
+      }
+      throw new Error(
+        "Invalid c.object() call: missing required 'item' property. Use c.object({ item: { host: c.string(), port: c.number() } })."
+      );
+    }
+    super({
+      kind: "object",
+      env: null,
+      cli: false,
+      help: "",
+      ...params
+    });
+    this.item = params.item;
+  }
+};
+
+// src/option/array.ts
+var ArrayOption = class extends OptionBase {
+  item;
+  constructor(params) {
+    super({
+      kind: "array",
+      env: null,
+      cli: false,
+      help: "",
+      ...params
+    });
+    this.item = params.item;
+  }
+  buildArrayOption(val, errors) {
+    if (this.item === null) {
+      errors?.errors.push({
+        message: `Array item cannot be null`,
+        kind: "invalid_state"
+      });
+      return new InvalidValue();
+    }
+    return new arrayOption_default(this.item, val);
+  }
+  checkType(val, path2, sourceOfVal, errors) {
+    if (val instanceof arrayOption_default) {
+      val.val.forEach((v, i) => {
+        if (this.item instanceof OptionBase && !(this.item instanceof ObjectOption)) {
+          this.item.checkType(v, [...path2, i], sourceOfVal, errors);
+        }
+      });
+      return val;
+    }
+    errors?.errors.push({
+      message: `Invalid state. Invalid kind in ${sourceOfVal}`,
+      source: sourceOfVal,
+      kind: "invalid_state"
+    });
+    return new InvalidValue();
+  }
+};
+
+// src/envFileLoader.ts
+import * as fs2 from "fs";
+var envFileCache = /* @__PURE__ */ new Map();
+function loadEnvFile(filePath) {
+  const cached = envFileCache.get(filePath);
+  if (cached) return cached;
+  const content = fs2.readFileSync(filePath, "utf-8");
+  const entries = /* @__PURE__ */ new Map();
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    if (key === "") continue;
+    let value = trimmed.slice(eqIndex + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    const column = raw.indexOf(key) + 1;
+    entries.set(key, {
+      value,
+      line: i + 1,
+      column
+    });
+  }
+  const result = { entries, filePath };
+  envFileCache.set(filePath, result);
+  return result;
+}
+function clearEnvFileCache() {
+  envFileCache.clear();
+}
+
+// src/option/errors.ts
+var OptionErrors = class {
+  errors = [];
+  warnings = [];
+  clearAll() {
+    this.errors = [];
+    this.warnings = [];
+    clearFileCache();
+    clearEnvFileCache();
+  }
+};
+
+// src/option/primitive.ts
+var PrimitiveOption = class extends OptionBase {
+};
+
+// src/sourceValidation.ts
+import * as fs3 from "fs";
+function validateFiles(files, dir) {
+  if (files && dir)
+    throw new ConfigFileError("Dir and files are specified, choose one");
+  let sourceFile = [];
+  if (files) {
+    if (Array.isArray(files)) {
+      const result = [];
+      files.forEach((file) => {
+        if (!fs3.existsSync(file)) {
+          throw new ConfigFileError(`Config file '${file}' does not exist`);
+        } else {
+          result.push(file);
+        }
+      });
+      sourceFile = result;
+    } else {
+      if (!fs3.existsSync(files)) {
+        throw new ConfigFileError(`Config file '${files}' does not exist`);
+      }
+      sourceFile = files;
+    }
+  }
+  if (dir) {
+    if (!(fs3.existsSync(dir) && fs3.lstatSync(dir).isDirectory())) {
+      throw new ConfigFileError(
+        `Config directory '${dir}' does not exist or is not a directory`
+      );
+    }
+    const filesInDirectory = fs3.readdirSync(dir).sort();
+    if (filesInDirectory.length === 0) {
+      throw new ConfigFileError(`Directory '${dir}' is empty`);
+    }
+    const result = [];
+    filesInDirectory.forEach((file) => {
+      result.push(`${dir}/${file}`);
+    });
+    sourceFile = result;
+  }
+  return sourceFile;
+}
+function loadEnvFiles(envFile, envData) {
+  const envFileResults = [];
+  if (!envFile) return { envFileResults, mergedEnvData: envData };
+  const envFiles = Array.isArray(envFile) ? envFile : [envFile];
+  for (const file of envFiles) {
+    if (!fs3.existsSync(file)) {
+      throw new ConfigFileError(`Invalid env file '${file}'`);
+    }
+    const result = loadEnvFile(file);
+    envFileResults.push(result);
+  }
+  const merged = {};
+  for (const result of envFileResults) {
+    for (const [key, entry] of result.entries) {
+      merged[key] = entry.value;
+    }
+  }
+  for (const [key, value] of Object.entries(envData)) {
+    if (value !== void 0) {
+      merged[key] = value;
+    }
+  }
+  return { envFileResults, mergedEnvData: merged };
+}
+
+// src/settings.ts
+var Settings = class {
+  schema;
+  sources;
+  errors = new OptionErrors();
+  sourceFile = [];
+  argsData = {};
+  envData = {};
+  optionsTree = {};
+  defaultData = {};
+  envFileResults = [];
+  program;
+  constructor(schema2, sources) {
+    this.schema = schema2;
+    this.sources = sources;
+    this.program = new Command().allowUnknownOption(true).allowExcessArguments(true);
+    this.load();
+  }
+  validateAndLoadFiles() {
+    this.sourceFile = validateFiles(this.sources.files, this.sources.dir);
+  }
+  loadAndMergeEnvFiles() {
+    const { envFileResults, mergedEnvData } = loadEnvFiles(
+      this.sources.envFile,
+      this.envData
+    );
+    this.envFileResults = envFileResults;
+    this.envData = mergedEnvData;
+  }
+  checkEnvMappingsWithoutEnvLoading() {
+    if (this.sources.env || this.sources.envFile) return;
+    const envMappedOptions = [];
+    this.traverseOptions(this.schema, [], (node, path2) => {
+      if (node.params.env) {
+        envMappedOptions.push(path2.join("."));
+      }
+    });
+    if (envMappedOptions.length > 0) {
+      this.errors.warnings.push(
+        `Options [${envMappedOptions.join(", ")}] have env mappings but env loading is disabled. Set 'env: true' in load options to read from environment variables.`
+      );
+    }
+  }
+  load() {
+    this.validateAndLoadFiles();
+    this.checkEnvMappingsWithoutEnvLoading();
+    if (this.sources.env) {
+      this.envData = { ...process.env };
+    }
+    this.loadAndMergeEnvFiles();
+    if (this.sources.args) {
+      this.traverseOptions(this.schema, [], this.addArg.bind(this));
+      this.program.parse(process.argv);
+      this.argsData = this.program.opts();
+    }
+    if (this.sources.defaults) {
+      this.defaultData = this.sources.defaults;
+    }
+    this.traverseOptions(
+      this.schema,
+      [],
+      this.buildOption.bind(this, this.optionsTree, {
+        sourceFile: this.sourceFile,
+        envData: this.envData,
+        argsData: this.argsData,
+        defaultValue: this.defaultData,
+        envFileResults: this.envFileResults,
+        errors: this.errors
+      })
+    );
+    if (this.sources.strict && this.errors.warnings.length > 0) {
+      for (const warning of this.errors.warnings) {
+        this.errors.errors.push({ message: warning, kind: "strict" });
+      }
+      this.errors.warnings = [];
+    }
+    if (this.errors.errors.length > 0) {
+      throw new ConfigLoadError(
+        [...this.errors.errors],
+        [...this.errors.warnings]
+      );
+    }
+  }
+  traverseOptions(node, path2, callback) {
+    if (node instanceof ObjectOption) {
+      const item = node.item;
+      Object.keys(item).forEach((key) => {
+        this.traverseOptions(item[key], [...path2, key], callback);
+      });
+    } else if (node instanceof OptionBase) {
+      callback(node, path2);
+    } else {
+      Object.keys(node).forEach((key) => {
+        const val = node[key];
+        this.traverseOptions(val, [...path2, key], callback);
+      });
+    }
+  }
+  buildOption(result, configData, node, path2) {
+    const {
+      sourceFile = [],
+      envData = {},
+      argsData = {},
+      defaultValue = {},
+      objectFromArray,
+      envFileResults,
+      errors
+    } = configData;
+    const value = node.getValue(
+      sourceFile,
+      envData,
+      argsData,
+      path2,
+      defaultValue,
+      objectFromArray,
+      envFileResults,
+      errors
+    );
+    if (value !== null) {
+      this.setOption(result, path2, value);
+    }
+  }
+  getValidatedArray(item, values, file) {
+    if (item instanceof PrimitiveOption) {
+      if (item.params.kind === "string") {
+        return values.map((v) => v);
+      }
+      if (item.params.kind === "number") {
+        return values.map((v) => parseInt(v, 10));
+      }
+      if (item.params.kind === "boolean") {
+        return values.map((v) => {
+          if (v === "true") return true;
+          if (v === "1") return true;
+          if (v === 1) return true;
+          if (v === "false") return false;
+          if (v === "0") return false;
+          if (v === 0) return false;
+          return v;
+        });
+      }
+    }
+    const arrayValues = values.map(
+      (v) => this.processArrayWithSchema(item, v, file)
+    );
+    return new configNodeArray_default(arrayValues);
+  }
+  processArrayWithSchema(item, v, file) {
+    const result = {};
+    this.traverseOptions(
+      item,
+      [],
+      this.buildOption.bind(this, result, {
+        objectFromArray: {
+          value: v,
+          file
+        },
+        errors: this.errors
+      })
+    );
+    return result;
+  }
+  setOption(options, path2, node) {
+    if (path2.length > 1) {
+      const [child, ...rest] = path2;
+      if (!options[child]) {
+        options[child] = {};
+      }
+      this.setOption(
+        options[child],
+        rest,
+        node
+      );
+    } else if (path2.length === 1) {
+      const [child] = path2;
+      if (node != null) {
+        if (node.value instanceof arrayOption_default) {
+          options[child] = node;
+          options[child].value = this.getValidatedArray(
+            node.value.item,
+            node.value.val,
+            node.file || node.variableName || node.argName || ""
+          );
+        } else {
+          options[child] = node;
+        }
+      }
+    } else {
+      throw new Error(
+        `Invalid path '${node.path}' getting from '${node.argName || node.file || node.variableName || ""}' in ' ${node.sourceType}`
+      );
+    }
+  }
+  addArg(node, path2 = []) {
+    if (node.params.cli) {
+      const ident = path2.join(".");
+      let help = node.params.help;
+      if (node.params.oneOf) {
+        const allowed = node.params.oneOf.map(String).join(", ");
+        help = help ? `${help} (one of: ${allowed})` : `one of: ${allowed}`;
+      }
+      this.program.option(`--${ident} <value>`, help);
+    }
+  }
+  getValuesFromTree(node) {
+    if (node instanceof configNode_default) {
+      if (node.value instanceof configNodeArray_default) {
+        return node.value.arrayValues.map(this.getValuesFromTree.bind(this));
+      }
+      return node.value;
+    }
+    return Object.entries(node).reduce(
+      (acc, [key, value]) => {
+        acc[key] = this.getValuesFromTree(value);
+        return acc;
+      },
+      {}
+    );
+  }
+  get() {
+    return this.getValuesFromTree(
+      this.optionsTree
+    );
+  }
+  getExtended() {
+    return this.optionsTree;
+  }
+  getWarnings() {
+    return [...this.errors.warnings];
+  }
+};
+var settings_default = Settings;
+
+// src/watcher.ts
+import * as fs4 from "fs";
+
+// src/diffConfig.ts
+var MASK = "***";
+function collectSensitivePaths(schema2, prefix = "") {
+  const paths = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(schema2)) {
+    const opt = schema2[key];
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    if (opt instanceof PrimitiveOption && opt.params.sensitive) {
+      paths.add(fullPath);
+    }
+    if (opt instanceof ObjectOption) {
+      const childPaths = collectSensitivePaths(opt.item, fullPath);
+      for (const p of childPaths) {
+        paths.add(p);
+      }
+    }
+  }
+  return paths;
+}
+function diffObjects(oldObj, newObj, sensitivePaths, prefix = "") {
+  const changes = [];
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+  for (const key of allKeys) {
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    const isSensitive = sensitivePaths.has(fullPath);
+    const oldVal = oldObj[key];
+    const newVal = newObj[key];
+    const hasOld = key in oldObj;
+    const hasNew = key in newObj;
+    if (hasNew && !hasOld) {
+      changes.push({
+        path: fullPath,
+        type: "added",
+        oldValue: void 0,
+        newValue: isSensitive ? MASK : newVal
+      });
+    } else if (hasOld && !hasNew) {
+      changes.push({
+        path: fullPath,
+        type: "removed",
+        oldValue: isSensitive ? MASK : oldVal,
+        newValue: void 0
+      });
+    } else if (oldVal !== null && newVal !== null && typeof oldVal === "object" && typeof newVal === "object" && !Array.isArray(oldVal) && !Array.isArray(newVal)) {
+      changes.push(
+        ...diffObjects(
+          oldVal,
+          newVal,
+          sensitivePaths,
+          fullPath
+        )
+      );
+    } else if (!Object.is(oldVal, newVal)) {
+      if (Array.isArray(oldVal) && Array.isArray(newVal) && JSON.stringify(oldVal) === JSON.stringify(newVal)) {
+        continue;
+      }
+      changes.push({
+        path: fullPath,
+        type: "changed",
+        oldValue: isSensitive ? MASK : oldVal,
+        newValue: isSensitive ? MASK : newVal
+      });
+    }
+  }
+  return changes;
+}
+function diffConfig(oldConfig, newConfig, schema2) {
+  const sensitivePaths = schema2 ? collectSensitivePaths(schema2) : /* @__PURE__ */ new Set();
+  return diffObjects(oldConfig, newConfig, sensitivePaths);
+}
+
+// src/watcher.ts
+function resolveFilePaths(sources) {
+  const paths = [];
+  const configFiles = validateFiles(
+    sources.files ?? false,
+    sources.dir ?? false
+  );
+  if (Array.isArray(configFiles)) {
+    paths.push(...configFiles);
+  } else if (configFiles) {
+    paths.push(configFiles);
+  }
+  if (sources.envFile) {
+    const envFiles = Array.isArray(sources.envFile) ? sources.envFile : [sources.envFile];
+    paths.push(...envFiles);
+  }
+  return paths;
+}
+function createWatcher(schema2, sources, options) {
+  const debounceMs = options.debounce ?? 100;
+  const initialSettings = new settings_default(schema2, sources);
+  let currentConfig = initialSettings.get();
+  const filePaths = resolveFilePaths(sources);
+  const watchers = [];
+  let debounceTimer = null;
+  let closed = false;
+  function reload() {
+    if (closed) return;
+    try {
+      clearFileCache();
+      clearEnvFileCache();
+      const settings = new settings_default(schema2, sources);
+      const newConfig = settings.get();
+      const changes = diffConfig(
+        currentConfig,
+        newConfig,
+        schema2
+      );
+      if (changes.length > 0) {
+        const oldConfig = currentConfig;
+        currentConfig = newConfig;
+        options.onChange(newConfig, oldConfig, changes);
+      }
+    } catch (err) {
+      if (options.onError) {
+        options.onError(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
+  function scheduleReload() {
+    if (closed) return;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(reload, debounceMs);
+    debounceTimer.unref();
+  }
+  for (const filePath of filePaths) {
+    try {
+      const watcher = fs4.watch(filePath, () => {
+        scheduleReload();
+      });
+      watcher.unref();
+      watchers.push(watcher);
+    } catch {
+    }
+  }
+  if (sources.dir && typeof sources.dir === "string") {
+    try {
+      const dirWatcher = fs4.watch(sources.dir, () => {
+        scheduleReload();
+      });
+      dirWatcher.unref();
+      watchers.push(dirWatcher);
+    } catch {
+    }
+  }
+  function close() {
+    if (closed) return;
+    closed = true;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    for (const watcher of watchers) {
+      watcher.close();
+    }
+    watchers.length = 0;
+  }
+  return {
+    get config() {
+      return currentConfig;
+    },
+    close
+  };
+}
+
+// src/builder/settings.ts
+var SettingsBuilder = class {
+  schema;
+  constructor(schema2) {
+    this.schema = schema2;
+  }
+  /**
+   * Loads and validates configuration, returning a fully-typed plain object.
+   * @param sources - Which sources to read (env, args, files, etc.).
+   * @returns The resolved configuration object matching the schema type.
+   * @throws {ConfigLoadError} If validation fails (missing required fields, type errors, etc.).
+   */
+  load(sources) {
+    const settings = new settings_default(this.schema, sources);
+    return settings.get();
+  }
+  /**
+   * Loads configuration and returns raw node data with source metadata alongside warnings.
+   * @param sources - Which sources to read (env, args, files, etc.).
+   * @returns An `ExtendedResult` containing the node tree and any warnings.
+   * @throws {ConfigLoadError} If validation fails.
+   */
+  loadExtended(sources) {
+    const settings = new settings_default(this.schema, sources);
+    return {
+      data: settings.getExtended(),
+      warnings: settings.getWarnings()
+    };
+  }
+  /**
+   * Watches config files for changes and reloads automatically.
+   * File watchers are `.unref()`'d so they don't prevent the process from exiting.
+   * @param sources - Which sources to read (env, args, files, etc.).
+   * @param options - Callbacks and debounce configuration.
+   * @returns A `ConfigWatcher` with the current config and a `close()` method.
+   * @throws {ConfigLoadError} If the initial load fails.
+   */
+  watch(sources, options) {
+    return createWatcher(this.schema, sources, options);
+  }
+};
+
+// src/maskSecrets.ts
+var MASK2 = "***";
+function maskNodeTree(tree) {
+  const result = {};
+  for (const [key, entry] of Object.entries(tree)) {
+    if (entry instanceof configNode_default) {
+      if (entry.sensitive) {
+        const masked = new configNode_default(
+          MASK2,
+          entry.path,
+          entry.sourceType,
+          entry.file,
+          entry.variableName,
+          entry.argName,
+          entry.line,
+          entry.column,
+          entry.sensitive
+        );
+        if (entry.value instanceof configNodeArray_default) {
+          masked.value = entry.value;
+        }
+        result[key] = masked;
+      } else {
+        result[key] = entry;
+      }
+    } else {
+      result[key] = maskNodeTree(entry);
+    }
+  }
+  return result;
+}
+function maskPlainObject(obj, schema2) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const schemaNode = schema2[key];
+    if (!schemaNode) {
+      result[key] = value;
+      continue;
+    }
+    if (schemaNode instanceof ObjectOption) {
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        result[key] = maskPlainObject(
+          value,
+          schemaNode.item
+        );
+      } else {
+        result[key] = value;
+      }
+    } else if (schemaNode instanceof OptionBase) {
+      result[key] = schemaNode.params.sensitive ? MASK2 : value;
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function maskSecrets(resultOrConfig, schema2) {
+  if ("data" in resultOrConfig && "warnings" in resultOrConfig && !schema2) {
+    const extended = resultOrConfig;
+    return {
+      data: maskNodeTree(extended.data),
+      warnings: [...extended.warnings]
+    };
+  }
+  if (schema2) {
+    return maskPlainObject(resultOrConfig, schema2);
+  }
+  return resultOrConfig;
+}
+
+// src/printConfig.ts
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 3) + "...";
+}
+function formatValue(val) {
+  if (val === null || val === void 0) return "";
+  if (typeof val === "object") return JSON.stringify(val);
+  if (typeof val === "string") return val;
+  return `${val}`;
+}
+function formatDetail(node) {
+  const parts = [];
+  if (node.sourceType === "file" || node.sourceType === "envFile") {
+    if (node.file) {
+      let loc = node.file;
+      if (node.line != null) {
+        loc += `:${node.line}`;
+        if (node.column != null) loc += `:${node.column}`;
+      }
+      parts.push(loc);
+    }
+    if (node.sourceType === "envFile" && node.variableName) {
+      parts.push(`(${node.variableName})`);
+    }
+  } else if (node.sourceType === "env" && node.variableName) {
+    parts.push(node.variableName);
+  } else if (node.sourceType === "args" && node.argName) {
+    parts.push(`--${node.argName}`);
+  }
+  return parts.join(" ");
+}
+function flattenTree(tree, prefix = "") {
+  const rows = [];
+  for (const [key, entry] of Object.entries(tree)) {
+    const path2 = prefix ? `${prefix}.${key}` : key;
+    if (entry instanceof configNode_default) {
+      if (entry.value instanceof configNodeArray_default) {
+        for (let i = 0; i < entry.value.arrayValues.length; i++) {
+          const child = entry.value.arrayValues[i];
+          const arrayPath = `${path2}[${i}]`;
+          if (child.value && typeof child.value === "object" && !(child.value instanceof configNodeArray_default)) {
+            const nested = child.value;
+            rows.push(...flattenTree(nested, arrayPath));
+          } else {
+            rows.push({
+              path: arrayPath,
+              value: formatValue(child.value),
+              source: child.sourceType,
+              detail: formatDetail(child)
+            });
+          }
+        }
+      } else {
+        rows.push({
+          path: path2,
+          value: entry.sensitive ? "***" : formatValue(entry.value),
+          source: entry.sourceType,
+          detail: formatDetail(entry)
+        });
+      }
+    } else {
+      rows.push(...flattenTree(entry, path2));
+    }
+  }
+  return rows;
+}
+function padRight(str, len) {
+  return str + " ".repeat(Math.max(0, len - str.length));
+}
+function buildTable(rows) {
+  const headers = {
+    path: "Path",
+    value: "Value",
+    source: "Source",
+    detail: "Detail"
+  };
+  const widths = {
+    path: Math.max(headers.path.length, ...rows.map((r) => r.path.length)),
+    value: Math.max(headers.value.length, ...rows.map((r) => r.value.length)),
+    source: Math.max(
+      headers.source.length,
+      ...rows.map((r) => r.source.length)
+    ),
+    detail: Math.max(
+      headers.detail.length,
+      ...rows.map((r) => r.detail.length)
+    )
+  };
+  const hr = `\u251C${"\u2500".repeat(widths.path + 2)}\u253C${"\u2500".repeat(widths.value + 2)}\u253C${"\u2500".repeat(widths.source + 2)}\u253C${"\u2500".repeat(widths.detail + 2)}\u2524`;
+  const top = `\u250C${"\u2500".repeat(widths.path + 2)}\u252C${"\u2500".repeat(widths.value + 2)}\u252C${"\u2500".repeat(widths.source + 2)}\u252C${"\u2500".repeat(widths.detail + 2)}\u2510`;
+  const bottom = `\u2514${"\u2500".repeat(widths.path + 2)}\u2534${"\u2500".repeat(widths.value + 2)}\u2534${"\u2500".repeat(widths.source + 2)}\u2534${"\u2500".repeat(widths.detail + 2)}\u2518`;
+  const formatRow = (r) => `\u2502 ${padRight(r.path, widths.path)} \u2502 ${padRight(r.value, widths.value)} \u2502 ${padRight(r.source, widths.source)} \u2502 ${padRight(r.detail, widths.detail)} \u2502`;
+  const lines = [top, formatRow(headers), hr, ...rows.map(formatRow), bottom];
+  return lines.join("\n");
+}
+function printConfig(result, options) {
+  const maxLen = options?.maxValueLength ?? 50;
+  const rows = flattenTree(result.data).map((r) => ({
+    ...r,
+    value: truncate(r.value, maxLen)
+  }));
+  let output;
+  if (rows.length === 0) {
+    output = "No configuration values loaded.";
+  } else {
+    output = buildTable(rows);
+  }
+  if (result.warnings.length > 0) {
+    output += "\n\nWarnings:";
+    for (const w of result.warnings) {
+      output += `
+  - ${w}`;
+    }
+  }
+  if (!options?.silent) {
+    console.log(output);
+  }
+  return output;
+}
+
+// src/index.ts
+var DEFAULTS = {
+  required: false,
+  env: null,
+  cli: false,
+  help: ""
+};
+function string(opts) {
+  return new PrimitiveOption({
+    kind: "string",
+    ...DEFAULTS,
+    ...opts
+  });
+}
+function number(opts) {
+  return new PrimitiveOption({
+    kind: "number",
+    ...DEFAULTS,
+    ...opts
+  });
+}
+function bool(opts) {
+  return new PrimitiveOption({
+    kind: "boolean",
+    ...DEFAULTS,
+    ...opts
+  });
+}
+var array = (opts) => {
+  return new ArrayOption({
+    ...DEFAULTS,
+    ...opts
+  });
+};
+var object = (opts) => {
+  return new ObjectOption({
+    required: false,
+    ...opts
+  });
+};
+var schema = (theSchema) => {
+  return new SettingsBuilder(theSchema);
+};
+var option = {
+  string,
+  number,
+  bool,
+  array,
+  object,
+  schema
+};
+var index_default = option;
+export {
+  ConfigFileError,
+  ConfigLoadError,
+  configNode_default as ConfigNode,
+  configNodeArray_default as ConfigNodeArray,
+  index_default as default,
+  diffConfig,
+  maskSecrets,
+  printConfig
+};