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
apiaryio · Feb 26, 2019 · 99f41c2 · 99f41c2
1 parent 2826ffe
commit 99f41c2
Show file tree

Hide file tree

Showing 26 changed files with 79 additions and 276 deletions.
diff --git a/README.md b/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/
 

diff --git a/lib/compileTransactionName.js → compile/compileTransactionName.js b/lib/compileTransactionName.js → compile/compileTransactionName.js
diff --git a/lib/compileURI/compileParams.js → compile/compileURI/compileParams.js b/lib/compileURI/compileParams.js → compile/compileURI/compileParams.js
diff --git a/lib/compileURI/expandURItemplate.js → compile/compileURI/expandURItemplate.js b/lib/compileURI/expandURItemplate.js → compile/compileURI/expandURItemplate.js
diff --git a/lib/compileURI/index.js → compile/compileURI/index.js b/lib/compileURI/index.js → compile/compileURI/index.js
diff --git a/lib/compileURI/validateParams.js → compile/compileURI/validateParams.js b/lib/compileURI/validateParams.js → compile/compileURI/validateParams.js
diff --git a/lib/detectTransactionExampleNumbers.js → compile/detectTransactionExampleNumbers.js b/lib/detectTransactionExampleNumbers.js → compile/detectTransactionExampleNumbers.js
diff --git a/lib/compile.js → compile/index.js b/lib/compile.js → compile/index.js
diff --git a/index.js b/index.js
@@ -0,0 +1,5 @@
+const parse = require('./parse');
+const compile = require('./compile');
+
+
+module.exports = { parse, compile };
diff --git a/lib/index.js b/lib/index.js
diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "dredd-transactions",
   "version": "0.0.0-semantically-released",
   "description": "Compiles HTTP Transactions (Request-Response pairs) from an API description document",
-  "main": "lib/index.js",
+  "main": "index.js",
   "engines": {
     "node": ">= 6"
   },
