Comply with the new guidelines of writing patterns

Author: tzeikob

Diff for: foundational/callback/factorial.js

@@ -1,4 +1,4 @@
-function factorial(num, cb) {
+function factorial (num, callback) {
   setTimeout(() => {
     try {
       if (typeof num !== "number") {
@@ -10,13 +10,14 @@ function factorial(num, cb) {
       }
 
       let result = 1;
+
       for (let i = 1; i <= num; i++) {
         result *= i;
       }
 
-      cb(null, result);
+      callback(null, result);
     } catch (error) {
-      cb(error);
+      callback(error);
     }
   });
 }

Diff for: foundational/callback/mapper.js

@@ -1,8 +1,12 @@
-function map(values, cb) {
+function map (values, callback) {
+  if (!values || !Array.isArray(values) || values.length === 0) {
+    throw new Error("Invalid values argument");
+  }
+
   const mapped = [];
 
   for (let i = 0; i < values.length; i++) {
-    mapped.push(cb(values[i]));
+    mapped.push(callback(values[i]));
   }
 
   return mapped;

Diff for: foundational/callback/readme.md

@@ -1,47 +1,46 @@
 # The Callback Pattern
 
-A callback is nothing more than a function, which in JavaScript is considered a **first-class** object. Functions can be assigned to variables, passed as arguments in other functions and even returned by functions. In both the synchronous and asynchronous world of JavaScript this is considered a foundational concept, because either we can pass functionality to be executed at the same cycle of the event loop or at a future event loop cycle without blocking the current code.
+A callback is nothing more than a function, which in JavaScript is considered a **first-class** object. Functions can be assigned to variables, passed as arguments in other functions and even returned by functions. In both the synchronous and asynchronous world of JavaScript this is considered a foundational concept, because either we can pass functionality to be executed at the current cycle (sync) or at a subsequent cycle (async) of the event loop.
 
-## Explanation
+## Implementation
 
-As callback is just a function, it can be passed to another function and invoked with the result when the operation in that function completes. It doesn't need to be an asynchronous operation though, callbacks can be used both in synchronous and asynchronous operations.
+As callback is just a function, it can be passed to another function and invoked with the result when the operation in that function completes. It doesn't need to be an asynchronous operation though, callbacks can be used both in **synchronous** and **asynchronous** operations.
 
 ### Callback in a synchronous operation
 
-In a synchronous operation, the callback patterns should be implemented like so,
+In a synchronous operation, the callback pattern should be implemented like so.
 
 ```javascript
-function operation(input, callback) {
+function operation (input, callback) {
   // Execute any business logic
   const result = ...
 
-  // Call back with the result
-  callback(result);
+  callback(result); // Call back with the result
 };
 
-operation(input, function callback(result) {
+// Execute the operation given a callback
+operation(input, (result) => {
   console.log(result);
 });
 ```
 
-where input can be any valid value or either a list of separated input values followed be the callback which always should come last.
+where input can be any valid value or either a list of separated input values followed be the `callback` which always should come last.
 
 ### Callback in an asynchronous operation
 
-In an asynchronous operation though, a callback should always be called asynchronously in order to be invoked in the next event loop cycles.
+In an asynchronous operation though, a `callback` should always be called asynchronously in order to be invoked in the next event loop cycles.
 
 ```javascript
-function operation(input, callback) {
+function operation (input, callback) {
   setTimeout(() => {
     // Execute any business logic
     const result = ...
 
-    // Call back with the result
-    callback(result);
+    callback(result); // Call back with the result
   });
 };
 
-operation(input, function callback(result) {
+operation(input, (result) => {
   console.log(result);
 });
 ```
@@ -53,32 +52,33 @@ operation(input, function callback(result) {
 The callback pattern can be used in other use cases as well, for instance in cases where you need to transform the values of a collection. In such cases a callback is given a value and returns it back modified instead of just handle it.
 
 ```javascript
-function operation(values, callback) {
+function operation (values, callback) {
   const results = [];
 
   for (let i = 0; i < values.length; i++) {
-    // Call with the value and return it back
+    // Execute the callback for each value
     const result = callback(values[i]);
 
-    results.push(result);
+    results.push(result); // Collect the next result
   }
 
   return results;
 }
 
 const values = [1, 2, 3, 4, 5];
 
-const results = operation(values, function callback(value) {
+// Execute the operation
+const results = operation(values, (value) => {
   return value * 2;
 });
 ```
 
 ### Error handling in a callback
 
-Another important thing is to be consistent with error handling in callbacks and have any error come first when propagating errors back.
+Another important thing is to be consistent with error handling in callbacks, in case an `error` is thrown the `callback` has always to be called given that error as the first and only argument.
 
 ```javascript
-function operation(input, callback) {
+function operation (input, callback) {
   setTimeout(() => {
     try {
       // Execute business logic
@@ -91,7 +91,8 @@ function operation(input, callback) {
   });
 }
 
-operation(input, function callback(error, result) {
+// Execute the operation
+operation(input, (error, result) => {
   // Error must always come first
   if (error) {
     return console.error(error);
@@ -101,7 +102,7 @@ operation(input, function callback(error, result) {
 });
 ```
 
-To sum up, a callback called synchronously blocks the current code until the operation completes, where an asynchronously called callback returns control back immediately and completes, given the result, at a later event loop cycle. In any use case mentioned above, there is no syntactic difference which means that the intent of the callback should always be explained in the documentation of the API about the synchronous or asynchronous manner the callback is called.
+To sum up, a callback called synchronously blocks the current code until the operation completes, where an asynchronously called callback returns control back immediately and completes at a subsequent event loop cycle. As mentioned above, there is no syntactic difference which means that the intent of the callback should always be explained in the documentation of the API about the synchronous or asynchronous manner the callback is called.
 
 ## Considerations
 
@@ -110,13 +111,16 @@ To sum up, a callback called synchronously blocks the current code until the ope
 Try to avoid inconsistencies in the behavior of a function which is using a callback, either the callback should always be called synchronously or asynchronously. It is considered very bad practice to have a function behave unpredictably mixing synchronous and asynchronous calls to the given callback. Let's say we have a `cache` map object and an asynchronous `factorial` function:
 
 ```javascript
-function compute(num, callback) {
+import { factorial } from "math";
+
+function compute (num, callback) {
   if (cache[num]) {
     return callback(cache[num]); // Call back synchronously
   }
 
+  // Calling the asynchronous factorial
   factorial(num, (result) => {
-    cache[num] = result; // Next time call back synchronously
+    cache[num] = result; // Save calculation into the cache
 
     callback(result); // Call back asynchronously once
   });
@@ -125,23 +129,24 @@ function compute(num, callback) {
 
 > We are skipping the error handling here just for simplicity and readability.
 
-Once you first compute the factorial of a number the next time you request the same number's factorial, the call to the callback will be synchronous. Instead try to stick with either synchronous or asynchronous behavior in any function expecting a callback.
+Once you first compute the `factorial` of a number the next time you request the same number's factorial, the call to the callback will be synchronous. Instead try to stick with either synchronous or asynchronous behavior in any function expecting a callback.
 
 ```javascript
-function compute(num, callback) {
+function compute (num, callback) {
   if (cache[num]) {
-    return setTimeout(() => callback(cache[num])); // Call always back asynchronously
+    // Call always back asynchronously
+    return setTimeout(() => callback(cache[num]));
   }
 
   factorial(num, (result) => {
-    cache[num] = result;
+    cache[num] = result; // Save calculation into the cache
 
     callback(result); // Call back asynchronously
   });
 }
 ```
 
-## Implementations
+## Use Cases
 
 Below you can find various trivial or real-world implementations of this pattern: