@speclynx/apidom-datamodel 4.0.2 → 4.0.3

package/src/serialisers/JSONSerialiser.cjs

@@ -0,0 +1,230 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _SourceMap = _interopRequireDefault(require("../elements/SourceMap.cjs"));
+var _Style = _interopRequireDefault(require("../elements/Style.cjs"));
+/**
+ * Serialized representation of an Element in JSON Refract format.
+ * @public
+ */
+
+/**
+ * Serialized representation of a KeyValuePair in JSON Refract format.
+ * @public
+ */
+
+/**
+ * Possible content types in a serialized element.
+ * @public
+ */
+
+/**
+ * Input document format for deserialization.
+ * @public
+ */
+
+/**
+ * JSONSerialiser handles serialization and deserialization of ApiDOM elements
+ * to and from JSON Refract format.
+ * @public
+ */
+class JSONSerialiser {
+  namespace;
+
+  // This will be set via prototype assignment to avoid circular dependency
+
+  constructor(namespace) {
+    this.namespace = namespace || new this.Namespace();
+  }
+
+  /**
+   * Serializes an Element to JSON Refract format.
+   */
+  serialise(element) {
+    if (!(element instanceof this.namespace.elements.Element)) {
+      throw new TypeError(`Given element \`${element}\` is not an Element instance`);
+    }
+    const payload = {
+      element: element.element
+    };
+    if (!element.isMetaEmpty) {
+      const serialisedMeta = this.serialiseMeta(element);
+      if (serialisedMeta) {
+        payload.meta = serialisedMeta.meta;
+        if (serialisedMeta.rawKeys.length > 0) {
+          payload.__meta_raw__ = serialisedMeta.rawKeys;
+        }
+      }
+    }
+    if (!element.isAttributesEmpty) {
+      payload.attributes = this.serialiseObject(element.attributes);
+    }
+
+    // Serialize source position as __mappings__ in meta (skip for SourceMapElement itself)
+    if (!(element instanceof _SourceMap.default)) {
+      const sourceMap = _SourceMap.default.from(element);
+      if (sourceMap) {
+        if (!payload.meta) {
+          payload.meta = {};
+        }
+        payload.meta.__mappings__ = this.serialise(sourceMap);
+      }
+    }
+
+    // Serialize style as __styles__ in meta (skip for StyleElement itself)
+    if (!(element instanceof _Style.default)) {
+      const styleElement = _Style.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;
+    }
+    return payload;
+  }
+
+  /**
+   * Deserializes a JSON Refract document to an Element.
+   */
+  deserialise(value) {
+    if (!value.element) {
+      throw new Error('Given value is not an object containing an element name');
+    }
+    const ElementClass = this.namespace.getElementClass(value.element);
+    const element = new ElementClass();
+    if (element.element !== value.element) {
+      element.element = value.element;
+    }
+
+    // Extract special meta keys without mutating input, filter remaining meta
+    let mappingsDoc;
+    let stylesDoc;
+    let metaToDeserialize = value.meta;
+    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;
+    }
+
+    // determine which meta keys were raw primitives before serialization
+    const rawKeys = value.__meta_raw__ ? new Set(value.__meta_raw__) : undefined;
+    if (metaToDeserialize) {
+      for (const [key, doc] of Object.entries(metaToDeserialize)) {
+        const deserialized = this.deserialise(doc);
+        // unwrap keys that were raw primitives before serialization
+        element.setMetaProperty(key, rawKeys?.has(key) ? deserialized.toValue() : deserialized);
+      }
+    }
+
+    // Restore source position from __mappings__
+    if (mappingsDoc) {
+      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);
+    }
+    const content = this.deserialiseContent(value.content);
+    if (content !== undefined || element.content === null) {
+      element.content = content;
+    }
+    return element;
+  }
+  serialiseContent(content) {
+    if (content instanceof this.namespace.elements.Element) {
+      return this.serialise(content);
+    }
+    if (content instanceof this.namespace.KeyValuePair) {
+      const kvp = content;
+      const pair = {
+        key: this.serialise(kvp.key)
+      };
+      if (kvp.value) {
+        pair.value = this.serialise(kvp.value);
+      }
+      return pair;
+    }
+    if (content && Array.isArray(content)) {
+      if (content.length === 0) {
+        return undefined;
+      }
+      return content.map(item => this.serialise(item));
+    }
+    return content;
+  }
+  deserialiseContent(content) {
+    if (content) {
+      if (content.element) {
+        return this.deserialise(content);
+      }
+      if (content.key) {
+        const pair = new this.namespace.KeyValuePair(this.deserialise(content.key));
+        if (content.value) {
+          pair.value = this.deserialise(content.value);
+        }
+        return pair;
+      }
+      if (Array.isArray(content)) {
+        return content.map(item => this.deserialise(item));
+      }
+    }
+    return content;
+  }
+  serialiseMeta(element) {
+    const meta = {};
+    const rawKeys = [];
+    let hasEntries = false;
+    for (const [key, value] of Object.entries(element.meta)) {
+      if (value instanceof this.namespace.elements.Element) {
+        meta[key] = this.serialise(value);
+        hasEntries = true;
+      } else if (value !== undefined) {
+        // refract primitives to maintain JSON Refract spec compatibility
+        const refracted = element.refract(value);
+        meta[key] = this.serialise(refracted);
+        rawKeys.push(key);
+        hasEntries = true;
+      }
+    }
+    return hasEntries ? {
+      meta,
+      rawKeys
+    } : undefined;
+  }
+  serialiseObject(obj) {
+    const result = {};
+    obj.forEach((value, key) => {
+      if (value) {
+        result[key.toValue()] = this.serialise(value);
+      }
+    });
+    if (Object.keys(result).length === 0) {
+      return undefined;
+    }
+    return result;
+  }
+  deserialiseObject(from, to) {
+    Object.keys(from).forEach(key => {
+      to.set(key, this.deserialise(from[key]));
+    });
+  }
+}
+var _default = exports.default = JSONSerialiser;

