From ba85af796eba936d96ead535022b8994344a06ef Mon Sep 17 00:00:00 2001
From: Ray <sympatheticfire@gmail.com>
Date: Wed, 14 Aug 2024 23:05:42 +0100
Subject: [PATCH] Updated array extension with docs

---
 src/extensions/array.js | 120 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 114 insertions(+), 6 deletions(-)

diff --git a/src/extensions/array.js b/src/extensions/array.js
index 95222c6..f85a4e6 100644
--- a/src/extensions/array.js
+++ b/src/extensions/array.js
@@ -19,15 +19,19 @@ Array.toFlatten = function (sourceArray, propName, destArray) {
   }
 };
 
-
+/**
+ * Add elements from an array into this array.
+ * @param {Array} array Array.
+ * @returns Array.
+ */
 Array.prototype.addRange = function (array) {
   if (array == null) {
     return this;
   }
 
-  for (let i = 0; i < array.length; i++) {
-    this.push(array[i]);
-  }
+  array.forEach(e => {
+    this.push(e);
+  });
 
   return this;
 };
@@ -70,6 +74,12 @@ Array.prototype.countMany = function (...filters) {
   return result;
 };
 
+/**
+ * Create an empty array of a given length with a given default value.
+ * @param {int} length Length of array.
+ * @param {object} value Default value.
+ * @returns Array.
+ */
 Array.prototype.create = function (length, value) {
   let result = [];
 
@@ -88,6 +98,12 @@ Array.prototype.flatten = function (propName) {
   return result;
 };
 
+/**
+ * Find index of first occurrence of value in property.
+ * @param {string} propName Property name.
+ * @param {object} value Property value.
+ * @returns Index of element.
+ */
 Array.prototype.index = function (propName, value) {
   const result = this.indexes(propName, value);
   if (result.length <= 0) {
@@ -97,6 +113,12 @@ Array.prototype.index = function (propName, value) {
   return result[0];
 };
 
+/**
+ * Find index of occurrences of value in property in array.
+ * @param {string} propName Property name.
+ * @param {object} value Property value.
+ * @returns Array of indexes.
+ */
 Array.prototype.indexes = function (propName, value) {
   let result = [];
 
@@ -117,6 +139,12 @@ Array.prototype.indexes = function (propName, value) {
   return result;
 };
 
+/**
+ * Insert an element into an array at index position.
+ * @param {int} index Array index.
+ * @param {object} item Array element.
+ * @returns Array.
+ */
 Array.prototype.insert = function(index, item) {
   if (index < 0) {
     this.splice(0, 0, item);
@@ -129,6 +157,11 @@ Array.prototype.insert = function(index, item) {
   return this;
 };
 
+/**
+ * Concatenates an array if value is not null or whitespace using a separator.
+ * @param {string} separator Separator text.
+ * @returns string.
+ */
 Array.prototype.joinIfNotNullOrWhitespace = function (separator) {
   const a = this;
 
@@ -149,6 +182,12 @@ Array.prototype.joinIfNotNullOrWhitespace = function (separator) {
   return result;
 };
 
+/**
+ * Returns first element that matches.
+ * @param {string} propName Property name.
+ * @param {string} value Property value.
+ * @returns Array element.
+ */
 Array.prototype.first = function (propName, value) {
   for (let i = 0; i < this.length; i++) {
     if (typeof(this[i][propName]) == "undefined") {
@@ -163,6 +202,11 @@ Array.prototype.first = function (propName, value) {
   return null;
 };
 
+/**
+ * Traverses an array tree following a property (by name), performing the defined function.
+ * @param {string} propName Property name.
+ * @param {function} func Function to perform at each element.
+ */
 Array.prototype.forEachTree = function (propName, func) {
   for (let i=0; i<this.length; i++) {
     if (func(this[i]) === false) {
@@ -179,6 +223,11 @@ Array.prototype.forEachTree = function (propName, func) {
   }
 };
 
+/**
+ * Sort an array alphanumerically using the named property (ascending).
+ * @param {string} propName Property name.
+ * @returns Array.
+ */
 Array.prototype.orderBy = function (propName) {
   this.sort(function(a, b) {
     if (a[propName] < b[propName]) {
@@ -193,6 +242,11 @@ Array.prototype.orderBy = function (propName) {
   return this;
 };
 
+/**
+ * Sort an array alphanumerically using the named property (descending).
+ * @param {string} propName Property name.
+ * @returns Array.
+ */
 Array.prototype.orderByDesc = function (propName) {
   this.sort(function(a, b) {
     if (a[propName] < b[propName]) {
@@ -207,6 +261,11 @@ Array.prototype.orderByDesc = function (propName) {
   return this;
 };
 
+/**
+ * Remove an element from an array.
+ * @param {object} element Element.
+ * @returns Array.
+ */
 Array.prototype.remove = function (element) {
   let result = [];
 
@@ -223,6 +282,11 @@ Array.prototype.remove = function (element) {
   return this;
 };
 
+/**
+ * Remove element at index position.
+ * @param {int} index Element index.
+ * @returns Array.
+ */
 Array.prototype.removeAt = function(index) {
   if ((index < 0) || (index >= this.length)) {
     return this;
@@ -233,6 +297,11 @@ Array.prototype.removeAt = function(index) {
   return this;
 };
 
+/**
+ * Remove elements in an array.
+ * @param {Array} array Array of elements to be removed.
+ * @returns Array.
+ */
 Array.prototype.removeRange = function (array) {
   for (let i=0; i<array.length; i++) {
     this.remove(array[i]);
@@ -242,8 +311,32 @@ Array.prototype.removeRange = function (array) {
 };
 
 /**
- * Find elements where a property equals a value.
- * @returns {Array} Of elements found.
+ * Returns array where each element's property does not equal value.
+ * @param {string} propName Property name.
+ * @param {*} value Property value.
+ * @returns Array.
+ */
+Array.prototype.notSelect = function (propName, value) {
+  let result = [];
+
+  for (let i = 0; i < this.length; i++) {
+    if (typeof(this[i][propName]) == "undefined") {
+      continue;
+    }
+
+    if (this[i][propName] != value){
+      result.push(this[i]);
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Returns array where each element's property equals value.
+ * @param {string} propName Property name.
+ * @param {*} value Property value.
+ * @returns Array.
  */
 Array.prototype.select = function (propName, value) {
   let result = [];
@@ -261,6 +354,11 @@ Array.prototype.select = function (propName, value) {
   return result;
 };
 
+/**
+ * Returns array where each element matches a set of property values.
+ * @param  {...any} filters Property-value pairs.
+ * @returns Array.
+ */
 Array.prototype.selectMany = function (...filters) {
   let result = this;
 
@@ -271,6 +369,11 @@ Array.prototype.selectMany = function (...filters) {
   return result;
 };
 
+/**
+ * Return array of element from array of object by property name.
+ * @param {string} propName Property name.
+ * @returns Array.
+ */
 Array.prototype.toList = function (propName) {
   let result = [];
 
@@ -285,6 +388,11 @@ Array.prototype.toList = function (propName) {
   return result;
 };
 
+/**
+ * Sort this object property using property name.
+ * @param {string} childPropName Property name.
+ * @param {string} sortPropName Sort by property name.
+ */
 Array.prototype.sortTree = function (childPropName, sortPropName) {
   this.orderBy(sortPropName);