oas-normalize 5.2.0 → 7.0.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 ReadMe
+Copyright (c) 2022 ReadMe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -14,22 +14,24 @@ npm install oas-normalize --save
 
 # Usage
 
-It's pretty simple:
-
 ```javascript
-const OASNormalize = require('oas-normalize');
+import OASNormalize from 'oas-normalize';
+// const { default: OASNormalize } = require('oas-normalize'); // If you're using CJS.
 
 const oas = new OASNormalize(
   // Or a string, pathname, JSON blob, whatever
   'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml'
 );
 
-oas.validate().then(definition => {
-  // Definition will always be JSON, and valid.
-  console.log(definition);
-}).catch(err => {
-  console.log(err);
-});
+oas
+  .validate()
+  .then(definition => {
+    // Definition will always be JSON, and valid.
+    console.log(definition);
+  })
+  .catch(err => {
+    console.log(err);
+  });
 ```
 
 # Errors
@@ -59,18 +61,23 @@ For validation errors, when available, you'll get back an object:
 
 If you want some more functionality, you can do anything here:
 
+<!--
+Prettier's table formatting sucks, hence the ignore block below.
+-->
+<!-- prettier-ignore-start -->
 | Function | What it does |
 | :--- | :--- |
 | `.load()` | Just load the file, valid or not, as JSON |
 | `.bundle()` | Bring together all files into one JSON blob (but retain `$ref` pointers) |
 | `.deref()` | Resolve `$ref` pointers |
 | `.validate([convertToLatest?])` | Validate the whole thing! |
+<!-- prettier-ignore-end -->
 
 # Other Little Features
 
 ### Always Return OpenAPI 3.x
 
-If you want `.validate` to always return an OpenAPI 3.x definition, supply `true` as its argument:
+If you want `.validate()` to always return an OpenAPI 3.x definition, supply `true` as its argument:
 
 ```js
 OASNormalize.validate(true).then(...);
@@ -81,7 +88,7 @@ OASNormalize.validate(true).then(...);
 For security reasons, you need to opt into allowing fetching by a local path. To enable it supply the `enablePaths` option to the class instance:
 
 ```js
-const oas = new OASNormalize('./petstore.json', { enablePaths: true })
+const oas = new OASNormalize('./petstore.json', { enablePaths: true });
 ```
 
 ### Colorized errors
@@ -91,7 +98,7 @@ If you wish errors from `.validate()` to be styled and colorized, supply `colori
 ```js
 const oas = new OASNormalize('https://example.com/petstore.json', {
   colorizeErrors: true,
-})
+});
 ```
 
 Error messages will look like such:

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import type { OpenAPI } from 'openapi-types';
+export declare type Options = {
+    colorizeErrors?: boolean;
+    enablePaths?: boolean;
+};
+export default class OASNormalize {
+    cache: {
+        bundle?: false | OpenAPI.Document;
+        deref?: false | OpenAPI.Document;
+        load?: false | Record<string, unknown>;
+    };
+    file: any;
+    opts: Options;
+    type: boolean | string;
+    constructor(file: any, opts?: Options);
+    load(): Promise<any>;
+    /**
+     * Bundle up the given OpenAPI or Swagger definition, resolving any external `$ref` pointers in
+     * the process.
+     *
+     */
+    bundle(): Promise<import("openapi-types").OpenAPIV2.Document<{}> | import("openapi-types").OpenAPIV3.Document<{}> | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "paths"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "paths">) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "webhooks"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "webhooks">) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "components"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "components">)>;
+    /**
+     * Dereference the given OpenAPI or Swagger.
+     *
+     */
+    deref(): Promise<import("openapi-types").OpenAPIV2.Document<{}> | import("openapi-types").OpenAPIV3.Document<{}> | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "paths"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "paths">) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "webhooks"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "webhooks">) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "components"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "components">)>;
+    /**
+     * Validate a given OpenAPI or Swagger definition, potentially upconverting it from Swagger to
+     * OpenAPI in the process if you wish.
+     *
+     */
+    validate(convertToLatest?: boolean): Promise<any>;
+    /**
+     * Retrieve the OpenAPI or Swagger version of the current API definition.
+     *
+     */
+    version(): Promise<string>;
+}

package/dist/index.js

