@o3co/ts.hocon 1.12.0 → 1.14.0

package/README.md

@@ -10,9 +10,11 @@ A [Lightbend HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) pars
 > **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/).
 
+**Docs:** [o3co.github.io/hocon](https://o3co.github.io/hocon/) — the cross-language hub for all four implementations, the hocon2 CLI and the shared conformance corpus.
+
 [日本語](README.ja.md)
 
-> **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.
+> **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`, `getPeriod`, `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), [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.
 
@@ -36,12 +38,13 @@ import { parse } from '@o3co/ts.hocon'          // ESM
 const { parse } = require('@o3co/ts.hocon')     // CJS
 ```
 
-On every PR and every release, CI loads all seven exports both ways against the
+On every PR and every release, CI loads all eight exports both ways against the
 built artifact, calls each one (including a package-scoped `include`, which
-behaves differently per bundle format), and checks that each condition declares
-its own type declarations. That gate exists because 1.10.0 shipped with all
-seven CJS entrypoints throwing at load; it catches that class of defect rather
-than promising none can exist.
+behaves differently per bundle format), checks that what a subpath returns or
+throws is an instance of the classes the root exports, and checks that each
+condition declares its own type declarations. That gate exists because 1.10.0
+shipped with all seven of its CJS entrypoints throwing at load; it catches that
+class of defect rather than promising none can exist.
 
 ### 2. Use
 
@@ -77,6 +80,49 @@ HOCON isn't just a serialization format — it's a **config-injection language**
 
 On top of that, HOCON combines the readability of YAML with the structure of JSON — making it a strong fit for anything beyond flat key-value config.
 
+## Configuration that stays inside its module
+
+In a large codebase, configuration tends to leak: one big file that every team edits, defaults copied into each service, and modules that read each other's keys. HOCON lets each module own its configuration the way it owns its code.
+
+- **Each module owns a namespace and ships its own defaults.** The `auth` module keeps `auth { … }` next to its code, with every default filled in. The application never copies those defaults; it brings them in with one `include`.
+- **The application overrides only what differs.** Later layers deep-merge over earlier ones, so the application states two keys, not the whole block.
+- **Each module reads only its own subtree, through its own schema.** The module asks for `auth` and validates it against the schema it defines. The shape of that section is the module's contract; nothing else in the file is visible to it.
+- **Wiring between modules lives in the application.** The module only declares the keys it reads (`auth.db`) and leaves them without a default when the application must supply them. The application connects them to shared values (`auth.db = ${shared.db}`). Modules never reference each other or the application's keys, so dependencies run one way.
+
+```hocon
+# auth/reference.conf: shipped inside the auth package, owned by the auth team
+auth {
+  session { lifetime = 30m, max-body = 64KiB }
+  # db: no default; the application supplies auth.db
+}
+```
+
+```hocon
+# application.conf: owned by the application
+include package("github.com/acme/auth", "reference.conf")
+
+shared.db { host = db.internal, port = 5432 }
+auth.db = ${shared.db}       # wiring lives in the application
+auth.session.lifetime = 2h   # override what differs; the rest stays the module's default
+```
+
+```ts
+// inside the auth module
+import { getValidated, hocon } from '@o3co/ts.hocon/zod'
+import { z } from 'zod'
+
+const Auth = z.object({
+  session: z.object({
+    lifetime: hocon.duration('s').pipe(z.number().int().positive()),
+    'max-body': hocon.bytes().pipe(z.number().int().positive()),
+  }),
+  db: z.object({ host: z.string(), port: z.number().int() }),
+})
+const auth = getValidated(config, 'auth', Auth)
+```
+
+`include package(...)` is not part of HOCON.md: it is a convention shared by the o3co implementations ([E11](https://github.com/o3co/xx.hocon/blob/main/docs/extra-spec-conventions.md#e11)), a non-JVM counterpart to `include classpath(...)`. It is how a module publishes its defaults without the application knowing where its files live (in ts.hocon, the default resolver hands `<identifier>/<file>` to Node module resolution from the including file, so the identifier there is the npm package name, such as `@acme/auth`, which E11 allows for TS-only config; a portable Go-style identifier like the one above needs a `packageResolver` that maps it to the package; see [`ParseOptions`](#parse-functions)). On the JVM, Lightbend's `reference.conf` convention plays the same role.
+
 ## Features
 
 - Full HOCON parsing: objects, arrays, scalars, substitutions (`${path}`, `${?path}`)
@@ -85,11 +131,12 @@ On top of that, HOCON combines the readability of YAML with the structure of JSO
 - `+=` append operator
 - `include "file.conf"` and `include file("file.conf")` directives
 - Triple-quoted strings (`"""..."""`)
-- Duration and byte size parsing (`getDuration()`, `getBytes()`)
+- Duration, byte size and period parsing (`getDuration()`, `getBytes()`, `getPeriod()`)
+- HOCON emitter (`renderHocon()`) — renders a resolved `Config` back to HOCON text; re-parsing yields the same value tree (E18 round-trip contract)
 - Sync and async API (`parse` / `parseAsync` / `parseFile` / `parseFileAsync`)
 - ESM + CJS dual package (every entrypoint smoke-tested in both formats on each CI run)
 - Optional [Zod](https://zod.dev/) integration for schema validation
-- Browser compatible (`parse`/`parseAsync` — no Node.js required)
+- Runs in browsers (`parse`/`parseAsync`; the bundler must stub Node built-ins, see [Browser Compatibility](#browser-compatibility))
 
 ## API
 
@@ -114,26 +161,35 @@ parseFileAsync(path: string, opts?: ParseOptions): Promise<Config>
 | `env` | `Record<string, string>` | Environment variables for substitution (default: `process.env`) |
 | `readFileSync` | `(path: string) => string` | Custom file reader (sync) |
 | `readFile` | `(path: string) => Promise<string>` | Custom file reader (async) |
+| `resolveSubstitutions` | `boolean` | `false` returns an unresolved Config, to resolve later (default `true`; see [Deferred resolution](#deferred-resolution-api-e12)) |
+| `originDescription` | `string` | Source name for resolve-error messages when there is no file path |
+| `resolveFrom` | `string \| string[]` | Where `include package(...)` starts Node module resolution (default: `baseDir`, which for `parseFile` is the file's directory; else `process.cwd()`) |
+| `packageResolver` | `PackageResolver` | Custom resolver for `include package(...)` (Yarn PnP, bundlers, edge runtimes, tests); `resolveFrom` is then ignored |
 
 ### Config methods
 
 | Method | Returns | Throws if |
 |--------|---------|-----------|
 | `get(path)` | `unknown \| undefined` | — |
+| `getValue(path)` (the raw value tree, for introspection) | `ReadonlyHoconValue \| undefined` | unresolved |
 | `getString(path)` | `string` | missing, wrong type, or unresolved |
 | `getNumber(path)` | `number` | missing, wrong type, or unresolved |
 | `getBoolean(path)` | `boolean` | missing, wrong type, or unresolved |
 | `getConfig(path)` | `Config` | missing, not an object, or unresolved |
 | `getList(path)` | `unknown[]` | missing, not an array, or unresolved |
-| `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 |
+| `getDuration(path, unit?)` | `number` | missing, not a string or number, invalid duration format, or not a finite number (E21) |
+| `getBytes(path, unit?)` | `number` | missing, not a string or number, invalid byte size format, negative, or beyond 2^53-1 bytes |
+| `getPeriod(path)` | `Period` | missing, not a string or number, or invalid period format |
 | `has(path)` | `boolean` | — |
 | `keys()` | `string[]` | — |
 | `withFallback(fallback)` | `Config` | — |
 | `resolve(opts?)` | `Config` | unresolvable substitution (unless `allowUnresolved: true`) |
 | `resolveWith(source, opts?)` | `Config` | source unresolved, or unresolvable substitution |
 | `isResolved()` | `boolean` | — |
-| `toObject()` | `unknown` | — |
+| `toObject(opts?)` | `unknown` | — (`{ nullPrototype: true }` returns objects that inherit nothing; see [Security Considerations](#security-considerations)) |
+| `renderHocon()` | `string` | unresolved |
+
+Every "Throws if" above is a `ConfigError` with `.path`, with two exceptions. An unresolved value read by `getValue` or a getter, or an unresolved `resolveWith` source, throws `NotResolvedError` (a `ConfigError` subclass). An unresolvable substitution in `resolve` / `resolveWith` throws `ResolveError`.
 
 ### Deferred resolution API (E12)
 
@@ -171,7 +227,7 @@ result.getString('r') // "val"
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `useSystemEnvironment` | `boolean` | `true` | Consult `process.env` for substitution fallback |
+| `useSystemEnvironment` | `boolean` | `true` | Consult the environment (`ParseOptions.env`, default `process.env`) for substitution fallback |
 | `allowUnresolved` | `boolean` | `false` | Leave unresolvable substitutions in place (no error) |
 
 ### Zod integration
@@ -194,21 +250,56 @@ const app = validate(cfg, Schema)
 const port = getValidated(cfg, 'server.port', z.number().int())
 ```
 
+Durations and byte sizes are strings in HOCON (`30m`, `64KiB`), so `z.number()` refuses them. The `hocon.duration(unit?)` and `hocon.bytes(unit?)` markers read them with the same rules as `getDuration()` / `getBytes()` and give a number in the requested unit (default `ms` / `B`; a plain number keeps the getters' meaning). Pipe the marker into a number schema for range and integer checks:
+
+```ts
+import { hocon, getValidated } from '@o3co/ts.hocon/zod'
+
+const Session = z.object({
+  lifetime: hocon.duration('s').pipe(z.number().int().min(60).max(86_400)),
+  maxBody: hocon.bytes().pipe(z.number().int().positive()),
+})
+
+// session { lifetime = 30m, maxBody = 64KiB }
+getValidated(cfg, 'session', Session) // { lifetime: 1800, maxBody: 65536 }
+```
+
+`hocon.period()` reads a period the way `getPeriod()` does and gives a `Period` (`{ years, months, days }`); refine it in the schema:
+
+```ts
+const Backup = z.object({
+  keep: hocon.period().refine((p) => p.years === 0, 'use months or days'),
+})
+
+// backup { keep = 2w }
+getValidated(cfg, 'backup', Backup) // { keep: { years: 0, months: 0, days: 14 } }
+```
+
+An invalid duration, size or period fails validation with the key's path. The markers are ordinary Zod schemas, so they work in `validate`, `getValidated`, `parseWithSchema`, `parseFileWithSchema` and anywhere else Zod runs them. Getters and markers both read exponent forms (`1e3`, `"1.5e2s"`). A marker reads a number through its JavaScript value, though, so a number literal with more significant digits than a double holds can read differently from the getters, which read the literal's text exactly (`1.99999999999999999` B is 1 through `getBytes()`, 2 through the marker); a period marker also reads a literal with a decimal point or an exponent (`7.0`, `1e2`) as an integer, which `getPeriod()` refuses. Write unit values with a unit (`30s`, `7d`) to avoid both.
+
+On an unresolved Config (parsed with `resolveSubstitutions: false`, a fallback stack not yet `resolve()`d, or the result of `resolve({ allowUnresolved: true })` with something left), `validate` throws `NotResolvedError`, as the getters do, rather than validating a tree with the pending values missing; `getValidated` throws it for a path whose value is unresolved and validates a resolved one. Call `resolve()` first.
+
 Install Zod as a peer dependency:
 ```bash
 npm install zod
 ```
 
+The Zod entry points (`validate`, `getValidated`, `parseWithSchema`, `parseFileWithSchema`) refuse an object key named `__proto__`, `constructor` or `prototype` anywhere in the value: Zod drops a `__proto__` key from a record without an error, and the three are refused alike so the result does not depend on the schema. The `ZodError` has one issue per key, at the object that holds it, with the key in the message and in `params.key` (`key "__proto__" names an object's prototype → at limits`). Rename the key, or read it with the plain getters (`cfg.getNumber('limits."constructor"')`), which are unaffected.
+
 ### Error types
 
 ```ts
-import { ParseError, ResolveError, ConfigError } from '@o3co/ts.hocon'
+import { ParseError, ResolveError, PackageLookupError, ConfigError, NotResolvedError } from '@o3co/ts.hocon'
 
-// ParseError   — lexing/parsing failure: .line, .col, .file?
-// ResolveError — substitution/include failure: .path, .line, .col, .file?
-// ConfigError  — wrong type or missing path: .path
+// ParseError         — lexing/parsing failure: .line, .col, .file?
+// ResolveError       — substitution/include failure: .path, .line, .col, .file?
+// PackageLookupError — include package(...) not found (a ResolveError): .identifier, .packageFile
+// ConfigError        — wrong type, missing path, invalid value: .path
+// NotResolvedError   — getter or Zod entry point on an unresolved value (a ConfigError): .path
 ```
 
+Every entrypoint (`/zod`, `/adapters/*`) throws these same classes, so `instanceof` against the root's exports works across entrypoints within one module system. The Zod entry points throw `ZodError` for a value that does not match the schema.
+
 ## HOCON Examples
 
 ```hocon
@@ -260,8 +351,36 @@ 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`). 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`).
+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). A number or a string with no unit is milliseconds for a duration and bytes for a byte size.
+
+The number is read from its text as an exact decimal and multiplied by the unit exactly (E20). A duration is then rounded once in the requested unit: `1.001s` is `1001` ms (`1001000000` ns), where Lightbend's double arithmetic gives `1000999999` ns. A byte size is truncated toward zero to whole bytes (as Lightbend does) before it is converted: `1.0009kB` is `1000`. A duration whose value is not a finite number is an error (E21). A byte size must be non-negative and at most 2^53-1 bytes (the largest integer a JS number holds exactly), so 1 or more of any exa-, zetta- or yotta- unit (`EB`, `Ei`/`EiB`, `E`/`e`, `exabyte`, … through `Y`) is an error; use fractions (`0.001EiB`) or a smaller unit.
+
+Supported byte units, the same set as Lightbend and case-sensitive like it:
+
+- bytes: `B`, `b`, `byte`, `bytes`
+- powers of 1000: `kB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`, `YB`, and `kilobyte(s)` … `yottabyte(s)`
+- powers of 1024: `Ki`/`KiB`, `Mi`/`MiB`, … `Yi`/`YiB`, and `kibibyte(s)` … `yobibyte(s)`
+- single letters, powers of 1024 in either case (java `-Xmx` style): `K`/`k`, `M`/`m`, `G`/`g`, `T`/`t`, `P`/`p`, `E`/`e`, `Z`/`z`, `Y`/`y`
+
+Other spellings are errors: `KB`, `kb`, `kib`, `Kilobytes`, `MEGABYTES`. (`'KB'` and the other names in `getBytes(path, unit)` are output units, a separate list.)
+
+### Periods
+
+```ts
+const c = parse(`
+  retention = 2w
+  billing   = "1 month"
+  archive   = 1y
+  grace     = 3       // a bare integer is days
+`)
+
+c.getPeriod('retention') // { years: 0, months: 0, days: 14 }
+c.getPeriod('billing')   // { years: 0, months: 1, days: 0 }
+c.getPeriod('archive')   // { years: 1, months: 0, days: 0 }
+c.getPeriod('grace')     // { years: 0, months: 0, days: 3 }
+```
+
+Supported period units: `d`/`day`/`days`, `w`/`week`/`weeks` (folded into days), `m`/`mo`/`month`/`months`, `y`/`year`/`years`. Unit names are case-sensitive and must be lowercase (`m` is months here, not minutes). A period is integer only (`7.5` is an error, unlike durations and sizes), may be negative, and each component must fit in a 32-bit signed integer, as in Lightbend (`java.time.Period`), rs.hocon and py.hocon.
 
 ## Spec Compliance
 
@@ -269,23 +388,29 @@ Conformance against the [Lightbend HOCON specification](https://github.com/light
 
 | Metric                                | Status        |
 | ------------------------------------- | ------------- |
-| Spec total (incl. out-of-scope)       | **89.3%**     |
-| In-scope only                         | **99.2%**     |
+| Spec total (incl. out-of-scope)       | **91.9%**     |
+| In-scope only                         | **100.0%**    |
 | Lightbend `test01`–`test13` suite     | 13/13 passing |
 
 **Extra-spec conventions (E-series) — implementation status:**
 
 | Item | Description | Status |
 |------|-------------|--------|
-| E11  | `include package(...)` service-locator includes | ✅ v1.3.0 |
+| E11  | `include package(...)` service-locator includes | ✅ v1.4.0 |
 | E12  | Deferred substitution resolution (`parse → withFallback → resolve()` lifecycle) | ✅ v1.4.0 |
+| E18  | HOCON emitter round-trip contract (`renderHocon()`) | ✅ v1.13.0 |
+| E19  | A float literal that overflows the double range (`1e999`) is a parse error | ✅ v1.14.0 |
+| E20  | Unit arithmetic is exact decimal (durations: a deliberate divergence from Lightbend) | ✅ v1.14.0 |
+| E21  | A duration the implementation cannot represent is an error | ✅ v1.14.0 |
+
+The E-series items are conventions shared by the o3co implementations beyond HOCON.md; see [`xx.hocon/docs/extra-spec-conventions.md`](https://github.com/o3co/xx.hocon/blob/main/docs/extra-spec-conventions.md).
 
 Not supported:
 
 - `include url(...)`
 - `include classpath(...)`
 
-Supported since v0.2.0 (P1):
+Supported since v1.0.0 (P1):
 
 - `.properties` file parsing
 
@@ -321,26 +446,33 @@ For typical application configs (loaded once at startup), the parsing cost is ne
 
 ### Feature Comparison with node-config
 
-Feature-level comparison with [node-config](https://github.com/node-config/node-config) **v4.4.2** reading JSON config files, as of 2026-07-26:
+Feature-level comparison with [node-config](https://github.com/node-config/node-config) **v5.0.1** reading JSON config files, as of 2026-10-16:
 
 | Feature | ts.hocon | node-config (JSON) |
 |---|---|---|
-| Comments | `//` `#` | No |
+| Comments | `//` `#` | Yes (`//`, `/* */`; `.json` is parsed as JSON5) |
 | 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) |
+| Deep merge | Yes (objects; arrays replaced, `+=` / concatenation to extend) | Yes (objects; 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) |
+| Typed getters | `getString`, `getNumber`, etc. (checked at runtime) | `get<T>()` (type parameter only, no runtime check) |
 
 ## Browser Compatibility
 
-`parse()` and `parseAsync()` work in browsers. `parseFile()` and `parseFileAsync()` require Node.js (or a custom `readFileSync`/`readFile` option).
+`parse()` and `parseAsync()` work in browsers, as do the adapters and the Zod integration. `parseFile()` and `parseFileAsync()` require Node.js (or a custom `readFileSync`/`readFile` option).
+
+The package still imports the Node built-ins `fs`, `path`, `module` and `url` (for file reading and `include package(...)`) and uses them only on those paths. A browser bundle needs them replaced by empty modules:
+
+- **Vite** (7 and 8) does this by default, so there is nothing to configure.
+- **Other bundlers:** map the four modules to an empty module (`export default {}`), for example with an esbuild plugin or webpack 5's `resolve.fallback: { fs: false, path: false, module: false, url: false }`. Marking them external is not enough, because the browser cannot load `fs`.
+
+That covers parsing without file includes. Includes read through your own `readFile` / `readFileSync` (below) also resolve paths, so they need a browser implementation of `path` instead of the empty module, such as the `path-browserify` package. `include package(...)` needs a custom `packageResolver` there (see `ParseOptions`).
 
 ```ts
 // Browser usage with custom file loader
@@ -407,7 +539,7 @@ const config = parseWithSchema(hoconInput, schema) // fails fast on startup
 | 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 |
+| [rs.hocon](https://github.com/o3co/rs.hocon) | Rust | [crates.io](https://crates.io/crates/hocon-parser) | 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 |
 
@@ -435,8 +567,9 @@ Deferring resolution matters: the plain `parse` resolves as it goes, so a
 | `@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` 2.9.x | Optional peer dependency; scalar resolution is that library's answer, with `version: '1.2'` declared so it cannot drift |
+| `@o3co/ts.hocon/adapters/json5` | — | JSON5 1.0.0, hand-rolled scanner, zero dependencies |
+| `@o3co/ts.hocon/adapters/toml` | `smol-toml` (>= 1.0) | Optional peer dependency |
+| `@o3co/ts.hocon/adapters/yaml` | `yaml` (>= 2.0) | Optional peer dependency; scalar resolution is that library's answer, with `version: '1.2'` declared so it cannot drift |
 
 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
@@ -458,11 +591,12 @@ cfg.getString('"foo.bar"')   // "dotted"  — one key whose name contains a dot
 cfg.getString('foo.bar')     // "nested"  — foo -> bar
 ```
 
-### Numbers from JSONC and YAML
+### Numbers from JSONC, JSON5 and YAML
 
 Integers are ingested losslessly: an integer literal too wide for a JS `number`
 keeps its digits instead of being rounded, and one outside the int64 range is
-refused rather than silently mangled. What you get back depends on the getter:
+refused rather than silently mangled (JSON5's hex integers included). What you
+get back depends on the getter:
 
 ```ts
 const cfg = parseJsonc('{"id": 9007199254740993}')