✨ Add lodash array functions (#50)

* ✨ Add array.concat
* ✨ Add array.difference
* ✨ Add array.drop
* ✨ Add array.pull
* ✨ Add array.remove

src/array/concat.js

@@ -0,0 +1,17 @@
+import _concat from 'lodash/concat'
+import convert from '../util/convert'
+
+/**
+ * Replaces an array concatenating the former array with additional arrays and/or values.
+ * @function
+ * @memberof array
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {...Array} arrays The arrays to concatenate.
+ * @return {Object} Returns the updated object.
+ * @example concat({ nested: { prop: [1, 2] } }, 'nested.prop', [3, 4]) // => { nested: { prop: [1, 2, 3, 4] } }
+ * @see {@link https://lodash.com/docs#concat|lodash.concat} for more information.
+ * @since 0.2.0
+ */
+const concat = convert(_concat)
+export default concat

src/array/concat.spec.js

@@ -0,0 +1,22 @@
+/* eslint-env jest */
+import concat from './concat'
+
+describe('Concat', () => {
+
+  it('should concat an array', () => {
+    const original = { nested: { prop: [1, 2] } }
+
+    const final = concat(original, 'nested.prop', [3, 4])
+
+    expect(final).toEqual({ nested: { prop: [1, 2, 3, 4] } })
+    expect(original).toEqual({ nested: { prop: [1, 2] } })
+  })
+
+  it('should add several arrays', () => {
+    expect(concat({ nested: { prop: [1, 2] } }, 'nested.prop', [3, 4], [5, 6])).toEqual({ nested: { prop: [1, 2, 3, 4, 5, 6] } })
+  })
+
+  it('should replace value with array', () => {
+    expect(concat({ nested: { prop: 1 } }, 'nested.prop', [2, 3])).toEqual({ nested: { prop: [1, 2, 3] } })
+  })
+})

src/array/difference.js

@@ -0,0 +1,17 @@
+import _difference from 'lodash/difference'
+import convert from '../util/convert'
+
+/**
+ * Replaces an array removing values in the other given arrays from the former array.
+ * @function
+ * @memberof array
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {...Array} arrays The arrays of values to exclude.
+ * @return {Object} Returns the updated object.
+ * @example difference({ nested: { prop: [1, 2] } }, 'nested.prop', [2, 3]) // => { nested: { prop: [1] } }
+ * @see {@link https://lodash.com/docs#difference|lodash.difference} for more information.
+ * @since 0.2.0
+ */
+const difference = convert(_difference)
+export default difference

src/array/difference.spec.js

@@ -0,0 +1,22 @@
+/* eslint-env jest */
+import difference from './difference'
+
+describe('Difference', () => {
+
+  it('should remove intersecting elements', () => {
+    const original = { nested: { prop: [1, 2, 3] } }
+
+    const final = difference(original, 'nested.prop', [3, 4])
+
+    expect(final).toEqual({ nested: { prop: [1, 2] } })
+    expect(original).toEqual({ nested: { prop: [1, 2, 3] } })
+  })
+
+  it('should remove intersecting elements from several arrays', () => {
+    expect(difference({ nested: { prop: [1, 2, 3, 4] } }, 'nested.prop', [1], [2])).toEqual({ nested: { prop: [3, 4] } })
+  })
+
+  it('should replace deep undefined with array', () => {
+    expect(difference(undefined, 'nested.prop', [1, 2])).toEqual({ nested: { prop: [] } })
+  })
+})

src/array/drop.js

@@ -0,0 +1,17 @@
+import _drop from 'lodash/drop'
+import convert from '../util/convert'
+
+/**
+ * Replaces an array dropping one or several elements at the start of the former array.
+ * @function
+ * @memberof array
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {number} [n=1] The number of elements to drop.
+ * @return {Object} Returns the updated object.
+ * @example drop({ nested: { prop: [1, 2, 3, 4] } }, 'nested.prop', 2) // => { nested: { prop: [3, 4] } }
+ * @see {@link https://lodash.com/docs#drop|lodash.drop} for more information.
+ * @since 0.2.0
+ */
+const drop = convert(_drop)
+export default drop

src/array/drop.spec.js

@@ -0,0 +1,22 @@
+/* eslint-env jest */
+import drop from './drop'
+
+describe('Drop', () => {
+
+  it('should drop an element at the start of the array', () => {
+    const original = { nested: { prop: [1, 2, 3] } }
+
+    const final = drop(original, 'nested.prop')
+
+    expect(final).toEqual({ nested: { prop: [2, 3] } })
+    expect(original).toEqual({ nested: { prop: [1, 2, 3] } })
+  })
+
+  it('should drop several elements at the start of the array', () => {
+    expect(drop({ nested: { prop: [1, 2, 3, 4] } }, 'nested.prop', 2)).toEqual({ nested: { prop: [3, 4] } })
+  })
+
+  it('should replace deep undefined with array', () => {
+    expect(drop(undefined, 'nested.prop')).toEqual({ nested: { prop: [] } })
+  })
+})

src/array/index.js

@@ -1,4 +1,9 @@
+import concat from './concat'
+import difference from './difference'
+import drop from './drop'
+import pull from './pull'
 import push from './push'
+import remove from './remove'
 import splice from './splice'
 import unshift from './unshift'
 import xor from './xor'
@@ -9,7 +14,12 @@ import xor from './xor'
  * @since 0.1.6
  */
 export {
+  concat,
+  difference,
+  drop,
+  pull,
   push,
+  remove,
   splice,
   unshift,
   xor,

src/array/pull.js

@@ -0,0 +1,17 @@
+import _pull from 'lodash/pull'
+import convert from '../util/convert'
+
+/**
+ * Replaces an array removing all given values from the former array.
+ * @function
+ * @memberof array
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {...*} values The values to remove.
+ * @return {Object} Returns the updated object.
+ * @example pull({ nested: { prop: [1, 2, 3, 1, 2, 3] } }, 'nested.prop', 1, 3) // => { nested: { prop: [2, 2] } }
+ * @see {@link https://lodash.com/docs#pull|lodash.pull} for more information.
+ * @since 0.2.0
+ */
+const pull = convert(_pull)
+export default pull

src/array/pull.spec.js

@@ -0,0 +1,18 @@
+/* eslint-env jest */
+import pull from './pull'
+
+describe('Pull', () => {
+
+  it('should remove matching elements', () => {
+    const original = { nested: { prop: [1, 2, 3, 1, 2, 3] } }
+
+    const final = pull(original, 'nested.prop', 2)
+
+    expect(final).toEqual({ nested: { prop: [1, 3, 1, 3] } })
+    expect(original).toEqual({ nested: { prop: [1, 2, 3, 1, 2, 3] } })
+  })
+
+  it('should remove several matching elements', () => {
+    expect(pull({ nested: { prop: [1, 2, 3, 1, 2, 3] } }, 'nested.prop', 1, 3)).toEqual({ nested: { prop: [2, 2] } })
+  })
+})

src/array/push.js

@@ -1,7 +1,7 @@
 import convertArrayMethod from './convertArrayMethod'
 
 /**
- * Add one or more elements to the end of an array.
+ * Replaces an array adding one or more elements to the end of the former array.
  * @function push
  * @memberof array
  * @param {Object} object The object to modify.

src/array/remove.js

@@ -0,0 +1,17 @@
+import _remove from 'lodash/fp/remove'
+import { convertLodashFp } from '../util/convert'
+
+/**
+ * Replaces an array removing elements that predicate returns truthy for from the former array.
+ * @function
+ * @memberof array
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {Function} [predicate={@link https://lodash.com/docs#identity|lodash.identity}] The function invoked per iteration.
+ * @return {Object} Returns the updated object.
+ * @example remove({ nested: { prop: [1, 2, 3, 4] } }, 'nested.prop', v => v > 2) // => { nested: { prop: [1, 2] } }
+ * @see {@link https://lodash.com/docs#remove|lodash.remove} for more information.
+ * @since 0.2.0
+ */
+const remove = convertLodashFp(_remove)
+export default remove

src/array/remove.spec.js

@@ -0,0 +1,18 @@
+/* eslint-env jest */
+import remove from './remove'
+
+describe('Drop', () => {
+
+  it('should remove an element', () => {
+    const original = { nested: { prop: [1, 2, 3] } }
+
+    const final = remove(original, 'nested.prop', v => v > 2)
+
+    expect(final).toEqual({ nested: { prop: [1, 2] } })
+    expect(original).toEqual({ nested: { prop: [1, 2, 3] } })
+  })
+
+  it('should replace deep undefined with array', () => {
+    expect(remove(undefined, 'nested.prop', () => true)).toEqual({ nested: { prop: [] } })
+  })
+})

src/array/splice.js

@@ -1,7 +1,7 @@
 import convertArrayMethod from './convertArrayMethod'
 
 /**
- * Changes the contents of an array by removing existing elements and/or adding new elements.
+ * Replaces an array removing and/or adding elements at <code>index</code> in the former array.
  * @function splice
  * @memberof array
  * @param {Object} object The object to modify.

src/array/unshift.js

@@ -1,7 +1,7 @@
 import convertArrayMethod from './convertArrayMethod'
 
 /**
- * Adds one or more elements at the start of an array.
+ * Replaces an array adding elements at the start of the former array.
  * @function unshift
  * @memberof array
  * @param {Object} object The object to modify.

src/array/xor.js

@@ -2,13 +2,13 @@ import convert from '../util/convert'
 import xor from 'lodash/xor'
 
 /**
- * Replaces by an array of unique values that is the symmetric difference of the former array and the given arrays.
+ * Replaces an array by the symmetric difference of the former array and the given arrays.
  * @function xor
  * @memberof array
  * @param {Object} object The object to modify.
  * @param {Array|string} path The path of the property to set.
  * @param {...Array} arrays The arrays to inspect.
- * @return {Array} Returns the new array of filtered values.
+ * @return {Object} Returns the updated object.
  * @example xor({ nested: { prop: [1, 2] } }, 'nested.prop', [2, 3]) // => { nested: { prop: [1, 3] } }
  * @see {@link https://lodash.com/docs#xor|lodash.xor} for more information.
  * @since 0.1.6