@speclynx/apidom-core 4.0.1 → 4.0.3

package/src/transformers/dehydrate.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _namespace = _interopRequireDefault(require("../namespace.cjs"));
+/**
+ * Creates a refract representation of an Element.
+ * https://github.com/refractproject/refract-spec
+ * @public
+ */
+const dehydrate = (element, namespace = _namespace.default) => {
+  return namespace.toRefract(element);
+};
+var _default = exports.default = dehydrate;

package/src/transformers/dehydrate.mjs

@@ -0,0 +1,10 @@
+import defaultNamespaceInstance from "../namespace.mjs";
+/**
+ * Creates a refract representation of an Element.
+ * https://github.com/refractproject/refract-spec
+ * @public
+ */
+const dehydrate = (element, namespace = defaultNamespaceInstance) => {
+  return namespace.toRefract(element);
+};
+export default dehydrate;

package/src/transformers/dehydrate.ts

@@ -0,0 +1,14 @@
+import { Element, Namespace } from '@speclynx/apidom-datamodel';
+
+import defaultNamespaceInstance from '../namespace.ts';
+
+/**
+ * Creates a refract representation of an Element.
+ * https://github.com/refractproject/refract-spec
+ * @public
+ */
+const dehydrate = (element: Element, namespace: Namespace = defaultNamespaceInstance): unknown => {
+  return namespace.toRefract(element);
+};
+
+export default dehydrate;

package/src/transformers/from.cjs

@@ -0,0 +1,34 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _namespace = _interopRequireDefault(require("../namespace.cjs"));
+/**
+ * Transforms data to an Element from a particular namespace.
+ *
+ * The name of the function was originally `from`,
+ * but it was renamed to `fromFn` to avoid issues with Parcel.js:
+ *
+ * - https://github.com/parcel-bundler/parcel/issues/9473
+ * - https://github.com/swagger-api/swagger-ui/issues/9466#issuecomment-1881053410
+ * @public
+ */
+const fromFn = (data, namespace = _namespace.default) => {
+  if ((0, _ramdaAdjunct.isString)(data)) {
+    // JSON serialized refract
+    try {
+      return namespace.fromRefract(JSON.parse(data));
+    } catch {
+      // noop
+    }
+  }
+  if ((0, _ramdaAdjunct.isPlainObject)(data) && (0, _ramda.has)('element', data)) {
+    // refract javascript structure
+    return namespace.fromRefract(data);
+  }
+  return namespace.toElement(data);
+};
+var _default = exports.default = fromFn;

package/src/transformers/from.mjs

@@ -0,0 +1,29 @@
+import { has } from 'ramda';
+import { isPlainObject, isString } from 'ramda-adjunct';
+import defaultNamespace from "../namespace.mjs";
+/**
+ * Transforms data to an Element from a particular namespace.
+ *
+ * The name of the function was originally `from`,
+ * but it was renamed to `fromFn` to avoid issues with Parcel.js:
+ *
+ * - https://github.com/parcel-bundler/parcel/issues/9473
+ * - https://github.com/swagger-api/swagger-ui/issues/9466#issuecomment-1881053410
+ * @public
+ */
+const fromFn = (data, namespace = defaultNamespace) => {
+  if (isString(data)) {
+    // JSON serialized refract
+    try {
+      return namespace.fromRefract(JSON.parse(data));
+    } catch {
+      // noop
+    }
+  }
+  if (isPlainObject(data) && has('element', data)) {
+    // refract javascript structure
+    return namespace.fromRefract(data);
+  }
+  return namespace.toElement(data);
+};
+export default fromFn;

package/src/transformers/from.ts

@@ -0,0 +1,34 @@
+import { has } from 'ramda';
+import { isPlainObject, isString } from 'ramda-adjunct';
+import { Element, Namespace } from '@speclynx/apidom-datamodel';
+
+import defaultNamespace from '../namespace.ts';
+
+/**
+ * Transforms data to an Element from a particular namespace.
+ *
+ * The name of the function was originally `from`,
+ * but it was renamed to `fromFn` to avoid issues with Parcel.js:
+ *
+ * - https://github.com/parcel-bundler/parcel/issues/9473
+ * - https://github.com/swagger-api/swagger-ui/issues/9466#issuecomment-1881053410
+ * @public
+ */
+const fromFn = (data: unknown, namespace: Namespace = defaultNamespace): Element | undefined => {
+  if (isString(data)) {
+    // JSON serialized refract
+    try {
+      return namespace.fromRefract(JSON.parse(data));
+    } catch {
+      // noop
+    }
+  }
+  if (isPlainObject(data) && has('element', data)) {
+    // refract javascript structure
+    return namespace.fromRefract(data);
+  }
+
+  return namespace.toElement(data);
+};
+
+export default fromFn;

