@o3co/ts.hocon 1.12.0 → 1.14.0

package/dist/chunk-XWKO4JM3.js

@@ -0,0 +1,158 @@
+import {
+  Config,
+  ConfigError,
+  ParseError,
+  buildTree,
+  buildTreeAsync,
+  containsPlaceholders,
+  guardStackDepth,
+  guardStackDepthAsync,
+  parseTokens,
+  resolve,
+  resolveAsync,
+  tokenize
+} from "./chunk-WTXULUZS.js";
+
+// src/parse.ts
+import * as fs from "fs";
+import * as path from "path";
+function defaultParseOptions() {
+  return { resolveSubstitutions: true };
+}
+function defaultResolveOptions() {
+  return { useSystemEnvironment: true, allowUnresolved: false };
+}
+function getEnv(opts) {
+  if (opts.env !== void 0) return opts.env;
+  if (typeof process !== "undefined" && process.env) return process.env;
+  return {};
+}
+function defaultReadFileSync(filePath) {
+  return fs.readFileSync(filePath, "utf-8");
+}
+async function defaultReadFile(filePath) {
+  return fs.promises.readFile(filePath, "utf-8");
+}
+function buildResolveContext(input, opts) {
+  const tokens = tokenize(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,
+    readFileSync: opts.readFileSync ?? defaultReadFileSync,
+    readFile: opts.readFile,
+    originDescription: opts.originDescription,
+    resolveFrom: opts.resolveFrom,
+    packageResolver: opts.packageResolver
+  };
+  return { ast, resolveOpts };
+}
+function parse(input, opts = {}) {
+  return parseStringWithOptions(input, opts);
+}
+var parseString = parse;
+function parseStringWithOptions(input, opts = {}) {
+  return guardStackDepth(
+    () => parseStringInner(input, opts),
+    (msg) => new ParseError(msg, 1, 1, opts.originDescription)
+  );
+}
+function parseStringInner(input, opts) {
+  const resolveSubstitutions = opts.resolveSubstitutions ?? true;
+  const { ast, resolveOpts } = buildResolveContext(input, opts);
+  if (resolveSubstitutions) {
+    const value = resolve(ast, resolveOpts);
+    if (value.kind !== "object") throw new Error("resolved value is not an object");
+    return new Config(value, { resolved: true, originDescription: opts.originDescription });
+  }
+  const tree = buildTree(ast, resolveOpts);
+  const hasPlaceholders = containsPlaceholders(tree);
+  return Config._fromUnresolvedResObj(tree, {
+    parseBaseDir: opts.baseDir,
+    originDescription: opts.originDescription,
+    resolved: !hasPlaceholders,
+    resolveOpts
+  });
+}
+function parseFileWithOptions(filePath, opts = {}) {
+  if (typeof process === "undefined" && !opts.readFileSync) {
+    throw new Error("parseFileWithOptions is not supported in browser environments without opts.readFileSync.");
+  }
+  const resolvedPath = path.resolve(filePath);
+  const readFileSync2 = opts.readFileSync ?? defaultReadFileSync;
+  const input = readFileSync2(resolvedPath);
+  return parseStringWithOptions(input, {
+    ...opts,
+    baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFileSync: readFileSync2
+  });
+}
+async function parseAsync(input, opts = {}) {
+  return guardStackDepthAsync(
+    () => parseStringInnerAsync(input, opts),
+    (msg) => new ParseError(msg, 1, 1, opts.originDescription)
+  );
+}
+async function parseStringInnerAsync(input, opts) {
+  const resolveSubstitutions = opts.resolveSubstitutions ?? true;
+  const { ast, resolveOpts } = buildResolveContext(input, opts);
+  if (resolveSubstitutions) {
+    const value = await resolveAsync(ast, resolveOpts);
+    if (value.kind !== "object") throw new Error("resolved value is not an object");
+    return new Config(value, { resolved: true, originDescription: opts.originDescription });
+  }
+  const tree = await buildTreeAsync(ast, resolveOpts);
+  const hasPlaceholders = containsPlaceholders(tree);
+  return Config._fromUnresolvedResObj(tree, {
+    parseBaseDir: opts.baseDir,
+    originDescription: opts.originDescription,
+    resolved: !hasPlaceholders,
+    resolveOpts
+  });
+}
+function parseFile(filePath, opts = {}) {
+  if (typeof process === "undefined" && !opts.readFileSync) {
+    throw new Error("parseFile is not supported in browser environments. Provide opts.readFileSync or use parse() instead.");
+  }
+  const resolvedPath = path.resolve(filePath);
+  const readFileSync2 = opts.readFileSync ?? defaultReadFileSync;
+  const input = readFileSync2(resolvedPath);
+  return parse(input, {
+    ...opts,
+    baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFileSync: readFileSync2
+  });
+}
+async function parseFileAsync(filePath, opts = {}) {
+  if (typeof process === "undefined" && !opts.readFile) {
+    throw new Error("parseFileAsync is not supported in browser environments. Provide opts.readFile or use parseAsync() instead.");
+  }
+  const resolvedPath = path.resolve(filePath);
+  const readFile = opts.readFile ?? defaultReadFile;
+  const input = await readFile(resolvedPath);
+  return parseAsync(input, {
+    ...opts,
+    baseDir: opts.baseDir ?? path.dirname(resolvedPath),
+    readFile,
+    readFileSync: opts.readFileSync ?? defaultReadFileSync
+  });
+}
+
+export {
+  defaultParseOptions,
+  defaultResolveOptions,
+  parse,
+  parseString,
+  parseStringWithOptions,
+  parseFileWithOptions,
+  parseAsync,
+  parseFile,
+  parseFileAsync
+};

