si-funciona 2.6.1 → 2.7.0

package/README.md

@@ -249,6 +249,7 @@ Simplify working with object by providing array-like parsing. Also, provides clo
         * [.mapObject(obj, fn, [thisArg])](#module_objectHelpers.mapObject) ⇒ <code>Object</code> \| <code>Array</code>
         * [.isObject(object)](#module_objectHelpers.isObject) ⇒ <code>boolean</code>
         * [.isInstanceObject(object)](#module_objectHelpers.isInstanceObject) ⇒ <code>boolean</code>
+        * [.isEqual(first, second)](#module_objectHelpers.isEqual) ⇒ <code>boolean</code>
         * [.isCloneable(value)](#module_objectHelpers.isCloneable) ⇒ <code>boolean</code>
         * [.filterObject(obj, fn, [thisArg])](#module_objectHelpers.filterObject) ⇒ <code>Object</code> \| <code>Array</code>
         * [.emptyObject(item)](#module_objectHelpers.emptyObject) ⇒ <code>boolean</code>
@@ -358,18 +359,19 @@ Optional flag will include the inherited keys from prototype chain when set.
 ### objectHelpers.mergeObjectsBase([options]) ⇒ <code>module:objectHelpers~mergeObjectsCallback</code> \| <code>mergeObjectsCallback</code>
 Perform a deep merge of objects. This will return a function that will combine all objects and sub-objects.
 Objects having the same attributes will overwrite from last object to first.
-NOTE: Use the mapLimit and relevancyRange to resolve "too much recursion" when the object is large and is known to
-have circular references. A high mapLimit may lead to heavy memory usage and slow performance.
+Every call of the returned function keeps its own record of the objects it has already visited (so circular
+references are followed only once, and an object which is referenced in several places is merged once), and nothing
+is remembered between calls: the results of separate calls never share state or go stale.
 
 **Kind**: static method of [<code>objectHelpers</code>](#module_objectHelpers)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | [options] | <code>Object</code> | <code>{}</code> |  |
-| [options.mapLimit] | <code>number</code> | <code>100</code> | Size of temporary reference array used in memory before assessing relevancy. |
+| [options.mapLimit] | <code>number</code> | <code>100</code> | Deprecated and ignored: the record of visited objects is now scoped to a single call, so it does not need trimming. |
 | [options.depthLimit] | <code>number</code> | <code>-1</code> | Control how many nested levels deep will be used, -1 = no limit, >-1 = nth level limited. |
-| [options.relevancyRange] | <code>number</code> | <code>1000</code> | Total reference map length subtract this range, any relevancy less than that amount at time of evaluation will be removed. |
-| [options.map] | <code>Iterable</code> \| <code>array</code> | <code>[]</code> | A predetermined list of references gathered (to be passed to itself during recursion). |
+| [options.relevancyRange] | <code>number</code> | <code>1000</code> | Deprecated and ignored: see mapLimit. |
+| [options.map] | <code>Iterable</code> \| <code>array</code> | <code>[]</code> | A predetermined list of references (source and the object it should resolve to) which every call starts from. It is only read, never added to. |
 | [options.useClone] | <code>boolean</code> | <code>false</code> |  |
 
 <a name="module_objectHelpers.mapObject"></a>
@@ -409,6 +411,26 @@ Check if the current object has inherited properties.
 | --- | --- |
 | object | <code>Object</code> \| <code>Array</code> | 
 
+<a name="module_objectHelpers.isEqual"></a>
+
+### objectHelpers.isEqual(first, second) ⇒ <code>boolean</code>
+Check whether two values are equal by value, however they are stored: two separately made arrays or objects with the
+same contents are equal, while two references only need to be the same when the value is a function.
+- Primitives are equal when they are the same value (and NaN equals NaN)
+- Arrays are equal when they have the same elements in the same order
+- Objects are equal when they have the same prototype (the same kind of object) and the same own properties with
+equal values, the order of the properties does not matter
+- Dates, regular expressions, Maps and Sets are compared by what they hold
+- Circular references are handled: a pair of objects which is already being compared is taken to be equal
+
+**Kind**: static method of [<code>objectHelpers</code>](#module_objectHelpers)  
+**Returns**: <code>boolean</code> - True when the values are equal.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| first | <code>\*</code> | The first value. |
+| second | <code>\*</code> | The second value. |
+
 <a name="module_objectHelpers.isCloneable"></a>
 
 ### objectHelpers.isCloneable(value) ⇒ <code>boolean</code>
@@ -504,8 +526,6 @@ Get a nested property value from an object.
 
 ### objectHelpers.cloneObject(object, [options]) ⇒ <code>Object</code>
 Clone objects for manipulation without data corruption, returns a copy of the provided object.
-NOTE: Use the mapLimit and relevancyRange to resolve "too much recursion" when the object is large and is known to
-have circular references. A high mapLimit may lead to heavy memory usage and slow performance.
 
 **Kind**: static method of [<code>objectHelpers</code>](#module_objectHelpers)  
 
@@ -513,9 +533,9 @@ have circular references. A high mapLimit may lead to heavy memory usage and slo
 | --- | --- | --- | --- |
 | object | <code>Object</code> |  | The original object that is being cloned |
 | [options] | <code>Object</code> | <code>{}</code> |  |
-| [options.mapLimit] | <code>number</code> | <code>100</code> | Size of temporary reference array used in memory before assessing relevancy. |
+| [options.mapLimit] | <code>number</code> | <code>100</code> | Deprecated and ignored (circular references are handled without trimming). |
 | [options.depthLimit] | <code>number</code> | <code>-1</code> | Control how many nested levels deep will be used, -1 = no limit, >-1 = nth level limited. |
-| [options.relevancyRange] | <code>number</code> | <code>1000</code> | Total reference map length subtract this range, any relevancy less than that amount at time of evaluation will be removed. |
+| [options.relevancyRange] | <code>number</code> | <code>1000</code> | Deprecated and ignored: see mapLimit. |
 
 <a name="module_objectHelpers..handleRetainObjects"></a>
 
@@ -577,31 +597,40 @@ Reduce several numbers to their simplest form / ratio
 <a name="module_numberHelpers.randomNumber"></a>
 
 ### numberHelpers.randomNumber(range, [offset], [interval]) ⇒ <code>number</code>
-Create a single random number within provided range. And with optional offset,
-The distance between the result numbers can be adjusted with interval.
+Create a single random number from offset up to (but never including) offset + range. With optional offset,
+the distance between the result numbers can be adjusted with interval. Matches randomInteger, which gives the
+whole numbers of the same span.
 
 **Kind**: static method of [<code>numberHelpers</code>](#module_numberHelpers)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| range | <code>number</code> |  | Choose the breadth of the random number (0-100 would be 100 for range) |
-| [offset] | <code>number</code> | <code>0</code> | Choose the starting number (1-10 would be 1 for offset, 9 for range) |
-| [interval] | <code>number</code> | <code>1</code> | Choose the distance between numbers (~5, ~10, ~15 would be 5 for interval, 1 for offset, 2 for range) |
+| range | <code>number</code> |  | Choose the breadth of the random number (0 up to, but not including, 100 would be 100 for range) |
+| [offset] | <code>number</code> | <code>0</code> | Choose the starting number (1 up to, but not including, 10 would be 1 for offset, 9 for range) |
+| [interval] | <code>number</code> | <code>1</code> | Choose the multiplier applied to the result (~5, ~10, ~15 would be 5 for interval, 1 for offset, 2 for range) |
 
 <a name="module_numberHelpers.randomInteger"></a>
 
 ### numberHelpers.randomInteger(range, [offset], [interval]) ⇒ <code>number</code>
-Create a single random integer within provide range. And with optional offset,
-The distance between the result numbers can be adjusted with interval.
+Create a single random integer from a set of `range` possible values, starting at the optional offset.
+With no offset the result is 0 to range - 1 (so range is the number of possible values, the same as an array length
+when choosing an index). The distance between the result numbers can be adjusted with interval.
 
 **Kind**: static method of [<code>numberHelpers</code>](#module_numberHelpers)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| range | <code>number</code> |  | Choose the breadth of the random number (0-100 would be 100 for range) |
-| [offset] | <code>number</code> | <code>0</code> | Choose the starting number (1-10 would be 1 for offset, 9 for range) |
-| [interval] | <code>number</code> | <code>1</code> | Choose the distance between numbers (5, 10, 15 would be 5 for interval, 1 for offset, 2 for range) |
+| range | <code>number</code> |  | The number of possible values (0-99 would be 100 for range) |
+| [offset] | <code>number</code> | <code>0</code> | Choose the starting number (1-10 would be 1 for offset, 10 for range) |
+| [interval] | <code>number</code> | <code>1</code> | Choose the distance between numbers (5, 10, 15 would be 5 for interval, 1 for offset, 3 for range) |
 
+**Example**  
+```js
+randomInteger(1) // always 0 (one possible value)
+randomInteger(2) // 0 or 1
+randomInteger(3, 1, 5) // 5, 10 or 15
+items[randomInteger(items.length)] // a random valid index
+```
 <a name="module_numberHelpers.lowestCommonDenominator"></a>
 
 ### numberHelpers.lowestCommonDenominator(...numbers) ⇒ <code>number</code>

package/browser/siFunciona.js

@@ -1707,13 +1707,19 @@
     })
     exports.default = void 0
     /**
- * Create a single random integer within provide range. And with optional offset,
- * The distance between the result numbers can be adjusted with interval.
+ * Create a single random integer from a set of `range` possible values, starting at the optional offset.
+ * With no offset the result is 0 to range - 1 (so range is the number of possible values, the same as an array length
+ * when choosing an index). The distance between the result numbers can be adjusted with interval.
+ * @example
+ * randomInteger(1) // always 0 (one possible value)
+ * randomInteger(2) // 0 or 1
+ * randomInteger(3, 1, 5) // 5, 10 or 15
+ * items[randomInteger(items.length)] // a random valid index
  * @memberOf module:numberHelpers
- * @param {number} range - Choose the breadth of the random number (0-100 would be 100 for range)
- * @param {number} [offset=0] - Choose the starting number (1-10 would be 1 for offset, 9 for range)
+ * @param {number} range - The number of possible values (0-99 would be 100 for range)
+ * @param {number} [offset=0] - Choose the starting number (1-10 would be 1 for offset, 10 for range)
  * @param {number} [interval=1] - Choose the distance between numbers (5, 10, 15 would be 5 for interval, 1 for
- * offset, 2 for range)
+ * offset, 3 for range)
  * @returns {number}
  */
     const randomInteger = (range, offset = 0, interval = 1) => (Math.floor(Math.random() * range) + offset) * interval
@@ -1727,13 +1733,14 @@
     })
     exports.default = void 0
     /**
- * Create a single random number within provided range. And with optional offset,
- * The distance between the result numbers can be adjusted with interval.
+ * Create a single random number from offset up to (but never including) offset + range. With optional offset,
+ * the distance between the result numbers can be adjusted with interval. Matches randomInteger, which gives the
+ * whole numbers of the same span.
  * @memberOf module:numberHelpers
- * @param {number} range - Choose the breadth of the random number (0-100 would be 100 for range)
- * @param {number} [offset=0] - Choose the starting number (1-10 would be 1 for offset, 9 for range)
- * @param {number} [interval=1] - Choose the distance between numbers (~5, ~10, ~15 would be 5 for interval, 1 for
- * offset, 2 for range)
+ * @param {number} range - Choose the breadth of the random number (0 up to, but not including, 100 would be 100 for range)
+ * @param {number} [offset=0] - Choose the starting number (1 up to, but not including, 10 would be 1 for offset, 9 for range)
+ * @param {number} [interval=1] - Choose the multiplier applied to the result (~5, ~10, ~15 would be 5 for interval,
+ * 1 for offset, 2 for range)
  * @returns {number}
  */
     const randomNumber = (range, offset = 0, interval = 1) => (Math.random() * range + offset) * interval
@@ -1959,14 +1966,12 @@
     function _interopRequireDefault (e) { return e && e.__esModule ? e : { default: e } }
     /**
  * Clone objects for manipulation without data corruption, returns a copy of the provided object.
- * NOTE: Use the mapLimit and relevancyRange to resolve "too much recursion" when the object is large and is known to
- * have circular references. A high mapLimit may lead to heavy memory usage and slow performance.
  * @memberOf module:objectHelpers
  * @param {Object} object - The original object that is being cloned
  * @param {Object} [options={}]
- * @param {number} [options.mapLimit=100] - Size of temporary reference array used in memory before assessing relevancy.
+ * @param {number} [options.mapLimit=100] - Deprecated and ignored (circular references are handled without trimming).
  * @param {number} [options.depthLimit=-1] - Control how many nested levels deep will be used, -1 = no limit, >-1 = nth level limited.
- * @param {number} [options.relevancyRange=1000] - Total reference map length subtract this range, any relevancy less than that amount at time of evaluation will be removed.
+ * @param {number} [options.relevancyRange=1000] - Deprecated and ignored: see mapLimit.
  * @returns {Object}
  */
     const cloneObject = (object, {
@@ -2506,91 +2511,89 @@
     })
     exports.default = void 0
     require('core-js/modules/esnext.iterator.constructor.js')
-    require('core-js/modules/esnext.iterator.find.js')
     require('core-js/modules/esnext.iterator.map.js')
     require('core-js/modules/esnext.iterator.reduce.js')
+    require('core-js/modules/esnext.map.delete-all.js')
+    require('core-js/modules/esnext.map.every.js')
+    require('core-js/modules/esnext.map.filter.js')
+    require('core-js/modules/esnext.map.find.js')
+    require('core-js/modules/esnext.map.find-key.js')
+    require('core-js/modules/esnext.map.includes.js')
+    require('core-js/modules/esnext.map.key-of.js')
+    require('core-js/modules/esnext.map.map-keys.js')
+    require('core-js/modules/esnext.map.map-values.js')
+    require('core-js/modules/esnext.map.merge.js')
+    require('core-js/modules/esnext.map.reduce.js')
+    require('core-js/modules/esnext.map.some.js')
+    require('core-js/modules/esnext.map.update.js')
     const _isCloneable = _interopRequireDefault(require('./isCloneable'))
     const _reduceObject = _interopRequireDefault(require('./reduceObject'))
-    const _relevancyFilter = _interopRequireDefault(require('../functions/relevancyFilter'))
     const _setValue = _interopRequireDefault(require('./setValue'))
     function _interopRequireDefault (e) { return e && e.__esModule ? e : { default: e } }
     /**
  * Perform a deep merge of objects. This will return a function that will combine all objects and sub-objects.
  * Objects having the same attributes will overwrite from last object to first.
- * NOTE: Use the mapLimit and relevancyRange to resolve "too much recursion" when the object is large and is known to
- * have circular references. A high mapLimit may lead to heavy memory usage and slow performance.
+ * Every call of the returned function keeps its own record of the objects it has already visited (so circular
+ * references are followed only once, and an object which is referenced in several places is merged once), and nothing
+ * is remembered between calls: the results of separate calls never share state or go stale.
  * @memberOf module:objectHelpers
  * @param {Object} [options={}]
- * @param {number} [options.mapLimit=100] - Size of temporary reference array used in memory before assessing relevancy.
+ * @param {number} [options.mapLimit=100] - Deprecated and ignored: the record of visited objects is now scoped to a
+ * single call, so it does not need trimming.
  * @param {number} [options.depthLimit=-1] - Control how many nested levels deep will be used, -1 = no limit, >-1 = nth level limited.
- * @param {number} [options.relevancyRange=1000] - Total reference map length subtract this range, any relevancy less than that amount at time of evaluation will be removed.
- * @param {Iterable|array} [options.map=[]] - A predetermined list of references gathered (to be passed to itself during recursion).
+ * @param {number} [options.relevancyRange=1000] - Deprecated and ignored: see mapLimit.
+ * @param {Iterable|array} [options.map=[]] - A predetermined list of references (source and the object it should
+ * resolve to) which every call starts from. It is only read, never added to.
  * @param {boolean} [options.useClone=false]
  * @returns {module:objectHelpers~mergeObjectsCallback|mergeObjectsCallback}
  */
     const mergeObjectsBase = ({
-      mapLimit = 100,
       depthLimit = -1,
-      relevancyRange = 1000,
       map = [],
       useClone = false
-    } = {}) => (...objects) => {
-      const firstObject = useClone ? Array.isArray(objects[0]) ? [] : {} : objects.shift()
-      if (objects.length < 1) {
-        return firstObject
-      }
-      if (depthLimit === 0) {
-        return firstObject
-      }
-      return objects.reduce((newObj, arg) => {
-        if (!arg) {
-          return newObj
+    } = {}) => {
+      const merge = (visited, depth, objects) => {
+        const firstObject = useClone ? Array.isArray(objects[0]) ? [] : {} : objects.shift()
+        if (objects.length < 1) {
+          return firstObject
         }
-        map.push({
-          source: arg,
-          object: newObj,
-          relevance: map.length
-        })
-        map = (0, _relevancyFilter.default)(map, {
-          mapLimit,
-          relevancyRange
-        })
-        return (0, _reduceObject.default)(arg, (returnObj, value, key) => {
-          if ((0, _isCloneable.default)(value)) {
-            let objectValue = newObj[key]
-            const exists = map.find(existing => existing.source === value)
-            if (exists) {
-              exists.relevance = map.length + 1
-              return (0, _setValue.default)(key, exists.object, returnObj)
-            }
-            if (!(0, _isCloneable.default)(objectValue) || !objectValue) {
-              objectValue = useClone ? Array.isArray(value) ? [] : {} : value
-            }
-            if ((0, _isCloneable.default)(objectValue)) {
-              return (0, _setValue.default)(key, mergeObjectsBase({
-                mapLimit,
-                depthLimit: depthLimit - 1,
-                relevancyRange,
-                map,
-                useClone
-              })(objectValue, value), returnObj)
-            }
-            map.push({
-              source: value,
-              object: objectValue,
-              relevance: map.length
-            })
-            map = (0, _relevancyFilter.default)(map, {
-              mapLimit,
-              relevancyRange
-            })
+        if (depth === 0) {
+          return firstObject
+        }
+        return objects.reduce((newObj, arg) => {
+          if (!arg) {
+            return newObj
           }
-          return (0, _setValue.default)(key, value, returnObj)
-        }, newObj)
-      }, firstObject || {})
+          if (!visited.has(arg)) {
+            visited.set(arg, newObj)
+          }
+          return (0, _reduceObject.default)(arg, (returnObj, value, key) => {
+            if ((0, _isCloneable.default)(value)) {
+              if (visited.has(value)) {
+                return (0, _setValue.default)(key, visited.get(value), returnObj)
+              }
+              let objectValue = newObj[key]
+              if (!(0, _isCloneable.default)(objectValue) || !objectValue) {
+                if (!useClone) {
+                  // Merging by reference: the source object is used as it is, there is nothing to merge it into.
+                  visited.set(value, value)
+                  return (0, _setValue.default)(key, value, returnObj)
+                }
+                objectValue = Array.isArray(value) ? [] : {}
+              }
+              return (0, _setValue.default)(key, merge(visited, depth - 1, [objectValue, value]), returnObj)
+            }
+            return (0, _setValue.default)(key, value, returnObj)
+          }, newObj)
+        }, firstObject || {})
+      }
+      return (...objects) => merge(new Map(map.map(({
+        source,
+        object
+      }) => [source, object])), depthLimit, objects)
     }
     const _default = exports.default = mergeObjectsBase
-  }, { '../functions/relevancyFilter': 32, './isCloneable': 52, './reduceObject': 62, './setValue': 64, 'core-js/modules/esnext.iterator.constructor.js': 214, 'core-js/modules/esnext.iterator.find.js': 217, 'core-js/modules/esnext.iterator.map.js': 219, 'core-js/modules/esnext.iterator.reduce.js': 220 }],
+  }, { './isCloneable': 52, './reduceObject': 62, './setValue': 64, 'core-js/modules/esnext.iterator.constructor.js': 214, 'core-js/modules/esnext.iterator.map.js': 219, 'core-js/modules/esnext.iterator.reduce.js': 220, 'core-js/modules/esnext.map.delete-all.js': 222, 'core-js/modules/esnext.map.every.js': 223, 'core-js/modules/esnext.map.filter.js': 224, 'core-js/modules/esnext.map.find-key.js': 225, 'core-js/modules/esnext.map.find.js': 226, 'core-js/modules/esnext.map.includes.js': 227, 'core-js/modules/esnext.map.key-of.js': 228, 'core-js/modules/esnext.map.map-keys.js': 229, 'core-js/modules/esnext.map.map-values.js': 230, 'core-js/modules/esnext.map.merge.js': 231, 'core-js/modules/esnext.map.reduce.js': 232, 'core-js/modules/esnext.map.some.js': 233, 'core-js/modules/esnext.map.update.js': 234 }],
   59: [function (require, module, exports) {
     'use strict'