feat: added push() and pushAll() operations

src/operations/common.js

@@ -1,7 +1,8 @@
 module.exports = {
     update,
     isNumber,
-    extractSubPath
+    extractSubPath,
+    updateArray
 };
 
 function update(object, path, map, shouldCreateIntermediate) {
@@ -69,3 +70,9 @@ function extractSubPath(path) {
         path[path.length - 1]
     ];
 }
+
+function updateArray(object, path, map) {
+    return update(object, path, item => (Array.isArray(item)
+        ? map(item)
+        : item));
+}

src/operations/index.js

@@ -1,5 +1,7 @@
 const update = require('./update');
 const set = require('./set');
 const remove = require('./remove');
+const push = require('./push');
+const pushAll = require('./pushAll');
 
-module.exports = { update, set, remove };
+module.exports = { update, set, remove, push, pushAll };

src/operations/push/index.js

@@ -0,0 +1,41 @@
+const pushAll = require('../pushAll');
+
+module.exports = push;
+
+/**
+ * Adds an element to the end of array-item selected by path
+ * @param {Object | any[]} object object to update
+ * @param {string | string[]} path path to be updated
+ * @param {*} value value to be added
+ * @returns {Object | any[]} updated object
+ * @description one of additional functions to work with array items
+ * @docs
+ * ```js
+ * import { push } from 'immutable-object-update';
+ *
+ * const state = {
+ *     a: {
+ *         b: [ 1 ]
+ *     }
+ * };
+ *
+ * const updated = push(state, [ 'a', 'b' ], 2);
+ *
+ * // or
+ *
+ * const updated = push(state, 'a.b', 2);
+ * ```
+ *
+ * As a result we will receive new object with structure below:
+ *
+ * ```js
+ * {
+ *     a: {
+ *         b: [ 1, 2 ]
+ *     }
+ * }
+ * ```
+ */
+function push(object, path, value) {
+    return pushAll(object, path, [ value ]);
+}

src/operations/pushAll/index.js

@@ -0,0 +1,45 @@
+const { updateArray } = require('../common');
+
+module.exports = pushAll;
+
+/**
+ * Adds number of elements to the end of array-item selected by path
+ * @param {Object | any[]} object object to update
+ * @param {string | string[]} path path to be updated
+ * @param {any[]} values values to be added
+ * @returns {Object | any[]} updated object
+ * @description one of additional functions to work with array items
+ * @docs
+ * ```js
+ * import { pushAll } from 'immutable-object-update';
+ *
+ * const state = {
+ *     a: {
+ *         b: [ 1 ]
+ *     }
+ * };
+ *
+ * const updated = pushAll(state, [ 'a', 'b' ], [ 2, 3, 4 ]);
+ *
+ * // or
+ *
+ * const updated = pushAll(state, 'a.b', [ 2, 3, 4 ]);
+ * ```
+ *
+ * As a result we will receive new object with structure below:
+ *
+ * ```js
+ * {
+ *     a: {
+ *         b: [ 1, 2, 3, 4 ]
+ *     }
+ * }
+ * ```
+ */
+function pushAll(object, path, values) {
+    return updateArray(
+        object,
+        path,
+        array => array.concat(values)
+    );
+}