some-common-functions-js 1.1.0 → 1.1.3

package/CHANGELOG.md

@@ -33,7 +33,15 @@ Improve README.md documentation.
 ## Version 1.0.9 - 2025/11/28 - ITA
 - Provided more documentation in test.js to remind a developer how to symbolic-link (mimick as installed) the package and running the test code.
 - Added new function, hasOnlyAll(), and updated the README.md documentation accordingly.
-
+  
 ## Version 1.1.0 - 2025/12/22 - ITA
 - Improved documentation.
 - Moved in more functions to the package: `deepClone(anObject)`, `getSortedObject(anObject)`, `timeStampYyyyMmDd(dateInstance)` and `timeStampString(dateInstance)`.
+  
+## Version 1.1.1 - 2025/12/26 - ITA
+- Removed lodash dependency and re-implemented the get() and set() object functions, reducing package size.
+- Re-implemented the getSortedObj() function to no longer use the get() object function.
+- Improved the duplicate removal process in getArrayWithNoDuplicates() function, so as to be more reliable across all cases. Implemented the new getNextDifferentObject() function in the light of that.
+
+## Version 1.1.2 - 2025/12/26 - ITA
+Corrected a minor error in the README documentation.

package/README.md

@@ -6,16 +6,18 @@ Common functions used for working with JavaScript objects and validating field v
 ## Installation
 ```
 npm install some-common-functions-js
-```
+```  
+  
 ## 1. JavaScript Object Utilities
-
+  
 ### `deepClone(anObject)`
-Returns a deep clone of a plain Javascript object. The clone, while it has field equal to that of the original object, is separate from the original object.
-
+Returns a deep clone of a plain Javascript object. The clone, while it has field equal to that of the original object, is separate from the original object.  
+  
 ### `getPaths(anObject)`
 Returns a string array of path/field names inside a JavaScript object.  
+  
 ***Example***  
-```
+```  
 const { getPaths } = require("some-common-functions-js");  
 let client = {  
     name: "Jack",  
@@ -35,11 +37,14 @@ let client = {
 let paths = getPaths(client);  
 // ["name", "surname", "address.streetNum", "address.streetName", "address.suburb",  
 //  "address.town", "address.country.name", "address.country.code"] 
-```
+```  
+  
 ### `getSortedObject(anObject)`
-Returns an object with sorted fields, by ordered by field name ascending.  
-***Examples*** 
-``` 
+Returns an object with sorted fields, ordered by field name ascending.  
+  
+***Examples***  
+```  
+const { get } = require("common-functions-js");
 const client = {
     firstName: "Isaiah",
     lastName: "Tshabalala",
@@ -74,11 +79,90 @@ const sortedObject = getSortedObject(client);
         lastName: 'Tshabalala'
     }
 */
-``` 
+```  
+  
+### `get(anObject, path)`
+Returns the value of an object at the specified path.  
+Can take the place of lodash get() function.
+  
+***Examples***  
+```  
+const { get }  = require("some-common-functions-js");
+const client = {
+    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 result = get(client, "address.country"); 
+// { name: "South Africa", code: "ZA" }
+
+result = get(client, "address.country.code"); 
+// "ZA"
+```  
+  
+### `set(anObject, path)`
+Sets the value of an object at the specified path.  
+Can take the place of lodash set() function.
+  
+***Examples***   
+```  
+const { set } = require("some-common-functions-js");
+
+let emptyObj = {}; 
+set(emptyObj, "address.country.name", "South Africa");
+set(emptyObj, "address.country.code", "ZA");
+set(emptyObj, "firstName", "Isaiah");
+set(emptyObj, "lastName", "Tshabalala");
+console.log(emptyObj);
+/*
+{
+  address: { country: { name: 'South Africa', code: 'ZA' } },
+  firstName: 'Isaiah',
+  lastName: 'Tshabalala'
+}
+*/
+```  
+  
+### `unset(anObject, path)`  
+Remove a field from an object at the specified path.  
+Can take the place of lodash unset() function.  
+  
+***Example***  
+```
+const {unset} = require("some-common-functions-js");
+let testObj = {
+    firstName: 'John',
+    lastName: 'Rambo',
+    address: { country: { name: 'South Africa', code: 'ZA' } }
+};
+
+unset(testObj, "address.country.code");
+unset(testObj, "lastName");
+console.log(testObj); // Expecting to have "address.country.code" and "lastName" removed.
+/*
+    {
+        firstName: 'John',
+        address: { country: { name: 'South Africa' } }
+    }
+*/
+```  
+    
 ### `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");  
 
 let car = {  
@@ -97,12 +181,14 @@ result = hasOnly(car, "maxSpeed", "gvm", "power");
 
 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",  
@@ -116,11 +202,13 @@ let result = hasAll(car, "make", "model");
 
 let result = hasAll(car, "passengerCapacity", "year");  
 // false, because car does not have "passengerCapacity" field.  
-```
+```  
+  
 ### `hasOnlyAll(anObject, ...fields)`
-Return `true` if an object contains only all the specified fields, nothing more, nothing less
-***Example***
-```
+Return `true` if an object contains only all the specified fields, nothing more, nothing less  
+  
+***Examples***  
+```  
 const { hasOnlyAll } = require("some-common-functions-js");  
 let car = {  
     make: "Ford",  
@@ -327,20 +415,16 @@ console.log(objArray);
 */  
 let teams = [  
     {  
-        score: 85,  
-        numGames: 10  
+        score: 85, numGames: 10  
     },  
     {  
-        score: 90,  
-        numGames: 12  
+        score: 90, numGames: 12  
     },  
     {  
-        score: 85,  
-        numGames: 8  
+        score: 85, numGames: 8  
     },  
     {  
-        score: 90,  
-        numGames: 10  
+        score: 90, numGames: 10  
     }  
 ];  
 // Using objCompare to sort fields where there are mixed sort directions.  
@@ -396,35 +480,84 @@ Create an array of objects with duplicates eliminated. Taking only the first or
  * 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***  
 ```
 const { getObjArrayWithNoDuplicates } = require("some-common-functions-js");  
-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 }  
+let teamsArray = [
+    { score: 90, numGames: 10, name: "John" },
+    { score: 90, numGames: 10, name: "Jane" },
+    { score: 90, numGames: 10, name: "Bob" },
+    { score: 90, numGames: 12, name: "Alice" },
+    { score: 90, numGames: 12, name: "Charlie" },
+    { score: 90, numGames: 12, name: "David" },
+    { score: 85, numGames: 8, name: "Eve" },
+    { score: 85, numGames: 8, name: "Frank" },
+    { score: 85, numGames: 10, name: "Grace" },
+    { score: 85, numGames: 10, name: "Henry" },
+    { score: 85, numGames: 10, name: "Ivy" }
 ]; // Sorted by "score desc", "numGames asc".  
 
 let noDuplicatesArray = getObjArrayWithNoDuplicates(teamsArray, true, "score desc", "numGames asc");  
-console.log(noDuplicatesArray); // Should contain only unique objects according to comparison fields.  
+console.log(noDuplicatesArray);
+// Should contain only unique objects according to comparison fields. First object per duplicate group.
 /*  
-    [  
-        { score: 90, numGames: 10 },  
-        { score: 90, numGames: 12 },  
-        { score: 85, numGames: 8 },  
-        { score: 85, numGames: 10 }  
-    ]  
+    [
+        { score: 90, numGames: 10, name: 'John' },
+        { score: 90, numGames: 12, name: 'Alice' },
+        { score: 85, numGames: 8, name: 'Eve' },
+        { score: 85, numGames: 10, name: 'Grace' }
+    ]
 */  
-```
+
+let noDuplicatesArray = getObjArrayWithNoDuplicates(teamsArray, true, "score desc", "numGames asc");  
+console.log(noDuplicatesArray);
+// Should contain unique objects according to comparison fields. Last object per duplicate group.
+/*
+    [
+        { score: 90, numGames: 10, name: 'Bob' },
+        { score: 90, numGames: 12, name: 'David' },
+        { score: 85, numGames: 8, name: 'Frank' },
+        { score: 85, numGames: 10, name: 'Ivy' }
+    ]
+*/
+```  
+  
+### `getNextDifferent(objArray, targetObj, startFrom, ...comparisonFields)` 
+Get the index in the array of objects, of the next element that is distinct from the target object.  
+Comparison fields must match the field & sort order of the object array. 
+Throw an error if the target object is greater than objArray[startFrom] in terms of sort order.
+Examples of comparison fields: "firstName", "lastName desc", "address.province asc", "address.townOrCity".  
+  
+***Example***  
+```  
+const { getNextDifferent } = require("some-common-functions-js");
+
+teamsArray = [
+    { score: 90, numGames: 10, name: "John" },
+    { score: 90, numGames: 10, name: "Jane" },
+    { score: 90, numGames: 10, name: "Bob" },
+    { score: 90, numGames: 12, name: "Alice" },
+    { score: 90, numGames: 12, name: "Charlie" },
+    { score: 90, numGames: 12, name: "David" },
+    { score: 85, numGames: 8, name: "Eve" },
+    { score: 85, numGames: 8, name: "Frank" },
+    { score: 85, numGames: 10, name: "Grace" },
+    { score: 85, numGames: 10, name: "Henry" },
+    { score: 85, numGames: 10, name: "Ivy" }
+]; // Sorted by "score desc", "numGames asc".
+
+let next = getNextDifferent(teamsArray, { score: 85, numGames: 8 }, 0, "score desc", "numGames asc"); 
+// Throws an error because the startFrom index is to the left ('less than') the target object in terms of the field sort order.
+
+next = getNextDifferent(teamsArray, { score: 90, numGames: 10 }, 0, "score desc", "numGames asc");
+// 3
+
+
+next = getNextDifferentObj(teamsArray, { score: 85, numGames: 10 }, 0, "score desc", "numGames asc");
+// -1
+```  
+  
 ## 4. Date Timestamp Functions
 ### `timeStampYyyyMmDd(dateInstance)`
 Converts the date object to a string of the form CCYY-MM-DD 
@@ -432,6 +565,9 @@ Converts the date object to a string of the form CCYY-MM-DD
 ### `timeStampString(dateInstance)`
 Converts a date object to a string of the form CCYY-MM-DDThh:mm:ss.ccc, e.g. '2024-02-25T15:00:25.251'
   
+### `addLeadingZeros(aNumber, newLength)`
+Add leading zeros to a numerical string.  E.g. addLeadingZeros(9, 3) = '009'
+  
 ---
 ## License
 MIT

package/index.js

@@ -4,8 +4,11 @@
  * 2025/11/19  ITA   1.00     Genesis.
  * 2025/11/28  ITA   1.01     Added function hasOnlyAll().
  * 2025/12/22  ITA   1.02     Improved documentation of the functions and moved in more functions.
+ * 2025/12/30  ITA   1.03     Removed lodash dependency by re-implementing get() and set() object functions, significantly reducing this package size.
+ *                            Added function getNextDifferent() to deal better with duplicate removal from arrays of objects.
+ * 2026/01/02  ITA   1.04     Improved the functions getNoDuplicatesArray() and getNextDifferent() to handle more test cases.
+ *                            Added function unset().
 */
-const loDash = require('lodash');
 
 /**Return true if userName is valid
  * @param {string} userName
@@ -203,27 +206,101 @@ function getPaths(anObject) {
 } // function getPaths()
 module.exports.getPaths = getPaths;
 
-/** Return an object with sorted fields, by ordered by field name ascending.
+/** Return an object with sorted fields,  ordered by field name ascending.
  * This is desirable when equality comparison is done to ensure two objects sharing equal field values
  * the pass the equality test stringify(object1) === stringify(object2)
  * @param {object} pObject 
  * @returns {object} an object with fields sorted in ascending order of field names.
 */
 function getSortedObject(pObject) {
+  const objClone = deepClone(pObject);
+  const paths = [];
+  const sortedObject = {};
 
-  const paths = getPaths(pObject);
+  // Obtain the outermost fields and sort them.
+  for (let field in objClone) {
+    paths.push(field);
+  }
   paths.sort();
-  const sortedObject = {};
 
+  // Assign the sorted fields to the new object.
   for (let index in paths) {
-      const path = paths[index];
-      const value = loDash.get(pObject, path);
-      loDash.set(sortedObject, path, value);
-  } // for (index in paths) {
+    const field = paths[index];
+    if (Object.prototype.toString.call(objClone[field]) === '[object Object]') {
+        sortedObject[field] = getSortedObject(objClone[field]);
+    }
+    else {
+        sortedObject[field] = objClone[field];
+    } //
+  } // for (let field in paths) {
+
   return sortedObject;
 } // function getSortedObject(pObject) {
 module.exports.getSortedObject = getSortedObject;
 
+/** Get the value of a field specified by the path from an object.
+ * @param {object} anObject a Javascript object.
+ * @param {string} path a path specifying the field whose value is to be obtained.
+ * @returns {*} the value of the field specified by the path.
+ */
+function get(anObject, path) {
+    if (getPaths(anObject).includes(path) === false) {
+        console.log(hasAll(anObject, path), path, anObject, getPaths(anObject));
+        throw new Error(`Path ${path} does not exist on the object.`);
+    }
+    let paths = path.split('.');
+    let currentObj = deepClone(anObject);
+
+    let value = currentObj[paths[0]];
+    if (paths.length > 1) {
+        paths.splice(0, 1);
+        return get(value,  paths.join('.'));
+    }
+    else {
+        return value;
+    }
+}
+module.exports.get = get;
+
+/** Set the value of a field specified by the path on an object.
+ * @param {object} anObject a Javascript object.
+ * @param {string} path a path specifying the field whose value is to be set.
+ * @param {*} value the value to set.
+ */
+function set(anObject, path, value) {
+    let paths = path.split('.');
+    if (paths.length > 1) {
+        if (!anObject[paths[0]]) {
+            anObject[paths[0]] = {};
+        }
+        const subObject = anObject[paths[0]];
+        paths.splice(0, 1);
+        set(subObject, paths.join('.'), value);
+    }
+    else {
+        anObject[paths[0]] = value;
+    }
+}
+module.exports.set = set;
+
+/** Unset the value of a field specified by the path on an object.
+ * @param {object} anObject a Javascript object.
+ * @param {string} path a path specifying the field whose value is to be set.
+ * @param {*} value the value to set.
+ */
+function unset(anObject, path) {
+    let paths = path.split('.');
+    if (paths.length > 1) {
+        const subObject = anObject[paths[0]];
+        paths.splice(0, 1);
+        unset(subObject, paths.join('.'));
+    }
+    else {
+        delete anObject[paths[0]];
+    }
+}
+module.exports.unset = unset;
+
 /**
  * Determine whether an object contains only 1, some or all of the specified fields, and not any other fields.
  * @param {object} anObject a Javascript object.
@@ -393,6 +470,42 @@ function binarySearchObj(objArray, searchObj, startFrom = 0, ...sortFields) {
 } // function binarySearchObj(objArray, searchObj, ...comparisonFields) {
 module.exports.binarySearchObj = binarySearchObj;
 
+/**Get the index of the first element in an object array that is different from the target element 
+ * according to the comparison fields.
+ * @param {Array<object>} objArray an array of objects
+ * @param {object} targetObj target object
+ * @param {number} startFrom index from which to start searching
+ * @param {...string} comparisonFields comparison fields plus sort order.
+ * @returns index of the next different object.
+ */
+function getNextDifferent(objArray, targetObj, startFrom, ...comparisonFields) {
+    let start = startFrom,
+          end = objArray.length - 1;
+
+    
+    if (start >= objArray.length) { // throw error if startFrom is outside the bounds of the array.
+        throw new Error('startFrom is outside the bounds of the array.');
+    }
+    // If target object is to the right of objArray[start], then throw an error..
+    if (objCompare(targetObj, objArray[start], ...comparisonFields) > 0) {
+        throw new Error('targetObj is to the right (\'greater than\') objArray[startFrom].');
+    }
+         
+    while (start < end) {   
+        let mid = Math.trunc((start + end) / 2);
+        if (objCompare(targetObj, objArray[mid], ...comparisonFields) === 0) {
+            start = mid + 1;
+        }
+        else if (objCompare(targetObj, objArray[mid], ...comparisonFields) < 0) {
+            end = mid;
+        }
+    }
+    if (objCompare(targetObj, objArray[start], ...comparisonFields) === 0)
+        return -1;
+    return start;
+}
+module.exports.getNextDifferent = getNextDifferent;
+
 /**Create an array with duplicates eliminated, according to certain fields. 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.
@@ -407,89 +520,42 @@ module.exports.binarySearchObj = binarySearchObj;
  * @returns {Array<object>} an array with no duplicates.
  */
 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]}`);
+    if (typeof firstOfDuplicates !== 'boolean')
+        throw new Error(`firstOfDuplicates must be boolean true or false.`);
 
     const noDuplicates = [];
+    let idx = 0;
+    let grpStart = 0; // Start index of current duplicate group.
+    while (grpStart < objArray.length - 1) {
+        if (firstOfDuplicates) {
+            noDuplicates.push(objArray[grpStart]);
+        }
+
+        grpStart = getNextDifferent(objArray, objArray[grpStart], grpStart + 1, ...comparisonFields);
+        if (grpStart < 0)
+            break; // No more different objects.
 
-    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;
+        let grpEnd = grpStart - 1;
+        if (!firstOfDuplicates) {
+            noDuplicates.push(objArray[grpEnd]);
         }
-        else {
-            if (!firstOfDuplicates) {
-                noDuplicates.push(objArray[next]);
-            }
-            else {
-                noDuplicates.push(objArray[next]);
-            }
+        idx = grpStart;
+    }
+    if (noDuplicates.length === 0) { // All objects are duplicates.
+        if (firstOfDuplicates)
+            noDuplicates.push(objArray[0]);
+        else
+            noDuplicates.push(objArray[objArray.length - 1]);
+    }
+    else {
+        if (objCompare(noDuplicates[noDuplicates.length - 1], objArray[objArray.length - 1], ...comparisonFields) !== 0) {
+            noDuplicates.push(objArray[objArray.length - 1]);
         }
-        
-        nextSearchObj = getNextSearchObj(objArray[next]);
-        next++;
-    } // while (comparison !== 0 && next < objArray.length) {
+    }
 
     return noDuplicates;
 } // function getObjArrayWithNoDuplicates(objArray, ...comparisonFields) {
@@ -519,8 +585,8 @@ function objCompare(obj1, obj2, ...comparisonFields) {
         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 value1 = get(obj1, fieldName);
+        const value2 = get(obj2, fieldName);
 
         const returnValue = (sortDir === 'desc'? -1: 1);
         if (value1 > value2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "some-common-functions-js",
-  "version": "1.1.0",
+  "version": "1.1.3",
   "description": "Common functions used with Javascript objects, and field validation functions.",
   "keywords": [
     "validation",
@@ -23,21 +23,18 @@
     "object utilities",
     "object validation",
     "object array search",
-    "object compaare",
+    "object compare",
     "nodejs"
   ],
   "repository": {
     "type": "git",
     "url": "https://github.com/IsaiahTshabalala/common-functions"
   },
-  "license": "ISC",
+  "license": "MIT",
   "author": "ITA",
   "type": "commonjs",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "dependencies": {
-    "lodash": "^4.17.21"
   }
 }