Input validation

readme.md

@@ -488,6 +488,12 @@ The query to be displayed by the prompt.
 
 The name of the attribute under which the prompt result will be saved, inside the returned object.
 
+#### `validate`
+
+- Type: `Array`
+
+Contains a list of validators to run when user input is available. Specifying this is **optional**. For the sturucture of a validator please refer to [validation](#Input-Validation).
+
 #### qoa.`input({ type, query, handle })`
 
 - Type: `Function`
@@ -515,6 +521,12 @@ The query to be displayed by the prompt.
 
 The name of the attribute under which the prompt result will be saved, inside the returned object.
 
+#### `validate`
+
+- Type: `Array`
+
+Contains a list of validators to run when user input is available. Specifying this is **optional**. For the sturucture of a validator please refer to [validation](#Input-Validation).
+
 #### qoa.`interactive({ type, query, handle, symbol, menu })`
 
 - Type: `Function`
@@ -669,6 +681,12 @@ The query to be displayed by the prompt.
 
 The name of the attribute under which the prompt result will be saved, inside the returned object.
 
+#### `validate`
+
+- Type: `Array`
+
+Contains a list of validators to run when user input is available. Specifying this is **optional**. For the sturucture of a validator please refer to [validation](#Input-Validation).
+
 #### qoa.`config({ prefix, underlineQuery })`
 
 - Type: `Function`
@@ -723,6 +741,56 @@ Underline the query of each prompt.
 
 Move the cursor to the top-left corner of the console and clear everything below it.
 
+## Input validation
+
+3 of the available prompts support input validation: `input`, `hidden` and `secure`.  
+A validator object consists of the following:
+
+##### `name`
+
+- Type: `String`
+
+The name of the validator.
+
+##### `validate`
+
+- Type: `Function`
+
+A function to validate the input. The first argument given to the function is the user input. The function should return either `true` or `false` to indicate the success/fail of the validation.
+
+##### `warning`
+
+- Type: `String`
+
+The warning message to print, when the validation fails. This setting is **optional**.
+
+#### Example
+```js
+const qoa = require('qoa');
+
+const {log} = console;
+
+const ps = [
+  {
+    type: 'input',
+    query: 'Type your username:',
+    handle: 'username',
+    validate: [
+      {
+        name: 'min_length_8',
+        validate: (answer) => answer.length >= 8,
+        warning: 'The input is less than 8 characters long',
+      }
+    ]
+  },
+];
+
+qoa.prompt(ps).then(log);
+//=> { username: 'user', username_validators: {min_length_8: false} }
+```
+As you can see, the validators appear in the result prefixed with the handle you specified. In this case `username_validators`.  
+This object contains every validator result, that was tested on the current answer, where the **key** is the name of the validator and the **value** is the result of the `validate` function.
+
 ## Development
 
 For more info on how to contribute to the project, please read the [contributing guidelines](https://github.com/klaussinani/qoa/blob/master/contributing.md).

src/hidden.js

@@ -53,6 +53,10 @@ class Hidden extends Text {
         result[this._handle] = secret;
         this._input.removeListener('keypress', onkeypress);
         prompt.close();
+        if (this._validators.length > 0) {
+          result[this._handle + '_validators'] = this._validateInput(secret);
+        }
+
         resolve(result);
       });
     });

src/input.js

@@ -15,6 +15,10 @@ class Input extends Text {
       prompt.question(this._formatQuery(), answer => {
         result[this._handle] = answer;
         prompt.close();
+        if (this._validators.length > 0) {
+          result[this._handle + '_validators'] = this._validateInput(answer);
+        }
+
         resolve(result);
       });
     });

src/secure.js

@@ -62,6 +62,10 @@ class Secure extends Text {
         result[this._handle] = secret;
         this._input.removeListener('keypress', onkeypress);
         prompt.close();
+        if (this._validators.length > 0) {
+          result[this._handle + '_validators'] = this._validateInput(secret);
+        }
+
         resolve(result);
       });
     });

src/text.js

@@ -7,6 +7,7 @@ class Text extends Prompt {
     super(opts);
     this._historySize = 0;
     this._promptSymbol = '';
+    this._validators = opts.validate || [];
   }
 
   get _promptOpts() {
@@ -30,6 +31,20 @@ class Text extends Prompt {
   _removeLastChar(x) {
     return x.slice(0, x.length - 1);
   }
+
+  _validateInput(answer) {
+    const result = {};
+    this._validators.forEach(validator => {
+      const validationResult = validator.validate(answer);
+      if (!validationResult && validator.warning) {
+        console.log(validator.warning);
+      }
+
+      result[validator.name] = validationResult;
+    });
+
+    return result;
+  }
 }
 
 module.exports = Text;