@o3co/ts.hocon 0.1.2 → 0.1.5

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 o3co Inc.
+   Copyright 2026 1o1 Co. Ltd.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.ja.md

@@ -1,4 +1,4 @@
-# ts.hocon
+# ts.hocon — TypeScript 向け HOCON パーサー
 
 [![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)
@@ -8,25 +8,15 @@
 [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) 仕様に完全準拠した TypeScript ライブラリです。
 
 > **[Claude](https://claude.ai/)（Anthropic）による実装** — Claude Code を用いて設計・実装されました。
+> [GitHub Copilot](https://github.com/features/copilot) および [OpenAI Codex](https://openai.com/index/openai-codex/) によるレビュー。
 
 [English](README.md)
 
 ---
 
-## 特徴
-
-- 完全な HOCON パース：オブジェクト、配列、スカラー値、代入（`${path}`、`${?path}`）
-- 自己参照代入（`path = ${path}:/extra`）
-- 重複キーのディープマージ（後勝ち）
-- `+=` 追加演算子
-- `include "file.conf"` および `include file("file.conf")` ディレクティブ
-- トリプルクォート文字列（`"""..."""`）
-- 同期・非同期 API（`parse` / `parseAsync` / `parseFile` / `parseFileAsync`）
-- ESM + CJS デュアルパッケージ
-- [Zod](https://zod.dev/) スキーマバリデーション統合（オプション）
-- ブラウザ対応（`parse`/`parseAsync` — Node.js 不要）
+## クイックスタート
 
-## インストール
+### 1. インストール
 
 ```bash
 npm install @o3co/ts.hocon
@@ -34,12 +24,11 @@ npm install @o3co/ts.hocon
 
 Node.js 18 以上が必要です。
 
-## クイックスタート
+### 2. 使い方
 
 ```ts
-import { parse, parseFile } from '@o3co/ts.hocon'
+import { parse } from '@o3co/ts.hocon'
 
-// 文字列からパース
 const cfg = parse(`
   server {
     host = "localhost"
@@ -47,17 +36,38 @@ const cfg = parse(`
   }
 `)
 
-// ファイルからパース
-const cfg = parseFile('application.conf')
+cfg.getString('server.host')   // "localhost"
+cfg.getNumber('server.port')   // 8080
+cfg.has('server.host')         // true
+```
+
+## なぜ HOCON？
 
-// スカラーゲッター（存在しない・型が違う場合は ConfigError をスロー）
-const host = cfg.getString('server.host')   // "localhost"
-const port = cfg.getNumber('server.port')   // 8080
+| | `.env` | JSON | YAML | HOCON |
+|---|---|---|---|---|
+| Comments | No | No | Yes | Yes |
+| Nesting | No | Yes | Yes | Yes |
+| References / Substitution | No | No | No | Yes (`${var}`) |
+| File inclusion | No | No | No | Yes (`include`) |
+| Object merging | No | No | Anchors (fragile) | Yes (deep merge) |
+| Optional values | No | No | No | Yes (`${?var}`) |
+| Trailing commas | N/A | No | N/A | Yes |
+| Unquoted strings | Yes | No | Yes | Yes |
 
-// 安全なアクセス
-const host = cfg.get('server.host')         // unknown | undefined
-const exists = cfg.has('server.host')       // true
-```
+HOCON は YAML の可読性と JSON の構造性を兼ね備え、どちらにもない機能 — 変数参照、インクルード、ディープマージ — を提供します。設定がフラットなキーバリューペア以上のものであれば、HOCON を検討する価値があります。
+
+## 特徴
+
+- 完全な HOCON パース：オブジェクト、配列、スカラー値、代入（`${path}`、`${?path}`）
+- 自己参照代入（`path = ${path}:/extra`）
+- 重複キーのディープマージ（後勝ち）
+- `+=` 追加演算子
+- `include "file.conf"` および `include file("file.conf")` ディレクティブ
+- トリプルクォート文字列（`"""..."""`）
+- 同期・非同期 API（`parse` / `parseAsync` / `parseFile` / `parseFileAsync`）
+- ESM + CJS デュアルパッケージ
+- [Zod](https://zod.dev/) スキーマバリデーション統合（オプション）
+- ブラウザ対応（`parse`/`parseAsync` — Node.js 不要）
 
 ## API
 
@@ -237,8 +247,57 @@ const cfg = await parseAsync(hoconString, {
 })
 ```
 
+## ベストプラクティス
+
+### 設定構成
+
+- **ドメインごとに分割**: 設定を論理的な単位に分けましょう（`database.conf`、`server.conf`、`logging.conf`）
+- **`include` で合成**: ドメイン別ファイルからフル設定を組み立てましょう
+- **設定にロジックを入れない**: HOCON は宣言的なデータのためのもので、条件分岐や計算には向きません
+
+### 環境変数
+
+- **`${ENV}` の使用を最小限に**: 設定ファイル自体にデフォルト値を定義し、`${?ENV}`（オプショナル）を使いましょう
+- **ローカル開発で環境変数を必須にしない**: デフォルトだけで動くようにしましょう
+- **必須の環境変数を文書化**: プロジェクトの README や `.env.example` にリストしましょう
+
+### 開発 / 本番の分離
+
+```text
+config/
+├── application.conf    # 共有デフォルト
+├── dev.conf            # include "application.conf" + 開発用オーバーライド
+└── prod.conf           # include "application.conf" + 本番用オーバーライド
+```
+
+### バリデーション
+
+- 設定のバリデーションは常にアプリケーション起動時に行い、使用時ではなく早期に検出しましょう
+- スキーマバリデーション（TypeScript は Zod、Go は struct Unmarshal、Rust は Serde）を使って早期にエラーをキャッチしましょう
+
+```typescript
+import { parseWithSchema } from '@o3co/ts.hocon/zod'
+import { z } from 'zod'
+
+const schema = z.object({
+  server: z.object({ host: z.string(), port: z.number() }),
+  debug: z.boolean(),
+})
+const config = parseWithSchema(hoconInput, schema) // 起動時に即座に失敗
+```
+
+## 関連プロジェクト
+
+| プロジェクト | 言語 | レジストリ | 説明 |
+|---------|----------|----------|-------------|
+| [go.hocon](https://github.com/o3co/go.hocon) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/go.hocon) | Go 向け HOCON パーサー |
+| [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/o3co-hocon) | Rust 向け HOCON パーサー |
+| [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties 変換 CLI |
+
+すべての実装が Lightbend HOCON 仕様に完全準拠しています。
+
 ## ライセンス
 
 Apache License 2.0 — [LICENSE](LICENSE) を参照。
 
-Copyright 2026 o3co Inc.
+Copyright 2026 1o1 Co. Ltd.

package/README.md

@@ -1,4 +1,4 @@
-# ts.hocon
+# ts.hocon — HOCON Parser for TypeScript
 
 [![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)
@@ -8,25 +8,15 @@
 A full [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) spec-compliant TypeScript library.
 
 > **Implemented by [Claude](https://claude.ai/) (Anthropic)** — designed and built end-to-end with Claude Code.
+> Reviewed by [GitHub Copilot](https://github.com/features/copilot) and [OpenAI Codex](https://openai.com/index/openai-codex/).
 
 [日本語](README.ja.md)
 
 ---
 
-## Features
-
-- Full HOCON parsing: objects, arrays, scalars, substitutions (`${path}`, `${?path}`)
-- Self-referential substitutions (`path = ${path}:/extra`)
-- Deep-merge for duplicate keys (last definition wins)
-- `+=` append operator
-- `include "file.conf"` and `include file("file.conf")` directives
-- Triple-quoted strings (`"""..."""`)
-- Sync and async API (`parse` / `parseAsync` / `parseFile` / `parseFileAsync`)
-- ESM + CJS dual package
-- Optional [Zod](https://zod.dev/) integration for schema validation
-- Browser compatible (`parse`/`parseAsync` — no Node.js required)
+## Quick Start
 
-## Installation
+### 1. Install
 
 ```bash
 npm install @o3co/ts.hocon
@@ -34,12 +24,11 @@ npm install @o3co/ts.hocon
 
 Requires Node.js 18+.
 
-## Quick Start
+### 2. Use
 
 ```ts
-import { parse, parseFile } from '@o3co/ts.hocon'
+import { parse } from '@o3co/ts.hocon'
 
-// Parse from string
 const cfg = parse(`
   server {
     host = "localhost"
@@ -47,17 +36,38 @@ const cfg = parse(`
   }
 `)
 
-// Parse from file
-const cfg = parseFile('application.conf')
+cfg.getString('server.host')   // "localhost"
+cfg.getNumber('server.port')   // 8080
+cfg.has('server.host')         // true
+```
+
+## Why HOCON?
 
-// Scalar getters (throw ConfigError on missing/wrong type)
-const host = cfg.getString('server.host')   // "localhost"
-const port = cfg.getNumber('server.port')   // 8080
+| | `.env` | JSON | YAML | HOCON |
+|---|---|---|---|---|
+| Comments | No | No | Yes | Yes |
+| Nesting | No | Yes | Yes | Yes |
+| References / Substitution | No | No | No | Yes (`${var}`) |
+| File inclusion | No | No | No | Yes (`include`) |
+| Object merging | No | No | Anchors (fragile) | Yes (deep merge) |
+| Optional values | No | No | No | Yes (`${?var}`) |
+| Trailing commas | N/A | No | N/A | Yes |
+| Unquoted strings | Yes | No | Yes | Yes |
 
-// Safe access
-const host = cfg.get('server.host')         // unknown | undefined
-const exists = cfg.has('server.host')       // true
-```
+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.
+
+## Features
+
+- Full HOCON parsing: objects, arrays, scalars, substitutions (`${path}`, `${?path}`)
+- Self-referential substitutions (`path = ${path}:/extra`)
+- Deep-merge for duplicate keys (last definition wins)
+- `+=` append operator
+- `include "file.conf"` and `include file("file.conf")` directives
+- Triple-quoted strings (`"""..."""`)
+- Sync and async API (`parse` / `parseAsync` / `parseFile` / `parseFileAsync`)
+- ESM + CJS dual package
+- Optional [Zod](https://zod.dev/) integration for schema validation
+- Browser compatible (`parse`/`parseAsync` — no Node.js required)
 
 ## API
 
@@ -237,8 +247,57 @@ const cfg = await parseAsync(hoconString, {
 })
 ```
 
+## Best Practices
+
+### Config Structure
+
+- **Split by domain**: Separate configuration into logical units (`database.conf`, `server.conf`, `logging.conf`)
+- **Use `include` for composition**: Compose a full config from domain-specific files
+- **Avoid logic in config**: HOCON is for declarative data, not conditionals or computation
+
+### Environment Variables
+
+- **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`
+
+### Dev / Prod Separation
+
+```text
+config/
+├── application.conf    # shared defaults
+├── dev.conf            # include "application.conf" + dev overrides
+└── prod.conf           # include "application.conf" + prod overrides
+```
+
+### Validation
+
+- Always validate config at application startup, not at point-of-use
+- Use schema validation (Zod for TypeScript, struct unmarshaling for Go, Serde for Rust) to catch errors early
+
+```typescript
+import { parseWithSchema } from '@o3co/ts.hocon/zod'
+import { z } from 'zod'
+
+const schema = z.object({
+  server: z.object({ host: z.string(), port: z.number() }),
+  debug: z.boolean(),
+})
+const config = parseWithSchema(hoconInput, schema) // fails fast on startup
+```
+
+## Related Projects
+
+| Project | Language | Registry | Description |
+|---------|----------|----------|-------------|
+| [go.hocon](https://github.com/o3co/go.hocon) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/go.hocon) | HOCON parser for Go |
+| [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/o3co-hocon) | HOCON parser for Rust |
+| [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties CLI |
+
+All implementations are full Lightbend HOCON spec compliant.
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE).
 
-Copyright 2026 o3co Inc.
+Copyright 2026 1o1 Co. Ltd.

package/dist/index.cjs

@@ -41,6 +41,20 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/coerce.ts
+var TRUTHY = /* @__PURE__ */ new Set(["true", "yes", "on"]);
+var FALSY = /* @__PURE__ */ new Set(["false", "no", "off"]);
+function coerceBoolean(value) {
+  const lower = value.toLowerCase();
+  if (TRUTHY.has(lower)) return true;
+  if (FALSY.has(lower)) return false;
+  return void 0;
+}
+function coerceNumber(value) {
+  if (!/^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return void 0;
+  return Number(value);
+}
+
 // src/errors.ts
 var ParseError = class extends Error {
   constructor(message, line, col, file) {
@@ -88,8 +102,8 @@ var Config = class _Config {
     const v = this.requireScalar(path2);
     if (typeof v === "number") return v;
     if (typeof v === "string") {
-      const n = Number(v);
-      if (!Number.isNaN(n)) return n;
+      const coerced = coerceNumber(v);
+      if (coerced !== void 0) return coerced;
     }
     throw new ConfigError(`expected number at ${path2}, got ${typeof v}`, path2);
   }
@@ -97,8 +111,8 @@ var Config = class _Config {
     const v = this.requireScalar(path2);
     if (typeof v === "boolean") return v;
     if (typeof v === "string") {
-      if (v === "true") return true;
-      if (v === "false") return false;
+      const coerced = coerceBoolean(v);
+      if (coerced !== void 0) return coerced;
     }
     throw new ConfigError(`expected boolean at ${path2}, got ${typeof v}`, path2);
   }

package/dist/index.d.cts

@@ -1,5 +1,4 @@
-import { C as Config } from './config-D4EyvNd8.cjs';
-export { H as HoconValue } from './config-D4EyvNd8.cjs';
+export { C as Config, H as HoconValue, P as ParseOptions, p as parse, a as parseAsync, b as parseFile, c as parseFileAsync } from './parse-C1NDMzD5.cjs';
 
 declare class ParseError extends Error {
     readonly line: number;
@@ -19,21 +18,4 @@ declare class ConfigError extends Error {
     constructor(message: string, path: string);
 }
 
-type ParseOptions = {
-    baseDir?: string;
-    env?: Record<string, string>;
-    readFile?: (filePath: string) => Promise<string>;
-    readFileSync?: (filePath: string) => string;
-};
-declare function parse(input: string, opts?: ParseOptions): Config;
-/**
- * Async wrapper around `parse()`. Returns a resolved Promise — the parsing
- * itself is synchronous. Use `parseFileAsync()` for async file I/O.
- * Note: `include` directives in string input are resolved synchronously
- * via `readFileSync`; `readFile` is not used by this function.
- */
-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>;
-
-export { Config, ConfigError, ParseError, type ParseOptions, ResolveError, parse, parseAsync, parseFile, parseFileAsync };
+export { ConfigError, ParseError, ResolveError };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { C as Config } from './config-D4EyvNd8.js';
-export { H as HoconValue } from './config-D4EyvNd8.js';
+export { C as Config, H as HoconValue, P as ParseOptions, p as parse, a as parseAsync, b as parseFile, c as parseFileAsync } from './parse-C1NDMzD5.js';
 
 declare class ParseError extends Error {
     readonly line: number;
@@ -19,21 +18,4 @@ declare class ConfigError extends Error {
     constructor(message: string, path: string);
 }
 
-type ParseOptions = {
-    baseDir?: string;
-    env?: Record<string, string>;
-    readFile?: (filePath: string) => Promise<string>;
-    readFileSync?: (filePath: string) => string;
-};
-declare function parse(input: string, opts?: ParseOptions): Config;
-/**
- * Async wrapper around `parse()`. Returns a resolved Promise — the parsing
- * itself is synchronous. Use `parseFileAsync()` for async file I/O.
- * Note: `include` directives in string input are resolved synchronously
- * via `readFileSync`; `readFile` is not used by this function.
- */
-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>;
-
-export { Config, ConfigError, ParseError, type ParseOptions, ResolveError, parse, parseAsync, parseFile, parseFileAsync };
+export { ConfigError, ParseError, ResolveError };

package/dist/index.js

@@ -1,3 +1,17 @@
+// src/coerce.ts
+var TRUTHY = /* @__PURE__ */ new Set(["true", "yes", "on"]);
+var FALSY = /* @__PURE__ */ new Set(["false", "no", "off"]);
+function coerceBoolean(value) {
+  const lower = value.toLowerCase();
+  if (TRUTHY.has(lower)) return true;
+  if (FALSY.has(lower)) return false;
+  return void 0;
+}
+function coerceNumber(value) {
+  if (!/^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return void 0;
+  return Number(value);
+}
+
 // src/errors.ts
 var ParseError = class extends Error {
   constructor(message, line, col, file) {
@@ -45,8 +59,8 @@ var Config = class _Config {
     const v = this.requireScalar(path2);
     if (typeof v === "number") return v;
     if (typeof v === "string") {
-      const n = Number(v);
-      if (!Number.isNaN(n)) return n;
+      const coerced = coerceNumber(v);
+      if (coerced !== void 0) return coerced;
     }
     throw new ConfigError(`expected number at ${path2}, got ${typeof v}`, path2);
   }
@@ -54,8 +68,8 @@ var Config = class _Config {
     const v = this.requireScalar(path2);
     if (typeof v === "boolean") return v;
     if (typeof v === "string") {
-      if (v === "true") return true;
-      if (v === "false") return false;
+      const coerced = coerceBoolean(v);
+      if (coerced !== void 0) return coerced;
     }
     throw new ConfigError(`expected boolean at ${path2}, got ${typeof v}`, path2);
   }

package/dist/parse-C1NDMzD5.d.cts

@@ -0,0 +1,48 @@
+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;
+}
+
+type ParseOptions = {
+    baseDir?: string;
+    env?: Record<string, string>;
+    readFile?: (filePath: string) => Promise<string>;
+    readFileSync?: (filePath: string) => string;
+};
+declare function parse(input: string, opts?: ParseOptions): Config;
+/**
+ * Async wrapper around `parse()`. Returns a resolved Promise — the parsing
+ * itself is synchronous. Use `parseFileAsync()` for async file I/O.
+ * Note: `include` directives in string input are resolved synchronously
+ * via `readFileSync`; `readFile` is not used by this function.
+ */
+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>;
+
+export { Config as C, type HoconValue as H, type ParseOptions as P, parseAsync as a, parseFile as b, parseFileAsync as c, parse as p };

package/dist/parse-C1NDMzD5.d.ts

@@ -0,0 +1,48 @@
+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;
+}
+
+type ParseOptions = {
+    baseDir?: string;
+    env?: Record<string, string>;
+    readFile?: (filePath: string) => Promise<string>;
+    readFileSync?: (filePath: string) => string;
+};
+declare function parse(input: string, opts?: ParseOptions): Config;
+/**
+ * Async wrapper around `parse()`. Returns a resolved Promise — the parsing
+ * itself is synchronous. Use `parseFileAsync()` for async file I/O.
+ * Note: `include` directives in string input are resolved synchronously
+ * via `readFileSync`; `readFile` is not used by this function.
+ */
+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>;
+
+export { Config as C, type HoconValue as H, type ParseOptions as P, parseAsync as a, parseFile as b, parseFileAsync as c, parse as p };