refactor: separate 'parse' and 'compile'

Close #27, close #103

BREAKING CHANGE: There won't be any wrapper code called Dredd Transactions anymore. The public interface now splits into two parts, two explicit steps, two distinct responsibilities: parse, and compile

README.md

@@ -48,32 +48,46 @@ Dredd Transactions library is written in JavaScript (ES2015+).
 
 ## Usage
 
-### `compile`
+### `parse`
 
-Compiles *HTTP Transactions* from given API description document.
+Parses given API description document into API Elements with options specific
+to Dredd. Assumes that documents with unrecognizable format are
+[API Blueprint][api-blueprint]. Turns any parser failures, including
+the unexpected ones, into [API Elements][api-elements] annotations.
 
 ```javascript
-var dt = require('dredd-transactions');
+const parse = require('dredd-transactions/parse');
+// const { parse } = require('dredd-transactions');
 
-dt.compile('# My API\n...', 'apiary.apib', function (error, compileResult) {
+parse('# My API\n...', (error, parseResult) => {
   // ...
 });
 ```
 
-### Arguments
+### `compile`
+
+Compiles *HTTP Transactions* from given [API Elements][api-elements]. *HTTP Transactions* are a backbone data structure to Dredd.
 
-- (string) - API description document provided as string.
-- (string) - Original file name of the API description document. **To be removed! See [#6][filename-deprecation].**
-- (function) - Callback.
+```javascript
+const compile = require('dredd-transactions/compile');
+// const { compile } = require('dredd-transactions');
 
-### Callback Arguments
+const compileResult = compile(mediaType, apiElements, filename);
+```
 
-- (enum[null, object]) - Standard JavaScript error object.
-- ([Compile Result][compile-result-object-spec])
+> **Note:** The `filename` argument is optional and about to get deprecated, see [#6][filename-deprecation]
 
 
 ## Data Structures
 
+<a name="parse-result-object"></a>
+### Parse Result (object)
+
+Result of parsing.
+
+- `mediaType`: `text/vnd.apiblueprint` (string, default, nullable) - Media type of the input format, can be empty in case of some fatal errors
+- `apiElements` ([API Elements][api-elements]) - API Elements parse result
+
 <a name="compile-result-object"></a>
 ### Compile Result (object)
 
@@ -161,9 +175,10 @@ Description of an error or warning which occurred during parsing of the API desc
 > **Note:** These properties are to be superseded by whatever comes out of the proposal in [apiaryio/dredd#227](https://github.com/apiaryio/dredd/issues/227).
 
 
-[dredd]: https://github.com/apiaryio/dredd
+[dredd]: https://dredd.org
 [mson-spec]: https://github.com/apiaryio/mson
 [api-elements]: http://api-elements.readthedocs.org/
+[api-blueprint]: https://apiblueprint.org/
 [api-blueprint-glossary]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md
 [blueprint-transactions]: https://github.com/apiaryio/blueprint-transactions/
 

lib/index.js

@@ -1,25 +1,5 @@
 const parse = require('./parse');
-const compileFromApiElements = require('./compile');
+const compile = require('./compile');
 
 
-function compile(apiDescription, filename, callback) {
-  parse(apiDescription, (err, parseResult) => {
-    // Shouldn't happen, 'parse' turns all parser crashes into annotations
-    if (err) { callback(err); return; }
-
-    // Should always set annotations and never throw, try/catch deals only
-    // with unexpected compiler crashes
-    let compileResult;
-    try {
-      const { mediaType, apiElements } = parseResult;
-      compileResult = compileFromApiElements(mediaType, apiElements, filename);
-    } catch (syncErr) {
-      callback(syncErr);
-      return;
-    }
-    callback(null, compileResult);
-  });
-}
-
-
-module.exports = { compile };
+module.exports = { compile, parse };

scripts/smoke.sh

@@ -56,10 +56,29 @@ if [ ! -z "$TRAVIS" ]; then
       "The packaging of Dredd Transactions should have prevented this."
     echo "======================================================================"
     exit 1
-  else
-    echo "SUCCESS"
-    echo "======================================================================"
   fi
+
+  echo "Importing dredd-transactions"
+  echo "======================================================================"
+  echo "const assert = require('assert');" > index.js
+  echo "const dt = require('dredd-transactions');" >> index.js
+  echo "assert.ok(typeof dt.parse === 'function');" >> index.js
+  echo "assert.ok(typeof dt.compile === 'function');" >> index.js
+  node index.js
+
+  echo "======================================================================"
+  echo "Importing dredd-transactions/parse and dredd-transactions/compile"
+  echo "======================================================================"
+  echo "const assert = require('assert');" > index.js
+  echo "const parse = require('dredd-transactions/parse');" >> index.js
+  echo "const compile = require('dredd-transactions/compile');" >> index.js
+  echo "assert.ok(typeof parse === 'function');" >> index.js
+  echo "assert.ok(typeof compile === 'function');" >> index.js
+  node index.js
+
+  echo "======================================================================"
+  echo "SUCCESS"
+  echo "======================================================================"
 else
   exit 1
 fi

test/integration/compile-test.js

@@ -147,7 +147,7 @@ describe('compile() · all API description formats', () => {
     fixtures('ordinary').forEachDescribe(({ mediaType, apiElements }) => {
       const message = '... dummy warning message ...';
       const stubbedCompile = proxyquire('../../lib/compile', {
-        './compileURI': proxyquire('../../lib/compileURI', {
+        './compileURI': proxyquire('../../lib/compile/compileURI', {
           './expandURItemplate': () => ({ uri: '/honey?beekeeper=Honza', errors: [], warnings: [message] }),
         }),
       });
@@ -208,7 +208,7 @@ describe('compile() · all API description formats', () => {
     fixtures('ordinary').forEachDescribe(({ mediaType, apiElements }) => {
       const message = '... dummy warning message ...';
       const stubbedCompile = proxyquire('../../lib/compile', {
-        './compileURI': proxyquire('../../lib/compileURI', {
+        './compileURI': proxyquire('../../lib/compile/compileURI', {
           './validateParams': () => ({ errors: [], warnings: [message] }),
         }),
       });

test/integration/compileAPIB-test.js

@@ -3,7 +3,7 @@ const proxyquire = require('proxyquire').noPreserveCache();
 
 const createAnnotationSchema = require('../schemas/createAnnotationSchema');
 const createCompileResultSchema = require('../schemas/createCompileResultSchema');
-const detectTransactionExampleNumbers = require('../../lib/detectTransactionExampleNumbers');
+const detectTransactionExampleNumbers = require('../../lib/compile/detectTransactionExampleNumbers');
 
 const { assert, fixtures } = require('../support');
 const compile = require('../../lib/compile');

test/integration/compileOpenAPI2-test.js

@@ -3,7 +3,7 @@ const proxyquire = require('proxyquire');
 
 const createAnnotationSchema = require('../schemas/createAnnotationSchema');
 const createCompileResultSchema = require('../schemas/createCompileResultSchema');
-const detectTransactionExampleNumbers = require('../../lib/detectTransactionExampleNumbers');
+const detectTransactionExampleNumbers = require('../../lib/compile/detectTransactionExampleNumbers');
 
 const { assert, fixtures } = require('../support');
 const compile = require('../../lib/compile');

test/unit/compileTransactionName-test.js

@@ -1,6 +1,6 @@
 const { assert } = require('chai');
 
-const compileTransactionName = require('../../lib/compileTransactionName');
+const compileTransactionName = require('../../lib/compile/compileTransactionName');
 
 
 describe('compileTransactionName()', () => {

test/unit/compileURI/compileParams-test.js

@@ -1,7 +1,7 @@
 const { assert } = require('chai');
 const fury = require('fury');
 
-const compileParams = require('../../../lib/compileURI/compileParams');
+const compileParams = require('../../../lib/compile/compileURI/compileParams');
 
 
 describe('compileParams()', () => {