@speclynx/apidom-core 4.0.1 → 4.0.3

package/src/transformers/serializers/yaml-1-2.cjs

@@ -0,0 +1,142 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _yaml = require("yaml");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _value = _interopRequireDefault(require("./value.cjs"));
+const getStyle = element => {
+  return element.style?.yaml ?? {};
+};
+
+// map our scalarStyle strings to YAML library Scalar.Type constants
+const scalarStyleMap = {
+  Plain: _yaml.Scalar.PLAIN,
+  SingleQuoted: _yaml.Scalar.QUOTE_SINGLE,
+  DoubleQuoted: _yaml.Scalar.QUOTE_DOUBLE,
+  Literal: _yaml.Scalar.BLOCK_LITERAL,
+  Folded: _yaml.Scalar.BLOCK_FOLDED
+};
+
+// the YAML library prefixes comments with '#' only (no space), so we add ' ' to get '# comment'
+const applyComments = (node, style) => {
+  if (style.comment) node.comment = ` ${style.comment}`;
+  if (style.commentBefore) node.commentBefore = ` ${style.commentBefore}`;
+};
+
+/**
+ * @public
+ */
+
+/**
+ * Converts an ApiDOM element tree to YAML library AST nodes,
+ * preserving style information from `element.style.yaml`.
+ */
+const toYAMLNode = (element, visited) => {
+  if (!(0, _apidomDatamodel.isElement)(element)) return element;
+
+  // cycle detection
+  if (visited.has(element)) return undefined;
+  visited.add(element);
+  const style = getStyle(element);
+  if ((0, _apidomDatamodel.isObjectElement)(element)) {
+    const map = new _yaml.YAMLMap();
+    map.flow = style.styleGroup === 'Flow';
+    applyComments(map, style);
+    element.forEach((value, key, member) => {
+      const memberStyle = (0, _apidomDatamodel.isMemberElement)(member) ? getStyle(member) : {};
+      const keyNode = toYAMLNode(key, visited);
+      const valueNode = toYAMLNode(value, visited);
+      const pair = new _yaml.Pair(keyNode, valueNode);
+      if (memberStyle.commentBefore && (0, _yaml.isNode)(keyNode)) {
+        keyNode.commentBefore = ` ${memberStyle.commentBefore}`;
+      }
+      if (memberStyle.comment && (0, _yaml.isNode)(valueNode)) {
+        valueNode.comment = ` ${memberStyle.comment}`;
+      }
+      map.items.push(pair);
+    });
+    return map;
+  }
+  if ((0, _apidomDatamodel.isArrayElement)(element)) {
+    const seq = new _yaml.YAMLSeq();
+    seq.flow = style.styleGroup === 'Flow';
+    applyComments(seq, style);
+    element.forEach(item => {
+      seq.items.push(toYAMLNode(item, visited));
+    });
+    return seq;
+  }
+  if ((0, _apidomDatamodel.isRefElement)(element)) {
+    return new _yaml.Scalar(String((0, _value.default)(element)));
+  }
+  if ((0, _apidomDatamodel.isLinkElement)(element)) {
+    return new _yaml.Scalar((0, _apidomDatamodel.isStringElement)(element.href) ? (0, _value.default)(element.href) : '');
+  }
+
+  // scalar element (string, number, boolean, null)
+  const scalarType = style.scalarStyle ? scalarStyleMap[style.scalarStyle] : undefined;
+  const scalar = new _yaml.Scalar((0, _value.default)(element));
+  if (scalarType) {
+    scalar.type = scalarType;
+  }
+
+  // use rawContent to infer YAML library format hints for plain scalars that resolved to numbers;
+  // only applies to Plain style — quoted scalars are always strings in YAML.
+  // note: the YAML library may normalize the representation (e.g. 1.0e10 -> 1e+10, 0x1A -> 0x1a)
+  // while preserving the format category (exponential, hex, octal, fractional digits)
+  if (style.rawContent && style.scalarStyle === 'Plain' && typeof scalar.value === 'number') {
+    if (/[eE]/.test(style.rawContent)) {
+      scalar.format = 'EXP';
+    } else if (/^0x/i.test(style.rawContent)) {
+      scalar.format = 'HEX';
+    } else if (/^0o/i.test(style.rawContent)) {
+      scalar.format = 'OCT';
+    }
+    const dotMatch = style.rawContent.match(/\.(\d+)/);
+    if (dotMatch) {
+      scalar.minFractionDigits = dotMatch[1].length;
+    }
+  }
+  applyComments(scalar, style);
+  return scalar;
+};
+
+/**
+ * @public
+ */
+const serializer = (element, {
+  directive = false,
+  preserveStyle = false,
+  aliasDuplicateObjects = false,
+  ...options
+} = {}) => {
+  const allOptions = {
+    aliasDuplicateObjects,
+    ...options
+  };
+  if (preserveStyle) {
+    const style = getStyle(element);
+    if (options.indent === undefined && typeof style.indent === 'number') {
+      allOptions.indent = style.indent;
+    }
+    if (typeof style.flowCollectionPadding === 'boolean') {
+      allOptions.flowCollectionPadding = style.flowCollectionPadding;
+    }
+    const rootNode = toYAMLNode(element, new WeakSet());
+    const doc = new _yaml.Document(undefined, allOptions);
+    doc.contents = rootNode;
+    if (directive) {
+      doc.directives.yaml.explicit = true;
+    }
+    return doc.toString(allOptions);
+  }
+  if (directive) {
+    const doc = new _yaml.Document((0, _value.default)(element), allOptions);
+    doc.directives.yaml.explicit = true;
+    return doc.toString(allOptions);
+  }
+  return (0, _yaml.stringify)((0, _value.default)(element), allOptions);
+};
+var _default = exports.default = serializer;

package/src/transformers/serializers/yaml-1-2.mjs

@@ -0,0 +1,137 @@
+import { Document, stringify, isNode, Scalar, YAMLMap, YAMLSeq, Pair } from 'yaml';
+import { isElement, isObjectElement, isArrayElement, isRefElement, isLinkElement, isStringElement, isMemberElement } from '@speclynx/apidom-datamodel';
+import toValue from "./value.mjs";
+const getStyle = element => {
+  return element.style?.yaml ?? {};
+};
+
+// map our scalarStyle strings to YAML library Scalar.Type constants
+const scalarStyleMap = {
+  Plain: Scalar.PLAIN,
+  SingleQuoted: Scalar.QUOTE_SINGLE,
+  DoubleQuoted: Scalar.QUOTE_DOUBLE,
+  Literal: Scalar.BLOCK_LITERAL,
+  Folded: Scalar.BLOCK_FOLDED
+};
+
+// the YAML library prefixes comments with '#' only (no space), so we add ' ' to get '# comment'
+const applyComments = (node, style) => {
+  if (style.comment) node.comment = ` ${style.comment}`;
+  if (style.commentBefore) node.commentBefore = ` ${style.commentBefore}`;
+};
+
+/**
+ * @public
+ */
+
+/**
+ * Converts an ApiDOM element tree to YAML library AST nodes,
+ * preserving style information from `element.style.yaml`.
+ */
+const toYAMLNode = (element, visited) => {
+  if (!isElement(element)) return element;
+
+  // cycle detection
+  if (visited.has(element)) return undefined;
+  visited.add(element);
+  const style = getStyle(element);
+  if (isObjectElement(element)) {
+    const map = new YAMLMap();
+    map.flow = style.styleGroup === 'Flow';
+    applyComments(map, style);
+    element.forEach((value, key, member) => {
+      const memberStyle = isMemberElement(member) ? getStyle(member) : {};
+      const keyNode = toYAMLNode(key, visited);
+      const valueNode = toYAMLNode(value, visited);
+      const pair = new Pair(keyNode, valueNode);
+      if (memberStyle.commentBefore && isNode(keyNode)) {
+        keyNode.commentBefore = ` ${memberStyle.commentBefore}`;
+      }
+      if (memberStyle.comment && isNode(valueNode)) {
+        valueNode.comment = ` ${memberStyle.comment}`;
+      }
+      map.items.push(pair);
+    });
+    return map;
+  }
+  if (isArrayElement(element)) {
+    const seq = new YAMLSeq();
+    seq.flow = style.styleGroup === 'Flow';
+    applyComments(seq, style);
+    element.forEach(item => {
+      seq.items.push(toYAMLNode(item, visited));
+    });
+    return seq;
+  }
+  if (isRefElement(element)) {
+    return new Scalar(String(toValue(element)));
+  }
+  if (isLinkElement(element)) {
+    return new Scalar(isStringElement(element.href) ? toValue(element.href) : '');
+  }
+
+  // scalar element (string, number, boolean, null)
+  const scalarType = style.scalarStyle ? scalarStyleMap[style.scalarStyle] : undefined;
+  const scalar = new Scalar(toValue(element));
+  if (scalarType) {
+    scalar.type = scalarType;
+  }
+
+  // use rawContent to infer YAML library format hints for plain scalars that resolved to numbers;
+  // only applies to Plain style — quoted scalars are always strings in YAML.
+  // note: the YAML library may normalize the representation (e.g. 1.0e10 -> 1e+10, 0x1A -> 0x1a)
+  // while preserving the format category (exponential, hex, octal, fractional digits)
+  if (style.rawContent && style.scalarStyle === 'Plain' && typeof scalar.value === 'number') {
+    if (/[eE]/.test(style.rawContent)) {
+      scalar.format = 'EXP';
+    } else if (/^0x/i.test(style.rawContent)) {
+      scalar.format = 'HEX';
+    } else if (/^0o/i.test(style.rawContent)) {
+      scalar.format = 'OCT';
+    }
+    const dotMatch = style.rawContent.match(/\.(\d+)/);
+    if (dotMatch) {
+      scalar.minFractionDigits = dotMatch[1].length;
+    }
+  }
+  applyComments(scalar, style);
+  return scalar;
+};
+
+/**
+ * @public
+ */
+const serializer = (element, {
+  directive = false,
+  preserveStyle = false,
+  aliasDuplicateObjects = false,
+  ...options
+} = {}) => {
+  const allOptions = {
+    aliasDuplicateObjects,
+    ...options
+  };
+  if (preserveStyle) {
+    const style = getStyle(element);
+    if (options.indent === undefined && typeof style.indent === 'number') {
+      allOptions.indent = style.indent;
+    }
+    if (typeof style.flowCollectionPadding === 'boolean') {
+      allOptions.flowCollectionPadding = style.flowCollectionPadding;
+    }
+    const rootNode = toYAMLNode(element, new WeakSet());
+    const doc = new Document(undefined, allOptions);
+    doc.contents = rootNode;
+    if (directive) {
+      doc.directives.yaml.explicit = true;
+    }
+    return doc.toString(allOptions);
+  }
+  if (directive) {
+    const doc = new Document(toValue(element), allOptions);
+    doc.directives.yaml.explicit = true;
+    return doc.toString(allOptions);
+  }
+  return stringify(toValue(element), allOptions);
+};
+export default serializer;

