fury - npm Package Compare versions

Comparing version 3.0.0-beta.9 to 3.0.0-beta.10

CHANGELOG.md

 # Fury Changelog
 
+## 3.0.0-beta.10 (2019-03-26)
+
+### Breaking
+
+- Fury will no longer catch exceptions thrown by an adapter during a
+  `parse`, or `serialize`.  
+  [#158](https://github.com/apiaryio/api-elements.js/issues/158)
+
+### Enhancement
+
+- Fury now pass into operations parse(), validate(), serialize() mediaType as one of adapter options
+- Fury now allows distinguish among Media Types for individual oprations (for more info see README)
+
 ## 3.0.0-beta.9 (2019-02-26)
@@ -4,0 +17,0 @@

lib/fury.js

@@ -14,4 +14,7 @@ const minimModule = require('minim');
   for (let i = 0; i < adapters.length; i += 1) {
-    if (adapters[i].mediaTypes.indexOf(mediaType) !== -1 && adapters[i][method]) {
-      return adapters[i];
+    const adapter = adapters[i];
+    if (Array.isArray(adapter.mediaTypes) && adapter.mediaTypes.includes(mediaType) && adapter[method]) {
+      return adapter;
+    } if (typeof adapter.mediaTypes === 'object' && adapter.mediaTypes[method] && adapter.mediaTypes[method].includes(mediaType) && adapter[method]) {
+      return adapter;
     }
@@ -23,2 +26,53 @@ }
 
+/**
+ * @interface FuryAdapter
+ *
+ * @property name {string}
+ * @property mediaTypes {string[]}
+ */
+
+/**
+ * @function detect
+ *
+ * @param source {string}
+ * @returns {boolean}
+ *
+ * @memberof FuryAdapter
+ */
+
+/**
+ * @function validate
+ *
+ * @param {Object} options
+ * @param {string} options.source
+ * @param {Namespace} options.minim
+ * @param {ParseCallback} callback
+ *
+ * @memberof FuryAdapter
+ */
+
+/**
+ * @function parse
+ *
+ * @param {Object} options
+ * @param {string} options.source
+ * @param {Namespace} options.minim
+ * @param {ParseCallback} callback
+ *
+ * @memberof FuryAdapter
+ */
+
+/**
+ * @function serialize
+ *
+ * @param {Object} options
+ * @param {Category} options.api
+ * @param {Namespace} options.minim
+ * @param {SerializeCallback} callback
+ *
+ * @memberof FuryAdapter
+ */
+
+/**
+ */
 class Fury {
@@ -30,4 +84,6 @@ constructor() {
 
-  /*
+  /**
    * Register to use an adapter with this Fury instance.
+   *
+   * @param {FuryAdapter}
    */
@@ -46,5 +102,15 @@ use(adapter) {
 
-  // Returns an array of adapters which can handle the given API Description Source
-  detect(source) {
-    return this.adapters.filter(adapter => adapter.detect && adapter.detect(source));
+  /**
+   * Returns an array of adapters which can handle the given API Description Source
+   * it is internally invoked while `mediaType` is not sent
+   * into methods `parse()`, `validate()` or `serialized()`
+   *
+   * @param source {string}
+   * @param method {string} - optional
+   *
+   * @return {FuryAdapter}
+   */
+  detect(source, method) {
+    const adapters = this.adapters.filter(adapter => (adapter.detect && adapter.detect(source, method)) && (method === undefined || adapter[method]));
+    return adapters;
   }
@@ -57,5 +123,21 @@
 
-    return this.detect(source).filter(adapter => adapter[method])[0];
+    return this.detect(source, method).filter(adapter => adapter[method])[0];
   }
 
+  /**
+   * @callback ParseCallback
+   *
+   * @param {Error} error
+   * @param {ParseResult} parseResult
+   */
+
+  /**
+   * Validate an API Description Document
+   *
+   * @param {Object} options
+   * @param {string} options.source
+   * @param {string} [options.mediaType]
+   * @param {Object} [options.adapterOptions]
+   * @param callback {ParseCallback}
+   */
   validate({ source, mediaType, adapterOptions }, done) {
@@ -79,3 +161,3 @@ const adapter = this.findAdapter(source, mediaType, 'validate');
 
-    let options = { minim: this.minim, source };
+    let options = { minim: this.minim, mediaType, source };
 
@@ -99,7 +181,14 @@ if (adapterOptions) {
 
-  /*
-   * Parse an input document into Javascript objects. This method uses
-   * the registered adapters to automatically detect the input format,
-   * then uses the adapter to convert into refract elements and loads
-   * these into objects.
+  /**
+   * Parse an API Description Document
+   *
+   * This method uses the registered adapters to automatically detect the
+   * input format, then uses the adapter to convert into refract elements
+   * and loads these into objects.
+   *
+   * @param {Object} options
+   * @param {string} options.source
+   * @param {string} [options.mediaType]
+   * @param {Object} [options.adapterOptions]
+   * @param callback {ParseCallback}
    */
@@ -115,28 +204,38 @@ parse({
 
-    try {
-      let options = { generateSourceMap, minim: this.minim, source };
+    let options = {
+      generateSourceMap, minim: this.minim, mediaType, source,
+    };
 
-      if (adapterOptions) {
-        options = Object.assign(options, adapterOptions);
+    if (adapterOptions) {
+      options = Object.assign(options, adapterOptions);
+    }
+
+    return adapter.parse(options, (err, parseResult) => {
+      if (err) {
+        return done(err);
       }
 
-      return adapter.parse(options, (err, parseResult) => {
-        if (err) {
-          return done(err);
-        }
+      if (!(parseResult instanceof this.minim.Element)) {
+        return done(null, this.load(parseResult));
+      }
 
-        if (!(parseResult instanceof this.minim.Element)) {
-          return done(null, this.load(parseResult));
-        }
-
-        return done(null, parseResult);
-      });
-    } catch (err) {
-      return done(err);
-    }
+      return done(null, parseResult);
+    });
   }
 
-  /*
-   * Serialize a parsed API into the given output format.
+  /**
+   * @callback SerializeCallback
+   *
+   * @param {Error} error
+   * @param {string} source
    */
+
+  /**
+   * Serialize an API Description into the given output format.
+   *
+   * @param {Object} options
+   * @param {Category} options.api
+   * @param {string} [options.mediaType]
+   * @param callback {SerializeCallback}
+   */
   serialize({ api, mediaType = 'text/vnd.apiblueprint' }, done) {
@@ -146,10 +245,6 @@ const adapter = findAdapter(this.adapters, mediaType, 'serialize');
     if (adapter) {
-      try {
-        return adapter.serialize({ api, minim: this.minim }, done);
-      } catch (err) {
-        return done(err);
-      }
-    } else {
-      return done(new Error('Media type did not match any registered serializer!'));
+      return adapter.serialize({ api, minim: this.minim, mediaType }, done);
     }
+
+    return done(new Error('Media type did not match any registered serializer!'));
   }
@@ -156,0 +251,0 @@ }

package.json

 {
   "name": "fury",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.0-beta.10",
   "description": "API Description SDK",
@@ -21,3 +21,3 @@ "author": "Apiary.io <[e-mail]>",
     "minim": "^0.23.1",
-    "minim-parse-result": "^0.11.0"
+    "minim-parse-result": "^0.11.1"
   },
@@ -31,3 +31,4 @@ "devDependencies": {
     "node": ">=6"
-  }
+  },
+  "gitHead": "853dfac567e80f4c57b6058eabcc231d282753a5"
 }

README.md

@@ -120,2 +120,25 @@ # Fury.js
 
+Note about `mediaTypes`: it allows two kinds of definitions. First one is **array** type. It is intended to "catch all" implementation.
+It is useful if your adapter implements only one of fury methods, or if all methods accepts same types of Media Type.
+
+Another possible option is to use object with mapping name of method to array of MediaTypes. It allows better granularity for detection.
+
+Examples:
+
+If your adapter support just one method or all methods supports same kind of input Media Type:
+
+```js
+export const mediaTypes = ['text/vnd.my-adapter'];
+```
+
+If you need to distinguish among supported input Media Types for methods use:
+
+```js
+export const mediaTypes = {
+  parse: ['text/vnd.my-parsing', 'text/vnd.another-supported-parsing'],
+  serialize: ['text/vnd.my-serialization'],
+  };
+```
+
+
 Adapters are made up of a name, a list of media types, and up to three optional public functions: `detect`, `parse`, and `serialize`. A simple example might look like this:
@@ -127,9 +150,12 @@
 
-export function detect(source) {
+export function detect(source[, method]) {
   // If no media type is know, then we fall back to auto-detection. Here you
   // can check the source and see if you think you can parse it.
+  // 
+  // optional parmeter `method` give you hint about caller is going to invoke
+  // note that value can be undefined
   return source.match(/some-test/i) !== null;
 }
 
-export function parse({minim, generateSourceMap, source}, done) {
+export function parse({minim, generateSourceMap, mediaType, source}, done) {
   // Here you convert the source into refract elements. Use the `minim`
@@ -142,3 +168,3 @@ // variable to access refract element classes.
 
-export function validate({minim, source}, done) {
+export function validate({minim, mediaType, source}, done) {
   // Here you validate the source and return a parse result for any warnings or
@@ -152,3 +178,3 @@ // errors.
 
-export function serialize({api, minim}, done) {
+export function serialize({api, mediaType, minim}, done) {
   // Here you convert `api` from javascript element objects to the serialized
@@ -155,0 +181,0 @@ // source format.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20090

increased by21.3%

Lines of code

216

increased by67.44%

Number of lines in readme file

199

increased by15.03%

Dependency changes

• Updatedminim-parse-result@^0.11.1