some-common-functions-js 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Change log
+
+## Version 1.00 - 2025/11/19 - ITA
+Genesis.
+
+## Version 1.01 - 2025/11/19 - ITA
+Improve README.md documentation.
+
+## Version 1.02 - 2025/11/20 - ITA
+- Improve README.md documentation and move documentation of changes to CHANGELOG.md
+- Move more previously tested and used utility functions to this package. These are:
+  - compare(value1, value2, sortDir = 'asc')  
+  - binarySearch(anArray, searchVal, startFrom = 0, arraySortDir = 'asc')
+  - objCompare(obj1, obj2, ...comparisonFields)
+  - binarySearchObj(objArray, searchObj, startFrom, ...sortFields)
+  - getObjArrayWithNoDuplicates(objArray, firstOfDuplicates, ...comparisonFields)
+- Add the "lodash" dependency used by some of these newly added functions.
+

package/README.md

@@ -3,73 +3,81 @@
 Common functions used for working with JavaScript objects and validating field values.
 
 ---
+## Installation
+**npm install some-common-functions-js**
 
 ## 1. JavaScript Object Utilities
 
 ### `getPaths(anObject)`
-Returns a string array of path/field names inside a JavaScript object.
-** Example **
-let client = {
-    name: "Jack",
-    surname: "Stober",
-    address: {
-        streetNum: "57",
-        streetName: "Tiger Drive",
-        suburb: "Lakeside Ext.1",
-        town: "Lakeside",
-        country {
-            name: "South Africa",
-            code: "za"
-        }
-    }
-};
-
-let paths = getPaths(client);
-// ["name", "surname", "address.streetNum", "address.streetName", "address.suburb",
-//  "address.town", "address.country.name", "address.country.code"]
+Returns a string array of path/field names inside a JavaScript object.  
+***Example***  
+const { getPaths } = require("some-common-functions-js");  
+```
+let client = {  
+    name: "Jack",  
+    surname: "Stober",  
+    address: {  
+        streetNum: "57",  
+        streetName: "Tiger Drive",  
+        suburb: "Lakeside Ext.1",  
+        town: "Lakeside",  
+        country {  
+            name: "South Africa",  
+            code: "za"  
+        }  
+    }  
+};  
 
+let paths = getPaths(client);  
+// ["name", "surname", "address.streetNum", "address.streetName", "address.suburb",  
+//  "address.town", "address.country.name", "address.country.code"]  
+```
 ### `hasOnly(anObject, ...fields)`
-Returns `true` if the object contains **only** some or all of the specified fields and no others.
-** Examples **
-const { hasOnly } = require("some-common-functions-js");
+Returns `true` if the object contains **only** some or all of the specified fields and no others.  
+***Examples***  
+```
+const { hasOnly } = require("some-common-functions-js");  
 
-let car = {
-    make: "Ford",
-    model: "Ranger",
-    year: "2015",
-};
+let car = {  
+    make: "Ford",  
+    model: "Ranger",  
+    year: "2015",  
+};  
 
-let result = hasOnly(car, ["make", "model", "year"]);
-// true, because car has *only all of the specified fields and no other fields.
+let result = hasOnly(car, "make", "model", "year");  
+// true, because car has *only all of the specified fields and no other fields.  
 
-result = hasOnly(car, ["make", "model", "year", "maxSpeed", "gvm"]);
-// true, because car has *only some of the specified fields and no other fields.
+result = hasOnly(car, "make", "model", "year", "maxSpeed", "gvm");  
+// true, because car has *only some of the specified fields and no other fields.  
 
-result = hasOnly(car, ["maxSpeed", "gvm", "power"]);
-// false, because car has fields other than the specified fields.
+result = hasOnly(car, "maxSpeed", "gvm", "power");  
+// false, because car has fields other than the specified fields.  
 
-result = hasOnly(car, ["make", "model"]);
-// false, because car has fields other than the specified fields.
+result = hasOnly(car, "make", "model");  
+// false, because car has fields other than the specified fields.  
+```
 
 ### `hasAll(anObject, ...fields)`
 Returns `true` if the object contains **all** the specified fields.  