@@ -0,0 +1,225 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+var fs_1 = __importDefault(require("fs"));
+var openapi_parser_1 = __importDefault(require("@readme/openapi-parser"));
+var node_fetch_1 = __importDefault(require("node-fetch"));
+var swagger2openapi_1 = __importDefault(require("swagger2openapi"));
+var utils = __importStar(require("./lib/utils"));
+var OASNormalize = /** @class */ (function () {
+    function OASNormalize(file, opts) {
+        this.file = file;
+        this.opts = __assign({ colorizeErrors: false, enablePaths: false }, opts);
+        this.type = utils.getType(this.file);
+        this.cache = {
+            load: false,
+            bundle: false,
+            deref: false
+        };
+    }
+    // Internal API for the most part
+    OASNormalize.prototype.load = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var resolve, _a, resp, contents;
+            var _this = this;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        if (this.cache.load)
+                            return [2 /*return*/, Promise.resolve(this.cache.load)];
+                        resolve = function (obj) {
+                            var ret = utils.stringToJSON(obj);
+                            _this.cache.load = ret;
+                            return Promise.resolve(ret);
+                        };
+                        _a = this.type;
+                        switch (_a) {
+                            case 'json': return [3 /*break*/, 1];
+                            case 'string-json': return [3 /*break*/, 1];
+                            case 'string-yaml': return [3 /*break*/, 1];
+                            case 'buffer': return [3 /*break*/, 2];
+                            case 'url': return [3 /*break*/, 3];
+                            case 'path': return [3 /*break*/, 5];
+                        }
+                        return [3 /*break*/, 6];
+                    case 1: return [2 /*return*/, resolve(this.file)];
+                    case 2: return [2 /*return*/, resolve(this.file.toString())];
+                    case 3: return [4 /*yield*/, (0, node_fetch_1["default"])(this.file).then(function (res) { return res.text(); })];
+                    case 4:
+                        resp = _b.sent();
+                        return [2 /*return*/, resolve(resp)];
+                    case 5:
+                        // Load a local file
+                        if (!this.opts.enablePaths) {
+                            return [2 /*return*/, Promise.reject(new Error('Use `opts.enablePaths` to enable accessing local files.'))];
+                        }
+                        contents = fs_1["default"].readFileSync(this.file).toString();
+                        return [2 /*return*/, resolve(contents)];
+                    case 6: return [2 /*return*/, Promise.reject(new Error('Could not load this file.'))];
+                }
+            });
+        });
+    };
+    /**
+     * Bundle up the given OpenAPI or Swagger definition, resolving any external `$ref` pointers in
+     * the process.
+     *
+     */
+    OASNormalize.prototype.bundle = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                if (this.cache.bundle)
+                    return [2 /*return*/, Promise.resolve(this.cache.bundle)];
+                return [2 /*return*/, this.load()
+                        .then(function (schema) { return openapi_parser_1["default"].bundle(schema); })
+                        .then(function (bundle) {
+                        _this.cache.bundle = bundle;
+                        return bundle;
+                    })];
+            });
+        });
+    };
+    /**
+     * Dereference the given OpenAPI or Swagger.
+     *
+     */
+    OASNormalize.prototype.deref = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                if (this.cache.deref)
+                    return [2 /*return*/, Promise.resolve(this.cache.deref)];
+                return [2 /*return*/, this.load()
+                        .then(function (schema) { return openapi_parser_1["default"].dereference(schema); })
+                        .then(function (dereferenced) {
+                        _this.cache.deref = dereferenced;
+                        return dereferenced;
+                    })];
+            });
+        });
+    };
+    /**
+     * Validate a given OpenAPI or Swagger definition, potentially upconverting it from Swagger to
+     * OpenAPI in the process if you wish.
+     *
+     */
+    OASNormalize.prototype.validate = function (convertToLatest) {
+        if (convertToLatest === void 0) { convertToLatest = false; }
+        return __awaiter(this, void 0, void 0, function () {
+            var colorizeErrors;
+            var _this = this;
+            return __generator(this, function (_a) {
+                colorizeErrors = this.opts.colorizeErrors;
+                return [2 /*return*/, this.load().then(function (schema) { return __awaiter(_this, void 0, void 0, function () {
+                        var baseVersion, clonedSchema;
+                        return __generator(this, function (_a) {
+                            baseVersion = parseInt(utils.version(schema), 10);
+                            if (baseVersion === 1) {
+                                return [2 /*return*/, Promise.reject(new Error('Swagger v1.2 is unsupported.'))];
+                            }
+                            else if (baseVersion === 2 || baseVersion === 3) {
+                                clonedSchema = JSON.parse(JSON.stringify(schema));
+                                return [2 /*return*/, openapi_parser_1["default"]
+                                        .validate(clonedSchema, {
+                                        validate: {
+                                            colorizeErrors: colorizeErrors
+                                        }
+                                    })
+                                        .then(function () {
+                                        if (!convertToLatest) {
+                                            return schema;
+                                        }
+                                        return swagger2openapi_1["default"].convertObj(schema, { anchors: true }).then(function (options) {
+                                            return options.openapi;
+                                        });
+                                    })["catch"](function (err) { return Promise.reject(err); })];
+                            }
+                            return [2 /*return*/, Promise.reject(new Error('The supplied API definition is unsupported.'))];
+                        });
+                    }); })];
+            });
+        });
+    };
+    /**
+     * Retrieve the OpenAPI or Swagger version of the current API definition.
+     *
+     */
+    OASNormalize.prototype.version = function () {
+        return this.load().then(function (schema) { return utils.version(schema); });
+    };
+    return OASNormalize;
+}());
+exports["default"] = OASNormalize;