package/src/transformers/serializers/json.cjs

@@ -0,0 +1,75 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _value = _interopRequireDefault(require("./value.cjs"));
+const getStyle = element => {
+  return element.style?.json ?? {};
+};
+
+/**
+ * @public
+ */
+
+/**
+ * Builds a POJO from an ApiDOM element tree. Numbers with rawContent
+ * are replaced with sentinel strings; all other values go through toValue().
+ */
+const toPojo = (element, sentinels) => {
+  const visited = new WeakSet();
+  const convert = node => {
+    if (!(0, _apidomDatamodel.isElement)(node)) return node;
+    if (visited.has(node)) return null;
+    visited.add(node);
+    if ((0, _apidomDatamodel.isObjectElement)(node)) {
+      const obj = {};
+      node.forEach((value, key) => {
+        const k = (0, _apidomDatamodel.isElement)(key) ? (0, _value.default)(key) : key;
+        if (typeof k === 'string') obj[k] = convert(value);
+      });
+      return obj;
+    }
+    if ((0, _apidomDatamodel.isArrayElement)(node)) {
+      const arr = [];
+      node.forEach(item => arr.push(convert(item)));
+      return arr;
+    }
+    if ((0, _apidomDatamodel.isRefElement)(node)) return String((0, _value.default)(node));
+    if ((0, _apidomDatamodel.isLinkElement)(node)) return (0, _apidomDatamodel.isStringElement)(node.href) ? (0, _value.default)(node.href) : '';
+
+    // number with rawContent — substitute with sentinel
+    if ((0, _apidomDatamodel.isNumberElement)(node)) {
+      const style = getStyle(node);
+      if (typeof style.rawContent === 'string') {
+        const sentinel = `\0RAW${sentinels.size}\0`;
+        sentinels.set(sentinel, style.rawContent);
+        return sentinel;
+      }
+    }
+    return (0, _value.default)(node);
+  };
+  return convert(element);
+};
+
+/**
+ * @public
+ */
+const serializer = (element, replacer, space, options) => {
+  if (options?.preserveStyle) {
+    const style = getStyle(element);
+    const indent = typeof space === 'number' ? space : typeof style.indent === 'number' ? style.indent : 0;
+    const sentinels = new Map();
+    const pojo = toPojo(element, sentinels);
+    let serialized = JSON.stringify(pojo, null, indent);
+
+    // replace quoted sentinels with raw number representations
+    for (const [sentinel, raw] of sentinels) {
+      serialized = serialized.replace(JSON.stringify(sentinel), raw);
+    }
+    return serialized;
+  }
+  return JSON.stringify((0, _value.default)(element), replacer, space);
+};
+var _default = exports.default = serializer;

package/src/transformers/serializers/json.mjs

@@ -0,0 +1,70 @@
+import { isElement, isObjectElement, isArrayElement, isRefElement, isLinkElement, isStringElement, isNumberElement } from '@speclynx/apidom-datamodel';
+import toValue from "./value.mjs";
+const getStyle = element => {
+  return element.style?.json ?? {};
+};
+
+/**
+ * @public
+ */
+
+/**
+ * Builds a POJO from an ApiDOM element tree. Numbers with rawContent
+ * are replaced with sentinel strings; all other values go through toValue().
+ */
+const toPojo = (element, sentinels) => {
+  const visited = new WeakSet();
+  const convert = node => {
+    if (!isElement(node)) return node;
+    if (visited.has(node)) return null;
+    visited.add(node);
+    if (isObjectElement(node)) {
+      const obj = {};
+      node.forEach((value, key) => {
+        const k = isElement(key) ? toValue(key) : key;
+        if (typeof k === 'string') obj[k] = convert(value);
+      });
+      return obj;
+    }
+    if (isArrayElement(node)) {
+      const arr = [];
+      node.forEach(item => arr.push(convert(item)));
+      return arr;
+    }
+    if (isRefElement(node)) return String(toValue(node));
+    if (isLinkElement(node)) return isStringElement(node.href) ? toValue(node.href) : '';
+
+    // number with rawContent — substitute with sentinel
+    if (isNumberElement(node)) {
+      const style = getStyle(node);
+      if (typeof style.rawContent === 'string') {
+        const sentinel = `\0RAW${sentinels.size}\0`;
+        sentinels.set(sentinel, style.rawContent);
+        return sentinel;
+      }
+    }
+    return toValue(node);
+  };
+  return convert(element);
+};
+
+/**
+ * @public
+ */
+const serializer = (element, replacer, space, options) => {
+  if (options?.preserveStyle) {
+    const style = getStyle(element);
+    const indent = typeof space === 'number' ? space : typeof style.indent === 'number' ? style.indent : 0;
+    const sentinels = new Map();
+    const pojo = toPojo(element, sentinels);
+    let serialized = JSON.stringify(pojo, null, indent);
+
+    // replace quoted sentinels with raw number representations
+    for (const [sentinel, raw] of sentinels) {
+      serialized = serialized.replace(JSON.stringify(sentinel), raw);
+    }
+    return serialized;
+  }
+  return JSON.stringify(toValue(element), replacer, space);
+};
+export default serializer;

package/src/transformers/serializers/json.ts

@@ -0,0 +1,107 @@
+import {
+  Element,
+  isElement,
+  isObjectElement,
+  isArrayElement,
+  isRefElement,
+  isLinkElement,
+  isStringElement,
+  isNumberElement,
+} from '@speclynx/apidom-datamodel';
+
+import toValue from './value.ts';
+
+interface JSONElementStyle {
+  indent?: number;
+  rawContent?: string;
+}
+
+const getStyle = (element: Element): JSONElementStyle => {
+  return (element.style?.json ?? {}) as JSONElementStyle;
+};
+
+/**
+ * @public
+ */
+export interface JSONSerializerOptions {
+  /** Preserve original formatting styles from `element.style.json` */
+  preserveStyle?: boolean;
+}
+
+/**
+ * Builds a POJO from an ApiDOM element tree. Numbers with rawContent
+ * are replaced with sentinel strings; all other values go through toValue().
+ */
+const toPojo = (element: Element, sentinels: Map<string, string>): unknown => {
+  const visited = new WeakSet<object>();
+
+  const convert = (node: unknown): unknown => {
+    if (!isElement(node)) return node;
+
+    if (visited.has(node as object)) return null;
+    visited.add(node as object);
+
+    if (isObjectElement(node)) {
+      const obj: Record<string, unknown> = {};
+      node.forEach((value, key) => {
+        const k = isElement(key) ? toValue(key) : key;
+        if (typeof k === 'string') obj[k] = convert(value);
+      });
+      return obj;
+    }
+
+    if (isArrayElement(node)) {
+      const arr: unknown[] = [];
+      node.forEach((item) => arr.push(convert(item)));
+      return arr;
+    }
+
+    if (isRefElement(node)) return String(toValue(node));
+    if (isLinkElement(node)) return isStringElement(node.href) ? toValue(node.href) : '';
+
+    // number with rawContent — substitute with sentinel
+    if (isNumberElement(node)) {
+      const style = getStyle(node);
+      if (typeof style.rawContent === 'string') {
+        const sentinel = `\0RAW${sentinels.size}\0`;
+        sentinels.set(sentinel, style.rawContent);
+        return sentinel;
+      }
+    }
+
+    return toValue(node);
+  };
+
+  return convert(element);
+};
+
+/**
+ * @public
+ */
+const serializer = (
+  element: Element,
+  replacer?: (this: unknown, key: string, value: unknown) => unknown,
+  space?: string | number,
+  options?: JSONSerializerOptions,
+): string => {
+  if (options?.preserveStyle) {
+    const style = getStyle(element);
+    const indent =
+      typeof space === 'number' ? space : typeof style.indent === 'number' ? style.indent : 0;
+
+    const sentinels = new Map<string, string>();
+    const pojo = toPojo(element, sentinels);
+    let serialized = JSON.stringify(pojo, null, indent);
+
+    // replace quoted sentinels with raw number representations
+    for (const [sentinel, raw] of sentinels) {
+      serialized = serialized.replace(JSON.stringify(sentinel), raw);
+    }
+
+    return serialized;
+  }
+
+  return JSON.stringify(toValue(element), replacer, space);
+};
+
+export default serializer;

package/src/transformers/serializers/value.cjs

@@ -0,0 +1,50 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+/**
+ * Transforms the ApiDOM into JavaScript POJO.
+ * This POJO would be the result of interpreting the ApiDOM
+ * into JavaScript structure.
+ * @public
+ */
+const serializer = element => {
+  if (!(0, _apidomDatamodel.isElement)(element)) return element;
+
+  // Shortcut optimization for primitive element types
+  if ((0, _apidomDatamodel.isStringElement)(element) || (0, _apidomDatamodel.isNumberElement)(element) || (0, _apidomDatamodel.isBooleanElement)(element) || (0, _apidomDatamodel.isNullElement)(element)) {
+    return element.toValue();
+  }
+
+  // WeakMap for cycle handling - stores references to already-visited elements
+  const references = new WeakMap();
+  const serialize = node => {
+    if (!(0, _apidomDatamodel.isElement)(node)) return node;
+    if ((0, _apidomDatamodel.isObjectElement)(node)) {
+      if (references.has(node)) return references.get(node);
+      const obj = {};
+      references.set(node, obj);
+      node.forEach((value, key) => {
+        const k = serialize(key);
+        const v = serialize(value);
+        if (typeof k === 'string') obj[k] = v;
+      });
+      return obj;
+    }
+    if ((0, _apidomDatamodel.isArrayElement)(node)) {
+      if (references.has(node)) return references.get(node);
+      const arr = [];
+      references.set(node, arr);
+      node.forEach(item => arr.push(serialize(item)));
+      return arr;
+    }
+    if ((0, _apidomDatamodel.isRefElement)(node)) return String(node.toValue());
+    if ((0, _apidomDatamodel.isLinkElement)(node)) {
+      return (0, _apidomDatamodel.isStringElement)(node.href) ? node.href.toValue() : '';
+    }
+    return node.toValue();
+  };
+  return serialize(element);
+};
+var _default = exports.default = serializer;

