fix(core): utilize proper YAML 1.2 serialization (#27)

Author: char0n

package-lock.json

@@ -46,7 +46,8 @@
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0",
     "short-unique-id": "^5.3.2",
-    "ts-mixer": "^6.0.4"
+    "ts-mixer": "^6.0.4",
+    "yaml": "^2.8.2"
   },
   "files": [
     "src/**/*.mjs",

packages/apidom-core/package.json

@@ -41,7 +41,10 @@ export { default as toJSON } from './transformers/serializers/json.ts';
 /**
  * Transforms the ApiDOM into YAML string.
  */
-export { default as toYAML } from './transformers/serializers/yaml-1-2.ts';
+export {
+  default as toYAML,
+  type YamlSerializerOptions,
+} from './transformers/serializers/yaml-1-2.ts';
 
 /**
  * Creates a refract representation of an Element.

packages/apidom-core/src/index.ts

@@ -1,104 +1,43 @@
-import { Element, ArrayElement, ObjectElement } from '@speclynx/apidom-datamodel';
-import { traverse, type Path } from '@speclynx/apidom-traverse';
+import {
+  Document,
+  stringify,
+  type CreateNodeOptions,
+  type DocumentOptions,
+  type SchemaOptions,
+  type ToStringOptions,
+} from 'yaml';
+import { Element } from '@speclynx/apidom-datamodel';
+
+import toValue from './value.ts';
 
-import serializeValue from './value.ts';
-
-interface YamlVisitorOptions {
-  readonly directive?: boolean;
-  readonly indent?: number;
-}
-
-class YamlVisitor {
-  protected static readonly indentChar = '  ';
-
-  public result: string;
-
-  protected readonly indent: number;
-
-  constructor({ directive = false, indent = 0 }: YamlVisitorOptions = {}) {
-    this.result = directive ? '%YAML 1.2\n---\n' : '';
-    this.indent = indent;
-  }
-
-  public NumberElement(path: Path<Element>): void {
-    this.result += serializeValue(path.node);
-  }
-
-  public BooleanElement(path: Path<Element>): void {
-    const value = serializeValue(path.node);
-    this.result += value ? 'true' : 'false';
-  }
-
-  public StringElement(path: Path<Element>): void {
-    // for simplicity and avoiding ambiguity we always wrap strings in quotes
-    this.result += JSON.stringify(serializeValue(path.node));
-  }
-
-  public NullElement(): void {
-    this.result += 'null';
-  }
-
-  public ArrayElement(path: Path<Element>): void {
-    const element = path.node as ArrayElement;
-
-    if (element.length === 0) {
-      this.result += '[]';
-      path.skip();
-      return;
-    }
-
-    element.forEach((item) => {
-      const visitor = new YamlVisitor({ indent: this.indent + 1 });
-      const indent = YamlVisitor.indentChar.repeat(this.indent);
-
-      traverse(item, visitor);
-
-      const { result } = visitor;
-
-      this.result += result.startsWith('\n') ? `\n${indent}-${result}` : `\n${indent}- ${result}`;
-    });
-
-    path.skip();
-  }
-
-  public ObjectElement(path: Path<Element>): void {
-    const element = path.node as ObjectElement;
-
-    if (element.length === 0) {
-      this.result += '{}';
-      path.skip();
-      return;
-    }
-
-    element.forEach((value, key) => {
-      const keyVisitor = new YamlVisitor({ indent: this.indent + 1 });
-      const valueVisitor = new YamlVisitor({ indent: this.indent + 1 });
-      const indent = YamlVisitor.indentChar.repeat(this.indent);
-
-      traverse(key, keyVisitor);
-      traverse(value, valueVisitor);
-
-      const { result: keyResult } = keyVisitor;
-      const { result: valueResult } = valueVisitor;
-
-      this.result += valueResult.startsWith('\n')
-        ? `\n${indent}${keyResult}:${valueResult}`
-        : `\n${indent}${keyResult}: ${valueResult}`;
-    });
-
-    path.skip();
-  }
+/**
+ * @public
+ */
+export interface YamlSerializerOptions
+  extends
+    DocumentOptions,
+    Pick<CreateNodeOptions, 'aliasDuplicateObjects'>,
+    Pick<SchemaOptions, 'sortMapEntries'>,
+    ToStringOptions {
+  /** Include %YAML directive and document marker */
+  directive?: boolean;
 }
 
 /**
  * @public
  */
-const serializer = (element: Element, { directive = false } = {}): string => {
-  const visitor = new YamlVisitor({ directive });
-
-  traverse(element, visitor);
-
-  return visitor.result;
+const serializer = (
+  element: Element,
+  { directive = false, aliasDuplicateObjects = false, ...options }: YamlSerializerOptions = {},
+): string => {
+  const allOptions = { aliasDuplicateObjects, ...options };
+
+  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;

packages/apidom-core/src/transformers/serializers/yaml-1-2.ts

@@ -1,4 +1,3 @@
-import dedent from 'dedent';
 import { assert } from 'chai';
 
 import { from } from '../../../src/index.ts';
@@ -10,44 +9,34 @@ describe('serializers', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from(true)!;
         const serialized = serialize(apidom);
-        const expected = dedent`
-          true
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, 'true\n');
       });
     });
 
     context('given NumberElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from(1)!;
         const serialized = serialize(apidom);
-        const expected = dedent`
-          1
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '1\n');
       });
     });
 
     context('given StringElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from('test')!;
         const serialized = serialize(apidom);
-        const expected = dedent`
-          "test"
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, 'test\n');
       });
 
       context('and is multiline', function () {
         specify('should serialize to YAML 1.2', function () {
           const apidom = from('test\n\ntest\n')!;
           const serialized = serialize(apidom);
-          const expected = String.raw`"test\n\ntest\n"`;
 
-          assert.strictEqual(serialized, expected);
+          assert.strictEqual(serialized, '|\ntest\n\ntest\n');
         });
       });
     });
@@ -56,137 +45,80 @@ describe('serializers', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from(null)!;
         const serialized = serialize(apidom);
-        const expected = dedent`
-          null
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, 'null\n');
       });
     });
 
     context('given empty ArrayElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from([])!;
         const serialized = serialize(apidom);
-        const expected = dedent`
-          []
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '[]\n');
       });
     });
 
     context('given simple ArrayElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from([1, true, 'test', null])!;
         const serialized = serialize(apidom, { directive: true });
-        const expected = dedent`
-          %YAML 1.2
-          ---
 
-          - 1
-          - true
-          - "test"
-          - null
-        `;
-
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '%YAML 1.2\n---\n- 1\n- true\n- test\n- null\n');
       });
     });
 
     context('given nested ArrayElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from([1, [true, 'test', null]])!;
         const serialized = serialize(apidom, { directive: true });
-        const expected = dedent`
-          %YAML 1.2
-          ---
-
-          - 1
-          -
-            - true
-            - "test"
-            - null
-        `;
-
-        assert.strictEqual(serialized, expected);
+
+        assert.strictEqual(serialized, '%YAML 1.2\n---\n- 1\n- - true\n  - test\n  - null\n');
       });
     });
 
     context('given ArrayElement in ObjectElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from({ a: [1] })!;
         const serialized = serialize(apidom, { directive: true });
-        const expected = dedent`
-          %YAML 1.2
-          ---
-
-          "a":
-            - 1
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '%YAML 1.2\n---\na:\n  - 1\n');
       });
     });
 
     context('given empty ObjectElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from({})!;
         const serialized = serialize(apidom);
-        const expected = dedent`
-          {}
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '{}\n');
       });
     });
 
     context('given simple ObjectElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from({ a: 1, b: true })!;
         const serialized = serialize(apidom, { directive: true });
-        const expected = dedent`
-          %YAML 1.2
-          ---
 
-          "a": 1
-          "b": true
-        `;
-
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '%YAML 1.2\n---\na: 1\nb: true\n');
       });
     });
 
     context('given nested ObjectElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from({ a: 1, b: { c: true } })!;
         const serialized = serialize(apidom, { directive: true });
-        const expected = dedent`
-          %YAML 1.2
-          ---
-
-          "a": 1
-          "b":
-            "c": true
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '%YAML 1.2\n---\na: 1\nb:\n  c: true\n');
       });
     });
 
     context('given ObjectElement in ArrayElement', function () {
       specify('should serialize to YAML 1.2', function () {
         const apidom = from([{ a: true }])!;
         const serialized = serialize(apidom, { directive: true });
-        const expected = dedent`
-          %YAML 1.2
-          ---
-
-          -
-            "a": true
-        `;
 
-        assert.strictEqual(serialized, expected);
+        assert.strictEqual(serialized, '%YAML 1.2\n---\n- a: true\n');
       });
     });
   });