package/src/transformers/serializers/yaml-1-2.ts

@@ -0,0 +1,205 @@
+import {
+  Document,
+  stringify,
+  isNode,
+  Scalar,
+  YAMLMap,
+  YAMLSeq,
+  Pair,
+  type Node as YAMLNode,
+  type CreateNodeOptions,
+  type DocumentOptions,
+  type SchemaOptions,
+  type ToStringOptions,
+} from 'yaml';
+import {
+  Element,
+  isElement,
+  isObjectElement,
+  isArrayElement,
+  isRefElement,
+  isLinkElement,
+  isStringElement,
+  isMemberElement,
+} from '@speclynx/apidom-datamodel';
+
+import toValue from './value.ts';
+
+interface YAMLElementStyle {
+  scalarStyle?: string;
+  styleGroup?: string;
+  rawContent?: string;
+  indent?: number;
+  flowCollectionPadding?: boolean;
+  comment?: string;
+  commentBefore?: string;
+}
+
+const getStyle = (element: Element): YAMLElementStyle => {
+  return (element.style?.yaml ?? {}) as YAMLElementStyle;
+};
+
+// map our scalarStyle strings to YAML library Scalar.Type constants
+const scalarStyleMap: Record<string, Scalar.Type> = {
+  Plain: Scalar.PLAIN,
+  SingleQuoted: Scalar.QUOTE_SINGLE,
+  DoubleQuoted: Scalar.QUOTE_DOUBLE,
+  Literal: Scalar.BLOCK_LITERAL,
+  Folded: Scalar.BLOCK_FOLDED,
+};
+
+// the YAML library prefixes comments with '#' only (no space), so we add ' ' to get '# comment'
+const applyComments = (node: YAMLNode, style: YAMLElementStyle): void => {
+  if (style.comment) node.comment = ` ${style.comment}`;
+  if (style.commentBefore) node.commentBefore = ` ${style.commentBefore}`;
+};
+
+/**
+ * @public
+ */
+export interface YAMLSerializerOptions
+  extends
+    DocumentOptions,
+    Pick<CreateNodeOptions, 'aliasDuplicateObjects'>,
+    Pick<SchemaOptions, 'sortMapEntries'>,
+    ToStringOptions {
+  /** Include %YAML directive and document marker */
+  directive?: boolean;
+  /** Preserve original formatting styles from `element.style.yaml` */
+  preserveStyle?: boolean;
+  /** Padding inside flow collections (e.g. `{ a: 1 }` vs `{a: 1}`) */
+  flowCollectionPadding?: boolean;
+}
+
+/**
+ * Converts an ApiDOM element tree to YAML library AST nodes,
+ * preserving style information from `element.style.yaml`.
+ */
+const toYAMLNode = (element: unknown, visited: WeakSet<object>): unknown => {
+  if (!isElement(element)) return element;
+
+  // cycle detection
+  if (visited.has(element as object)) return undefined;
+  visited.add(element as object);
+
+  const style = getStyle(element);
+
+  if (isObjectElement(element)) {
+    const map = new YAMLMap();
+    map.flow = style.styleGroup === 'Flow';
+    applyComments(map, style);
+
+    element.forEach((value, key, member) => {
+      const memberStyle = isMemberElement(member) ? getStyle(member) : {};
+      const keyNode = toYAMLNode(key, visited);
+      const valueNode = toYAMLNode(value, visited);
+      const pair = new Pair(keyNode, valueNode);
+
+      if (memberStyle.commentBefore && isNode(keyNode)) {
+        keyNode.commentBefore = ` ${memberStyle.commentBefore}`;
+      }
+      if (memberStyle.comment && isNode(valueNode)) {
+        valueNode.comment = ` ${memberStyle.comment}`;
+      }
+
+      map.items.push(pair);
+    });
+
+    return map;
+  }
+
+  if (isArrayElement(element)) {
+    const seq = new YAMLSeq();
+    seq.flow = style.styleGroup === 'Flow';
+    applyComments(seq, style);
+
+    element.forEach((item) => {
+      seq.items.push(toYAMLNode(item, visited));
+    });
+
+    return seq;
+  }
+
+  if (isRefElement(element)) {
+    return new Scalar(String(toValue(element)));
+  }
+
+  if (isLinkElement(element)) {
+    return new Scalar(isStringElement(element.href) ? toValue(element.href) : '');
+  }
+
+  // scalar element (string, number, boolean, null)
+  const scalarType = style.scalarStyle ? scalarStyleMap[style.scalarStyle] : undefined;
+
+  const scalar = new Scalar(toValue(element));
+  if (scalarType) {
+    scalar.type = scalarType;
+  }
+
+  // use rawContent to infer YAML library format hints for plain scalars that resolved to numbers;
+  // only applies to Plain style — quoted scalars are always strings in YAML.
+  // note: the YAML library may normalize the representation (e.g. 1.0e10 -> 1e+10, 0x1A -> 0x1a)
+  // while preserving the format category (exponential, hex, octal, fractional digits)
+  if (style.rawContent && style.scalarStyle === 'Plain' && typeof scalar.value === 'number') {
+    if (/[eE]/.test(style.rawContent)) {
+      scalar.format = 'EXP';
+    } else if (/^0x/i.test(style.rawContent)) {
+      scalar.format = 'HEX';
+    } else if (/^0o/i.test(style.rawContent)) {
+      scalar.format = 'OCT';
+    }
+    const dotMatch = style.rawContent.match(/\.(\d+)/);
+    if (dotMatch) {
+      scalar.minFractionDigits = dotMatch[1].length;
+    }
+  }
+
+  applyComments(scalar, style);
+
+  return scalar;
+};
+
+/**
+ * @public
+ */
+const serializer = (
+  element: Element,
+  {
+    directive = false,
+    preserveStyle = false,
+    aliasDuplicateObjects = false,
+    ...options
+  }: YAMLSerializerOptions = {},
+): string => {
+  const allOptions: YAMLSerializerOptions = { aliasDuplicateObjects, ...options };
+
+  if (preserveStyle) {
+    const style = getStyle(element);
+    if (options.indent === undefined && typeof style.indent === 'number') {
+      allOptions.indent = style.indent;
+    }
+    if (typeof style.flowCollectionPadding === 'boolean') {
+      allOptions.flowCollectionPadding = style.flowCollectionPadding;
+    }
+
+    const rootNode = toYAMLNode(element, new WeakSet());
+    const doc = new Document(undefined, allOptions);
+    doc.contents = rootNode as YAMLNode;
+
+    if (directive) {
+      doc.directives!.yaml.explicit = true;
+    }
+
+    return doc.toString(allOptions);
+  }
+
+  if (directive) {
+    const doc = new Document(toValue(element), allOptions);
+    doc.directives!.yaml.explicit = true;
+    return doc.toString(allOptions);
+  }
+
+  return stringify(toValue(element), allOptions);
+};
+
+export default serializer;

