@o3co/ts.hocon 0.1.4 → 1.0.0

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)
@@ -288,11 +288,11 @@ const config = parseWithSchema(hoconInput, schema) // 起動時に即座に失
 
 ## 関連プロジェクト
 
-| プロジェクト | 言語 | 説明 |
-|---------|----------|-------------|
-| [go.hocon](https://github.com/o3co/go.hocon) | Go | Go 向け HOCON パーサー |
-| [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | Rust 向け HOCON パーサー |
-| [hocon2](https://github.com/o3co/hocon2) | Go | HOCON → JSON/YAML/TOML/Properties 変換 CLI ツール |
+| プロジェクト | 言語 | レジストリ | 説明 |
+|---------|----------|----------|-------------|
+| [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 仕様に完全準拠しています。
 

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)
@@ -64,6 +64,7 @@ HOCON gives you the readability of YAML, the structure of JSON, and features tha
 - `+=` append operator
 - `include "file.conf"` and `include file("file.conf")` directives
 - Triple-quoted strings (`"""..."""`)
+- Duration and byte size parsing (`getDuration()`, `getBytes()`)
 - Sync and async API (`parse` / `parseAsync` / `parseFile` / `parseFileAsync`)
 - ESM + CJS dual package
 - Optional [Zod](https://zod.dev/) integration for schema validation
@@ -71,6 +72,8 @@ HOCON gives you the readability of YAML, the structure of JSON, and features tha
 
 ## API
 
+For full API documentation, see [o3co.github.io/ts.hocon](https://o3co.github.io/ts.hocon/) (generated with TypeDoc, updated on each minor/major release).
+
 ### Parse functions
 
 ```ts
@@ -101,6 +104,8 @@ parseFileAsync(path: string, opts?: ParseOptions): Promise<Config>
 | `getBoolean(path)` | `boolean` | missing, wrong type |
 | `getConfig(path)` | `Config` | missing, not an object |
 | `getList(path)` | `unknown[]` | missing, not an array |
+| `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` | — |
@@ -175,13 +180,37 @@ description = """
 """
 ```
 
+### Duration and Byte Sizes
+
+```ts
+const c = parse(`
+  timeout   = "30s"
+  cache-ttl = "5m"
+  max-size  = "512MiB"
+`)
+
+c.getDuration('timeout')        // 30000 (ms)
+c.getDuration('timeout', 's')   // 30
+c.getDuration('cache-ttl', 'm') // 5
+
+c.getBytes('max-size')          // 536870912 (bytes)
+c.getBytes('max-size', 'MiB')  // 512
+```
+
+Supported duration units: `ns`, `us`, `ms`, `s`, `m`, `h`, `d` (and long forms like `seconds`, `minutes`).
+Supported byte units: `B`, `KB`/`KiB`, `MB`/`MiB`, `GB`/`GiB`, `TB`/`TiB` (and long forms like `megabytes`, `mebibytes`).
+
 ## Spec Compliance
 
 Tested against the [Lightbend official test suite](https://github.com/lightbend/config/tree/main/config/src/test/resources): **13/13 test groups pass**.
 
 Not supported in v0.1.0:
+
 - `include url(...)`
 - `include classpath(...)`
+
+Supported since v0.2.0 (P1):
+
 - `.properties` file parsing
 
 ## Performance
@@ -288,14 +317,30 @@ const config = parseWithSchema(hoconInput, schema) // fails fast on startup
 
 ## Related Projects
 
-| Project | Language | Description |
-|---------|----------|-------------|
-| [go.hocon](https://github.com/o3co/go.hocon) | Go | HOCON parser for Go |
-| [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | HOCON parser for Rust |
-| [hocon2](https://github.com/o3co/hocon2) | Go | CLI tools to convert HOCON → JSON/YAML/TOML/Properties |
+| 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.
 
+## 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()`.
+- **`include classpath(...)`** is not supported. This is a JVM-specific include form with no equivalent outside Java runtimes.
+- **No watch/reload** — the library parses config at load time. For live-reloading, re-call `parse()` or `parseFile()` on change.
+- **No streaming parser** — the entire input is loaded into memory. For very large configs, validate input size before parsing (see Security Considerations).
+- **`.properties` include** — supports basic `key=value` / `key:value` syntax. Does not support multiline values (backslash continuation), Unicode escapes, or key escaping from the full Java .properties specification.
+
+## Security Considerations
+
+When parsing untrusted HOCON input, be aware of:
+
+- **Path traversal in includes:** `include "../../../etc/passwd"` will resolve relative to `baseDir`. 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.
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE).