@speclynx/apidom-core 2.11.0 → 2.12.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.12.1](https://github.com/speclynx/apidom/compare/v2.12.0...v2.12.1) (2026-02-18)
+
+**Note:** Version bump only for package @speclynx/apidom-core
+
+# [2.12.0](https://github.com/speclynx/apidom/compare/v2.11.0...v2.12.0) (2026-02-18)
+
+### Features
+
+- add support for lossless JSON/YAML roundtrips ([#97](https://github.com/speclynx/apidom/issues/97)) ([dc17c9a](https://github.com/speclynx/apidom/commit/dc17c9a78fbc7df07a91e8f35b12be6409117d91))
+
 # [2.11.0](https://github.com/speclynx/apidom/compare/v2.10.3...v2.11.0) (2026-02-12)
 
 **Note:** Version bump only for package @speclynx/apidom-core

package/README.md

@@ -587,6 +587,21 @@ const objElement = new ObjectElement({ a: 'b' });
 toJSON(objElement); // => '{"a":"b"}'
 ```
 
+`toJSON` also accepts an options object as the second argument. When `preserveStyle` is `true`,
+the serializer uses style information from `element.style.json` (captured during parsing with `style: true`)
+to preserve original formatting such as indentation and raw number representation.
+
+```js
+import { toJSON } from '@speclynx/apidom-core';
+import { parse } from '@speclynx/apidom-parser-adapter-json';
+
+const parseResult = await parse(jsonString, { style: true });
+// ... modify elements ...
+toJSON(parseResult.result, { preserveStyle: true });
+```
+
+`toJSON` also supports the positional signature `toJSON(element, replacer?, space?)` matching [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
+
 ### toYAML
 
 Transforms the ApiDOM into YAML string.
@@ -606,6 +621,22 @@ toYAML(objElement);
  */
 ```
 
+`toYAML` accepts an optional second argument with serialization options. When `preserveStyle` is `true`,
+the serializer uses style information from `element.style.yaml` (captured during parsing with `style: true`)
+to preserve original formatting such as quoting styles, flow/block collections, comments, and indentation.
+Number format categories (exponential, hex, octal, fractional digits) are also preserved, though the
+underlying yaml library may normalize the exact representation (e.g., `1.0e10` becomes `1e+10`,
+`0x1A` becomes `0x1a`).
+
+```js
+import { toYAML } from '@speclynx/apidom-core';
+import { parse } from '@speclynx/apidom-parser-adapter-yaml-1-2';
+
+const parseResult = await parse(yamlString, { style: true });
+// ... modify elements ...
+toYAML(parseResult.result, { preserveStyle: true });
+```
+
 ### dehydrate
 
 Creates a [refract representation](https://github.com/refractproject/refract-spec) of an Element.