✨ Add lodash collection functions (#80)

* ✨ Add collection.filter
* ✨ Add collection.orderBy
* ✨ Add collection.reject
* ✨ Add collection.shuffle
* ✨ Add collection.sortBy

src/collection/filter.js

@@ -0,0 +1,17 @@
+import _filter from 'lodash/filter'
+import { convert } from 'util/convert'
+
+/**
+ * Replaces by an array of elements <code>predicate</code> returns truthy for.
+ * @function
+ * @memberof collection
+ * @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.
+ * @see {@link https://lodash.com/docs#filter|lodash.filter} for more information.
+ * @example filter({ nested: { prop: [1, 2, 3, 4] } }, 'nested.prop', v => v % 2) // => { nested: { prop: [1, 3] } }
+ * @since 0.3.0
+ */
+const filter = convert(_filter)
+export { filter, filter as default }

src/collection/filter.spec.js

@@ -0,0 +1,19 @@
+/* eslint-env jest */
+import { filter } from './filter'
+import { immutaTest } from 'test.utils'
+
+describe('Filter', () => {
+  it('should filter an array', () => {
+    immutaTest((input, path) => {
+      const output = filter(input, path, v => v % 2)
+      expect(output).toEqual({
+        nested: { prop: [1, 3] },
+        other: {},
+      })
+      return output
+    }, {
+      nested: { prop: [1, 2, 3, 4] },
+      other: {},
+    }, 'nested.prop')
+  })
+})

src/collection/index.js

@@ -1,9 +1,20 @@
+import { filter } from './filter'
 import { map } from './map'
+import { orderBy } from './orderBy'
+import { reject } from './reject'
+import { shuffle } from './shuffle'
+import { sortBy } from './sortBy'
 
 /**
  * Collection functions.
  * @namespace collection
+ * @since 0.1.8
  */
 export {
+  filter,
   map,
+  orderBy,
+  reject,
+  shuffle,
+  sortBy,
 }

src/collection/map.js

@@ -11,8 +11,7 @@ import { convert } from 'util/convert'
  * @param {function} [iteratee={@link https://lodash.com/docs#identity|lodash.identity}] The function invoked per iteration.
  * @return {Object} Returns the updated object.
  * @see {@link https://lodash.com/docs#map|lodash.map} for more information.
- * @see {@link https://lodash.com/docs#identity|lodash.identity} for more information.
- * @see {@link object.update|update} for more information.
+ * @example map({ nested: { prop: [1, 2, 3] } }, 'nested.prop', v => v * 2) // => { nested: { prop: [2, 4, 6] } }
  * @since 0.1.8
  */
 const map = convert(_map)

src/collection/orderBy.js

@@ -0,0 +1,20 @@
+import _orderBy from 'lodash/orderBy'
+import { convert } from 'util/convert'
+
+/**
+ * Replaces by an array of sorted by <code>iteratees</code> in specified <code>orders</code>.
+ * @function
+ * @memberof collection
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {Array[]|Function[]|Object[]|string[]} [iteratees=[{@link https://lodash.com/docs#identity|lodash.identity}]] The iteratees to sort by.
+ * @param {string[]} [orders] The sort orders of <code>iteratees</code>.
+ * @return {Object} Returns the updated object.
+ * @see {@link https://lodash.com/docs#orderBy|lodash.orderBy} for more information.
+ * @example
+ * orderBy({ nested: { prop: [{ name: 'Yvo', age: 2 }, { name: 'Nico', age: 666 }, { name: 'Nico', age: 30 }] } }, 'nested.prop', ['name', 'age'], ['asc', 'desc'])
+ * // => { nested: { prop: [{ name: 'Nico', age: 666 }, { name: 'Nico', age: 30 }, { name: 'Yvo', age: 2 }] } }
+ * @since 0.3.0
+ */
+const orderBy = convert(_orderBy)
+export { orderBy, orderBy as default }

src/collection/orderBy.spec.js

@@ -0,0 +1,41 @@
+/* eslint-env jest */
+import { immutaTest } from 'test.utils'
+import { orderBy } from './orderBy'
+
+describe('OrderBy', () => {
+  it('should sort array by name asc and age desc', () => {
+    immutaTest((input, path) => {
+      const output = orderBy(input, path, ['name', 'age'], ['asc', 'desc'])
+      expect(output).toEqual({
+        nested: {
+          prop: [{
+            name: 'Nico',
+            age: 666,
+          }, {
+            name: 'Nico',
+            age: 30,
+          }, {
+            name: 'Yvo',
+            age: 2,
+          }],
+        },
+        other: {},
+      })
+      return output
+    }, {
+      nested: {
+        prop: [{
+          name: 'Yvo',
+          age: 2,
+        }, {
+          name: 'Nico',
+          age: 666,
+        }, {
+          name: 'Nico',
+          age: 30,
+        }],
+      },
+      other: {},
+    }, 'nested.prop')
+  })
+})

src/collection/reject.js

@@ -0,0 +1,17 @@
+import _reject from 'lodash/reject'
+import { convert } from 'util/convert'
+
+/**
+ * Replaces by an array of elements <code>predicate</code> returns falsy for.
+ * @function
+ * @memberof collection
+ * @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.
+ * @see {@link https://lodash.com/docs#reject|lodash.reject} for more information.
+ * @example reject({ nested: { prop: [1, 2, 3, 4] } }, 'nested.prop', v => v % 2) // => { nested: { prop: [2, 4] } }
+ * @since 0.3.0
+ */
+const reject = convert(_reject)
+export { reject, reject as default }

src/collection/reject.spec.js

@@ -0,0 +1,19 @@
+/* eslint-env jest */
+import { immutaTest } from 'test.utils'
+import { reject } from './reject'
+
+describe('Reject', () => {
+  it('should reject elements of an array', () => {
+    immutaTest((input, path) => {
+      const output = reject(input, path, v => v % 2)
+      expect(output).toEqual({
+        nested: { prop: [2, 4] },
+        other: {},
+      })
+      return output
+    }, {
+      nested: { prop: [1, 2, 3, 4] },
+      other: {},
+    }, 'nested.prop')
+  })
+})

src/collection/shuffle.js

@@ -0,0 +1,16 @@
+import _shuffle from 'lodash/shuffle'
+import { convert } from 'util/convert'
+
+/**
+ * Replaces by an array of shuffled elements.
+ * @function
+ * @memberof collection
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @return {Object} Returns the updated object.
+ * @see {@link https://lodash.com/docs#shuffle|lodash.shuffle} for more information.
+ * @example shuffle({ nested: { prop: [1, 2, 3, 4, 5, 6, 7, 8, 9] } }, 'nested.prop') // => { nested: { prop: [7, 3, 9, 1, 4, 5, 6, 8, 2] } }
+ * @since 0.3.0
+ */
+const shuffle = convert(_shuffle)
+export { shuffle, shuffle as default }

src/collection/shuffle.spec.js

@@ -0,0 +1,17 @@
+/* eslint-env jest */
+import { immutaTest } from 'test.utils'
+import { shuffle } from './shuffle'
+
+describe('Shuffle', () => {
+  it('should shuffle an array', () => {
+    immutaTest((input, path) => {
+      const output = shuffle(input, path)
+      expect(output.nested.prop).toEqual(expect.arrayContaining([1, 2, 3, 4, 5, 6, 7, 8, 9]))
+      expect(output.nested.prop).not.toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9])
+      return output
+    }, {
+      nested: { prop: [1, 2, 3, 4, 5, 6, 7, 8, 9] },
+      other: {},
+    }, 'nested.prop')
+  })
+})

src/collection/sortBy.js

@@ -0,0 +1,19 @@
+import _sortBy from 'lodash/sortBy'
+import { convert } from 'util/convert'
+
+/**
+ * Replaces by an array of sorted by <code>iteratees</code>.
+ * @function
+ * @memberof collection
+ * @param {Object} object The object to modify.
+ * @param {Array|string} path The path of the property to set.
+ * @param {Array[]|Function[]|Object[]|string[]} [iteratees=[{@link https://lodash.com/docs#identity|lodash.identity}]] The iteratees to sort by.
+ * @return {Object} Returns the updated object.
+ * @see {@link https://lodash.com/docs#sortBy|lodash.sortBy} for more information.
+ * @example
+ * sortBy({ nested: { prop: [{ name: 'Yvo', age: 2 }, { name: 'Nico', age: 666 }, { name: 'Nico', age: 30 }] } }, 'nested.prop', ['name', 'age'])
+ * // => { nested: { prop: [{ name: 'Nico', age: 30 }, { name: 'Nico', age: 666 }, { name: 'Yvo', age: 2 }] } }
+ * @since 0.3.0
+ */
+const sortBy = convert(_sortBy)
+export { sortBy, sortBy as default }

src/collection/sortBy.spec.js

@@ -0,0 +1,41 @@
+/* eslint-env jest */
+import { immutaTest } from 'test.utils'
+import { sortBy } from './sortBy'
+
+describe('SortBy', () => {
+  it('should sort array by name and age', () => {
+    immutaTest((input, path) => {
+      const output = sortBy(input, path, ['name', 'age'])
+      expect(output).toEqual({
+        nested: {
+          prop: [{
+            name: 'Nico',
+            age: 30,
+          }, {
+            name: 'Nico',
+            age: 666,
+          }, {
+            name: 'Yvo',
+            age: 2,
+          }],
+        },
+        other: {},
+      })
+      return output
+    }, {
+      nested: {
+        prop: [{
+          name: 'Yvo',
+          age: 2,
+        }, {
+          name: 'Nico',
+          age: 666,
+        }, {
+          name: 'Nico',
+          age: 30,
+        }],
+      },
+      other: {},
+    }, 'nested.prop')
+  })
+})