feat: Introduced options property for including wrong answers

MilosPaunovic · MilosPaunovic · commit af97dcb15a0e · 2022-09-30T09:42:00.000+02:00
diff --git a/.eslintignore b/.eslintignore
@@ -1,3 +1,3 @@
 /dist/*
-/questions/*
-/test/*
+/node_modules/*
+/questions/*
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -18,5 +18,14 @@ module.exports = {
 		'linebreak-style': 'off',
 		'no-unused-vars': 'off',
 		'no-param-reassign': 'off',
+		'no-underscore-dangle': 'off',
 	},
+	overrides: [
+		{
+			files: ['test/*'],
+			rules: {
+				'no-unused-expressions': 'off',
+			},
+		},
+	],
 };
diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml
@@ -1,6 +1,7 @@
 name: Testing
 
 on:
+  workflow_dispatch:
   pull_request:
     types: [opened, synchronize]
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,12 +1,31 @@
-## [1.0.4](https://github.com/MilosPaunovic/questionnaire/compare/1.0.3...1.0.4)
+# Changelog
+
+## [2.0.0](https://github.com/MilosPaunovic/questionnaire/compare/1.0.4...2.0.0) - 2022-09-30
+
+### Breaking changes
+
+This major release introduces a breaking change as the method `questions()` now expects an object parameter, instead of number, like in the previous versions.
+
+### Added
+
+* Allowed options argument to be passed for recieving wrong answers, as well as the correct one. 
+
+## [1.0.4](https://github.com/MilosPaunovic/questionnaire/compare/1.0.3...1.0.4) - 2022-09-28
+
+### Fixed
 
 * Included question data files into the final bundle.
 
-## [1.0.3](https://github.com/MilosPaunovic/questionnaire/compare/1.0.2...1.0.3)
+## [1.0.3](https://github.com/MilosPaunovic/questionnaire/compare/1.0.2...1.0.3) - 2022-09-28
+
+### Changed
 
-* Trimmed down list of questions following the [advice](https://www.linkedin.com/feed/update/urn:li:activity:6980753295447330816?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A6980753295447330816%2C6980847167380803586%29) of the initial answers creator.
 * Improved the way of library bundling.
 
-## [1.0.2](https://github.com/MilosPaunovic/questionnaire/commits/1.0.2)
+### Removed
+
+* Trimmed down list of questions following the [advice](https://www.linkedin.com/feed/update/urn:li:activity:6980753295447330816?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A6980753295447330816%2C6980847167380803586%29) of the initial answers creator.
+
+## [1.0.2](https://github.com/MilosPaunovic/questionnaire/commits/1.0.2) - 2022-09-28
 
-* Initial release with two variations of questions in Serbian (Latin and Cyrillic) and two methods, question and questions.
+_Initial release._
diff --git a/README.md b/README.md
@@ -42,22 +42,31 @@ Currently available country codes and variations:
 
 #### Question
 
-Returns random question from the list in the object form, containing both question and answer properties.
+Returns random question from the list in the object form, containing question and answer properties.
 
 ```js
-QUESTIONNAIRE.question();
+QUESTIONNAIRE.question(); // => { question: 'QUESTION', answer: 'ANSWER' }
+```
+
+Returns random question from the list in the object form, containing question, answer and wrong (containg number of wrong answers you've specified, in range from 1 to 30) properties.
 
-// => { question: 'QUESTION', answer: 'ANSWER' }
+```js
+QUESTIONNAIRE.question({ wrong: 3}); // => { question: 'QUESTION', answer: 'ANSWER', wrong: ['WRONG', 'WRONG', 'WRONG'] }
 ```
 
+
 #### Questions
 
-Returns array of question objects from the list, defaults to 10, accepted values between 1 and 10000
+Returns an array of 10 question objects from the list.
 
 ```js
-QUESTIONNAIRE.questions(howMany = 10)
+QUESTIONNAIRE.questions() // => [{ question: 'QUESTION', answer: 'ANSWER' }, { question: 'QUESTION', answer: 'ANSWER' }...]
+```
+
+Returns an array of question objects with wrong answers (containg number of wrong answers you've specified, in range from 1 to 30) from the list (number of items defaults to 10, accepted range from 1 to 10000).
 
-// => [{ question: 'QUESTION', answer: 'ANSWER' }, { question: 'QUESTION', answer: 'ANSWER' }...]
+```js
+QUESTIONNAIRE.questions({ howMany: 7, wrong: 1 }) // => [{ question: 'QUESTION', answer: 'ANSWER', wrong: ['WRONG'] }, { question: 'QUESTION', answer: 'ANSWER', wrong: ['WRONG'] }...]
 ```
 
 ## Contributing
diff --git a/dist/questionnaire.js b/dist/questionnaire.js
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@paunovic/questionnaire",
-  "version": "1.0.4",
+  "version": "2.0.0",
   "description": "Serving random questions in multiple languages has never been this easy.",
   "author": "Milos Paunovic <paun992@hotmail.com>",
   "license": "MIT",
diff --git a/questions/README.md b/questions/README.md
@@ -6,7 +6,7 @@ Every questions entry should be simple JavaScript file which exports only one co
 
 ## Naming conventions
 
-Every questions file should be placed in folder named in the format of 2 digit ISO Country code, and the file name itself should be an IETF primary language tag, with optional IETF language subtag from other standards such as ISO 639, ISO 15924, ISO 3166-1 and UN M.49, if necessary. Example would be `rs/sr-Cyrl` for Serbian written in Cyrillic script.
+Every questions file should be placed in folder named in the format of 2 letter ISO Country code, and the file name itself should be an IETF primary language tag, with optional IETF language subtag from other standards such as ISO 639, ISO 15924, ISO 3166-1 and UN M.49, if necessary. Example would be `rs/sr-Cyrl` for Serbian written in Cyrillic script.
 
 Find out more at [Country Code](https://countrycode.org/) and [Wikipedia](https://en.wikipedia.org/wiki/IETF_language_tag).
 
diff --git a/src/helpers/general.js b/src/helpers/general.js
@@ -1,14 +1,54 @@
 /**
- * Function which returns random number for range between 1 and supplied maximum.
- *
- * @param {number} maximum - Parameter which tells the upper limit of generated random number
- * @return {number} Random number between 1 and suplied maximum
+ * Returns random number in range between 1 and supplied maximum.
  *
+ * @param {number} maximum Upper limit of generated random number.
+ * @return {number} Random number between 1 and suplied maximum.
  */