-The object may contain additional fields.
-** Examples **
-const { hasAll } = require("some-common-functions-js");
-
-let car = {
-    make: "Ford",
-    model: "Ranger",
-    year: "2015",
-    power: "1000kW",
-    type: "pickup truck"
-};
-
-let result = hasAll(car, ["make", "model"]);
-// true, because car has all the specified fields.
-
-let result = hasAll(car, ["passengerCapacity", "year"]);
-// false, because car does not have "passengerCapacity" field.
+The object may contain additional fields.  
+***Examples***  
+```
+const { hasAll } = require("some-common-functions-js");  
+
+let car = {  
+    make: "Ford",  
+    model: "Ranger",  
+    year: "2015",  
+    power: "1000kW",  
+    type: "pickup truck"  
+};  
+
+let result = hasAll(car, "make", "model");  
+// true, because car has all the specified fields.  
+
+let result = hasAll(car, "passengerCapacity", "year");  
+// false, because car does not have "passengerCapacity" field.  
+```
 ---
 
 ## 2. Field Validation Functions
@@ -92,7 +100,308 @@ Returns `true` if an organisation name is valid.
 ### `isValidPassword(password)`
 Returns `true` if the password meets the required strength rules.
 
+## 3. Comparison and Binary Search functions for primitive types and javascript objects
+
+### `compare(value1, value2, sortDir = 'asc')`
+Compares two values of the same primitive type, according to the sort direction.  
+* A return value of -1 means that value1 is before value2 in terms of sort order.
+* A return value of 1 means that value1 is after value2 in terms of sort order.
+* A return value of 0 means that value1 is equal to value2.
+* Sort directions: 'asc', 'desc'. Default is 'asc'.
+
+***Examples***  
+const { compare } = require("some-common-functions-js");  
+
+let x = "Fong Kong";  
+let y = "Isaiah Tshabalala";  
+let result = compare(x, y);  // -1 because "Fong Kong" is before "Isaiah Tshabalala" in ascending order.  
+result = compare(y, x);  
+console.log(result); // 1 because "Isaiah Tshabalala" is after "Fong Kong" in ascending order.  
+
+result = compare(x, y, 'desc');  
+console.log(result); // 1 because "Fong Kong" is after "Isaiah Tshabalala" in descending order.
+
+### `binarySearch(anArray, searchVal, startFrom = 0, arraySortDir = 'asc')`
+Binary Searches a sorted primitive type array for a value and returns the index.  
+* ArraySortDir specifies the direction in which the array is sorted (desc or asc).
+* If the array contains the value searched for, then the index returned is the location of this value on the array,
+* otherwise, the index is of closest value in the array that is before or after the search value in terms of sort order.
+* The programmer must write equality-check code to determine if the array element at the returned index is indeed the sought element.
+* Value of -1 is returned for an empty array.
+* This function is to be used also in cases where values are to be inserted into the array while maintaining sort order.
+* Sort directions: 'asc', 'desc'. Default is 'asc'.
+
+ ***Example***  
+ const { binarySearch, compare } = require("some-common-functions-js");  
+ let myArray = [100, 101, 102, 103, 104, 105, 106, 107];  
+ let index = binarySearch(myArray, 103); // 3  
+ let result = compare(103, myArray[index]); // 0, 103 === myArray[index].  
+
+ index = binarySearch(myArray, 103, 4); // 4  
+ result = compare(103, myArray[4]); // -1 meaning 103 is less than (before) myArray[4]
+
+### `objCompare(obj1, obj2, ...comparisonFields)`
+Compare 2 objects according to the comparison fields specified in the comparison fields, and return the result.
+* Each each of the comparisonFields must be of the form 'fieldName sortDirection' or 'fieldName'. 
+* Sort directions: 'asc', 'desc'. Default: 'asc'.
+* Examples: 'lastName desc', 'firstName', 'firstName asc', 'address.provinceName asc'.
+* If sort direction is not provided, then it is assumed to be ascending.
+
+***Example***  
+```
+const { objCompare } = require('some-common-functions-js');
+
+let anObject = {  
+    firstName: "Isaiah",  
+    lastName: "Tshabalala",  
+    address: {  
+        houseNum: "23-B",  
+        streetName: "Main Road",  
+        mainPlace: "Lakeside",  
+        subPlace: "Lakeside Ext.1",  
+        city: "Johannesburg",  
+        country: {  
+            name: "South Africa",  
+            code: "ZA"  
+        }  
+    }  
+};  
+
+let anObject2 = {  
+    firstName: "Lindiwe",  
+    lastName: "Tshabalala",  
+    address: {  
+        houseNum: "5520",  
+        streetName: "Main Road",  
+        mainPlace: "Evaton",  
+        subPlace: "Evaton Small Farms",  
+        city: "Vereeniging",  
+        country: {  
+            name: "South Africa",  
+            code: "ZA"  
+        }  
+    }  
+};  
+
+let result = objCompare(anObject, anObject2, "lastName", "firstName");  
+// -1 because "Tshabalala Isaiah" is before "Tshabalala Lindiwe" according to ascending order.  
+
+result objCompare(anObject, anObject2, "address.country.name", "address.city desc");  
+// 1 because same country (0), but "Johannesburg" is after "Vereeniging" according to descending order.  
+
+let anObject3 = {  
+    firstName: "Huang",  
+    lastName: "Shi",  
+    address: {  
+        houseNum: "5520",  
+        streetName: "Yuan Road",  
+        mainPlace: "Qīngyún Chéng",  
+        subPlace: "Phase 1",  
+        city: "Dragon City",  
+        country: {  
+            name: "China",  
+            code: "CN"  
+        }  
+    }  
+};  
+
+let objArray = [anObject2, anObject, anObject3];  
+// Using objCompare to sort objects in objArray using multiple fields including nested fields.  
+objArray.sort((obj1, obj2)=> {  
+                    return commonFunctions.objCompare(  
+                                                        obj1, obj2,  
+                                                        "address.country.name",  
+                                                        "address.city",  
+                                                        "adress.mainPlace",  
+                                                        "address.subPlace",  
+                                                        "lastName",  
+                                                        "firstName"  
+                                                    );  
+                                                });  
+console.log(objArray);   
+
+/*  
+    [  
+        {  
+            firstName: 'Huang',  
+            lastName: 'Shi',  
+            address: {  
+                houseNum: '5520',  
+                streetName: 'Yuan Road',  
+                mainPlace: 'Qīngyún Chéng',  
+                subPlace: 'Phase 1',  
+                city: 'Dragon City',  
+                country: {  
+                    name: "China",  
+                    code: "CN"  
+                }  
+            }  
+        },  
+        {  
+            firstName: 'Albertina',  
+            lastName: 'Tshabalala',  
+            address: {  
+                houseNum: '5520',  
+                streetName: 'Main Road',  
+                mainPlace: 'Evaton',  
+                subPlace: 'Evaton Small Farms',  
+                city: 'Vereeniging',  
+                country: {  
+                    name: "South Africa",  
+                    code: "ZA"  
+                }  
+            }  
+        },  
+        {  
+            firstName: 'Isaiah',  
+            lastName: 'Tshabalala',  
+            address: {  
+                houseNum: '5520',  
+                streetName: 'Main Road',  
+                mainPlace: 'Evaton',  
+                subPlace: 'Evaton Small Farms',  
+                city: 'Vereeniging',  
+                country: {  
+                    name: "South Africa",  
+                    code: "ZA"  
+                }  
+            }  
+        }  
+    ]  
+*/  
+
+let teams = [  
+    {  
+        score: 85,  
+        numGames: 10  
+    },  
+    {  
+        score: 90,  
+        numGames: 12  
+    },  
+    {  
+        score: 85,  
+        numGames: 8  
+    },  
+    {  
+        score: 90,  
+        numGames: 10  
+    }  
+];  
+// Using objCompare to sort fields where there  
+teams.sort((team1, team2) => {  
+    return commonFunctions.objCompare(  
+                                        team1, team2,  
+                                        "score desc",  
+                                        "numGames asc"  
+                                    );  
+});  
+console.log(teams);  
+/*  
+
+let teams = [  
+    {  
+        score: 85,  
+        numGames: 10  
+    },  
+    {  
+        score: 90,  
+        numGames: 12  
+    },  
+    {  
+        score: 85,  
+        numGames: 8  
+    },  
+    {  
+        score: 90,  
+        numGames: 10  
+    }  
+];  
+// Sort by score descending, then by numGames ascending.  
+objArray.sort((team1, team2) => {  
+    return commonFunctions.objCompare(  
+                                        team1, team2,  
+                                        "score desc",  
+                                        "numGames asc"  
+                                    );  
+});  
+
+/*  
+    [  
+        { score: 90, numGames: 10 },  
+        { score: 90, numGames: 12 },  
+        { score: 85, numGames: 8 },  
+        { score: 85, numGames: 10 }  
+    ]  
+*/  
+```
+### `binarySearchObj(objArray, searchObj, startFrom, ...sortFields)`
+Binary Search the sorted (ascending or descending order) array of objects for a value and return the index.  
+* The assumption is that the array is sorted in order of 1 or more sort fields,
+* for example 'lastName asc', 'firstName', 'address.province asc', 'address.townOrCity asc'.
+* If sort direction is not provided, then it is assumed to be 'asc' (ascending).
+* If the array contains the object with values searched for, then the index returned is the location of this value in the array,
+* otherwise, the index is of the closest value in the array that is before or after the searchObj value.
+* Return -1 for an empty array.
+* Assumed field data types are Number, String and Date.
+* This function is to be used also in cases where objects are to be inserted into the array while maintaining sort order.
+
+***Example***  
+```
+let teamsArray = [  
+    { score: 90, numGames: 10 },  
+    { score: 90, numGames: 12 },  
+    { score: 85, numGames: 8 },  
+    { score: 85, numGames: 10 }  
+]; // Sorted by "score desc", "numGames asc".  
+
+
+let searchObj = { score: 85, numGames: 8 };  
+let anIndex = (commonFunctions.binarySearchObj(teamsArray, searchObj, "score desc", "numGames asc"));  
+
+let result = commonFunctions.objCompare(searchObj, teamsArray[anIndex], "score desc", "numGames asc"); // 0 -- an object with value { score: 85, numGames: 8} exists at teamsArray[anIndex];  
+```
+
+## 4. `getObjArrayWithNoDuplicates(objArray, firstOfDuplicates, ...comparisonFields)`
+Create an array of objects with duplicates eliminated. Taking only the first or last object from each duplicate set. The input array must be sorted according to the values comparisonFields.  
+ * If firstOfDuplicates === true, then the first element in each set of duplicates is taken.  
+ * if firstOfDuplicates === false, then the last element is taken from each set of duplicates.  
+ * Assumed field data types are Number, String and Date.  
+ * The array must be sorted according to the comparison fields before calling this function.  
+ * The value of the comparison field must include both the field name and sort direction.  
+ * Sort direction assumed to be "asc" if not provided.  
+ * Examples of comparison fields: "firstName", "lastName desc", "address.province asc", "address.townOrCity".  
+
+***Example***  
+```
+let teamsArray = [  
+    { score: 90, numGames: 10 },  
+    { score: 90, numGames: 10 },  
+    { score: 90, numGames: 10 },  
+    { score: 90, numGames: 12 },  
+    { score: 90, numGames: 12 },  
+    { score: 90, numGames: 12 },  
+    { score: 85, numGames: 8 },  
+    { score: 85, numGames: 8 },  
+    { score: 85, numGames: 10 },  
+    { score: 85, numGames: 10 },  
+    { score: 85, numGames: 10 }  
+]; // Sorted by "score desc", "numGames asc".  
+
+let noDuplicatesArray = commonFunctions.getObjArrayWithNoDuplicates(teamsArray, true, "score desc", "numGames asc");  
+console.log(noDuplicatesArray); // Should contain only unique objects according to comparison fields.  
+/*  
+    [  
+        { score: 90, numGames: 10 },  
+        { score: 90, numGames: 12 },  
+        { score: 85, numGames: 8 },  
+        { score: 85, numGames: 10 }  
+    ]  
+*/  
+```
+
 ---
 
 ## License
