v1.0.0

Author: georapbox

CHAGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## v1.0.0
+
+### Changes
+- Provide named exports for each API method. Now you can also import like this: `import {push} from 'immutable-arrays'`
+
+### Breaking Changes
+Change API methods' names to avoid redundancy. This was more of an issue when the library was used as a global in browser where someone would need to type `immutableArrays.immutablePush()`.  
+Below is a list with the renamed methods:
+- `immutablePush` renamed to `push`;
+- `immutablePop` renamed to `pop`;
+- `immutableShift` renamed to `shift`;
+- `immutableUnshift` renamed to `unshift`;
+- `immutableSplice` renamed to `splice`;
+- `immutableReverse` renamed to `reverse`;
+- `immutableSort` renamed to `sort`;
+- `immutableDelete` renamed to `del`;
+
 ## v0.4.3
 - Include test coverage in build process
 - Add test to cover scenario with all optional arguments being undefined for immutableSplice method

README.md

@@ -19,36 +19,67 @@ Immutable versions of normally mutable array methods
 $ npm install immutable-arrays
 ```
 
-## Test
+## Usage
+
+### Old school browser global
+```html
+<script src="immutable-arrays/lib/immutableArrays.min.js"></script>
+<script>
+  var res = immutableArrays.push([1, 2, 3, 4], 10);
+</script>
+```
 
-```sh
-$ npm test
+### Node.js
+```js
+var immutableArrays = require('immutable-arrays');
+var res = immutableArrays.push([1, 2, 3, 4], 10);
+```
+
+### ES6 imports
+
+#### Importing defaults
+
+```js
+import immutableArrays from 'immutable-arrays';
+const res = immutableArrays.push([1, 2, 3, 4], 10);
+```
+
+#### Importing a single method
+
+```js
+import {push} from 'immutable-arrays';
+const res = push([1, 2, 3, 4], 10);
+
+// or
+
+import {push as immutablePush} from 'immutable-arrays';
+const res = immutablePush([1, 2, 3, 4], 10);
 ```
 
-## Functions
+## API
 
 <dl>
-<dt><a href="#immutablePush">immutablePush(array, ...elementN)</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.push">immutableArrays.push(array, ...elementN)</a> ⇒ <code>Array</code></dt>
 <dd><p>Adds one or more elements to the end of an array by returning a new array instead of mutating the original one.</p></dd>
-<dt><a href="#immutablePop">immutablePop(array)</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.pop">immutableArrays.pop(array)</a> ⇒ <code>Array</code></dt>
 <dd><p>Removes the last element from an array by returning a new array instead of mutating the original one.</p></dd>
-<dt><a href="#immutableDelete">immutableDelete(array, index)</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.del">immutableArrays.del(array, index)</a> ⇒ <code>Array</code></dt>
 <dd><p>Deletes an element from an array by its index in the array.</p></dd>
-<dt><a href="#immutableShift">immutableShift(array)</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.shift">immutableArrays.shift(array)</a> ⇒ <code>Array</code></dt>
 <dd><p>Removes the first element from an array.</p></dd>
-<dt><a href="#immutableUnshift">immutableUnshift(array, ...elementN)</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.unshift">immutableArrays.unshift(array, ...elementN)</a> ⇒ <code>Array</code></dt>
 <dd><p>Adds one or more elements to the beginning of an array.</p></dd>
-<dt><a href="#immutableReverse">immutableReverse(array)</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.reverse">immutableArrays.reverse(array)</a> ⇒ <code>Array</code></dt>
 <dd><p>Reverses an array (not in place). The first array element becomes the last, and the last array element becomes the first.</p></dd>
-<dt><a href="#immutableSort">immutableSort(array, [compareFunction])</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.sort">immutableArrays.sort(array, [compareFunction])</a> ⇒ <code>Array</code></dt>
 <dd><p>Sorts the elements of an array (not in place) and returns a sorted array.</p></dd>
-<dt><a href="#immutableSplice">immutableSplice(array, [start], [deleteCount], [...elementN])</a> ⇒ <code>Array</code></dt>
+<dt><a href="#immutableArrays.splice">immutableArrays.splice(array, [start], [deleteCount], [...elementN])</a> ⇒ <code>Array</code></dt>
 <dd><p>Removes existing elements and/or adds new elements to an array.</p></dd>
 </dl>
 
