@o3co/ts.hocon 1.10.0 → 1.11.0

package/README.ja.md

@@ -24,6 +24,20 @@ npm install @o3co/ts.hocon
 
 Node.js 22 以上が必要です。
 
+ESM / CJS の両方に対応しています。`import` でも `require` でも同じエントリポイント
+（`adapters/*` のサブパスを含む）に到達します:
+
+```ts
+import { parse } from '@o3co/ts.hocon'          // ESM
+const { parse } = require('@o3co/ts.hocon')     // CJS
+```
+
+CI では PR ごと・リリースごとに、ビルド成果物に対して 7 つの export すべてを両形式で
+ロードし、実際に呼び出し（バンドル形式で挙動が変わる package include を含む）、各条件が
+自前の型定義を宣言しているかまで検証します。1.10.0 で CJS の 7 エントリポイントすべてが
+ロード時に例外を投げた実績があるためのゲートであり、この種の欠陥を検出するものです
+（あらゆる欠陥が起こり得ないという保証ではありません）。
+
 ### 2. 使い方
 
 ```ts
@@ -67,7 +81,7 @@ HOCON は単なるシリアライズ形式ではなく、**プログラムに注
 - `include "file.conf"` および `include file("file.conf")` ディレクティブ
 - トリプルクォート文字列（`"""..."""`）
 - 同期・非同期 API（`parse` / `parseAsync` / `parseFile` / `parseFileAsync`）
-- ESM + CJS デュアルパッケージ
+- ESM + CJS デュアルパッケージ（全エントリポイントを CI で両形式ロード検証）
 - [Zod](https://zod.dev/) スキーマバリデーション統合（オプション）
 - ブラウザ対応（`parse`/`parseAsync` — Node.js 不要）
 
@@ -268,6 +282,16 @@ const cfg = await parseAsync(hoconString, {
 - **`${ENV}` の使用を最小限に**: 設定ファイル自体にデフォルト値を定義し、`${?ENV}`（オプショナル）を使いましょう
 - **ローカル開発で環境変数を必須にしない**: デフォルトだけで動くようにしましょう
 - **必須の環境変数を文書化**: プロジェクトの README や `.env.example` にリストしましょう
+- **変数名の階層は `.` ではなく `__` で**: `loadEnv`（および `parseDotEnv`）で一括マウント
+  するとき、階層を作るのは `__` **だけ** です。`.` は通常のキー文字なので、次の 2 つは
+  別々のキーであり、どちらも失われません:
+
+  ```text
+  APP_FOO__BAR=nested   # -> foo.bar      : cfg.getString('foo.bar')
+  APP_FOO.BAR=dotted    # -> "foo.bar"    : cfg.getString('"foo.bar"')
+  ```
+
+  単独の `_` もセグメントの一部のままです（`APP_DB__MAX_CONN` → `db.max_conn`）。
 
 ### 開発 / 本番の分離
 
@@ -304,6 +328,110 @@ const config = parseWithSchema(hoconInput, schema) // 起動時に即座に失
 
 3 つのパーサー実装（[ts.hocon](https://github.com/o3co/ts.hocon)、[rs.hocon](https://github.com/o3co/rs.hocon)、[go.hocon](https://github.com/o3co/go.hocon)）はすべて同じ Lightbend HOCON 仕様で追跡されています — 実装ごとの準拠率は [横断ロールアップ](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) を参照してください。
 
+## フォーマットアダプタ
+
+*他のプログラム* が所有する設定ファイルを HOCON としてマウントできます。自分の
+ドキュメント内の `${...}` からその内容を参照できるようになります:
+
+```ts
+import { parseStringWithOptions } from '@o3co/ts.hocon'
+import { loadEnv } from '@o3co/ts.hocon/adapters/env'
+
+const base = loadEnv({ prefix: 'APP_' })            // APP_DB__HOST -> db.host
+const cfg = parseStringWithOptions(src, { resolveSubstitutions: false })
+const merged = cfg.withFallback(base).resolve()
+```
+
+解決を遅延させることが重要です。素の `parse` はパースしながら解決するため、
+フォールバックを付ける前に `${...}` の解決が失敗してしまいます。
+
+| サブパス | 必要な依存 | 備考 |
+| --- | --- | --- |
+| `@o3co/ts.hocon/adapters/properties` | — | `java.util.Properties`。`include` と構文レイヤーを共有 |
+| `@o3co/ts.hocon/adapters/env` | — | プレフィックス付き名前空間の一括マウント。`.env` の読み込みも可能 |
+| `@o3co/ts.hocon/adapters/jsonc` | — | コメントと末尾カンマを許す JSON |
+| `@o3co/ts.hocon/adapters/toml` | `smol-toml` | オプショナルなピア依存 |
+| `@o3co/ts.hocon/adapters/yaml` | `yaml` 2.9.x | オプショナルなピア依存。スカラー解決はそのライブラリの答えで、`version: '1.2'` を明示してドリフトを防止 |
+
+TOML と YAML のライブラリは **オプショナルなピア依存** なので、本パッケージを入れても
+何も追加でインストールされません — 実際に使うものだけを足してください。プレーンな JSON に
+アダプタは不要です（HOCON は JSON のスーパーセットです）。
+
+外部のデータはあくまでデータです。マウントされた値の中の `${a.b}` は参照ではなく
+リテラルなテキストとして扱われます。そのファイルは HOCON の構文に同意していない
+プログラムのものだからです。
+
+### 環境変数名の付け方
+
+パス区切りは `__` だけです。変数名の中の `.` は境界ではなくキー文字なので、
+`APP_FOO.BAR` と `APP_FOO__BAR` は別のキーであり、同時に設定できます:
+
+```ts
+const cfg = loadEnv({ prefix: 'APP_', env: { 'APP_FOO.BAR': 'dotted', APP_FOO__BAR: 'nested' } })
+cfg.getString('"foo.bar"')   // "dotted"  — 名前にドットを含む 1 つのキー
+cfg.getString('foo.bar')     // "nested"  — foo -> bar
+```
+
+### JSONC / YAML の数値
+
+整数は精度を落とさずに取り込まれます。JS の `number` で表せない幅の整数リテラルも
+桁がそのまま保持され、int64 の範囲を超える値は黙って壊れる代わりにエラーになります。
+取得結果はゲッターによって変わります:
+
+```ts
+const cfg = parseJsonc('{"id": 9007199254740993}')
+cfg.getString('id')   // "9007199254740993"  — ソースそのままの正確な値
+cfg.getNumber('id')   // 9007199254740992    — JS の数値モデルで丸められる
+cfg.toObject()        // { id: 9007199254740992 }
+```
+
+したがって大きな識別子（snowflake ID、台帳の連番など）は `getString` で読んでください。
+`getNumber` と `toObject` は JavaScript の数値セマンティクスをそのまま適用します
+（HOCON テキストに同じリテラルを書いた場合と同じ挙動です）。保証されるのは
+**取り込み時に情報が失われない** ことです。
+
+YAML のスカラー解決はそれ以外の点では `yaml` ライブラリのものです。アダプタは
+デフォルト任せにせず `version: '1.2'` を明示し、`fromYamlValue` はデコード済みの
+ツリーを受け取るため、別のライブラリやスキーマを使うこともできます。
+
+## 既知の制限
+
+- **`include url(...)`** は未対応です。リモート設定の取得はこのパーサーの範囲外です。アプリの HTTP クライアントで取得してから `parse()` に渡してください。
+- **`include classpath(...)`** は未対応です。JVM 固有の include 形式で、Java ランタイム以外に対応物がありません。
+- **watch / reload なし** — ライブラリはロード時にパースするだけです。ライブリロードが必要なら変更時に `parse()` / `parseFile()` を呼び直してください。
+- **ストリーミングパーサーなし** — 入力全体をメモリに載せます。非常に大きな設定はパース前にサイズを検証してください（セキュリティ上の考慮事項を参照）。
+
+## セキュリティ上の考慮事項
+
+信頼できない HOCON 入力をパースする際は次に注意してください:
+
+- **include のパストラバーサル:** 相対 `include` パスは `baseDir` から解決され、`..` セグメントで外に出て `/etc/passwd` のような機密ファイルに到達し得ます。信頼できない入力をパースするなら、パスを検証するカスタム `readFileSync`/`readFile` を渡してください。
+- **入力サイズ:** パーサーに入力サイズ上限はありません。信頼できない入力は `parse()` の前にサイズを検証してください。
+- **include の深さ:** 深い include 連鎖によるスタックオーバーフローを防ぐため 50 段に制限されています。
+- **プロトタイプ汚染:** `__proto__` / `constructor` / `prototype` という名前のキーは
+  **通常のキーとして保持されます**。`.properties` ファイルや環境変数がそれらを正当に
+  使っていることがあり、落とせば黙ったデータ欠落になるからです。ライブラリ内部の安全性は
+  拒否リストではなく構造で担保しています。ネスト構築には `__proto__` セッターを継承しない
+  null プロトタイプのオブジェクトを使い、各アダプタと `toObject()` はキーを own データ
+  プロパティとして定義します。パース自体は何も汚染せず、返るオブジェクトのプロトタイプは
+  常に `Object.prototype` です。
+
+  **重要なのは結果をどう扱うか** です。設定データが own な `__proto__` キーを持ち得ます:
+
+  ```ts
+  const data = cfg.toObject()
+  { ...data }             // 安全
+  structuredClone(data)   // 安全
+  Object.assign({}, data) // 危険 — キーが消え、設定データがコピー先のプロトタイプになる
+  deepMerge({}, data)     // 危険 — 素朴な再帰マージはグローバルな Object.prototype に書き込み得る
+  ```
+
+  いずれも **コピー先** オブジェクトのプロトタイプに起因するため、避けるのは利用側の責務です。
+  コピーはスプレッドか `structuredClone`、走査は `Object.entries()` / `Object.keys()` を使い、
+  `__proto__` を通常のキー名として扱ってください。制御下にない場所へ渡す場合は
+  `cfg.toObject({ nullPrototype: true })` が何も継承しないツリーを返します（ただし利用側が
+  素の `{}` にコピーする場合の問題までは解消できません）。
+
 ## ライセンス
 
 Apache License 2.0 — [LICENSE](LICENSE) を参照。

package/README.md

@@ -28,6 +28,21 @@ npm install @o3co/ts.hocon
 
 Requires Node.js 22+.
 
+Both module systems are supported — `import` and `require` reach the same
+entrypoints, including every `adapters/*` subpath:
+
+```ts
+import { parse } from '@o3co/ts.hocon'          // ESM
+const { parse } = require('@o3co/ts.hocon')     // CJS
+```
+
+On every PR and every release, CI loads all seven exports both ways against the
+built artifact, calls each one (including a package-scoped `include`, which
+behaves differently per bundle format), and checks that each condition declares
+its own type declarations. That gate exists because 1.10.0 shipped with all
+seven CJS entrypoints throwing at load; it catches that class of defect rather
+than promising none can exist.
+
 ### 2. Use
 
 ```ts
@@ -72,7 +87,7 @@ On top of that, HOCON combines the readability of YAML with the structure of JSO
 - Triple-quoted strings (`"""..."""`)
 - Duration and byte size parsing (`getDuration()`, `getBytes()`)
 - Sync and async API (`parse` / `parseAsync` / `parseFile` / `parseFileAsync`)
-- ESM + CJS dual package
+- ESM + CJS dual package (every entrypoint smoke-tested in both formats on each CI run)
 - Optional [Zod](https://zod.dev/) integration for schema validation
 - Browser compatible (`parse`/`parseAsync` — no Node.js required)
 
@@ -354,6 +369,17 @@ const cfg = await parseAsync(hoconString, {
 - **Minimize `${ENV}` usage**: Prefer `${?ENV}` (optional) with sensible defaults defined in the config itself
 - **Never require env vars for local development**: Defaults should work out of the box
 - **Document required env vars**: List them in your project's README or a `.env.example`
+- **Name variables with `__`, never `.`**: when bulk-mounting with `loadEnv` (or
+  `parseDotEnv`), `__` is the *only* thing that creates hierarchy. A dot is
+  ordinary key text, so the two spellings below are different keys and both
+  survive:
+
+  ```text
+  APP_FOO__BAR=nested   # -> foo.bar      : cfg.getString('foo.bar')
+  APP_FOO.BAR=dotted    # -> "foo.bar"    : cfg.getString('"foo.bar"')
+  ```
+
+  A single `_` also stays part of its segment (`APP_DB__MAX_CONN` → `db.max_conn`).
 
 ### Dev / Prod Separation
 
@@ -414,7 +440,7 @@ Deferring resolution matters: the plain `parse` resolves as it goes, so a
 | `@o3co/ts.hocon/adapters/env` | — | Bulk-mounts a prefixed namespace; also reads `.env` |
 | `@o3co/ts.hocon/adapters/jsonc` | — | JSON with comments and trailing commas |
 | `@o3co/ts.hocon/adapters/toml` | `smol-toml` | Optional peer dependency |
-| `@o3co/ts.hocon/adapters/yaml` | `yaml` | Optional peer dependency; YAML 1.2 core schema |
+| `@o3co/ts.hocon/adapters/yaml` | `yaml` 2.9.x | Optional peer dependency; scalar resolution is that library's answer, with `version: '1.2'` declared so it cannot drift |
 
 The TOML and YAML libraries are **optional peer dependencies**, so installing
 this package still pulls in nothing — you add the one you actually use. Plain
@@ -424,6 +450,40 @@ Foreign data stays data: a `${a.b}` in a mounted value is literal text, never a
 reference, because the file belongs to a program that never agreed to HOCON's
 syntax.
 
+### Environment variable names
+
+`__` is the only path separator, so a literal `.` in a variable name is key
+text rather than a boundary — `APP_FOO.BAR` and `APP_FOO__BAR` are two
+different keys and can be set at the same time:
+
+```ts
+const cfg = loadEnv({ prefix: 'APP_', env: { 'APP_FOO.BAR': 'dotted', APP_FOO__BAR: 'nested' } })
+cfg.getString('"foo.bar"')   // "dotted"  — one key whose name contains a dot
+cfg.getString('foo.bar')     // "nested"  — foo -> bar
+```
+
+### Numbers from JSONC and YAML
+
+Integers are ingested losslessly: an integer literal too wide for a JS `number`
+keeps its digits instead of being rounded, and one outside the int64 range is
+refused rather than silently mangled. What you get back depends on the getter:
+
+```ts
+const cfg = parseJsonc('{"id": 9007199254740993}')
+cfg.getString('id')   // "9007199254740993"  — exact, the source's own text
+cfg.getNumber('id')   // 9007199254740992    — the JS number model rounds
+cfg.toObject()        // { id: 9007199254740992 }
+```
+
+So read large identifiers (snowflake IDs, ledger sequence numbers) with
+`getString`. `getNumber` and `toObject` apply JavaScript's own number
+semantics, exactly as they do for the same literal written in HOCON text — the
+guarantee is that nothing is lost *on the way in*.
+
+YAML scalar resolution otherwise belongs to the `yaml` library; the adapter
+declares `version: '1.2'` rather than trusting a default, and `fromYamlValue`
+takes an already-decoded tree so you can use a different library or schema.
+
 ## Known Limitations
 
 - **`include url(...)`** is not supported. Fetching remote configuration is outside the scope of this parser. Use your application's HTTP client to fetch the content, then pass it to `parse()`.
@@ -438,6 +498,34 @@ When parsing untrusted HOCON input, be aware of:
 - **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.
+- **Prototype pollution:** keys named `__proto__`, `constructor` or `prototype`
+  are **kept as ordinary keys** — a `.properties` file or environment variable
+  may legitimately use them, and dropping them would be silent data loss.
+  Safety inside this library is structural rather than a denylist: the nesting
+  step builds null-prototype objects, which inherit no `__proto__` setter, every
+  adapter materializes objects by defining own data properties, and `toObject()`
+  does the same. Parsing pollutes nothing, and the returned object's prototype is
+  always `Object.prototype`.
+
+  **What you do with the result matters**, because config data can now hand you
+  an own `__proto__` key:
+
+  ```ts
+  const data = cfg.toObject()
+  { ...data }             // safe
+  structuredClone(data)   // safe
+  Object.assign({}, data) // NOT safe — the key vanishes and config data becomes
+                          //            the copy's prototype
+  deepMerge({}, data)     // NOT safe — a naive recursive merge can write onto
+                          //            the global Object.prototype
+  ```
+
+  Both hazards come from the *destination* object's prototype, so they are the
+  consumer's to avoid: copy with spread or `structuredClone`, iterate with
+  `Object.entries()` / `Object.keys()`, and treat `__proto__` as an ordinary
+  key name. `cfg.toObject({ nullPrototype: true })` returns a tree that inherits
+  nothing — useful when the data is going somewhere you do not control, though it
+  cannot fix a consumer that copies into a plain `{}`.
 
 ## License
 

package/dist/adapters/env.cjs

@@ -550,37 +550,48 @@ function deepMergeHoconValues(base, overlay) {
 // src/internal/resolver/include-loader.ts
 var import_node_module = require("module");
 var nodePath = __toESM(require("path"), 1);
+var import_node_url = require("url");
+
+// src/internal/strip-bom.ts
+function stripBom(input) {
+  return input.charCodeAt(0) === 65279 ? input.slice(1) : input;
+}
 
 // src/internal/properties/properties.ts
 function nestPairs(pairs) {
   const root = /* @__PURE__ */ Object.create(null);
