feat(form): add a form serializer (#509)

* feat(form): add multipart/form-data serializer

* test(form): add multipart/form-data serializer tests

* test(form): add data structures tests

* chore(form): change fury to apielements/core and mocha version

* feat(form): add application/x-www-form-urlencoded support

* chore(form): add engine specification

* chore(form): change eslint version

Author: Natalie Mikešová

commitlint.config.js

@@ -10,6 +10,7 @@ module.exports = {
       'apib',
       'apiaryb',
       'remote',
+      'form',
       'deps',
       'deps-dev',
     ]],

packages/form-serializer/README.md

@@ -0,0 +1,13 @@
+# API Elements: Multipart / Form data serializer
+
+## Usage
+
+```js
+const formSerializer = require('@apielements/form-serializer');
+fury.use(formSerializer);
+
+const mediaType = 'multipart/form-data';
+fury.serialize({ api, mediatype }, (error, body) => {
+    console.log(body);
+});
+```

packages/form-serializer/lib/adapter.js

@@ -0,0 +1,10 @@
+const serializeForm = require('./serializeForm');
+
+const name = 'form';
+const mediaTypes = ['multipart/form-data', 'application/x-www-form-urlencoded'];
+
+function serialize({ api, mediaType }) {
+  return new Promise(resolve => resolve(serializeForm({ api, mediaType })));
+}
+
+module.exports = { name, mediaTypes, serialize };

packages/form-serializer/lib/serializeForm.js

@@ -0,0 +1,58 @@
+const _ = require('lodash');
+const querystring = require('querystring');
+
+function collectElementByIDs(element) {
+  const dataStructures = {};
+
+  if (typeof element.content === 'string') {
+    dataStructures.undefined = element.content;
+    return dataStructures;
+  }
+
+  const { parents } = element;
+  if (parents) {
+    const rootElement = parents.get(0);
+
+    if (rootElement) {
+      rootElement.recursiveChildren.forEach((element) => {
+        if (element.id) {
+          dataStructures[element.id.toValue()] = element;
+        }
+      });
+    }
+  }
+
+  return dataStructures;
+}
+
+function serializeForm({ api, mediaType }) {
+  const dataStructures = collectElementByIDs(api);
+  let values = api.valueOf(undefined, dataStructures);
+
+  if (mediaType === 'multipart/form-data') {
+    const boundary = 'BOUNDARY';
+
+    let content = '';
+
+    if (typeof values === 'string') {
+      content += `--${boundary}\r\n`;
+      content += 'Content-Disposition: form-data; name="undefined"\r\n\r\n';
+      content += `${values}\r\n`;
+    } else {
+      _.forOwn(values, (value, key) => {
+        content += `--${boundary}\r\n`;
+        content += `Content-Disposition: form-data; name="${key}"\r\n\r\n`;
+        content += `${value}\r\n`;
+      });
+    }
+
+    content += `--${boundary}--\r\n`;
+    return content;
+  }
+  if (typeof values === 'string') {
+    values = { undefined: values };
+  }
+  return querystring.encode(values);
+}
+
+module.exports = serializeForm;

packages/form-serializer/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@apielements/form-serializer",
+  "version": "0.1.0",
+  "description": "Multipart/form-data serializer for API Elements",
+  "author": "Apiary.io <support@apiary.io>",
+  "license": "MIT",
+  "main": "./lib/adapter.js",
+  "files": [
+    "lib/adapter.js",
+    "lib/serializeForm.js"
+  ],
+  "homepage": "https://github.com/apiaryio/api-elements.js/tree/master/packages/form-serializer",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apiaryio/api-elements.js.git",
+    "directory": "packages/form-serializer"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "lint:fix": "eslint . --fix",
+    "test": "mocha test"
+  },
+  "devDependencies": {
+    "chai": "^4.2.0",
+    "eslint": "^5.16.0",
+    "@apielements/core": "^0.1.0",
+    "mocha": "^7.1.1"
+  },
+  "peerDependencies": {
+    "@apielements/core": "^0.1.0"
+  },
+  "dependencies": {
+    "lodash": "^4.17.15"
+  },
+  "engines": {
+    "node": ">=8"
+  }
+}

packages/form-serializer/test/adapter-test.js

