Improve Concept Exercise: Elyses Analytic Enchantments (array-analysis) (#1489)

Author: pertrai1

concepts/array-analysis/.meta/config.json

@@ -1,5 +1,5 @@
 {
   "blurb": "JavaScript provides a number of useful array methods for analysis.",
-  "authors": ["peterchu999", "SleeplessByte"],
+  "authors": ["peterchu999", "SleeplessByte", "pertrai1"],
   "contributors": []
 }

concepts/array-analysis/about.md

@@ -1,7 +1,10 @@
 # About
 
-In JavaScript, instances of an `Array` are regular objects, decorated with lots of [useful methods][array-docs] from the `Array.prototype`. It includes the `length` property, as well as methods for traversing, analyzing and mutating the array. The array's elements are indexed properties of that array.
+In JavaScript, instances of an [`Array`][arrays-concept] are regular objects, decorated with lots of [useful methods][array-docs].
+It includes the `length` property, as well as methods for traversing, analyzing and mutating the array.
+The array's elements are indexed properties of that array.
 Instead of manually iterating over those indexed properties, use array analysis.
+Many of the built-in functions that analyse the contents of an array, take a function that returns true or false as an argument. Such a function is called [`predicate`][predicate_in_programming]
 
 In general, using the abstractions/built-in methods is more idiomatic, readable and maintainable than using a `for` or `.forEach` equivalent.
 
@@ -68,4 +71,6 @@ const hasValue42 = values.includes(42);
 // => false
 ```
 
+[predicate_in_programming]: https://derk-jan.com/2020/05/predicate/
 [array-docs]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Instance_methods
+[arrays-concept]: /tracks/javascript/concepts/arrays

concepts/array-analysis/introduction.md

@@ -1,8 +1,10 @@
 # Introduction
 
-In JavaScript, an array is a list-like structure with no fixed length which can hold any type of primitives or objects, or even mixed types. The array elements can be accessed by their index. Arrays are also given a bunch of built-in methods. Some of these built-in methods can analyse the contents of the array. Many of the built-in functions that analyse the contents of an array, take a [`predicate`][predicate_in_programming] as argument.
+[Arrays][arrays-concept] have built-in methods to analyse the contents of the array.
+Most of these methods take a function that returns true or false as an argument.
+Such a function is called [`predicate`][predicate_in_programming].
 
-The built-in functions are meant to be used _instead of a `for` loop_ or the built-in `Array#forEach()`:
+The built-in methods are meant to be used _instead of a `for` loop_ or the built-in `forEach` method:
 
 Example of analysis using a for loop :
 
@@ -24,4 +26,68 @@ numbers.indexOf('two');
 // => 1
 ```
 
+Some other helpful built-in methods that are available to analyze an array are shown below. See [MDN][mdn-array-methods] for a full list of array methods.
+
+## `includes`
+
+> The includes() method determines whether an array includes a certain value among its entries, returning true or false as appropriate. [^1]
+
+```javascript
+const numbers = [1, 'two', 3, 'four'];
+numbers.includes(1);
+// => true
+numbers.includes('one');
+// => false
+```
+
+## `every`
+
+> The every() method tests whether all elements in the array pass the test implemented by the provided function. It returns a Boolean value. [^2]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.every((num) => num % 2 !== 0);
+// => true
+```
+
+## `some`
+
+> The some() method tests whether at least one element in the array passes the test implemented by the provided function. [^3]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.some((num) => num % 2 !== 0);
+// => true
+```
+
+## `find`
+
+> The find() method returns the value of the first element in the provided array that satisfies the provided testing function. If no values satisfy the testing function, undefined is returned. [^4]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.find((num) => num < 5);
+// => 1
+```
+
+## `findIndex`
+
+> The findIndex() method returns the index of the first element in the array that satisfies the provided testing function. Otherwise, it returns -1, indicating that no element passed the test. [^5]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.findIndex((num) => num > 7);
+// => 4
+numbers.findIndex((num) => num > 9);
+// => -1
+```
+
+[^1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes
+[^2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
+[^3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
+[^4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
+[^5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex
+
 [predicate_in_programming]: https://derk-jan.com/2020/05/predicate/
+[mdn-array-methods]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#instance_methods
+[arrays-concept]: /tracks/javascript/concepts/arrays

exercises/concept/elyses-analytic-enchantments/.docs/introduction.md

@@ -1,8 +1,10 @@
 # Introduction
 
-In JavaScript, an array is a list-like structure with no fixed length which can hold any type of primitives or objects, or even mixed types. The array elements can be accessed by their index. Arrays are also given a bunch of built-in methods. Some of these built-in methods can analyse the contents of the array. Many of the built-in functions that analyse the contents of an array, take a [`predicate`][predicate_in_programming] as argument.
+[Arrays][arrays-concept] have built-in methods to analyse the contents of the array.
+Most of these methods take a function that returns true or false as an argument.
+Such a function is called [`predicate`][predicate_in_programming].
 
-The built-in functions are meant to be used _instead of a `for` loop_ or the built-in `Array#forEach()`:
+The built-in methods are meant to be used _instead of a `for` loop_ or the built-in `forEach` method:
 
 Example of analysis using a for loop :
 
@@ -24,4 +26,68 @@ numbers.indexOf('two');
 // => 1
 ```
 
+Some other helpful built-in methods that are available to analyze an array are shown below. See [MDN][mdn-array-methods] for a full list of array methods.
+
+## `includes`
+
+> The includes() method determines whether an array includes a certain value among its entries, returning true or false as appropriate. [^1]
+
+```javascript
+const numbers = [1, 'two', 3, 'four'];
+numbers.includes(1);
+// => true
+numbers.includes('one');
+// => false
+```
+
+## `every`
+
+> The every() method tests whether all elements in the array pass the test implemented by the provided function. It returns a Boolean value. [^2]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.every((num) => num % 2 !== 0);
+// => true
+```
+
+## `some`
+
+> The some() method tests whether at least one element in the array passes the test implemented by the provided function. [^3]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.some((num) => num % 2 !== 0);
+// => true
+```
+
+## `find`
+
+> The find() method returns the value of the first element in the provided array that satisfies the provided testing function. If no values satisfy the testing function, undefined is returned. [^4]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.find((num) => num < 5);
+// => 1
+```
+
+## `findIndex`
+
+> The findIndex() method returns the index of the first element in the array that satisfies the provided testing function. Otherwise, it returns -1, indicating that no element passed the test. [^5]
+
+```javascript
+const numbers = [1, 3, 5, 7, 9];
+numbers.findIndex((num) => num > 7);
+// => 4
+numbers.findIndex((num) => num > 9);
+// => -1
+```
+
+[^1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes
+[^2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
+[^3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
+[^4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
+[^5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex
+
 [predicate_in_programming]: https://derk-jan.com/2020/05/predicate/
+[mdn-array-methods]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#instance_methods
+[arrays-concept]: /tracks/javascript/concepts/arrays

exercises/concept/elyses-analytic-enchantments/.meta/config.json

@@ -1,7 +1,7 @@
 {
   "blurb": "Elyse's magic training continues, teaching you about useful built-in methods to analyse arrays.",
   "authors": ["peterchu999", "SleeplessByte"],
-  "contributors": [],
+  "contributors": ["pertrai1"],
   "files": {
     "solution": ["enchantments.js"],
     "test": ["enchantments.spec.js"],

exercises/concept/elyses-analytic-enchantments/.meta/design.md

@@ -0,0 +1,28 @@
+# Design
+
+## Learning objectives
+
+Using an array method to ...
+
+- determine the index of an item in the array
+- determine if an item is included in the array
+- determine if every item in the array meets a certain criteria
+- determine if some items in the array meets a certain criteria
+- find the first item that meets a certain criteria
+- find the index of an item that meets a certain criteria
+
+## Out of scope
+
+The following topics are out of scope because they are covered in other concepts.
+
+- array transformation (map, filter, etc.)
+- array loops (forEach, for...of)
+- array manipulation (push, pop, etc.)
+
+## Concepts
+
+- `array-analysis`
+
+## Prerequisites
+
+- `arrays` are needed to understand the basics of arrays

exercises/concept/elyses-analytic-enchantments/enchantments.spec.js

@@ -9,103 +9,56 @@ import {
   getFirstEvenCardPosition,
 } from './enchantments';
 
-/**
- * @template T the expected return type
- * @typedef {Array<[number[], number, T]>} TestSingleMatrix
- */
-
-/**
- * @template T the expected return type
- * @typedef {Array<[number[], T]>} TestAllMatrix
- **/
-
-describe('elyses analytic enchantments', () => {
-  describe('getCardPosition', () => {
-    /** @type {TestSingleMatrix<number>} */
-    const getCardPositionTestCases = [
-      [[1, 2, 3], 1, 0],
-      [[1, 2, 2], 2, 1],
-      [[1, 2, 3], 4, -1],
-    ];
-
-    getCardPositionTestCases.forEach(([array, item, expected]) => {
-      test(`getCardIndex([${array}], ${item})`, () => {
-        expect(getCardPosition(array, item)).toStrictEqual(expected);
-      });
-    });
+describe('getCardPosition', () => {
+  test('when it is the first card', () => {
+    expect(getCardPosition([1, 2, 3], 1)).toBe(0);
   });
-
-  describe('doesStackIncludeCard', () => {
-    /** @type {TestSingleMatrix<boolean>} */
-    const doesStackIncludeCardTestCases = [
-      [[1, 2, 3], 1, true],
-      [[1, 2, 3], 4, false],
-    ];
-
-    doesStackIncludeCardTestCases.forEach(([array, item, expected]) => {
-      test(`doesStackIncludeCard([${array}],${item})`, () => {
-        expect(doesStackIncludeCard(array, item)).toBe(expected);
-      });
-    });
+  test('when the card is not found', () => {
+    expect(getCardPosition([1, 2, 3], 4)).toBe(-1);
   });
+});
 
-  describe('isEachCardEven', () => {
-    /** @type {TestAllMatrix<boolean>} */
-    const isEachCardEvenTestCases = [
-      [[1], false],
-      [[2, 5], false],
-      [[2, 4, 8, 6], true],
-    ];
-
-    isEachCardEvenTestCases.forEach(([array, expected]) => {
-      test(`isEachCardEven([${array}])`, () => {
-        expect(isEachCardEven(array)).toStrictEqual(expected);
-      });
-    });
+describe('doesStackIncludeCard', () => {
+  test('when there is a card found', () => {
+    expect(doesStackIncludeCard([1, 2, 3], 1)).toBe(true);
   });
-
-  describe('doesStackIncludeOddCard', () => {
-    /** @type {TestAllMatrix<boolean>} */
-    const doesStackIncludesOddCardTestCases = [
-      [[2, 4, 6], false],
-      [[2, 5], true],
-      [[1, 3, 5, 7], true],
-    ];
-
-    doesStackIncludesOddCardTestCases.forEach(([array, expected]) => {
-      test(`doesStackIncludeOddCard([${array}])`, () => {
-        expect(doesStackIncludeOddCard(array)).toStrictEqual(expected);
-      });
-    });
+  test('when a card is not found', () => {
+    expect(doesStackIncludeCard([1, 2, 3], 4)).toBe(false);
   });
+});
 
-  describe('getFirstOddCard', () => {
-    /** @type {TestAllMatrix<number | undefined>} */
-    const getFirstOddCardTestCases = [
-      [[2, 4, 1, 3], 1],
-      [[1, 2], 1],
-      [[4, 2, 6], undefined],
-    ];
+describe('isEachCardEven', () => {
+  test('when all cards are even', () => {
+    expect(isEachCardEven([2, 4, 6])).toBe(true);
+  });
+  test('when any card is odd', () => {
+    expect(isEachCardEven([2, 5, 6])).toBe(false);
+  });
+});
 
-    getFirstOddCardTestCases.forEach(([array, expected]) => {
-      test(`getFirstOddCard([${array}])`, () => {
-        expect(getFirstOddCard(array)).toStrictEqual(expected);
-      });
-    });
+describe('doesStackIncludeOddCard', () => {
+  test('should be true if odd number card is found', () => {
+    expect(doesStackIncludeOddCard([2, 5])).toBe(true);
   });
+  test('should be false if no odd number card is found', () => {
+    expect(doesStackIncludeOddCard([2, 4, 6])).toBe(false);
+  });
+});
 
-  describe('getFirstEvenCardPosition', () => {
-    /** @type {TestAllMatrix<number>} */
-    const getFirstEvenCardPositionTestCases = [
-      [[2, 4, 1, 3], 0],
-      [[1, 2], 1],
-      [[1, 3, 5], -1],
-    ];
+describe('getFirstOddCard', () => {
+  test('should return the first odd card found', () => {
+    expect(getFirstOddCard([2, 4, 1, 3])).toBe(1);
+  });
+  test('should return undefined if odd card is not found', () => {
+    expect(getFirstOddCard([4, 2, 6])).toBeUndefined();
+  });
+});
 
-    getFirstEvenCardPositionTestCases.forEach(([array, expected]) => {
-      test(`getFirstEvenCardPosition([${array}])`, () => {
-        expect(getFirstEvenCardPosition(array)).toStrictEqual(expected);
-      });
-    });
+describe('getFirstEvenCardPosition', () => {
+  test('should return position of first even card', () => {
+    expect(getFirstEvenCardPosition([2, 4, 1, 3])).toBe(0);
+  });
+  test('should return -1 when the card is not found', () => {
+    expect(getFirstEvenCardPosition([1, 3, 5])).toBe(-1);
   });
 });