-MIT
+MIT
+

package/index.js

@@ -3,7 +3,7 @@
  * Date        Dev   Version  Description
  * 2025/11/19  ITA   1.00     Genesis.
 */
-
+const loDash = require('lodash');
 
 function isValidUserName(userName) {
     if (!userName) // The username must be provided.
@@ -85,7 +85,7 @@ module.exports.isValidPassword = isValidPassword;
 /**
  * Get the paths (fields) of the plain Javascript object.
  * @param {object} anObject 
- * @returns a string array of paths.
+ * @returns a sorted string array of paths.
  */
 function getPaths(anObject) {
     const paths = [];
@@ -155,4 +155,232 @@ function hasAll(anObject, ...fields) {
 
     return (count === fields.length);
 }
-module.exports.hasAll = hasAll;
+module.exports.hasAll = hasAll;
+
+
+/**Binary Search the sorted primitive data array for a value and return the index.
+ * ArraySortDir specifies the direction in which the array is sorted (desc or asc).
+ * If the array contains the value searched for, then the index returned is the location of this value on the array,
+ * otherwise, the index is of closest value in the array that is before or after the search value in terms of sort order.
+ * Return -1 for an empty array.
+ * This function is to be used also in cases where values are to be inserted into the array while maintaining sort order.
+ */
+function binarySearch(anArray, searchVal, startFrom = 0, arraySortDir = 'asc') {
+
+    const sortDirections = ['asc', 'desc']
+    if (!['asc', 'desc'].includes(arraySortDir))
+        throw new Error(`arraySortDir must be one of ${sortDirections}`);
+
+    if (anArray.length === 0)
+        return -1; // Empty array.
+
+    let start = startFrom,
+        end = anArray.length - 1;
+
+    while(start < end) {
+        if (compare(anArray[start], searchVal) === 0)
+            return start;
+        else if (compare(anArray[end], searchVal) === 0)
+            return end;
+
+        const mid = Math.trunc((start + end) / 2);
+        const comparison = compare(anArray[mid], searchVal, arraySortDir);
+        if (comparison < 0)
+            start = mid + 1;
+        else if (comparison > 0)
+            end = mid - 1;
+        else
+            return mid;
+    } // while(start < end) {
+
+    return start;
+} // function binarySearch(anArray, arraySortDir, searchVal) {
+module.exports.binarySearch = binarySearch;
+
+/** Compare two values of the same primitive type, according to the sort direction.
+ * A return value of -1 means that value1 is before value2 in terms of sort order.
+ * A return value of 1 means that value1 is after value2 in terms of sort order.
+ * A return value of 0 means that value1 is equal to value2.
+ * Sort directions: 'asc', 'desc'. Default is 'asc'.
+*/
+function compare(value1, value2, sortDir = 'asc') {
+    if (!['asc', 'desc'].includes(sortDir))
+        throw new Error(`sortDir must be one of ${sortDir}`);
+
+    const returnValue = (sortDir === 'desc'? -1 : 1);
+    if (value1 > value2)
+        return returnValue;
+    else if (value1 < value2)
+        return -returnValue;
+    else // Avoid if (value1 === value2) because this may yield false for reference types (ie. Dates), because of different memory addresses.
+        return 0;
+} // function compare(value1, value2, sortDir) {
+module.exports.compare = compare;
+
+/**Binary Search the sorted (ascending or descending order) array of objects for a value and return the index.
+ * The assumption is that the array is sorted in order of 1 or more sort fields,
+ * for example'lastName asc', 'firstName', 'address.province asc', 'address.townOrCity asc'.
+ * If the array contains the object with values searched for, then the index returned is the location of this value in the array,
+ * otherwise, the index is of the closest value in the array that is before or after the searchObj value.
+ * Return -1 for an empty array.
+ * Assumed field data types are Number, String and Date.
+ * This function is to be used also in cases where objects are to be inserted into the array while maintaining sort order.
+ */
+function binarySearchObj(objArray, searchObj, startFrom, ...sortFields) {
+    if (objArray.length === 0)
+        return -1;
+
+    let start = startFrom,
+        end = objArray.length - 1;
+
+    while(start < end) {
+        if (objCompare(objArray[start], searchObj, ...sortFields) === 0)
+            return start;
+        else if (objCompare(objArray[end], searchObj, ...sortFields) === 0)
+            return end;
+
+        let mid = Math.trunc((start + end) / 2);
+
+        if (objCompare(objArray[mid], searchObj, ...sortFields) < 0)
+            start = mid + 1;
+        else if (objCompare(objArray[mid], searchObj, ...sortFields) > 0)
+            end = mid - 1;
+        else
+            return mid;
+    } // while(start < end) {
+    
+    return start;
+} // function binarySearchObj(objArray, searchObj, ...comparisonFields) {
+module.exports.binarySearchObj = binarySearchObj;
+
+/**Create an array with duplicates eliminated. Taking only the first or last object from each duplicate set.
+ * If firstOfDuplicates === true, then the first element in each set of duplicates is taken.
+ * if firstOfDuplicates === false, then the last element is taken from each set of duplicates.
+ * Assumed field data types are Number, String and Date.
+ * The array must be sorted according to the comparison fields before calling this function.
+ * The value of the comparison field must include both the field name and sort direction.
+ * Sort direction assumed to be "asc" if not provided.
+ * Examples of comparison fields: "firstName", "lastName desc", "address.province asc", "address.townOrCity".
+ */
+function getObjArrayWithNoDuplicates(objArray, firstOfDuplicates, ...comparisonFields) {
+    function getNextSearchObj(pNext) {
+        const nextObj = {...objArray[next]};
+        let lastField;
+        if (comparisonFields.length > 0)
+            lastField = comparisonFields[comparisonFields.length - 1].split(' ');
+        else
+            throw new Error('Supply atleast 1 comparisonFields parameter.');
+
+        const lastFieldName = lastField[0];
+        const sortDir = lastField.length > 1? lastField[1] : 'asc';
+        const lastFieldValue = loDash.get(nextObj, lastFieldName);
+
+        if (typeof lastFieldValue === 'number') {
+            if (sortDir === 'asc')
+                loDash.set(nextObj, lastFieldName, 1e-10 + lastFieldValue);
+            else
+                loDash.set(nextObj, lastFieldName, -1e-10 + lastFieldValue);
+        }
+        else if (typeof lastFieldValue === 'string') { // instance of String
+            if (sortDir === 'asc')
+                loDash.set(nextObj, lastFieldName, lastFieldValue + ' ');
+            else
+                loDash.set(nextObj, lastFieldName, ' ' + lastFieldValue);
+        }
+        else if (lastFieldValue instanceof Date) {
+            if (sortDir === 'asc')
+                loDash.set(nextObj, lastFieldName, new Date(1 + lastFieldValue.getTime()));
+            else
+                loDash.set(nextObj, lastFieldName, new Date(-1 + lastFieldValue.getTime()));
+        }
+        else
+            throw new Error(`${lastFieldName} must be type Number, String or Date`);
+
+        return nextObj;
+    } // function getNextSearchObj(pNext)
+
+    if (objArray.length <= 1)
+        return [...objArray];
+
+    if (![true, false].includes(firstOfDuplicates))
+        throw new Error(`firstOfDuplicates must be one of ${[true, false]}`);
+
+    const noDuplicates = [];
+
+    let next = 0;
+    let nextSearchObj;
+    if ((firstOfDuplicates)) {
+        noDuplicates.push(objArray[next]);
+    }        
+    nextSearchObj = getNextSearchObj(objArray[next]);
+
+    while (next < objArray.length) {
+        // The aim is to jump to the next element that is not a duplicate of objArray[next].
+        next = binarySearchObj(objArray, nextSearchObj, next, ...comparisonFields);
+        let comparison = objCompare(objArray[next], nextSearchObj, ...comparisonFields);
+        if (comparison < 0) {
+            if (firstOfDuplicates) {
+                next++;
+                if  (next < objArray.length) {
+                    noDuplicates.push(objArray[next]);
+                    nextSearchObj = getNextSearchObj(objArray[next]);
+                }
+            }
+            else  {
+                noDuplicates.push(objArray[next]);
+                next++;
+                if (next < objArray.length)
+                    nextSearchObj = getNextSearchObj(objArray[next]);
+            }
+            continue;
+        }
+        else {
+            if (!firstOfDuplicates) {
+                noDuplicates.push(objArray[next]);
+            }
+            else {
+                noDuplicates.push(objArray[next]);
+            }
+        }
+        
+        nextSearchObj = getNextSearchObj(objArray[next]);
+        next++;
+    } // while (comparison !== 0 && next < objArray.length) {
+
+    return noDuplicates;
+} // function getObjArrayWithNoDuplicates(objArray, ...comparisonFields) {
+module.exports.getObjArrayWithNoDuplicates = getObjArrayWithNoDuplicates;
+
+/**Compare 2 objects according to the comparison fields specified in the comparison fields, and return the result.
+ * Each each of the comparisonFields must be of the form 'fieldName sortDirection' or 'fieldName'. 
+ * Sort directions: 'asc', 'desc'.
+ * Examples: 'lastName desc', 'firstName', 'firstName asc', 'address.provinceName asc'.
+ * If sort direction is not provided, then it is assumed to be ascending.
+*/
+function objCompare(obj1, obj2, ...comparisonFields) {
+    if (comparisonFields.length === 0)
+        throw new Error('comparisonFields not supplied!');
+
+    const sortDirections = ['', 'asc', 'desc'];
+    for (const index in comparisonFields) {
+        const field = comparisonFields[index].split(' ');
+        const fieldName = field[0];
+        let sortDir = '';
+        if (field.length === 2)
+            sortDir = field[1];
+
+        if (!sortDirections.includes(sortDir))
+            throw new Error('Sort direction must be one of ' + sortDirections.toString());
+
+        const value1 = loDash.get(obj1, fieldName);
+        const value2 = loDash.get(obj2, fieldName);
+
+        const returnValue = (sortDir === 'desc'? -1: 1);
+        if (value1 > value2)
+            return returnValue;
+        else if (value1 < value2)
+            return -returnValue;
+    } // for (const field in comparisonFields) {
+    return 0;
+} // function comparison(obj1, obj2, ...comparisonFields) {
+module.exports.objCompare = objCompare;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "some-common-functions-js",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Common functions used with Javascript objects, and field validation functions.",
   "keywords": [
     "validation",
@@ -12,6 +12,8 @@
     "password validation",
     "phone validation",
     "username validation",
+    "object comparison",
+    "comparison",
     "javascript",
     "utilities",
     "utility",
@@ -31,5 +33,8 @@
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
   }
 }