api 5.0.0-beta.3 → 5.0.1

package/src/cli/codegen/languages/typescript.ts

@@ -1,28 +1,21 @@
-import type Oas from 'oas';
-import type { Operation } from 'oas';
-import type { HttpMethods, JSONSchema, SchemaObject } from 'oas/dist/rmoas.types';
-import type {
-  ClassDeclaration,
-  JSDocStructure,
-  MethodDeclaration,
-  OptionalKind,
-  ParameterDeclarationStructure,
-  TypeParameterDeclarationStructure,
-  VariableStatement,
-} from 'ts-morph';
-import type { Options as JSONSchemaToTypescriptOptions } from 'json-schema-to-typescript';
 import type Storage from '../../storage';
 import type { InstallerOptions } from '../language';
+import type Oas from 'oas';
+import type { Operation } from 'oas';
+import type { HttpMethods, SchemaObject } from 'oas/dist/rmoas.types';
+import type { ClassDeclaration, JSDocStructure, OptionalKind, ParameterDeclarationStructure } from 'ts-morph';
 
 import fs from 'fs';
 import path from 'path';
-import CodeGeneratorLanguage from '../language';
-import logger from '../../logger';
-import objectHash from 'object-hash';
-import { IndentationText, Project, QuoteKind, ScriptTarget, VariableDeclarationKind } from 'ts-morph';
-import { compile } from 'json-schema-to-typescript';
-import { format as prettier } from 'json-schema-to-typescript/dist/src/formatter';
+
 import execa from 'execa';
