@jsopen/objects 2.1.1 → 2.2.1

package/README.md

@@ -7,6 +7,24 @@
 
 A 'swiss army knife' solution for working with javascript objects.
 
+## Functions
+
+### [merge](docs/merge.md)
+Is a powerful, flexible tool for merging objects, arrays, and their nested properties.
+
+### [clone / deepClone](docs/clone.md)
+Easy ways to create shallow or deep copies of objects and arrays.
+
+### [omit / omitUndefined / omitNull / omitNullish](docs/omit.md)
+Easily exclude specific keys or nullish values from objects.
+
+### [updateErrorMessage](docs/update-error-message.md)
+Update an Error object's message while correctly refreshing the stack trace.
+
+### [Utilities](docs/utils.md)
+Various utility functions for object and type checking.
+
+
 ## Installation
 
 `$ npm install @jsopen/objects`

package/merge.d.ts

@@ -18,8 +18,8 @@ export declare namespace merge {
         /**
          * Optional variable that determines the depth of an operation or inclusion behavior.
          *
-         * - If set to `true`, it enables a deep operation for only native js objects, excluding classes.
-         * - If set to `'full'`, it enables a deep operation for all objects, including classes, excluding built-in objects
+         * - If set to `true`, it enables a deep operation for only plain objects and arrays. Non-plain objects (class instances) are assigned by reference.
+         * - If set to `'full'`, it enables a deep operation for all objects, including classes, excluding built-in objects.
          * - If assigned a `NodeCallback` function, it provides a custom callback mechanism for handling the operation.
          *
          * This variable can be used to define the level of depth or customization for a given process.

package/merge.js

@@ -12,20 +12,20 @@ export function merge(targetObject, sourceObject, options) {
         Array.isArray(sourceObject))) {
         throw new TypeError('"target" argument must be an object or array of objects');
     }
-    const keepExisting = options?.keepExisting;
-    const keepExistingFn = typeof options?.keepExisting === 'function'
+    const optsKeepExisting = !!options?.keepExisting;
+    const optsKeepExistingFn = typeof options?.keepExisting === 'function'
         ? options?.keepExisting
         : undefined;
-    const filterFn = options?.filter;
-    const ignoreUndefined = options?.ignoreUndefined ?? true;
-    const ignoreNulls = options?.ignoreNulls;
-    const deep = options?.deep;
-    const deepFull = deep === 'full';
-    const deepFn = typeof options?.deep === 'function' ? options?.deep : undefined;
-    const copyDescriptors = options?.copyDescriptors;
-    const mergeArrays = options?.mergeArrays;
-    const mergeArraysUnique = options?.mergeArrays === 'unique';
-    const mergeArraysFn = typeof options?.mergeArrays === 'function'
+    const optsFilterFn = options?.filter;
+    const optsIgnoreUndefined = options?.ignoreUndefined ?? true;
+    const optsIgnoreNulls = options?.ignoreNulls;
+    const optsDeep = options?.deep;
+    const optsDeepFull = optsDeep === 'full';
+    const optsDeepFn = typeof options?.deep === 'function' ? options?.deep : undefined;
+    const optsCopyDescriptors = options?.copyDescriptors;
+    const optsMergeArrays = !!options?.mergeArrays;
+    const optsMergeArraysUnique = options?.mergeArrays === 'unique';
+    const optsMergeArraysFn = typeof options?.mergeArrays === 'function'
         ? options?.mergeArrays
         : undefined;
     const _merge = (target, source, parentPath = '') => {
@@ -37,18 +37,25 @@ export function merge(targetObject, sourceObject, options) {
         let key;
         let descriptor;
         let srcVal;
-        let _goDeep = false;
+        let trgVal;
+        let goDeep;
+        let srcIsPlainObject;
+        let srcIsArray;
+        let srcIsBuiltIn;
+        let trgIsArray;
+        let curPath;
+        let keepExisting;
         if (isPlainObject(target))
             Object.setPrototypeOf(target, Object.getPrototypeOf(source));
         const ignoreFn = options?.ignoreSource;
-        let i = 0;
+        let i;
         const len = keys.length;
         for (i = 0; i < len; i++) {
             key = keys[i];
             /** Should not overwrite __proto__ and constructor properties */
             if (key === '__proto__' || key === 'constructor')
                 continue;
-            if (copyDescriptors) {
+            if (optsCopyDescriptors) {
                 descriptor = Object.getOwnPropertyDescriptor(source, key);
                 if (descriptor?.get || descriptor?.set) {
                     Object.defineProperty(target, key, descriptor);
@@ -56,6 +63,7 @@ export function merge(targetObject, sourceObject, options) {
                 }
             }
             srcVal = source[key];
+            /** Check if the property should be ignored */
             if (ignoreFn?.(srcVal, {
                 key,
                 source,
@@ -64,76 +72,99 @@ export function merge(targetObject, sourceObject, options) {
             })) {
                 continue;
             }
-            _goDeep = !!(deep &&
-                typeof srcVal === 'object' &&
-                (!isBuiltIn(srcVal) || Array.isArray(srcVal)));
-            if (_goDeep) {
-                if (deepFn)
-                    _goDeep = deepFn(srcVal, {
-                        key,
-                        source,
-                        target,
-                        path: parentPath + (parentPath ? '.' : '') + String(key),
-                    });
-                else
-                    _goDeep = deepFull || isPlainObject(srcVal) || Array.isArray(srcVal);
-            }
-            if (!_goDeep && keepExisting && hasOwnProperty.call(target, key)) {
-                if (!keepExistingFn)
-                    continue;
-                if (keepExistingFn(srcVal, {
+            srcIsPlainObject = isPlainObject(srcVal);
+            srcIsArray = Array.isArray(srcVal);
+            srcIsBuiltIn = isBuiltIn(srcVal) && !srcIsArray;
+            trgVal = target[key];
+            trgIsArray = Array.isArray(trgVal);
+            curPath = parentPath + (parentPath ? '.' : '') + String(key);
+            if (optsFilterFn &&
+                !optsFilterFn(srcVal, {
                     key,
                     source,
                     target,
-                    path: parentPath + (parentPath ? '.' : '') + String(key),
+                    path: curPath,
                 })) {
-                    continue;
-                }
+                continue;
             }
-            if (filterFn &&
-                !filterFn(srcVal, {
+            /** Determine if we should go deeper into the object */
+            goDeep = !!(optsDeep &&
+                !srcIsBuiltIn &&
+                /** Source value should be an object */
+                typeof srcVal === 'object' &&
+                /** deep full or plain object */
+                (optsDeepFull || srcIsPlainObject || srcIsArray));
+            keepExisting =
+                optsKeepExisting &&
+                    hasOwnProperty.call(target, key) &&
+                    (!optsKeepExistingFn ||
+                        optsKeepExistingFn(srcVal, {
+                            key,
+                            source,
+                            target,
+                            path: curPath,
+                        }));
+            if (goDeep && optsDeepFn) {
+                goDeep = optsDeepFn(srcVal, {
                     key,
                     source,
                     target,
-                    path: parentPath + (parentPath ? '.' : '') + String(key),
-                })) {
-                continue;
+                    path: curPath,
+                });
             }
-            if (ignoreUndefined && srcVal === undefined) {
+            if (optsIgnoreUndefined && srcVal === undefined) {
                 continue;
             }
-            if (ignoreNulls && srcVal === null) {
+            if (optsIgnoreNulls && srcVal === null) {
                 continue;
             }
-            if (_goDeep) {
+            if (goDeep) {
+                // if (keepExisting) &&
                 /** Array */
-                if (Array.isArray(srcVal)) {
-                    if (Array.isArray(target[key]) &&
-                        (mergeArrays ||
-                            mergeArraysFn?.(srcVal, {
-                                key,
-                                source,
-                                target,
-                                path: parentPath + (parentPath ? '.' : '') + String(key),
-                            }))) {
-                        target[key] = _arrayClone(target[key], parentPath + (parentPath ? '.' : '') + String(key));
+                if (srcIsArray) {
+                    /** If the target value is not an array, we do not need a deep merge operation */
+                    if (!trgIsArray) {
+                        if (keepExisting)
+                            continue;
+                        srcVal = _arrayClone(srcVal, curPath);
+                    }
+                    else {
+                        srcVal = _arrayClone(srcVal, curPath);
+                        if (optsMergeArrays &&
+                            (!optsMergeArraysFn ||
+                                optsMergeArraysFn?.(srcVal, {
+                                    key,
+                                    source,
+                                    target,
+                                    path: curPath,
+                                }))) {
+                            srcVal = [...trgVal, ...srcVal];
+                            if (optsMergeArraysUnique)
+                                target[key] = Array.from(new Set(srcVal));
+                            else
+                                target[key] = srcVal;
+                            continue;
+                        }
+                        else {
+                            if (optsMergeArraysUnique)
+                                srcVal = Array.from(new Set(srcVal));
+                        }
                     }
-                    else
-                        target[key] = [];
-                    target[key].push(..._arrayClone(srcVal, parentPath + (parentPath ? '.' : '') + String(key)));
-                    if (mergeArraysUnique)
-                        target[key] = Array.from(new Set(target[key]));
-                    continue;
                 }
                 else {
                     /** Object */
-                    if (!isObject(target[key]))
+                    if (!isObject(target[key])) {
+                        if (keepExisting)
+                            continue;
                         target[key] = {};
-                    _merge(target[key], srcVal, parentPath + (parentPath ? '.' : '') + String(key));
+                    }
+                    _merge(target[key], srcVal, curPath);
                     continue;
                 }
             }
-            if (copyDescriptors) {
+            if (keepExisting)
+                continue;
+            if (optsCopyDescriptors) {
                 descriptor = { ...Object.getOwnPropertyDescriptor(source, key) };
                 descriptor.value = srcVal;
                 Object.defineProperty(target, key, descriptor);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jsopen/objects",
   "description": "Helper utilities for working with JavaScript objects and arrays",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/update-error-message.d.ts

@@ -3,10 +3,4 @@
  * @param err
  * @param newMessage
  */
-export declare function updateErrorMessage(err: Error, newMessage: string): Error | undefined;
-/**
- * Updates the error message and stack trace at sametime.
- * @param err
- * @param newMessage
- */
-export declare function updateErrorMessageFallback(err: Error, newMessage: string): Error;
+export declare function updateErrorMessage(err: Error, newMessage: string): Error;

package/update-error-message.js

@@ -5,22 +5,6 @@
  */
 export function updateErrorMessage(err, newMessage) {
     err.message = String(newMessage);
-    /** V8 */
-    if (typeof Error.captureStackTrace === 'function') {
-        Error.captureStackTrace(err);
-        return;
-    }
-    /** Other engines */
-    return updateErrorMessageFallback(err, newMessage);
-}
-/**
- * Updates the error message and stack trace at sametime.
- * @param err
- * @param newMessage
- */
-export function updateErrorMessageFallback(err, newMessage) {
-    err.message = String(newMessage);
-    /** Other engines */
     const stack = typeof err.stack === 'string' ? err.stack : null;
     if (!stack)
         return err;