js: make method parameters objects

--

* As requested by using parties, the options to be passed into the
  methods are now objects, with the objects' properties better
  describing what they do, and to avoid the need to type several nulls
  in a method call if one wants the last parameter.
  - src/Keyring.js, src/gpgme.js: Changed parameters and their
    validations
  - BrowserTest/*.js Had to adapt quite some calls to the new format

1 files changed, 86 insertions, 57 deletions

diff --git a/lang/js/src/Keyring.js b/lang/js/src/Keyring.js
index cb053ba1..d6ba1d6f 100644
--- a/lang/js/src/Keyring.js
+++ b/lang/js/src/Keyring.js
@@ -35,27 +35,38 @@ export class GPGME_Keyring {
     /**
      * Queries Keys (all Keys or a subset) from gnupg.
      *
-     * @param {String | Array<String>} pattern (optional) A pattern to
+     * @param {Object} options
+     * @param {String | Array<String>} options.pattern (optional) A pattern to
      * search for in userIds or KeyIds.
-     * @param {Boolean} prepare_sync (optional) if set to true, most data
-     * (with the exception of armored Key blocks) will be cached for the
+     * @param {Boolean} options.prepare_sync (optional) if set to true, most
+     * data (with the exception of armored Key blocks) will be cached for the
      * Keys. This enables direct, synchronous use of these properties for
      * all keys. It does not check for changes on the backend. The cached
      * information can be updated with the {@link Key.refresh} method.
-     * @param {Boolean} search (optional) retrieve Keys from external
+     * @param {Boolean} options.search (optional) retrieve Keys from external
      * servers with the method(s) defined in gnupg (e.g. WKD/HKP lookup)
      * @returns {Promise<Array<GPGME_Key>>}
      * @static
      * @async
      */