-  const sorted = [...pairs].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-  for (const [key, value] of sorted) {
-    setNested(root, key.split("."), value);
+  const sorted = [...pairs].sort(([a], [b]) => compareSegments(a, b));
+  for (const [segments, value] of sorted) {
+    setNested(root, segments, value);
   }
   return root;
 }
-var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function compareSegments(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return a.length - b.length;
+}
+function pathKey(segments) {
+  return JSON.stringify(segments);
+}
 function setNested(obj, segments, value) {
   let current = obj;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i];
-    if (seg === void 0 || DANGEROUS_KEYS.has(seg)) return;
     if (!(seg in current) || typeof current[seg] !== "object" || current[seg] === null) {
       current[seg] = /* @__PURE__ */ Object.create(null);
     }
     current = current[seg];
   }
   const last = segments[segments.length - 1];
-  if (last === void 0 || DANGEROUS_KEYS.has(last)) return;
   if (typeof current[last] === "object" && current[last] !== null) return;
   current[last] = value;
 }
 
-// src/internal/resolver/include-loader.ts
-var import_meta = {};
-var _require = (0, import_node_module.createRequire)(import_meta.url);
-
 // src/value/numeric-array.ts
 function numericObjectToArray(value) {
   if (value.kind !== "object") return null;
@@ -1168,10 +1179,10 @@ var Config = class _Config {
     }
     if (v.kind === "object") {
       const converted = numericObjectToArray(v);
-      if (converted !== null) return converted.map(hoconToJs);
+      if (converted !== null) return converted.map((item) => hoconToJs(item));
     }
     if (v.kind !== "array") throw new ConfigError(`expected array at ${path}`, path);
-    return v.items.map(hoconToJs);
+    return v.items.map((item) => hoconToJs(item));
   }
   has(path) {
     return this.lookupNode(path) !== void 0;
@@ -1299,8 +1310,52 @@ var Config = class _Config {
       originDescription: this._originDescription
     });
   }
