@speclynx/apidom-parser-adapter-json 2.10.3 → 2.12.0

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.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-parser-adapter-json
+
 ## [2.10.3](https://github.com/speclynx/apidom/compare/v2.10.2...v2.10.3) (2026-02-10)
 
 **Note:** Version bump only for package @speclynx/apidom-parser-adapter-json

package/README.md

@@ -72,7 +72,8 @@ This adapter exposes an instance of [base ApiDOM namespace](https://github.com/s
 Option | Type | Default | Description
 --- | --- | --- | ---
 <a name="sourceMap"></a>`sourceMap` | `Boolean` | `false` | Indicate whether to generate source maps.
-<a name="strict"></a>`strict` | `Boolean` | `false` | Use strict parsing mode (native `JSON.parse`). When `true`, parsing is faster but throws on invalid JSON and doesn't support source maps.
+<a name="style"></a>`style` | `Boolean` | `false` | Indicate whether to capture format-specific style information for round-trip preservation.
+<a name="strict"></a>`strict` | `Boolean` | `false` | Use strict parsing mode (native `JSON.parse`). When `true`, parsing is faster but throws on invalid JSON and doesn't support source maps or style preservation.
 
 All unrecognized arbitrary options will be ignored.
 
@@ -84,6 +85,7 @@ This adapter supports two parsing modes:
 - Uses [web-tree-sitter](https://www.npmjs.com/package/web-tree-sitter) for parsing
 - Provides error recovery for malformed JSON
 - Supports source map generation
+- Supports style preservation (indentation, raw number representation)
 - Slightly slower but more resilient
 
 **Strict mode** (`strict: true`):
@@ -91,6 +93,7 @@ This adapter supports two parsing modes:
 - Faster performance
 - Throws `SyntaxError` on invalid JSON
 - Does not support source maps (throws error if both `strict` and `sourceMap` are `true`)
+- Does not support style preservation (throws error if both `strict` and `style` are `true`)
 
 ## Usage
 
@@ -115,7 +118,10 @@ await detect('{invalid}', { strict: true }); // => false
 // parsing (tree-sitter mode - default, with source maps)
 const parseResult = await parse('{"prop": "value"}', { sourceMap: true });
 
-// parsing (strict mode - faster, no source maps)
+// parsing (tree-sitter mode, with style preservation)
+const parseResultStyled = await parse('{"prop": "value"}', { style: true });
+
+// parsing (strict mode - faster, no source maps or style)
 const parseResultStrict = await parse('{"prop": "value"}', { strict: true });
 ```
 

package/dist/apidom-parser-adapter-json.browser.js

@@ -136,12 +136,14 @@ const detect = async source => {
  * @public
  */
 const parse = async (source, {
-  sourceMap = false
+  sourceMap = false,
+  style = false
 } = {}) => {
   const cst = await (0,_lexical_analysis_index_ts__WEBPACK_IMPORTED_MODULE_0__["default"])(source);
   try {
     return (0,_syntactic_analysis_index_ts__WEBPACK_IMPORTED_MODULE_1__["default"])(cst, {
-      sourceMap
+      sourceMap,
+      style
     });
   } finally {
     cst.delete();
@@ -244,6 +246,24 @@ const maybeAddSourceMap = (info, element, ctx) => {
   element.endCharacter = info.endPosition.column;
   element.endOffset = info.endIndex;
 };
+
+// build json style object for an element
+const buildJsonStyle = (ctx, extras) => {
+  const jsonStyle = {
+    indent: ctx.indent
+  };
+  if (extras) Object.assign(jsonStyle, extras);
+  return {
+    json: jsonStyle
+  };
+};
+
+// detect indent from an object's first pair child position
+// called during transformChildren when we encounter the first pair
+const detectIndent = (objectColumn, firstPairColumn) => {
+  const diff = firstPairColumn - objectColumn;
+  return diff > 0 ? diff : 2;
+};
 const transform = (cursor, transformerMap, ctx) => {
   const info = getCursorInfo(cursor);
 
@@ -307,11 +327,27 @@ const createTransformers = transformerMap => ({
     const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__["default"]();
     maybeAddSourceMap(info, element, ctx);
 
+    // Detect indent from first pair if style is enabled and not yet detected
+    if (ctx.style && ctx.indent === 0) {
+      if (cursor.gotoFirstChild()) {
+        do {
+          if (cursor.nodeType === 'pair') {
+            ctx.indent = detectIndent(info.startPosition.column, cursor.startPosition.column);
+            break;
+          }
+        } while (cursor.gotoNextSibling());
+        cursor.gotoParent();
+      }
+    }
+
     // Transform children (pairs)
     const children = transformChildren(cursor, transformerMap, ctx);
     for (const child of children) {
       element.push(child);
     }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
     return element;
   },
   array(cursor, ctx) {
@@ -324,6 +360,9 @@ const createTransformers = transformerMap => ({
     for (const child of children) {
       element.push(child);
     }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
     return element;
   },
   pair(cursor, ctx) {
@@ -365,30 +404,47 @@ const createTransformers = transformerMap => ({
         });
       }
     }
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
     maybeAddSourceMap(info, element, ctx);
     return element;
   },
   number(cursor, ctx) {
     const info = getCursorInfo(cursor);
     const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__["default"](Number(info.text));
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx, {
+        rawContent: info.text
+      });
+    }
     maybeAddSourceMap(info, element, ctx);
     return element;
   },
   null(cursor, ctx) {
     const info = getCursorInfo(cursor);
     const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__["default"]();
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
     maybeAddSourceMap(info, element, ctx);
     return element;
   },
   true(cursor, ctx) {
     const info = getCursorInfo(cursor);
     const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"](true);
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
     maybeAddSourceMap(info, element, ctx);
     return element;
   },
   false(cursor, ctx) {
     const info = getCursorInfo(cursor);
     const element = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__["default"](false);
+    if (ctx.style) {
+      element.style = buildJsonStyle(ctx);
+    }
     maybeAddSourceMap(info, element, ctx);
     return element;
   },
@@ -419,11 +475,14 @@ Object.assign(transformers, createTransformers(transformers));
  * @public
  */
 const analyze = (cst, {
-  sourceMap = false
+  sourceMap = false,
+  style = false
 } = {}) => {
   const cursor = cst.walk();
   const ctx = {
     sourceMap,
+    style,
+    indent: 0,
     annotations: []
   };
   const result = transform(cursor, transformers, ctx);
@@ -5924,6 +5983,66 @@ function unpackSourceMap(packed) {
 
 /***/ },
 
+/***/ 9686
+(__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */ });
+/* harmony import */ var _primitives_ObjectElement_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(7071);
+
+/**
+ * Shape with optional style property.
+ * @public
+ */
+/**
+ * StyleElement stores format-specific style information for round-trip preservation.
+ *
+ * The style data is stored as a plain object with format-specific namespaces
+ * (e.g., `yaml`, `json`). This element exists only during serialization/deserialization
+ * (refract format) - in memory, style lives directly on `element.style`.
+ *
+ * Follows the same pattern as SourceMapElement with __mappings__.
+ *
+ * @public
+ */
+class StyleElement extends _primitives_ObjectElement_mjs__WEBPACK_IMPORTED_MODULE_0__["default"] {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = '__styles__';
+  }
+
+  /**
+   * Transfers style property from one element to another.
+   */
+  static transfer(from, to) {
+    to.style = from.style;
+  }
+
+  /**
+   * Creates a StyleElement from an element's style property.
+   * Returns undefined if the element has no style.
+   */
+  static from(source) {
+    if (!source.style) {
+      return undefined;
+    }
+    return new StyleElement(source.style);
+  }
+
+  /**
+   * Restores the style property on the target element from this StyleElement.
+   */
+  applyTo(target) {
+    target.style = this.toValue();
+  }
+}
+/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (StyleElement);
+
+/***/ },
+
 /***/ 6911
 (__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) {
 
@@ -5988,6 +6107,7 @@ const isSourceMapElement = element => element instanceof _elements_SourceMap_mjs
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   hasElementSourceMap: () => (/* binding */ hasElementSourceMap),
+/* harmony export */   hasElementStyle: () => (/* binding */ hasElementStyle),
 /* harmony export */   includesClasses: () => (/* binding */ includesClasses),
 /* harmony export */   includesSymbols: () => (/* binding */ includesSymbols),
 /* harmony export */   isAnnotationElement: () => (/* reexport safe */ _elements_mjs__WEBPACK_IMPORTED_MODULE_1__.isAnnotationElement),
@@ -6012,6 +6132,14 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+/**
+ * Checks if an element has format-specific style information.
+ * @public
+ */
+const hasElementStyle = element => {
+  return element.style !== undefined;
+};
+
 /**
  * Checks if an element has complete source position information.
  * Returns true only if all 6 position properties are numbers.
@@ -6553,6 +6681,12 @@ class Element {
    */
   parent;
 
+  /**
+   * Format-specific style information for round-trip preservation.
+   * Each format owns its own namespace (e.g., `yaml`, `json`).
+   */
+  style;
+
   // ============================================================================
   // Source Position (LSP-compatible, TextDocument-compatible, UTF-16 code units)
   // web-tree-sitter automatically provides position data in UTF-16 code units.
@@ -6761,7 +6895,13 @@ class Element {
 
   /** Unique identifier for this element. */
   get id() {
-    return this.getMetaProperty('id', '');
+    if (this.isFrozen) {
+      return this.getMetaProperty('id', '');
+    }
+    if (!this.hasMetaProperty('id')) {
+      this.setMetaProperty('id', '');
+    }
+    return this.meta.get('id');
   }
   set id(value) {
     this.setMetaProperty('id', value);
@@ -6769,7 +6909,13 @@ class Element {
 
   /** CSS-like class names. */
   get classes() {
-    return this.getMetaProperty('classes', []);
+    if (this.isFrozen) {
+      return this.getMetaProperty('classes', []);
+    }
+    if (!this.hasMetaProperty('classes')) {
+      this.setMetaProperty('classes', []);
+    }
+    return this.meta.get('classes');
   }
   set classes(value) {
     this.setMetaProperty('classes', value);
@@ -6777,7 +6923,13 @@ class Element {
 
   /** Hyperlinks associated with this element. */
   get links() {
-    return this.getMetaProperty('links', []);
+    if (this.isFrozen) {
+      return this.getMetaProperty('links', []);
+    }
+    if (!this.hasMetaProperty('links')) {
+      this.setMetaProperty('links', []);
+    }
+    return this.meta.get('links');
   }
   set links(value) {
     this.setMetaProperty('links', value);
@@ -6928,16 +7080,26 @@ class Element {
   }
 
   /**
-   * Gets a meta property, creating it with default value if not present.
+   * Gets a meta property.
+   *
+   * When the property doesn't exist:
+   * - With defaultValue: returns a new refracted element instance (not cached)
+   * - Without defaultValue: returns undefined
+   *
+   * Note: Each call with a default creates a new instance. Use setMetaProperty
+   * first if you need reference equality across multiple accesses.
    */
+
   getMetaProperty(name, defaultValue) {
-    if (!this.meta.hasKey(name)) {
-      if (this.isFrozen) {
-        const element = this.refract(defaultValue);
+    if (!this.hasMetaProperty(name)) {
+      if (defaultValue === undefined) {
+        return undefined;
+      }
+      const element = this.refract(defaultValue);
+      if (element && this.isFrozen) {
         element.freeze();
-        return element;
       }
-      this.meta.set(name, defaultValue);
+      return element;
     }
     return this.meta.get(name);
   }
@@ -7414,17 +7576,18 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   CollectionElement: () => (/* reexport safe */ _primitives_CollectionElement_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]),
 /* harmony export */   CommentElement: () => (/* reexport safe */ _elements_Comment_mjs__WEBPACK_IMPORTED_MODULE_12__["default"]),
 /* harmony export */   Element: () => (/* reexport safe */ _primitives_Element_mjs__WEBPACK_IMPORTED_MODULE_0__["default"]),
-/* harmony export */   KeyValuePair: () => (/* reexport safe */ _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_16__["default"]),
+/* harmony export */   KeyValuePair: () => (/* reexport safe */ _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_17__["default"]),
 /* harmony export */   LinkElement: () => (/* reexport safe */ _elements_LinkElement_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]),
 /* harmony export */   MemberElement: () => (/* reexport safe */ _primitives_MemberElement_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]),
 /* harmony export */   NullElement: () => (/* reexport safe */ _primitives_NullElement_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]),
 /* harmony export */   NumberElement: () => (/* reexport safe */ _primitives_NumberElement_mjs__WEBPACK_IMPORTED_MODULE_4__["default"]),
 /* harmony export */   ObjectElement: () => (/* reexport safe */ _primitives_ObjectElement_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]),
-/* harmony export */   ObjectSlice: () => (/* reexport safe */ _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_15__["default"]),
+/* harmony export */   ObjectSlice: () => (/* reexport safe */ _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_16__["default"]),
 /* harmony export */   ParseResultElement: () => (/* reexport safe */ _elements_ParseResult_mjs__WEBPACK_IMPORTED_MODULE_13__["default"]),
 /* harmony export */   RefElement: () => (/* reexport safe */ _elements_RefElement_mjs__WEBPACK_IMPORTED_MODULE_10__["default"]),
 /* harmony export */   SourceMapElement: () => (/* reexport safe */ _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_14__["default"]),
 /* harmony export */   StringElement: () => (/* reexport safe */ _primitives_StringElement_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]),
+/* harmony export */   StyleElement: () => (/* reexport safe */ _elements_Style_mjs__WEBPACK_IMPORTED_MODULE_15__["default"]),
 /* harmony export */   refract: () => (/* binding */ refract)
 /* harmony export */ });
 /* harmony import */ var _primitives_Element_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(728);
@@ -7442,8 +7605,10 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _elements_Comment_mjs__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__(94);
 /* harmony import */ var _elements_ParseResult_mjs__WEBPACK_IMPORTED_MODULE_13__ = __webpack_require__(4823);
 /* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_14__ = __webpack_require__(5810);
-/* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_15__ = __webpack_require__(8504);
-/* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_16__ = __webpack_require__(6663);
+/* harmony import */ var _elements_Style_mjs__WEBPACK_IMPORTED_MODULE_15__ = __webpack_require__(9686);
+/* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_16__ = __webpack_require__(8504);
+/* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_17__ = __webpack_require__(6663);
+
 
 
 
@@ -7530,6 +7695,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
 /* harmony export */ });
 /* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(5810);
+/* harmony import */ var _elements_Style_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(9686);
+
 
 /**
  * Serialized representation of an Element in JSON Refract format.
@@ -7588,6 +7755,17 @@ class JSONSerialiser {
         payload.meta.__mappings__ = this.serialise(sourceMap);
       }
     }
+
+    // Serialize style as __styles__ in meta (skip for StyleElement itself)
+    if (!(element instanceof _elements_Style_mjs__WEBPACK_IMPORTED_MODULE_1__["default"])) {
+      const styleElement = _elements_Style_mjs__WEBPACK_IMPORTED_MODULE_1__["default"].from(element);
+      if (styleElement) {
+        if (!payload.meta) {
+          payload.meta = {};
+        }
+        payload.meta.__styles__ = this.serialise(styleElement);
+      }
+    }
     const content = this.serialiseContent(element.content);
     if (content !== undefined) {
       payload.content = content;
@@ -7608,15 +7786,18 @@ class JSONSerialiser {
       element.element = value.element;
     }
 
-    // Extract __mappings__ without mutating input, filter remaining meta
+    // Extract __mappings__ and __styles__ without mutating input, filter remaining meta
     let mappingsDoc;
+    let stylesDoc;
     let metaToDeserialize = value.meta;
-    if (value.meta?.__mappings__) {
+    if (value.meta?.__mappings__ || value.meta?.__styles__) {
       const {
         __mappings__,
+        __styles__,
         ...rest
       } = value.meta;
       mappingsDoc = __mappings__;
+      stylesDoc = __styles__;
       metaToDeserialize = Object.keys(rest).length > 0 ? rest : undefined;
     }
     if (metaToDeserialize) {
@@ -7628,6 +7809,12 @@ class JSONSerialiser {
       const sourceMap = this.deserialise(mappingsDoc);
       sourceMap.applyTo(element);
     }
+
+    // Restore style from __styles__
+    if (stylesDoc) {
+      const styleElement = this.deserialise(stylesDoc);
+      styleElement.applyTo(element);
+    }
     if (value.attributes) {
       this.deserialiseObject(value.attributes, element.attributes);
     }
@@ -7971,16 +8158,21 @@ const detect = async (source, {
  */
 const parse = async (source, {
   sourceMap = false,
+  style = false,
   strict = false
 } = {}) => {
   if (strict && sourceMap) {
     throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_1__["default"]('Cannot use sourceMap with strict parsing. Strict parsing does not support source maps.');
   }
+  if (strict && style) {
+    throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_1__["default"]('Cannot use style with strict parsing. Strict parsing does not support style preservation.');
+  }
   if (strict) {
     return _native_index_ts__WEBPACK_IMPORTED_MODULE_2__.parse(source);
   }
   return _tree_sitter_index_ts__WEBPACK_IMPORTED_MODULE_3__.parse(source, {
-    sourceMap
+    sourceMap,
+    style
   });
 };
 })();