feat(reference): reimplement architecture 2.0 for OpenAPI 3.0.x dereferencing

packages/apidom-reference/src/dereference/index.ts

@@ -79,7 +79,12 @@ const dereference = async (
     parseResult = await parse(uri, options);
   }
 
-  const mergedOptions = mergeOptions(options, { resolve: { baseURI: sanitizedURI } });
+  const mergedOptions = mergeOptions(options, {
+    resolve: { baseURI: sanitizedURI },
+    dereference: {
+      immutable: refSet !== null, // if refSet was node provided, then we can work in mutable mode
+    },
+  });
 
   return dereferenceApiDOM(parseResult, mergedOptions);
 };

packages/apidom-reference/src/dereference/strategies/openapi-3-0/index.ts

@@ -1,6 +1,5 @@
 import stampit from 'stampit';
-import { defaultTo, propEq } from 'ramda';
-import { createNamespace, visit, Element } from '@swagger-api/apidom-core';
+import { Element, createNamespace, visit, cloneDeep } from '@swagger-api/apidom-core';
 import openApi3_0Namespace, {
   getNodeType,
   isOpenApi3_0Element,
@@ -41,15 +40,40 @@ const OpenApi3_0DereferenceStrategy: stampit.Stamp<IDereferenceStrategy> = stamp
 
       async dereference(file: IFile, options: IReferenceOptions): Promise<Element> {
         const namespace = createNamespace(openApi3_0Namespace);
-        const refSet = defaultTo(ReferenceSet(), options.dereference.refSet);
+        const refSet = options.dereference.refSet ?? ReferenceSet();
         let reference;
 
         if (!refSet.has(file.uri)) {
           reference = Reference({ uri: file.uri, value: file.parseResult });
           refSet.add(reference);
         } else {
           // pre-computed refSet was provided as configuration option
-          reference = refSet.find(propEq(file.uri, 'uri'));
+          reference = refSet.find((ref) => ref.uri === file.uri);
+        }
+
+        /**
+         * Clone refSet due the dereferencing process being mutable.
+         * We don't want to mutate the original refSet and the references.
+         */
+        if (options.dereference.immutable) {
+          const immutableRefs = refSet.refs.map((ref) =>
+            Reference({
+              ...ref,
+              uri: `immutable://${ref.uri}`,
+            }),
+          );
+          const mutableRefs = refSet.refs.map((ref) =>
+            Reference({
+              ...ref,
+              value: cloneDeep(ref.value),
+            }),
+          );
+
+          refSet.clean();
+          mutableRefs.forEach((ref) => refSet.add(ref));
+          immutableRefs.forEach((ref) => refSet.add(ref));
+
+          reference = refSet.find((ref) => ref.uri === file.uri);
         }
 
         const visitor = OpenApi3_0DereferenceVisitor({ reference, namespace, options });
@@ -59,13 +83,30 @@ const OpenApi3_0DereferenceStrategy: stampit.Stamp<IDereferenceStrategy> = stamp
         });
 
         /**
-         * Release all memory if this refSet was not provided as an configuration option.
+         * Release all memory if this refSet was not provided as a configuration option.
          * If provided as configuration option, then provider is responsible for cleanup.
          */
         if (options.dereference.refSet === null) {
           refSet.clean();
         }
 
+        /**
+         * If immutable option is set, then we need to remove mutable refs from the refSet.
+         */
+        if (options.dereference.immutable) {
+          const immutableRefs = refSet.refs
+            .filter((ref) => ref.uri.startsWith('immutable://'))
+            .map((ref) =>
+              Reference({
+                ...ref,
+                uri: ref.uri.replace(/^immutable:\/\//, ''),
+              }),
+            );
+
+          refSet.clean();
+          immutableRefs.forEach((ref) => refSet.add(ref));
+        }
+
         return dereferencedElement;
       },
     },