@o3co/ts.hocon 1.2.0 → 1.4.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@o3co/ts.hocon.svg)](https://www.npmjs.com/package/@o3co/ts.hocon)
 [![CI](https://github.com/o3co/ts.hocon/actions/workflows/test.yml/badge.svg)](https://github.com/o3co/ts.hocon/actions/workflows/test.yml)
-[![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/main/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
+[![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/develop/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
 [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) 仕様の TypeScript パーサー。現在の準拠率は [仕様準拠](#仕様準拠) を参照。
@@ -54,7 +54,9 @@ cfg.has('server.host')         // true
 | Trailing commas | N/A | No | N/A | Yes |
 | Unquoted strings | Yes | No | Yes | Yes |
 
-HOCON は YAML の可読性と JSON の構造性を兼ね備え、どちらにもない機能 — 変数参照、インクルード、ディープマージ — を提供します。設定がフラットなキーバリューペア以上のものであれば、HOCON を検討する価値があります。
+HOCON は単なるシリアライズ形式ではなく、**プログラムに注入するための設定言語** です。JSON / YAML / TOML はデータ構造の表現に徹しており、ファイルの重ね合わせ・環境変数・参照解決はアプリ側（Pydantic、Serde、Zod 等）の責務になります。HOCON はそれらを仕様そのものに内包しているため、プログラムが設定を受け取る時点で、フォールバックは合成済み・`${VAR}` 参照は解決済みの「1 枚の設定」になっています。「このレイヤーに値があるか？」に由来する条件分岐は、コードではなくフォーマット境界で消えます。
+
+加えて HOCON は YAML の可読性と JSON の構造性を兼ね備えるため、フラットなキーバリュー設定を超えるユースケースには強い選択肢になります。
 
 ## 特徴
 

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@o3co/ts.hocon.svg)](https://www.npmjs.com/package/@o3co/ts.hocon)
 [![CI](https://github.com/o3co/ts.hocon/actions/workflows/test.yml/badge.svg)](https://github.com/o3co/ts.hocon/actions/workflows/test.yml)
-[![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/main/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
+[![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/develop/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
 A [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) parser for TypeScript. See [Spec Compliance](#spec-compliance) for the current conformance rate.
@@ -58,7 +58,9 @@ cfg.has('server.host')         // true
 | Trailing commas | N/A | No | N/A | Yes |
 | Unquoted strings | Yes | No | Yes | Yes |
 
-HOCON gives you the readability of YAML, the structure of JSON, and features that neither has — substitutions, includes, and deep merge. If your config is more than a few flat key-value pairs, HOCON is worth considering.
+HOCON isn't just a serialization format — it's a **config-injection language**. JSON, YAML, and TOML describe data structures and leave file layering, environment variables, and reference resolution to your code (Pydantic, Serde, Zod, etc.). HOCON bakes those into the spec itself: by the time your program reads the config, fallback files are merged and `${VAR}` references resolved into a single composed object. Conditional branching from "is this value present in this layer?" disappears at the format boundary.
+
+On top of that, HOCON combines the readability of YAML with the structure of JSON — making it a strong fit for anything beyond flat key-value config.
 
 ## Features
 
@@ -103,18 +105,60 @@ parseFileAsync(path: string, opts?: ParseOptions): Promise<Config>
 | Method | Returns | Throws if |
 |--------|---------|-----------|
 | `get(path)` | `unknown \| undefined` | — |
-| `getString(path)` | `string` | missing, wrong type |
-| `getNumber(path)` | `number` | missing, wrong type |
-| `getBoolean(path)` | `boolean` | missing, wrong type |
-| `getConfig(path)` | `Config` | missing, not an object |
-| `getList(path)` | `unknown[]` | missing, not an array |
+| `getString(path)` | `string` | missing, wrong type, or unresolved |
+| `getNumber(path)` | `number` | missing, wrong type, or unresolved |
+| `getBoolean(path)` | `boolean` | missing, wrong type, or unresolved |
+| `getConfig(path)` | `Config` | missing, not an object, or unresolved |
+| `getList(path)` | `unknown[]` | missing, not an array, or unresolved |
 | `getDuration(path, unit?)` | `number` | missing, not a string, or invalid duration format |
 | `getBytes(path, unit?)` | `number` | missing, not a string, or invalid byte size format |
 | `has(path)` | `boolean` | — |
 | `keys()` | `string[]` | — |
 | `withFallback(fallback)` | `Config` | — |
+| `resolve(opts?)` | `Config` | unresolvable substitution (unless `allowUnresolved: true`) |
+| `resolveWith(source, opts?)` | `Config` | source unresolved, or unresolvable substitution |
+| `isResolved()` | `boolean` | — |
 | `toObject()` | `unknown` | — |
 
+### Deferred resolution API (E12)
+
+Separate the parse, fallback-layering, and resolve steps for runtime config injection.
+
+```ts
+import { parseStringWithOptions, fromMap, empty } from '@o3co/ts.hocon'
+import type { ResolveOptions } from '@o3co/ts.hocon'
+
+// 1. Parse without resolving — substitutions deferred
+const cfg = parseStringWithOptions(
+  'version = ${shortversion}-${CI_RUN_NUMBER}\nvariables { shortversion = "1.2.3" }',
+  { resolveSubstitutions: false }
+)
+cfg.isResolved() // false — ${CI_RUN_NUMBER} still pending
+
+// 2. Layer runtime fallbacks
+const runtime = fromMap({ CI_RUN_NUMBER: '42' })
+const vars = cfg.getConfig('variables')   // already available (not a substitution)
+const merged = cfg.withFallback(runtime).withFallback(vars)
+
+// 3. Resolve the full fallback stack
+const resolved = merged.resolve({ useSystemEnvironment: false })
+resolved.getString('version') // "1.2.3-42"
+
+// resolveWith: resolve receiver using source for lookup, source keys NOT in result
+const receiver = parseStringWithOptions('r = ${key}', { resolveSubstitutions: false })
+const source = fromMap({ key: 'val' })
+const result = receiver.resolveWith(source)
+result.has('key')    // false — source keys excluded
+result.getString('r') // "val"
+```
+
+`ResolveOptions`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `useSystemEnvironment` | `boolean` | `true` | Consult `process.env` for substitution fallback |
+| `allowUnresolved` | `boolean` | `false` | Leave unresolvable substitutions in place (no error) |
+
 ### Zod integration
 
 ```ts
@@ -214,7 +258,14 @@ Conformance against the [Lightbend HOCON specification](https://github.com/light
 | In-scope only                         | **83.3%**     |
 | Lightbend `test01`–`test13` suite     | 13/13 passing |
 
-Not supported in v0.1.0:
+**Extra-spec conventions (E-series) — implementation status:**
+
+| Item | Description | Status |
+|------|-------------|--------|
+| E11  | `include package(...)` service-locator includes | ✅ v1.3.0 |
+| E12  | Deferred substitution resolution (`parse → withFallback → resolve()` lifecycle) | ✅ v1.4.0 |
+
+Not supported:
 
 - `include url(...)`
 - `include classpath(...)`

package/dist/config-BwjvKeZ5.d.cts

@@ -0,0 +1,271 @@
+type DurationUnit = 'ns' | 'us' | 'ms' | 's' | 'm' | 'h' | 'd';
+type ByteUnit = 'B' | 'KB' | 'KiB' | 'MB' | 'MiB' | 'GB' | 'GiB' | 'TB' | 'TiB';
+
+type ScalarValueType = 'string' | 'number' | 'boolean' | 'null';
+type HoconValue = {
+    kind: 'object';
+    fields: Map<string, HoconValue>;
+} | {
+    kind: 'array';
+    items: HoconValue[];
+} | {
+    kind: 'scalar';
+    raw: string;
+    valueType: ScalarValueType;
+};
+
+interface Segment {
+    readonly text: string;
+    readonly line: number;
+    readonly col: number;
+}
+
+type SubstPlaceholder = {
+    _kind: 'subst-placeholder';
+    segments: Segment[];
+    optional: boolean;
+    listSuffix: boolean;
+    line: number;
+    col: number;
+    prefixLen: number;
+};
+type ConcatPlaceholder = {
+    _kind: 'concat-placeholder';
+    nodes: ResolverValue[];
+    /** 1-based line of the concat value in the source file (from AST Concat pos). */
+    line: number;
+    /** 1-based column of the concat value in the source file (from AST Concat pos). */
+    col: number;
+};
+type AppendPlaceholder = {
+    _kind: 'append-placeholder';
+    existing: ResolverValue;
+    elem: ResolverValue;
+};
+type ResObj = {
+    _kind: 'res-obj';
+    fields: Map<string, ResolverValue>;
+    priorValues: Map<string, ResolverValue>;
+};
+type ResolverValue = HoconValue | SubstPlaceholder | ConcatPlaceholder | AppendPlaceholder | ResObj;
+/**
+ * Custom resolver for `include package("id", "file")`.
+ *
+ * Receives:
+ * - `identifier`, `file`: the qualifier arguments (post HOCON unescape, byte-exact)
+ * - `includingFile`: absolute path of the including `.conf` file when known
+ *   (currently always `undefined`; reserved for future threading from a future
+ *   `parseFile` integration)
+ * - `baseDir`: the directory context active when the include is resolved
+ *   (typically `path.dirname(includingFile)` of the parent, or the caller-set
+ *   `baseDir` parse option). Set when known, `undefined` for parses of literal
+ *   input strings without a directory context.
+ *
+ * Must return an absolute path or throw.
+ *
+ * When not provided, the default resolver uses `createRequire(import.meta.url)`
+ * which works in both CJS and ESM Node contexts. The default resolver picks the
+ * lookup starting paths in priority order:
+ *   `resolveFrom` > `baseDir` > `path.dirname(includingFile)` > `process.cwd()`
+ */
+type PackageResolver = (identifier: string, file: string, includingFile: string | undefined, baseDir: string | undefined) => string;
+type ResolveOptions$1 = {
+    env: Record<string, string>;
+    baseDir: string | undefined;
+    readFileSync: (filePath: string) => string;
+    readFile?: (filePath: string) => Promise<string>;
+    includeStack?: string[];
+    /** Override the starting directory for `require.resolve` used by the default package resolver. */
+    resolveFrom?: string | string[];
+    /** Custom resolver for `include package(...)`. When provided, takes full control; `resolveFrom` is ignored. */
+    packageResolver?: PackageResolver;
+    /**
+     * When false (default), env var lookups inside SubstitutionResolver are
+     * suppressed. Set to true to preserve the current fused-resolve behaviour
+     * where process.env is consulted as fallback. Phase-2 callers (resolveTree)
+     * receive this flag explicitly; the fused resolve() path passes true for
+     * backward compat.
+     *
+     * E12 ResolveOptions.useSystemEnvironment.
+     */
+    useSystemEnvironment?: boolean;
+    /**
+     * When true, leaves unresolved (non-optional) substitution placeholders in
+     * place instead of throwing ResolveError. Phase 2 only; ignored by buildTree.
+     *
+     * E12 ResolveOptions.allowUnresolved.
+     */
+    allowUnresolved?: boolean;
+    /**
+     * Human-readable origin for error messages (e.g. file name or description).
+     * When set, ResolveError messages include this as a prefix to help callers
+     * identify which config source caused the error.
+     *
+     * E12 origin preservation.
+     */
+    originDescription?: string;
+};
+
+type ParseOptions = {
+    baseDir?: string;
+    env?: Record<string, string>;
+    readFile?: (filePath: string) => Promise<string>;
+    readFileSync?: (filePath: string) => string;
+    /** When true (default), run substitution resolution after parse. When false,
+     *  return an unresolved Config with placeholders intact. E12 §"ParseOptions". */
+    resolveSubstitutions?: boolean;
+    /** Source name surfaced in error messages when no file path is available. E12. */
+    originDescription?: string;
+    /**
+     * Override the starting directory (or directories) used when resolving
+     * `include package("id", "file")` via Node module resolution.
+     *
+     * Default: `path.dirname(includingConfFile)` when known, `process.cwd()` otherwise.
+     * Ignored when `packageResolver` is also provided.
+     */
+    resolveFrom?: string | string[];
+    /**
+     * Custom resolver for `include package("id", "file")`.
+     * See {@link PackageResolver} for the full callback signature and contract
+     * (parameters, lookup-starting-path priority, error semantics).
+     *
+     * When provided, takes full control of resolution; `resolveFrom` is ignored.
+     * Use this for Yarn Berry PnP, bundler contexts, edge runtimes, or test isolation.
+     *
+     * Note: on macOS/Windows (case-insensitive filesystems), the default resolver may
+     * resolve case-insensitively for intermediate path segments. Use a custom
+     * `packageResolver` for strict cross-platform enforcement.
+     */
+    packageResolver?: PackageResolver;
+};
+type ResolveOptions = {
+    /** When true (default), env var lookups are available during resolve. E12. */
+    useSystemEnvironment?: boolean;
+    /** When true, leaves unresolved non-optional substitutions in place instead
+     *  of throwing ResolveError. Default false. E12. */
+    allowUnresolved?: boolean;
+};
+/** Returns a ParseOptions object with Lightbend-aligned defaults:
+ *  resolveSubstitutions=true, originDescription=undefined. */
+declare function defaultParseOptions(): Required<Pick<ParseOptions, 'resolveSubstitutions'>> & ParseOptions;
+/** Returns a ResolveOptions object with Lightbend-aligned defaults:
+ *  useSystemEnvironment=true, allowUnresolved=false. */
+declare function defaultResolveOptions(): Required<ResolveOptions>;
+declare function parse(input: string, opts?: ParseOptions): Config;
+/** Lightbend-aligned alias for parse(). Produces a fully resolved Config. */
+declare const parseString: typeof parse;
+/** Parse a HOCON string with explicit options. When opts.resolveSubstitutions
+ *  is false, returns an unresolved Config with substitution placeholders intact.
+ *  Use Config.resolve() or Config.resolveWith() to complete resolution later. */
+declare function parseStringWithOptions(input: string, opts?: ParseOptions): Config;
+/** Parse a HOCON file with explicit options. */
+declare function parseFileWithOptions(filePath: string, opts?: ParseOptions): Config;
+/**
+ * Truly async version of `parse()`. Include directives are resolved
+ * asynchronously via `readFile` when provided.
+ */
+declare function parseAsync(input: string, opts?: ParseOptions): Promise<Config>;
+declare function parseFile(filePath: string, opts?: ParseOptions): Config;
+declare function parseFileAsync(filePath: string, opts?: ParseOptions): Promise<Config>;
+
+declare class Config {
+    private readonly root;
+    /** @internal resolved flag: true when no substitution placeholders remain. */
+    private readonly _resolved;
+    /** @internal base directory for re-runs (file-parsed configs). */
+    readonly _parseBaseDir: string | undefined;
+    /** @internal origin description for error messages. */
+    readonly _originDescription: string | undefined;
+    /** @internal ResObj tree for deferred-resolution path. Set when resolved=false. */
+    readonly _resObjRoot: ResObj | undefined;
+    /** @internal ResolveOptions stored for the resolve() call. */
+    private readonly _resolveOpts;
+    constructor(root: HoconValue & {
+        kind: 'object';
+    }, opts?: {
+        resolved?: boolean;
+        parseBaseDir?: string;
+        originDescription?: string;
+        resObjRoot?: ResObj;
+        resolveOpts?: ResolveOptions$1;
+    });
+    /** Returns true when the Config's value tree contains no unresolved
+     *  substitution placeholders. Whole-config granularity (E12 decision 11). */
+    isResolved(): boolean;
+    /** @internal Test-only: construct a resolved Config from a HoconValue. */
+    static _fromResolvedValue(root: HoconValue & {
+        kind: 'object';
+    }, opts?: {
+        originDescription?: string;
+    }): Config;
+    /** @internal Construct an unresolved Config carrying a ResObj tree.
+     *  Used by parseStringWithOptions (deferred path) in T6. */
+    static _fromUnresolvedResObj(tree: ResObj, opts: {
+        parseBaseDir?: string;
+        originDescription?: string;
+        resolved: boolean;
+        resolveOpts: ResolveOptions$1;
+    }): Config;
+    get(path: string): unknown;
+    getString(path: string): string;
+    getNumber(path: string): number;
+    getBoolean(path: string): boolean;
+    getDuration(path: string, unit?: DurationUnit): number;
+    getBytes(path: string, unit?: ByteUnit): number;
+    getConfig(path: string): Config;
+    getList(path: string): unknown[];
+    has(path: string): boolean;
+    keys(): string[];
+    withFallback(fallback: Config | undefined): Config;
+    /**
+     * Runs substitution resolution (phase 2) on the stored unresolved tree.
+     * Idempotent: calling resolve() on an already-resolved Config returns an
+     * equivalent resolved Config.
+     *
+     * opts.allowUnresolved (default false) — when true, leaves unresolved
+     * non-optional placeholders in place rather than throwing.
+     * opts.useSystemEnvironment (default true) — when false, env var lookups
+     * are suppressed (hermetic resolution).
+     *
+     * E12 decision 3.
+     */
+    resolve(opts?: ResolveOptions): Config;
+    /**
+     * Resolves receiver substitutions using source as lookup context.
+     * Source's keys are NOT merged into the result — differs from
+     * `this.withFallback(source).resolve()` which includes source keys.
+     *
+     * Precondition (E12 decision 10): source must be resolved. If
+     * source.isResolved() is false, throws NotResolvedError.
+     *
+     * On an already-resolved receiver, resolveWith is a no-op (returns an
+     * equivalent resolved Config, source keys not included).
+     *
+     * E12 decisions 9, 10.
+     */
+    resolveWith(source: Config, opts?: ResolveOptions): Config;
+    toObject(): unknown;
+    /**
+     * @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
+     * against Lightbend ground truth. NOT part of the public API.
+     *
+     * Throws if the Config is unresolved (contains placeholders).
+     */
+    _renderJSONForTest(): string;
+    private lookupNode;
+    /**
+     * _resObjRootSubtreeHasPlaceholders — walk _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
+     * the whole subtree when their value is a direct placeholder scalar, but object
+     * 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 requireScalar;
+}
+
+export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ResolveOptions as R, type ScalarValueType as S, type ParseOptions as a, defaultResolveOptions as b, parseAsync as c, defaultParseOptions as d, parseFile as e, parseFileAsync as f, parseFileWithOptions as g, parseString as h, parseStringWithOptions as i, parse as p };

package/dist/config-BwjvKeZ5.d.ts

@@ -0,0 +1,271 @@
+type DurationUnit = 'ns' | 'us' | 'ms' | 's' | 'm' | 'h' | 'd';
+type ByteUnit = 'B' | 'KB' | 'KiB' | 'MB' | 'MiB' | 'GB' | 'GiB' | 'TB' | 'TiB';
+
+type ScalarValueType = 'string' | 'number' | 'boolean' | 'null';
+type HoconValue = {
+    kind: 'object';
+    fields: Map<string, HoconValue>;
+} | {
+    kind: 'array';
+    items: HoconValue[];
+} | {
+    kind: 'scalar';
+    raw: string;
+    valueType: ScalarValueType;
+};
+
+interface Segment {
+    readonly text: string;
+    readonly line: number;
+    readonly col: number;
+}
+
+type SubstPlaceholder = {
+    _kind: 'subst-placeholder';
+    segments: Segment[];
+    optional: boolean;
+    listSuffix: boolean;
+    line: number;
+    col: number;
+    prefixLen: number;
+};
+type ConcatPlaceholder = {
+    _kind: 'concat-placeholder';
+    nodes: ResolverValue[];
+    /** 1-based line of the concat value in the source file (from AST Concat pos). */
+    line: number;
+    /** 1-based column of the concat value in the source file (from AST Concat pos). */
+    col: number;
+};
+type AppendPlaceholder = {
+    _kind: 'append-placeholder';
+    existing: ResolverValue;
+    elem: ResolverValue;
+};
+type ResObj = {
+    _kind: 'res-obj';
+    fields: Map<string, ResolverValue>;
+    priorValues: Map<string, ResolverValue>;
+};
+type ResolverValue = HoconValue | SubstPlaceholder | ConcatPlaceholder | AppendPlaceholder | ResObj;
+/**
+ * Custom resolver for `include package("id", "file")`.
+ *
+ * Receives:
+ * - `identifier`, `file`: the qualifier arguments (post HOCON unescape, byte-exact)
+ * - `includingFile`: absolute path of the including `.conf` file when known
+ *   (currently always `undefined`; reserved for future threading from a future
+ *   `parseFile` integration)
+ * - `baseDir`: the directory context active when the include is resolved
+ *   (typically `path.dirname(includingFile)` of the parent, or the caller-set
+ *   `baseDir` parse option). Set when known, `undefined` for parses of literal
+ *   input strings without a directory context.
+ *
+ * Must return an absolute path or throw.
+ *
+ * When not provided, the default resolver uses `createRequire(import.meta.url)`
+ * which works in both CJS and ESM Node contexts. The default resolver picks the
+ * lookup starting paths in priority order:
+ *   `resolveFrom` > `baseDir` > `path.dirname(includingFile)` > `process.cwd()`
+ */
+type PackageResolver = (identifier: string, file: string, includingFile: string | undefined, baseDir: string | undefined) => string;
+type ResolveOptions$1 = {
+    env: Record<string, string>;
+    baseDir: string | undefined;
+    readFileSync: (filePath: string) => string;
+    readFile?: (filePath: string) => Promise<string>;
+    includeStack?: string[];
+    /** Override the starting directory for `require.resolve` used by the default package resolver. */
+    resolveFrom?: string | string[];
+    /** Custom resolver for `include package(...)`. When provided, takes full control; `resolveFrom` is ignored. */
+    packageResolver?: PackageResolver;
+    /**
+     * When false (default), env var lookups inside SubstitutionResolver are
+     * suppressed. Set to true to preserve the current fused-resolve behaviour
+     * where process.env is consulted as fallback. Phase-2 callers (resolveTree)
+     * receive this flag explicitly; the fused resolve() path passes true for
+     * backward compat.
+     *
+     * E12 ResolveOptions.useSystemEnvironment.
+     */
+    useSystemEnvironment?: boolean;
+    /**
+     * When true, leaves unresolved (non-optional) substitution placeholders in
+     * place instead of throwing ResolveError. Phase 2 only; ignored by buildTree.
+     *
+     * E12 ResolveOptions.allowUnresolved.
+     */
+    allowUnresolved?: boolean;
+    /**
+     * Human-readable origin for error messages (e.g. file name or description).
+     * When set, ResolveError messages include this as a prefix to help callers
+     * identify which config source caused the error.
+     *
+     * E12 origin preservation.
+     */
+    originDescription?: string;
+};
+
+type ParseOptions = {
+    baseDir?: string;
+    env?: Record<string, string>;
+    readFile?: (filePath: string) => Promise<string>;
+    readFileSync?: (filePath: string) => string;
+    /** When true (default), run substitution resolution after parse. When false,
+     *  return an unresolved Config with placeholders intact. E12 §"ParseOptions". */
+    resolveSubstitutions?: boolean;
+    /** Source name surfaced in error messages when no file path is available. E12. */
+    originDescription?: string;
+    /**
+     * Override the starting directory (or directories) used when resolving
+     * `include package("id", "file")` via Node module resolution.
+     *
+     * Default: `path.dirname(includingConfFile)` when known, `process.cwd()` otherwise.
+     * Ignored when `packageResolver` is also provided.
+     */
+    resolveFrom?: string | string[];
+    /**
+     * Custom resolver for `include package("id", "file")`.
+     * See {@link PackageResolver} for the full callback signature and contract
+     * (parameters, lookup-starting-path priority, error semantics).
+     *
+     * When provided, takes full control of resolution; `resolveFrom` is ignored.
+     * Use this for Yarn Berry PnP, bundler contexts, edge runtimes, or test isolation.
+     *
+     * Note: on macOS/Windows (case-insensitive filesystems), the default resolver may
+     * resolve case-insensitively for intermediate path segments. Use a custom
+     * `packageResolver` for strict cross-platform enforcement.
+     */
+    packageResolver?: PackageResolver;
+};
+type ResolveOptions = {
+    /** When true (default), env var lookups are available during resolve. E12. */
+    useSystemEnvironment?: boolean;
+    /** When true, leaves unresolved non-optional substitutions in place instead
+     *  of throwing ResolveError. Default false. E12. */
+    allowUnresolved?: boolean;
+};
+/** Returns a ParseOptions object with Lightbend-aligned defaults:
+ *  resolveSubstitutions=true, originDescription=undefined. */
+declare function defaultParseOptions(): Required<Pick<ParseOptions, 'resolveSubstitutions'>> & ParseOptions;
+/** Returns a ResolveOptions object with Lightbend-aligned defaults:
+ *  useSystemEnvironment=true, allowUnresolved=false. */
+declare function defaultResolveOptions(): Required<ResolveOptions>;
+declare function parse(input: string, opts?: ParseOptions): Config;
+/** Lightbend-aligned alias for parse(). Produces a fully resolved Config. */
+declare const parseString: typeof parse;
+/** Parse a HOCON string with explicit options. When opts.resolveSubstitutions
+ *  is false, returns an unresolved Config with substitution placeholders intact.
+ *  Use Config.resolve() or Config.resolveWith() to complete resolution later. */
+declare function parseStringWithOptions(input: string, opts?: ParseOptions): Config;
+/** Parse a HOCON file with explicit options. */
+declare function parseFileWithOptions(filePath: string, opts?: ParseOptions): Config;
+/**
+ * Truly async version of `parse()`. Include directives are resolved
+ * asynchronously via `readFile` when provided.
+ */
+declare function parseAsync(input: string, opts?: ParseOptions): Promise<Config>;
+declare function parseFile(filePath: string, opts?: ParseOptions): Config;
+declare function parseFileAsync(filePath: string, opts?: ParseOptions): Promise<Config>;
+
+declare class Config {
+    private readonly root;
+    /** @internal resolved flag: true when no substitution placeholders remain. */
+    private readonly _resolved;
+    /** @internal base directory for re-runs (file-parsed configs). */
+    readonly _parseBaseDir: string | undefined;
+    /** @internal origin description for error messages. */
+    readonly _originDescription: string | undefined;
+    /** @internal ResObj tree for deferred-resolution path. Set when resolved=false. */
+    readonly _resObjRoot: ResObj | undefined;
+    /** @internal ResolveOptions stored for the resolve() call. */
+    private readonly _resolveOpts;
+    constructor(root: HoconValue & {
+        kind: 'object';
+    }, opts?: {
+        resolved?: boolean;
+        parseBaseDir?: string;
+        originDescription?: string;
+        resObjRoot?: ResObj;
+        resolveOpts?: ResolveOptions$1;
+    });
+    /** Returns true when the Config's value tree contains no unresolved
+     *  substitution placeholders. Whole-config granularity (E12 decision 11). */
+    isResolved(): boolean;
+    /** @internal Test-only: construct a resolved Config from a HoconValue. */
+    static _fromResolvedValue(root: HoconValue & {
+        kind: 'object';
+    }, opts?: {
+        originDescription?: string;
+    }): Config;
+    /** @internal Construct an unresolved Config carrying a ResObj tree.
+     *  Used by parseStringWithOptions (deferred path) in T6. */
+    static _fromUnresolvedResObj(tree: ResObj, opts: {
+        parseBaseDir?: string;
+        originDescription?: string;
+        resolved: boolean;
+        resolveOpts: ResolveOptions$1;
+    }): Config;
+    get(path: string): unknown;
+    getString(path: string): string;
+    getNumber(path: string): number;
+    getBoolean(path: string): boolean;
+    getDuration(path: string, unit?: DurationUnit): number;
+    getBytes(path: string, unit?: ByteUnit): number;
+    getConfig(path: string): Config;
+    getList(path: string): unknown[];
+    has(path: string): boolean;
+    keys(): string[];
+    withFallback(fallback: Config | undefined): Config;
+    /**
+     * Runs substitution resolution (phase 2) on the stored unresolved tree.
+     * Idempotent: calling resolve() on an already-resolved Config returns an
+     * equivalent resolved Config.
+     *
+     * opts.allowUnresolved (default false) — when true, leaves unresolved
+     * non-optional placeholders in place rather than throwing.
+     * opts.useSystemEnvironment (default true) — when false, env var lookups
+     * are suppressed (hermetic resolution).
+     *
+     * E12 decision 3.
+     */
+    resolve(opts?: ResolveOptions): Config;
+    /**
+     * Resolves receiver substitutions using source as lookup context.
+     * Source's keys are NOT merged into the result — differs from
+     * `this.withFallback(source).resolve()` which includes source keys.
+     *
+     * Precondition (E12 decision 10): source must be resolved. If
+     * source.isResolved() is false, throws NotResolvedError.
+     *
+     * On an already-resolved receiver, resolveWith is a no-op (returns an
+     * equivalent resolved Config, source keys not included).
+     *
+     * E12 decisions 9, 10.
+     */
+    resolveWith(source: Config, opts?: ResolveOptions): Config;
+    toObject(): unknown;
+    /**
+     * @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
+     * against Lightbend ground truth. NOT part of the public API.
+     *
+     * Throws if the Config is unresolved (contains placeholders).
+     */
+    _renderJSONForTest(): string;
+    private lookupNode;
+    /**
+     * _resObjRootSubtreeHasPlaceholders — walk _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
+     * the whole subtree when their value is a direct placeholder scalar, but object
+     * 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 requireScalar;
+}
+
+export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ResolveOptions as R, type ScalarValueType as S, type ParseOptions as a, defaultResolveOptions as b, parseAsync as c, defaultParseOptions as d, parseFile as e, parseFileAsync as f, parseFileWithOptions as g, parseString as h, parseStringWithOptions as i, parse as p };