package/dist/lib/utils.d.ts

@@ -0,0 +1,21 @@
+import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+/**
+ * Retrieve the Swagger or OpenAPI version that a given Swagger or OpenAPI definition are targeting.
+ *
+ */
+export declare function version(schema: OpenAPIV2.Document & OpenAPIV3.Document & OpenAPIV3_1.Document): string;
+/**
+ * Determine if a given variable is a `Buffer`.
+ *
+ */
+export declare function isBuffer(obj: any): any;
+/**
+ * Convert a YAML blob or stringified JSON object into a JSON object.
+ *
+ */
+export declare function stringToJSON(string: string | Record<string, unknown>): any;
+/**
+ * Determine the type of a given variable. Returns `false` if unrecognized.
+ *
+ */
+export declare function getType(obj: any): false | "path" | "json" | "buffer" | "string-json" | "string-yaml" | "url";

package/dist/lib/utils.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+exports.getType = exports.stringToJSON = exports.isBuffer = exports.version = void 0;
+var js_yaml_1 = __importDefault(require("js-yaml"));
+/**
+ * Retrieve the Swagger or OpenAPI version that a given Swagger or OpenAPI definition are targeting.
+ *
+ */
+function version(schema) {
+    return schema.swagger || schema.openapi;
+}
+exports.version = version;
+/**
+ * Determine if a given variable is a `Buffer`.
+ *
+ */
+function isBuffer(obj) {
+    return (obj != null &&
+        obj.constructor != null &&
+        typeof obj.constructor.isBuffer === 'function' &&
+        obj.constructor.isBuffer(obj));
+}
+exports.isBuffer = isBuffer;
+/**
+ * Convert a YAML blob or stringified JSON object into a JSON object.
+ *
+ */
+function stringToJSON(string) {
+    if (typeof string === 'object') {
+        return string;
+    }
+    else if (string.match(/^\s*{/)) {
+        return JSON.parse(string);
+    }
+    return js_yaml_1["default"].load(string);
+}
+exports.stringToJSON = stringToJSON;
+/**
+ * Determine the type of a given variable. Returns `false` if unrecognized.
+ *
+ */
+function getType(obj) {
+    if (isBuffer(obj)) {
+        return 'buffer';
+    }
+    else if (typeof obj === 'object') {
+        return 'json';
+    }
+    else if (typeof obj === 'string') {
+        if (obj.match(/\s*{/)) {
+            return 'string-json';
+        }
+        else if (obj.match(/\n/)) {
+            // Not sure about this...
+            return 'string-yaml';
+        }
+        else if (obj.substring(0, 4) === 'http') {
+            return 'url';
+        }
+        return 'path';
+    }
+    return false;
+}
+exports.getType = getType;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "oas-normalize",
-  "version": "5.2.0",
+  "version": "7.0.0",
   "description": "OpenAPI 3.x or Swagger 2.0? YAML or JSON? URL, path, string or object? Who cares! It just works.",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "engines": {
-    "node": "^12 || ^14 || ^16"
+    "node": ">=14"
   },
   "tags": [
     "api",
@@ -29,25 +30,36 @@
     "url": "https://github.com/readmeio/oas-normalize/issues"
   },
   "scripts": {
-    "lint": "eslint .",
+    "build": "tsc",
+    "lint": "eslint . --ext .js,.ts && npm run prettier",
+    "prebuild": "rm -rf dist/",
+    "prepack": "npm run build",
     "pretest": "npm run lint",
-    "prettier": "prettier --list-different --write \"./**/**.{js,jsx}\"",
+    "prettier": "prettier --list-different \"./**/**.{md,js,ts}\"",
+    "prettier:write": "prettier --list-different --write \"./**/**.{md,js,ts}\"",
     "test": "jest --coverage"
   },
   "license": "MIT",
   "dependencies": {
-    "@readme/openapi-parser": "^2.1.0",
+    "@readme/openapi-parser": "^2.2.0",
     "js-yaml": "^4.1.0",
     "node-fetch": "^2.6.1",
+    "openapi-types": "^12.0.0",
     "swagger2openapi": "^7.0.8"
   },
   "devDependencies": {
-    "@readme/eslint-config": "^8.5.1",
-    "@readme/oas-examples": "^5.0.0",
-    "eslint": "^8.12.0",
-    "jest": "^27.5.1",
+    "@readme/eslint-config": "^10.0.0",
+    "@readme/oas-examples": "^5.1.1",
+    "@types/jest": "^28.1.6",
+    "@types/js-yaml": "^4.0.5",
+    "@types/node-fetch": "^2.6.2",
+    "eslint": "^8.21.0",
+    "jest": "^28.0.3",
+    "jet": "^0.8.1",
     "nock": "^13.2.4",
-    "prettier": "^2.6.1"
+    "prettier": "^2.7.1",
+    "ts-jest": "^28.0.7",
+    "typescript": "^4.7.4"
   },
   "prettier": "@readme/eslint-config/prettier"
 }

package/src/.sink.d.ts

@@ -0,0 +1,2 @@
+// These packages don't have any TS types so we need to declare a module in order to use them.
+declare module 'swagger2openapi';

package/src/index.ts

@@ -0,0 +1,167 @@
+import type { OpenAPI } from 'openapi-types';
+
+import fs from 'fs';
+
+import openapiParser from '@readme/openapi-parser';
+import fetch from 'node-fetch';
+
+import converter from 'swagger2openapi';
+
+import * as utils from './lib/utils';
+
+export type Options = {
+  colorizeErrors?: boolean;
+  enablePaths?: boolean;
+};
+
+export default class OASNormalize {
+  cache: {
+    bundle?: false | OpenAPI.Document;
+    deref?: false | OpenAPI.Document;
+    load?: false | Record<string, unknown>;
+  };
+
+  file: any;
+
+  opts: Options;
+
+  type: boolean | string;
+
+  constructor(file: any, opts?: Options) {
+    this.file = file;
+    this.opts = {
+      colorizeErrors: false,
+      enablePaths: false,
+      ...opts,
+    };
+
+    this.type = utils.getType(this.file);
+
+    this.cache = {
+      load: false,
+      bundle: false,
+      deref: false,
+    };
+  }
+
+  // Internal API for the most part
+  async load() {
+    if (this.cache.load) return Promise.resolve(this.cache.load);
+
+    const resolve = (obj: Parameters<typeof utils.stringToJSON>[0]) => {
+      const ret = utils.stringToJSON(obj);
+      this.cache.load = ret;
+      return Promise.resolve(ret);
+    };
+
+    switch (this.type) {
+      case 'json':
+      case 'string-json':
+      case 'string-yaml':
+        return resolve(this.file);
+
+      case 'buffer':
+        return resolve(this.file.toString());
+
+      case 'url':
+        const resp = await fetch(this.file).then(res => res.text());
+        return resolve(resp);
+
+      case 'path':
+        // Load a local file
+        if (!this.opts.enablePaths) {
+          return Promise.reject(new Error('Use `opts.enablePaths` to enable accessing local files.'));
+        }
+
+        const contents = fs.readFileSync(this.file).toString();
+        return resolve(contents);
+
+      default:
+        return Promise.reject(new Error('Could not load this file.'));
+    }
+  }
+
+  /**
+   * Bundle up the given OpenAPI or Swagger definition, resolving any external `$ref` pointers in
+   * the process.
+   *
+   */
+  async bundle() {
+    if (this.cache.bundle) return Promise.resolve(this.cache.bundle);
+
+    return this.load()
+      .then(schema => openapiParser.bundle(schema))
+      .then(bundle => {
+        this.cache.bundle = bundle;
+        return bundle;
+      });
+  }
+
+  /**
+   * Dereference the given OpenAPI or Swagger.
+   *
+   */
+  async deref() {
+    if (this.cache.deref) return Promise.resolve(this.cache.deref);
+
+    return this.load()
+      .then(schema => openapiParser.dereference(schema))
+      .then(dereferenced => {
+        this.cache.deref = dereferenced;
+        return dereferenced;
+      });
+  }
+
+  /**
+   * Validate a given OpenAPI or Swagger definition, potentially upconverting it from Swagger to
+   * OpenAPI in the process if you wish.
+   *
+   */
+  async validate(convertToLatest = false) {
+    const colorizeErrors = this.opts.colorizeErrors;
+
+    return this.load().then(async schema => {
+      const baseVersion = parseInt(utils.version(schema), 10);
+
+      if (baseVersion === 1) {
+        return Promise.reject(new Error('Swagger v1.2 is unsupported.'));
+      } else if (baseVersion === 2 || baseVersion === 3) {
+        /**
+         * `openapiParser.validate()` dereferences schemas at the same time as validation and does
+         * not give us an option to disable this. Since all we already have a dereferencing method
+         * on this library and our `validate()` method here just needs to tell us if the definition
+         * is valid or not we need to clone it before passing it over to `openapi-parser` so as to
+         * not run into pass-by-reference problems.
+         */
+        const clonedSchema = JSON.parse(JSON.stringify(schema));
+
+        return openapiParser
+          .validate(clonedSchema, {
+            validate: {
+              colorizeErrors,
+            },
+          })
+          .then(() => {
+            if (!convertToLatest) {
+              return schema;
+            }
+
+            return converter.convertObj(schema, { anchors: true }).then((options: { openapi: OpenAPI.Document }) => {
+              return options.openapi;
+            });
+          })
+          .catch(err => Promise.reject(err));
+      }
+
+      return Promise.reject(new Error('The supplied API definition is unsupported.'));
+    });
+  }
+
+  /**
+   * Retrieve the OpenAPI or Swagger version of the current API definition.
+   *
+   */
+  version() {
+    return this.load().then(schema => utils.version(schema));
+  }
+}

package/src/lib/utils.ts

@@ -0,0 +1,63 @@
+import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+
+import YAML from 'js-yaml';
+
+/**
+ * Retrieve the Swagger or OpenAPI version that a given Swagger or OpenAPI definition are targeting.
+ *
+ */
+export function version(schema: OpenAPIV2.Document & OpenAPIV3.Document & OpenAPIV3_1.Document) {
+  return schema.swagger || schema.openapi;
+}
+
+/**
+ * Determine if a given variable is a `Buffer`.
+ *
+ */
+export function isBuffer(obj: any) {
+  return (
+    obj != null &&
+    obj.constructor != null &&
+    typeof obj.constructor.isBuffer === 'function' &&
+    obj.constructor.isBuffer(obj)
+  );
+}
+
+/**
+ * Convert a YAML blob or stringified JSON object into a JSON object.
+ *
+ */
+export function stringToJSON(string: string | Record<string, unknown>) {
+  if (typeof string === 'object') {
+    return string;
+  } else if (string.match(/^\s*{/)) {
+    return JSON.parse(string);
+  }
+
+  return YAML.load(string);
+}
+
+/**
+ * Determine the type of a given variable. Returns `false` if unrecognized.
+ *
+ */
+export function getType(obj: any) {
+  if (isBuffer(obj)) {
+    return 'buffer';
+  } else if (typeof obj === 'object') {
+    return 'json';
+  } else if (typeof obj === 'string') {
+    if (obj.match(/\s*{/)) {
+      return 'string-json';
+    } else if (obj.match(/\n/)) {
+      // Not sure about this...
+      return 'string-yaml';
+    } else if (obj.substring(0, 4) === 'http') {
+      return 'url';
+    }
+
+    return 'path';
+  }
+
+  return false;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "baseUrl": "./src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "lib": ["dom", "es2020"],
+    "outDir": "dist/",
+    "paths": {
+      "swagger2openapi": [".sink.d.ts"]
+    },
+  },
+  "include": ["./src/**/*"]
+}

package/index.js

@@ -1,120 +0,0 @@
-const fetch = require('node-fetch');
-const fs = require('fs');
-const converter = require('swagger2openapi');
-const openapiParser = require('@readme/openapi-parser');
-const utils = require('./lib/utils');
-
-class oasNormalize {
-  constructor(file, opts) {
-    this.file = file;
-    this.opts = {
-      colorizeErrors: false,
-      enablePaths: false,
-      ...opts,
-    };
-
-    this.type = utils.type(this.file);
-
-    this.cache = {
-      load: false,
-      bundle: false,
-      deref: false,
-    };
-  }
-
-  // Internal API for the most part
-  async load() {
-    if (this.cache.load) return Promise.resolve(this.cache.load);
-
-    const resolve = obj => {
-      const ret = utils.stringToJSON(obj);
-      this.cache.load = ret;
-      return Promise.resolve(ret);
-    };
-
-    if (this.type === 'json' || this.type === 'string-json' || this.type === 'string-yaml') {
-      return resolve(this.file);
-    } else if (this.type === 'buffer') {
-      return resolve(this.file.toString());
-    } else if (this.type === 'url') {
-      const resp = await fetch(this.file).then(res => res.text());
-      return resolve(resp);
-    } else if (this.type === 'path') {
-      // Load a local file
-      if (!this.opts.enablePaths) {
-        return Promise.reject(new Error('Use `opts.enablePaths` to enable accessing local files.'));
-      }
-
-      const contents = fs.readFileSync(this.file).toString();
-      return resolve(contents);
-    }
-
-    return Promise.reject(new Error('Could not load this file.'));
-  }
-
-  async bundle() {
-    if (this.cache.bundle) return Promise.resolve(this.cache.bundle);
-
-    return this.load()
-      .then(schema => openapiParser.bundle(schema))
-      .then(bundle => {
-        this.cache.bundle = bundle;
-        return bundle;
-      });
-  }
-
-  async deref() {
-    if (this.cache.deref) return Promise.resolve(this.cache.deref);
-
-    return this.load()
-      .then(schema => openapiParser.dereference(schema))
-      .then(dereferenced => {
-        this.cache.deref = dereferenced;
-        return dereferenced;
-      });
-  }
-
-  async validate(convertToLatest = false) {
-    const colorizeErrors = this.opts.colorizeErrors;
-
-    return this.load().then(async schema => {
-      const baseVersion = parseInt(utils.version(schema), 10);
-
-      if (baseVersion === 1) {
-        return Promise.reject(new Error('Swagger v1.2 is unsupported.'));
-      } else if (baseVersion === 2 || baseVersion === 3) {
-        // `openapiParser.validate()` dereferences schemas at the same time as validation and does
-        // not give us an option to disable this. Since all we already have a dereferencing method
-        // on this library and our `validate()` method here just needs to tell us if the definition
-        // is valid or not we need to clone it before passing it over to `openapi-parser` so as to
-        // not run into pass-by-reference problems.
-        const clonedSchema = JSON.parse(JSON.stringify(schema));
-
-        return openapiParser
-          .validate(clonedSchema, {
-            validate: {
-              colorizeErrors,
-            },
-          })
-          .then(() => {
-            if (!convertToLatest) {
-              return schema;
-            }
-
-            return converter.convertObj(schema, { anchors: true }).then(options => {
-              return options.openapi;
-            });
-          })
-          .catch(err => Promise.reject(err));
-      }
-
-      return Promise.reject(new Error('The supplied API definition is unsupported.'));
-    });
-  }
-
-  version() {
-    return this.load().then(schema => utils.version(schema));
-  }
-}
-
-module.exports = oasNormalize;

package/lib/utils.js

@@ -1,44 +0,0 @@
-const YAML = require('js-yaml');
-
-module.exports = {
-  // YAML or JSON string to JSON Object
-  stringToJSON: string => {
-    if (typeof string === 'object') {
-      return string;
-    } else if (string.match(/^\s*{/)) {
-      return JSON.parse(string);
-    }
-
-    return YAML.load(string);
-  },
-
-  type: obj => {
-    if (module.exports.isBuffer(obj)) {
-      return 'buffer';
-    } else if (typeof obj === 'object') {
-      return 'json';
-    } else if (typeof obj === 'string') {
-      if (obj.match(/\s*{/)) {
-        return 'string-json';
-      }
-      if (obj.match(/\n/)) {
-        // Not sure about this...
-        return 'string-yaml';
-      }
-      if (obj.substr(0, 4) === 'http') {
-        return 'url';
-      }
-      return 'path';
-    }
-
-    return false;
-  },
-
-  version: schema => schema.swagger || schema.openapi,
-
-  isBuffer: obj =>
-    obj != null &&
-    obj.constructor != null &&
-    typeof obj.constructor.isBuffer === 'function' &&
-    obj.constructor.isBuffer(obj),
-};