refactor(ns-ads): enhance usage of TypeScript (#3727)

Refs #3481

babel.config.cjs

@@ -21,7 +21,12 @@ module.exports = {
             exclude: ['transform-function-name'],
           },
         ],
-        '@babel/preset-typescript',
+        [
+          '@babel/preset-typescript',
+          {
+            allowDeclareFields: true,
+          }
+        ],
       ],
       plugins: [
         [
@@ -53,7 +58,12 @@ module.exports = {
             exclude: ['transform-function-name'], // this is here because of https://github.com/babel/babel/discussions/12874
           },
         ],
-        '@babel/preset-typescript',
+        [
+          '@babel/preset-typescript',
+          {
+            allowDeclareFields: true,
+          }
+        ],
       ],
       plugins: [
         [
@@ -84,7 +94,12 @@ module.exports = {
             exclude: ['transform-function-name'], // this is here because of https://github.com/babel/babel/discussions/12874
           },
         ],
-        '@babel/preset-typescript',
+        [
+          '@babel/preset-typescript',
+          {
+            allowDeclareFields: true,
+          }
+        ],
       ],
       plugins: [
         [

packages/apidom-ns-api-design-systems/src/refractor/index.ts

@@ -13,7 +13,7 @@ import { keyMap, getNodeType } from '../traversal/visitor';
 import createToolbox from './toolbox';
 
 const refract = <T extends Element>(
-  value: any,
+  value: unknown,
   { specPath = ['visitors', 'document', 'objects', 'Main', '$visitor'], plugins = [] } = {},
 ): T => {
   const element = baseRefract(value);
@@ -25,10 +25,9 @@ const refract = <T extends Element>(
    * Though we allow consumers to define their onw plugins on already transformed ApiDOM.
    */
   const RootVisitorClass = path(specPath, resolvedSpec) as typeof VisitorClass;
-  const rootVisitor = new RootVisitorClass();
+  const rootVisitor = new RootVisitorClass({ specObj: resolvedSpec });
 
-  // @ts-ignore
-  visit(element, rootVisitor, { state: { specObj: resolvedSpec } });
+  visit(element, rootVisitor);
 
   /**
    * Running plugins visitors means extra single traversal === performance hit.
@@ -41,7 +40,7 @@ const refract = <T extends Element>(
 
 export const createRefractor =
   (specPath: string[]) =>
-  (value: any, options = {}) =>
+  (value: unknown, options = {}) =>
     refract(value, { ...options, specPath });
 
 export default refract;

packages/apidom-ns-api-design-systems/src/refractor/visitors/SpecificationVisitor.ts

@@ -3,22 +3,26 @@ import { isFunction } from 'ramda-adjunct';
 import { visit, cloneDeep } from '@swagger-api/apidom-core';
 
 import { keyMap, getNodeType } from '../../traversal/visitor';
-import Visitor from './Visitor';
+import Visitor, { VisitorOptions } from './Visitor';
 import FallbackVisitor from './FallbackVisitor';
 import type specification from '../specification';
 
 /**
  * This is a base class for every visitor that does
  * internal look-ups to retrieve other child visitors.
  */
+export interface SpecificationVisitorOptions extends VisitorOptions {
+  readonly specObj: typeof specification;
+}
+
 class SpecificationVisitor extends Visitor {
-  public readonly specObj!: typeof specification;
+  protected readonly specObj!: typeof specification;
 
-  public readonly passingOptionsNames = ['specObj'];
+  protected readonly passingOptionsNames = ['specObj'];
 
-  constructor(options = {}) {
-    super();
-    Object.assign(this, options);
+  constructor({ specObj, ...rest }: SpecificationVisitorOptions) {
+    super({ ...rest });
+    this.specObj = specObj;
   }
 
   retrievePassingOptions() {
@@ -45,16 +49,15 @@ class SpecificationVisitor extends Visitor {
     const VisitorClz = this.retrieveVisitor(specPath) as typeof Visitor;
     const visitorOpts = { ...passingOpts, ...options };
 
-    // @ts-ignore
-    return new VisitorClz(visitorOpts as any);
+    return new VisitorClz(visitorOpts);
   }
 
   toRefractedElement(specPath: string[], element: any, options = {}) {
     /**
-     * This is `Visitor shortcut`: mechanism for short circuiting the traversal and replacing
+     * This is `Visitor shortcut`: mechanism for short-circuiting the traversal and replacing
      * it by basic node cloning.
      *
-     * Visiting the element is equivalent to cloning it  if the prototype of a visitor
+     * Visiting the element is equivalent to cloning it if the prototype of a visitor
      * is the same as the prototype of FallbackVisitor. If that's the case, we can avoid
      * bootstrapping the traversal cycle for fields that don't require any special visiting.
      */

packages/apidom-ns-api-design-systems/src/refractor/visitors/Visitor.ts

@@ -1,8 +1,14 @@
 import { hasElementSourceMap, Element } from '@swagger-api/apidom-core';
 
+export interface VisitorOptions {}
+
 class Visitor {
   public element!: Element;
 
+  constructor(options: VisitorOptions = {}) {
+    Object.assign(this, options);
+  }
+
   // eslint-disable-next-line class-methods-use-this
   public copyMetaAndAttributes(from: Element, to: Element) {
     // copy sourcemaps

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/info/index.ts

@@ -3,12 +3,12 @@ import { Mixin } from 'ts-mixer';
 
 import InfoElement from '../../../../elements/Info';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import FixedFieldsVisitor, { FixedFieldsVisitorOptions } from '../../generics/FixedFieldsVisitor';
 
 class InfoVisitor extends Mixin(FixedFieldsVisitor, FallbackVisitor) {
-  public readonly element: InfoElement;
+  public declare readonly element: InfoElement;
 
-  constructor(options = {}) {
+  constructor(options: FixedFieldsVisitorOptions) {
     super(options);
     this.specPath = always(['document', 'objects', 'Info']);
     this.element = new InfoElement();

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/main/PrinciplesVisitor.ts

@@ -5,7 +5,7 @@ import FallbackVisitor from '../../FallbackVisitor';
 import SpecificationVisitor from '../../SpecificationVisitor';
 
 class PrinciplesVisitor extends Mixin(SpecificationVisitor, FallbackVisitor) {
-  public readonly element: ArrayElement;
+  public declare readonly element: ArrayElement;
 
   constructor(options = {}) {
     super(options);

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/main/ScenariosVisitor.ts

@@ -5,7 +5,7 @@ import FallbackVisitor from '../../FallbackVisitor';
 import SpecificationVisitor from '../../SpecificationVisitor';
 
 class ScenariosVisitor extends Mixin(SpecificationVisitor, FallbackVisitor) {
-  public readonly element: ArrayElement;
+  public declare readonly element: ArrayElement;
 
   constructor(options = {}) {
     super(options);

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/main/StandardsVisitor.ts

@@ -4,7 +4,7 @@ import { ArrayElement, Element, BREAK } from '@swagger-api/apidom-core';
 import FallbackVisitor from '../../FallbackVisitor';
 import SpecificationVisitor from '../../SpecificationVisitor';
 
-class StandardsVisitor extends Mixin(FallbackVisitor, SpecificationVisitor) {
+class StandardsVisitor extends Mixin(SpecificationVisitor, FallbackVisitor) {
   public readonly element: ArrayElement;
 
   constructor(options = {}) {

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/main/index.ts

@@ -3,12 +3,12 @@ import { always } from 'ramda';
 
 import MainElement from '../../../../elements/Main';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import FixedFieldsVisitor, { FixedFieldsVisitorOptions } from '../../generics/FixedFieldsVisitor';
 
 class MainVisitor extends Mixin(FixedFieldsVisitor, FallbackVisitor) {
-  public readonly element: MainElement;
+  public declare readonly element: MainElement;
 
-  constructor(options = {}) {
+  constructor(options: FixedFieldsVisitorOptions) {
     super(options);
     this.specPath = always(['document', 'objects', 'Main']);
     this.element = new MainElement();

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/principle/index.ts

@@ -3,12 +3,12 @@ import { Mixin } from 'ts-mixer';
 
 import PrincipleElement from '../../../../elements/Principle';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import FixedFieldsVisitor, { FixedFieldsVisitorOptions } from '../../generics/FixedFieldsVisitor';
 
 class PrincipleVisitor extends Mixin(FixedFieldsVisitor, FallbackVisitor) {
-  public readonly element: PrincipleElement;
+  public declare readonly element: PrincipleElement;
 
-  constructor(options = {}) {
+  constructor(options: FixedFieldsVisitorOptions) {
     super(options);
     this.specPath = always(['document', 'objects', 'Principle']);
     this.element = new PrincipleElement();

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/requirement-level/index.ts

@@ -6,6 +6,8 @@ import SpecificationVisitor from '../../SpecificationVisitor';
 import RequirementLevelElement from '../../../../elements/RequirementLevel';
 
 class RequirementLevelVisitor extends Mixin(SpecificationVisitor, FallbackVisitor) {
+  public declare element: RequirementLevelElement;
+
   StringElement(stringElement: StringElement) {
     const requirementLevelElement = new RequirementLevelElement(toValue(stringElement));
 

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/requirement/index.ts

@@ -3,12 +3,12 @@ import { Mixin } from 'ts-mixer';
 
 import RequirementElement from '../../../../elements/Requirement';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import FixedFieldsVisitor, { FixedFieldsVisitorOptions } from '../../generics/FixedFieldsVisitor';
 
 class RequirementVisitor extends Mixin(FixedFieldsVisitor, FallbackVisitor) {
-  public readonly element: RequirementElement;
+  public declare readonly element: RequirementElement;
 
-  constructor(options = {}) {
+  constructor(options: FixedFieldsVisitorOptions) {
     super(options);
     this.specPath = always(['document', 'objects', 'Requirement']);
     this.element = new RequirementElement();

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/scenario/ThenVisitor.ts

@@ -2,12 +2,12 @@ import { Mixin } from 'ts-mixer';
 import { ArrayElement, Element, BREAK } from '@swagger-api/apidom-core';
 
 import FallbackVisitor from '../../FallbackVisitor';
-import SpecificationVisitor from '../../SpecificationVisitor';
+import SpecificationVisitor, { SpecificationVisitorOptions } from '../../SpecificationVisitor';
 
 class ThenVisitor extends Mixin(SpecificationVisitor, FallbackVisitor) {
-  public readonly element: ArrayElement;
+  public declare readonly element: ArrayElement;
 
-  constructor(options = {}) {
+  constructor(options: SpecificationVisitorOptions) {
     super(options);
     this.element = new ArrayElement();
     this.element.classes.push('scenario-then');

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/scenario/index.ts

@@ -3,12 +3,12 @@ import { Mixin } from 'ts-mixer';
 
 import ScenarioElement from '../../../../elements/Scenario';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import FixedFieldsVisitor, { FixedFieldsVisitorOptions } from '../../generics/FixedFieldsVisitor';
 
 class ScenarioVisitor extends Mixin(FixedFieldsVisitor, FallbackVisitor) {
-  public readonly element: ScenarioElement;
+  public declare readonly element: ScenarioElement;
 
-  constructor(options = {}) {
+  constructor(options: FixedFieldsVisitorOptions) {
     super(options);
     this.specPath = always(['document', 'objects', 'Scenario']);
     this.element = new ScenarioElement();

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/standard-identifier/index.ts

@@ -2,13 +2,13 @@ import { Mixin } from 'ts-mixer';
 import { ArrayElement, BREAK, Element } from '@swagger-api/apidom-core';
 
 import FallbackVisitor from '../../FallbackVisitor';
-import SpecificationVisitor from '../../SpecificationVisitor';
+import SpecificationVisitor, { SpecificationVisitorOptions } from '../../SpecificationVisitor';
 import StandardIdentifierElement from '../../../../elements/StandardIdentifier';
 
 class StandardIdentifierVisitor extends Mixin(SpecificationVisitor, FallbackVisitor) {
-  public readonly element: StandardIdentifierElement;
+  public declare readonly element: StandardIdentifierElement;
 
-  constructor(options = {}) {
+  constructor(options: SpecificationVisitorOptions) {
     super(options);
     this.element = new StandardIdentifierElement();
   }

packages/apidom-ns-api-design-systems/src/refractor/visitors/api-design-systems/standard/index.ts

@@ -3,12 +3,12 @@ import { Mixin } from 'ts-mixer';
 
 import StandardElement from '../../../../elements/Standard';
 import FallbackVisitor from '../../FallbackVisitor';
-import FixedFieldsVisitor from '../../generics/FixedFieldsVisitor';
+import FixedFieldsVisitor, { FixedFieldsVisitorOptions } from '../../generics/FixedFieldsVisitor';
 
 class StandardVisitor extends Mixin(FixedFieldsVisitor, FallbackVisitor) {
-  public readonly element: StandardElement;
+  public declare readonly element: StandardElement;
 
-  constructor(options = {}) {
+  constructor(options: FixedFieldsVisitorOptions) {
     super(options);
     this.specPath = always(['document', 'objects', 'Standard']);
     this.element = new StandardElement();

packages/apidom-ns-api-design-systems/src/refractor/visitors/generics/FixedFieldsVisitor.ts

@@ -8,14 +8,25 @@ import {
   toValue,
 } from '@swagger-api/apidom-core';
 
-import SpecificationVisitor from '../SpecificationVisitor';
+import SpecificationVisitor, { SpecificationVisitorOptions } from '../SpecificationVisitor';
+
+export interface FixedFieldsVisitorOptions extends SpecificationVisitorOptions {
+  readonly specPath: (element: Element) => string[];
+  readonly ignoredFields?: string[];
+}
 
 class FixedFieldsVisitor extends SpecificationVisitor {
-  public specPath!: (element: Element) => string[];
+  protected specPath: (element: Element) => string[];
 
-  public ignoredFields: string[] = [];
+  protected ignoredFields: string[];
+
+  constructor({ specPath, ignoredFields, ...rest }: FixedFieldsVisitorOptions) {
+    super({ ...rest });
+    this.specPath = specPath;
+    this.ignoredFields = ignoredFields || [];
+  }
 
-  public ObjectElement(objectElement: ObjectElement) {
+  ObjectElement(objectElement: ObjectElement) {
     const specPath = this.specPath(objectElement);
     const fields = this.retrieveFixedFields(specPath);
 

packages/apidom-parser-adapter-json/test/syntactic-analysis/__snapshots__/TreeCursorIterator.ts.snap

@@ -12,6 +12,7 @@ TreeCursorSyntaxNode {
             column: 1,
             row: 0,
           },
+          fieldName: undefined,
           hasError: false,
           isMissing: false,
           isNamed: false,
@@ -49,6 +50,7 @@ TreeCursorSyntaxNode {
             column: 3,
             row: 0,
           },
+          fieldName: undefined,
           hasError: false,
           isMissing: false,
           isNamed: false,
@@ -86,6 +88,7 @@ TreeCursorSyntaxNode {
             column: 6,
             row: 0,
           },
+          fieldName: undefined,
           hasError: false,
           isMissing: false,
           isNamed: false,
@@ -121,6 +124,7 @@ TreeCursorSyntaxNode {
     column: 6,
     row: 0,
   },
+  fieldName: undefined,
   hasError: false,
   isMissing: false,
   isNamed: true,