-
 export const randomNumber = (maximum) => {
-	if (!maximum) throw new Error('Missing parameter maximum.');
-	if (!parseInt(maximum, 10)) throw new Error('Parameter maximum must be convertible to number.');
+	if (!maximum) throw new Error('Parameter maximum is missing.');
+	if (!parseInt(maximum, 10)) throw new Error('Parameter maximum must be castable to integer.');
 
 	return Math.floor(Math.random() * parseInt(maximum, 10)) + 1;
 };
+
+/**
+ * Returns an array of random numbers in range between 1 and supplied maximum.
+ *
+ * @param {number} items Number of array items to be returned.
+ * @param {number} maximum Upper limit of generated random number.
+ * @return {number} Array of random numbers between 1 and suplied maximum.
+ */
+export const randomNumbers = (items, maximum) => {
+	if (!items) throw new Error('Parameter items is missing.');
+	if (!parseInt(items, 10)) throw new Error('Parameter items must be castable to integer.');
+
+	if (!maximum) throw new Error('Parameter maximum is missing.');
+	if (!parseInt(maximum, 10)) throw new Error('Parameter maximum must be castable to integer.');
+
+	const result = new Set();
+
+	while (result.size < items) {
+		result.add(randomNumber(maximum));
+	}
+
+	return Array.from(result);
+};
+
+/**
+ * Checks if the parameter can be casted to integer and, if so, limits the
+ * value to supplied minimum and maximum.
+ *
+ * @param {any} value Parameter value itself.
+ * @param {string} name Name of the parameter for error message.
+ * @param {number} minimum Lower limit of value.
+ * @param {number} maximum Upper limit of value.
+ * @return {number} Properly casted and limited value.
+ */
+export const parameterLimitter = (value, name, minimum, maximum) => {
+	if (!parseInt(value, 10)) throw new Error(`Parameter ${name} must be castable to integer.`);
+
+	if (parseInt(value, 10) < minimum) value = minimum;
+	if (parseInt(value, 10) > maximum) value = maximum;
+
+	return value;
+};
diff --git a/src/index.js b/src/index.js
@@ -1,62 +1,69 @@
 /*
- * @paunovic/questionnaire@1.0.4
+ * @paunovic/questionnaire@2.0.0
  * (c) Milos Paunovic
  * Released under the MIT License.
  */
 
 import { LANGUAGES } from './helpers/languages.js';