-<a name="immutablePush"></a>
+<a name="immutableArrays.push"></a>
 
-## immutablePush(array, ...elementN) ⇒ <code>Array</code>
+## immutableArrays.push(array, ...elementN) ⇒ <code>Array</code>
 Adds one or more elements to the end of an array by returning
 a new array instead of mutating the original one.
 
@@ -62,14 +93,14 @@ a new array instead of mutating the original one.
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutablePush(originalArray, 'f', 'g');
+const resultArray = immutableArrays.push(originalArray, 'f', 'g');
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['a', 'b', 'c', 'd', 'e', 'f', 'g']
 ```
 
-<a name="immutablePop"></a>
+<a name="immutableArrays.pop"></a>
 
-## immutablePop(array) ⇒ <code>Array</code>
+## immutableArrays.pop(array) ⇒ <code>Array</code>
 Removes the last element from an array by returning
 a new array instead of mutating the original one.
 
@@ -82,14 +113,14 @@ a new array instead of mutating the original one.
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutablePop(originalArray);
+const resultArray = immutableArrays.pop(originalArray);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['a', 'b', 'c', 'd']
 ```
 
-<a name="immutableDelete"></a>
+<a name="immutableArrays.del"></a>
 
-## immutableDelete(array, index) ⇒ <code>Array</code>
+## immutableArrays.del(array, index) ⇒ <code>Array</code>
 Deletes an element from an array by its index in the array.
 
 **Returns**: <code>Array</code> - A new array with the element removed.  
@@ -102,14 +133,14 @@ Deletes an element from an array by its index in the array.
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableDelete(originalArray, 2);
+const resultArray = immutableArrays.del(originalArray, 2);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['a', 'b', 'd', 'e']
 ```
 
-<a name="immutableShift"></a>
+<a name="immutableArrays.shift"></a>
 
-## immutableShift(array) ⇒ <code>Array</code>
+## immutableArrays.shift(array) ⇒ <code>Array</code>
 Removes the first element from an array.
 
 **Returns**: <code>Array</code> - A new array with the first element removed.  
@@ -121,14 +152,14 @@ Removes the first element from an array.
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableShift(originalArray);
+const resultArray = immutableArrays.shift(originalArray);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['b', 'c', 'd', 'e']
 ```
 
-<a name="immutableUnshift"></a>
+<a name="immutableArrays.unshift"></a>
 
-## immutableUnshift(array, ...elementN) ⇒ <code>Array</code>
+## immutableArrays.unshift(array, ...elementN) ⇒ <code>Array</code>
 Adds one or more elements to the beginning of an array.
 
 **Returns**: <code>Array</code> - A new array with the new elements added to the front.  
@@ -141,14 +172,14 @@ Adds one or more elements to the beginning of an array.
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableUnshift(originalArray, 'f', 'g');
+const resultArray = immutableArrays.unshift(originalArray, 'f', 'g');
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['f', 'g', 'a', 'b', 'c', 'd', 'e']
 ```
 
-<a name="immutableReverse"></a>
+<a name="immutableArrays.reverse"></a>
 
-## immutableReverse(array) ⇒ <code>Array</code>
+## immutableArrays.reverse(array) ⇒ <code>Array</code>
 Reverses an array (not in place).
 The first array element becomes the last, and the last array element becomes the first.
 
@@ -161,14 +192,14 @@ The first array element becomes the last, and the last array element becomes the
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableReverse(originalArray);
+const resultArray = immutableArrays.reverse(originalArray);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['e', 'd', 'c', 'b', 'a']
 ```
 
-<a name="immutableSort"></a>
+<a name="immutableArrays.sort"></a>
 
-## immutableSort(array, [compareFunction]) ⇒ <code>Array</code>
+## immutableArrays.sort(array, [compareFunction]) ⇒ <code>Array</code>
 Sorts the elements of an array (not in place) and returns a sorted array.
 
 **Returns**: <code>Array</code> - A new sorted array.
