@o3co/ts.hocon 1.12.0 → 1.13.0

package/dist/adapters/json5.d.cts

@@ -0,0 +1,47 @@
+import { C as Config } from '../config-6sApTEMM.cjs';
+
+/**
+ * Read JSON5 (https://json5.org, spec 1.0.0) as HOCON config.
+ *
+ * Unlike the jsonc adapter — which strips comments and hands the rest to
+ * `JSON.parse` — JSON5 changes the token grammar itself (unquoted identifier
+ * keys, single-quoted strings with line continuations, hex integers, leading
+ * and trailing decimal points, an explicit plus sign), so this adapter is a
+ * hand-rolled scanner and recursive-descent parser. Zero dependencies, like
+ * every adapter in this package; it is a port of go.hocon's `adapters/json5`.
+ *
+ * The accepted grammar is JSON5 1.0.0 as defined by the reference
+ * implementation (the json5 npm package), the dialect owner this spec item
+ * tracks — the same ownership rule F3.2 applies to JSONC. That is why a `//`
+ * comment here ends at LS/PS as well as LF/CR, while the jsonc adapter's runs
+ * through them: each dialect's owner decides. Where the mapping spec is
+ * stricter than JSON5, the spec wins:
+ *
+ *   - `Infinity` and `NaN` (signed or bare) are errors, not values (spec F0.6).
+ *   - Integers — decimal or hex — must fit in int64 (spec F0.5); a number
+ *     written with `.`, `e` or `E` is a float, all other decimal forms and
+ *     every hex form are integers. An integer past 2^53 is carried as a
+ *     `bigint` so its digits survive verbatim (`getString` returns them
+ *     exactly); `getNumber` and `toObject` still apply the JS number model,
+ *     as they do for HOCON's own literals.
+ *   - An unpaired `\uXXXX` surrogate **escape** is an error, and a valid pair
+ *     combines into the astral codepoint (spec F3.5). This deliberately
+ *     differs from the jsonc adapter, which accepts one: there `JSON.parse` —
+ *     the host language's own decoder — owns the escape, and refusing would be
+ *     the spec overriding the platform (the S1.2.6 class). Here the scanner is
+ *     ours, so the four implementations can and do agree. A lone surrogate
+ *     *code unit* sitting raw in the source string is still accepted as data —
+ *     a JavaScript string is UTF-16 and holds it natively; go.hocon's
+ *     equivalent check rejects invalid UTF-8 bytes, a case that cannot arise
+ *     in a JS string.
+ *   - Duplicate keys follow HOCON semantics: objects merge, otherwise the
+ *     later value wins (spec F0.7).
+ *   - The document holds exactly one value; whitespace and comments may follow
+ *     it, anything else is an error (the F3.2 strictness rule).
+ *
+ * See the F3.x items in the format-ingestion mapping spec:
+ * https://github.com/o3co/xx.hocon/blob/main/docs/format-ingestion-mapping.md
+ */
+declare function parseJson5(input: string, originDescription?: string): Config;
+
+export { parseJson5 };

package/dist/adapters/json5.d.ts

@@ -0,0 +1,47 @@
+import { C as Config } from '../config-6sApTEMM.js';
+
+/**
+ * Read JSON5 (https://json5.org, spec 1.0.0) as HOCON config.
+ *
+ * Unlike the jsonc adapter — which strips comments and hands the rest to
+ * `JSON.parse` — JSON5 changes the token grammar itself (unquoted identifier
+ * keys, single-quoted strings with line continuations, hex integers, leading
+ * and trailing decimal points, an explicit plus sign), so this adapter is a
+ * hand-rolled scanner and recursive-descent parser. Zero dependencies, like
+ * every adapter in this package; it is a port of go.hocon's `adapters/json5`.
+ *
+ * The accepted grammar is JSON5 1.0.0 as defined by the reference
+ * implementation (the json5 npm package), the dialect owner this spec item
+ * tracks — the same ownership rule F3.2 applies to JSONC. That is why a `//`
+ * comment here ends at LS/PS as well as LF/CR, while the jsonc adapter's runs
+ * through them: each dialect's owner decides. Where the mapping spec is
+ * stricter than JSON5, the spec wins:
+ *
+ *   - `Infinity` and `NaN` (signed or bare) are errors, not values (spec F0.6).
+ *   - Integers — decimal or hex — must fit in int64 (spec F0.5); a number
+ *     written with `.`, `e` or `E` is a float, all other decimal forms and
+ *     every hex form are integers. An integer past 2^53 is carried as a
+ *     `bigint` so its digits survive verbatim (`getString` returns them
+ *     exactly); `getNumber` and `toObject` still apply the JS number model,
+ *     as they do for HOCON's own literals.
+ *   - An unpaired `\uXXXX` surrogate **escape** is an error, and a valid pair
+ *     combines into the astral codepoint (spec F3.5). This deliberately
+ *     differs from the jsonc adapter, which accepts one: there `JSON.parse` —
+ *     the host language's own decoder — owns the escape, and refusing would be
+ *     the spec overriding the platform (the S1.2.6 class). Here the scanner is
+ *     ours, so the four implementations can and do agree. A lone surrogate
+ *     *code unit* sitting raw in the source string is still accepted as data —
+ *     a JavaScript string is UTF-16 and holds it natively; go.hocon's
+ *     equivalent check rejects invalid UTF-8 bytes, a case that cannot arise
+ *     in a JS string.
+ *   - Duplicate keys follow HOCON semantics: objects merge, otherwise the
+ *     later value wins (spec F0.7).
+ *   - The document holds exactly one value; whitespace and comments may follow
+ *     it, anything else is an error (the F3.2 strictness rule).
+ *
+ * See the F3.x items in the format-ingestion mapping spec:
+ * https://github.com/o3co/xx.hocon/blob/main/docs/format-ingestion-mapping.md
+ */
+declare function parseJson5(input: string, originDescription?: string): Config;
+
+export { parseJson5 };