+import setWith from 'lodash.setwith';
+import { IndentationText, Project, QuoteKind, ScriptTarget, VariableDeclarationKind } from 'ts-morph';
+
+import logger from '../../logger';
+import CodeGeneratorLanguage from '../language';
+
+import { docblockEscape, formatter, generateTypeName, wordWrap } from './typescript/util';
 
 export type TSGeneratorOptions = {
   outputJS?: boolean;
@@ -37,11 +30,6 @@ type OperationTypeHousing = {
   operation: Operation;
 };
 
-// https://www.30secondsofcode.org/js/s/word-wrap
-function wordWrap(str: string, max = 88) {
-  return str.replace(new RegExp(`(?![^\\n]{1,${max}}$)([^\\n]{1,${max}})\\s`, 'g'), '$1\n');
-}
-
 export default class TSGenerator extends CodeGeneratorLanguage {
   project: Project;
 
@@ -53,21 +41,22 @@ export default class TSGenerator extends CodeGeneratorLanguage {
 
   files: Record<string, string>;
 
-  methodGenerics: Map<string, MethodDeclaration>;
-
   sdk: ClassDeclaration;
 
-  sdkExport: VariableStatement;
-
-  schemas: Map<
+  schemas: Record<
     string,
-    {
-      schema: SchemaObject;
-      name: string;
-      tsType?: string;
-    }
+    // Operation-level type
+    | {
+        body?: any;
+        metadata?: any;
+        response?: Record<string, any>;
+      }
+    // Wholesale collection of `$ref` pointer types
+    | Record<string, any>
   >;
 
+  usesHTTPMethodRangeInterface = false;
+
   constructor(spec: Oas, specPath: string, identifier: string, opts: TSGeneratorOptions = {}) {
     const options: { outputJS: boolean; compilerTarget: 'cjs' | 'esm' } = {
       outputJS: false,
@@ -83,10 +72,14 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     super(spec, specPath, identifier);
 
     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',
@@ -99,7 +92,9 @@ export default class TSGenerator extends CodeGeneratorLanguage {
         quoteKind: QuoteKind.Single,
       },
       compilerOptions: {
-        declaration: true,
+        // 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' ? ScriptTarget.ES5 : ScriptTarget.ES2020,
@@ -118,18 +113,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     this.outputJS = options.outputJS;
 
     this.types = new Map();
-    this.methodGenerics = new Map();
-    this.schemas = new Map();
-  }
-
-  static formatter(content: string) {
-    return prettier(content, {
-      format: true,
-      style: {
-        printWidth: 120,
-        singleQuote: true,
-      },
-    } as JSONSchemaToTypescriptOptions);
+    this.schemas = {};
   }
 
   async installer(storage: Storage, opts: InstallerOptions = {}): Promise<void> {
@@ -158,7 +142,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     // 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 execa('npm', [...npmInstall, storage.getIdentifierStorageDir()].filter(Boolean)).then(res => {
+    return execa('npm', [...npmInstall].filter(Boolean)).then(res => {
       if (opts.dryRun) {
         (opts.logger ? opts.logger : logger)(res.command);
         (opts.logger ? opts.logger : logger)(res.stdout);
@@ -171,80 +155,129 @@ export default class TSGenerator extends CodeGeneratorLanguage {
    *
    */
   async generator() {
-    const { operations, methods } = await this.loadOperationsAndMethods();
+    const sdkSource = this.createSourceFile();
+
+    if (Object.keys(this.schemas).length) {
+      this.createSchemasFile();
+      this.createTypesFile();
+
+      // Export all of our available types so they can be used in SDK implementations.
+      //
+      // We're exporting all of the types individually because TS has no way right now of allowing
+      // us to do `export type * from './types'` on a non-named entry.
+      //
+      // https://github.com/microsoft/TypeScript/issues/37238
+      const 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(id => 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(id => id.getText().includes('HTTPMethodRange'))
+        .replaceWithText("import type { ConfigOptions, FetchResponse } from 'api/dist/core'");
+    }
+
+    if (this.outputJS) {
+      return this.project
+        .emitToMemory()
+        .getFiles()
+        .map(sourceFile => {
+          const file = path.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 {};
+          }
+
+          let code = 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 {
+            [file]: code,
+          };
+        })
+        .reduce((prev, next) => Object.assign(prev, next));
+    }
+
+    return [
+      ...this.project.getSourceFiles().map(sourceFile => ({
+        [sourceFile.getBaseName()]: formatter(sourceFile.getFullText()),
+      })),
+
+      // Because we're returning the raw source files for TS generation we also need to separately
+      // emit out our declaration files so we can put those into a separate file in the installed
+      // SDK directory.
+      ...this.project
+        .emitToMemory({ emitOnlyDtsFiles: true })
+        .getFiles()
+        .map(sourceFile => ({
+          [path.basename(sourceFile.filePath)]: formatter(sourceFile.text),
+        })),
+    ].reduce((prev, next) => Object.assign(prev, next));
+  }
+
+  /**
+   * Create our main SDK source file.
+   *
+   */
+  createSourceFile() {
+    const { operations } = this.loadOperationsAndMethods();
 
-    const sdkSource = this.project.createSourceFile('index.ts', '');
+    const sourceFile = this.project.createSourceFile('index.ts', '');
 
-    sdkSource.addImportDeclarations([
+    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 = sdkSource.addClass({
+    this.sdk = sourceFile.addClass({
       name: 'SDK',
-    });
-
-    this.sdkExport = sdkSource.addVariableStatement({
-      declarationKind: VariableDeclarationKind.Const,
-      declarations: [
-        {
-          name: 'createSDK',
-          initializer: writer => {
-            // `ts-morph` doesn't have any way to cleanly create an IFEE.
-            writer.writeLine('(() => { return new SDK(); })()');
-            return writer;
-          },
-        },
+      properties: [
+        { name: 'spec', type: 'Oas' },
+        { name: 'core', type: 'APICore' },
       ],
     });
 
-    /**
-     * 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: writer => {
         writer.writeLine('this.spec = Oas.init(definition);');
@@ -254,21 +287,6 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     });
 
     // 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',
@@ -277,14 +295,14 @@ export default class TSGenerator extends CodeGeneratorLanguage {
         docs: [
           {
             description: writer =>
-              writer.writeLine(
-                wordWrap('Optionally configure various options, such as response parsing, that the SDK allows.')
-              ),
+              writer.writeLine(wordWrap('Optionally configure various options 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.',
+                text: wordWrap(
+                  'config.timeout Override the default `fetch` request timeout of 30 seconds. This number should be represented in milliseconds.'
+                ),
               },
             ],
           },
@@ -357,148 +375,102 @@ sdk.server('https://eu.api.example.com/v14');`)
       },
     ]);
 
-    // Add all common method accessors into the SDK.
-    Array.from(methods).forEach((method: string) => this.createGenericMethodAccessor(method));
-
     // Add all available operation ID accessors into the SDK.
     Object.entries(operations).forEach(([operationId, data]: [string, OperationTypeHousing]) => {
       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(exp => {
-      /**
-       * 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:
-       *
-       *  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 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
-       */
-      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)
-      );
+    // Export our SDK into the source file.
+    sourceFile.addVariableStatement({
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [
+        {
+          name: 'createSDK',
+          initializer: writer => {
+            // `ts-morph` doesn't have any way to cleanly create an IFEE.
+            writer.writeLine('(() => { return new SDK(); })()');
+            return writer;
+          },
+        },
+      ],
     });
 
-    if (this.outputJS) {
-      return this.project
-        .emitToMemory()
-        .getFiles()
-        .map(sourceFile => ({
-          [path.basename(sourceFile.filePath)]: TSGenerator.formatter(sourceFile.text),
-        }))
-        .reduce((prev, next) => Object.assign(prev, next));
-    }
-
-    return [
-      ...this.project.getSourceFiles().map(sourceFile => ({
-        [sourceFile.getBaseName()]: TSGenerator.formatter(sourceFile.getFullText()),
-      })),
+    sourceFile.addExportAssignment({ isExportEquals: false, expression: 'createSDK' });
 
-      // Because we're returning the raw source files for TS generation we also need to separately
-      // emit out our declaration files so we can put those into a separate file in the installed
-      // SDK directory.
-      ...this.project
-        .emitToMemory({ emitOnlyDtsFiles: true })
-        .getFiles()
-        .map(sourceFile => ({
-          [path.basename(sourceFile.filePath)]: TSGenerator.formatter(sourceFile.text),
-        })),
-    ].reduce((prev, next) => Object.assign(prev, next));
+    return sourceFile;
   }
 
   /**
-   * Create a generic HTTP method accessor on the SDK.
+   * 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.
    *
-   * @param method
    */
-  createGenericMethodAccessor(method: string) {
-    const parameters: OptionalKind<ParameterDeclarationStructure>[] = [{ name: 'path', type: 'string' }];
-    const docblock: OptionalKind<JSDocStructure> = {
-      description: writer => {
-        writer.writeLine(`Access any ${method.toUpperCase()} endpoint on your API.`);
-        return writer;
-      },
-      tags: [{ tagName: 'param', text: 'path API path to make a request against.' }],
-    };
+  createSchemasFile() {
+    const sourceFile = this.project.createSourceFile('schemas.ts', '');
 
-    // 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.' });
-    }
+    const sortedSchemas = new Map(Array.from(Object.entries(this.schemas)).sort());
 
-    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.',
+    Array.from(sortedSchemas).forEach(([schemaName, schema]) => {
+      sourceFile.addVariableStatement({
+        declarationKind: VariableDeclarationKind.Const,
+        declarations: [
+          {
+            name: schemaName,
+            initializer: writer => {
+              /**
+               * This is the conversion prefix that we add to all `$ref` pointers we find in
+               * generated JSON Schema.
+               *
+               * 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`.
+               *
+               * And because our TypeScript type name generator properly ignores `:`, this is safe
+               * to prepend to all generated type names.
+               */
+              let str = JSON.stringify(schema);
+              str = str.replace(/"::convert::([a-zA-Z_$\\d]*)"/g, '$1');
+
+              writer.writeLine(`${str} as const`);
+              return writer;
+            },
+          },
+        ],
+      });
     });
 
-    this.methodGenerics.set(
-      method,
-      this.sdk.addMethod({
-        name: method,
-        returnType: 'Promise<T>',
-        parameters,
-        typeParameters: ['T = unknown'],
-        docs: [docblock],
-        statements: writer => {
-          /**
-           * @example return this.core.fetch(path, 'get', body, metadata);
-           * @example return this.core.fetch(path, 'get', metadata);
-           */
-          const fetchStmt = writer.write('return this.core.fetch(path, ').quote(method).write(', ');
-
-          const fetchArgs = parameters.slice(1).map(p => p.name);
-          fetchArgs.forEach((arg, i) => {
-            fetchStmt.write(arg);
-            if (fetchArgs.length > 1 && i !== fetchArgs.length) {
-              fetchStmt.write(', ');
-            }
-          });
+    sourceFile.addStatements(`export { ${Array.from(sortedSchemas.keys()).join(', ')} }`);
 
-          fetchStmt.write(');');
+    return sourceFile;
+  }
 
-          return fetchStmt;
-        },
-      })
-    );
+  /**
+   * 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.
+   *
+   * @see {@link https://npm.im/json-schema-to-ts}
+   */
+  createTypesFile() {
+    const 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(([typeName, typeExpression]) => {
+      sourceFile.addTypeAlias({ isExported: true, name: typeName, type: typeExpression });
+    });
+
+    return sourceFile;
   }
 
   /**
    * Create operation accessors on the SDK.
    *
-   * @param operation
-   * @param operationId
-   * @param paramTypes
-   * @param responseTypes
    */
   createOperationAccessor(
     operation: Operation,
@@ -506,7 +478,7 @@ sdk.server('https://eu.api.example.com/v14');`)
     paramTypes?: OperationTypeHousing['types']['params'],
     responseTypes?: OperationTypeHousing['types']['responses']
   ) {
-    const docblock: OptionalKind<JSDocStructure> = { tags: [] };
+    const docblock: OptionalKind<JSDocStructure> = {};
     const summary = operation.getSummary();
     const description = operation.getDescription();
     if (summary || description) {
@@ -515,9 +487,9 @@ sdk.server('https://eu.api.example.com/v14');`)
       // what we surface the main docblock description.
       docblock.description = writer => {
         if (description) {
-          writer.writeLine(description);
+          writer.writeLine(docblockEscape(wordWrap(description)));
         } else if (summary) {
-          writer.writeLine(summary);
+          writer.writeLine(docblockEscape(wordWrap(summary)));
         }
 
         writer.newLineIfLastNot();
@@ -525,7 +497,7 @@ sdk.server('https://eu.api.example.com/v14');`)
       };
 
       if (summary && description) {
-        docblock.tags.push({ tagName: 'summary', text: summary });
+        docblock.tags = [{ tagName: 'summary', text: docblockEscape(wordWrap(summary)) }];
       }
     }
 
@@ -544,9 +516,7 @@ sdk.server('https://eu.api.example.com/v14');`)
 
         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,
         };
       }
@@ -556,28 +526,39 @@ sdk.server('https://eu.api.example.com/v14');`)
 
         parameters.metadata = {
           name: 'metadata',
-          type: this.schemas.get(paramTypes.metadata).tsType,
+          type: paramTypes.metadata,
           hasQuestionToken: hasOptionalMetadata,
         };
       }
     }
 
-    let returnType = 'Promise<T>';
-    let typeParameters: (string | OptionalKind<TypeParameterDeclarationStructure>)[] = null;
+    let returnType = 'Promise<FetchResponse<number, unknown>>';
     if (responseTypes) {
-      returnType = `Promise<${Object.values(responseTypes)
-        .map(hash => this.schemas.get(hash).tsType)
+      returnType = `Promise<${Object.entries(responseTypes)
+        .map(([status, responseType]) => {
+          if (status.toLowerCase() === 'default') {
+            return `FetchResponse<number, ${responseType}>`;
+          } else if (status.length === 3 && status.toUpperCase().endsWith('XX')) {
+            const 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, ${responseType}>`;
+            }
+
+            this.usesHTTPMethodRangeInterface = true;
+            return `FetchResponse<HTTPMethodRange<${statusPrefix}00, ${statusPrefix}99>, ${responseType}>`;
+          }
+
+          return `FetchResponse<${status}, ${responseType}>`;
+        })
         .join(' | ')}>`;
-    } else {
-      // We should only add the `<T>` method typing if we don't have any response types present.
-      typeParameters = ['T = unknown'];
     }
 
     const operationIdAccessor = this.sdk.addMethod({
       name: operationId,
-      typeParameters,
       returnType,
-      docs: docblock ? [docblock] : null,
+      docs: Object.keys(docblock).length ? [docblock] : null,
       statements: writer => {
         /**
          * @example return this.core.fetch('/pet/findByStatus', 'get', body, metadata);
@@ -618,21 +599,19 @@ sdk.server('https://eu.api.example.com/v14');`)
     if (shouldAddAltTypedOverloads) {
       // Create an overload that has both `body` and `metadata` parameters as required.
       operationIdAccessor.addOverload({
-        typeParameters,
         parameters: [
           { ...parameters.body, hasQuestionToken: false },
           { ...parameters.metadata, hasQuestionToken: false },
         ],
         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,
         parameters: [{ ...parameters.metadata }],
         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
@@ -643,88 +622,20 @@ sdk.server('https://eu.api.example.com/v14');`)
       // see if what the user is supplying is `metadata` or `body` content when they supply one or
       // both.
       operationIdAccessor.addParameters([
-        { ...parameters.body, hasQuestionToken: true },
+        {
+          ...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: `${parameters.body.type} | ${parameters.metadata.type}`,
+          hasQuestionToken: true,
+        },
         { ...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,
-          parameters: [
-            { name: 'path', type: `'${operation.path}'` },
-            { ...parameters.body, hasQuestionToken: false },
-            { ...parameters.metadata, hasQuestionToken: false },
-          ],
-          returnType,
-          docs: docblock ? [docblock] : null,
-        });
-
-        // Create an overload that just has a single `metadata` parameter.
-        this.methodGenerics.get(operation.method).addOverload({
-          typeParameters,
-          parameters: [{ name: 'path', type: `'${operation.path}'` }, parameters.metadata],
-          returnType,
-          docs: docblock ? [docblock] : null,
-        });
-      } else {
-        this.methodGenerics.get(operation.method).addOverload({
-          typeParameters: responseTypes ? null : ['T = unknown'],
-          parameters: [{ name: 'path', type: `'${operation.path}'` }, ...Object.values(parameters)],
-          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
-   */
-  async convertJSONSchemaToTypescript(schema: JSONSchema, name: string) {
-    // Though our JSON Schema type exposes JSONSchema4, which `json-schema-to-typescript` wants, it
-    // won't accept our custom union type of JSON Schema 4, JSON Schema 6, and JSON Schema 7.
-    const ts = await compile(schema as any, 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,
-    });
-
-    let primaryType: string;
-    const tempProject = this.project.createSourceFile(`${name}.types.tmp.ts`, ts);
-    const declarations = tempProject.getExportedDeclarations();
-
-    Array.from(declarations.keys()).forEach(declarationName => {
-      if (!primaryType) {
-        primaryType = declarationName;
-      }
-
-      declarations.get(declarationName).forEach(declaration => {
-        this.types.set(declarationName, declaration.getText());
-      });
-    });
-
-    this.project.removeSourceFile(tempProject);
-
-    return {
-      primaryType,
-    };
   }
 
   /**
@@ -733,7 +644,7 @@ sdk.server('https://eu.api.example.com/v14');`)
    * along with every HTTP method that's in use.
    *
    */
-  async loadOperationsAndMethods() {
+  loadOperationsAndMethods() {
     const operations: Record</* operationId */ string, OperationTypeHousing> = {};
     const methods = new Set();
 
@@ -749,32 +660,19 @@ sdk.server('https://eu.api.example.com/v14');`)
           camelCase: true,
         });
 
-        const params = this.prepareParameterTypesForOperation(operation, operationId);
-        const responses = this.prepareResponseTypesForOperation(operation, operationId);
-
-        if (operation.hasOperationId()) {
-          operations[operationId] = {
-            types: {
-              params,
-              responses,
-            },
-            operation,
-          };
-        }
+        operations[operationId] = {
+          types: {
+            params: this.prepareParameterTypesForOperation(operation, operationId),
+            responses: this.prepareResponseTypesForOperation(operation, operationId),
+          },
+          operation,
+        };
       });
     });
 
-    // Run through and convert every schema we need to use into TS types.
-    await Promise.all(
-      Array.from(this.schemas.entries()).map(async ([hash, { schema, name: schemaName }]) => {
-        const ts = await this.convertJSONSchemaToTypescript(schema as JSONSchema, schemaName);
-
-        this.schemas.set(hash, {
-          ...this.schemas.get(hash),
-          tsType: ts.primaryType,
-        });
-      })
-    );
+    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,
@@ -786,13 +684,24 @@ sdk.server('https://eu.api.example.com/v14');`)
    * Compile the parameter (path, query, cookie, and header) schemas for an API operation into
    * usable TypeScript types.
    *
-   * @param operation
-   * @param operationId
    */
   prepareParameterTypesForOperation(operation: Operation, operationId: string) {
-    const schemas = operation.getParametersAsJsonSchema({
+    const schemas = operation.getParametersAsJSONSchema({
+      includeDiscriminatorMappingRefs: false,
       mergeIntoBodyAndMetadata: true,
       retainDeprecatedProperties: true,
+      transformer: (s: SchemaObject) => {
+        // 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) {
+          const typeName = generateTypeName(s['x-readme-ref-name']);
+          this.addSchemaToExport(s, typeName, typeName);
+
+          return `::convert::${typeName}` as SchemaObject;
+        }
+
+        return s;
+      },
     });
 
     if (!schemas || !schemas.length) {
@@ -804,22 +713,22 @@ sdk.server('https://eu.api.example.com/v14');`)
       .reduce((prev, next) => Object.assign(prev, next));
 
     return Object.entries(res)
-      .map(([paramType, schema]) => {
-        const schemaName = schema['x-readme-ref-name'] || `${operationId}_${paramType}_param`;
-        const hash = objectHash({
-          name: schemaName,
-          schema,
-        });
-
-        if (!this.schemas.has(hash)) {
-          this.schemas.set(hash, {
-            schema,
-            name: schemaName,
-          });
+      .map(([paramType, schema]: [string, string | unknown]) => {
+        let 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 = generateTypeName(operationId, paramType, 'param');
+          this.addSchemaToExport(schema, typeName, `${generateTypeName(operationId)}.${paramType}`);
         }
 
         return {
-          [paramType]: hash,
+          // Types are prefixed with `types.` because that's how we're importing them from
+          // `types.d.ts`.
+          [paramType]: `types.${typeName}`,
         };
       })
       .reduce((prev, next) => Object.assign(prev, next), {}) as Record<'body' | 'formData' | 'metadata', string>;
@@ -828,9 +737,6 @@ sdk.server('https://eu.api.example.com/v14');`)
   /**
    * 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
    */
   prepareResponseTypesForOperation(operation: Operation, operationId: string) {
     const responseStatusCodes = operation.getResponseStatusCodes();
@@ -840,7 +746,22 @@ sdk.server('https://eu.api.example.com/v14');`)
 
     const schemas = responseStatusCodes
       .map(status => {
-        const schema = operation.getResponseAsJsonSchema(status);
+        const schema = operation.getResponseAsJSONSchema(status, {
+          includeDiscriminatorMappingRefs: false,
+          transformer: (s: SchemaObject) => {
+            // 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) {
+              const typeName = generateTypeName(s['x-readme-ref-name']);
+              this.addSchemaToExport(s, typeName, `${typeName}`);
+
+              return `::convert::${typeName}` as SchemaObject;
+            }
+
+            return s;
+          },
+        });
+
         if (!schema) {
           return false;
         }
@@ -853,25 +774,42 @@ sdk.server('https://eu.api.example.com/v14');`)
 
     const res = Object.entries(schemas)
       .map(([status, { schema }]) => {
-        const schemaName = schema['x-readme-ref-name'] || `${operationId}_Response_${status}`;
-        const hash = objectHash({
-          name: schemaName,
-          schema,
-        });
-
-        if (!this.schemas.has(hash)) {
-          this.schemas.set(hash, {
-            schema,
-            name: schemaName,
-          });
+        let 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 = 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, `${generateTypeName(operationId)}.response['${status}']`);
         }
 
         return {
-          [status]: hash,
+          // Types are prefixed with `types.` because that's how we're importing them from
+          // `types.d.ts`.
+          [status]: `types.${typeName}`,
         };
       })
       .reduce((prev, next) => 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.
+   *
+   */
+  addSchemaToExport(schema: any, typeName: string, pointer: string) {
+    if (this.types.has(typeName)) {
+      return;
+    }
+
+    setWith(this.schemas, pointer, schema, Object);
+    this.types.set(typeName, `FromSchema<typeof schemas.${pointer}>`);
+  }
 }