feat(parser): rewriting the library in typescript (#932)

## 🐳 Context

Now that our fork of
[@apidevtools/swagger-parser](https://npm.im/@apidevtools/swagger-parser)
has fully deviated and was moved here from [our other
repository](https://github.com/readmeio/openapi-parser) I have built off
of JonLuca's[^1] starting work over in
APIDevTools/swagger-parser#253 and rewritten the
library in TS.

This is all going to be the basis for a slew of forthcoming changes in
order to support error levels.

Because this is a full rewrite, and a lot of things have changed, this
will incur a major version bump.

## 🧰 Changes

* [x] Rewrote our OpenAPI parser in TS.
* [x] Added in dual support for CJS and ESM.
* [x] Resolved a number of test quirks and invalid false positive
assertions.

[^1]: Because I adapted heavily from his draft PR of this rewrite over
in the swagger-parser repository I've credited him as a co-author of
this work.

---------

Co-authored-by: JonLuca De Caro <[email protected]>
Co-authored-by: Kanad Gupta <[email protected]>

.eslintrc

@@ -1,4 +1,4 @@
 {
   "extends": ["@readme/eslint-config", "@readme/eslint-config/typescript", "@readme/eslint-config/esm"],
-  "root": true
+  "root": true,
 }

.prettierignore

@@ -0,0 +1 @@
+packages/parser/test/specs/large-file-memory-leak/cloudflare-stringified.json

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll": "explicit"
+  },
+  "editor.formatOnSave": true
+}

package.json

@@ -27,7 +27,7 @@
     "./packages/*"
   ],
   "devDependencies": {
-    "@readme/eslint-config": "^14.0.0",
+    "@readme/eslint-config": "^14.2.0",
     "@vitest/coverage-v8": "^3.0.4",
     "alex": "^11.0.1",
     "eslint": "^8.57.0",

packages/oas-normalize/package.json

@@ -77,7 +77,8 @@
     "eslint": "^8.57.0",
     "nock": "^14.0.0",
     "tsup": "^8.0.2",
-    "typescript": "^5.1.6"
+    "typescript": "^5.1.6",
+    "vitest": "^3.0.5"
   },
   "prettier": "@readme/eslint-config/prettier"
 }

packages/oas-normalize/src/index.ts

@@ -1,9 +1,10 @@
 import type { Options } from './lib/types.js';
+import type { ParserOptions } from '@readme/openapi-parser';
 import type { OpenAPI, OpenAPIV2, OpenAPIV3 } from 'openapi-types';
 
 import fs from 'node:fs';
 
-import openapiParser from '@readme/openapi-parser';
+import { OpenAPIParser } from '@readme/openapi-parser';
 import postmanToOpenAPI from '@readme/postman-to-openapi';
 import converter from 'swagger2openapi';
 
@@ -108,9 +109,8 @@ export default class OASNormalize {
 
         return schema;
       })
-      .then(schema => openapiParser.bundle(schema))
+      .then(schema => new OpenAPIParser().bundle(schema))
       .then(bundle => {
-        // @ts-expect-error The typings on the parser are messed up rigth now while a rewrite is in progress.
         this.cache.bundle = bundle;
         return bundle;
       });
@@ -134,9 +134,8 @@ export default class OASNormalize {
 
         return schema;
       })
-      .then(schema => openapiParser.dereference(schema))
+      .then(schema => new OpenAPIParser().dereference(schema))
       .then(dereferenced => {
-        // @ts-expect-error The typings on the parser are messed up rigth now while a rewrite is in progress.
         this.cache.deref = dereferenced;
         return dereferenced;
       });
@@ -181,7 +180,7 @@ export default class OASNormalize {
    */
   async validate(
     opts: {
-      parser?: openapiParser.Options;
+      parser?: ParserOptions;
     } = {},
   ): Promise<true> {
     const parserOptions = opts.parser || {};
@@ -208,7 +207,7 @@ export default class OASNormalize {
         }
 
         /**
-         * `openapiParser.validate()` dereferences schemas at the same time as validation, mutating
+         * `OpenAPIParser.validate()` dereferences schemas at the same time as validation, mutating
          * the supplied parameter in the process, and does not give us an option to disable this.
          * As we already have a dereferencing method on this library, and this method just needs to
          * tell us if the API definition is valid or not, we need to clone the schema before
@@ -217,8 +216,7 @@ export default class OASNormalize {
         // eslint-disable-next-line try-catch-failsafe/json-parse
         const clonedSchema = JSON.parse(JSON.stringify(schema));
 
-        // @ts-expect-error The typings on the parser are messed up rigth now while a rewrite is in progress.
-        return openapiParser.validate(clonedSchema, parserOptions).then(() => {
+        return new OpenAPIParser().validate(clonedSchema, parserOptions).then(() => {
           // The API definition, whatever its format or specification, is valid.
           return true;
         });

packages/oas-to-har/package.json

@@ -62,7 +62,8 @@
     "jest-expect-har": "^7.1.0",
     "tsup": "^8.0.2",
     "type-fest": "^4.18.3",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "vitest": "^3.0.5"
   },
   "prettier": "@readme/eslint-config/prettier"
 }

packages/oas-to-snippet/package.json

@@ -62,7 +62,8 @@
     "oas": "file:../oas",
     "tsup": "^8.0.2",
     "type-fest": "^4.18.3",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "vitest": "^3.0.5"
   },
   "prettier": "@readme/eslint-config/prettier"
 }

packages/oas/package.json

@@ -105,7 +105,8 @@
     "@types/memoizee": "^0.4.11",
     "@types/node": "^22.7.6",
     "tsup": "^8.0.2",
-    "typescript": "^5.4.4"
+    "typescript": "^5.4.4",
+    "vitest": "^3.0.5"
   },
   "prettier": "@readme/eslint-config/prettier"
 }

packages/oas/test/operation/index.test.ts

@@ -1,7 +1,7 @@
 import type * as RMOAS from '../../src/types.js';
 
 import petstoreSpec from '@readme/oas-examples/3.0/json/petstore.json';
-import openapiParser from '@readme/openapi-parser';
+import { OpenAPIParser } from '@readme/openapi-parser';
 import { beforeAll, describe, it, expect } from 'vitest';
 
 import Oas from '../../src/index.js';
@@ -708,7 +708,7 @@ describe('#getSecurityWithTypes()', () => {
 
     // The original API doc should still be valid.
     const clonedSpec = JSON.parse(JSON.stringify(spec.api));
-    await expect(openapiParser.validate(clonedSpec)).resolves.toStrictEqual(
+    await expect(OpenAPIParser.validate(clonedSpec)).resolves.toStrictEqual(
       expect.objectContaining({
         openapi: '3.1.0',
       }),

packages/oas/test/operation/lib/get-response-as-json-schema.test.ts

@@ -1,6 +1,6 @@
 import type { HttpMethods, ResponseObject, SchemaObject } from '../../../src/types.js';
 
-import openapiParser from '@readme/openapi-parser';
+import { OpenAPIParser } from '@readme/openapi-parser';
 import { beforeAll, describe, test, expect, it } from 'vitest';
 
 import Oas from '../../../src/index.js';
@@ -301,7 +301,7 @@ describe('quirks', () => {
       });
 
       // The original spec should still validate too!
-      await expect(openapiParser.validate(cloneObject(definition))).resolves.toStrictEqual(
+      await expect(OpenAPIParser.validate(cloneObject(definition))).resolves.toStrictEqual(
         expect.objectContaining({
           openapi: '3.0.2',
         }),

packages/parser/.eslintrc

@@ -1,49 +1,10 @@
 {
-  "root": true,
-  "extends": [
-    "@readme/eslint-config",
-    "@readme/eslint-config/typescript",
-  ],
-  "env": {
-    "browser": true,
-    "node": true
-  },
   "rules": {
+    "camelcase": ["error", { "allow": ["OpenAPIV3_1"] }],
+    "lines-between-class-members": "off",
+    "no-continue": "off",
     "no-plusplus": "off",
-    "no-restricted-syntax": "off",
-    "no-underscore-dangle": "off",
-    "no-use-before-define": "off",
     "prefer-rest-params": "off",
-    "prefer-spread": "off"
+    "prefer-spread": "off",
   },
-  "overrides": [
-    {
-      // The typings in this file are pretty bad right now, when we have native types we can
-      // remove this.
-      "files": ["lib/index.d.ts"],
-      "rules": {
-        "@typescript-eslint/consistent-indexed-object-style": "off",
-        "@typescript-eslint/consistent-type-imports": "off",
-        "@typescript-eslint/no-explicit-any": "off",
-        "@typescript-eslint/sort-type-constituents": "off",
-        "eslint-comments/no-unused-disable": "off",
-        "lines-between-class-members": "off",
-        "max-classes-per-file": "off",
-        "quotes": "off",
-        "typescript-sort-keys/interface": "off"
-      }
-    },
-    {
-      // These can all get removed when the library is moved over to native TS.
-      "files": ["*.js"],
-      "rules": {
-        "@typescript-eslint/no-this-alias": "off",
-        "@typescript-eslint/no-unused-vars": "off",
-        "@typescript-eslint/no-use-before-define": "off",
-        "@typescript-eslint/no-var-requires": "off",
-        "eslint-comments/no-unused-disable": "off",
-        "func-names": "off"
-      }
-    }
-  ]
 }