feat: added unshift() and unshiftAll() operations

src/operations/index.js

@@ -7,5 +7,19 @@ const pop = require('./pop');
 const popN = require('./popN');
 const shift = require('./shift');
 const shiftN = require('./shiftN');
+const unshift = require('./unshift');
+const unshiftAll = require('./unshiftAll');
 
-module.exports = { update, set, remove, push, pushAll, pop, popN, shift, shiftN };
+module.exports = {
+    update,
+    set,
+    remove,
+    push,
+    pushAll,
+    pop,
+    popN,
+    shift,
+    shiftN,
+    unshift,
+    unshiftAll
+};

src/operations/unshift/index.js

@@ -0,0 +1,41 @@
+const unshiftAll = require('../unshiftAll');
+
+module.exports = unshift;
+
+/**
+ * Adds an element to the beginning 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 { unshift } from 'immutable-object-update';
+ *
+ * const state = {
+ *     a: {
+ *         b: [ 1 ]
+ *     }
+ * };
+ *
+ * const updated = unshift(state, [ 'a', 'b' ], 0);
+ *
+ * // or
+ *
+ * const updated = unshift(state, 'a.b', 0);
+ * ```
+ *
+ * As a result we will receive new object with structure below:
+ *
+ * ```js
+ * {
+ *     a: {
+ *         b: [ 0, 1 ]
+ *     }
+ * }
+ * ```
+ */
+function unshift(object, path, value) {
+    return unshiftAll(object, path, [ value ]);
+}

src/operations/unshiftAll/index.js

@@ -0,0 +1,47 @@
+const { updateArray } = require('../common');
+
+module.exports = unshiftAll;
+
+/**
+ * Adds number of elements to the beginning 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 { unshiftAll } from 'immutable-object-update';
+ *
+ * const state = {
+ *     a: {
+ *         b: [ 1 ]
+ *     }
+ * };
+ *
+ * const updated = unshiftAll(state, [ 'a', 'b' ], [ 2, 3, 4 ]);
+ *
+ * // or
+ *
+ * const updated = unshiftAll(state, 'a.b', [ 2, 3, 4 ]);
+ * ```
+ *
+ * As a result we will receive new object with structure below:
+ *
+ * ```js
+ * {
+ *     a: {
+ *         b: [ 2, 3, 4, 1 ]
+ *     }
+ * }
+ * ```
+ *
+ * > Please note: items will be added all at once, so the original order will be saved
+ */
+function unshiftAll(object, path, values) {
+    return updateArray(
+        object,
+        path,
+        array => values.concat(array)
+    );
+}