-    getKeys (pattern, prepare_sync=false, search=false){
+    getKeys (options){
+        if (options && typeof options !== 'object'){
+            return Promise.reject(gpgme_error('PARAM_WRONG'));
+        }
         return new Promise(function (resolve, reject) {
             let msg = createMessage('keylist');
-            if (pattern !== undefined && pattern !== null){
-                msg.setParameter('keys', pattern);
+            if (options && options.pattern) {
+                if (
+                    typeof options.pattern === 'string'
+                    || Array.isArray(options.pattern)
+                ){
+                    msg.setParameter('keys', options.pattern);
+                } else {
+                    reject(gpgme_error('PARAM_WRONG'));
+                }
             }
             msg.setParameter('sigs', true);
-            if (search === true){
+            if (options && options.search === true){
                 msg.setParameter('locate', true);
             }
             msg.post().then(function (result){
@@ -64,11 +75,11 @@ export class GPGME_Keyring {
                     resolve([]);
                 } else {
                     let secondrequest;
-                    if (prepare_sync === true) {
+                    if (options && options.prepare_sync === true) {
                         secondrequest = function () {
                             let msg2 = createMessage('keylist');
-                            if (pattern){
-                                msg2.setParameter('keys', pattern);
+                            if (options.pattern){
+                                msg2.setParameter('keys', options.pattern);
                             }
                             msg2.setParameter('secret', true);
                             return msg2.post();
@@ -80,7 +91,7 @@ export class GPGME_Keyring {
                     }
                     secondrequest().then(function (answer) {
                         for (let i=0; i < result.keys.length; i++){
-                            if (prepare_sync === true){
+                            if (options.prepare_sync === true){
                                 if (answer && answer.keys) {
                                     for (let j=0;
                                         j < answer.keys.length; j++ ){
@@ -100,7 +111,7 @@ export class GPGME_Keyring {
                                 }
                             }
                             let k = createKey(result.keys[i].fingerprint,
-                                !prepare_sync, result.keys[i]);
+                                !options.prepare_sync, result.keys[i]);
                             resultset.push(k);
                         }
                         resolve(resultset);
@@ -126,31 +137,42 @@ export class GPGME_Keyring {
     /**
      * Fetches the armored public Key blocks for all Keys matching the
      * pattern (if no pattern is given, fetches all keys known to gnupg).
-     * @param {String|Array<String>} pattern (optional) The Pattern to
+     * @param {Object} options (optional)
+     * @param {String|Array<String>} options.pattern The Pattern to
      * search for
-     * @param {Boolean} with_secret_fpr (optional) also return a list of
+     * @param {Boolean} options.with_secret_fpr also return a list of
      * fingerprints for the keys that have a secret key available
      * @returns {Promise<exportResult|GPGME_Error>} Object containing the
      * armored Key(s) and additional information.
      * @static
      * @async
      */
-    getKeysArmored (pattern, with_secret_fpr) {
+    getKeysArmored (options) {
+        if (options && typeof options !== 'object'){
+            return Promise.reject(gpgme_error('PARAM_WRONG'));
+        }
         return new Promise(function (resolve, reject) {
             let msg = createMessage('export');
             msg.setParameter('armor', true);
-            if (with_secret_fpr === true) {
+            if (options.with_secret_fpr === true) {
                 msg.setParameter('with-sec-fprs', true);
             }
-            if (pattern !== undefined && pattern !== null){
-                msg.setParameter('keys', pattern);
+            if (options.pattern){
+                if (
+                    typeof options.pattern === 'string'
+                    || Array.isArray(options.pattern)
+                ){
+                    msg.setParameter('keys', options.pattern);
+                }
             }
             msg.post().then(function (answer){
                 const result = { armored: answer.data };
-                if (with_secret_fpr === true
-                    && answer.hasOwnProperty('sec-fprs')
-                ) {
-                    result.secret_fprs = answer['sec-fprs'];
+                if (options.with_secret_fpr === true){
+                    if (answer.hasOwnProperty('sec-fprs')){
+                        result.secret_fprs = answer['sec-fprs'];
+                    } else {
+                        result.secret_fprs = [];
+                    }
                 }
                 resolve(result);
             }, function (error){
@@ -300,7 +322,6 @@ export class GPGME_Keyring {
                     changes.signature = (result.status & 4) === 4;
                     changes.subkey = (result.status & 8) === 8;
                     // 16 new secret key: not implemented
-
                     fprs.push(result.fingerprint);
                     infos[result.fingerprint] = {
                         changes: changes,
@@ -309,19 +330,20 @@ export class GPGME_Keyring {
                 }
                 let resultset = [];
                 if (prepare_sync === true){
-                    me.getKeys(fprs, true).then(function (result){
-                        for (let i=0; i < result.length; i++) {
-                            resultset.push({
-                                key: result[i],
-                                changes:
-                                    infos[result[i].fingerprint].changes,
-                                status: infos[result[i].fingerprint].status
-                            });
-                        }
-                        resolve({ Keys:resultset,summary: summary });
-                    }, function (error){
-                        reject(error);
-                    });
+                    me.getKeys({ pattern: fprs, prepare_sync: true })
+                        .then(function (result){
+                            for (let i=0; i < result.length; i++) {
+                                resultset.push({
+                                    key: result[i],
+                                    changes:
+                                        infos[result[i].fingerprint].changes,
+                                    status: infos[result[i].fingerprint].status
+                                });
+                            }
+                            resolve({ Keys:resultset,summary: summary });
+                        }, function (error){
+                            reject(error);
+                        });
                 } else {
                     for (let i=0; i < fprs.length; i++) {
                         resultset.push({
@@ -364,42 +386,49 @@ export class GPGME_Keyring {
      * Generates a new Key pair directly in gpg, and returns a GPGME_Key
      * representing that Key. Please note that due to security concerns,
      * secret Keys can not be deleted or exported from inside gpgme.js.
-     *
-     * @param {String} userId The user Id, e.g. 'Foo Bar <[email protected]>'
-     * @param {String} algo (optional) algorithm (and optionally key size)
-     * to be used. See {@link supportedKeyAlgos} below for supported
+     * @param {Object} options
+     * @param {String} option.userId The user Id, e.g. 'Foo Bar <[email protected]>'
+     * @param {String} option.algo (optional) algorithm (and optionally key
+     * size) to be used. See {@link supportedKeyAlgos} below for supported
      * values. If ommitted, 'default' is used.
-     * @param {Number} expires (optional) Expiration time in seconds from now.
-     * If not set or set to 0, expiration will be 'never'
-     * @param {String} subkey_algo (optional) algorithm of the encryption
-     * subkey. If ommited the same as algo is used.
+     * @param {Number} option.expires (optional) Expiration time in seconds
+     * from now. If not set or set to 0, expiration will be 'never'
+     * @param {String} options.subkey_algo (optional) algorithm of the
+     * encryption subkey. If ommited the same as algo is used.
      *
      * @return {Promise<Key|GPGME_Error>}
      * @async
      */
-    generateKey (userId, algo = 'default', expires, subkey_algo){
-        if (
-            typeof (userId) !== 'string' ||
+    generateKey (options){
+        if (!options
+            || typeof options !== 'object'
+            || typeof options.userId !== 'string'
             // eslint-disable-next-line no-use-before-define
-            supportedKeyAlgos.indexOf(algo) < 0 ||
-            (expires && !( Number.isInteger(expires) || expires < 0 ))
+            || ( options.algo && supportedKeyAlgos.indexOf(options.algo) < 0 )
+            || ( options.expires && !(
+                Number.isInteger(options.expires) || options.expires < 0 ) )
         ){
             return Promise.reject(gpgme_error('PARAM_WRONG'));
         }
         // eslint-disable-next-line no-use-before-define
-        if (subkey_algo && supportedKeyAlgos.indexOf(subkey_algo) < 0 ){
+        if (options.subkey_algo && supportedKeyAlgos.indexOf(
+            options.subkey_algo) < 0
+        ){
             return Promise.reject(gpgme_error('PARAM_WRONG'));
         }
         let me = this;
         return new Promise(function (resolve, reject){
             let msg = createMessage('createkey');
-            msg.setParameter('userid', userId);
-            msg.setParameter('algo', algo );
-            if (subkey_algo) {
-                msg.setParameter('subkey-algo', subkey_algo );
+            msg.setParameter('userid', options.userId);
+            if (!options.algo){
+                options.algo === 'default';
+            }
+            msg.setParameter('algo', options.algo);
+            if (options.subkey_algo) {
+                msg.setParameter('subkey-algo', options.subkey_algo );
             }
-            if (expires){
-                msg.setParameter('expires', expires);
+            if (options.expires){
+                msg.setParameter('expires', options.expires);
             } else {
                 msg.setParameter('expires', 0);
             }