api 4.4.0 → 4.5.2

package/README.md

@@ -23,7 +23,7 @@ npm install api --save
 Using `api` is as simple as supplying it an OpenAPI and using the SDK as you would any other!
 
 ```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas/master/packages/examples/3.0/json/petstore.json');
+const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json');
 
 sdk.listPets().then(res => {
   console.log(`My pets name is ${res[0].name}!`);
@@ -164,3 +164,17 @@ By default we parse the response based on the `content-type` header for you. You
 ```js
 sdk.config({ parseResponse: false });
 ```
+
+#### Where is the cache stored?
+
+By default the cache is configured with the [find-cache-dir](https://npm.im/find-cache-dir) library so the cache will be in `node_modules/.cache/api`. If placing this cache within the `node_modules/` directory is a problem for your environment (maybe you use `npm prune`) you can configure this by supplying an additional argument to the SDK instantiator:
+
+```js
+const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json', {
+  cacheDir: './path/to/my/custom/cache/dir',
+});
+
+sdk.listPets().then(res => {
+  console.log(`My pets name is ${res[0].name}!`);
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api",
-  "version": "4.4.0",
+  "version": "4.5.2",
   "description": "Generate an SDK from an OpenAPI definition",
   "main": "src/index.js",
   "scripts": {
@@ -34,7 +34,7 @@
     "make-dir": "^3.1.0",
     "mimer": "^2.0.2",
     "node-fetch": "^2.6.0",
-    "oas": "^18.1.0"
+    "oas": "^18.3.4"
   },
   "devDependencies": {
     "@readme/eslint-config": "^8.0.2",
@@ -48,8 +48,9 @@
   "prettier": "@readme/eslint-config/prettier",
   "jest": {
     "testPathIgnorePatterns": [
-      "__tests__/__fixtures__/"
+      "__tests__/__fixtures__/",
+      ".api-test/"
     ]
   },
-  "gitHead": "dab29250c2aea8ff2148aa35d50f9fc11cf69647"
+  "gitHead": "a4206f70f041c16dd748735e7ad2a3f808d3cd67"
 }

package/src/cache.js

@@ -9,18 +9,8 @@ const os = require('os');
 const path = require('path');
 const makeDir = require('make-dir');
 
-let cacheDir = findCacheDir({ name: pkg.name });
-if (typeof cacheDir === 'undefined') {
-  // The `find-cache-dir` module returns `undefined` if the `node_modules/` directory isn't writable, or there's no
-  // `package.json` in the root-most directory. If this happens, we can instead adhoc create a cache directory in the
-  // users OS temp directory and store our data there.
-  //
-  // @link https://github.com/avajs/find-cache-dir/issues/29
-  cacheDir = makeDir.sync(path.join(os.tmpdir(), pkg.name));
-}
-
-class SdkCache {
-  constructor(uri) {
+class Cache {
+  constructor(uri, cacheDir = false) {
     /**
      * Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
      *
@@ -37,8 +27,23 @@ class SdkCache {
         : u;
 
     this.uri = resolveReadMeRegistryAccessor(uri);
-    this.uriHash = SdkCache.getCacheHash(this.uri);
-    this.dir = cacheDir;
+    this.uriHash = Cache.getCacheHash(this.uri);
+
+    if (cacheDir) {
+      this.dir = cacheDir;
+    } else {
+      this.dir = findCacheDir({ name: pkg.name });
+      if (typeof this.dir === 'undefined') {
+        // The `find-cache-dir` module returns `undefined` if the `node_modules/` directory isn't
+        // writable, or there's no `package.json` in the root-most directory. If this happens, we
+        // can instead adhoc create a cache directory in the users OS temp directory and store our
+        // data there.
+        //
+        // @link https://github.com/avajs/find-cache-dir/issues/29
+        this.dir = makeDir.sync(path.join(os.tmpdir(), pkg.name));
+      }
+    }
+
     this.cacheStore = path.join(this.dir, 'cache.json');
     this.specsCache = path.join(this.dir, 'specs');
 
@@ -87,7 +92,18 @@ class SdkCache {
     }
 
     const cache = this.getCache();
-    return JSON.parse(fs.readFileSync(cache[this.uriHash].path, 'utf8'));
+
+    // Prior to v4.5.0 we were putting a fully resolved path to the API definition in the cache
+    // store but if you had specified a custom caching directory and would generate the cache on
+    // your system, that filepath would obviously not be the same in other environments. For this
+    // reason the `path` was removed from the cache store in favor of storing the `hash` instead.
+    //
+    // If we still have `path` in the config cache for backwards compatibility we should use it.
+    if ('path' in cache[this.uriHash]) {
+      return JSON.parse(fs.readFileSync(cache[this.uriHash].path, 'utf8'));
+    }
+
+    return JSON.parse(fs.readFileSync(path.join(this.specsCache, `${cache[this.uriHash].hash}.json`)));
   }
 
   async load() {
@@ -154,16 +170,16 @@ class SdkCache {
         const cache = self.getCache();
         if (!(self.uriHash in cache)) {
           const saved = JSON.stringify(spec, null, 2);
-          const jsonHash = crypto.createHash('md5').update(saved).digest('hex');
+          const fileHash = crypto.createHash('md5').update(saved).digest('hex');
 
           cache[self.uriHash] = {
-            path: path.join(self.specsCache, `${jsonHash}.json`),
+            hash: fileHash,
             original: self.uri,
             title: 'title' in spec.info ? spec.info.title : undefined,
             version: 'version' in spec.info ? spec.info.version : undefined,
           };
 
-          fs.writeFileSync(cache[self.uriHash].path, saved);
+          fs.writeFileSync(path.join(self.specsCache, `${fileHash}.json`), saved);
           fs.writeFileSync(self.cacheStore, JSON.stringify(cache, null, 2));
 
           self.cache = cache;
@@ -206,4 +222,4 @@ class SdkCache {
   }
 }
 
-module.exports = SdkCache;
+module.exports = Cache;

package/src/index.js

@@ -13,24 +13,16 @@ global.Headers = fetch.Headers;
 global.FormData = require('form-data');
 
 class Sdk {
-  constructor(uri) {
+  constructor(uri, opts = {}) {
     this.uri = uri;
     this.userAgent = `${pkg.name} (node)/${pkg.version}`;
-  }
 
-  static getOperations(spec) {
-    return Object.keys(spec.api.paths)
-      .map(path => {
-        return Object.keys(spec.api.paths[path]).map(method => {
-          return spec.operation(path, method);
-        });
-      })
-      .reduce((prev, next) => prev.concat(next), []);
+    this.cacheDir = opts.cacheDir ? opts.cacheDir : false;
   }
 
   load() {
     let authKeys = [];
-    const cache = new Cache(this.uri);
+    const cache = new Cache(this.uri, this.cacheDir);
     const self = this;
     let config = { parseResponse: true };
     let server = false;
@@ -68,30 +60,62 @@ class 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(spec) {
       const supportedVerbs = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 
       return supportedVerbs
-        .map(name => {
+        .map(httpVerb => {
           return {
-            [name]: ((method, path, ...args) => {
+            [httpVerb]: ((method, path, ...args) => {
               const operation = spec.operation(path, method);
               return fetchOperation(spec, operation, ...args);
-            }).bind(null, name),
+            }).bind(null, httpVerb),
           };
         })
         .reduce((prev, next) => 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.
+     *
+     * @param spec
+     */
     function loadOperations(spec) {
-      return Sdk.getOperations(spec)
-        .filter(operation => operation.schema.operationId)
+      return Object.entries(spec.getPaths())
+        .map(([, operations]) => Object.values(operations))
+        .reduce((prev, next) => prev.concat(next), [])
+        .filter(operation => operation.hasOperationId())
         .reduce((prev, next) => {
-          return Object.assign(prev, {
-            [next.schema.operationId]: ((operation, ...args) => {
+          // `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.
+          const operationId = next.getOperationId({ camelCase: true });
+          const originalOperationId = next.getOperationId();
+
+          const op = {
+            [operationId]: ((operation, ...args) => {
               return fetchOperation(spec, operation, ...args);
             }).bind(null, next),
-          });
+          };
+
+          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.
+            op[originalOperationId] = ((operation, ...args) => {
+              return fetchOperation(spec, operation, ...args);
+            }).bind(null, next);
+          }
+
+          return Object.assign(prev, op);
         }, {});
     }
 
@@ -170,6 +194,6 @@ class Sdk {
   }
 }
 
-module.exports = uri => {
-  return new Sdk(uri).load();
+module.exports = (uri, opts = {}) => {
+  return new Sdk(uri, opts).load();
 };