package/src/transformers/sexprs.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+/**
+ * Transforms ApiDOM into S-expressions (Symbolic Expressions).
+ * @public
+ */
+const sexprs = element => {
+  let result = '';
+  let nestingLevel = 0;
+  (0, _apidomTraverse.traverse)(element, {
+    enter(path) {
+      const {
+        element: elementName
+      } = path.node;
+      const capitalizedElementName = elementName.charAt(0).toUpperCase() + elementName.slice(1);
+      const indent = '  '.repeat(nestingLevel);
+      result += nestingLevel > 0 ? '\n' : '';
+      result += `${indent}(${capitalizedElementName}Element`;
+      nestingLevel += 1;
+    },
+    leave() {
+      nestingLevel -= 1;
+      result += ')';
+    }
+  });
+  return result;
+};
+var _default = exports.default = sexprs;

package/src/transformers/sexprs.mjs

@@ -0,0 +1,28 @@
+import { traverse } from '@speclynx/apidom-traverse';
+
+/**
+ * Transforms ApiDOM into S-expressions (Symbolic Expressions).
+ * @public
+ */
+const sexprs = element => {
+  let result = '';
+  let nestingLevel = 0;
+  traverse(element, {
+    enter(path) {
+      const {
+        element: elementName
+      } = path.node;
+      const capitalizedElementName = elementName.charAt(0).toUpperCase() + elementName.slice(1);
+      const indent = '  '.repeat(nestingLevel);
+      result += nestingLevel > 0 ? '\n' : '';
+      result += `${indent}(${capitalizedElementName}Element`;
+      nestingLevel += 1;
+    },
+    leave() {
+      nestingLevel -= 1;
+      result += ')';
+    }
+  });
+  return result;
+};
+export default sexprs;

