@o3co/ts.hocon 0.1.5 → 1.0.0

package/dist/index.cjs

@@ -54,6 +54,130 @@ function coerceNumber(value) {
   if (!/^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return void 0;
   return Number(value);
 }
+var DURATION_UNITS = {
+  ns: 1e-6,
+  nanosecond: 1e-6,
+  nanoseconds: 1e-6,
+  us: 1e-3,
+  microsecond: 1e-3,
+  microseconds: 1e-3,
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1e3,
+  second: 1e3,
+  seconds: 1e3,
+  m: 6e4,
+  minute: 6e4,
+  minutes: 6e4,
+  h: 36e5,
+  hour: 36e5,
+  hours: 36e5,
+  d: 864e5,
+  day: 864e5,
+  days: 864e5
+};
+var OUTPUT_DURATION_UNITS = {
+  ns: 1e-6,
+  us: 1e-3,
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+function parseDuration(value, outputUnit = "ms") {
+  const trimmed = value.trim();
+  let i = 0;
+  while (i < trimmed.length) {
+    const ch = trimmed[i];
+    if (ch !== "-" && ch !== "." && (ch < "0" || ch > "9")) break;
+    i++;
+  }
+  if (i === 0) return NaN;
+  const num = Number(trimmed.slice(0, i));
+  if (Number.isNaN(num)) return NaN;
+  const unit = trimmed.slice(i).trim().toLowerCase();
+  const mult = DURATION_UNITS[unit];
+  if (mult === void 0) return NaN;
+  const ms = num * mult;
+  const divisor = OUTPUT_DURATION_UNITS[outputUnit];
+  if (divisor === void 0) return NaN;
+  return ms / divisor;
+}
+var BYTE_UNITS = {
+  B: 1,
+  byte: 1,
+  bytes: 1,
+  KB: 1e3,
+  kilobyte: 1e3,
+  kilobytes: 1e3,
+  KiB: 1024,
+  kibibyte: 1024,
+  kibibytes: 1024,
+  MB: 1e6,
+  megabyte: 1e6,
+  megabytes: 1e6,
+  MiB: 1048576,
+  mebibyte: 1048576,
+  mebibytes: 1048576,
+  GB: 1e9,
+  gigabyte: 1e9,
+  gigabytes: 1e9,
+  GiB: 1073741824,
+  gibibyte: 1073741824,
+  gibibytes: 1073741824,
+  TB: 1e12,
+  terabyte: 1e12,
+  terabytes: 1e12,
+  TiB: 1099511627776,
+  tebibyte: 1099511627776,
+  tebibytes: 1099511627776,
+  // lowercase short-form aliases
+  b: 1,
+  kb: 1e3,
+  kib: 1024,
+  mb: 1e6,
+  mib: 1048576,
+  gb: 1e9,
+  gib: 1073741824,
+  tb: 1e12,
+  tib: 1099511627776
+};
+var OUTPUT_BYTE_UNITS = {
+  B: 1,
+  KB: 1e3,
+  KiB: 1024,
+  MB: 1e6,
+  MiB: 1048576,
+  GB: 1e9,
+  GiB: 1073741824,
+  TB: 1e12,
+  TiB: 1099511627776
+};
+function parseBytes(value, outputUnit = "B") {
+  const trimmed = value.trim();
+  let i = 0;
+  while (i < trimmed.length) {
+    const ch = trimmed[i];
+    if (ch !== "-" && ch !== "." && (ch < "0" || ch > "9")) break;
+    i++;
+  }
+  if (i === 0) return NaN;
+  const num = Number(trimmed.slice(0, i));
+  if (Number.isNaN(num)) return NaN;
+  const unit = trimmed.slice(i).trim();
+  let mult = BYTE_UNITS[unit];
+  if (mult === void 0) {
+    mult = BYTE_UNITS[unit.toLowerCase()];
+  }
+  if (mult === void 0) return NaN;
+  const bytes = num * mult;
+  const divisor = OUTPUT_BYTE_UNITS[outputUnit];
+  if (divisor === void 0) return NaN;
+  const result = bytes / divisor;
+  return outputUnit === "B" ? Math.round(result) : result;
+}
 
 // src/errors.ts
 var ParseError = class extends Error {
@@ -116,6 +240,20 @@ var Config = class _Config {
     }
     throw new ConfigError(`expected boolean at ${path2}, got ${typeof v}`, path2);
   }
+  getDuration(path2, unit) {
+    const v = this.requireScalar(path2);
+    if (typeof v !== "string") throw new ConfigError(`expected duration string at ${path2}, got ${typeof v}`, path2);
+    const result = parseDuration(v, unit);
+    if (Number.isNaN(result)) throw new ConfigError(`invalid duration at ${path2}: ${JSON.stringify(v)}`, path2);
+    return result;
+  }
+  getBytes(path2, unit) {
+    const v = this.requireScalar(path2);
+    if (typeof v !== "string") throw new ConfigError(`expected byte size string at ${path2}, got ${typeof v}`, path2);
+    const result = parseBytes(v, unit);
+    if (Number.isNaN(result)) throw new ConfigError(`invalid byte size at ${path2}: ${JSON.stringify(v)}`, path2);
+    return result;
+  }
   getConfig(path2) {
     const v = this.lookupNode(path2);
     if (v === void 0) throw new ConfigError(`path not found: ${path2}`, path2);
@@ -142,7 +280,7 @@ var Config = class _Config {
     return hoconToJs(this.root);
   }
   lookupNode(path2) {
-    const segments = path2.split(".");
+    const segments = splitConfigPath(path2);
     let current = this.root;
     for (const seg of segments) {
       if (current.kind !== "object") return void 0;
@@ -159,6 +297,45 @@ var Config = class _Config {
     return v.value;
   }
 };
+function splitConfigPath(path2) {
+  const segments = [];
+  let i = 0;
+  while (i < path2.length) {
+    if (path2[i] === '"') {
+      i++;
+      let segment = "";
+      let closed = false;
+      while (i < path2.length) {
+        const ch = path2[i];
+        if (ch === "\\" && i + 1 < path2.length) {
+          const next = path2[i + 1];
+          segment += next;
+          i += 2;
+          continue;
+        }
+        if (ch === '"') {
+          closed = true;
+          i++;
+          break;
+        }
+        segment += ch;
+        i++;
+      }
+      if (!closed) throw new ConfigError(`unterminated quoted path segment: ${path2}`, path2);
+      segments.push(segment);
+      if (i < path2.length && path2[i] === ".") i++;
+    } else {
+      const dot = path2.indexOf(".", i);
+      if (dot === -1) {
+        segments.push(path2.slice(i));
+        break;
+      }
+      segments.push(path2.slice(i, dot));
+      i = dot + 1;
+    }
+  }
+  return segments;
+}
 function hoconToJs(v) {
   switch (v.kind) {
     case "scalar":
@@ -272,6 +449,7 @@ function tokenize(input) {
       advance();
       advance();
       let value = "";
+      let closed = false;
       while (pos < input.length) {
         if (peek() === '"') {
           let quoteCount = 0;
@@ -281,6 +459,7 @@ function tokenize(input) {
           }
           if (quoteCount >= 3) {
             for (let i = 0; i < quoteCount - 3; i++) value += '"';
+            closed = true;
             break;
           }
           for (let i = 0; i < quoteCount; i++) value += '"';
@@ -288,6 +467,9 @@ function tokenize(input) {
         }
         value += advance();
       }
+      if (!closed) {
+        throw new ParseError("unterminated triple-quoted string", sl, sc);
+      }
       if (value.startsWith("\n")) value = value.slice(1);
       push("triple_string", value, sl, sc, true);
       continue;
@@ -326,13 +508,19 @@ function tokenize(input) {
               value += "\f";
               break;
             case "u": {
+              if (pos + 4 > input.length) {
+                throw new ParseError("Invalid unicode escape: not enough characters", line, col);
+              }
               const hex = input.slice(pos, pos + 4);
+              if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                throw new ParseError(`Invalid unicode escape: \\u${hex}`, line, col);
+              }
               value += String.fromCharCode(parseInt(hex, 16));
               for (let i = 0; i < 4; i++) advance();
               break;
             }
             default:
-              value += esc;
+              throw new ParseError(`Unknown escape sequence: \\${esc}`, line, col);
           }
         } else {
           value += advance();
@@ -357,10 +545,10 @@ function tokenize(input) {
   return tokens;
 }
 function isUnquotedStart(ch) {
-  return ch !== "" && !'{}[],:=+#\n\r	 "$'.includes(ch);
+  return ch !== "" && !'{}[],:=+#\n\r	 "$?!@*&^\\'.includes(ch);
 }
 function isUnquotedContinue(ch, nextFn) {
-  if (ch === "" || '{}[],:=\n\r	 #"$'.includes(ch) || ch === " ") return false;
+  if (ch === "" || '{}[],:=\n\r	 #"$?!@*&^\\'.includes(ch) || ch === " ") return false;
   if (ch === "+" && nextFn() === "=") return false;
   if (ch === "/" && nextFn() === "/") return false;
   return true;
@@ -462,20 +650,46 @@ function parseTokens(tokens) {
     skip("newline");
     const t2 = peek();
     let path2;
-    if (t2.kind === "string") {
+    let required = false;
+    if (t2.kind === "unquoted" && (t2.value === "required(" || t2.value === "required" || t2.value.startsWith("required("))) {
+      if (t2.value === "required") {
+        const next2 = tokens[pos + 1] ?? { kind: "eof", value: "" };
+        if (next2.kind !== "unquoted" || !next2.value.startsWith("(")) {
+          throw new ParseError("include required must be followed by (", t2.line, t2.col);
+        }
+      }
+      required = true;
+      advance();
+      const innerPrefix = t2.value.startsWith("required(") ? t2.value.slice("required(".length) : "";
+      if (innerPrefix.startsWith("url") || innerPrefix.startsWith("classpath")) {
+        throw new ParseError("include url(...) and classpath(...) are not supported", t2.line, t2.col);
+      }
+      const next = peek();
+      if (next.kind === "unquoted" && (next.value === "url" || next.value.startsWith("url(") || next.value === "classpath" || next.value.startsWith("classpath("))) {
+        throw new ParseError("include url(...) and classpath(...) are not supported", next.line, next.col);
+      }
+      while (peek().kind !== "string" && peek().kind !== "eof") advance();
+      if (peek().kind === "eof") throw new ParseError("expected include path", t2.line, t2.col);
+      path2 = advance().value;
+      while (peek().kind !== "newline" && peek().kind !== "rbrace" && peek().kind !== "eof" && peek().kind !== "comma") advance();
+    } else if (t2.kind === "string") {
       path2 = advance().value;
     } else if (t2.kind === "unquoted" && (t2.value === "file(" || t2.value === "file")) {
       advance();
       while (peek().kind !== "string" && peek().kind !== "eof") advance();
       if (peek().kind === "eof") throw new ParseError("expected include path", t2.line, t2.col);
       path2 = advance().value;
-      while (peek().kind !== "newline" && peek().kind !== "rbrace" && peek().kind !== "eof") advance();
+      while (peek().kind !== "newline" && peek().kind !== "rbrace" && peek().kind !== "eof" && peek().kind !== "comma") advance();
+    } else if (t2.kind === "unquoted" && (t2.value === "url" || t2.value.startsWith("url("))) {
+      throw new ParseError("include url(...) is not supported", t2.line, t2.col);
+    } else if (t2.kind === "unquoted" && (t2.value === "classpath" || t2.value.startsWith("classpath("))) {
+      throw new ParseError("include classpath(...) is not supported", t2.line, t2.col);
     } else {
       throw new ParseError(`expected include path, got ${t2.kind}`, t2.line, t2.col);
     }
     return {
       key: [],
-      value: { kind: "include", path: path2, pos: p },
+      value: { kind: "include", path: path2, required, pos: p },
       append: false,
       pos: p
     };
@@ -510,7 +724,7 @@ function parseTokens(tokens) {
         break;
       }
       if (hadSpace) {
-        parts.push({ kind: "scalar", value: " ", pos: { line: t2.line, col: t2.col } });
+        parts.push({ kind: "scalar", value: " ", pos: { line: t2.line, col: t2.col }, _separator: true });
       }
       parts.push(node);
     }
@@ -546,13 +760,88 @@ function parseTokens(tokens) {
   const t = peek();
   if (t.kind === "lbrace") {
     advance();
-    return parseObject(true);
+    const first = parseObject(true);
+    const allFields = first.kind === "object" ? [...first.fields] : [];
+    while (true) {
+      skip("newline");
+      if (peek().kind === "eof") break;
+      if (peek().kind === "lbrace") {
+        advance();
+        const extra = parseObject(true);
+        if (extra.kind === "object") allFields.push(...extra.fields);
+      } else {
+        const rest = parseObject(false);
+        if (rest.kind === "object") allFields.push(...rest.fields);
+        break;
+      }
+    }
+    skip("newline");
+    const remaining = peek();
+    if (remaining.kind !== "eof") {
+      throw new ParseError(`Unexpected token '${remaining.value}' after closing brace`, remaining.line, remaining.col);
+    }
+    return { kind: "object", fields: allFields, pos: first.pos };
   }
   return parseObject(false);
 }
 
 // src/internal/resolver/resolver.ts
 var nodePath = __toESM(require("path"), 1);
+
+// src/internal/properties/properties.ts
+function parseProperties(input) {
+  const root = /* @__PURE__ */ Object.create(null);
+  for (const line of input.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("!")) continue;
+    const sepIdx = findSeparator(trimmed);
+    if (sepIdx === -1) continue;
+    const key = trimmed.slice(0, sepIdx).trim();
+    const value = trimmed.slice(sepIdx + 1).trim();
+    if (key === "") continue;
+    setNested(root, key.split("."), value);
+  }
+  return root;
+}
+function findSeparator(line) {
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === "=" || line[i] === ":") return i;
+  }
+  return -1;
+}
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function setNested(obj, segments, value) {
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (seg === void 0 || DANGEROUS_KEYS.has(seg)) return;
+    if (!(seg in current) || typeof current[seg] !== "object" || current[seg] === null) {
+      current[seg] = /* @__PURE__ */ Object.create(null);
+    }
+    current = current[seg];
+  }
+  const last = segments[segments.length - 1];
+  if (last === void 0 || DANGEROUS_KEYS.has(last)) return;
+  current[last] = value;
+}
+function propertiesToHoconValue(input) {
+  const parsed = parseProperties(input);
+  return recordToHoconValue(parsed);
+}
+function recordToHoconValue(obj) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const [key, val] of Object.entries(obj)) {
+    if (typeof val === "string") {
+      fields.set(key, { kind: "scalar", value: val });
+    } else if (val !== null && typeof val === "object") {
+      fields.set(key, recordToHoconValue(val));
+    }
+  }
+  return { kind: "object", fields };
+}
+
+// src/internal/resolver/resolver.ts
+var separatorValues = /* @__PURE__ */ new WeakSet();
 function isSubst(v) {
   return v._kind === "subst-placeholder";
 }
@@ -574,6 +863,12 @@ function resolve2(ast, opts) {
   const resolvedCache = /* @__PURE__ */ new Map();
   return resolveResObj(root, root, resolving, resolvedCache, opts);
 }
+async function resolveAsync(ast, opts) {
+  const root = await buildResObjAsync(ast, opts);
+  const resolving = /* @__PURE__ */ new Set();
+  const resolvedCache = /* @__PURE__ */ new Map();
+  return resolveResObj(root, root, resolving, resolvedCache, opts);
+}
 function buildResObj(ast, opts) {
   if (ast.kind !== "object") {
     throw new ResolveError("root AST must be an object", "", ast.pos.line, ast.pos.col);
@@ -586,7 +881,7 @@ function buildResObj(ast, opts) {
 }
 function applyField(obj, field, opts) {
   if (field.key.length === 0 && field.value.kind === "include") {
-    const included = loadInclude(field.value.path, opts);
+    const included = loadInclude(field.value.path, field.value.required, opts);
     deepMergeResObjInto(obj, included);
     return;
   }
@@ -624,8 +919,11 @@ function applyField(obj, field, opts) {
 }
 function astToResolverValue(ast, opts) {
   switch (ast.kind) {
-    case "scalar":
-      return { kind: "scalar", value: ast.value };
+    case "scalar": {
+      const sv = { kind: "scalar", value: ast.value };
+      if (ast._separator) separatorValues.add(sv);
+      return sv;
+    }
     case "array":
       return { kind: "array", items: ast.items.map((i) => astToResolverValue(i, opts)) };
     case "object": {
@@ -640,6 +938,18 @@ function astToResolverValue(ast, opts) {
       return { kind: "scalar", value: null };
   }
 }
+function hoconValueToResObj(hv) {
+  const obj = makeResObj();
+  if (hv.kind !== "object") return obj;
+  for (const [key, val] of hv.fields) {
+    if (val.kind === "object") {
+      obj.fields.set(key, hoconValueToResObj(val));
+    } else {
+      obj.fields.set(key, val);
+    }
+  }
+  return obj;
+}
 function deepMergeResObjInto(dst, src) {
   for (const [k, srcVal] of src.fields) {
     const dstVal = dst.fields.get(k);
@@ -727,12 +1037,18 @@ function resolveConcat(nodes, scope, root, resolving, resolvedCache, opts) {
   const resolved = nodes.map((n) => resolveVal(n, scope, root, resolving, resolvedCache, opts)).filter((v) => v !== void 0);
   if (resolved.length === 0) return { kind: "scalar", value: null };
   if (resolved.length === 1) return resolved[0];
-  if (resolved.every((v) => v.kind === "object")) {
+  const nonSep = resolved.filter((v) => !separatorValues.has(v));
+  if (nonSep.length > 0 && nonSep.every((v) => v.kind === "object")) {
     const merged = /* @__PURE__ */ new Map();
-    for (const v of resolved) {
+    for (const v of nonSep) {
       if (v.kind === "object") {
         for (const [k, val] of v.fields) {
-          merged.set(k, val);
+          const existing = merged.get(k);
+          if (existing?.kind === "object" && val.kind === "object") {
+            merged.set(k, deepMergeHoconValues(existing, val));
+          } else {
+            merged.set(k, val);
+          }
         }
       }
     }
@@ -749,6 +1065,18 @@ function resolveConcat(nodes, scope, root, resolving, resolvedCache, opts) {
   const str = resolved.map((v) => v.kind === "scalar" ? String(v.value) : JSON.stringify(v)).join("");
   return { kind: "scalar", value: str };
 }
+function deepMergeHoconValues(base, overlay) {
+  const merged = new Map(base.fields);
+  for (const [k, v] of overlay.fields) {
+    const existing = merged.get(k);
+    if (existing?.kind === "object" && v.kind === "object") {
+      merged.set(k, deepMergeHoconValues(existing, v));
+    } else {
+      merged.set(k, v);
+    }
+  }
+  return { kind: "object", fields: merged };
+}
 function resolveAppend(a, scope, root, resolving, resolvedCache, opts) {
   const existing = resolveVal(a.existing, scope, root, resolving, resolvedCache, opts) ?? { kind: "array", items: [] };
   const elem = resolveVal(a.elem, scope, root, resolving, resolvedCache, opts);
@@ -806,35 +1134,203 @@ function parseSubstPath(raw) {
   }
   return segments;
 }
-function loadInclude(includePath, opts) {
-  const { baseDir, readFileSync: readFileSync2, includeStack = [], env } = opts;
+function isFileNotFoundError(e) {
+  if (!(e instanceof Error)) return false;
+  const code = e.code;
+  if (code === "ENOENT" || code === "MODULE_NOT_FOUND") return true;
+  const msg = e.message.toLowerCase();
+  return msg.includes("not found") || msg.includes("no such file") || msg.includes("enoent");
+}
+function loadSingleInclude(candidate, opts) {
+  const { readFileSync: readFileSync2, includeStack = [], env } = opts;
+  if (includeStack.includes(candidate)) {
+    throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
+  }
+  let content;
+  try {
+    content = readFileSync2(candidate);
+  } catch (e) {
+    if (isFileNotFoundError(e)) return void 0;
+    throw e;
+  }
+  if (candidate.endsWith(".properties")) {
+    return hoconValueToResObj(propertiesToHoconValue(content));
+  }
+  const ast = parseTokens(tokenize(content));
+  return buildResObj(ast, {
+    env,
+    baseDir: nodePath.dirname(candidate),
+    readFileSync: readFileSync2,
+    includeStack: [...includeStack, candidate]
+  });
+}
+function loadInclude(includePath, required, opts) {
+  const { baseDir, includeStack = [] } = opts;
   const absPath = baseDir ? nodePath.resolve(baseDir, includePath) : nodePath.resolve(includePath);
   if (includeStack.includes(absPath)) {
     throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0);
   }
-  const candidates = [absPath];
-  if (!absPath.endsWith(".conf") && !absPath.endsWith(".json") && !absPath.endsWith(".properties")) {
-    candidates.push(absPath + ".conf", absPath + ".json");
+  if (includeStack.length >= 50) {
+    throw new ResolveError(`include depth limit exceeded (max 50)`, includePath, 0, 0);
   }
-  for (const candidate of candidates) {
-    let content;
-    try {
-      content = readFileSync2(candidate);
-    } catch {
-      continue;
+  const hasExplicitExt = absPath.endsWith(".conf") || absPath.endsWith(".json") || absPath.endsWith(".properties");
+  if (hasExplicitExt) {
+    const result = loadSingleInclude(absPath, opts);
+    if (result !== void 0) return result;
+    if (required) {
+      throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
     }
-    if (includeStack.includes(candidate)) {
-      throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
+    return makeResObj();
+  }
+  const merged = makeResObj();
+  let foundAny = false;
+  const probeExts = [".properties", ".json", ".conf"];
+  for (const ext of probeExts) {
+    const obj = loadSingleInclude(`${absPath}${ext}`, opts);
+    if (obj !== void 0) {
+      deepMergeResObjInto(merged, obj);
+      foundAny = true;
     }
-    const ast = parseTokens(tokenize(content));
-    return buildResObj(ast, {
-      env,
-      baseDir: nodePath.dirname(candidate),
-      readFileSync: readFileSync2,
-      includeStack: [...includeStack, candidate]
+  }
+  if (!foundAny && required) {
+    throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+  }
+  return merged;
+}
+async function buildResObjAsync(ast, opts) {
+  if (ast.kind !== "object") {
+    throw new ResolveError("root AST must be an object", "", ast.pos.line, ast.pos.col);
+  }
+  const obj = makeResObj();
+  for (const field of ast.fields) {
+    await applyFieldAsync(obj, field, opts);
+  }
+  return obj;
+}
+async function applyFieldAsync(obj, field, opts) {
+  if (field.key.length === 0 && field.value.kind === "include") {
+    const included = await loadIncludeAsync(field.value.path, field.value.required, opts);
+    deepMergeResObjInto(obj, included);
+    return;
+  }
+  const [head, ...tail] = field.key;
+  if (!head) return;
+  if (tail.length > 0) {
+    const syntheticAst = {
+      kind: "object",
+      fields: [{ key: tail, value: field.value, append: field.append, pos: field.pos }],
+      pos: field.pos
+    };
+    await applyFieldAsync(obj, { key: [head], value: syntheticAst, append: false, pos: field.pos }, opts);
+    return;
+  }
+  if (field.append) {
+    const existing2 = obj.fields.get(head) ?? { kind: "array", items: [] };
+    obj.priorValues.set(head, existing2);
+    obj.fields.set(head, {
+      _kind: "append-placeholder",
+      existing: existing2,
+      elem: await astToResolverValueAsync(field.value, opts)
     });
+    return;
+  }
+  const existing = obj.fields.get(head);
+  const newVal = await astToResolverValueAsync(field.value, opts);
+  if (existing !== void 0) {
+    obj.priorValues.set(head, existing);
+  }
+  if (existing !== void 0 && isResObj(existing) && isResObj(newVal)) {
+    deepMergeResObjInto(existing, newVal);
+    return;
+  }
+  obj.fields.set(head, newVal);
+}
+async function astToResolverValueAsync(ast, opts) {
+  switch (ast.kind) {
+    case "scalar": {
+      const sv = { kind: "scalar", value: ast.value };
+      if (ast._separator) separatorValues.add(sv);
+      return sv;
+    }
+    case "array": {
+      const items = [];
+      for (const i of ast.items) {
+        items.push(await astToResolverValueAsync(i, opts));
+      }
+      return { kind: "array", items };
+    }
+    case "object":
+      return await buildResObjAsync(ast, opts);
+    case "subst":
+      return { _kind: "subst-placeholder", path: ast.path, optional: ast.optional, line: ast.pos.line, col: ast.pos.col };
+    case "concat": {
+      const nodes = [];
+      for (const n of ast.nodes) {
+        nodes.push(await astToResolverValueAsync(n, opts));
+      }
+      return { _kind: "concat-placeholder", nodes };
+    }
+    case "include":
+      return { kind: "scalar", value: null };
+  }
+}
+async function loadSingleIncludeAsync(candidate, opts) {
+  const { readFile, readFileSync: readFileSync2, includeStack = [], env } = opts;
+  const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
+  if (includeStack.includes(candidate)) {
+    throw new ResolveError(`circular include: ${candidate}`, candidate, 0, 0);
+  }
+  let content;
+  try {
+    content = await read(candidate);
+  } catch (e) {
+    if (isFileNotFoundError(e)) return void 0;
+    throw e;
+  }
+  if (candidate.endsWith(".properties")) {
+    return hoconValueToResObj(propertiesToHoconValue(content));
   }
-  return makeResObj();
+  const ast = parseTokens(tokenize(content));
+  return buildResObjAsync(ast, {
+    env,
+    baseDir: nodePath.dirname(candidate),
+    readFileSync: readFileSync2,
+    readFile,
+    includeStack: [...includeStack, candidate]
+  });
+}
+async function loadIncludeAsync(includePath, required, opts) {
+  const { baseDir, includeStack = [] } = opts;
+  const absPath = baseDir ? nodePath.resolve(baseDir, includePath) : nodePath.resolve(includePath);
+  if (includeStack.includes(absPath)) {
+    throw new ResolveError(`circular include: ${absPath}`, absPath, 0, 0);
+  }
+  if (includeStack.length >= 50) {
+    throw new ResolveError(`include depth limit exceeded (max 50)`, includePath, 0, 0);
+  }
+  const hasExplicitExt = absPath.endsWith(".conf") || absPath.endsWith(".json") || absPath.endsWith(".properties");
+  if (hasExplicitExt) {
+    const result = await loadSingleIncludeAsync(absPath, opts);
+    if (result !== void 0) return result;
+    if (required) {
+      throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+    }
+    return makeResObj();
+  }
+  const merged = makeResObj();
+  let foundAny = false;
+  const probeExts = [".properties", ".json", ".conf"];
+  for (const ext of probeExts) {
+    const obj = await loadSingleIncludeAsync(`${absPath}${ext}`, opts);
+    if (obj !== void 0) {
+      deepMergeResObjInto(merged, obj);
+      foundAny = true;
+    }
+  }
+  if (!foundAny && required) {
+    throw new ResolveError(`required include file not found: ${includePath}`, includePath, 0, 0);
+  }
+  return merged;
 }
 
 // src/parse.ts
@@ -851,20 +1347,28 @@ function defaultReadFileSync(filePath) {
 async function defaultReadFile(filePath) {
   return fs.promises.readFile(filePath, "utf-8");
 }
-function parse(input, opts = {}) {
+function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
   const ast = parseTokens(tokens);
   const resolveOpts = {
     env: getEnv(opts),
     baseDir: opts.baseDir,
-    readFileSync: opts.readFileSync ?? defaultReadFileSync
+    readFileSync: opts.readFileSync ?? defaultReadFileSync,
+    readFile: opts.readFile
   };
+  return { ast, resolveOpts };
+}
+function parse(input, opts = {}) {
+  const { ast, resolveOpts } = buildResolveContext(input, opts);
   const value = resolve2(ast, resolveOpts);
   if (value.kind !== "object") throw new Error("resolved value is not an object");
   return new Config(value);
 }
 async function parseAsync(input, opts = {}) {
-  return Promise.resolve(parse(input, opts));
+  const { ast, resolveOpts } = buildResolveContext(input, opts);
+  const value = await resolveAsync(ast, resolveOpts);
+  if (value.kind !== "object") throw new Error("resolved value is not an object");
+  return new Config(value);
 }
 function parseFile(filePath, opts = {}) {
   if (typeof process === "undefined" && !opts.readFileSync) {
@@ -886,9 +1390,10 @@ async function parseFileAsync(filePath, opts = {}) {
   const resolvedPath = path.resolve(filePath);
   const readFile = opts.readFile ?? defaultReadFile;
   const input = await readFile(resolvedPath);
-  return parse(input, {
+  return parseAsync(input, {
     ...opts,
     baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFile,
     readFileSync: opts.readFileSync ?? defaultReadFileSync
   });
 }