package/dist/{config-Dlq6rF3w.d.cts → config-OccaKqXu.d.cts}

@@ -206,6 +206,19 @@ declare function defaultParseOptions(): Required<Pick<ParseOptions, 'resolveSubs
 /** Returns a ResolveOptions object with Lightbend-aligned defaults:
  *  useSystemEnvironment=true, allowUnresolved=false. */
 declare function defaultResolveOptions(): Required<ResolveOptions>;
+/**
+ * Parse a HOCON string into a Config. Substitutions are resolved unless
+ * `opts.resolveSubstitutions` is false (then the Config is unresolved; finish
+ * it with `resolve()` / `resolveWith()`). Includes are read with
+ * `opts.readFileSync` (default: `fs`). A bare `include "x.conf"` resolves
+ * relative to `opts.baseDir` (default: the current directory); a relative
+ * `include file("x.conf")` always resolves from the current directory.
+ *
+ * @throws {@link ParseError} on a syntax error, or a document nested too deeply.
+ * @throws {@link ResolveError} on a substitution that cannot be resolved, a cycle,
+ *   or a required include that cannot be found.
+ * @throws {@link ConfigError} when the document root is not an object.
+ */
 declare function parse(input: string, opts?: ParseOptions): Config;
 /** Lightbend-aligned alias for parse(). Produces a fully resolved Config. */
 declare const parseString: typeof parse;
@@ -220,11 +233,35 @@ declare function parseFileWithOptions(filePath: string, opts?: ParseOptions): Co
  * asynchronously via `readFile` when provided.
  */
 declare function parseAsync(input: string, opts?: ParseOptions): Promise<Config>;
+/**
+ * Read and parse a HOCON file, as {@link parse} does with the file's text; a
+ * bare `include` resolves relative to the file's directory (unless
+ * `opts.baseDir` is set), a relative `include file(...)` from the current
+ * directory. Needs Node.js, or `opts.readFileSync` elsewhere.
+ *
+ * @throws as {@link parse}, plus whatever reading the file throws.
+ */
 declare function parseFile(filePath: string, opts?: ParseOptions): Config;
