@o3co/ts.hocon 1.8.0 → 1.9.0

package/README.md

@@ -14,7 +14,7 @@ A [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) pars
 
 > **Library stance:** ts.hocon is a HOCON config loader — its purpose is reading `.hocon` config files and providing typed access via the Config API (`getString`, `getNumber`, `getBoolean`, `getDuration`, `getBytes`, `toObject`). It is not a low-level parser API. Internal types like `HoconValue` may change between minor versions.
 >
-> **Cross-language conformance:** This implementation is tested against shared expected-JSON fixtures from [o3co/xx.hocon](https://github.com/o3co/xx.hocon) alongside [go.hocon](https://github.com/o3co/go.hocon) and [rs.hocon](https://github.com/o3co/rs.hocon) to ensure all three implementations meet the same Lightbend HOCON specification.
+> **Cross-language conformance:** This implementation is tested against shared expected-JSON fixtures from [o3co/xx.hocon](https://github.com/o3co/xx.hocon) alongside [go.hocon](https://github.com/o3co/go.hocon), [rs.hocon](https://github.com/o3co/rs.hocon), and [py.hocon](https://github.com/o3co/py.hocon) to ensure all four implementations meet the same Lightbend HOCON specification.
 
 ---
 
@@ -245,7 +245,7 @@ c.getBytes('max-size')          // 536870912 (bytes)
 c.getBytes('max-size', 'MiB')  // 512
 ```
 
-Supported duration units: `ns`, `us`, `ms`, `s`, `m`, `h`, `d` (and long forms like `seconds`, `minutes`).
+Supported duration units: `ns`, `us`, `ms`, `s`, `m`, `h`, `d` (and long forms like `seconds`, `minutes`). Duration unit names are case-sensitive and must be lowercase (HOCON spec). Byte units are more case-tolerant: the canonical forms below plus lowercase aliases (`kb`, `kib`, …), any-case long forms (`megabytes`), and single-letter powers-of-two in both cases (`K`/`k`, per Lightbend).
 Supported byte units: `B`, `KB`/`KiB`, `MB`/`MiB`, `GB`/`GiB`, `TB`/`TiB` (and long forms like `megabytes`, `mebibytes`).
 
 ## Spec Compliance
@@ -386,9 +386,10 @@ const config = parseWithSchema(hoconInput, schema) // fails fast on startup
 |---------|----------|----------|-------------|
 | [go.hocon](https://github.com/o3co/go.hocon) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/go.hocon) | HOCON parser for Go |
 | [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/o3co-hocon) | HOCON parser for Rust |
+| [py.hocon](https://github.com/o3co/py.hocon) | Python | [PyPI](https://pypi.org/project/hocon-parser/) | HOCON parser for Python |
 | [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties CLI |
 
-The three parser implementations ([ts.hocon](https://github.com/o3co/ts.hocon), [rs.hocon](https://github.com/o3co/rs.hocon), [go.hocon](https://github.com/o3co/go.hocon)) are all tracked against the same Lightbend HOCON spec — see the [cross-impl roll-up](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) for per-impl conformance rates.
+The four parser implementations ([ts.hocon](https://github.com/o3co/ts.hocon), [rs.hocon](https://github.com/o3co/rs.hocon), [go.hocon](https://github.com/o3co/go.hocon), [py.hocon](https://github.com/o3co/py.hocon)) are all tracked against the same Lightbend HOCON spec — see the [cross-impl roll-up](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) for per-impl conformance rates.
 
 ## Known Limitations
 
@@ -402,7 +403,7 @@ The three parser implementations ([ts.hocon](https://github.com/o3co/ts.hocon),
 
 When parsing untrusted HOCON input, be aware of:
 
-- **Path traversal in includes:** `include "../../../etc/passwd"` will resolve relative to `baseDir`. Use a custom `readFileSync`/`readFile` that validates paths if parsing untrusted input.
+- **Path traversal in includes:** a relative `include` path resolves against `baseDir` and can climb out of it with `..` segments to reach sensitive files such as `/etc/passwd`. Use a custom `readFileSync`/`readFile` that validates paths if parsing untrusted input.
 - **Input size:** The parser has no built-in input size limit. For untrusted input, validate size before calling `parse()`.
 - **Include depth:** Limited to 50 levels to prevent stack overflow from deep include chains.
 

package/dist/index.cjs

@@ -141,7 +141,7 @@ function parseDuration(value, outputUnit = "ms") {
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimHoconWs(trimmed.slice(i)).toLowerCase();
+  const unit = trimHoconWs(trimmed.slice(i));
   const divisor = OUTPUT_DURATION_UNITS[outputUnit];
   if (divisor === void 0) return NaN;
   if (unit === "") {
@@ -701,20 +701,6 @@ function isFileNotFoundError(e) {
 var import_node_module = require("module");
 var nodePath = __toESM(require("path"), 1);
 
-// src/internal/parser/empty-check.ts
-function hasContentTokens(tokens) {
-  return tokens.some((t) => t.kind !== "eof" && t.kind !== "newline");
-}
-function assertNonEmptyDocument(tokens, sourceDescriptor) {
-  if (!hasContentTokens(tokens)) {
-    throw new ParseError(
-      `empty file is not a valid HOCON document (HOCON.md L130): ${sourceDescriptor}`,
-      1,
-      1
-    );
-  }
-}
-
 // src/internal/lexer/lexer.ts
 function isHoconWhitespace(ch) {
   const cp = ch.codePointAt(0) ?? -1;
@@ -1160,6 +1146,16 @@ var Parser = class {
       }
       return { kind: "object", fields: allFields, pos: first.pos };
     }
+    if (t.kind === "lbracket") {
+      this.advance();
+      const arr = this.parseArray();
+      this.skip("newline");
+      const remaining = this.peek();
+      if (remaining.kind !== "eof") {
+        throw new ParseError(`Unexpected token '${remaining.value}' after root array`, remaining.line, remaining.col);
+      }
+      return { ...arr, pos: { line: t.line, col: t.col } };
+    }
     return this.parseObject(false);
   }
   peek(offset = 0) {
@@ -1599,6 +1595,16 @@ var _require = (0, import_node_module.createRequire)(import_meta.url);
 function isPnpPath(p) {
   return p.includes(".yarn/cache") || p.includes(".pnp.cjs") || p.includes(".pnp.loader");
 }
+function assertObjectRootedInclude(ast, sourcePath) {
+  if (ast.kind === "array") {
+    throw new ResolveError(
+      `included file has array at file root \u2014 an included file must contain an object, not an array (HOCON.md L993-994): ${sourcePath}`,
+      sourcePath,
+      ast.pos.line,
+      ast.pos.col
+    );
+  }
+}
 function validatePackageFile(file, identifier) {
   if (file.length === 0) {
     throw new ParseError(`include package("${identifier}", ...): file argument must be non-empty`, 0, 0);
@@ -1778,10 +1784,9 @@ var IncludeLoader = class {
     const resolver = packageResolver ?? ((id, f, includingFile, bDir) => defaultPackageResolver(id, f, includingFile, bDir, resolveFrom));
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const content = readFileSync2(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1811,10 +1816,9 @@ var IncludeLoader = class {
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
     const content = await read(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1837,10 +1841,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -1864,10 +1866,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -3059,8 +3059,14 @@ async function defaultReadFile(filePath) {
 }
 function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
-  assertNonEmptyDocument(tokens, "input");
   const ast = parseTokens(tokens);
+  if (ast.kind === "array") {
+    const origin = opts.originDescription ?? "input";
+    throw new ConfigError(
+      `${origin}: ${ast.pos.line}:${ast.pos.col}: document has type array rather than object at file root (HOCON.md L989-991); the Config API requires an object root`,
+      ""
+    );
+  }
   const resolveOpts = {
     env: getEnv(opts),
     baseDir: opts.baseDir,

package/dist/index.js

@@ -80,7 +80,7 @@ function parseDuration(value, outputUnit = "ms") {
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimHoconWs(trimmed.slice(i)).toLowerCase();
+  const unit = trimHoconWs(trimmed.slice(i));
   const divisor = OUTPUT_DURATION_UNITS[outputUnit];
   if (divisor === void 0) return NaN;
   if (unit === "") {
@@ -640,20 +640,6 @@ function isFileNotFoundError(e) {
 import { createRequire } from "module";
 import * as nodePath from "path";
 
-// src/internal/parser/empty-check.ts
-function hasContentTokens(tokens) {
-  return tokens.some((t) => t.kind !== "eof" && t.kind !== "newline");
-}
-function assertNonEmptyDocument(tokens, sourceDescriptor) {
-  if (!hasContentTokens(tokens)) {
-    throw new ParseError(
-      `empty file is not a valid HOCON document (HOCON.md L130): ${sourceDescriptor}`,
-      1,
-      1
-    );
-  }
-}
-
 // src/internal/lexer/lexer.ts
 function isHoconWhitespace(ch) {
   const cp = ch.codePointAt(0) ?? -1;
@@ -1099,6 +1085,16 @@ var Parser = class {
       }
       return { kind: "object", fields: allFields, pos: first.pos };
     }
+    if (t.kind === "lbracket") {
+      this.advance();
+      const arr = this.parseArray();
+      this.skip("newline");
+      const remaining = this.peek();
+      if (remaining.kind !== "eof") {
+        throw new ParseError(`Unexpected token '${remaining.value}' after root array`, remaining.line, remaining.col);
+      }
+      return { ...arr, pos: { line: t.line, col: t.col } };
+    }
     return this.parseObject(false);
   }
   peek(offset = 0) {
@@ -1537,6 +1533,16 @@ var _require = createRequire(import.meta.url);
 function isPnpPath(p) {
   return p.includes(".yarn/cache") || p.includes(".pnp.cjs") || p.includes(".pnp.loader");
 }
+function assertObjectRootedInclude(ast, sourcePath) {
+  if (ast.kind === "array") {
+    throw new ResolveError(
+      `included file has array at file root \u2014 an included file must contain an object, not an array (HOCON.md L993-994): ${sourcePath}`,
+      sourcePath,
+      ast.pos.line,
+      ast.pos.col
+    );
+  }
+}
 function validatePackageFile(file, identifier) {
   if (file.length === 0) {
     throw new ParseError(`include package("${identifier}", ...): file argument must be non-empty`, 0, 0);
@@ -1716,10 +1722,9 @@ var IncludeLoader = class {
     const resolver = packageResolver ?? ((id, f, includingFile, bDir) => defaultPackageResolver(id, f, includingFile, bDir, resolveFrom));
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const content = readFileSync2(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1749,10 +1754,9 @@ var IncludeLoader = class {
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
     const content = await read(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1775,10 +1779,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -1802,10 +1804,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -2997,8 +2997,14 @@ async function defaultReadFile(filePath) {
 }
 function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
-  assertNonEmptyDocument(tokens, "input");
   const ast = parseTokens(tokens);
+  if (ast.kind === "array") {
+    const origin = opts.originDescription ?? "input";
+    throw new ConfigError(
+      `${origin}: ${ast.pos.line}:${ast.pos.col}: document has type array rather than object at file root (HOCON.md L989-991); the Config API requires an object root`,
+      ""
+    );
+  }
   const resolveOpts = {
     env: getEnv(opts),
     baseDir: opts.baseDir,

package/dist/zod.cjs

@@ -119,7 +119,7 @@ function parseDuration(value, outputUnit = "ms") {
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimHoconWs(trimmed.slice(i)).toLowerCase();
+  const unit = trimHoconWs(trimmed.slice(i));
   const divisor = OUTPUT_DURATION_UNITS[outputUnit];
   if (divisor === void 0) return NaN;
   if (unit === "") {
@@ -683,20 +683,6 @@ function isFileNotFoundError(e) {
 var import_node_module = require("module");
 var nodePath = __toESM(require("path"), 1);
 
-// src/internal/parser/empty-check.ts
-function hasContentTokens(tokens) {
-  return tokens.some((t) => t.kind !== "eof" && t.kind !== "newline");
-}
-function assertNonEmptyDocument(tokens, sourceDescriptor) {
-  if (!hasContentTokens(tokens)) {
-    throw new ParseError(
-      `empty file is not a valid HOCON document (HOCON.md L130): ${sourceDescriptor}`,
-      1,
-      1
-    );
-  }
-}
-
 // src/internal/lexer/lexer.ts
 function isHoconWhitespace(ch) {
   const cp = ch.codePointAt(0) ?? -1;
@@ -1142,6 +1128,16 @@ var Parser = class {
       }
       return { kind: "object", fields: allFields, pos: first.pos };
     }
+    if (t.kind === "lbracket") {
+      this.advance();
+      const arr = this.parseArray();
+      this.skip("newline");
+      const remaining = this.peek();
+      if (remaining.kind !== "eof") {
+        throw new ParseError(`Unexpected token '${remaining.value}' after root array`, remaining.line, remaining.col);
+      }
+      return { ...arr, pos: { line: t.line, col: t.col } };
+    }
     return this.parseObject(false);
   }
   peek(offset = 0) {
@@ -1581,6 +1577,16 @@ var _require = (0, import_node_module.createRequire)(import_meta.url);
 function isPnpPath(p) {
   return p.includes(".yarn/cache") || p.includes(".pnp.cjs") || p.includes(".pnp.loader");
 }
+function assertObjectRootedInclude(ast, sourcePath) {
+  if (ast.kind === "array") {
+    throw new ResolveError(
+      `included file has array at file root \u2014 an included file must contain an object, not an array (HOCON.md L993-994): ${sourcePath}`,
+      sourcePath,
+      ast.pos.line,
+      ast.pos.col
+    );
+  }
+}
 function validatePackageFile(file, identifier) {
   if (file.length === 0) {
     throw new ParseError(`include package("${identifier}", ...): file argument must be non-empty`, 0, 0);
@@ -1760,10 +1766,9 @@ var IncludeLoader = class {
     const resolver = packageResolver ?? ((id, f, includingFile, bDir) => defaultPackageResolver(id, f, includingFile, bDir, resolveFrom));
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const content = readFileSync2(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1793,10 +1798,9 @@ var IncludeLoader = class {
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
     const content = await read(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1819,10 +1823,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -1846,10 +1848,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -3026,8 +3026,14 @@ function defaultReadFileSync(filePath) {
 }
 function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
-  assertNonEmptyDocument(tokens, "input");
   const ast = parseTokens(tokens);
+  if (ast.kind === "array") {
+    const origin = opts.originDescription ?? "input";
+    throw new ConfigError(
+      `${origin}: ${ast.pos.line}:${ast.pos.col}: document has type array rather than object at file root (HOCON.md L989-991); the Config API requires an object root`,
+      ""
+    );
+  }
   const resolveOpts = {
     env: getEnv(opts),
     baseDir: opts.baseDir,

package/dist/zod.js

@@ -80,7 +80,7 @@ function parseDuration(value, outputUnit = "ms") {
   if (i === 0) return NaN;
   const num = Number(trimmed.slice(0, i));
   if (Number.isNaN(num)) return NaN;
-  const unit = trimHoconWs(trimmed.slice(i)).toLowerCase();
+  const unit = trimHoconWs(trimmed.slice(i));
   const divisor = OUTPUT_DURATION_UNITS[outputUnit];
   if (divisor === void 0) return NaN;
   if (unit === "") {
@@ -644,20 +644,6 @@ function isFileNotFoundError(e) {
 import { createRequire } from "module";
 import * as nodePath from "path";
 
-// src/internal/parser/empty-check.ts
-function hasContentTokens(tokens) {
-  return tokens.some((t) => t.kind !== "eof" && t.kind !== "newline");
-}
-function assertNonEmptyDocument(tokens, sourceDescriptor) {
-  if (!hasContentTokens(tokens)) {
-    throw new ParseError(
-      `empty file is not a valid HOCON document (HOCON.md L130): ${sourceDescriptor}`,
-      1,
-      1
-    );
-  }
-}
-
 // src/internal/lexer/lexer.ts
 function isHoconWhitespace(ch) {
   const cp = ch.codePointAt(0) ?? -1;
@@ -1103,6 +1089,16 @@ var Parser = class {
       }
       return { kind: "object", fields: allFields, pos: first.pos };
     }
+    if (t.kind === "lbracket") {
+      this.advance();
+      const arr = this.parseArray();
+      this.skip("newline");
+      const remaining = this.peek();
+      if (remaining.kind !== "eof") {
+        throw new ParseError(`Unexpected token '${remaining.value}' after root array`, remaining.line, remaining.col);
+      }
+      return { ...arr, pos: { line: t.line, col: t.col } };
+    }
     return this.parseObject(false);
   }
   peek(offset = 0) {
@@ -1541,6 +1537,16 @@ var _require = createRequire(import.meta.url);
 function isPnpPath(p) {
   return p.includes(".yarn/cache") || p.includes(".pnp.cjs") || p.includes(".pnp.loader");
 }
+function assertObjectRootedInclude(ast, sourcePath) {
+  if (ast.kind === "array") {
+    throw new ResolveError(
+      `included file has array at file root \u2014 an included file must contain an object, not an array (HOCON.md L993-994): ${sourcePath}`,
+      sourcePath,
+      ast.pos.line,
+      ast.pos.col
+    );
+  }
+}
 function validatePackageFile(file, identifier) {
   if (file.length === 0) {
     throw new ParseError(`include package("${identifier}", ...): file argument must be non-empty`, 0, 0);
@@ -1720,10 +1726,9 @@ var IncludeLoader = class {
     const resolver = packageResolver ?? ((id, f, includingFile, bDir) => defaultPackageResolver(id, f, includingFile, bDir, resolveFrom));
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const content = readFileSync2(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1753,10 +1758,9 @@ var IncludeLoader = class {
     const resolvedPath = resolver(identifier, file, void 0, baseDir);
     const read = readFile ? async (p) => readFile(p) : async (p) => readFileSync2(p);
     const content = await read(resolvedPath);
-    if (content.length === 0) return makeResObj();
     const tokens = tokenize(content);
-    assertNonEmptyDocument(tokens, resolvedPath);
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, resolvedPath);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(resolvedPath),
@@ -1779,10 +1783,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObj(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -1806,10 +1808,8 @@ var IncludeLoader = class {
       return hoconValueToResObj(propertiesToHoconValue(content));
     }
     const tokens = tokenize(content);
-    if (!hasContentTokens(tokens)) {
-      return makeResObj();
-    }
     const ast = parseTokens(tokens);
+    assertObjectRootedInclude(ast, candidate);
     return this.onBuildResObjAsync(ast, {
       ...this.opts,
       baseDir: nodePath.dirname(candidate),
@@ -2986,8 +2986,14 @@ function defaultReadFileSync(filePath) {
 }
 function buildResolveContext(input, opts) {
   const tokens = tokenize(input);
-  assertNonEmptyDocument(tokens, "input");
   const ast = parseTokens(tokens);
+  if (ast.kind === "array") {
+    const origin = opts.originDescription ?? "input";
+    throw new ConfigError(
+      `${origin}: ${ast.pos.line}:${ast.pos.col}: document has type array rather than object at file root (HOCON.md L989-991); the Config API requires an object root`,
+      ""
+    );
+  }
   const resolveOpts = {
     env: getEnv(opts),
     baseDir: opts.baseDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/ts.hocon",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Full Lightbend HOCON spec-compliant parser and config library for TypeScript",
   "keywords": [
     "hocon",
@@ -29,6 +29,15 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "coverage": "vitest run --coverage",
+    "bench": "vitest bench",
+    "docs": "typedoc"
+  },
   "peerDependencies": {
     "zod": ">=4.0.0"
   },
@@ -39,18 +48,18 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "4.1.2",
-    "js-yaml": "^4.1.1",
+    "@types/node": "^25.9.5",
+    "@vitest/coverage-v8": "4.1.10",
+    "js-yaml": "^4.3.0",
     "tsup": "^8.5.1",
-    "typedoc": "^0.28.18",
+    "typedoc": "^0.28.20",
     "typescript": "^5.9.3",
-    "vitest": "4.1.2",
-    "zod": "^4.3.6"
+    "vitest": "4.1.10",
+    "zod": "^4.4.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/o3co/ts.hocon"
+    "url": "git+https://github.com/o3co/ts.hocon.git"
   },
   "license": "Apache-2.0",
   "engines": {
@@ -58,13 +67,5 @@
   },
   "homepage": "https://o3co.github.io/ts.hocon/",
   "bugs": "https://github.com/o3co/ts.hocon/issues",
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "coverage": "vitest run --coverage",
-    "bench": "vitest bench",
-    "docs": "typedoc"
-  }
-}
+  "packageManager": "pnpm@10.30.2"
+}