package/src/serialisers/JSONSerialiser.mjs

@@ -0,0 +1,221 @@
+import SourceMapElement from "../elements/SourceMap.mjs";
+import StyleElement from "../elements/Style.mjs";
+/**
+ * Serialized representation of an Element in JSON Refract format.
+ * @public
+ */
+/**
+ * Serialized representation of a KeyValuePair in JSON Refract format.
+ * @public
+ */
+/**
+ * Possible content types in a serialized element.
+ * @public
+ */
+/**
+ * Input document format for deserialization.
+ * @public
+ */
+/**
+ * JSONSerialiser handles serialization and deserialization of ApiDOM elements
+ * to and from JSON Refract format.
+ * @public
+ */
+class JSONSerialiser {
+  namespace;
+
+  // This will be set via prototype assignment to avoid circular dependency
+
+  constructor(namespace) {
+    this.namespace = namespace || new this.Namespace();
+  }
+
+  /**
+   * Serializes an Element to JSON Refract format.
+   */
+  serialise(element) {
+    if (!(element instanceof this.namespace.elements.Element)) {
+      throw new TypeError(`Given element \`${element}\` is not an Element instance`);
+    }
+    const payload = {
+      element: element.element
+    };
+    if (!element.isMetaEmpty) {
+      const serialisedMeta = this.serialiseMeta(element);
+      if (serialisedMeta) {
+        payload.meta = serialisedMeta.meta;
+        if (serialisedMeta.rawKeys.length > 0) {
+          payload.__meta_raw__ = serialisedMeta.rawKeys;
+        }
+      }
+    }
+    if (!element.isAttributesEmpty) {
+      payload.attributes = this.serialiseObject(element.attributes);
+    }
+
+    // Serialize source position as __mappings__ in meta (skip for SourceMapElement itself)
+    if (!(element instanceof SourceMapElement)) {
+      const sourceMap = SourceMapElement.from(element);
+      if (sourceMap) {
+        if (!payload.meta) {
+          payload.meta = {};
+        }
+        payload.meta.__mappings__ = this.serialise(sourceMap);
+      }
+    }
+
+    // Serialize style as __styles__ in meta (skip for StyleElement itself)
+    if (!(element instanceof StyleElement)) {
+      const styleElement = StyleElement.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;
+    }
+    return payload;
+  }
+
+  /**
+   * Deserializes a JSON Refract document to an Element.
+   */
+  deserialise(value) {
+    if (!value.element) {
+      throw new Error('Given value is not an object containing an element name');
+    }
+    const ElementClass = this.namespace.getElementClass(value.element);
+    const element = new ElementClass();
+    if (element.element !== value.element) {
+      element.element = value.element;
+    }
+
+    // Extract special meta keys without mutating input, filter remaining meta
+    let mappingsDoc;
+    let stylesDoc;
+    let metaToDeserialize = value.meta;
+    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;
+    }
+
+    // determine which meta keys were raw primitives before serialization
+    const rawKeys = value.__meta_raw__ ? new Set(value.__meta_raw__) : undefined;
+    if (metaToDeserialize) {
+      for (const [key, doc] of Object.entries(metaToDeserialize)) {
+        const deserialized = this.deserialise(doc);
+        // unwrap keys that were raw primitives before serialization
+        element.setMetaProperty(key, rawKeys?.has(key) ? deserialized.toValue() : deserialized);
+      }
+    }
+
+    // Restore source position from __mappings__
+    if (mappingsDoc) {
+      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);
+    }
+    const content = this.deserialiseContent(value.content);
+    if (content !== undefined || element.content === null) {
+      element.content = content;
+    }
+    return element;
+  }
+  serialiseContent(content) {
+    if (content instanceof this.namespace.elements.Element) {
+      return this.serialise(content);
+    }
+    if (content instanceof this.namespace.KeyValuePair) {
+      const kvp = content;
+      const pair = {
+        key: this.serialise(kvp.key)
+      };
+      if (kvp.value) {
+        pair.value = this.serialise(kvp.value);
+      }
+      return pair;
+    }
+    if (content && Array.isArray(content)) {
+      if (content.length === 0) {
+        return undefined;
+      }
+      return content.map(item => this.serialise(item));
+    }
+    return content;
+  }
+  deserialiseContent(content) {
+    if (content) {
+      if (content.element) {
+        return this.deserialise(content);
+      }
+      if (content.key) {
+        const pair = new this.namespace.KeyValuePair(this.deserialise(content.key));
+        if (content.value) {
+          pair.value = this.deserialise(content.value);
+        }
+        return pair;
+      }
+      if (Array.isArray(content)) {
+        return content.map(item => this.deserialise(item));
+      }
+    }
+    return content;
+  }
+  serialiseMeta(element) {
+    const meta = {};
+    const rawKeys = [];
+    let hasEntries = false;
+    for (const [key, value] of Object.entries(element.meta)) {
+      if (value instanceof this.namespace.elements.Element) {
+        meta[key] = this.serialise(value);
+        hasEntries = true;
+      } else if (value !== undefined) {
+        // refract primitives to maintain JSON Refract spec compatibility
+        const refracted = element.refract(value);
+        meta[key] = this.serialise(refracted);
+        rawKeys.push(key);
+        hasEntries = true;
+      }
+    }
+    return hasEntries ? {
+      meta,
+      rawKeys
+    } : undefined;
+  }
+  serialiseObject(obj) {
+    const result = {};
+    obj.forEach((value, key) => {
+      if (value) {
+        result[key.toValue()] = this.serialise(value);
+      }
+    });
+    if (Object.keys(result).length === 0) {
+      return undefined;
+    }
+    return result;
+  }
+  deserialiseObject(from, to) {
+    Object.keys(from).forEach(key => {
+      to.set(key, this.deserialise(from[key]));
+    });
+  }
+}
+export default JSONSerialiser;