necessary 14.3.2 → 14.4.1

package/README.md

@@ -2,7 +2,9 @@
 
 A collection of utility functions.
 
-This package was partly inspired by [lodash](https://lodash.com/), [async](https://caolan.github.io/async/) and the like. The idea was to create utility functions that addressed some modest requirements and would result in a relatively small footprint. That said, the bare bones implementations, especially the asynchronous functions, should provide some confidence whilst debugging.
+This package was partly inspired by [lodash](https://lodash.com/), [async](https://caolan.github.io/async/) and the like. 
+The idea was to create utility functions that addressed some modest requirements and would result in a relatively small footprint. 
+That said, the bare bones implementations, especially the asynchronous functions, should provide some confidence whilst debugging.
 
 These can only be used in the browser:
 
@@ -43,7 +45,8 @@ You can also clone the repository with [Git](https://git-scm.com/)...
 
 ## Usage
 
-Each of the collections of utility functions described below is exported as a plain old JavaScript object. To get hold of them, import the requisite object and then destructure it:
+Each of the collections of utility functions described below is exported as a plain old JavaScript object. 
+To get hold of them, import the requisite object and then destructure it:
 
 ```
 import { arrayUtilities, asynchronousUtilities, fileSystemUtilities } from "necessary";
@@ -65,23 +68,28 @@ const { first, last } = arrayUtilities,
 ...
 ```
 
-The miscellaneous functions are a special case. They can be treated as above but may well have other functions assigned to them. See below.
+The miscellaneous functions are a special case. 
+They can be treated as above but may well have other functions assigned to them. 
+See below.
 
 ## Ajax utilities
 
 - `get()`
-- `post()`cp 
+- `post()`
 - `request()`
 
 The first two `get()` and `post()` functions make use of the third `request()` function, which is more generic and can be used for arbitrary HTTP requests.
 
-* The `get()` function sends a `GET` request, taking `host`, `uri`, `query` and `operation` arguments, together with an optional `headers` argument after the `query` argument.
+* The `get()` function sends a `GET` request, taking `host`, `uri` and `query` arguments, together with an optional `headers` argument after the `query` argument.
 
 The `query` argument should be a plain old JavaScript object, the names and values of which are encoded and concatenated to form the query string.
 
-The `headers` argument should also be a plain old JavaScript object. If it does not have an `accept` property then one wil be provided with the value `application/json`.
+The `headers` argument should also be a plain old JavaScript object. 
+If it does not have an `accept` property then one wil be provided with the value `application/json`.
 
-The `callback` argument is expected to be a function taking `content` and `statusCode` arguments. If the `accept` property of the main `headers` argument is set to `application/json` then the operation's `content` argument can be assumed to be JSON, or `null` if the request body cannot be parsed as such. The `statusCode` argument will be the response status code, for example `200` for a successful `OK` response.
+The `callback` argument is expected to be a function taking `content` and `statusCode` arguments. 
+If the `accept` property of the main `headers` argument is set to `application/json` then the function's `content` argument can be assumed to be JSON, or `null` if the request body cannot be parsed as such. 
+The `statusCode` argument will be the response status code, for example `200` for a successful `OK` response.
 
 ```
 const host = "...",
@@ -101,7 +109,10 @@ Note that the `uri` argument must include a leading forward slash `/` since the
 
 * The `post()` function behaves almost identically to the `get()` function, with the following differences.
 
-It sends a `POST` rather than a `GET` request. There is an additional `content` argument that comes before the `callabck` argument and after the `headers` argument, which is again optional. If the `headers` argument does not have a `content-type` property then one will be provided with the value of `application/json`. If the `content-type` property of the `headers` argument is set to `application/json` then the `content` argument is assumed to be a plain old JavaScript object and is stringified as JSON.
+It sends a `POST` rather than a `GET` request. 
+There is an additional `content` argument that comes before the `callabck` argument and after the `headers` argument, which is again optional. 
+If the `headers` argument does not have a `content-type` property then one will be provided with the value of `application/json`. 
+If the `content-type` property of the `headers` argument is set to `application/json` then the `content` argument is assumed to be a plain old JavaScript object and is stringified as JSON.
 
 ```
 const host = "...",
@@ -152,7 +163,8 @@ Note that the `headers` argument is not optional this time.
 Functions for applications running on a shell such as Bash or ZSH. 
 In fact there is only one currently. 
 
-* The `prompt()` function is meant for use in shell applications. It takes a plain old JavaScript `options` object and a `callback` function as its first and second arguments, respectively:
+* The `prompt()` function is meant for use in shell applications. 
+It takes a plain old JavaScript `options` object and a `callback` function as its first and second arguments, respectively:
 
 ```
 const hidden = true,
@@ -173,13 +185,18 @@ prompt(options, (answer) => {
 });
 ```
 
-There are a range of properties available for the `options` object. The `description` and `errorMessage` properties are mandatory. The remaining properties are optional.
+There are a range of properties available for the `options` object. 
+The `description` and `errorMessage` properties are mandatory. 
+The remaining properties are optional.
 
-The default values of the `attempts` and `encoding` properties are `3` and `utf8`, respectively. The default value of the `hidden` property is `false`. Setting it to `true` results in password-style input, that is, the characters remain hidden.
+The default values of the `attempts` and `encoding` properties are `3` and `utf8`, respectively. 
+The default value of the `hidden` property is `false`. Setting it to `true` results in password-style input, that is, the characters remain hidden.
 
 If no `validateFunction` property is given then you must set a `validatePattern` property instead, which must be a regular expression.
 
-The `initialAnswer` property sets the initial answer at the prompt. You might want to set it to `yes`, for example. Lastly, setting the `answer` property to anything other than `null` or `undefined` causes the `callback` function to be invoked immediately without any prompt being shown. This can be useful for debugging.
+The `initialAnswer` property sets the initial answer at the prompt. 
+You might want to set it to `yes`, for example. Lastly, setting the `answer` property to anything other than `null` or `undefined` causes the `callback` function to be invoked immediately without any prompt being shown. 
+This can be useful for debugging.
 
 ## Logging utilities
 
@@ -195,7 +212,9 @@ log("...") // Results in '28-01-2018 15:44:47.363 bin/main.js(35) ...' being log
 
 You can pass an error instead of a string to `log()`, in which case it will print the file path and line number of the place where the error was thrown along with the error message.
 
-Additionally, it is possible to print to a log file if a log directory and, optionally, a base name for the log file are specified. The base name here means the file name minus the extension and separator. The default is `default`:
+Additionally, it is possible to print to a log file if a log directory and, optionally, a base name for the log file are specified. 
+The base name here means the file name minus the extension and separator. 
+The default is `default`:
 
 ```
 const { setLogFileBaseName, setLogDirectoryPath } = log;
@@ -218,7 +237,8 @@ log.error("...") // Printed to the console and optionally, to the log file.
 log.trace("...") // Ignored, because the trace level is lower than the debug level.
 ```
 
-There is also a `setLogOptions()` function which allows you to pass the log level, base file name and directory path as a plain old JavaScript object. See below for a usage example.
+There is also a `setLogOptions()` function which allows you to pass the log level, base file name and directory path as a plain old JavaScript object. 
+See below for a usage example.
 
 Finally, log files are rolled over every night. So `./log/example.log` would become `./log/example.28-01-2018.log` and a new `./log/example.log` file would be started at midnight.
 
@@ -228,11 +248,21 @@ Finally, log files are rolled over every night. So `./log/example.log` would bec
 - `createGetRequest()`
 - `createPostRequest()`
 
-Functions that leverage Node's [HTTP](https://nodejs.org/api/http.html) nad [HTTPS](https://nodejs.org/api/https.html) inbuilt modules in order to provide HTTP request functionality. These functions are deliberately low level. They will take away some of the pain of using the aforementioned modules but will not automatically set headers, parse responses, etc. Specifically, methods have to be called on the instance of the [ClientRequest](https://nodejs.org/api/http.html#http_class_http_clientrequest) class that they each return in order to make the request and on the instance of the [IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage) passed to the callback function in order to parse the response.
+Functions that leverage Node's [HTTP](https://nodejs.org/api/http.html) nad [HTTPS](https://nodejs.org/api/https.html) inbuilt modules in order to provide HTTP request functionality. 
+These functions are deliberately low level. 
+They will take away some of the pain of using the aforementioned modules but will not automatically set headers, parse responses, etc. 
+Specifically, methods have to be called on the instance of the [ClientRequest](https://nodejs.org/api/http.html#http_class_http_clientrequest) class that they each return in order to make the request and on the instance of the [IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage) passed to the callback function in order to parse the response.
 
-* The `createRequest()` function provides a means to make arbitrary requests. It takes `host`, `uri`, `query`, `method`, `headers` and `callback` arguments. It returns an instance of Node's ClientRequest class. The callback function must have an `error` argument, which will be `null` if the request is successful, and a `response` argument, which will be an instance of Node's IncomingMessage class. The `query` and `headers` arguments should be plain old JavaScript objects, with the former being converted into a query string. The other arguments bar the last callback argument should be strings.
+* The `createRequest()` function provides a means to make arbitrary requests. 
+* It takes `host`, `uri`, `query`, `method`, `headers` and `callback` arguments. 
+* It returns an instance of Node's ClientRequest class. 
+* The callback function must have an `error` argument, which will be `null` if the request is successful, and a `response` argument, which will be an instance of Node's IncomingMessage class. 
+* The `query` and `headers` arguments should be plain old JavaScript objects, with the former being converted into a query string. 
+* The other arguments bar the last callback argument should be strings.
 
-In the following example a GET request is made. Note that because the request body is empty, it is enough to call the request object's `end()` method in order to make the request. Note also that the response is piped directly to a file.
+In the following example a GET request is made. 
+Note that because the request body is empty, it is enough to call the request object's `end()` method in order to make the request. 
+Note also that the response is piped directly to a file.
 
 ```
 const { createWriteStream } = require("fs");
@@ -257,7 +287,9 @@ const host = ...,
 request.end();
 ```
 
-In the following example the `queryStringFromQuery()` function from the HTTP utilities is used to encode the body of the request. Note that the `content-type` header is set explicitly. Note that the request body is piped directly from a file:
+In the following example the `queryStringFromQuery()` function from the HTTP utilities is used to encode the body of the request. 
+Note that the `content-type` header is set explicitly. 
+Note that the request body is piped directly from a file:
 
 ```
 const { createReadStream } = require("fs");
@@ -417,7 +449,8 @@ const line = "${name}, aged ${age}.",
 - `renameEntry()`
 - `removeEntry()`
 
-An inglorious collection of functions which do no more than paper over some of Node's synchronous [native file system API](https://nodejs.org/api/fs.html) functions. All of the functions will throw native errors upon failure.
+An inglorious collection of functions which do no more than paper over some of Node's synchronous [native file system API](https://nodejs.org/api/fs.html) functions. 
+All of the functions will throw native errors upon failure.
 
 * The `getEntryStats()` function returns an instance of the [fs.Stats](https://nodejs.org/api/fs.html#fs_class_fs_stats) class:
 
@@ -447,25 +480,31 @@ isDirectoryEmpty("root/etc"); // returns true if the directory is empty
 readDirectory("root/etc"); // returns the contents of the 'root/etc' directory
 ```
 
-* The `readFile()` function takes the file encoding as an optional second string argument. The default is `utf8`. It returns the content of the file upon success:
+* The `readFile()` function takes the file encoding as an optional second string argument. 
+* The default is `utf8`. 
+* It returns the content of the file upon success:
 
 ```
 readFile("root/etc/init.conf"); // returns the content of the 'root/etc/init.conf' file
 ```
 
-* The `copyFile()` function takes as arguments the source and target file paths. It will overwrite an existing file without throwing an error. It does not return anything upon success:
+* The `copyFile()` function takes as arguments the source and target file paths. 
+* It will overwrite an existing file without throwing an error. 
+* It does not return anything upon success:
 
 ```
 copyFile("root/etc/init.conf", "tmp/init.conf"); // copies the 'init.conf' file in the '/root/etc' folder to the '/tmp' folder
 ```
 
-* The `writeFile()` function takes the content of the file as a second string argument. It does not return anything upon success:
+* The `writeFile()` function takes the content of the file as a second string argument. 
+* It does not return anything upon success:
 
 ```
 writeFile("root/etc/init.conf", ""); // writes '' to the 'root/etc/init.conf' file
 ```
 
-* The `appendToFile()` function takes the content to append file as a second string argument. It will create teh file if necessary and does not return anything upon success:
+* The `appendToFile()` function takes the content to append file as a second string argument. 
+* It will create teh file if necessary and does not return anything upon success:
 
 ```
 appendToFile("root/etc/init.conf", ""); // appends '' to the 'root/etc/init.conf' file
@@ -477,7 +516,8 @@ appendToFile("root/etc/init.conf", ""); // appends '' to the 'root/etc/init.conf
 createDirectory("root/etc/init"); // Creates the 'root/etc/init' directory
 ```
 
-* The `createFile()` creates an empty file. It does not return anything upon success:
+* The `createFile()` creates an empty file. 
+* It does not return anything upon success:
 
 ```
 createFile("root/etc/init.conf"); // writes '' to the 'root/etc/init.conf' file
@@ -503,7 +543,8 @@ Note that in the case of a directory, all of its sub-entries will be removed as
 renameFile("hosts", "host"); // Renames the 'hosts' file to 'host'
 ```
 
-Note that if the parent directory of the newly named file or directory does not exist then this function will fail. Instead use the `moveEntry()` function.
+Note that if the parent directory of the newly named file or directory does not exist then this function will fail. 
+Instead use the `moveEntry()` function.
 
 ## Configuration utilities
 
@@ -521,7 +562,8 @@ const { logOptions } = rc;
 setLogOptions(logOptions);
 ```
 
-The default name for the file is `.rc` and it must be present in the current working directory. It must have the following format:
+The default name for the file is `.rc` and it must be present in the current working directory. 
+It must have the following format:
 
 ```
 {
@@ -547,7 +589,9 @@ If neither of these checks are successful then it will return the first element
 
 Note that it will not try to assign the `name` property of the chosen environment to itself, because functions already have a `name` property.
 
-Before returning the JSON, it will search for uppercase strings. If such a string is the name of an environment variable, it will be replaced by the environment variable's value. This means that you can choose to keep sensitive information out of the runtime configuration and therefore, for instance, safely commit it to the repository. 
+Before returning the JSON, it will search for uppercase strings. 
+If such a string is the name of an environment variable, it will be replaced by the environment variable's value. 
+This means that you can choose to keep sensitive information out of the runtime configuration and therefore, for instance, safely commit it to the repository. 
 
 You can change the base extension of the file that is parsed, that is the part of the extension between the leading dot and `rc`, by making use of the `setRCBaseExtension()` function:
 
@@ -561,7 +605,10 @@ rc(); // Provides the first environment in the '.defaultrc' file
 
 Note that the `rc()` function can be included in any file but only needs to be called once. But be careful that it is called before it is ever destructured.
 
-Aside from the aforementioned `setRCBaseExtension()` functions, the `checkRCFileExists()`, `createVacuousRCFile()`, `readRCFile()` and `writeRCFile()` functions do as their names suggest. The `updateRCFile()` function, if passed a plain old JavaScript object as the first argument, will add the properties therein, overwriting any existing properties. Properties to be removed can be given as further arguments. If you do not want to add as well as remove properties, set the first argument to a falsey value.
+Aside from the aforementioned `setRCBaseExtension()` functions, the `checkRCFileExists()`, `createVacuousRCFile()`, `readRCFile()` and `writeRCFile()` functions do as their names suggest. 
+The `updateRCFile()` function, if passed a plain old JavaScript object as the first argument, will add the properties therein, overwriting any existing properties. 
+Properties to be removed can be given as further arguments. 
+If you do not want to add as well as remove properties, set the first argument to a falsey value.
 
 ```
 const { readRCFile, writeRCFile, updateRCFile, checkRCFileExists, createVacuousRCFile } = rc;
@@ -594,7 +641,8 @@ updateRCFile(null, "example");  // Updates the rc file, removing the 'example' p
 - `pathWithoutBottommostNameFromPath()`
 - `pathWithoutTopmostDirectoryNameFromPath()`
 
-These functions manipulate or query strings that represent file and directory paths. Note that only forward slash `/` delimiters are supported. Trailing delimiters are not needed, but tolerated.
+These functions manipulate or query strings that represent file and directory paths. 
+Note that only forward slash `/` delimiters are supported. Trailing delimiters are not needed, but tolerated.
 
 * The `isPathName()` function returns `true` if the string argument contains no `/` delimiters apart from the first and last characters:
 
@@ -646,9 +694,11 @@ isTopmostNameInAbsolutePath("root", "/root/etc");  // returns false
 isTopmostNameInAbsolutePath("etc", "/root/etc"); // returns false
 ```
 
-Note that the function assumes that the first argument is a topmost name and that the second argument is an abolute path. It does not check, it simply compares the two arguments with a single regex.
+Note that the function assumes that the first argument is a topmost name and that the second argument is an abolute path. 
+It does not check, it simply compares the two arguments with a single regex.
 
-* The `combinePaths()` function will combine the first string argument with the second string argument by successively removing the bottommost directory name of the former for each topmost parent directory `..` signifier it finds in the latter. Current directory `.` signifiers are also removed:
+* The `combinePaths()` function will combine the first string argument with the second string argument by successively removing the bottommost directory name of the former for each topmost parent directory `..` signifier it finds in the latter. 
+* Current directory `.` signifiers are also removed:
 
 ```
 combinePaths("etc/", "./init"); // returns 'etc/init'
@@ -668,7 +718,8 @@ concatenatePaths("root/", "etc/"); // returns 'root/etc/'
 
 Note that the function assumes that the second argument is a relative name or path although without a leading current directory `.` or parent directory `..` signifier.
 
-* The `bottommostNameFromPath()`, `topmostDirectoryPathFromPath()`, `topmostDirectoryNameFromPath()`, `pathWithoutBottommostNameFromPath()` and `pathWithoutTopmostDirectoryNameFromPath()` functions work as their names suggest. Each expects there to be at least one delimiter, returning `null` otherwise:
+* The `bottommostNameFromPath()`, `topmostDirectoryPathFromPath()`, `topmostDirectoryNameFromPath()`, `pathWithoutBottommostNameFromPath()` and `pathWithoutTopmostDirectoryNameFromPath()` functions work as their names suggest. 
+* Each expects there to be at least one delimiter, returning `null` otherwise:
 
 ```
 bottommostNameFromPath("../etc"); // returns 'etc'
@@ -739,18 +790,24 @@ pathWithoutTopmostDirectoryNameFromPath("root/etc/init.conf"); // returns 'etc/i
 - `backwardsReduce()`
 - `forwardsForEach()`
 - `backwardsForEach()`
+- `forwardsFindIndex()`
+- `backwardsFindIndex()`
 
 Note that none of these functions take or pass on a `thisArg` argument when they might otherwise have done. Use `bind()`.
 
-* The functions `first()` through to `last()` return the requisite element of the array argument, if passed an array of at least the required length. If the array is not long enough they return `undefined`. 
+* The functions `first()` through to `last()` return the requisite element of the array argument, if passed an array of at least the required length. 
+If the array is not long enough they return `undefined`. 
   
-* The `head()` function returns an array containing the first element of its array argument whilst the `tail()` function returns an array containing all but the first element of its array argument. The `back()` function returns an array containing hte last element of its array argument whilst the `front()` function returns an array returning all but the last element of its array argument.
+* The `head()` function returns an array containing the first element of its array argument whilst the `tail()` function returns an array containing all but the first element of its array argument. 
+ 
+* The `back()` function returns an array containing hte last element of its array argument whilst the `front()` function returns an array returning all but the last element of its array argument.
 
 * The `push()` function is similar to its native counterpart but will push an array rather than a single element.
 
 * The `unshift()` function is similar to its native counterpart but will unshift an array rather than a single element.
 
-* The `concat()` function is similar to its native counterpart, however it alters the first array argument *in place*. Like its native counterpart it will also take a single element as the second argument and convert it to an array.
+* The `concat()` function is similar to its native counterpart, however it alters the first array argument *in place*. 
+Like its native counterpart it will also take a single element as the second argument and convert it to an array.
 
 ```
 concat([1, 2, 3], 4); // the array argument becomes [1, 2, 3, 4]
@@ -762,7 +819,8 @@ concat([1, 2, 3], 4); // the array argument becomes [1, 2, 3, 4]
 clear([1, 2, 3]); // the array argument becomes []
 ```
 
-* The `copy()` function copies the second array argument over the top of the first array argument, in other words it replaces each element of the first array argument with the corresponding element in the second array argument. If there are more elements in the second array argument that the first, the first is lengthened:
+* The `copy()` function copies the second array argument over the top of the first array argument, in other words it replaces each element of the first array argument with the corresponding element in the second array argument. 
+If there are more elements in the second array argument that the first, the first is lengthened:
 
 ```
 copy([1, 2, 3], [4, 5, 6, 7]); // the first array argument becomes [4, 5, 6, 7]
@@ -774,7 +832,8 @@ copy([1, 2, 3], [4, 5, 6, 7]); // the first array argument becomes [4, 5, 6, 7]
 merge([1, 2, 3], [4, 5, 6, 7]); // the first array argument becomes [1, 2, 3, 4, 5, 6, 7]
 ```
 
-* The `match()` function compares the first and second array arguments in order. If they are of the same length and the callback argument supplied returns a truthy value when invoked with each pair of elements then it returns true:
+* The `match()` function compares the first and second array arguments in order. 
+If they are of the same length and the callback argument supplied returns a truthy value when invoked with each pair of elements then it returns true:
 
 ```
 match([1, 2, 3], [-1, -2, -3], (valueA, valueB) => (valueA === -valueB)); // returns true
@@ -796,15 +855,21 @@ correlate([1, 2, 3], [-4, -2, -3, -1], (valueA, valueB) => (valueA === -valueB))
 
 Again note that pairs of elements can match once and once only.
  
-* The `resolve()` function repeatedly iterates over the elements of the first array argument, removing them and adding them to the second array argument if the callback function returns a truthy value. If the callback function does not return a truthy value for any of the elements of the first array argument or the length of the first array is zero, it terminates. 
+* The `resolve()` function repeatedly iterates over the elements of the first array argument, removing them and adding them to the second array argument if the callback function returns a truthy value. 
+If the callback function does not return a truthy value for any of the elements of the first array argument or the length of the first array is zero, it terminates. 
 
 ```
 resolve([1, 2, 3], [], (value) => true); // moves the elemnts of the first array argument into the second array argument and returns true
 ```
 
-The above code snippet is perhaps not very helpful so it is worth explaining this function's utility in the context of a use case. Suppose a compiler has to compile all the files in a given directory. There are inter-dependencies between the files, however, so some files will not compile until their dependents have compiled. If there are orderings of files that allow them to all be compiled, this function will find one of them by trial and error, so to speak. The second array argument will contain the elements according to this ordering.
+The above code snippet is perhaps not very helpful so it is worth explaining this function's utility in the context of a use case. 
+Suppose a compiler has to compile all the files in a given directory. 
+There are inter-dependencies between the files, however, so some files will not compile until their dependents have compiled. 
+If there are orderings of files that allow them to all be compiled, this function will find one of them by trial and error, so to speak. 
+The second array argument will contain the elements according to this ordering.
 
-The first array argument is left untouched whether or not the function succeeds. The second array argument may contain elements if it has only been partially successful, however.
+The first array argument is left untouched whether or not the function succeeds. 
+The second array argument may contain elements if it has only been partially successful, however.
 
 * The `find()` function is like its native counterpart, however it returns an array of all the elements for which the callback function returns a truthy value, rather than just the first:
 
@@ -818,13 +883,17 @@ find([1, 2, -1, -2], (element, index) => (element > 0)); // returns [1, 2]
 replace([1, 0, -2], 3, (element, index) => (element === 0)); // the array argument becomes [1, 3, -2]
 ```
 
-* The `splice()` function works in a similar vein to its native counterpart, however it takes an array as the optional fourth argument rather than a series of elements from the fourth argument onwards. It mutates the first array argument and returns an array of the elements that have been deleted:
+* The `splice()` function works in a similar vein to its native counterpart, however it takes an array as the optional fourth argument rather than a series of elements from the fourth argument onwards. 
+It mutates the first array argument and returns an array of the elements that have been deleted:
 
 ```
 splice([1, 2, 3], 1, 2, [4, 5]); // the first array argument becomes [1, 4, 5]
 ```
 
-* The `filter()` function is like its native counterpart, however it filters the first array argument *in place*. The second argument should be a callback function that will be invoked for each element of the array. If it does not return a truthy value, the corresponding element will be deleted. The deleted elements are returned.
+* The `filter()` function is like its native counterpart, however it filters the first array argument *in place*. 
+The second argument should be a callback function that will be invoked for each element of the array. 
+If it does not return a truthy value, the corresponding element will be deleted. 
+The deleted elements are returned.
 
 ```
 filter([1, 2, -2], (element, index) => (element > 0)); // returns [-2] and the array argument becomes [1, 2] 
@@ -878,7 +947,9 @@ augment([1, 2, 3], [-1, 4, -2, 5], (element, index) => (element > 0)); // the ar
 separate([1, -1, -2, 2, 3, -3], [], [], (element, index) => {(element > 0)); // the second and third array arguments become [1, 2, 3] and [-1, -2, 3], respectively.
 ```
 
-The `forwardsXXX()` and `backwardsXXX()`functions do as their names suggest. The `fowardsXXX()` function take an array for their first argument but otherwise behave identically to their native counterparts. The `backwardsXXX()` functions behave similarly, only backwards.
+The `forwardsXXX()` and `backwardsXXX()`functions do as their names suggest. 
+The `fowardsXXX()` functions take an array for their first argument but otherwise behave identically to their native counterparts. 
+The `backwardsXXX()` functions behave similarly, only backwards.
 
 ## HTTP utilities
 
@@ -892,7 +963,9 @@ The `forwardsXXX()` and `backwardsXXX()`functions do as their names suggest. The
 
 Helper functions to manipulate HTTP headers and URLs, build query strings and so on.
 
-* The `overwrite()` function takes a plain old JavaScript object `headers` argument together with `name` and `value` string arguments. If the corresponding property of the `headers` object exists then it is replaced with the `value` value. This function's utility lies in the fact that the name comparisons are case insensitive.
+* The `overwrite()` function takes a plain old JavaScript object `headers` argument together with `name` and `value` string arguments. 
+If the corresponding property of the `headers` object exists then it is replaced with the `value` value. 
+This function's utility lies in the fact that the name comparisons are case insensitive.
 
 ```
 const headers = {
@@ -902,7 +975,9 @@ const headers = {
 overwrite(headers, "content-type", "text/html"); // headers["Content-Type"] = "text/html"
 ```
 
-* The `underwrite()` function takes a plain old JavaScript object `headers` argument together with `name` and `value` string arguments. If the corresponding property of the `headers` object does not exist then it is created with the `value` value. This function's utility lies in the fact that the name comparisons are case insensitive.
+* The `underwrite()` function takes a plain old JavaScript object `headers` argument together with `name` and `value` string arguments. 
+If the corresponding property of the `headers` object does not exist then it is created with the `value` value. 
+This function's utility lies in the fact that the name comparisons are case insensitive.
 
 ```
 const headers = {
@@ -940,7 +1015,8 @@ secureFromHost("https://site.com"); // returns true
 hostnameFromHost("http://site.com"); // returns "site.com"
 ```
 
-* The `queryStringFromQuery()` function takes a plain old JavaScript object `query` argument and returns the corresponding URL encoded query string. It uses the [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) to encode the names and values
+* The `queryStringFromQuery()` function takes a plain old JavaScript object `query` argument and returns the corresponding URL encoded query string. 
+It uses the [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) to encode the names and values
 
 ```
 const query = {
@@ -950,7 +1026,8 @@ const query = {
 queryStringFromQuery(query); // returns John%20Doe
 ```
 
-* The `urlFromHostURIAndQuery()` function takes `host` and `uri` string arguments together with a `query` plain old JavaScript object argument. It creates a query string from the `query` object and concatenates this with the two other arguments in oder to create a fully qualified HTTP URL.
+* The `urlFromHostURIAndQuery()` function takes `host` and `uri` string arguments together with a `query` plain old JavaScript object argument. 
+It creates a query string from the `query` object and concatenates this with the two other arguments in oder to create a fully qualified HTTP URL.
 
 ```
 const host = "https://site.com",
@@ -971,9 +1048,11 @@ Ideally the `host` argument should not include a trailing forward slash whereas
 - `indexOf()`
 - `substring()`
 
-String functions with support for Unicode. Specifically, characters in Unicode astral plains are counted twice in native string functions and methods whereas these functions effectively count astral Unicode characters only once. 
+String functions with support for Unicode. 
+Specifically, characters in Unicode astral plains are counted twice in native string functions and methods whereas these functions effectively count astral Unicode characters only once. 
 
-* The `strlen()` function takes a single `string` argument. It works in much the same way as the `length` property of the `String` prototype, however it is Unicode safe:
+* The `strlen()` function takes a single `string` argument. 
+It works in much the same way as the `length` property of the `String` prototype, however it is Unicode safe:
 
 ```
 "𝔸𝔹C".length = 5  // The 𝔹 and C characters are in an astral plane and count as two each.
@@ -982,7 +1061,10 @@ strlen("𝔸𝔹C") = 3 // The string is converted to an array whose length is 3
 
 ```
 
-* The `strcmp` function takes `stringA` and `stringB` arguments. It compares them character by character in order to find the lexicographically lesser of the two. Its return value is the difference between the code points of the first differing characters, with the code point of either string given as zero if it is empty. Some examples should clarify:
+* The `strcmp` function takes `stringA` and `stringB` arguments. 
+It compares them character by character in order to find the lexicographically lesser of the two. 
+Its return value is the difference between the code points of the first differing characters, with the code point of either string given as zero if it is empty. 
+Some examples should clarify:
 
 ```
 strcmp("", "") = 0;
@@ -1012,7 +1094,8 @@ indexOf("𝔸b", "b"); // Returns 1.
 
 In the above example the aforementioned native method would return 2.
 
-* The `substring()` function takes `string` and `start` arguments and an optional `end` argument. It works in much the same way as the `substring()` method of the `String` prototype, however it is Unicode safe:
+* The `substring()` function takes `string` and `start` arguments and an optional `end` argument. 
+It works in much the same way as the `substring()` method of the `String` prototype, however it is Unicode safe:
 
 ```
 "𝔸𝔹C".substring(3) = "C" // The 𝔹 character is in an astral plane and counts as two.  
@@ -1026,7 +1109,8 @@ Note the native `substring()` method can be particularly egregious because the `
 
 - `migrate()`
 
-A single `migrate()` function to handle the migration of JSON files with a required `version` entry. This function can be used in conjunction with the configuration utilities but does not have to be.
+A single `migrate()` function to handle the migration of JSON files with a required `version` entry. 
+This function can be used in conjunction with the configuration utilities but does not have to be.
 
 * The `migrate` function takes `json`, `migrationMap` and `latestVersion` arguments. Perhaps the easiest way to demonstrate its use is by way of an extensive example.
 
@@ -1074,7 +1158,8 @@ function migrateConfigurationFile() {
 }
 ```
 
-Note carefully the matching of the keys to their corresponding values. Each key matches the version that the `migrate()` function finds in the JSON. It therefore must apply the requisite migration function to migrate the JSON to the next version. 
+Note carefully the matching of the keys to their corresponding values. Each key matches the version that the `migrate()` function finds in the JSON. 
+It therefore must apply the requisite migration function to migrate the JSON to the next version. 
 
 Lastly, the migration function must have the prescribed signature and return the migrated JSON. Again an example will suffice:
 
@@ -1092,7 +1177,8 @@ function migrateConfigurationToVersion_2_0(configuration) {
 }
 ```
 
-In this admittedly somewhat trivial example, all the migration function does is to update the version number. Exactly how the JSON otherwise changes is immaterial but the version number must be updated in this way otherwise the `migrate()` function will loop indefinitely.
+In this admittedly somewhat trivial example, all the migration function does is to update the version number. 
+Exactly how the JSON otherwise changes is immaterial but the version number must be updated in this way otherwise the `migrate()` function will loop indefinitely.
 
 ## Asynchronous utilities
 
@@ -1102,9 +1188,13 @@ In this admittedly somewhat trivial example, all the migration function does is
 - `eventually()`
 - `repeatedly()`
 
-These functions generally take either an operation or an array of operations, an operation being a function that mutates a context rather than returning a value. They also take a `done()` function and an optional `context` argument. They all pass a `next()` function to the operations followed by the `done()` function, the `context` and then an `index` argument. Operations can call the `done()` function instead of the `next()` function in order to terminate early.
+These functions generally take either an operation or an array of operations, an operation being a function that mutates a context rather than returning a value. 
+They also take a `done()` function and an optional `context` argument. 
+They all pass a `next()` function to the operations followed by the `done()` function, the `context` and then an `index` argument. Operations can call the `done()` function instead of the `next()` function in order to terminate early.
 
-* The `whilst()` function takes a single operation, which it calls each time the operation invokes the given `next()` function or until the operation invokes the given `done()` function. The operation can also force termination by returning a truthy value, in which case it must *not* call the given `next()` or `done()` functions. In the example below the operation will be executed ten times:
+* The `whilst()` function takes a single operation, which it calls each time the operation invokes the given `next()` function or until the operation invokes the given `done()` function. 
+The operation can also force termination by returning a truthy value, in which case it must *not* call the given `next()` or `done()` functions. 
+In the example below the operation will be executed ten times:
 
 ```
 const context = {}; ///
@@ -1126,7 +1216,9 @@ whilst(operation, () => {
 }, context);
 ```
 
-* The `forEach()` function takes an array as the first argument followed by a single operation, which it calls for each element of the array unless the operation invokes the given `done()` function. If the `done()` function is never invoked by the operation, it is called once each of the array elements has been passed to the operation, provided the operationinvokes the given `next ()` function each time. In the example below the operation will be executed four times:
+* The `forEach()` function takes an array as the first argument followed by a single operation, which it calls for each element of the array unless the operation invokes the given `done()` function. 
+If the `done()` function is never invoked by the operation, it is called once each of the array elements has been passed to the operation, provided the operation invokes the given `next ()` function each time. 
+In the example below the operation will be executed four times:
 
 ```
 const context = {};
@@ -1150,7 +1242,9 @@ forEach(array, operation, () => {
 }, context);
 ```
 
-* The `sequence()` function takes an array of operations, which it calls in turn unless the operation invokes the given `done()` function. If the `done()` function is never invoked by a operation, it is called once each of the operations have been called, provided each operation invokes the given `next ()` function. In the example below each of the operations bar the last is executed:
+* The `sequence()` function takes an array of operations, which it calls in turn unless the operation invokes the given `done()` function. 
+If the `done()` function is never invoked by a operation, it is called once each of the operations have been called, provided each operation invokes the given `next ()` function. 
+In the example below each of the operations bar the last is executed:
 
 ```
 const context = {};
@@ -1171,7 +1265,9 @@ sequence(operations, () => {
 }, context);
 ```
 
-* The `eventually()` function takes an array of operations, each of which it calls immediately without waiting for the operations to invoke the given `next()` functions. When each of the operations has invoked the given `next()` function, it will call the `done()` function. Note that in this case invoking the `done()` function from within a operation will not halt the execution of other operations, it is passed as an argument only for the sake of convention. In the example below each of the operations is executed:
+* The `eventually()` function takes an array of operations, each of which it calls immediately without waiting for the operations to invoke the given `next()` functions. When each of the operations has invoked the given `next()` function, it will call the `done()` function. 
+Note that in this case invoking the `done()` function from within a operation will not halt the execution of other operations, it is passed as an argument only for the sake of convention. 
+In the example below each of the operations is executed:
 
 ```
 const context = {};
@@ -1189,7 +1285,9 @@ eventually(operations, () => {
   /// done
 }, context);
 ```
-* The `repeatedly()` function takes a single operation and a `length` argument, immediately calling the operation a `length` number of times without waiting for it to invoke the given `next()` function each time. When the operation has invoked the given `next()` function a `length` number of times, it will call the `done()` function. Note that in this case invoking the `done()` function from within the operation will not halt its execution the requisite number of times, it is passed as an argument only for the sake of convention. In the example below the operation is executed ten times:
+* The `repeatedly()` function takes a single operation and a `length` argument, immediately calling the operation a `length` number of times without waiting for it to invoke the given `next()` function each time. When the operation has invoked the given `next()` function a `length` number of times, it will call the `done()` function. 
+Note that in this case invoking the `done()` function from within the operation will not halt its execution the requisite number of times, it is passed as an argument only for the sake of convention. 
+In the example below the operation is executed ten times:
 
 ```
 const context = {};
@@ -1209,7 +1307,8 @@ repeatedly(operation, length, () => {
 
 ## Building
 
-Automation is done with [npm scripts](https://docs.npmjs.com/misc/scripts), have a look at the `package.json` file. The pertinent commands are:
+Automation is done with [npm scripts](https://docs.npmjs.com/misc/scripts), have a look at the `package.json` file. 
+The pertinent commands are:
 
     npm run build-debug
     npm run watch-debug