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]>

Author: 3 people

.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-lock.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",

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/package.json

@@ -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-normalize/src/index.ts

@@ -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-har/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-to-snippet/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"
 }