api 5.0.0-beta.3 → 5.0.0

package/dist/index.js

@@ -1,15 +1,4 @@
 "use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -59,8 +48,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 var oas_1 = __importDefault(require("oas"));
-var core_1 = __importDefault(require("./core"));
 var cache_1 = __importDefault(require("./cache"));
+var core_1 = __importDefault(require("./core"));
 var packageInfo_1 = require("./packageInfo");
 var Sdk = /** @class */ (function () {
     function Sdk(uri, opts) {
@@ -77,28 +66,6 @@ var Sdk = /** @class */ (function () {
         var isLoaded = false;
         var isCached = cache.isCached();
         var sdk = {};
-        /**
-         * Create dynamic accessors for every HTTP method that the OpenAPI specification supports.
-         *
-         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-7}
-         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-7}
-         */
-        function loadMethods() {
-            return ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']
-                .map(function (httpVerb) {
-                var _a;
-                return _a = {},
-                    _a[httpVerb] = (function (method, path) {
-                        var args = [];
-                        for (var _i = 2; _i < arguments.length; _i++) {
-                            args[_i - 2] = arguments[_i];
-                        }
-                        return core.fetch.apply(core, __spreadArray([path, method], args, false));
-                    }).bind(null, httpVerb),
-                    _a;
-            })
-                .reduce(function (prev, next) { return Object.assign(prev, next); });
-        }
         /**
          * Create dynamic accessors for every operation with a defined operation ID. If an operation
          * does not have an operation ID it can be accessed by its `.method('/path')` accessor instead.
@@ -112,15 +79,15 @@ var Sdk = /** @class */ (function () {
                 return Object.values(operations);
             })
                 .reduce(function (prev, next) { return prev.concat(next); }, [])
-                .filter(function (operation) { return operation.hasOperationId(); })
                 .reduce(function (prev, next) {
                 var _a;
                 // `getOperationId()` creates dynamic operation IDs when one isn't available but we need
                 // to know here if we actually have one present or not. The `camelCase` option here also
                 // cleans up any `operationId` that we might have into something that can be used as a
                 // valid JS method.
+                var originalOperationId = next.getOperationId();
                 var operationId = next.getOperationId({ camelCase: true });
-                return Object.assign(prev, (_a = {},
+                var op = (_a = {},
                     _a[operationId] = (function (operation) {
                         var args = [];
                         for (var _i = 1; _i < arguments.length; _i++) {
@@ -128,7 +95,24 @@ var Sdk = /** @class */ (function () {
                         }
                         return core.fetchOperation.apply(core, __spreadArray([operation], args, false));
                     }).bind(null, next),
-                    _a));
+                    _a);
+                if (operationId !== originalOperationId) {
+                    // If we cleaned up their operation ID into a friendly method accessor (`findPetById`
+                    // versus `find pet by id`) we should still let them use the non-friendly version if
+                    // they want.
+                    //
+                    // This work is to maintain backwards compatibility with `api@4` and does not exist
+                    // within our code generated SDKs -- those only allow the cleaner camelCase
+                    // `operationId` to be used.
+                    op[originalOperationId] = (function (operation) {
+                        var args = [];
+                        for (var _i = 1; _i < arguments.length; _i++) {
+                            args[_i - 1] = arguments[_i];
+                        }
+                        return core.fetchOperation.apply(core, __spreadArray([operation], args, false));
+                    }).bind(null, next);
+                }
+                return Object.assign(prev, op);
             }, {});
         }
         function loadFromCache() {
@@ -150,7 +134,7 @@ var Sdk = /** @class */ (function () {
                         case 4:
                             spec = new oas_1["default"](cachedSpec);
                             core.setSpec(spec);
-                            sdk = Object.assign(sdk, __assign(__assign({}, loadMethods()), loadOperations(spec)));
+                            sdk = Object.assign(sdk, loadOperations(spec));
                             isLoaded = true;
                             return [2 /*return*/];
                     }
@@ -234,10 +218,10 @@ var Sdk = /** @class */ (function () {
                 core.setAuth.apply(core, values);
             },
             /**
-             * Optionally configure various options, such as response parsing, that the SDK allows.
+             * Optionally configure various options that the SDK allows.
              *
              * @param config Object of supported SDK options and toggles.
-             * @param config.parseResponse If responses are parsed according to its `Content-Type` header.
+             * @param config.timeout Override the default `fetch` request timeout of 30 seconds (30000ms).
              */
             config: function (config) {
                 core.setConfig(config);

package/dist/packageInfo.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "api";
-export declare const PACKAGE_VERSION = "5.0.0-beta.3";
+export declare const PACKAGE_VERSION = "5.0.0";

package/dist/packageInfo.js

@@ -3,4 +3,4 @@ exports.__esModule = true;
 exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
 // This file is automatically updated by the build script.
 exports.PACKAGE_NAME = 'api';
-exports.PACKAGE_VERSION = '5.0.0-beta.3';
+exports.PACKAGE_VERSION = '5.0.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api",
-  "version": "5.0.0-beta.3",
+  "version": "5.0.0",
   "description": "Magical SDK generation from an OpenAPI definition 🪄",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,10 +10,11 @@
   "scripts": {
     "build": "tsc",
     "debug:bin": "node -r ts-node/register src/bin.ts",
-    "prebuild": "rm -rf dist/; npm run prebuild.packageConfig",
-    "prebuild.packageConfig": "node -p \"'// This file is automatically updated by the build script.\\nexport const PACKAGE_NAME = \\'' + require('./package.json').name + '\\';\\nexport const PACKAGE_VERSION = \\'' + require('./package.json').version + '\\';'\" > src/packageInfo.ts; git add src/packageInfo.ts",
+    "prebuild": "rm -rf dist/; npm run version",
     "prepack": "npm run build",
-    "test": "nyc mocha \"test/**/*.test.ts\""
+    "test": "nyc mocha $(find test -name '*.test.ts' -not -path '*/smoketest.test.ts')",
+    "test:smoke": "npx mocha test/cli/codegen/languages/typescript/smoketest.test.ts",
+    "version": "node -p \"'// This file is automatically updated by the build script.\\nexport const PACKAGE_NAME = \\'' + require('./package.json').name + '\\';\\nexport const PACKAGE_VERSION = \\'' + require('./package.json').version + '\\';'\" > src/packageInfo.ts; git add src/packageInfo.ts"
   },
   "repository": {
     "type": "git",
@@ -36,14 +37,14 @@
     "swagger"
   ],
   "dependencies": {
-    "@readme/oas-to-har": "^17.0.8",
+    "@readme/oas-to-har": "^20.0.0",
     "@readme/openapi-parser": "^2.2.0",
     "caseless": "^0.12.0",
     "chalk": "^4.1.2",
-    "commander": "^9.2.0",
+    "commander": "^9.4.0",
     "datauri": "^4.1.0",
     "execa": "^5.1.1",
-    "fetch-har": "^8.0.3",
+    "fetch-har": "^8.1.3",
     "figures": "^3.2.0",
     "find-cache-dir": "^3.3.1",
     "form-data-encoder": "^1.7.2",
@@ -51,28 +52,37 @@
     "get-stream": "^6.0.1",
     "isomorphic-fetch": "^3.0.0",
     "js-yaml": "^4.1.0",
-    "json-schema-to-typescript": "^10.1.5",
+    "json-schema-to-ts": "^2.5.5",
     "json-schema-traverse": "^1.0.0",
+    "lodash.camelcase": "^4.3.0",
+    "lodash.deburr": "^4.1.0",
     "lodash.merge": "^4.6.2",
+    "lodash.setwith": "^4.3.2",
+    "lodash.startcase": "^4.4.0",
     "make-dir": "^3.1.0",
-    "oas": "^18.3.4",
-    "object-hash": "^3.0.0",
+    "node-abort-controller": "^3.0.1",
+    "oas": "^20.0.0",
     "ora": "^5.4.1",
+    "prettier": "^2.7.1",
     "prompts": "^2.4.2",
     "remove-undefined-objects": "^2.0.1",
-    "ssri": "^9.0.0",
-    "ts-morph": "^15.1.0",
-    "validate-npm-package-name": "^4.0.0"
+    "ssri": "^10.0.0",
+    "ts-morph": "^16.0.0",
+    "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@readme/oas-examples": "^5.4.1",
+    "@readme/oas-examples": "^5.7.1",
     "@types/caseless": "^0.12.2",
     "@types/chai": "^4.3.1",
     "@types/find-cache-dir": "^3.2.1",
     "@types/js-yaml": "^4.0.5",
+    "@types/lodash.camelcase": "^4.3.7",
+    "@types/lodash.deburr": "^4.1.7",
     "@types/lodash.merge": "^4.6.7",
-    "@types/mocha": "^9.1.1",
-    "@types/object-hash": "^2.2.1",
+    "@types/lodash.setwith": "^4.3.7",
+    "@types/lodash.startcase": "^4.4.7",
+    "@types/mocha": "^10.0.0",
+    "@types/prettier": "^2.7.1",
     "@types/prompts": "^2.0.14",
     "@types/sinon-chai": "^3.2.8",
     "@types/ssri": "^7.1.1",
@@ -82,6 +92,7 @@
     "mocha": "^10.0.0",
     "mock-require": "^3.0.3",
     "nyc": "^15.1.0",
+    "oas-normalize": "^7.1.0",
     "sinon": "^14.0.0",
     "sinon-chai": "^3.7.0",
     "typescript": "^4.7.4",
@@ -94,5 +105,5 @@
       "test/"
     ]
   },
-  "gitHead": "24d5b83545735176786d212a69121a029cf6dea1"
+  "gitHead": "bb044ecdb3296c24838056764553fa7f18e6d228"
 }

package/src/bin.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
-import * as pkg from './packageInfo';
+
 import commands from './cli/commands';
+import * as pkg from './packageInfo';
 
 (async () => {
   const program = new Command();

package/src/cache.ts

@@ -1,17 +1,16 @@
 import type { OASDocument } from 'oas/dist/rmoas.types';
 
-import 'isomorphic-fetch';
-import OpenAPIParser from '@readme/openapi-parser';
 import crypto from 'crypto';
-import findCacheDir from 'find-cache-dir';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import makeDir from 'make-dir';
 
-import { PACKAGE_NAME } from './packageInfo';
+import findCacheDir from 'find-cache-dir';
+import 'isomorphic-fetch';
+import makeDir from 'make-dir';
 
 import Fetcher from './fetcher';
+import { PACKAGE_NAME } from './packageInfo';
 
 type CacheStore = Record<
   string,
@@ -103,28 +102,6 @@ export default class Cache {
     }
   }
 
-  static validate(json: any) {
-    if (json.swagger) {
-      throw new Error('Sorry, this module only supports OpenAPI definitions.');
-    }
-
-    // The `validate` method handles dereferencing for us.
-    return OpenAPIParser.validate(json, {
-      dereference: {
-        // If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`.
-        // This allows us to not only do easy circular reference detection but also stringify and
-        // save dereferenced API definitions back into the cache directory.
-        circular: 'ignore',
-      },
-    }).catch(err => {
-      if (/is not a valid openapi definition/i.test(err.message)) {
-        throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
-      }
-
-      throw err;
-    });
-  }
-
   isCached() {
     const cache = this.getCache();
     return cache && this.uriHash in cache;
@@ -171,10 +148,11 @@ export default class Cache {
   }
 
   async load() {
-    // If the class was supplied a raw object, just go ahead and bypass the caching system and
-    // return that.
+    // If the class was supplied a raw object we should still validate and make sure that it's
+    // dereferenced in order for everything to function, but we shouldn't worry about saving it
+    // into the cache directory architecture.
     if (typeof this.uri === 'object') {
-      return this.uri;
+      return Fetcher.validate(this.uri);
     }
 
     return this.fetcher.load().then(async spec => this.save(spec));

package/src/cli/codegen/index.ts

@@ -1,5 +1,5 @@
-import type Oas from 'oas';
 import type CodeGeneratorLanguage from './language';
+import type Oas from 'oas';
 
 import TSGenerator from './languages/typescript';
 

package/src/cli/codegen/language.ts

@@ -1,5 +1,6 @@
-import type Oas from 'oas';
 import type Storage from '../storage';
+import type Oas from 'oas';
+
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../../packageInfo';
 
 export interface InstallerOptions {
@@ -35,6 +36,22 @@ export default abstract class CodeGeneratorLanguage {
     // a `petstore` spec installed on api@4.2.0.
     const info = spec.getDefinition().info;
     this.userAgent = `${identifier}/${info.version} (${PACKAGE_NAME}/${PACKAGE_VERSION})`;
+
+    /**
+     * This check is barbaric but there are a number of issues with how the `transformer` work we
+     * have in `oas` and in `.getParametersAsJSONSchema()` and `.getResponseAsJSONSchema()` that
+     * are fully crashing when attempting to codegen an SDK for an API definition that has a
+     * circular reference.
+     *
+     * In order to get v5 out the door we're not going to support this case initialy.
+     *
+     * @see {@link https://github.com/readmeio/api/issues/549}
+     */
+    if (JSON.stringify(spec.api).includes('"$ref":"#/')) {
+      throw new Error(
+        'Sorry, this library does not yet support generating an SDK for an OpenAPI definition that contains circular references.'
+      );
+    }
   }
 
   abstract generator(): Promise<Record<string, string>>;

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

@@ -0,0 +1,183 @@
+import camelCase from 'lodash.camelcase';
+import deburr from 'lodash.deburr';
+import startCase from 'lodash.startcase';
+import { format as prettier } from 'prettier';
+
+/**
+ * This is a mix of reserved JS words and keywords in TypeScript that might be reserved or
+ * allowable but functionally confusing (like `let any = 'buster';`)
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}
+ */
+const RESERVED_WORDS = [
+  'abstract',
+  'any',
+  'arguments',
+  'as',
+  'async',
+  'await',
+  'boolean',
+  'break',
+  'byte',
+  'case',
+  'catch',
+  'char',
+  'class',
+  'const',
+  'continue',
+  'constructor',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'double',
+  'else',
+  'enum',
+  'eval',
+  'export',
+  'extends',
+  'false',
+  'final',
+  'finally',
+  'float',
+  'for',
+  'from',
+  'function',
+  'get',
+  'goto',
+  'if',
+  'implements',
+  'import',
+  'interface',
+  'in',
+  'instanceof',
+  'int',
+  'let',
+  'long',
+  'native',
+  'new',
+  'null',
+  'number',
+  'of',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'module',
+  'namespace',
+  'return',
+  'set',
+  'short',
+  'static',
+  'string',
+  'super',
+  'switch',
+  'synchronized',
+  'this',
+  'throw',
+  'throws',
+  'transient',
+  'true',
+  'try',
+  'type',
+  'typeof',
+  'var',
+  'void',
+  'while',
+  'with',
+  'volatile',
+  'yield',
+
+  // These aren't reserved keywords but because we maybe codegen'ing an SDK to be used in the
+  // browser it'd be very bad if we overwrote these. This obviously doesn't account for browser APIs
+  // you can access outside of the `Window` API (like `alert()`), but we can add checks for those
+  // later if we need to.
+  'frames',
+  'global',
+  'globalThis',
+  'navigator',
+  'self',
+  'window',
+];
+
+export function formatter(content: string) {
+  return prettier(content, {
+    parser: 'typescript',
+    printWidth: 100,
+    singleQuote: true,
+  });
+}
+
+/**
+ * @see {@link https://www.30secondsofcode.org/js/s/word-wrap}
+ */
+export function wordWrap(str: string, max = 88) {
+  return str.replace(new RegExp(`(?![^\\n]{1,${max}}$)([^\\n]{1,${max}})\\s`, 'g'), '$1\n');
+}
+
+/**
+ * Safely escape some string characters that may break a docblock.
+ *
+ */
+export function docblockEscape(str: string) {
+  return str.replace(/\/\*/g, '/\\*').replace(/\*\//g, '*\\/');
+}
+
+/**
+ * Convert a string that might contain spaces or special characters to one that can safely be used
+ * as a TypeScript interface or enum name.
+ *
+ * This function has been adapted and slighty modified from `json-schema-to-typescript`.
+ *
+ * @license MIT
+ * @see {@link https://github.com/bcherny/json-schema-to-typescript}
+ */
+export function toSafeString(str: string) {
+  // identifiers in javaScript/ts:
+  // First character: a-zA-Z | _ | $
+  // Rest: a-zA-Z | _ | $ | 0-9
+
+  // remove accents, umlauts, ... by their basic latin letters
+  return (
+    deburr(str)
+      // if the string starts with a number, prefix it with character that typescript can accept
+      // https://github.com/bcherny/json-schema-to-typescript/issues/489
+      .replace(/^(\d){1}/, '$$1')
+      // replace chars which are not valid for typescript identifiers with whitespace
+      .replace(/(^\s*[^a-zA-Z_$])|([^a-zA-Z_$\d])/g, ' ')
+      // uppercase leading underscores followed by lowercase
+      .replace(/^_[a-z]/g, (match: string) => match.toUpperCase())
+      // remove non-leading underscores followed by lowercase (convert snake_case)
+      .replace(/_[a-z]/g, (match: string) => match.substr(1, match.length).toUpperCase())
+      // uppercase letters after digits, dollars
+      .replace(/([\d$]+[a-zA-Z])/g, (match: string) => match.toUpperCase())
+      // uppercase first letter after whitespace
+      .replace(/\s+([a-zA-Z])/g, (match: string) => match.toUpperCase().trim())
+      // remove remaining whitespace
+      .replace(/\s/g, '')
+  );
+}
+
+export function generateTypeName(...parts: string[]) {
+  let str;
+
+  // If the end of our string ends with something like `2XX`, the combination of `startCase` and
+  // `camelCase` will transform it into `2Xx`.
+  if (parts.length > 1) {
+    const last = parts[parts.length - 1];
+    if (last.match(/^(\d)XX$/)) {
+      str = startCase(camelCase(parts.slice(0, -1).join(' ')));
+      str += ` ${last}`;
+    }
+  }
+
+  if (!str) {
+    str = startCase(camelCase(parts.join(' ')));
+  }
+
+  if (RESERVED_WORDS.includes(str.toLowerCase())) {
+    str = `$${str}`;
+  }
+
+  return toSafeString(str);
+}