@@ -0,0 +1,72 @@
+const { Fury } = require('@apielements/core');
+const { expect } = require('chai');
+const adapter = require('../lib/adapter');
+
+describe('Form Serializer Adapter', () => {
+  let fury;
+
+  before(() => {
+    fury = new Fury();
+    fury.use(adapter);
+  });
+
+  describe('Multipart/form-data mediaType', () => {
+    it('has a name', () => {
+      expect(adapter.name).to.equal('form');
+    });
+
+    it('has a multipart/form-data media type', () => {
+      expect(adapter.mediaTypes).to.include('multipart/form-data');
+    });
+
+    it('can serialize an object element', (done) => {
+      const element = new fury.minim.elements.Object({ message: 'Hello world' });
+
+      fury.serialize({ api: element, mediaType: 'multipart/form-data' }, (error, result) => {
+        expect(error).to.be.null;
+        expect(result).to.equal('--BOUNDARY\r\nContent-Disposition: form-data; name="message"\r\n\r\nHello world\r\n--BOUNDARY--\r\n');
+        done();
+      });
+    });
+
+    it('can serialize a string element', (done) => {
+      const element = new fury.minim.elements.String('Hello world');
+
+      fury.serialize({ api: element, mediaType: 'multipart/form-data' }, (error, result) => {
+        expect(error).to.be.null;
+        expect(result).to.equal('--BOUNDARY\r\nContent-Disposition: form-data; name="undefined"\r\n\r\nHello world\r\n--BOUNDARY--\r\n');
+        done();
+      });
+    });
+  });
+
+  describe('Application/x-www-form-urlencoded mediaType', () => {
+    it('has a name', () => {
+      expect(adapter.name).to.equal('form');
+    });
+
+    it('has an application/x-www-form-urlencoded media type', () => {
+      expect(adapter.mediaTypes).to.include('application/x-www-form-urlencoded');
+    });
+
+    it('can serialize an object element', (done) => {
+      const element = new fury.minim.elements.Object({ message: 'Hello world' });
+
+      fury.serialize({ api: element, mediaType: 'application/x-www-form-urlencoded' }, (error, result) => {
+        expect(error).to.be.null;
+        expect(result).to.equal('message=Hello%20world');
+        done();
+      });
+    });
+
+    it('can serialize a string element', (done) => {
+      const element = new fury.minim.elements.String('Hello world');
+
+      fury.serialize({ api: element, mediaType: 'application/x-www-form-urlencoded' }, (error, result) => {
+        expect(error).to.be.null;
+        expect(result).to.equal('undefined=Hello%20world');
+        done();
+      });
+    });
+  });
+});

packages/form-serializer/test/serializeForm-test.js

@@ -0,0 +1,34 @@
+const { Fury } = require('@apielements/core');
+const { expect } = require('chai');
+const serializeForm = require('../lib/serializeForm.js');
+
+const { minim: namespace } = new Fury();
+
+describe('#serializeForm', () => {
+  it('can serialize a primitive element with value', () => {
+    const element = new namespace.elements.String('Hello world');
+
+    expect(serializeForm({ api: element, mediaType: 'multipart/form-data' })).to.equal('--BOUNDARY\r\nContent-Disposition: form-data; name="undefined"\r\n\r\nHello world\r\n--BOUNDARY--\r\n');
+  });
+
+  it('can serialize a primitive element with a default value', () => {
+    const element = new namespace.elements.String();
+    element.attributes.set('default', 'Hello world');
+
+    expect(serializeForm({ api: element, mediaType: 'multipart/form-data' })).to.equal('--BOUNDARY\r\nContent-Disposition: form-data; name="undefined"\r\n\r\nHello world\r\n--BOUNDARY--\r\n');
+  });
+
+  it('can serialize an element with references via parent tree', () => {
+    const element = new namespace.elements.Element();
+    element.element = 'message';
+
+    new namespace.elements.Category([
+      new namespace.elements.Category([
+        new namespace.elements.String('Hello world', { id: 'message' }),
+      ], { classes: ['dataStructures'] }),
+      element,
+    ]).freeze();
+
+    expect(serializeForm({ api: element, mediaType: 'multipart/form-data' })).to.equal('--BOUNDARY\r\nContent-Disposition: form-data; name="undefined"\r\n\r\nHello world\r\n--BOUNDARY--\r\n');
+  });
+});