@o3co/ts.hocon 0.1.0 → 0.1.2

package/README.ja.md

@@ -174,6 +174,55 @@ v0.1.0 で未対応の機能:
 - `include classpath(...)`
 - `.properties` ファイルのパース
 
+## パフォーマンス
+
+### ts.hocon のパースコスト
+
+[Vitest bench](https://vitest.dev/guide/features.html#benchmarking)（tinybench）で計測。`pnpm bench` で再現できます。
+
+| シナリオ | ops/sec | 1回あたりの時間 |
+|---|---|---|
+| 小規模設定（10キー） | ~200,000 | ~5 µs |
+| 中規模設定（100キー） | ~23,000 | ~43 µs |
+| 大規模設定（1,000キー） | ~2,100 | ~476 µs |
+| substitution 10個 | ~74,000 | ~14 µs |
+| substitution 50個 | ~14,000 | ~71 µs |
+| substitution 100個 | ~6,900 | ~145 µs |
+| ネスト深度 5 | ~210,000 | ~5 µs |
+| ネスト深度 10 | ~147,000 | ~7 µs |
+| ネスト深度 20 | ~80,000 | ~13 µs |
+
+### JSON.parse との比較
+
+JSON.parse は V8 のネイティブ C++ 実装であり、最速の基準線です。この比較は HOCON の豊富な機能によるオーバーヘッドを示します。
+
+| 設定サイズ | ts.hocon | JSON.parse | 倍率 |
+|---|---|---|---|
+| 小規模（10キー） | ~198K ops/s | ~1,967K ops/s | ~10x |
+| 中規模（100キー） | ~23K ops/s | ~280K ops/s | ~12x |
+| 大規模（1,000キー） | ~2.2K ops/s | ~12K ops/s | ~5.4x |
+
+一般的なアプリケーション設定（起動時に1回読み込み）であれば、パースコストは無視できるレベルです。1,000キーの設定でも 0.5 ms 未満でパースできます。
+
+### node-config との機能比較
+
+ts.hocon は [node-config](https://github.com/node-config/node-config)（JSON）と比較して、大幅に豊富な設定機能を提供します：
+
+| 機能 | ts.hocon | node-config (JSON) |
+|---|---|---|
+| コメント | `//` `#` | 非対応 |
+| 複数行文字列 | `"""..."""` | 非対応 |
+| substitution（`${path}`） | 対応 | 非対応 |
+| optional substitution（`${?path}`） | 対応 | 非対応 |
+| 環境変数参照 | 対応（substitution経由） | 部分対応（`custom-environment-variables` ファイル） |
+| include | 対応 | 非対応 |
+| ディープマージ | 対応（配列も対応） | 部分対応（配列は置換） |
+| 追加演算子（`+=`） | 対応 | 非対応 |
+| 環境別設定 | HOCON仕様で自由に構成可 | 対応（ファイル名規約） |
+| スキーマ検証 | Zod 統合 | 非対応 |
+| プログラマティック API | `parse(string)` | ファイルベース初期化後に `get()` |
+| 型付きゲッター | `getString`, `getNumber` 等 | `get()`（any） |
+
 ## ブラウザ対応
 
 `parse()` と `parseAsync()` はブラウザで動作します。`parseFile()` と `parseFileAsync()` は Node.js（またはカスタムの `readFileSync`/`readFile` オプション）が必要です。

package/README.md

@@ -174,6 +174,55 @@ Not supported in v0.1.0:
 - `include classpath(...)`
 - `.properties` file parsing
 
+## Performance
+
+### ts.hocon Parsing Cost
+
+Measured with [Vitest bench](https://vitest.dev/guide/features.html#benchmarking) (tinybench). Run `pnpm bench` to reproduce.
+
+| Scenario | ops/sec | Time per op |
+|---|---|---|
+| Small config (10 keys) | ~200,000 | ~5 µs |
+| Medium config (100 keys) | ~23,000 | ~43 µs |
+| Large config (1,000 keys) | ~2,100 | ~476 µs |
+| 10 substitutions | ~74,000 | ~14 µs |
+| 50 substitutions | ~14,000 | ~71 µs |
+| 100 substitutions | ~6,900 | ~145 µs |
+| Depth 5 nesting | ~210,000 | ~5 µs |
+| Depth 10 nesting | ~147,000 | ~7 µs |
+| Depth 20 nesting | ~80,000 | ~13 µs |
+
+### Comparison with JSON.parse
+
+JSON.parse is V8's native C++ implementation — the fastest possible baseline. This comparison shows the overhead of HOCON's rich feature set.
+
+| Config Size | ts.hocon | JSON.parse | Ratio |
+|---|---|---|---|
+| Small (10 keys) | ~198K ops/s | ~1,967K ops/s | ~10x |
+| Medium (100 keys) | ~23K ops/s | ~280K ops/s | ~12x |
+| Large (1,000 keys) | ~2.2K ops/s | ~12K ops/s | ~5.4x |
+
+For typical application configs (loaded once at startup), the parsing cost is negligible — even a 1,000-key config parses in under 0.5 ms.
+
+### Feature Comparison with node-config
+
+ts.hocon provides significantly richer configuration capabilities compared to [node-config](https://github.com/node-config/node-config) (JSON):
+
+| Feature | ts.hocon | node-config (JSON) |
+|---|---|---|
+| Comments | `//` `#` | No |
+| Multi-line strings | `"""..."""` | No |
+| Substitution (`${path}`) | Yes | No |
+| Optional substitution (`${?path}`) | Yes | No |
+| Environment variable reference | Yes (via substitution) | Partial (`custom-environment-variables` file) |
+| Include | Yes | No |
+| Deep merge | Yes (arrays too) | Partial (arrays replaced) |
+| Append operator (`+=`) | Yes | No |
+| Environment-based config | Configurable via HOCON | Yes (filename convention) |
+| Schema validation | Zod integration | No |
+| Programmatic API | `parse(string)` | File-based initialization, then `get()` |
+| Typed getters | `getString`, `getNumber`, etc. | `get()` (any) |
+
 ## Browser Compatibility
 
 `parse()` and `parseAsync()` work in browsers. `parseFile()` and `parseFileAsync()` require Node.js (or a custom `readFileSync`/`readFile` option).

package/dist/config-D4EyvNd8.d.cts

@@ -0,0 +1,31 @@
+type HoconValue = {
+    kind: 'object';
+    fields: Map<string, HoconValue>;
+} | {
+    kind: 'array';
+    items: HoconValue[];
+} | {
+    kind: 'scalar';
+    value: string | number | boolean | null;
+};
+
+declare class Config {
+    private readonly root;
+    constructor(root: HoconValue & {
+        kind: 'object';
+    });
+    get(path: string): unknown;
+    getString(path: string): string;
+    getNumber(path: string): number;
+    getBoolean(path: string): boolean;
+    getConfig(path: string): Config;
+    getList(path: string): unknown[];
+    has(path: string): boolean;
+    keys(): string[];
+    withFallback(fallback: Config): Config;
+    toObject(): unknown;
+    private lookupNode;
+    private requireScalar;
+}
+
+export { Config as C, type HoconValue as H };

package/dist/config-D4EyvNd8.d.ts

@@ -0,0 +1,31 @@
+type HoconValue = {
+    kind: 'object';
+    fields: Map<string, HoconValue>;
+} | {
+    kind: 'array';
+    items: HoconValue[];
+} | {
+    kind: 'scalar';
+    value: string | number | boolean | null;
+};
+
+declare class Config {
+    private readonly root;
+    constructor(root: HoconValue & {
+        kind: 'object';
+    });
+    get(path: string): unknown;
+    getString(path: string): string;
+    getNumber(path: string): number;
+    getBoolean(path: string): boolean;
+    getConfig(path: string): Config;
+    getList(path: string): unknown[];
+    has(path: string): boolean;
+    keys(): string[];
+    withFallback(fallback: Config): Config;
+    toObject(): unknown;
+    private lookupNode;
+    private requireScalar;
+}
+
+export { Config as C, type HoconValue as H };