@o3co/ts.hocon 1.8.0 → 1.10.0

package/README.md

@@ -14,7 +14,7 @@ A [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) pars
 
 > **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.
 >
-> **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.
+> **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), [rs.hocon](https://github.com/o3co/rs.hocon), and [py.hocon](https://github.com/o3co/py.hocon) to ensure all four implementations meet the same Lightbend HOCON specification.
 
 ---
 
@@ -245,7 +245,7 @@ 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 duration units: `ns`, `us`, `ms`, `s`, `m`, `h`, `d` (and long forms like `seconds`, `minutes`). Duration unit names are case-sensitive and must be lowercase (HOCON spec). Byte units are more case-tolerant: the canonical forms below plus lowercase aliases (`kb`, `kib`, …), any-case long forms (`megabytes`), and single-letter powers-of-two in both cases (`K`/`k`, per Lightbend).
 Supported byte units: `B`, `KB`/`KiB`, `MB`/`MiB`, `GB`/`GiB`, `TB`/`TiB` (and long forms like `megabytes`, `mebibytes`).
 
 ## Spec Compliance
@@ -386,9 +386,43 @@ const config = parseWithSchema(hoconInput, schema) // fails fast on startup
 |---------|----------|----------|-------------|
 | [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 |
+| [py.hocon](https://github.com/o3co/py.hocon) | Python | [PyPI](https://pypi.org/project/hocon-parser/) | HOCON parser for Python |
 | [hocon2](https://github.com/o3co/hocon2) | Go | [pkg.go.dev](https://pkg.go.dev/github.com/o3co/hocon2) | HOCON → JSON/YAML/TOML/Properties CLI |
 
-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.
+The four 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), [py.hocon](https://github.com/o3co/py.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.
+
+## Format adapters
+
+Config files that belong to *other* programs can be mounted as HOCON, so a
+`${...}` in your document can reach into them:
+
+```ts
+import { parseStringWithOptions } from '@o3co/ts.hocon'
+import { loadEnv } from '@o3co/ts.hocon/adapters/env'
+
+const base = loadEnv({ prefix: 'APP_' })            // APP_DB__HOST -> db.host
+const cfg = parseStringWithOptions(src, { resolveSubstitutions: false })
+const merged = cfg.withFallback(base).resolve()
+```
+
+Deferring resolution matters: the plain `parse` resolves as it goes, so a
+`${...}` aimed at the fallback would fail before the fallback is attached.
+
+| Subpath | Needs | Notes |
+| --- | --- | --- |
+| `@o3co/ts.hocon/adapters/properties` | — | `java.util.Properties`, sharing the `include` syntax layer |
+| `@o3co/ts.hocon/adapters/env` | — | Bulk-mounts a prefixed namespace; also reads `.env` |
+| `@o3co/ts.hocon/adapters/jsonc` | — | JSON with comments and trailing commas |
+| `@o3co/ts.hocon/adapters/toml` | `smol-toml` | Optional peer dependency |
+| `@o3co/ts.hocon/adapters/yaml` | `yaml` | Optional peer dependency; YAML 1.2 core schema |
+
+The TOML and YAML libraries are **optional peer dependencies**, so installing
+this package still pulls in nothing — you add the one you actually use. Plain
+JSON needs no adapter at all, HOCON being a JSON superset.
+
+Foreign data stays data: a `${a.b}` in a mounted value is literal text, never a
+reference, because the file belongs to a program that never agreed to HOCON's
+syntax.
 
 ## Known Limitations
 
@@ -396,13 +430,12 @@ The three parser implementations ([ts.hocon](https://github.com/o3co/ts.hocon),
 - **`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.
+- **Path traversal in includes:** a relative `include` path resolves against `baseDir` and can climb out of it with `..` segments to reach sensitive files such as `/etc/passwd`. 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.