@@ -183,26 +214,26 @@ Sorts the elements of an array (not in place) and returns a sorted array.
 const numberArray = [20, 3, 4, 10, -3, 1, 0, 5];
 const stringArray = ['Blue', 'Humpback', 'Beluga'];
 
-const resultArray = immutableSort(numberArray, (a, b) => a - b);
+const resultArray = immutableArrays.sort(numberArray, (a, b) => a - b);
 // -> numberArray [20, 3, 4, 10, -3, 1, 0, 5]
 // -> resultArray [-3, 0, 1, 3, 4, 5, 10, 20]
 
-const resultArray = immutableSort(numberArray, (a, b) => b - a);
+const resultArray = immutableArrays.sort(numberArray, (a, b) => b - a);
 // -> numberArray [20, 3, 4, 10, -3, 1, 0, 5]
 // -> resultArray [20, 10, 5, 4, 3, 1, 0, -3]
 
-const resultArray = immutableSort(stringArray);
+const resultArray = immutableArrays.sort(stringArray);
 // -> stringArray ['Blue', 'Humpback', 'Beluga']
 // -> resultArray ['Beluga', 'Blue', 'Humpback']
 
-const resultArray = immutableSort(stringArray, (a, b) => a.toLowerCase() < b.toLowerCase());
+const resultArray = immutableArrays.sort(stringArray, (a, b) => a.toLowerCase() < b.toLowerCase());
 // -> stringArray ['Blue', 'Humpback', 'Beluga']
 // -> resultArray ['Humpback', 'Blue', 'Beluga']
 ```
 
-<a name="immutableSplice"></a>
+<a name="immutableArrays.splice"></a>
 
-## immutableSplice(array, [start], [deleteCount], [...elementN]) ⇒ <code>Array</code>
+## immutableArrays.splice(array, [start], [deleteCount], [...elementN]) ⇒ <code>Array</code>
 Removes existing elements and/or adds new elements to an array.
 
 **Returns**: <code>Array</code> - The result array.  
@@ -217,51 +248,63 @@ Removes existing elements and/or adds new elements to an array.
 **Example**  
 ```js
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0);
+const resultArray = immutableArrays.splice(originalArray, 0);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray []
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0, 1);
+const resultArray = immutableArrays.splice(originalArray, 0, 1);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['b', 'c', 'd', 'e']
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0, 3);
+const resultArray = immutableArrays.splice(originalArray, 0, 3);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['d', 'e']
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0, originalArray.length);
+const resultArray = immutableArrays.splice(originalArray, 0, originalArray.length);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray []
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0, -3);
+const resultArray = immutableArrays.splice(originalArray, 0, -3);
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['a', 'b', 'c', 'd', 'e']
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0, 0, 'lorem', 'ipsum');
+const resultArray = immutableArrays.splice(originalArray, 0, 0, 'lorem', 'ipsum');
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['lorem', 'ipsum', 'a', 'b', 'c', 'd', 'e']
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, originalArray.length, 0, 'lorem', 'ipsum');
+const resultArray = immutableArrays.splice(originalArray, originalArray.length, 0, 'lorem', 'ipsum');
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['a', 'b', 'c', 'd', 'e', 'lorem', 'ipsum']
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, 0, 2, 'lorem', 'ipsum');
+const resultArray = immutableArrays.splice(originalArray, 0, 2, 'lorem', 'ipsum');
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['lorem', 'ipsum', 'c', 'd', 'e']
 
 const originalArray = ['a', 'b', 'c', 'd', 'e'];
-const resultArray = immutableSplice(originalArray, originalArray.length - 2, 2, 'lorem', 'ipsum');
+const resultArray = immutableArrays.splice(originalArray, originalArray.length - 2, 2, 'lorem', 'ipsum');
 // -> originalArray ['a', 'b', 'c', 'd', 'e']
 // -> resultArray ['a', 'b', 'c', 'lorem', 'ipsum']
 ```
 
+## Test
+
+```sh
+$ npm test
+```
+
+## Test Coverage
+
+```sh
+$ npm run coverage
+```
+
 ## License
 
 [The MIT License (MIT)](https://georapbox.mit-license.org/@2017)