-import { randomNumber } from './helpers/general.js';
+import { randomNumber, randomNumbers, parameterLimitter } from './helpers/general.js';
 
 /**
-	* Initialize the package by selecting language and variation to use.
-	*
-	* @param {object} details Initial details for initialization, contains 2
-	* digit ISO country code and variation to language, e.g. "cyrillic"
-	* @return {object} Available functions to be consumed
-	*
-	*/
-
+ * Initialize the package by selecting language and variation to use.
+ *
+ * @param {object} details Details for library initialization.
+ * @param {string} [details.countryCode=rs] 2 letter ISO country code.
+ * @param {string} [details.variation=default] Variation of the language.
+ * @return {object} Available functions to be consumed.
+ */
 export const initialize = ({ countryCode = 'rs', variation = 'default' } = {}) => {
-	if (!LANGUAGES[countryCode]) throw new Error('Parameter countryCode is invalid.');
-	else if (!LANGUAGES[countryCode][variation]) throw new Error('Parameter variation is invalid.');
+	if (!LANGUAGES[countryCode]) throw new Error('Parameter countryCode is not valid.');
+	else if (!LANGUAGES[countryCode][variation]) throw new Error('Parameter variation is not valid.');
 
 	const QUESTIONS = LANGUAGES[countryCode][variation];
+	const AVAILABLE = QUESTIONS.length - 1;
 
 	/**
-		* Function which returns random question object from the list.
-		*
-		* @return {object} Random question object from the list
-		*
-		*/
+	 * Returns random question object from the list.
+	 *
+	 * @param {object} [options] Guidelines for question generation.
+	 * @param {number} [options.wrong] Number of wrong answers to be included.
+	 * @return {object} Random question object from the list.
+	 */
+	const question = ({ wrong } = {}) => {
+		if (!wrong) return QUESTIONS[randomNumber(AVAILABLE)];
 
-	const question = () => QUESTIONS[randomNumber(QUESTIONS.length - 1)];
-
-	/**
-		* Function which returns an array of random questions from the list.
-		*
-		* @param {number} [howMany=10] - Number of questions to be generated
-		* @return {object[]} Array of question objects from the list
-		*
-		*/
+		const _wrong = parameterLimitter(wrong, 'wrong', 1, 30);
+		const _indexes = randomNumbers(_wrong, AVAILABLE);
 
-	const questions = (howMany = 10) => {
-		if (!parseInt(howMany, 10)) throw new Error('Parameter howMany must be convertible to number.');
+		const _answers = [];
 
-		const NUMBER = parseInt(howMany, 10);
+		for (let i = 0; i < _wrong; i += 1) {
+			const _answer = QUESTIONS[_indexes?.[i]]?.answer;
+			_answers.push(_answer || QUESTIONS[randomNumber(AVAILABLE)].answer);
+		}
 
-		// Limiting result set to at least one
-		if (NUMBER < 1) howMany = 1;
+		return { ...QUESTIONS[randomNumber(AVAILABLE)], wrong: _answers };
+	};
 
-		// Limiting result set to 10000 at a time for performance reasons
-		if (NUMBER > 10000) howMany = 10000;
+	/**
+	 * Returns an array of random questions from the list.
+	 *
+	 * @param {object} [options] Guidelines for question generation.
+	 * @param {number} [options.howMany=10] Number of question items to be generated.
+	 * @param {number} [options.wrong] Number of wrong answers to be included.
+	 * @return {array} Array of random question objects from the list.
+	 */
+	const questions = ({ howMany = 10, wrong } = {}) => {
+		const _howMany = parameterLimitter(howMany, 'howMany', 1, 10000);
+		const _wrong = wrong ? parameterLimitter(wrong, 'wrong', 1, 30) : undefined;
 
-		const result = [];
+		const _result = [];
 
-		for (let i = 0; i < howMany; i += 1) {
-			result.push(question());
+		for (let i = 0; i < _howMany; i += 1) {
+			_result.push(question({ wrong: _wrong }));
 		}
 
-		return result;
+		return _result;
 	};
 
 	return { question, questions };
diff --git a/test/general.js b/test/general.js
@@ -1,28 +1,27 @@
+import { describe, it } from 'mocha';
 import { expect, assert } from 'chai';
 import { initialize } from '../src/index.js';
 
 describe('Testing basic functionalities of the entire library', () => {
-
 	it('Should successfully initialize with default parameters', () => {
-		const QUESTIONNAIRE = initialize()
+		const QUESTIONNAIRE = initialize();
 		expect(Object.keys(QUESTIONNAIRE)).not.to.be.empty;
 	});
 
 	it('Should successfully initialize with parameters passed', () => {
-		const QUESTIONNAIRE = initialize({ countryCode: 'rs', variation: 'cyrillic' })
+		const QUESTIONNAIRE = initialize({ countryCode: 'rs', variation: 'cyrillic' });
 		expect(Object.keys(QUESTIONNAIRE)).not.to.be.empty;
 	});
 
 	it('Should throw an error (invalid countryCode parameter passed)', () => {
-		assert.throw(() => { initialize({ countryCode: 'INVALID' }); }, Error, 'Parameter countryCode is invalid.');
+		assert.throw(() => { initialize({ countryCode: 'INVALID' }); }, Error, 'Parameter countryCode is not valid.');
 	});
 
 	it('Should throw an error (invalid variation parameter passed, without countryCode)', () => {
-		assert.throw(() => { initialize({ variation: 'INVALID' }); }, Error, 'Parameter variation is invalid.');
+		assert.throw(() => { initialize({ variation: 'INVALID' }); }, Error, 'Parameter variation is not valid.');
 	});
 
 	it('Should throw an error (invalid variation parameter passed, with countryCode)', () => {
-		assert.throw(() => { initialize({ countryCode: 'rs', variation: 'INVALID' }); }, Error, 'Parameter variation is invalid.');
+		assert.throw(() => { initialize({ countryCode: 'rs', variation: 'INVALID' }); }, Error, 'Parameter variation is not valid.');
 	});
-
 });
diff --git a/test/question.js b/test/question.js
@@ -1,18 +1,46 @@
-import { assert } from 'chai';
+import { describe, it } from 'mocha';
+import { assert, expect } from 'chai';
 import { initialize } from '../src/index.js';
 
-const QUESTIONNAIRE = initialize()
+const QUESTIONNAIRE = initialize();
 
 describe('Testing question() method', () => {
-
-	it('Should return a random question', () => {
+	it('Return a random question', () => {
 		const result = QUESTIONNAIRE.question();
 		assert.isObject(result) && assert.isNotEmpty(result);
 	});
 
-	it('Should ignore passed parameter and return a random question', () => {
-		const result = QUESTIONNAIRE.question(1);
+	it('Ignore parameter type different than object', () => {
+		const result = QUESTIONNAIRE.question('INVALID');
+		assert.isObject(result) && assert.isNotEmpty(result);
+	});
+
+	it('Ignore empty object parameter', () => {
+		const result = QUESTIONNAIRE.question({});
+		assert.isObject(result) && assert.isNotEmpty(result);
+	});
+
+	it('Ignore object parameter with invalid key/value pair', () => {
+		const result = QUESTIONNAIRE.question({ INVALID: 'INVALID' });
 		assert.isObject(result) && assert.isNotEmpty(result);
 	});
 
+	it('Invalid number of wrong answers', () => {
+		assert.throw(() => { QUESTIONNAIRE.question({ wrong: 'INVALID' }); }, Error, 'Parameter wrong must be castable to integer.');
+	});
+
+	it('Valid number of wrong answers', () => {
+		const result = QUESTIONNAIRE.question({ wrong: 5 });
+		assert.isObject(result) && assert.isNotEmpty(result) && expect(result).to.have.key('wrong') && expect(result.wrong).to.have.lengthOf(5);
+	});
+
+	it('Smaller number of wrong answers, should default to 1', () => {
+		const result = QUESTIONNAIRE.question({ wrong: -1 });
+		assert.isObject(result) && assert.isNotEmpty(result) && expect(result).to.have.key('wrong') && expect(result.wrong).to.have.lengthOf(1);
+	});
+
+	it('Larger number of wrong answers, should default to 30', () => {
+		const result = QUESTIONNAIRE.question({ wrong: 31 });
+		assert.isObject(result) && assert.isNotEmpty(result) && expect(result).to.have.key('wrong') && expect(result.wrong).to.have.lengthOf(30);
+	});
 });
diff --git a/test/questions.js b/test/questions.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@paunovic/questionnaire",`
`3`		`- "version": "1.0.4",`
	`3`	`+ "version": "2.0.0",`
`4`	`4`	`"description": "Serving random questions in multiple languages has never been this easy.",`
`5`	`5`	`"author": "Milos Paunovic <paun992@hotmail.com>",`
`6`	`6`	`"license": "MIT",`