@o3co/ts.hocon 1.13.0 → 1.14.1

package/dist/{config-6sApTEMM.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;
@@ -394,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
@@ -404,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 };