@o3co/ts.hocon 1.9.0 → 1.11.0

package/dist/adapters/yaml.d.cts

@@ -0,0 +1,51 @@
+import { C as Config } from '../config-Dlq6rF3w.cjs';
+
+/**
+ * Read a YAML document as HOCON config.
+ *
+ * This is a HOCON library, not a YAML implementation, and the API keeps that
+ * boundary. What this package owns is the decoded-tree → HOCON step, exposed
+ * directly as {@link fromYamlValue}: root must be a mapping, `${...}` stays
+ * literal, NaN and infinity are refused, a multi-document stream is refused,
+ * binary becomes its base64 text. How YAML *text* becomes a tree — whether
+ * `010` is 8 or 10, whether `no` is a boolean — is the YAML library's answer,
+ * not a contract here.
+ *
+ * `parseYaml` is a convenience front on `yaml` (eemeli), pinned to
+ * `version: '1.2'` so a library default cannot drift under it. A caller who
+ * needs a different library, version or schema decodes the text themselves and
+ * hands the tree to {@link fromYamlValue} — that is the supported way to swap
+ * parsers, and it keeps the choice, and its consequences, in the caller's
+ * hands:
+ *
+ * ```ts
+ * import jsy from 'js-yaml'
+ * const cfg = fromYamlValue(jsy.load(src), 'their-file.yml')
+ * ```
+ *
+ * Integers are ingested losslessly (F0.5): the document is decoded with
+ * `intAsBigInt`, so a literal too wide for a JS `number` keeps its digits —
+ * `getString` returns them exactly — and one outside int64 is refused rather
+ * than rounded. `getNumber` and `toObject` still apply the JS number model, so
+ * read large identifiers with `getString`.
+ *
+ * See docs/specs/format-ingestion-mapping.md items F5.x in the hocon scope.
+ */
+declare function parseYaml(input: string, originDescription?: string): Config;
+/**
+ * Build a Config from an already-decoded YAML value tree, produced by whatever
+ * YAML library and settings the caller chose. This is the tree-level boundary
+ * this module actually owns (spec F5); `parseYaml` is just a default decoder in
+ * front of it.
+ *
+ * Leaf normalization accepts the shapes common across JS YAML libraries, not
+ * only the default one: a `Map` (eemeli with `mapAsMap`) has its scalar keys
+ * stringified per F5.3, a `Date` (js-yaml 4 timestamps) becomes its ISO string
+ * — the same reasoning as F4.2 for TOML dates — and a `Uint8Array` becomes
+ * base64 (F5.5), at any size. A `bigint` (a library decoding integers widely)
+ * narrows to a number where a double is exact and otherwise keeps its digits,
+ * bounded by int64 (F0.5).
+ */
+declare function fromYamlValue(value: unknown, originDescription?: string): Config;
+
+export { fromYamlValue, parseYaml };

package/dist/adapters/yaml.d.ts

@@ -0,0 +1,51 @@
+import { C as Config } from '../config-Dlq6rF3w.js';
+
+/**
+ * Read a YAML document as HOCON config.
+ *
+ * This is a HOCON library, not a YAML implementation, and the API keeps that
+ * boundary. What this package owns is the decoded-tree → HOCON step, exposed
+ * directly as {@link fromYamlValue}: root must be a mapping, `${...}` stays
+ * literal, NaN and infinity are refused, a multi-document stream is refused,
+ * binary becomes its base64 text. How YAML *text* becomes a tree — whether
+ * `010` is 8 or 10, whether `no` is a boolean — is the YAML library's answer,
+ * not a contract here.
+ *
+ * `parseYaml` is a convenience front on `yaml` (eemeli), pinned to
+ * `version: '1.2'` so a library default cannot drift under it. A caller who
+ * needs a different library, version or schema decodes the text themselves and
+ * hands the tree to {@link fromYamlValue} — that is the supported way to swap
+ * parsers, and it keeps the choice, and its consequences, in the caller's
+ * hands:
+ *
+ * ```ts
+ * import jsy from 'js-yaml'
+ * const cfg = fromYamlValue(jsy.load(src), 'their-file.yml')
+ * ```
+ *
+ * Integers are ingested losslessly (F0.5): the document is decoded with
+ * `intAsBigInt`, so a literal too wide for a JS `number` keeps its digits —
+ * `getString` returns them exactly — and one outside int64 is refused rather
+ * than rounded. `getNumber` and `toObject` still apply the JS number model, so
+ * read large identifiers with `getString`.
+ *
+ * See docs/specs/format-ingestion-mapping.md items F5.x in the hocon scope.
+ */
+declare function parseYaml(input: string, originDescription?: string): Config;
+/**
+ * Build a Config from an already-decoded YAML value tree, produced by whatever
+ * YAML library and settings the caller chose. This is the tree-level boundary
+ * this module actually owns (spec F5); `parseYaml` is just a default decoder in
+ * front of it.
+ *
+ * Leaf normalization accepts the shapes common across JS YAML libraries, not
+ * only the default one: a `Map` (eemeli with `mapAsMap`) has its scalar keys
+ * stringified per F5.3, a `Date` (js-yaml 4 timestamps) becomes its ISO string
+ * — the same reasoning as F4.2 for TOML dates — and a `Uint8Array` becomes
+ * base64 (F5.5), at any size. A `bigint` (a library decoding integers widely)
+ * narrows to a number where a double is exact and otherwise keeps its digits,
+ * bounded by int64 (F0.5).
+ */
+declare function fromYamlValue(value: unknown, originDescription?: string): Config;
+
+export { fromYamlValue, parseYaml };