api 5.0.0-beta.3 → 5.0.0

package/dist/cli/codegen/languages/typescript.js

@@ -76,18 +76,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 exports.__esModule = true;
 var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
-var language_1 = __importDefault(require("../language"));
-var logger_1 = __importDefault(require("../../logger"));
-var object_hash_1 = __importDefault(require("object-hash"));
-var ts_morph_1 = require("ts-morph");
-var json_schema_to_typescript_1 = require("json-schema-to-typescript");
-var formatter_1 = require("json-schema-to-typescript/dist/src/formatter");
 var execa_1 = __importDefault(require("execa"));
-// https://www.30secondsofcode.org/js/s/word-wrap
-function wordWrap(str, max) {
-    if (max === void 0) { max = 88; }
-    return str.replace(new RegExp("(?![^\\n]{1,".concat(max, "}$)([^\\n]{1,").concat(max, "})\\s"), 'g'), '$1\n');
-}
+var lodash_setwith_1 = __importDefault(require("lodash.setwith"));
+var ts_morph_1 = require("ts-morph");
+var logger_1 = __importDefault(require("../../logger"));
+var language_1 = __importDefault(require("../language"));
+var util_1 = require("./typescript/util");
 var TSGenerator = /** @class */ (function (_super) {
     __extends(TSGenerator, _super);
     function TSGenerator(spec, specPath, identifier, opts) {
@@ -99,11 +93,16 @@ var TSGenerator = /** @class */ (function (_super) {
             options.compilerTarget = 'esm';
         }
         _this = _super.call(this, spec, specPath, identifier) || this;
+        _this.usesHTTPMethodRangeInterface = false;
         _this.requiredPackages = {
-            'api@beta': {
+            api: {
                 reason: "Required for the `api/dist/core` library that the codegen'd SDK uses for making requests.",
                 url: 'https://npm.im/api'
             },
+            'json-schema-to-ts': {
+                reason: 'Required for TypeScript type handling.',
+                url: 'https://npm.im/json-schema-to-ts'
+            },
             oas: {
                 reason: 'Used within `api/dist/core` and is also loaded for TypeScript types.',
                 url: 'https://npm.im/oas'
@@ -114,24 +113,17 @@ var TSGenerator = /** @class */ (function (_super) {
                 indentationText: ts_morph_1.IndentationText.TwoSpaces,
                 quoteKind: ts_morph_1.QuoteKind.Single
             },
-            compilerOptions: __assign({ declaration: true, outDir: 'dist', resolveJsonModule: true, target: options.compilerTarget === 'cjs' ? ts_morph_1.ScriptTarget.ES5 : ts_morph_1.ScriptTarget.ES2020 }, (options.compilerTarget === 'cjs' ? { esModuleInterop: true } : {}))
+            compilerOptions: __assign({ 
+                // If we're exporting a TypeScript SDK then we don't need to pollute the codegen directory
+                // with unnecessary declaration `.d.ts` files.
+                declaration: options.outputJS, outDir: 'dist', resolveJsonModule: true, target: options.compilerTarget === 'cjs' ? ts_morph_1.ScriptTarget.ES5 : ts_morph_1.ScriptTarget.ES2020 }, (options.compilerTarget === 'cjs' ? { esModuleInterop: true } : {}))
         });
         _this.compilerTarget = options.compilerTarget;
         _this.outputJS = options.outputJS;
         _this.types = new Map();
-        _this.methodGenerics = new Map();
-        _this.schemas = new Map();
+        _this.schemas = {};
         return _this;
     }
-    TSGenerator.formatter = function (content) {
-        return (0, formatter_1.format)(content, {
-            format: true,
-            style: {
-                printWidth: 120,
-                singleQuote: true
-            }
-        });
-    };
     TSGenerator.prototype.installer = function (storage, opts) {
         if (opts === void 0) { opts = {}; }
         return __awaiter(this, void 0, void 0, function () {
@@ -162,7 +154,7 @@ var TSGenerator = /** @class */ (function (_super) {
                         // This will install the installed SDK as a dependency within the current working directory,
                         // adding `@api/<sdk identifier>` as a dependency there so you can load it with
                         // `require('@api/<sdk identifier>)`.
-                        return [2 /*return*/, (0, execa_1["default"])('npm', __spreadArray(__spreadArray([], npmInstall, true), [storage.getIdentifierStorageDir()], false).filter(Boolean)).then(function (res) {
+                        return [2 /*return*/, (0, execa_1["default"])('npm', __spreadArray([], npmInstall, true).filter(Boolean), { cwd: storage.getIdentifierStorageDir() }).then(function (res) {
                                 if (opts.dryRun) {
                                     (opts.logger ? opts.logger : logger_1["default"])(res.command);
                                     (opts.logger ? opts.logger : logger_1["default"])(res.stdout);
@@ -178,300 +170,278 @@ var TSGenerator = /** @class */ (function (_super) {
      */
     TSGenerator.prototype.generator = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var _a, operations, methods, sdkSource;
+            var sdkSource, types;
             var _this = this;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0: return [4 /*yield*/, this.loadOperationsAndMethods()];
-                    case 1:
-                        _a = _b.sent(), operations = _a.operations, methods = _a.methods;
-                        sdkSource = this.project.createSourceFile('index.ts', '');
-                        sdkSource.addImportDeclarations([
-                            { defaultImport: 'Oas', moduleSpecifier: 'oas' },
-                            { defaultImport: 'APICore', moduleSpecifier: 'api/dist/core' },
-                            { defaultImport: 'definition', moduleSpecifier: this.specPath },
-                        ]);
-                        // @todo add TOS, License, info.* to a docblock at the top of the SDK.
-                        this.sdk = sdkSource.addClass({
-                            name: 'SDK'
-                        });
-                        this.sdkExport = sdkSource.addVariableStatement({
-                            declarationKind: ts_morph_1.VariableDeclarationKind.Const,
-                            declarations: [
-                                {
-                                    name: 'createSDK',
-                                    initializer: function (writer) {
-                                        // `ts-morph` doesn't have any way to cleanly create an IFEE.
-                                        writer.writeLine('(() => { return new SDK(); })()');
-                                        return writer;
-                                    }
-                                },
-                            ]
-                        });
-                        /**
-                         * There's an annoying quirk with `ts-morph` where if we set the `createSDK` function to be the
-                         * default export with `isDefaultExport` then when we compile it to an ES5 target for CJS
-                         * environments it'll be exported as `export.default = createSDK`, which when you try to load it
-                         * you'll need to run `require('@api/sdk').default`.
-                         *
-                         * Instead here by plainly creating `createSDK` in the source file and then setting this export
-                         * assignment it'll export the SDK IFEE initializer as `module.exports = createSDK` so people
-                         * can cleanly load their SDK with `require('@api/sdk)`.
-                         *
-                         * A whole lot of debugging went into here to let people not have to worry about `.default`
-                         * messes. I hope it's worth it!
-                         */
-                        if (this.compilerTarget === 'cjs') {
-                            sdkSource.addExportAssignment({
-                                expression: 'createSDK'
-                            });
-                        }
-                        else {
-                            /**
-                             * Because `createSDK` above is an IFEE constant we can't use `setIsDefaultExport` on it due
-                             * to `ts-morph` not having great handling for IFEE's.
-                             *
-                             * If we were to call `setIsDefaultExport` on our IFEE to attempt to compile it as
-                             * `export default createSDK` then `ts-morph` hard crashes with a "Error replacing tree: The
-                             * children of the old and new trees were expected to have the same count" exception due to
-                             * it not being able properly handle IFEE's. It's for that reason that we need to manually
-                             * write a statement expression to set `createSDK` as the default export.
-                             *
-                             * Another quirk that this work avoids is there being an empty `export {};` at the very end
-                             * of our compiled `d.ts` declaration file. I'm not sure why it was being added, and it
-                             * didn't appear to be harming anything, but us manually creating this export statement
-                             * causes it to go away.
-                             *
-                             * Thankfully, fortunately, and curiously, these are all only problems in non-CJS compiled
-                             * targets. ¯\_(ツ)_/¯
-                             */
-                            sdkSource.addStatements('export default createSDK');
-                        }
-                        this.sdk.addProperties([
-                            { name: 'spec', type: 'Oas' },
-                            { name: 'core', type: 'APICore' },
-                            { name: 'authKeys', type: '(number | string)[][]', initializer: '[]' },
-                        ]);
-                        this.sdk.addConstructor({
-                            statements: function (writer) {
-                                writer.writeLine('this.spec = Oas.init(definition);');
-                                writer.write('this.core = new APICore(this.spec, ').quote(_this.userAgent).write(');');
-                                return writer;
+            return __generator(this, function (_a) {
+                sdkSource = this.createSourceFile();
+                if (Object.keys(this.schemas).length) {
+                    this.createSchemasFile();
+                    this.createTypesFile();
+                    types = Array.from(this.types.keys());
+                    types.sort();
+                    sdkSource.addExportDeclarations([
+                        {
+                            isTypeOnly: true,
+                            namedExports: types,
+                            moduleSpecifier: './types'
+                        },
+                    ]);
+                }
+                else {
+                    // If we don't have any schemas then we shouldn't import a `types` file that doesn't exist.
+                    sdkSource
+                        .getImportDeclarations()
+                        .find(function (id) { return id.getText() === "import type * as types from './types';"; })
+                        .remove();
+                }
+                // If this SDK doesn't use the `HTTPMethodRange` interface for handling `2XX` response status
+                // codes then we should remove it from being imported.
+                if (!this.usesHTTPMethodRangeInterface) {
+                    sdkSource
+                        .getImportDeclarations()
+                        .find(function (id) { return id.getText().includes('HTTPMethodRange'); })
+                        .replaceWithText("import type { ConfigOptions, FetchResponse } from 'api/dist/core'");
+                }
+                if (this.outputJS) {
+                    return [2 /*return*/, this.project
+                            .emitToMemory()
+                            .getFiles()
+                            .map(function (sourceFile) {
+                            var _a;
+                            var file = path_1["default"].basename(sourceFile.filePath);
+                            if (file === 'schemas.js' || file === 'types.js') {
+                                // If we're generating a JS SDK then we don't need to generate these two files as the
+                                // user will have `.d.ts` files for them instead.
+                                return {};
                             }
-                        });
-                        // Add our core API methods for controlling auth, servers, and various configurable abilities.
-                        sdkSource.addInterface({
-                            name: 'ConfigOptions',
-                            properties: [
-                                {
-                                    name: 'parseResponse',
-                                    type: 'boolean',
-                                    docs: [
-                                        wordWrap('By default we parse the response based on the `Content-Type` header of the request. You can disable this functionality by negating this option.'),
-                                    ]
-                                },
-                            ]
-                        });
-                        this.sdk.addMethods([
-                            {
-                                name: 'config',
-                                parameters: [{ name: 'config', type: 'ConfigOptions' }],
-                                statements: function (writer) { return writer.writeLine('this.core.setConfig(config);'); },
-                                docs: [
-                                    {
-                                        description: function (writer) {
-                                            return writer.writeLine(wordWrap('Optionally configure various options, such as response parsing, that the SDK allows.'));
-                                        },
-                                        tags: [
-                                            { tagName: 'param', text: 'config Object of supported SDK options and toggles.' },
-                                            {
-                                                tagName: 'param',
-                                                text: 'config.parseResponse If responses are parsed according to its `Content-Type` header.'
-                                            },
-                                        ]
-                                    },
-                                ]
-                            },
+                            var code = (0, util_1.formatter)(sourceFile.text);
+                            if (file === 'index.js' && _this.compilerTarget === 'cjs') {
+                                /**
+                                 * There's an annoying quirk with `ts-morph` where if we're exporting a default export
+                                 * to a CJS environment, it'll export it as `exports.default`. Because we don't want
+                                 * folks in these environments to have to load their SDKs with
+                                 * `require('@api/sdk').default` we're overriding that here to change it to being the
+                                 * module exports.
+                                 *
+                                 * `ts-morph` unfortunately doesn't give us any options for programatically doing this
+                                 * so we need to resort to modifying the emitted JS code.
+                                 */
+                                code = code
+                                    .replace(/Object\.defineProperty\(exports, '__esModule', { value: true }\);\n/, '')
+                                    .replace('exports.default = createSDK;', 'module.exports = createSDK;');
+                            }
+                            return _a = {},
+                                _a[file] = code,
+                                _a;
+                        })
+                            .reduce(function (prev, next) { return Object.assign(prev, next); })];
+                }
+                return [2 /*return*/, __spreadArray(__spreadArray([], this.project.getSourceFiles().map(function (sourceFile) {
+                        var _a;
+                        return (_a = {},
+                            _a[sourceFile.getBaseName()] = (0, util_1.formatter)(sourceFile.getFullText()),
+                            _a);
+                    }), true), this.project
+                        .emitToMemory({ emitOnlyDtsFiles: true })
+                        .getFiles()
+                        .map(function (sourceFile) {
+                        var _a;
+                        return (_a = {},
+                            _a[path_1["default"].basename(sourceFile.filePath)] = (0, util_1.formatter)(sourceFile.text),
+                            _a);
+                    }), true).reduce(function (prev, next) { return Object.assign(prev, next); })];
+            });
+        });
+    };
+    /**
+     * Create our main SDK source file.
+     *
+     */
+    TSGenerator.prototype.createSourceFile = function () {
+        var _this = this;
+        var operations = this.loadOperationsAndMethods().operations;
+        var sourceFile = this.project.createSourceFile('index.ts', '');
+        sourceFile.addImportDeclarations([
+            // This import will be automatically removed later if the SDK ends up not having any types.
+            { defaultImport: 'type * as types', moduleSpecifier: './types' },
+            {
+                // `HTTPMethodRange` will be conditionally removed later if it ends up not being used.
+                defaultImport: 'type { ConfigOptions, FetchResponse, HTTPMethodRange }',
+                moduleSpecifier: 'api/dist/core'
+            },
+            { defaultImport: 'Oas', moduleSpecifier: 'oas' },
+            { defaultImport: 'APICore', moduleSpecifier: 'api/dist/core' },
+            { defaultImport: 'definition', moduleSpecifier: this.specPath },
+        ]);
+        // @todo add TOS, License, info.* to a docblock at the top of the SDK.
+        this.sdk = sourceFile.addClass({
+            name: 'SDK',
+            properties: [
+                { name: 'spec', type: 'Oas' },
+                { name: 'core', type: 'APICore' },
+            ]
+        });
+        this.sdk.addConstructor({
+            statements: function (writer) {
+                writer.writeLine('this.spec = Oas.init(definition);');
+                writer.write('this.core = new APICore(this.spec, ').quote(_this.userAgent).write(');');
+                return writer;
+            }
+        });
+        // Add our core API methods for controlling auth, servers, and various configurable abilities.
+        this.sdk.addMethods([
+            {
+                name: 'config',
+                parameters: [{ name: 'config', type: 'ConfigOptions' }],
+                statements: function (writer) { return writer.writeLine('this.core.setConfig(config);'); },
+                docs: [
+                    {
+                        description: function (writer) {
+                            return writer.writeLine((0, util_1.wordWrap)('Optionally configure various options that the SDK allows.'));
+                        },
+                        tags: [
+                            { tagName: 'param', text: 'config Object of supported SDK options and toggles.' },
                             {
-                                name: 'auth',
-                                parameters: [{ name: '...values', type: 'string[] | number[]' }],
-                                statements: function (writer) {
-                                    writer.writeLine('this.core.setAuth(...values);');
-                                    writer.writeLine('return this;');
-                                    return writer;
-                                },
-                                docs: [
-                                    {
-                                        description: function (writer) {
-                                            return writer.writeLine(wordWrap("If the API you're using requires authentication you can supply the required credentials through this method and the library will magically determine how they should be used within your API request.\n\nWith the exception of OpenID and MutualTLS, it supports all forms of authentication supported by the OpenAPI specification.\n\n@example <caption>HTTP Basic auth</caption>\nsdk.auth('username', 'password');\n\n@example <caption>Bearer tokens (HTTP or OAuth 2)</caption>\nsdk.auth('myBearerToken');\n\n@example <caption>API Keys</caption>\nsdk.auth('myApiKey');"));
-                                        },
-                                        tags: [
-                                            { tagName: 'see', text: '{@link https://spec.openapis.org/oas/v3.0.3#fixed-fields-22}' },
-                                            { tagName: 'see', text: '{@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-22}' },
-                                            {
-                                                tagName: 'param',
-                                                text: 'values Your auth credentials for the API; can specify up to two strings or numbers.'
-                                            },
-                                        ]
-                                    },
-                                ]
+                                tagName: 'param',
+                                text: (0, util_1.wordWrap)('config.timeout Override the default `fetch` request timeout of 30 seconds. This number should be represented in milliseconds.')
                             },
+                        ]
+                    },
+                ]
+            },
+            {
+                name: 'auth',
+                parameters: [{ name: '...values', type: 'string[] | number[]' }],
+                statements: function (writer) {
+                    writer.writeLine('this.core.setAuth(...values);');
+                    writer.writeLine('return this;');
+                    return writer;
+                },
+                docs: [
+                    {
+                        description: function (writer) {
+                            return writer.writeLine((0, util_1.wordWrap)("If the API you're using requires authentication you can supply the required credentials through this method and the library will magically determine how they should be used within your API request.\n\nWith the exception of OpenID and MutualTLS, it supports all forms of authentication supported by the OpenAPI specification.\n\n@example <caption>HTTP Basic auth</caption>\nsdk.auth('username', 'password');\n\n@example <caption>Bearer tokens (HTTP or OAuth 2)</caption>\nsdk.auth('myBearerToken');\n\n@example <caption>API Keys</caption>\nsdk.auth('myApiKey');"));
+                        },
+                        tags: [
+                            { tagName: 'see', text: '{@link https://spec.openapis.org/oas/v3.0.3#fixed-fields-22}' },
+                            { tagName: 'see', text: '{@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-22}' },
                             {
-                                name: 'server',
-                                parameters: [
-                                    { name: 'url', type: 'string' },
-                                    { name: 'variables', initializer: '{}' },
-                                ],
-                                statements: function (writer) { return writer.writeLine('this.core.setServer(url, variables);'); },
-                                docs: [
-                                    {
-                                        description: function (writer) {
-                                            return writer.writeLine(wordWrap("If the API you're using offers alternate server URLs, and server variables, you can tell the SDK which one to use with this method. To use it you can supply either one of the server URLs that are contained within the OpenAPI definition (along with any server variables), or you can pass it a fully qualified URL to use (that may or may not exist within the OpenAPI definition).\n\n@example <caption>Server URL with server variables</caption>\nsdk.server('https://{region}.api.example.com/{basePath}', {\n  name: 'eu',\n  basePath: 'v14',\n});\n\n@example <caption>Fully qualified server URL</caption>\nsdk.server('https://eu.api.example.com/v14');"));
-                                        },
-                                        tags: [
-                                            { tagName: 'param', text: 'url Server URL' },
-                                            { tagName: 'param', text: 'variables An object of variables to replace into the server URL.' },
-                                        ]
-                                    },
-                                ]
+                                tagName: 'param',
+                                text: 'values Your auth credentials for the API; can specify up to two strings or numbers.'
                             },
-                        ]);
-                        // Add all common method accessors into the SDK.
-                        Array.from(methods).forEach(function (method) { return _this.createGenericMethodAccessor(method); });
-                        // Add all available operation ID accessors into the SDK.
-                        Object.entries(operations).forEach(function (_a) {
-                            var operationId = _a[0], data = _a[1];
-                            _this.createOperationAccessor(data.operation, operationId, data.types.params, data.types.responses);
-                        });
-                        // @todo should all of these isolated into their own file outside of the main sdk class file?
-                        // Add all known types that we're using into the SDK.
-                        Array.from(this.types.values()).forEach(function (exp) {
+                        ]
+                    },
+                ]
+            },
+            {
+                name: 'server',
+                parameters: [
+                    { name: 'url', type: 'string' },
+                    { name: 'variables', initializer: '{}' },
+                ],
+                statements: function (writer) { return writer.writeLine('this.core.setServer(url, variables);'); },
+                docs: [
+                    {
+                        description: function (writer) {
+                            return writer.writeLine((0, util_1.wordWrap)("If the API you're using offers alternate server URLs, and server variables, you can tell the SDK which one to use with this method. To use it you can supply either one of the server URLs that are contained within the OpenAPI definition (along with any server variables), or you can pass it a fully qualified URL to use (that may or may not exist within the OpenAPI definition).\n\n@example <caption>Server URL with server variables</caption>\nsdk.server('https://{region}.api.example.com/{basePath}', {\n  name: 'eu',\n  basePath: 'v14',\n});\n\n@example <caption>Fully qualified server URL</caption>\nsdk.server('https://eu.api.example.com/v14');"));
+                        },
+                        tags: [
+                            { tagName: 'param', text: 'url Server URL' },
+                            { tagName: 'param', text: 'variables An object of variables to replace into the server URL.' },
+                        ]
+                    },
+                ]
+            },
+        ]);
+        // Add all available operation ID accessors into the SDK.
+        Object.entries(operations).forEach(function (_a) {
+            var operationId = _a[0], data = _a[1];
+            _this.createOperationAccessor(data.operation, operationId, data.types.params, data.types.responses);
+        });
+        // Export our SDK into the source file.
+        sourceFile.addVariableStatement({
+            declarationKind: ts_morph_1.VariableDeclarationKind.Const,
+            declarations: [
+                {
+                    name: 'createSDK',
+                    initializer: function (writer) {
+                        // `ts-morph` doesn't have any way to cleanly create an IFEE.
+                        writer.writeLine('(() => { return new SDK(); })()');
+                        return writer;
+                    }
+                },
+            ]
+        });
+        sourceFile.addExportAssignment({ isExportEquals: false, expression: 'createSDK' });
+        return sourceFile;
+    };
+    /**
+     * Create our main schemas file. This is where all of the JSON Schema that our TypeScript typing
+     * infrastructure sources its data from. Without this there are no types.
+     *
+     */
+    TSGenerator.prototype.createSchemasFile = function () {
+        var sourceFile = this.project.createSourceFile('schemas.ts', '');
+        var sortedSchemas = new Map(Array.from(Object.entries(this.schemas)).sort());
+        Array.from(sortedSchemas).forEach(function (_a) {
+            var schemaName = _a[0], schema = _a[1];
+            sourceFile.addVariableStatement({
+                declarationKind: ts_morph_1.VariableDeclarationKind.Const,
+                declarations: [
+                    {
+                        name: schemaName,
+                        initializer: function (writer) {
                             /**
-                             * When `ts-morph` compiles declaration files when we're targeting CJS environments it creates
-                             * the default export as `export = _default` instead of `export default const _default`. This
-                             * causes TS to throw a TS2309 error for "An export assignment cannot be used in a module
-                             * with other exported elements" because our types and interfaces are also being exported and
-                             * the `export =` overrides those.
-                             *
-                             * Fixing this is, to be frank, a fucking HARD problem for a couple reasons:
+                             * This is the conversion prefix that we add to all `$ref` pointers we find in
+                             * generated JSON Schema.
                              *
-                             *  1. Our JSON Schema types and interfaces are coming from `json-schema-to-typescript` and
-                             *    that library exports its data a raw string containing multiple types and interfaces.
-                             *    The only way we're able to capture and use them in our codegenerated SDK is because
-                             *    we're ingesting that string into `ts-morph` and then using its APIs to extract exported
-                             *    declarations (which are still strings) and then they're re-inserted into our main
-                             *    source file here.
-                             *  2. Though `ts-morph` has APIs for adding type aliases and interfaces to a source file what
-                             *    it doesn't have is the ability to pass in a string, or a `Writer` class that exposes,
-                             *    to write raw strings to a type or an interface. If it did we'd be able to replace this
-                             *    `addStatements` call with an `addTypeAlias` and `addInterface` call for each of our
-                             *    JSON Schema schemas that we've got along with an `isExported` flag for `ts-morph` to
-                             *    export it.
+                             * Because the pointer name is a string we want to have it reference the schema
+                             * constant we're adding into the codegen'd schema file. As there's no way, not even
+                             * using `eval()` in this case, to convert a string to a constant we're prefixing
+                             * them with this so we can later remove it and rewrite the value to a literal.
+                             * eg. `'Pet'` becomes `Pet`.
                              *
-                             * Because neither of these are solvable problems right now we're instead opting to **not**
-                             * export types and interfaces from these SDKs. This isn't a great solution because it
-                             * /slightly/ reduces the usability of the TS codegen functionality but in order for the TS
-                             * declaration files that we generate to be valid this is the only option that we've got.
-                             *
-                             * However, that said, if somebody needs an interface or type exported they can export it
-                             * themselves in the SDK code that we compile for them.
-                             *
-                             * @fixme
+                             * And because our TypeScript type name generator properly ignores `:`, this is safe
+                             * to prepend to all generated type names.
                              */
-                            sdkSource.addStatements(
-                            // All expressions coming out of `json-schema-to-typescript` are exported so by popping this
-                            // off we'll just be inserting plain interfaces and types into the SDK source.
-                            exp.substring('export '.length));
-                        });
-                        if (this.outputJS) {
-                            return [2 /*return*/, this.project
-                                    .emitToMemory()
-                                    .getFiles()
-                                    .map(function (sourceFile) {
-                                    var _a;
-                                    return (_a = {},
-                                        _a[path_1["default"].basename(sourceFile.filePath)] = TSGenerator.formatter(sourceFile.text),
-                                        _a);
-                                })
-                                    .reduce(function (prev, next) { return Object.assign(prev, next); })];
+                            var str = JSON.stringify(schema);
+                            str = str.replace(/"::convert::([a-zA-Z_$\\d]*)"/g, '$1');
+                            writer.writeLine("".concat(str, " as const"));
+                            return writer;
                         }
-                        return [2 /*return*/, __spreadArray(__spreadArray([], this.project.getSourceFiles().map(function (sourceFile) {
-                                var _a;
-                                return (_a = {},
-                                    _a[sourceFile.getBaseName()] = TSGenerator.formatter(sourceFile.getFullText()),
-                                    _a);
-                            }), true), this.project
-                                .emitToMemory({ emitOnlyDtsFiles: true })
-                                .getFiles()
-                                .map(function (sourceFile) {
-                                var _a;
-                                return (_a = {},
-                                    _a[path_1["default"].basename(sourceFile.filePath)] = TSGenerator.formatter(sourceFile.text),
-                                    _a);
-                            }), true).reduce(function (prev, next) { return Object.assign(prev, next); })];
-                }
+                    },
+                ]
             });
         });
+        sourceFile.addStatements("export { ".concat(Array.from(sortedSchemas.keys()).join(', '), " }"));
+        return sourceFile;
     };
     /**
-     * Create a generic HTTP method accessor on the SDK.
+     * Create our main types file. This sources its data from the JSON Schema `schemas.ts` file and
+     * will re-export types to be used in TypeScript implementations and IDE intellisense. This
+     * typing work is functional with the `json-schema-to-ts` library.
      *
-     * @param method
+     * @see {@link https://npm.im/json-schema-to-ts}
      */
-    TSGenerator.prototype.createGenericMethodAccessor = function (method) {
-        var parameters = [{ name: 'path', type: 'string' }];
-        var docblock = {
-            description: function (writer) {
-                writer.writeLine("Access any ".concat(method.toUpperCase(), " endpoint on your API."));
-                return writer;
-            },
-            tags: [{ tagName: 'param', text: 'path API path to make a request against.' }]
-        };
-        // Method generic body + metadata parameters are always optional.
-        if (method !== 'get') {
-            parameters.push({ name: 'body', type: 'unknown', hasQuestionToken: true });
-            docblock.tags.push({ tagName: 'param', text: 'body Request body payload data.' });
-        }
-        parameters.push({ name: 'metadata', type: 'Record<string, unknown>', hasQuestionToken: true });
-        docblock.tags.push({
-            tagName: 'param',
-            text: 'metadata Object containing all path, query, header, and cookie parameters to supply.'
+    TSGenerator.prototype.createTypesFile = function () {
+        var sourceFile = this.project.createSourceFile('types.ts', '');
+        sourceFile.addImportDeclarations([
+            { defaultImport: 'type { FromSchema }', moduleSpecifier: 'json-schema-to-ts' },
+            { defaultImport: '* as schemas', moduleSpecifier: './schemas' },
+        ]);
+        Array.from(new Map(Array.from(this.types.entries()).sort())).forEach(function (_a) {
+            var typeName = _a[0], typeExpression = _a[1];
+            sourceFile.addTypeAlias({ isExported: true, name: typeName, type: typeExpression });
         });
-        this.methodGenerics.set(method, this.sdk.addMethod({
-            name: method,
-            returnType: 'Promise<T>',
-            parameters: parameters,
-            typeParameters: ['T = unknown'],
-            docs: [docblock],
-            statements: function (writer) {
-                /**
-                 * @example return this.core.fetch(path, 'get', body, metadata);
-                 * @example return this.core.fetch(path, 'get', metadata);
-                 */
-                var fetchStmt = writer.write('return this.core.fetch(path, ').quote(method).write(', ');
-                var fetchArgs = parameters.slice(1).map(function (p) { return p.name; });
-                fetchArgs.forEach(function (arg, i) {
-                    fetchStmt.write(arg);
-                    if (fetchArgs.length > 1 && i !== fetchArgs.length) {
-                        fetchStmt.write(', ');
-                    }
-                });
-                fetchStmt.write(');');
-                return fetchStmt;
-            }
-        }));
+        return sourceFile;
     };
     /**
      * Create operation accessors on the SDK.
      *
-     * @param operation
-     * @param operationId
-     * @param paramTypes
-     * @param responseTypes
      */
     TSGenerator.prototype.createOperationAccessor = function (operation, operationId, paramTypes, responseTypes) {
         var _this = this;
-        var docblock = { tags: [] };
+        var docblock = {};
         var summary = operation.getSummary();
         var description = operation.getDescription();
         if (summary || description) {
@@ -480,16 +450,16 @@ var TSGenerator = /** @class */ (function (_super) {
             // what we surface the main docblock description.
             docblock.description = function (writer) {
                 if (description) {
-                    writer.writeLine(description);
+                    writer.writeLine((0, util_1.docblockEscape)((0, util_1.wordWrap)(description)));
                 }
                 else if (summary) {
-                    writer.writeLine(summary);
+                    writer.writeLine((0, util_1.docblockEscape)((0, util_1.wordWrap)(summary)));
                 }
                 writer.newLineIfLastNot();
                 return writer;
             };
             if (summary && description) {
-                docblock.tags.push({ tagName: 'summary', text: summary });
+                docblock.tags = [{ tagName: 'summary', text: (0, util_1.docblockEscape)((0, util_1.wordWrap)(summary)) }];
             }
         }
         var hasOptionalBody = false;
@@ -502,9 +472,7 @@ var TSGenerator = /** @class */ (function (_super) {
                 hasOptionalBody = !operation.hasRequiredRequestBody();
                 parameters.body = {
                     name: 'body',
-                    type: paramTypes.body
-                        ? this.schemas.get(paramTypes.body).tsType
-                        : this.schemas.get(paramTypes.formData).tsType,
+                    type: paramTypes.body ? paramTypes.body : paramTypes.formData,
                     hasQuestionToken: hasOptionalBody
                 };
             }
@@ -512,27 +480,37 @@ var TSGenerator = /** @class */ (function (_super) {
                 hasOptionalMetadata = !operation.hasRequiredParameters();
                 parameters.metadata = {
                     name: 'metadata',
-                    type: this.schemas.get(paramTypes.metadata).tsType,
+                    type: paramTypes.metadata,
                     hasQuestionToken: hasOptionalMetadata
                 };
             }
         }
-        var returnType = 'Promise<T>';
-        var typeParameters = null;
+        var returnType = 'Promise<FetchResponse<number, unknown>>';
         if (responseTypes) {
-            returnType = "Promise<".concat(Object.values(responseTypes)
-                .map(function (hash) { return _this.schemas.get(hash).tsType; })
+            returnType = "Promise<".concat(Object.entries(responseTypes)
+                .map(function (_a) {
+                var status = _a[0], responseType = _a[1];
+                if (status.toLowerCase() === 'default') {
+                    return "FetchResponse<number, ".concat(responseType, ">");
+                }
+                else if (status.length === 3 && status.toUpperCase().endsWith('XX')) {
+                    var statusPrefix = status.slice(0, 1);
+                    if (!Number.isInteger(Number(statusPrefix))) {
+                        // If this matches the `_XX` format, but it isn't `{number}XX` then we can't handle
+                        // it and should instead fall back to treating it as an unknown number.
+                        return "FetchResponse<number, ".concat(responseType, ">");
+                    }
+                    _this.usesHTTPMethodRangeInterface = true;
+                    return "FetchResponse<HTTPMethodRange<".concat(statusPrefix, "00, ").concat(statusPrefix, "99>, ").concat(responseType, ">");
+                }
+                return "FetchResponse<".concat(status, ", ").concat(responseType, ">");
+            })
                 .join(' | '), ">");
         }
-        else {
-            // We should only add the `<T>` method typing if we don't have any response types present.
-            typeParameters = ['T = unknown'];
-        }
         var operationIdAccessor = this.sdk.addMethod({
             name: operationId,
-            typeParameters: typeParameters,
             returnType: returnType,
-            docs: docblock ? [docblock] : null,
+            docs: Object.keys(docblock).length ? [docblock] : null,
             statements: function (writer) {
                 /**
                  * @example return this.core.fetch('/pet/findByStatus', 'get', body, metadata);
@@ -569,20 +547,18 @@ var TSGenerator = /** @class */ (function (_super) {
         if (shouldAddAltTypedOverloads) {
             // Create an overload that has both `body` and `metadata` parameters as required.
             operationIdAccessor.addOverload({
-                typeParameters: typeParameters,
                 parameters: [
                     __assign(__assign({}, parameters.body), { hasQuestionToken: false }),
                     __assign(__assign({}, parameters.metadata), { hasQuestionToken: false }),
                 ],
                 returnType: returnType,
-                docs: docblock ? [docblock] : null
+                docs: Object.keys(docblock).length ? [docblock] : null
             });
             // Create an overload that just has a single `metadata` parameter.
             operationIdAccessor.addOverload({
-                typeParameters: typeParameters,
                 parameters: [__assign({}, parameters.metadata)],
                 returnType: returnType,
-                docs: docblock ? [docblock] : null
+                docs: Object.keys(docblock).length ? [docblock] : null
             });
             // Create an overload that has both `body` and `metadata` parameters as optional. Even though
             // our `metadata` parameter is actually required for this operation this is the only way we're
@@ -592,88 +568,18 @@ var TSGenerator = /** @class */ (function (_super) {
             // see if what the user is supplying is `metadata` or `body` content when they supply one or
             // both.
             operationIdAccessor.addParameters([
-                __assign(__assign({}, parameters.body), { hasQuestionToken: true }),
+                __assign(__assign({}, parameters.body), { 
+                    // Overloads have to be the most distilled version of the method so that's why we need to
+                    // type `body` as either `body` or `metadata`. If we didn't do this, if `body` was a JSON
+                    // Schema type that didn't allow `additionalProperties` then the implementation overload
+                    // would throw type errors.
+                    type: "".concat(parameters.body.type, " | ").concat(parameters.metadata.type), hasQuestionToken: true }),
                 __assign(__assign({}, parameters.metadata), { hasQuestionToken: true }),
             ]);
         }
         else {
             operationIdAccessor.addParameters(Object.values(parameters));
         }
-        // Add a typed generic HTTP method overload for this operation.
-        if (this.methodGenerics.has(operation.method)) {
-            // If we created alternate overloads for the operation accessor then we need to do the same
-            // for its generic HTTP counterpart.
-            if (shouldAddAltTypedOverloads) {
-                // Create an overload that has both `body` and `metadata` parameters as required.
-                this.methodGenerics.get(operation.method).addOverload({
-                    typeParameters: typeParameters,
-                    parameters: [
-                        { name: 'path', type: "'".concat(operation.path, "'") },
-                        __assign(__assign({}, parameters.body), { hasQuestionToken: false }),
-                        __assign(__assign({}, parameters.metadata), { hasQuestionToken: false }),
-                    ],
-                    returnType: returnType,
-                    docs: docblock ? [docblock] : null
-                });
-                // Create an overload that just has a single `metadata` parameter.
-                this.methodGenerics.get(operation.method).addOverload({
-                    typeParameters: typeParameters,
-                    parameters: [{ name: 'path', type: "'".concat(operation.path, "'") }, parameters.metadata],
-                    returnType: returnType,
-                    docs: docblock ? [docblock] : null
-                });
-            }
-            else {
-                this.methodGenerics.get(operation.method).addOverload({
-                    typeParameters: responseTypes ? null : ['T = unknown'],
-                    parameters: __spreadArray([{ name: 'path', type: "'".concat(operation.path, "'") }], Object.values(parameters), true),
-                    returnType: returnType,
-                    docs: docblock ? [docblock] : null
-                });
-            }
-        }
-    };
-    /**
-     * Convert a JSON Schema object into a readily available TypeScript type or interface along with
-     * any `$ref` pointers that are in use and turn those into TS types too.
-     *
-     * Under the hood this uses https://npm.im/json-schema-to-typescript for all composition and
-     * conversion.
-     *
-     * @param schema
-     * @param name
-     */
-    TSGenerator.prototype.convertJSONSchemaToTypescript = function (schema, name) {
-        return __awaiter(this, void 0, void 0, function () {
-            var ts, primaryType, tempProject, declarations;
-            var _this = this;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, (0, json_schema_to_typescript_1.compile)(schema, name, {
-                            bannerComment: '',
-                            // Running Prettier here for every JSON Schema object we're generating is way too slow so
-                            // we're instead running it at the very end after we've constructed the SDK.
-                            format: false
-                        })];
-                    case 1:
-                        ts = _a.sent();
-                        tempProject = this.project.createSourceFile("".concat(name, ".types.tmp.ts"), ts);
-                        declarations = tempProject.getExportedDeclarations();
-                        Array.from(declarations.keys()).forEach(function (declarationName) {
-                            if (!primaryType) {
-                                primaryType = declarationName;
-                            }
-                            declarations.get(declarationName).forEach(function (declaration) {
-                                _this.types.set(declarationName, declaration.getText());
-                            });
-                        });
-                        this.project.removeSourceFile(tempProject);
-                        return [2 /*return*/, {
-                                primaryType: primaryType
-                            }];
-                }
-            });
-        });
     };
     /**
      * Scour through the current OpenAPI definition and compile a store of every operation, along
@@ -682,78 +588,59 @@ var TSGenerator = /** @class */ (function (_super) {
      *
      */
     TSGenerator.prototype.loadOperationsAndMethods = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var operations, methods;
-            var _this = this;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        operations = {};
-                        methods = new Set();
-                        // Prepare all of the schemas that we need to process for every operation within this API
-                        // definition.
-                        Object.entries(this.spec.getPaths()).forEach(function (_a) {
-                            var ops = _a[1];
-                            Object.entries(ops).forEach(function (_a) {
-                                var method = _a[0], operation = _a[1];
-                                methods.add(method);
-                                var operationId = operation.getOperationId({
-                                    // This `camelCase` option will clean up any weird characters that might be present in
-                                    // the `operationId` so as we don't break TS compilation with an invalid method accessor.
-                                    camelCase: true
-                                });
-                                var params = _this.prepareParameterTypesForOperation(operation, operationId);
-                                var responses = _this.prepareResponseTypesForOperation(operation, operationId);
-                                if (operation.hasOperationId()) {
-                                    operations[operationId] = {
-                                        types: {
-                                            params: params,
-                                            responses: responses
-                                        },
-                                        operation: operation
-                                    };
-                                }
-                            });
-                        });
-                        // Run through and convert every schema we need to use into TS types.
-                        return [4 /*yield*/, Promise.all(Array.from(this.schemas.entries()).map(function (_a) {
-                                var hash = _a[0], _b = _a[1], schema = _b.schema, schemaName = _b.name;
-                                return __awaiter(_this, void 0, void 0, function () {
-                                    var ts;
-                                    return __generator(this, function (_c) {
-                                        switch (_c.label) {
-                                            case 0: return [4 /*yield*/, this.convertJSONSchemaToTypescript(schema, schemaName)];
-                                            case 1:
-                                                ts = _c.sent();
-                                                this.schemas.set(hash, __assign(__assign({}, this.schemas.get(hash)), { tsType: ts.primaryType }));
-                                                return [2 /*return*/];
-                                        }
-                                    });
-                                });
-                            }))];
-                    case 1:
-                        // Run through and convert every schema we need to use into TS types.
-                        _a.sent();
-                        return [2 /*return*/, {
-                                operations: operations,
-                                methods: methods
-                            }];
-                }
+        var _this = this;
+        var operations = {};
+        var methods = new Set();
+        // Prepare all of the schemas that we need to process for every operation within this API
+        // definition.
+        Object.entries(this.spec.getPaths()).forEach(function (_a) {
+            var ops = _a[1];
+            Object.entries(ops).forEach(function (_a) {
+                var method = _a[0], operation = _a[1];
+                methods.add(method);
+                var operationId = operation.getOperationId({
+                    // This `camelCase` option will clean up any weird characters that might be present in
+                    // the `operationId` so as we don't break TS compilation with an invalid method accessor.
+                    camelCase: true
+                });
+                operations[operationId] = {
+                    types: {
+                        params: _this.prepareParameterTypesForOperation(operation, operationId),
+                        responses: _this.prepareResponseTypesForOperation(operation, operationId)
+                    },
+                    operation: operation
+                };
             });
         });
+        if (!Object.keys(operations).length) {
+            throw new Error('Sorry, this OpenAPI definition does not have any operation paths to generate an SDK for.');
+        }
+        return {
+            operations: operations,
+            methods: methods
+        };
     };
     /**
      * Compile the parameter (path, query, cookie, and header) schemas for an API operation into
      * usable TypeScript types.
      *
-     * @param operation
-     * @param operationId
      */
     TSGenerator.prototype.prepareParameterTypesForOperation = function (operation, operationId) {
         var _this = this;
-        var schemas = operation.getParametersAsJsonSchema({
+        var schemas = operation.getParametersAsJSONSchema({
+            includeDiscriminatorMappingRefs: false,
             mergeIntoBodyAndMetadata: true,
-            retainDeprecatedProperties: true
+            retainDeprecatedProperties: true,
+            transformer: function (s) {
+                // As our schemas are dereferenced in the `oas` library we don't want to pollute our
+                // codegen'd schemas file with duplicate schemas.
+                if ('x-readme-ref-name' in s) {
+                    var typeName = (0, util_1.generateTypeName)(s['x-readme-ref-name']);
+                    _this.addSchemaToExport(s, typeName, typeName);
+                    return "::convert::".concat(typeName);
+                }
+                return s;
+            }
         });
         if (!schemas || !schemas.length) {
             return false;
@@ -768,19 +655,20 @@ var TSGenerator = /** @class */ (function (_super) {
             .map(function (_a) {
             var _b;
             var paramType = _a[0], schema = _a[1];
-            var schemaName = schema['x-readme-ref-name'] || "".concat(operationId, "_").concat(paramType, "_param");
-            var hash = (0, object_hash_1["default"])({
-                name: schemaName,
-                schema: schema
-            });
-            if (!_this.schemas.has(hash)) {
-                _this.schemas.set(hash, {
-                    schema: schema,
-                    name: schemaName
-                });
+            var typeName;
+            if (typeof schema === 'string' && schema.startsWith('::convert::')) {
+                // If this schema is a string and has our conversion prefix then we've already created
+                // a type for it.
+                typeName = schema.replace('::convert::', '');
+            }
+            else {
+                typeName = (0, util_1.generateTypeName)(operationId, paramType, 'param');
+                _this.addSchemaToExport(schema, typeName, "".concat((0, util_1.generateTypeName)(operationId), ".").concat(paramType));
             }
             return _b = {},
-                _b[paramType] = hash,
+                // Types are prefixed with `types.` because that's how we're importing them from
+                // `types.d.ts`.
+                _b[paramType] = "types.".concat(typeName),
                 _b;
         })
             .reduce(function (prev, next) { return Object.assign(prev, next); }, {});
@@ -788,9 +676,6 @@ var TSGenerator = /** @class */ (function (_super) {
     /**
      * Compile the response schemas for an API operation into usable TypeScript types.
      *
-     * @todo what does this do for a spec that has no responses?
-     * @param operation
-     * @param operationId
      */
     TSGenerator.prototype.prepareResponseTypesForOperation = function (operation, operationId) {
         var _this = this;
@@ -801,7 +686,19 @@ var TSGenerator = /** @class */ (function (_super) {
         var schemas = responseStatusCodes
             .map(function (status) {
             var _a;
-            var schema = operation.getResponseAsJsonSchema(status);
+            var schema = operation.getResponseAsJSONSchema(status, {
+                includeDiscriminatorMappingRefs: false,
+                transformer: function (s) {
+                    // As our schemas are dereferenced in the `oas` library we don't want to pollute our
+                    // codegen'd schemas file with duplicate schemas.
+                    if ('x-readme-ref-name' in s) {
+                        var typeName = (0, util_1.generateTypeName)(s['x-readme-ref-name']);
+                        _this.addSchemaToExport(s, typeName, "".concat(typeName));
+                        return "::convert::".concat(typeName);
+                    }
+                    return s;
+                }
+            });
             if (!schema) {
                 return false;
             }
@@ -814,24 +711,39 @@ var TSGenerator = /** @class */ (function (_super) {
             .map(function (_a) {
             var _b;
             var status = _a[0], schema = _a[1].schema;
-            var schemaName = schema['x-readme-ref-name'] || "".concat(operationId, "_Response_").concat(status);
-            var hash = (0, object_hash_1["default"])({
-                name: schemaName,
-                schema: schema
-            });
-            if (!_this.schemas.has(hash)) {
-                _this.schemas.set(hash, {
-                    schema: schema,
-                    name: schemaName
-                });
+            var typeName;
+            if (typeof schema === 'string' && schema.startsWith('::convert::')) {
+                // If this schema is a string and has our conversion prefix then we've already created
+                // a type for it.
+                typeName = schema.replace('::convert::', '');
+            }
+            else {
+                typeName = (0, util_1.generateTypeName)(operationId, 'response', status);
+                // Because `status` will usually be a number here we need to set the pointer for it
+                // within  an `[]` as if we do `FromSchema<typeof schemas.operation.response.200>`,
+                // TypeScript will throw a compilation error.
+                _this.addSchemaToExport(schema, typeName, "".concat((0, util_1.generateTypeName)(operationId), ".response['").concat(status, "']"));
             }
             return _b = {},
-                _b[status] = hash,
+                // Types are prefixed with `types.` because that's how we're importing them from
+                // `types.d.ts`.
+                _b[status] = "types.".concat(typeName),
                 _b;
         })
             .reduce(function (prev, next) { return Object.assign(prev, next); }, {});
         return Object.keys(res).length ? res : undefined;
     };
+    /**
+     * Add a given schema into our schema dataset that we'll be be exporting as types.
+     *
+     */
+    TSGenerator.prototype.addSchemaToExport = function (schema, typeName, pointer) {
+        if (this.types.has(typeName)) {
+            return;
+        }
+        (0, lodash_setwith_1["default"])(this.schemas, pointer, schema, Object);
+        this.types.set(typeName, "FromSchema<typeof schemas.".concat(pointer, ">"));
+    };
     return TSGenerator;
 }(language_1["default"]));
 exports["default"] = TSGenerator;