rubico 2.7.2 → 2.7.4

package/x/defaultsDeep.js

@@ -1,33 +1,35 @@
 const isArray = require('../_internal/isArray')
+const curry2 = require('../_internal/curry2')
+const __ = require('../_internal/placeholder')
 
 /**
  * @name arrayDefaultsDeepFromArray
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var array Array<Array|Object|any>,
- *   defaultArray Array<Array|Object|any>,
- *
- * arrayDefaultsDeepFromArray(array, defaultArray) -> Array
+ * arrayDefaultsDeepFromArray(
+ *   data Array<Array|Object|any>,
+ *   defaults Array<Array|Object|any>
+ * ) -> Object
  * ```
  */
-const arrayDefaultsDeepFromArray = function (array, defaultArray) {
-  const defaultArrayLength = defaultArray.length,
-    result = array.slice()
+function arrayDefaultsDeepFromArray(data, defaults) {
+  const defaultArrayLength = defaults.length,
+    result = data.slice()
   let index = -1
   while (++index < defaultArrayLength) {
-    const item = array[index],
-      defaultItem = defaultArray[index]
-    if (isArray(item) && isArray(defaultItem)) {
-      result[index] = arrayDefaultsDeepFromArray(item, defaultItem)
-    } else if (item == null) {
-      result[index] = defaultItem
-    } else if (defaultItem == null) {
-      result[index] = item
-    } else if (item.constructor == Object && defaultItem.constructor == Object) {
-      result[index] = objectDefaultsDeepFromObject(item, defaultItem)
+    const element = data[index],
+      defaultElement = defaults[index]
+    if (isArray(element) && isArray(defaultElement)) {
+      result[index] = arrayDefaultsDeepFromArray(element, defaultElement)
+    } else if (element == null) {
+      result[index] = defaultElement
+    } else if (defaultElement == null) {
+      result[index] = element
+    } else if (element.constructor == Object && defaultElement.constructor == Object) {
+      result[index] = objectDefaultsDeepFromObject(element, defaultElement)
     } else {
-      result[index] = item
+      result[index] = element
     }
   }
   return result
@@ -38,62 +40,89 @@ const arrayDefaultsDeepFromArray = function (array, defaultArray) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var object Object<Array|Object|any>,
- *   defaultObject Object<Array|Object|any>
- *
- * objectDefaultsDeepFromObject(object, defaultObject) -> Object
+ * objectDefaultsDeepFromObject(
+ *   data Object<Array|Object|any>,
+ *   defaults Object<Array|Object|any>
+ * ) -> Object
  * ```
  */
-const objectDefaultsDeepFromObject = function (object, defaultObject) {
-  const result = { ...object }
-  for (const key in defaultObject) {
-    const item = object[key],
-      defaultItem = defaultObject[key]
-    if (isArray(item) && isArray(defaultItem)) {
-      result[key] = arrayDefaultsDeepFromArray(item, defaultItem)
-    } else if (item == null) {
-      result[key] = defaultItem
-    } else if (defaultItem == null) {
-      result[key] = item
-    } else if (item.constructor == Object && defaultItem.constructor == Object) {
-      result[key] = objectDefaultsDeepFromObject(item, defaultItem)
+function objectDefaultsDeepFromObject(data, defaults) {
+  const result = { ...data }
+  for (const key in defaults) {
+    const element = data[key],
+      defaultElement = defaults[key]
+    if (isArray(element) && isArray(defaultElement)) {
+      result[key] = arrayDefaultsDeepFromArray(element, defaultElement)
+    } else if (element == null) {
+      result[key] = defaultElement
+    } else if (defaultElement == null) {
+      result[key] = element
+    } else if (element.constructor == Object && defaultElement.constructor == Object) {
+      result[key] = objectDefaultsDeepFromObject(element, defaultElement)
     } else {
-      result[key] = item
+      result[key] = element
     }
   }
   return result
 }
 
+/**
+ * @name _defaultsDeep
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * _defaultsDeep(
+ *   data Object<Array|Object|any>,
+ *   defaults (Object|Array)<Array|Object|any>
+ * ) -> result Object
+ * ```
+ */
+function _defaultsDeep(data, defaults) {
+  if (isArray(data) && isArray(defaults)) {
+    return arrayDefaultsDeepFromArray(data, defaults)
+  }
+  if (data == null || defaults == null) {
+    return data
+  }
+  if (data.constructor == Object && defaults.constructor == Object) {
+    return objectDefaultsDeepFromObject(data, defaults)
+  }
+  return data
+}
+
 /**
  * @name defaultsDeep
  *
  * @synopsis
  * ```coffeescript [specscript]
- * var defaultCollection Array|Object,
- *   value Array|Object
+ * data (Object|Array)<Array|Object|any>
+ * defaults (Object|Array)<Array|Object|any>
  *
- * defaultsDeep(defaultCollection)(value) -> Array|Object
+ * defaultsDeep(data, defaults) -> result Object
+ * defaultsDeep(defaults)(data) -> result Object
  * ```
  *
  * @description
- * Deeply assign default values to an array or object by an array or object of possibly nested default values.
+ * Deeply assign default values to an object or array `data` using an array or object of default values `defaults`. The keys or indices of each element of `defaults` are used to extend `data` where there is no existing value. Both `data` and `defaults` may have nested arrays or objects.
  *
  * ```javascript [playground]
  * import defaultsDeep from 'https://unpkg.com/rubico/dist/x/defaultsDeep.es.js'
  *
- * const defaultUser = defaultsDeep({
+ * const user = {
+ *   name: 'John',
+ *   images: [{ url: 'https://placehold.co/600x400' }],
+ * }
+ *
+ * const userWithDefaults = defaultsDeep(user, {
  *   name: 'placeholder',
  *   images: [
- *     { url: 'https://via.placeholder.com/150' },
- *     { url: 'https://via.placeholder.com/150' },
- *     { url: 'https://via.placeholder.com/150' },
+ *     { url: 'https://placehold.co/150' },
+ *     { url: 'https://placehold.co/150' },
+ *     { url: 'https://placehold.co/150' },
  *   ],
  * })
  *
- * console.log(defaultUser({
- *   name: 'John',
- *   images: [{ url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' }],
- * }))
+ * console.log(userWithDefaults)
  * // {
  * //   name: 'John',
  * //   images: [
@@ -104,22 +133,30 @@ const objectDefaultsDeepFromObject = function (object, defaultObject) {
  * // }
  * ```
  *
+ * The `defaults` array or object may be provided to `defaultsDeep` without `data` to create a lazy version of `defaultsDeep` that accepts `data` as a single argument. This "lazy" API can be used for function pipelines and function compositions.
+ *
+ * ```javascript [playground]
+ * pipe({ a: 1 }, [
+ *   defaultsDeep({ b: 2, c: 3, g: [1, 2, 3] }),
+ *   console.log, // { a: 1, b: 2, c: 3, g: [1, 2, 3] }
+ * ])
+ * ```
+ *
  * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [compose](/docs/compose)
  *  * [callProp](/docs/callProp)
  *  * [differenceWith](/docs/differenceWith)
  *
  */
-const defaultsDeep = defaultCollection => function defaulting(value) {
-  if (isArray(value) && isArray(defaultCollection)) {
-    return arrayDefaultsDeepFromArray(value, defaultCollection)
-  }
-  if (value == null || defaultCollection == null) {
-    return value
+function defaultsDeep(...args) {
+  if (args.length == 1) {
+    return curry2(_defaultsDeep, __, args[0])
   }
-  if (value.constructor == Object && defaultCollection.constructor == Object) {
-    return objectDefaultsDeepFromObject(value, defaultCollection)
+  if (args.length == 2) {
+    return _defaultsDeep(...args)
   }
-  return value
+  throw new TypeError('Invalid number of arguments')
 }
 
 module.exports = defaultsDeep

package/x/defaultsDeep.test.js

@@ -2,6 +2,29 @@ const assert = require('assert')
 const defaultsDeep = require('./defaultsDeep')
 
 describe('defaultsDeep', () => {
+  it('eager API', async () => {
+    assert.deepEqual(
+      defaultsDeep([3], [1, 2, 3]),
+      [3, 2, 3],
+    )
+    assert.deepEqual(
+      defaultsDeep([[]], [[1], 2, 3]),
+      [[1], 2, 3],
+    )
+  })
+
+  it('Invalid number of arguments', async () => {
+    assert.throws(
+      () => defaultsDeep(),
+      new TypeError('Invalid number of arguments'),
+    )
+
+    assert.throws(
+      () => defaultsDeep(1, 2, 3),
+      new TypeError('Invalid number of arguments'),
+    )
+  })
+
   it('default array', async () => {
     assert.deepEqual(
       defaultsDeep([1, 2, 3])([3]),
@@ -97,7 +120,7 @@ describe('defaultsDeep', () => {
       { obj: { a: '1' } },
     )
   })
-  it('nullish default item should use current item', async () => {
+  it('nullish default element should use current element', async () => {
     assert.deepEqual(
       defaultsDeep([null, 1, 2, 3, 4])([0, 1, 2]),
       [0, 1, 2, 3, 4],

package/x/differenceWith.js

@@ -32,13 +32,13 @@ const differenceWithArrayAsync = async function (
 ) {
   const allValuesLength = allValues.length
   while (++index < allValuesLength) {
-    const item = allValues[index]
-    let doesItemExistByComparator = arraySome(array, curry2(comparator, item, __))
-    if (isPromise(doesItemExistByComparator)) {
-      doesItemExistByComparator = await doesItemExistByComparator
+    const element = allValues[index]
+    let doesElementExistByComparator = arraySome(array, curry2(comparator, element, __))
+    if (isPromise(doesElementExistByComparator)) {
+      doesElementExistByComparator = await doesElementExistByComparator
     }
-    if (!doesItemExistByComparator) {
-      result.push(item)
+    if (!doesElementExistByComparator) {
+      result.push(element)
     }
   }
   return result
@@ -61,14 +61,14 @@ const differenceWithArray = function (comparator, allValues, array) {
     result = []
   let index = -1
   while (++index < allValuesLength) {
-    const item = allValues[index],
-      doesItemExistByComparator = arraySome(array, curry2(comparator, item, __))
-    if (isPromise(doesItemExistByComparator)) {
-      return doesItemExistByComparator.then(funcConcatSync(
-        curry3(thunkConditional, __, noop, thunkify2(arrayPush, result, item)),
+    const element = allValues[index],
+      doesElementExistByComparator = arraySome(array, curry2(comparator, element, __))
+    if (isPromise(doesElementExistByComparator)) {
+      return doesElementExistByComparator.then(funcConcatSync(
+        curry3(thunkConditional, __, noop, thunkify2(arrayPush, result, element)),
         thunkify5(differenceWithArrayAsync, comparator, allValues, array, result, index)))
-    } else if (!doesItemExistByComparator) {
-      result.push(item)
+    } else if (!doesElementExistByComparator) {
+      result.push(element)
     }
   }
   return result

package/x/find.d.ts

@@ -15,7 +15,7 @@ export = find;
  * ```
  *
  * @description
- * Get the first item in a foldable collection that matches a predicate.
+ * Get the first element in a foldable collection that matches a predicate.
  *
  * ```javascript [playground]
  * import find from 'https://unpkg.com/rubico/dist/x/find.es.js'

package/x/find.js

@@ -22,7 +22,7 @@ const asyncIteratorFind = require('../_internal/asyncIteratorFind')
  * ```
  *
  * @description
- * Get the first item in a foldable collection that matches a predicate.
+ * Get the first element in a foldable collection that matches a predicate.
  *
  * ```javascript [playground]
  * import find from 'https://unpkg.com/rubico/dist/x/find.es.js'

package/x/find.test.js

@@ -2,7 +2,7 @@ const assert = require('assert')
 const find = require('./find')
 
 describe('find', () => {
-  it('gets the first item that passes test', async () => {
+  it('gets the first element that passes test', async () => {
     assert.strictEqual(
       find(x => x > 2)([1, 2, 3]),
       3,
@@ -33,7 +33,7 @@ describe('find', () => {
     )
   })
 
-  it('returns undefined for no items passing', async () => {
+  it('returns undefined for no elements passing', async () => {
     assert.strictEqual(
       find(x => x > 3)([1, 2, 3]),
       undefined,

package/x/findIndex.test.js

@@ -2,7 +2,7 @@ const assert = require('assert')
 const findIndex = require('./findIndex')
 
 describe('findIndex', function () {
-  it('finds the index in an array of the first item matching a predicate function', async function () {
+  it('finds the index in an array of the first element matching a predicate function', async function () {
     const startsWithAAA = string => string.startsWith('AAA')
     {
       const foundIndex = findIndex(startsWithAAA)([

package/x/first.d.ts

@@ -10,7 +10,7 @@ export = first;
  * ```
  *
  * @description
- * Get the first item of a collection
+ * Get the first element of a collection
  *
  * ```javascript [playground]
  * import first from 'https://unpkg.com/rubico/dist/x/first.es.js'

package/x/first.js

@@ -9,7 +9,7 @@
  * ```
  *
  * @description
- * Get the first item of a collection
+ * Get the first element of a collection
  *
  * ```javascript [playground]
  * import first from 'https://unpkg.com/rubico/dist/x/first.es.js'

package/x/first.test.js

@@ -2,7 +2,7 @@ const assert = require('assert')
 const first = require('./first')
 
 describe('first', () => {
-  it('gets the first item of an array', async () => {
+  it('gets the first element of an array', async () => {
     assert.strictEqual(first([1, 2, 3]), 1)
     assert.strictEqual(first([]), undefined)
   })

package/x/groupBy.d.ts

@@ -35,7 +35,7 @@ export = groupBy;
  * // }
  * ```
  *
- * Additionally, pass a resolver in property position to resolve a value for group membership for each item.
+ * Additionally, pass a resolver in property position to resolve a value for group membership for each element.
  *
  * ```javascript [playground]
  * import groupBy from 'https://unpkg.com/rubico/dist/x/groupBy.es.js'

package/x/groupBy.js

@@ -4,33 +4,33 @@ const reduce = require('../reduce')
 const __ = require('../_internal/placeholder')
 const curry3 = require('../_internal/curry3')
 
-// (mapOfArrays Map<any=>Array>, key any, item any) => mapOfArrays
+// (mapOfArrays Map<any=>Array>, key any, element any) => mapOfArrays
 // TODO: benchmark vs mapOfArrays.has(key)
-const group = function (mapOfArrays, key, item) {
+const group = function (mapOfArrays, key, element) {
   const array = mapOfArrays.get(key)
   if (array == null) {
-    mapOfArrays.set(key, [item])
+    mapOfArrays.set(key, [element])
   } else {
-    array.push(item)
+    array.push(element)
   }
   return mapOfArrays
 }
 
-// property string => (mapOfArrays Map<any=>Array>, item any) => mapOfArrays
+// property string => (mapOfArrays Map<any=>Array>, element any) => mapOfArrays
 const groupByProperty = property => function groupByPropertyReducer(
-  mapOfArrays, item,
+  mapOfArrays, element,
 ) {
-  return group(mapOfArrays, item[property], item)
+  return group(mapOfArrays, element[property], element)
 }
 
-// resolver any=>any => (mapOfArrays Map<any=>Array>, item any) => mapOfArrays
+// resolver any=>any => (mapOfArrays Map<any=>Array>, element any) => mapOfArrays
 const groupByResolver = resolver => function groupByResolverReducer(
-  mapOfArrays, item,
+  mapOfArrays, element,
 ) {
-  const key = resolver(item)
+  const key = resolver(element)
   return isPromise(key)
-    ? key.then(curry3(group, mapOfArrays, __, item))
-    : group(mapOfArrays, key, item)
+    ? key.then(curry3(group, mapOfArrays, __, element))
+    : group(mapOfArrays, key, element)
 }
 
 
@@ -70,7 +70,7 @@ const groupByResolver = resolver => function groupByResolverReducer(
  * // }
  * ```
  *
- * Additionally, pass a resolver in property position to resolve a value for group membership for each item.
+ * Additionally, pass a resolver in property position to resolve a value for group membership for each element.
  *
  * ```javascript [playground]
  * import groupBy from 'https://unpkg.com/rubico/dist/x/groupBy.es.js'

package/x/last.d.ts

@@ -10,7 +10,7 @@ export = last;
  * ```
  *
  * @description
- * Get the last item of a collection
+ * Get the last element of a collection
  *
  * ```javascript [playground]
  * import last from 'https://unpkg.com/rubico/dist/x/last.es.js'

package/x/last.js

@@ -9,7 +9,7 @@
  * ```
  *
  * @description
- * Get the last item of a collection
+ * Get the last element of a collection
  *
  * ```javascript [playground]
  * import last from 'https://unpkg.com/rubico/dist/x/last.es.js'

package/x/last.test.js

@@ -2,7 +2,7 @@ const assert = require('assert')
 const last = require('./last')
 
 describe('last', () => {
-  it('gets the last item of an array', async () => {
+  it('gets the last element of an array', async () => {
     assert.strictEqual(last([1, 2, 3]), 3)
     assert.strictEqual(last([]), undefined)
   })

package/x/maxBy.d.ts

@@ -4,22 +4,22 @@ export = maxBy;
  *
  * @synopsis
  * ```coffeescript [specscript]
- * maxBy(array Array, path string) -> maxItemByPath any
+ * maxBy(array Array, path string) -> maxElementByPath any
  *
- * maxBy(path string)(array Array) -> maxItemByPath any
+ * maxBy(path string)(array Array) -> maxElementByPath any
  * ```
  *
  * @description
- * Finds the item that is the max by a property denoted by path.
+ * Finds the element that is the max by a property denoted by path.
  *
  * ```javascript [playground]
  * import maxBy from 'https://unpkg.com/rubico/dist/x/maxBy.es.js'
  *
  * const array = [{ a: 1 }, { a: 2 }, { a: 3 }]
  *
- * const maxItem = maxBy(array, 'a')
+ * const maxElement = maxBy(array, 'a')
  *
- * console.log(maxItem) // { a: 3 }
+ * console.log(maxElement) // { a: 3 }
  * ```
  *
  * `maxBy` composes in a lazy way.
@@ -29,13 +29,13 @@ export = maxBy;
  *
  * const numbers = [1, 2, 3]
  *
- * const maxItem = pipe(numbers, [
+ * const maxElement = pipe(numbers, [
  *   map(number => number ** 2),
  *   map(number => ({ a: { b: { c: number } } })),
  *   maxBy('a.b.c')
  * ])
  *
- * console.log(maxItem) // { a: { b: { c: 9 } } }
+ * console.log(maxElement) // { a: { b: { c: 9 } } }
  * ```
  */
 declare function maxBy(...args: any[]): any;

package/x/maxBy.js

@@ -7,21 +7,21 @@ const curry2 = require('../_internal/curry2')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * _maxBy(array Array, path string) -> maxItemByPath any
+ * _maxBy(array Array, path string) -> maxElementByPath any
  * ```
  */
 const _maxBy = function (array, path) {
   const length = array.length
   const getter = get(path)
   let index = 0
-  let maxItem = array[index]
+  let maxElement = array[index]
   while (++index < length) {
-    const item = array[index]
-    if (getter(item) > getter(maxItem)) {
-      maxItem = item
+    const element = array[index]
+    if (getter(element) > getter(maxElement)) {
+      maxElement = element
     }
   }
-  return maxItem
+  return maxElement
 }
 
 /**
@@ -29,22 +29,22 @@ const _maxBy = function (array, path) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * maxBy(array Array, path string) -> maxItemByPath any
+ * maxBy(array Array, path string) -> maxElementByPath any
  *
- * maxBy(path string)(array Array) -> maxItemByPath any
+ * maxBy(path string)(array Array) -> maxElementByPath any
  * ```
  *
  * @description
- * Finds the item that is the max by a property denoted by path.
+ * Finds the element that is the max by a property denoted by path.
  *
  * ```javascript [playground]
  * import maxBy from 'https://unpkg.com/rubico/dist/x/maxBy.es.js'
  *
  * const array = [{ a: 1 }, { a: 2 }, { a: 3 }]
  *
- * const maxItem = maxBy(array, 'a')
+ * const maxElement = maxBy(array, 'a')
  *
- * console.log(maxItem) // { a: 3 }
+ * console.log(maxElement) // { a: 3 }
  * ```
  *
  * `maxBy` composes in a lazy way.
@@ -54,13 +54,13 @@ const _maxBy = function (array, path) {
  *
  * const numbers = [1, 2, 3]
  *
- * const maxItem = pipe(numbers, [
+ * const maxElement = pipe(numbers, [
  *   map(number => number ** 2),
  *   map(number => ({ a: { b: { c: number } } })),
  *   maxBy('a.b.c')
  * ])
  *
- * console.log(maxItem) // { a: { b: { c: 9 } } }
+ * console.log(maxElement) // { a: { b: { c: 9 } } }
  * ```
  */
 const maxBy = function (...args) {

package/x/maxBy.test.js

@@ -4,20 +4,20 @@ const pipe = require('../pipe')
 const map = require('../map')
 
 describe('maxBy', () => {
-  it('Finds the item that is the max by a property denoted by path', async () => {
+  it('Finds the element that is the max by a property denoted by path', async () => {
     const array = [{ a: 1 }, { a: 2 }, { a: 3 }]
-    const maxItem = maxBy(array, 'a')
-    assert.deepEqual(maxItem, { a: 3 })
+    const maxElement = maxBy(array, 'a')
+    assert.deepEqual(maxElement, { a: 3 })
   })
 
   it('composes in a lazy way', async () => {
     const numbers = [1, 2, 3]
-    const maxItem = pipe(numbers, [
+    const maxElement = pipe(numbers, [
       map(number => number ** 2),
       map(number => ({ a: { b: { c: number } } })),
       maxBy('a.b.c'),
     ])
-    assert.deepEqual(maxItem, { a: { b: { c: 9 } } })
+    assert.deepEqual(maxElement, { a: { b: { c: 9 } } })
   })
 
   it('returns undefined for empty array', async () => {

package/x/pluck.test.js

@@ -4,7 +4,7 @@ const pluck = require('./pluck')
 const createAbc = v => ({ a: { b: { c: v } } })
 
 describe('pluck', () => {
-  it('creates a new collection by getting a path from every item of an old collection', async () => {
+  it('creates a new collection by getting a path from every element of an old collection', async () => {
     const nested = [1, 2, 3].map(createAbc)
     assert.deepEqual(
       pluck('a.b.c')(nested),

package/x/prepend.d.ts

@@ -5,7 +5,7 @@ export = prepend;
  * @synopsis
  * ```coffeescript [specscript]
  * prepend(
- *   item string|Array,
+ *   element string|Array,
  * )(value string|Array) -> string|array
  * ```
  *
@@ -35,4 +35,4 @@ export = prepend;
  *
  * @since 1.7.3
  */
-declare function prepend(item: any): (value: any) => string | any[];
+declare function prepend(element: any): (value: any) => string | any[];