feat(ns-asyncapi-2-0): introduce plugginable refracting

apidom/package.json

@@ -52,6 +52,7 @@
     "@commitlint/config-conventional": "=12.0.0",
     "@types/chai": "=4.2.12",
     "@types/mocha": "=7.0.2",
+    "@types/sinon": "=9.0.10",
     "@typescript-eslint/eslint-plugin": "=3.0.2",
     "@typescript-eslint/parser": "=3.0.2",
     "axios-mock-adapter": "=1.19.0",

apidom/packages/@types/minim.d.ts

@@ -10,7 +10,7 @@ declare module 'minim' {
   export function refract(value: any): Element;
 
   export class Element {
-    static refract(value: any, option?: Record<string, any>): Element;
+    static refract(value: any, options?: Record<string, any>): Element;
 
     public element: string;
 

apidom/packages/apidom-ns-asyncapi-2-0/src/index.ts

@@ -1,4 +1,4 @@
-export { default } from './namespace';
+import './refractor/registration';
 
 export {
   isRefElement,
@@ -13,6 +13,8 @@ export {
   isStringElement,
 } from 'apidom';
 
+export { default } from './namespace';
+
 export {
   isAsyncApi2_0Element,
   isAsyncApiVersionElement,

apidom/packages/apidom-ns-asyncapi-2-0/src/namespace.ts

@@ -19,131 +19,6 @@ import ServerElement from './elements/Server';
 import ServerBindingsElement from './elements/ServerBindings';
 import ServersElement from './elements/Servers';
 import ServerVariableElement from './elements/ServerVariable';
-import { createRefractor } from './refractor';
-
-// register refractors specific to element types
-AsyncApi2_0Element.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'AsyncApi',
-  '$visitor',
-]);
-AsyncApiVersionElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'AsyncApiVersion',
-  '$visitor',
-]);
-ChannelBindingsElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'ChannelBindings',
-  '$visitor',
-]);
-ChannelItemElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'ChannelItem',
-  '$visitor',
-]);
-ChannelsElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Channels',
-  '$visitor',
-]);
-ComponentsElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Components',
-  '$visitor',
-]);
-ContactElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Contact',
-  '$visitor',
-]);
-IdentifierElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Identifier',
-  '$visitor',
-]);
-InfoElement.refract = createRefractor(['visitors', 'document', 'objects', 'Info', '$visitor']);
-LicenseElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'License',
-  '$visitor',
-]);
-OperationElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Operation',
-  '$visitor',
-]);
-ParameterElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Parameter',
-  '$visitor',
-]);
-ParametersElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Parameters',
-  '$visitor',
-]);
-ReferenceElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Reference',
-  '$visitor',
-]);
-SchemaElement.refract = createRefractor(['visitors', 'document', 'objects', 'Schema', '$visitor']);
-SecurityRequirementElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'SecurityRequirement',
-  '$visitor',
-]);
-ServerElement.refract = createRefractor(['visitors', 'document', 'objects', 'Server', '$visitor']);
-ServerBindingsElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'ServerBindings',
-  '$visitor',
-]);
-ServersElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'Servers',
-  '$visitor',
-]);
-ServerVariableElement.refract = createRefractor([
-  'visitors',
-  'document',
-  'objects',
-  'ServerVariable',
-  '$visitor',
-]);
 
 const asyncApi2_0 = {
   namespace: (options: NamespacePluginOptions) => {

apidom/packages/apidom-ns-asyncapi-2-0/src/refractor/index.ts

@@ -1,25 +1,49 @@
 import { refract as baseRefract } from 'minim';
-import { Element, dereference } from 'apidom';
+import { Element, dereference, mergeAllVisitors, createNamespace } from 'apidom';
+import { propOr } from 'ramda';
 import { invokeArgs } from 'ramda-adjunct';
 
 import { visit } from '../traversal/visitor';
 import specification from './specification';
+import * as predicates from '../predicates';
+import asyncApi2_0Namespace from '../namespace';
 
 const refract = <T extends Element>(
   value: any,
-  { specPath = ['visitors', 'document', 'objects', 'AsyncApi', '$visitor'] } = {},
+  { specPath = ['visitors', 'document', 'objects', 'AsyncApi', '$visitor'], plugins = [] } = {},
 ): T => {
   const element = baseRefract(value);
   const resolvedSpec = dereference(specification);
-  const visitor = invokeArgs(specPath, [], resolvedSpec);
 
+  /**
+   * This is where generic ApiDOM becomes semantic (namespace applied).
+   * We don't allow consumers to hook into this translation.
+   * Though we allow consumers to define their onw plugins on already transformed ApiDOM.
+   */
+  const rootVisitor = invokeArgs(specPath, [], resolvedSpec);
   // @ts-ignore
-  visit(element, visitor, { state: { specObj: resolvedSpec } });
+  visit(element, rootVisitor, { state: { specObj: resolvedSpec } });
 
-  return visitor.element;
+  /**
+   * Run plugins only when necessary.
+   * Running plugins visitors means extra single traversal.
+   * This can be optimized in future for performance.
+   */
+  if (plugins.length > 0) {
+    const namespace = createNamespace(asyncApi2_0Namespace);
+    const toolbox = { predicates: { ...predicates }, namespace };
+    const pluginsSpecs = plugins.map((plugin: any) => plugin(toolbox));
+    const pluginsVisitor = mergeAllVisitors(pluginsSpecs.map(propOr({}, 'visitor')));
+    pluginsSpecs.forEach(invokeArgs(['pre'], []));
+    const newElement: any = visit(rootVisitor.element, pluginsVisitor);
+    pluginsSpecs.forEach(invokeArgs(['post'], []));
+    return newElement;
+  }
+
+  return rootVisitor.element;
 };
 
 export const createRefractor = (specPath: string[]) => (value: any, options = {}) =>
-  refract(value, { specPath, ...options });
+  refract(value, { ...options, specPath });
 
 export default refract;

apidom/packages/apidom-ns-asyncapi-2-0/src/refractor/registration.ts

@@ -0,0 +1,145 @@
+import AsyncApi2_0Element from '../elements/AsyncApi2-0';
+import AsyncApiVersionElement from '../elements/AsyncApiVersion';
+import ChannelBindingsElement from '../elements/ChannelBindings';
+import ChannelItemElement from '../elements/ChannelItem';
+import ChannelsElement from '../elements/Channels';
+import ComponentsElement from '../elements/Components';
+import ContactElement from '../elements/Contact';
+import IdentifierElement from '../elements/Identifier';
+import InfoElement from '../elements/Info';
+import LicenseElement from '../elements/License';
+import OperationElement from '../elements/Operation';
+import ParameterElement from '../elements/Parameter';
+import ParametersElement from '../elements/Parameters';
+import ReferenceElement from '../elements/Reference';
+import SchemaElement from '../elements/Schema';
+import SecurityRequirementElement from '../elements/SecurityRequirement';
+import ServerElement from '../elements/Server';
+import ServerBindingsElement from '../elements/ServerBindings';
+import ServersElement from '../elements/Servers';
+import ServerVariableElement from '../elements/ServerVariable';
+import { createRefractor } from './index';
+
+// register refractors specific to element types
+AsyncApi2_0Element.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'AsyncApi',
+  '$visitor',
+]);
+AsyncApiVersionElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'AsyncApiVersion',
+  '$visitor',
+]);
+ChannelBindingsElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'ChannelBindings',
+  '$visitor',
+]);
+ChannelItemElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'ChannelItem',
+  '$visitor',
+]);
+ChannelsElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Channels',
+  '$visitor',
+]);
+ComponentsElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Components',
+  '$visitor',
+]);
+ContactElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Contact',
+  '$visitor',
+]);
+IdentifierElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Identifier',
+  '$visitor',
+]);
+InfoElement.refract = createRefractor(['visitors', 'document', 'objects', 'Info', '$visitor']);
+LicenseElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'License',
+  '$visitor',
+]);
+OperationElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Operation',
+  '$visitor',
+]);
+ParameterElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Parameter',
+  '$visitor',
+]);
+ParametersElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Parameters',
+  '$visitor',
+]);
+ReferenceElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Reference',
+  '$visitor',
+]);
+SchemaElement.refract = createRefractor(['visitors', 'document', 'objects', 'Schema', '$visitor']);
+SecurityRequirementElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'SecurityRequirement',
+  '$visitor',
+]);
+ServerElement.refract = createRefractor(['visitors', 'document', 'objects', 'Server', '$visitor']);
+ServerBindingsElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'ServerBindings',
+  '$visitor',
+]);
+ServersElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'Servers',
+  '$visitor',
+]);
+ServerVariableElement.refract = createRefractor([
+  'visitors',
+  'document',
+  'objects',
+  'ServerVariable',
+  '$visitor',
+]);