+/**
+ * {@link parseFile} with the file and its includes read asynchronously
+ * (`opts.readFile`, default `fs.promises`). Needs Node.js, or `opts.readFile`
+ * elsewhere.
+ *
+ * @throws (rejects) as {@link parseFile}.
+ */
 declare function parseFileAsync(filePath: string, opts?: ParseOptions): Promise<Config>;
 
 type DurationUnit = 'ns' | 'us' | 'ms' | 's' | 'm' | 'h' | 'd';
 type ByteUnit = 'B' | 'KB' | 'KiB' | 'MB' | 'MiB' | 'GB' | 'GiB' | 'TB' | 'TiB';
+/**
+ * A calendar period, as {@link Config.getPeriod} returns it. Weeks are folded
+ * into days (`2w` is 14 days). A component may be negative.
+ */
+interface Period {
+    readonly years: number;
+    readonly months: number;
+    readonly days: number;
+}
 
 declare class Config {
     private readonly root;
@@ -236,6 +273,13 @@ declare class Config {
     readonly _originDescription: string | undefined;
     /** @internal ResObj tree for deferred-resolution path. Set when resolved=false. */
     readonly _resObjRoot: ResObj | undefined;
+    /**
+     * @internal What is still unresolved after a partial resolve
+     * (`allowUnresolved: true`), with resolved values in place. The unresolved
+     * checks read this; `_resObjRoot` keeps the original tree for the next
+     * resolve. Unset when the two are the same (a deferred parse).
+     */
+    private readonly _pendingRoot;
     /** @internal ResolveOptions stored for the resolve() call. */
     private readonly _resolveOpts;
     constructor(root: HoconValue & {
@@ -245,6 +289,7 @@ declare class Config {
         parseBaseDir?: string;
         originDescription?: string;
         resObjRoot?: ResObj;
+        pendingRoot?: ResObj;
         resolveOpts?: ResolveOptions$1;
     });
     /** Returns true when the Config's value tree contains no unresolved
@@ -279,13 +324,87 @@ declare class Config {
      * cannot be represented. This matches `getConfig` / `getList`.
      */
     getValue(path: string): ReadonlyHoconValue | undefined;
+    /**
+     * The scalar at `path` as its text: a number or boolean comes back as written
+     * (`8080`, `true`).
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a scalar, or the value is
+     *   `null`.
+     */
     getString(path: string): string;
+    /**
+     * The scalar at `path` as a number. A string that reads as a decimal number
+     * (`"8080"`, `"1.5e3"`) is accepted.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a scalar, or the value is not a
+     *   number.
+     */
     getNumber(path: string): number;
+    /**
+     * The scalar at `path` as a boolean: `true` / `yes` / `on` and `false` /
+     * `no` / `off`, in any case.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a scalar, or the value is not one
+     *   of those words.
+     */
     getBoolean(path: string): boolean;
+    /**
+     * The duration at `path` in `unit` (default `ms`): a string with a unit
+     * (`"30s"`, `"1.5h"`), or a number or unit-less string, which is
+     * milliseconds. The number is read exactly and rounded once in `unit` (E20).
+     * Negative durations are allowed.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a string or number, the text is
+     *   not a duration, or the result is not a finite number (E21).
+     */
     getDuration(path: string, unit?: DurationUnit): number;
+    /**
+     * The byte size at `path` in `unit` (default `B`): a string with a unit
+     * (`"64KiB"`, `"1.5MB"`), or a number or unit-less string, which is bytes.
+     * The exact size is truncated toward zero to whole bytes, then converted to
+     * `unit` (E20).
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a string or number, the text is
+     *   not a byte size, the size is negative, or it exceeds 2^53-1 bytes (the
+     *   largest integer a JS number holds exactly).
+     */
     getBytes(path: string, unit?: ByteUnit): number;
+    /**
+     * The calendar period at `path` (`7d`, `2w`, `3m`, `1y`; a bare integer is
+     * days). Integer only, unlike {@link getDuration} / {@link getBytes}.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a string or number, or the text
+     *   is not a period.
+     */
+    getPeriod(path: string): Period;
+    /**
+     * The object at `path` as a Config of its own, with paths relative to it.
+     *
+     * @throws {@link NotResolvedError} when the object holds an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not an object.
+     */
     getConfig(path: string): Config;
+    /**
+     * The list at `path` as plain values (see {@link get}). An object with integer
+     * keys (`"0"`, `"1"`, …) is read as a list too, in key order with gaps closed
+     * up; its other keys are ignored (S15).
+     *
+     * @throws {@link NotResolvedError} when the list holds an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a list.
+     */
     getList(path: string): unknown[];
+    /**
+     * Whether `path` is present. A path whose value is still an unresolved
+     * substitution is present too (`true`, no throw), as in go.hocon; reading it
+     * throws {@link NotResolvedError}. A path *under* such a value is not known
+     * yet and answers `false`.
+     */
     has(path: string): boolean;
     keys(): string[];
     withFallback(fallback: Config | undefined): Config;
@@ -363,6 +482,28 @@ declare class Config {
     toObject(opts?: {
         nullPrototype?: boolean;
     }): unknown;
+    /**
+     * Renders this resolved Config as HOCON text (E18; lockstep with go.hocon's
+     * `Config.RenderHOCON`, v1.11.0).
+     *
+     * The output round-trips: parsing it back yields the same value tree. That
+     * is the correctness contract, not byte-for-byte formatting — a scalar is
+     * quoted whenever leaving it bare would re-parse as a different type (a
+     * string `"8080"` becomes `"8080"`, not `8080`), and left bare only when it
+     * provably cannot.
+     *
+     * The Config must be resolved and hold only data (objects, arrays, string /
+     * number / boolean / null scalars) — exactly what {@link fromMap} and the
+     * format adapters produce. An unresolved placeholder throws
+     * {@link ConfigError}; substitutions have no textual round trip through a
+     * value tree.
+     *
+     * The root object's fields are emitted without enclosing braces, nested
+     * objects as `key { … }`, arrays as newline-separated `[ … ]`, indented two
+     * spaces. Source comments are not represented — a value tree does not carry
+     * them.
+     */
+    renderHocon(): string;
     /**
      * @internal Test-only: renders this resolved Config's value tree as canonical
      * JSON (sorted keys, no whitespace). Used by Layer-2 fixture tests to compare
@@ -372,9 +513,12 @@ declare class Config {
      */
     _renderJSONForTest(): string;
     private lookupNode;
+    /** Whether `path` names a field in the unresolved tree (a placeholder included). */
+    private _unresolvedTreeHas;
     /**
-     * _resObjRootSubtreeHasPlaceholders — walk _resObjRoot to the given path and
-     * return true if the subtree there contains any unresolved placeholder.
+     * _subtreeHasPlaceholders — walk the unresolved tree (`_pendingRoot` after a
+     * partial resolve, else `_resObjRoot`) to the given path and return true if
+     * the subtree there contains any unresolved placeholder.
      * Used by getConfig / getList (T2) to detect transitive unresolved placeholders
      * in object / array subtrees that would otherwise appear to be "resolved" in the
      * partial HoconValue root (because individual leaf fields are omitted rather than
@@ -382,8 +526,8 @@ declare class Config {
      * sub-containers are retained in the partial root with the placeholder-keyed
      * fields omitted from them — so the object appears "present but empty-ish").
      */
-    private _resObjRootSubtreeHasPlaceholders;
+    private _subtreeHasPlaceholders;
     private requireScalar;
 }
 
-export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ReadonlyHoconValue as R, type ScalarValueType as S, type ParseOptions as a, type ResolveOptions as b, asArray as c, asBoolean as d, asNumber as e, asObject as f, asString as g, defaultParseOptions as h, defaultResolveOptions as i, isArray as j, isNull as k, isObject as l, isScalar as m, parseAsync as n, parseFile as o, parse as p, parseFileAsync as q, parseFileWithOptions as r, parseString as s, parseStringWithOptions as t };
+export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ReadonlyHoconValue as R, type ScalarValueType as S, type ParseOptions as a, type Period as b, type ResolveOptions as c, asArray as d, asBoolean as e, asNumber as f, asObject as g, asString as h, defaultParseOptions as i, defaultResolveOptions as j, isArray as k, isNull as l, isObject as m, isScalar as n, parseAsync as o, parse as p, parseFile as q, parseFileAsync as r, parseFileWithOptions as s, parseString as t, parseStringWithOptions as u };

package/dist/{config-Dlq6rF3w.d.ts → config-OccaKqXu.d.ts}

@@ -206,6 +206,19 @@ declare function defaultParseOptions(): Required<Pick<ParseOptions, 'resolveSubs
 /** Returns a ResolveOptions object with Lightbend-aligned defaults:
  *  useSystemEnvironment=true, allowUnresolved=false. */
 declare function defaultResolveOptions(): Required<ResolveOptions>;
+/**
+ * Parse a HOCON string into a Config. Substitutions are resolved unless
+ * `opts.resolveSubstitutions` is false (then the Config is unresolved; finish
+ * it with `resolve()` / `resolveWith()`). Includes are read with
+ * `opts.readFileSync` (default: `fs`). A bare `include "x.conf"` resolves
+ * relative to `opts.baseDir` (default: the current directory); a relative
+ * `include file("x.conf")` always resolves from the current directory.
+ *
+ * @throws {@link ParseError} on a syntax error, or a document nested too deeply.
+ * @throws {@link ResolveError} on a substitution that cannot be resolved, a cycle,
+ *   or a required include that cannot be found.
+ * @throws {@link ConfigError} when the document root is not an object.
+ */
 declare function parse(input: string, opts?: ParseOptions): Config;
 /** Lightbend-aligned alias for parse(). Produces a fully resolved Config. */
 declare const parseString: typeof parse;
@@ -220,11 +233,35 @@ declare function parseFileWithOptions(filePath: string, opts?: ParseOptions): Co
  * asynchronously via `readFile` when provided.
  */
 declare function parseAsync(input: string, opts?: ParseOptions): Promise<Config>;
+/**
+ * Read and parse a HOCON file, as {@link parse} does with the file's text; a
+ * bare `include` resolves relative to the file's directory (unless
+ * `opts.baseDir` is set), a relative `include file(...)` from the current
+ * directory. Needs Node.js, or `opts.readFileSync` elsewhere.
+ *
+ * @throws as {@link parse}, plus whatever reading the file throws.
+ */
 declare function parseFile(filePath: string, opts?: ParseOptions): Config;
+/**
+ * {@link parseFile} with the file and its includes read asynchronously
+ * (`opts.readFile`, default `fs.promises`). Needs Node.js, or `opts.readFile`
+ * elsewhere.
+ *
+ * @throws (rejects) as {@link parseFile}.
+ */
 declare function parseFileAsync(filePath: string, opts?: ParseOptions): Promise<Config>;
 
 type DurationUnit = 'ns' | 'us' | 'ms' | 's' | 'm' | 'h' | 'd';
 type ByteUnit = 'B' | 'KB' | 'KiB' | 'MB' | 'MiB' | 'GB' | 'GiB' | 'TB' | 'TiB';
+/**
+ * A calendar period, as {@link Config.getPeriod} returns it. Weeks are folded
+ * into days (`2w` is 14 days). A component may be negative.
+ */
+interface Period {
+    readonly years: number;
+    readonly months: number;
+    readonly days: number;
+}
 
 declare class Config {
     private readonly root;
@@ -236,6 +273,13 @@ declare class Config {
     readonly _originDescription: string | undefined;
     /** @internal ResObj tree for deferred-resolution path. Set when resolved=false. */
     readonly _resObjRoot: ResObj | undefined;
+    /**
+     * @internal What is still unresolved after a partial resolve
+     * (`allowUnresolved: true`), with resolved values in place. The unresolved
+     * checks read this; `_resObjRoot` keeps the original tree for the next
+     * resolve. Unset when the two are the same (a deferred parse).
+     */
+    private readonly _pendingRoot;
     /** @internal ResolveOptions stored for the resolve() call. */
     private readonly _resolveOpts;
     constructor(root: HoconValue & {
@@ -245,6 +289,7 @@ declare class Config {
         parseBaseDir?: string;
         originDescription?: string;
         resObjRoot?: ResObj;
+        pendingRoot?: ResObj;
         resolveOpts?: ResolveOptions$1;
     });
     /** Returns true when the Config's value tree contains no unresolved
@@ -279,13 +324,87 @@ declare class Config {
      * cannot be represented. This matches `getConfig` / `getList`.
      */
     getValue(path: string): ReadonlyHoconValue | undefined;
+    /**
+     * The scalar at `path` as its text: a number or boolean comes back as written
+     * (`8080`, `true`).
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a scalar, or the value is
+     *   `null`.
+     */
     getString(path: string): string;
+    /**
+     * The scalar at `path` as a number. A string that reads as a decimal number
+     * (`"8080"`, `"1.5e3"`) is accepted.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a scalar, or the value is not a
+     *   number.
+     */
     getNumber(path: string): number;
+    /**
+     * The scalar at `path` as a boolean: `true` / `yes` / `on` and `false` /
+     * `no` / `off`, in any case.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a scalar, or the value is not one
+     *   of those words.
+     */
     getBoolean(path: string): boolean;
+    /**
+     * The duration at `path` in `unit` (default `ms`): a string with a unit
+     * (`"30s"`, `"1.5h"`), or a number or unit-less string, which is
+     * milliseconds. The number is read exactly and rounded once in `unit` (E20).
+     * Negative durations are allowed.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a string or number, the text is
+     *   not a duration, or the result is not a finite number (E21).
+     */
     getDuration(path: string, unit?: DurationUnit): number;
+    /**
+     * The byte size at `path` in `unit` (default `B`): a string with a unit
+     * (`"64KiB"`, `"1.5MB"`), or a number or unit-less string, which is bytes.
+     * The exact size is truncated toward zero to whole bytes, then converted to
+     * `unit` (E20).
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a string or number, the text is
+     *   not a byte size, the size is negative, or it exceeds 2^53-1 bytes (the
+     *   largest integer a JS number holds exactly).
+     */
     getBytes(path: string, unit?: ByteUnit): number;
+    /**
+     * The calendar period at `path` (`7d`, `2w`, `3m`, `1y`; a bare integer is
+     * days). Integer only, unlike {@link getDuration} / {@link getBytes}.
+     *
+     * @throws {@link NotResolvedError} when the value is an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a string or number, or the text
+     *   is not a period.
+     */
+    getPeriod(path: string): Period;
+    /**
+     * The object at `path` as a Config of its own, with paths relative to it.
+     *
+     * @throws {@link NotResolvedError} when the object holds an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not an object.
+     */
     getConfig(path: string): Config;
+    /**
+     * The list at `path` as plain values (see {@link get}). An object with integer
+     * keys (`"0"`, `"1"`, …) is read as a list too, in key order with gaps closed
+     * up; its other keys are ignored (S15).
+     *
+     * @throws {@link NotResolvedError} when the list holds an unresolved substitution.
+     * @throws {@link ConfigError} when `path` is missing or is not a list.
+     */
     getList(path: string): unknown[];
+    /**
+     * Whether `path` is present. A path whose value is still an unresolved
+     * substitution is present too (`true`, no throw), as in go.hocon; reading it
+     * throws {@link NotResolvedError}. A path *under* such a value is not known
+     * yet and answers `false`.
+     */
     has(path: string): boolean;
     keys(): string[];
     withFallback(fallback: Config | undefined): Config;
@@ -363,6 +482,28 @@ declare class Config {
     toObject(opts?: {
         nullPrototype?: boolean;
     }): unknown;
+    /**
+     * Renders this resolved Config as HOCON text (E18; lockstep with go.hocon's
+     * `Config.RenderHOCON`, v1.11.0).
+     *
+     * The output round-trips: parsing it back yields the same value tree. That
+     * is the correctness contract, not byte-for-byte formatting — a scalar is
+     * quoted whenever leaving it bare would re-parse as a different type (a
+     * string `"8080"` becomes `"8080"`, not `8080`), and left bare only when it
+     * provably cannot.
+     *
+     * The Config must be resolved and hold only data (objects, arrays, string /
+     * number / boolean / null scalars) — exactly what {@link fromMap} and the
+     * format adapters produce. An unresolved placeholder throws
+     * {@link ConfigError}; substitutions have no textual round trip through a
+     * value tree.
+     *
+     * The root object's fields are emitted without enclosing braces, nested
+     * objects as `key { … }`, arrays as newline-separated `[ … ]`, indented two
+     * spaces. Source comments are not represented — a value tree does not carry
+     * them.
+     */
+    renderHocon(): string;
     /**
      * @internal Test-only: renders this resolved Config's value tree as canonical
      * JSON (sorted keys, no whitespace). Used by Layer-2 fixture tests to compare
@@ -372,9 +513,12 @@ declare class Config {
      */
     _renderJSONForTest(): string;
     private lookupNode;
+    /** Whether `path` names a field in the unresolved tree (a placeholder included). */
+    private _unresolvedTreeHas;
     /**
-     * _resObjRootSubtreeHasPlaceholders — walk _resObjRoot to the given path and
-     * return true if the subtree there contains any unresolved placeholder.
+     * _subtreeHasPlaceholders — walk the unresolved tree (`_pendingRoot` after a
+     * partial resolve, else `_resObjRoot`) to the given path and return true if
+     * the subtree there contains any unresolved placeholder.
      * Used by getConfig / getList (T2) to detect transitive unresolved placeholders
      * in object / array subtrees that would otherwise appear to be "resolved" in the
      * partial HoconValue root (because individual leaf fields are omitted rather than
@@ -382,8 +526,8 @@ declare class Config {
      * sub-containers are retained in the partial root with the placeholder-keyed
      * fields omitted from them — so the object appears "present but empty-ish").
      */
-    private _resObjRootSubtreeHasPlaceholders;
+    private _subtreeHasPlaceholders;
     private requireScalar;
 }
 
-export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ReadonlyHoconValue as R, type ScalarValueType as S, type ParseOptions as a, type ResolveOptions as b, asArray as c, asBoolean as d, asNumber as e, asObject as f, asString as g, defaultParseOptions as h, defaultResolveOptions as i, isArray as j, isNull as k, isObject as l, isScalar as m, parseAsync as n, parseFile as o, parse as p, parseFileAsync as q, parseFileWithOptions as r, parseString as s, parseStringWithOptions as t };
+export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ReadonlyHoconValue as R, type ScalarValueType as S, type ParseOptions as a, type Period as b, type ResolveOptions as c, asArray as d, asBoolean as e, asNumber as f, asObject as g, asString as h, defaultParseOptions as i, defaultResolveOptions as j, isArray as k, isNull as l, isObject as m, isScalar as n, parseAsync as o, parse as p, parseFile as q, parseFileAsync as r, parseFileWithOptions as s, parseString as t, parseStringWithOptions as u };