@o3co/ts.hocon 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.ja.md +14 -6
  2. package/README.md +22 -6
  3. package/dist/index.cjs +601 -204
  4. package/dist/index.js +601 -204
  5. package/dist/zod.cjs +601 -204
  6. package/dist/zod.js +601 -204
  7. package/package.json +4 -4
package/README.ja.md CHANGED
@@ -2,10 +2,10 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@o3co/ts.hocon.svg)](https://www.npmjs.com/package/@o3co/ts.hocon)
4
4
  [![CI](https://github.com/o3co/ts.hocon/actions/workflows/test.yml/badge.svg)](https://github.com/o3co/ts.hocon/actions/workflows/test.yml)
5
- [![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/main/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
5
+ [![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/develop/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
6
6
  [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
7
7
 
8
- [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) 仕様に完全準拠した TypeScript ライブラリです。
8
+ [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) 仕様の TypeScript パーサー。現在の準拠率は [仕様準拠](#仕様準拠) を参照。
9
9
 
10
10
  > **[Claude](https://claude.ai/)（Anthropic）による実装** — Claude Code を用いて設計・実装されました。
11
11
  > [GitHub Copilot](https://github.com/features/copilot) および [OpenAI Codex](https://openai.com/index/openai-codex/) によるレビュー。
@@ -22,7 +22,7 @@
22
22
  npm install @o3co/ts.hocon
23
23
  ```
24
24
 
25
- Node.js 18 以上が必要です。
25
+ Node.js 22 以上が必要です。
26
26
 
27
27
  ### 2. 使い方
28
28
 
@@ -54,7 +54,9 @@ cfg.has('server.host') // true
54
54
  | Trailing commas | N/A | No | N/A | Yes |
55
55
  | Unquoted strings | Yes | No | Yes | Yes |
56
56
 
57
- HOCON は YAML の可読性と JSON の構造性を兼ね備え、どちらにもない機能 — 変数参照、インクルード、ディープマージ — を提供します。設定がフラットなキーバリューペア以上のものであれば、HOCON を検討する価値があります。
57
+ HOCON は単なるシリアライズ形式ではなく、**プログラムに注入するための設定言語** です。JSON / YAML / TOML はデータ構造の表現に徹しており、ファイルの重ね合わせ・環境変数・参照解決はアプリ側（Pydantic、Serde、Zod 等）の責務になります。HOCON はそれらを仕様そのものに内包しているため、プログラムが設定を受け取る時点で、フォールバックは合成済み・`${VAR}` 参照は解決済みの「1 枚の設定」になっています。「このレイヤーに値があるか？」に由来する条件分岐は、コードではなくフォーマット境界で消えます。
58
+
59
+ 加えて HOCON は YAML の可読性と JSON の構造性を兼ね備えるため、フラットなキーバリュー設定を超えるユースケースには強い選択肢になります。
58
60
 
59
61
  ## 特徴
60
62
 
@@ -177,7 +179,13 @@ description = """
177
179
 
178
180
  ## 仕様準拠
179
181
 
180
- [Lightbend 公式テストスイート](https://github.com/lightbend/config/tree/main/config/src/test/resources)でテスト済み: **13/13 テストグループ合格**。
182
+ [Lightbend HOCON 仕様](https://github.com/lightbend/config/blob/main/HOCON.md) への準拠状況は [`docs/spec-compliance.md`](docs/spec-compliance.md) に項目単位で記載しています。以下の表は 2026-05-13 時点のスナップショットです — 最新値は [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) を参照してください。
183
+
184
+ | 指標 | 状況 |
185
+ | -------------------------------------- | ------------- |
186
+ | 仕様全体（out-of-scope を含む） | **74.2%** |
187
+ | In-scope のみ | **83.3%** |
188
+ | Lightbend `test01`–`test13` テスト群 | 13/13 合格 |
181
189
 
182
190
  v0.1.0 で未対応の機能:
183
191
  - `include url(...)`
@@ -294,7 +302,7 @@ const config = parseWithSchema(hoconInput, schema) // 起動時に即座に失
294
302
  | [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/o3co-hocon) | Rust 向け HOCON パーサー |
295
303
  | [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties 変換 CLI |
296
304
 
297
- すべての実装が Lightbend HOCON 仕様に完全準拠しています。
305
+ 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) を参照してください。
298
306
 
299
307
  ## ライセンス
300
308
 
package/README.md CHANGED
@@ -2,16 +2,20 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@o3co/ts.hocon.svg)](https://www.npmjs.com/package/@o3co/ts.hocon)
4
4
  [![CI](https://github.com/o3co/ts.hocon/actions/workflows/test.yml/badge.svg)](https://github.com/o3co/ts.hocon/actions/workflows/test.yml)
5
- [![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/main/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
5
+ [![codecov](https://codecov.io/gh/o3co/ts.hocon/branch/develop/graph/badge.svg)](https://codecov.io/gh/o3co/ts.hocon)
6
6
  [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
7
7
 
8
- A full [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) spec-compliant TypeScript library.
8
+ 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.
9
9
 
10
10
  > **Implemented by [Claude](https://claude.ai/) (Anthropic)** — designed and built end-to-end with Claude Code.
11
11
  > Reviewed by [GitHub Copilot](https://github.com/features/copilot) and [OpenAI Codex](https://openai.com/index/openai-codex/).
12
12
 
13
13
  [日本語](README.ja.md)
14
14
 
15
+ > **Library stance:** ts.hocon is a HOCON config loader — its purpose is reading `.hocon` config files and providing typed access via the Config API (`getString`, `getNumber`, `getBoolean`, `getDuration`, `getBytes`, `toObject`). It is not a low-level parser API. Internal types like `HoconValue` may change between minor versions.
16
+ >
17
+ > **Cross-language conformance:** This implementation is tested against shared expected-JSON fixtures from [o3co/xx.hocon](https://github.com/o3co/xx.hocon) alongside [go.hocon](https://github.com/o3co/go.hocon) and [rs.hocon](https://github.com/o3co/rs.hocon) to ensure all three implementations meet the same Lightbend HOCON specification.
18
+
15
19
  ---
16
20
 
17
21
  ## Quick Start
@@ -22,7 +26,7 @@ A full [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md)
22
26
  npm install @o3co/ts.hocon
23
27
  ```
24
28
 
25
- Requires Node.js 18+.
29
+ Requires Node.js 22+.
26
30
 
27
31
  ### 2. Use
28
32
 
@@ -54,7 +58,9 @@ cfg.has('server.host') // true
54
58
  | Trailing commas | N/A | No | N/A | Yes |
55
59
  | Unquoted strings | Yes | No | Yes | Yes |
56
60
 
57
- 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.
61
+ 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.
62
+
63
+ 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.
58
64
 
59
65
  ## Features
60
66
 
@@ -202,7 +208,13 @@ Supported byte units: `B`, `KB`/`KiB`, `MB`/`MiB`, `GB`/`GiB`, `TB`/`TiB` (and l
202
208
 
203
209
  ## Spec Compliance
204
210
 
205
- Tested against the [Lightbend official test suite](https://github.com/lightbend/config/tree/main/config/src/test/resources): **13/13 test groups pass**.
211
+ Conformance against the [Lightbend HOCON specification](https://github.com/lightbend/config/blob/main/HOCON.md) is tracked at item granularity in [`docs/spec-compliance.md`](docs/spec-compliance.md). The table below is a snapshot as of 2026-05-13; see [`xx.hocon/docs/compliance-matrix.md`](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) for live cross-impl values.
212
+
213
+ | Metric | Status |
214
+ | ------------------------------------- | ------------- |
215
+ | Spec total (incl. out-of-scope) | **74.2%** |
216
+ | In-scope only | **83.3%** |
217
+ | Lightbend `test01`–`test13` suite | 13/13 passing |
206
218
 
207
219
  Not supported in v0.1.0:
208
220
 
@@ -213,6 +225,10 @@ Supported since v0.2.0 (P1):
213
225
 
214
226
  - `.properties` file parsing
215
227
 
228
+ ### Stricter than Lightbend
229
+
230
+ - **S8.6 leading-hyphen rejection** (Unreleased): `a = -foo`, `a = -bar`, `a = -` etc. now raise a lex error per HOCON.md L270–276, where Lightbend silently falls back to unquoted strings. Mitigation: quote the value (`a = "-foo"`). See [CHANGELOG](CHANGELOG.md#unreleased) and [`docs/spec-compliance.md`](docs/spec-compliance.md) §S8.6.
231
+
216
232
  ## Performance
217
233
 
218
234
  ### ts.hocon Parsing Cost
@@ -323,7 +339,7 @@ const config = parseWithSchema(hoconInput, schema) // fails fast on startup
323
339
  | [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/o3co-hocon) | HOCON parser for Rust |
324
340
  | [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties CLI |
325
341
 
326
- All implementations are full Lightbend HOCON spec compliant.
342
+ The three parser implementations ([ts.hocon](https://github.com/o3co/ts.hocon), [rs.hocon](https://github.com/o3co/rs.hocon), [go.hocon](https://github.com/o3co/go.hocon)) are all tracked against the same Lightbend HOCON spec — see the [cross-impl roll-up](https://github.com/o3co/xx.hocon/blob/main/docs/compliance-matrix.md) for per-impl conformance rates.
327
343
 
328
344
  ## Known Limitations
329
345