-  toObject() {
-    return hoconToJs(this.root);
+  /**
+   * The whole config as plain JS data: objects, arrays, strings, numbers,
+   * booleans and `null`.
+   *
+   * Keys are reproduced exactly as the config carries them, `__proto__`,
+   * `constructor` and `prototype` included: each is defined as an **own data
+   * property**, so the returned object's prototype is always
+   * `Object.prototype`, and this call writes nothing to the global one.
+   *
+   * ### Passing the result to other code
+   *
+   * A config file — especially a `.properties` file or an env namespace you
+   * merged in — can therefore hand you an own `__proto__` key, and what happens
+   * next depends entirely on how the consumer copies it:
+   *
+   * ```ts
+   * const data = cfg.toObject()
+   * { ...data }                  // safe — own properties are copied as data
+   * structuredClone(data)        // safe
+   * Object.assign({}, data)      // NOT safe — [[Set]] on the {} target hits
+   *                              // Object.prototype's __proto__ setter: the key
+   *                              // vanishes and config data becomes the result's
+   *                              // prototype
+   * deepMerge({}, data)          // NOT safe — a naive recursive merge reads
+   *                              // target['__proto__'], gets Object.prototype,
+   *                              // and writes to it: global pollution
+   * for (const k in data) …      // prefer Object.entries / Object.keys
+   * ```
+   *
+   * Those two hazards come from the **destination** object's prototype, so no
+   * option here can disarm them — copy with spread or `structuredClone` instead.
+   *
+   * What `{ nullPrototype: true }` does give you is a result that inherits
+   * nothing: every object comes back with a `null` prototype, so reading
+   * `x.__proto__`, `x.constructor` or `x.toString` yields config data or
+   * `undefined` rather than something from `Object.prototype`, and code that
+   * merges *into* this object cannot climb out of it. Keys are all still
+   * present. The trade-off is the usual one for prototype-less objects: not
+   * `instanceof Object`, and no `hasOwnProperty` of their own.
+   *
+   * Numbers follow the JS number model, so an integer wider than 2^53 rounds
+   * here even when the config holds it exactly — read those with
+   * {@link Config.getString} instead.
+   */
+  toObject(opts) {
+    return hoconToJs(this.root, opts?.nullPrototype === true);
   }
   /**
    * @internal Test-only: renders this resolved Config's value tree as canonical
@@ -1412,16 +1467,25 @@ function scalarToJs(raw, valueType) {
       return raw;
   }
 }
-function hoconToJs(v) {
+function hoconToJs(v, nullPrototype = false) {
   switch (v.kind) {
     case "scalar":
       return scalarToJs(v.raw, v.valueType);
     case "array":
-      return v.items.map(hoconToJs);
+      return v.items.map((item) => hoconToJs(item, nullPrototype));
     case "object": {
-      const obj = /* @__PURE__ */ Object.create(null);
-      for (const [k, val] of v.fields) obj[k] = hoconToJs(val);
-      return Object.assign({}, obj);
+      const entries = Array.from(v.fields, ([k, val]) => [k, hoconToJs(val, nullPrototype)]);
+      if (nullPrototype) {
+        const obj = /* @__PURE__ */ Object.create(null);
+        for (const [k, val] of entries) Object.defineProperty(obj, k, {
+          value: val,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+        return obj;
+      }
+      return Object.fromEntries(entries);
     }
   }
 }