package/src/transformers/serializers/value.mjs

@@ -0,0 +1,47 @@
+import { isElement, isObjectElement, isArrayElement, isRefElement, isLinkElement, isStringElement, isBooleanElement, isNumberElement, isNullElement } from '@speclynx/apidom-datamodel';
+
+/**
+ * Transforms the ApiDOM into JavaScript POJO.
+ * This POJO would be the result of interpreting the ApiDOM
+ * into JavaScript structure.
+ * @public
+ */
+const serializer = element => {
+  if (!isElement(element)) return element;
+
+  // Shortcut optimization for primitive element types
+  if (isStringElement(element) || isNumberElement(element) || isBooleanElement(element) || isNullElement(element)) {
+    return element.toValue();
+  }
+
+  // WeakMap for cycle handling - stores references to already-visited elements
+  const references = new WeakMap();
+  const serialize = node => {
+    if (!isElement(node)) return node;
+    if (isObjectElement(node)) {
+      if (references.has(node)) return references.get(node);
+      const obj = {};
+      references.set(node, obj);
+      node.forEach((value, key) => {
+        const k = serialize(key);
+        const v = serialize(value);
+        if (typeof k === 'string') obj[k] = v;
+      });
+      return obj;
+    }
+    if (isArrayElement(node)) {
+      if (references.has(node)) return references.get(node);
+      const arr = [];
+      references.set(node, arr);
+      node.forEach(item => arr.push(serialize(item)));
+      return arr;
+    }
+    if (isRefElement(node)) return String(node.toValue());
+    if (isLinkElement(node)) {
+      return isStringElement(node.href) ? node.href.toValue() : '';
+    }
+    return node.toValue();
+  };
+  return serialize(element);
+};
+export default serializer;

package/src/transformers/serializers/value.ts

@@ -0,0 +1,70 @@
+import {
+  Element,
+  isElement,
+  isObjectElement,
+  isArrayElement,
+  isRefElement,
+  isLinkElement,
+  isStringElement,
+  isBooleanElement,
+  isNumberElement,
+  isNullElement,
+} from '@speclynx/apidom-datamodel';
+
+/**
+ * Transforms the ApiDOM into JavaScript POJO.
+ * This POJO would be the result of interpreting the ApiDOM
+ * into JavaScript structure.
+ * @public
+ */
+const serializer = <T extends Element | unknown>(element: T): unknown => {
+  if (!isElement(element)) return element;
+
+  // Shortcut optimization for primitive element types
+  if (
+    isStringElement(element) ||
+    isNumberElement(element) ||
+    isBooleanElement(element) ||
+    isNullElement(element)
+  ) {
+    return element.toValue();
+  }
+
+  // WeakMap for cycle handling - stores references to already-visited elements
+  const references = new WeakMap<Element, object | unknown[]>();
+
+  const serialize = (node: unknown): unknown => {
+    if (!isElement(node)) return node;
+
+    if (isObjectElement(node)) {
+      if (references.has(node)) return references.get(node);
+      const obj: Record<string, unknown> = {};
+      references.set(node, obj);
+      node.forEach((value, key) => {
+        const k = serialize(key);
+        const v = serialize(value);
+        if (typeof k === 'string') obj[k] = v;
+      });
+      return obj;
+    }
+
+    if (isArrayElement(node)) {
+      if (references.has(node)) return references.get(node);
+      const arr: unknown[] = [];
+      references.set(node, arr);
+      node.forEach((item) => arr.push(serialize(item)));
+      return arr;
+    }
+
+    if (isRefElement(node)) return String(node.toValue());
+    if (isLinkElement(node)) {
+      return isStringElement(node.href) ? node.href.toValue() : '';
+    }
+
+    return node.toValue();
+  };
+
+  return serialize(element);
+};
+
+export default serializer;