@@ -24,7 +24,8 @@
     "url": "https://github.com/apiaryio/dredd-transactions"
   },
   "files": [
-    "lib",
+    "parse",
+    "compile",
     "README.md"
   ],
   "dependencies": {

diff --git a/lib/parse.js → parse/index.js b/lib/parse.js → parse/index.js
diff --git a/scripts/pretest.js b/scripts/pretest.js
@@ -5,7 +5,7 @@ const fs = require('fs');
 
 const fury = require('fury');
 
-const parse = require('../lib/parse');
+const parse = require('../parse');
 
 
 const FIXTURES_DIR = path.join(__dirname, '..', 'test', 'fixtures');

diff --git a/scripts/smoke.sh b/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
diff --git a/test/integration/compile-test.js b/test/integration/compile-test.js
@@ -4,7 +4,7 @@ const createAnnotationSchema = require('../schemas/createAnnotationSchema');
 const createCompileResultSchema = require('../schemas/createCompileResultSchema');
 
 const { assert, fixtures } = require('../support');
-const compile = require('../../lib/compile');
+const compile = require('../../compile');
 
 
 describe('compile() · all API description formats', () => {
@@ -146,8 +146,8 @@ describe('compile() · all API description formats', () => {
     // we need to pretend it's possible in this test.
     fixtures('ordinary').forEachDescribe(({ mediaType, apiElements }) => {
       const message = '... dummy warning message ...';
-      const stubbedCompile = proxyquire('../../lib/compile', {
-        './compileURI': proxyquire('../../lib/compileURI', {
+      const stubbedCompile = proxyquire('../../compile', {
+        './compileURI': proxyquire('../../compile/compileURI', {
           './expandURItemplate': () => ({ uri: '/honey?beekeeper=Honza', errors: [], warnings: [message] }),
         }),
       });
@@ -207,8 +207,8 @@ describe('compile() · all API description formats', () => {
     // test.
     fixtures('ordinary').forEachDescribe(({ mediaType, apiElements }) => {
       const message = '... dummy warning message ...';
-      const stubbedCompile = proxyquire('../../lib/compile', {
-        './compileURI': proxyquire('../../lib/compileURI', {
+      const stubbedCompile = proxyquire('../../compile', {
+        './compileURI': proxyquire('../../compile/compileURI', {
           './validateParams': () => ({ errors: [], warnings: [message] }),
         }),
       });

diff --git a/test/integration/compileAPIB-test.js b/test/integration/compileAPIB-test.js
@@ -3,10 +3,10 @@ const proxyquire = require('proxyquire').noPreserveCache();
 
 const createAnnotationSchema = require('../schemas/createAnnotationSchema');
 const createCompileResultSchema = require('../schemas/createCompileResultSchema');
-const detectTransactionExampleNumbers = require('../../lib/detectTransactionExampleNumbers');
+const detectTransactionExampleNumbers = require('../../compile/detectTransactionExampleNumbers');
 
 const { assert, fixtures } = require('../support');
-const compile = require('../../lib/compile');
+const compile = require('../../compile');
 
 
 describe('compile() · API Blueprint', () => {
@@ -52,7 +52,7 @@ describe('compile() · API Blueprint', () => {
 
   describe('with multiple transaction examples', () => {
     const detectTransactionExampleNumbersStub = sinon.spy(detectTransactionExampleNumbers);
-    const stubbedCompile = proxyquire('../../lib/compile', {
+    const stubbedCompile = proxyquire('../../compile', {
       './detectTransactionExampleNumbers': detectTransactionExampleNumbersStub,
     });
     const { mediaType, apiElements } = fixtures('multiple-transaction-examples').apib;
@@ -99,7 +99,7 @@ describe('compile() · API Blueprint', () => {
 
   describe('without multiple transaction examples', () => {
     const detectTransactionExampleNumbersStub = sinon.spy(detectTransactionExampleNumbers);
-    const stubbedCompile = proxyquire('../../lib/compile', {
+    const stubbedCompile = proxyquire('../../compile', {
       './detectTransactionExampleNumbers': detectTransactionExampleNumbersStub,
     });
     const { mediaType, apiElements } = fixtures('one-transaction-example').apib;

diff --git a/test/integration/compileOpenAPI2-test.js b/test/integration/compileOpenAPI2-test.js
@@ -3,10 +3,10 @@ const proxyquire = require('proxyquire');
 
 const createAnnotationSchema = require('../schemas/createAnnotationSchema');
 const createCompileResultSchema = require('../schemas/createCompileResultSchema');
-const detectTransactionExampleNumbers = require('../../lib/detectTransactionExampleNumbers');
+const detectTransactionExampleNumbers = require('../../compile/detectTransactionExampleNumbers');
 
 const { assert, fixtures } = require('../support');
-const compile = require('../../lib/compile');
+const compile = require('../../compile');
 
 
 describe('compile() · OpenAPI 2', () => {
@@ -135,7 +135,7 @@ describe('compile() · OpenAPI 2', () => {
   describe('with multiple responses', () => {
     const filename = 'apiDescription.json';
     const detectTransactionExampleNumbersStub = sinon.spy(detectTransactionExampleNumbers);
-    const stubbedCompile = proxyquire('../../lib/compile', {
+    const stubbedCompile = proxyquire('../../compile', {
       './detectTransactionExampleNumbers': detectTransactionExampleNumbersStub,
     });
     const { mediaType, apiElements } = fixtures('multiple-responses').openapi2;

diff --git a/test/integration/compileOpenAPI3-test.js b/test/integration/compileOpenAPI3-test.js
@@ -1,7 +1,7 @@
 const createCompileResultSchema = require('../schemas/createCompileResultSchema');
 
 const { assert, fixtures } = require('../support');
-const compile = require('../../lib/compile');
+const compile = require('../../compile');
 
 
 describe('compile() · OpenAPI 3', () => {