@@ -1510,6 +1574,8 @@ function fromMap(values, originDescription) {
   const root = { kind: "object", fields };
   return Config._fromResolvedValue(root, { originDescription });
 }
+var INT64_MAX = 9223372036854775807n;
+var INT64_MIN = -9223372036854775808n;
 function coerceObject(obj, atPath) {
   const fields = /* @__PURE__ */ new Map();
   for (const [k, v] of Object.entries(obj)) {
@@ -1538,14 +1604,14 @@ function coerceValue(v, atPath) {
           atPath
         );
       }
-      return { kind: "scalar", raw: String(v), valueType: "number" };
+      return { kind: "scalar", raw: Object.is(v, -0) ? "-0" : String(v), valueType: "number" };
     }
     case "boolean":
       return { kind: "scalar", raw: v ? "true" : "false", valueType: "boolean" };
     case "bigint": {
-      if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) {
+      if (v > INT64_MAX || v < INT64_MIN) {
         throw new ConfigError(
-          `fromMap: bigint ${v} exceeds Number.MAX_SAFE_INTEGER (not representable as HOCON number) at path "${atPath}"`,
+          `fromMap: integer ${v} is out of int64 range (HOCON integers are int64; spec F0.5) at path "${atPath}"`,
           atPath
         );
       }
@@ -1586,11 +1652,12 @@ function loadEnv(opts = {}) {
     const value = source[name];
     if (value === void 0) continue;
     const path = toPath(name.slice(prefix.length));
-    const prev = seen.get(path);
+    const key = pathKey(path);
+    const prev = seen.get(key);
     if (prev !== void 0) {
-      throw new ConfigError(`loadEnv: ${prev} and ${name} both map to "${path}"`, path);
+      throw new ConfigError(`loadEnv: ${prev} and ${name} both map to "${path.join(".")}"`, path.join("."));
     }
-    seen.set(path, name);
+    seen.set(key, name);
     pairs.push([path, value]);
   }
   return fromMap(nestPairs(pairs), opts.originDescription ?? "environment variables");
@@ -1599,7 +1666,7 @@ function parseDotEnv(input, opts = {}) {
   const origin = opts.originDescription ?? ".env";
   const prefix = opts.prefix ?? "";
   const pairs = [];
-  const lines = input.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  const lines = stripBom(input).replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
   for (let i = 0; i < lines.length; i++) {
     const raw = (lines[i] ?? "").trim();
     if (raw === "" || raw.startsWith("#")) continue;
@@ -1615,11 +1682,14 @@ function parseDotEnv(input, opts = {}) {
   return fromMap(nestPairs(pairs), origin);
 }
 function toPath(name) {
-  const segs = name.split(SEPARATOR).map((s) => s.toLowerCase());
+  const segs = name.split(SEPARATOR).map(asciiLower);
   if (segs.some((s) => s === "")) {
     throw new ConfigError(`env: "${name}" produces an empty path segment`, name);
   }
-  return segs.join(".");
+  return segs;
+}
+function asciiLower(s) {
+  return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
 }
 function dotEnvValue(v, origin, line, name) {
   const fail = (msg) => {

package/dist/adapters/env.d.cts

@@ -1,4 +1,4 @@
-import { C as Config } from '../config-PdhVgeLS.cjs';
+import { C as Config } from '../config-Dlq6rF3w.cjs';
 
 type EnvOptions = {
     /**
@@ -22,6 +22,16 @@ type EnvOptions = {
  * Reading a single variable needs nothing from here — HOCON's own `${?VAR}`
  * already does that. This is for mounting a whole namespace as a subtree.
  *
+ * `__` is the only path separator: a single `_` stays part of its segment
+ * (`APP_DB__MAX_CONN` → `db.max_conn`), and a literal `.` in a variable name is
+ * key text rather than a boundary, so `APP_FOO.BAR` becomes the single
+ * top-level key `foo.bar` — addressable as the quoted path `"foo.bar"` — and
+ * coexists with `APP_FOO__BAR` instead of colliding with it (F1.2).
+ *
+ * Two names that do map to one path are an error, the environment having no
+ * order to break the tie with (F1.6). Keys named `__proto__`, `constructor` or
+ * `prototype` are kept like any other (F2.9).
+ *
  * Values are always strings, and a `${...}` inside one stays literal (F0.2, F1.4).
  */
 declare function loadEnv(opts?: EnvOptions & {
@@ -35,6 +45,11 @@ declare function loadEnv(opts?: EnvOptions & {
  * double quotes with `\n \r \t \\ \"`. Multi-line values and trailing comments
  * are not supported — an unquoted value containing ` #` is an error rather than
  * a guess about whether a comment was meant. No `${...}` expansion.
+ *
+ * Names map to paths exactly as in {@link loadEnv}: `__` is the only separator,
+ * so a literal `.` stays key text (`FOO.BAR` → the single key `foo.bar`). A
+ * file has a definite line order, so a repeated name is last-wins (F0.7)
+ * rather than the collision error the process environment gets.
  */
 declare function parseDotEnv(input: string, opts?: EnvOptions): Config;
 

package/dist/adapters/env.d.ts

@@ -1,4 +1,4 @@
-import { C as Config } from '../config-PdhVgeLS.js';
+import { C as Config } from '../config-Dlq6rF3w.js';
 
 type EnvOptions = {
     /**
@@ -22,6 +22,16 @@ type EnvOptions = {
  * Reading a single variable needs nothing from here — HOCON's own `${?VAR}`
  * already does that. This is for mounting a whole namespace as a subtree.
  *
+ * `__` is the only path separator: a single `_` stays part of its segment
+ * (`APP_DB__MAX_CONN` → `db.max_conn`), and a literal `.` in a variable name is
+ * key text rather than a boundary, so `APP_FOO.BAR` becomes the single
+ * top-level key `foo.bar` — addressable as the quoted path `"foo.bar"` — and
+ * coexists with `APP_FOO__BAR` instead of colliding with it (F1.2).
+ *
+ * Two names that do map to one path are an error, the environment having no
+ * order to break the tie with (F1.6). Keys named `__proto__`, `constructor` or
+ * `prototype` are kept like any other (F2.9).
+ *
  * Values are always strings, and a `${...}` inside one stays literal (F0.2, F1.4).
  */
 declare function loadEnv(opts?: EnvOptions & {
@@ -35,6 +45,11 @@ declare function loadEnv(opts?: EnvOptions & {
  * double quotes with `\n \r \t \\ \"`. Multi-line values and trailing comments
  * are not supported — an unquoted value containing ` #` is an error rather than
  * a guess about whether a comment was meant. No `${...}` expansion.
+ *
+ * Names map to paths exactly as in {@link loadEnv}: `__` is the only separator,
+ * so a literal `.` stays key text (`FOO.BAR` → the single key `foo.bar`). A
+ * file has a definite line order, so a repeated name is last-wins (F0.7)
+ * rather than the collision error the process environment gets.
  */
 declare function parseDotEnv(input: string, opts?: EnvOptions): Config;