@o3co/ts.hocon 0.1.5 → 1.1.0

package/README.md

@@ -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
@@ -296,6 +325,22 @@ const config = parseWithSchema(hoconInput, schema) // fails fast on startup
 
 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).