package/src/transformers/sexprs.ts

@@ -0,0 +1,30 @@
+import { Element } from '@speclynx/apidom-datamodel';
+import { traverse, type Path } from '@speclynx/apidom-traverse';
+
+/**
+ * Transforms ApiDOM into S-expressions (Symbolic Expressions).
+ * @public
+ */
+const sexprs = (element: Element): string => {
+  let result = '';
+  let nestingLevel = 0;
+
+  traverse(element, {
+    enter(path: Path<Element>) {
+      const { element: elementName } = path.node;
+      const capitalizedElementName = elementName.charAt(0).toUpperCase() + elementName.slice(1);
+      const indent = '  '.repeat(nestingLevel);
+      result += nestingLevel > 0 ? '\n' : '';
+      result += `${indent}(${capitalizedElementName}Element`;
+      nestingLevel += 1;
+    },
+    leave() {
+      nestingLevel -= 1;
+      result += ')';
+    },
+  });
+
+  return result;
+};
+
+export default sexprs;

package/src/transformers/to-string.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _namespace = _interopRequireDefault(require("../namespace.cjs"));
+var _dehydrate = _interopRequireDefault(require("./dehydrate.cjs"));
+/**
+ * Create a refracted string representation of an Element.
+ * @public
+ */
+const toString = (element, namespace = _namespace.default) => {
+  const refractStructure = (0, _dehydrate.default)(element, namespace);
+  return JSON.stringify(refractStructure);
+};
+var _default = exports.default = toString;

package/src/transformers/to-string.mjs

@@ -0,0 +1,11 @@
+import defaultNamespace from "../namespace.mjs";
+import dehydrate from "./dehydrate.mjs";
+/**
+ * Create a refracted string representation of an Element.
+ * @public
+ */
+const toString = (element, namespace = defaultNamespace) => {
+  const refractStructure = dehydrate(element, namespace);
+  return JSON.stringify(refractStructure);
+};
+export default toString;

package/src/transformers/to-string.ts

@@ -0,0 +1,15 @@
+import { Element, Namespace } from '@speclynx/apidom-datamodel';
+
+import defaultNamespace from '../namespace.ts';
+import dehydrate from './dehydrate.ts';
+
+/**
+ * Create a refracted string representation of an Element.
+ * @public
+ */
+const toString = (element: Element, namespace: Namespace = defaultNamespace): string => {
+  const refractStructure = dehydrate(element, namespace);
+  return JSON.stringify(refractStructure);
+};
+
+export default toString;