redux-create-state - npm Package Compare versions

Comparing version 0.1.0 to 1.0.0

package.json

 {
   "name": "redux-create-state",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Create new Redux state immutably",
   "keywords": [
     "redux",
+    "create",
     "state",
@@ -8,0 +9,0 @@ "immutable"

README.md

 # Redux Create State
 
-A utility library (or actually just a single function) to ease the process of creating a new state object immutably in Redux.
+A utility function for Redux to ease the process of creating a new state object, immutably.
 
-As stated in the [Redux website](http://redux.js.org/docs/recipes/reducers/ImmutableUpdatePatterns.html):
+**Features**
+
+* Tiny (~1kb minified)
+* Fast (clones only the necessary objects and arrays)
+* Simple API (it's just one function)
+* Works in IE9+ and all modern browsers
+
+**Why do I need this?**
+
+As stated on the [Redux website](http://redux.js.org/docs/recipes/reducers/ImmutableUpdatePatterns.html):
+
 > The key to updating nested data is **that every level of nesting must be copied and updated appropriately**. This is often a difficult concept for those learning Redux, and there are some specific problems that frequently occur when trying to update nested objects. These lead to accidental direct mutation, and should be avoided.
 
-This library provides a single function for creating a new state based on the current state, immutably. It works by first creating a shallow clone of the current state and then cloning all the nested arrays and objects between the root object and the inserted values. So the whole state is not deep cloned automatically, only the necessary arrays and objects.
+This function aims to make that problem go away. It works by first creating a *shallow* clone of the current state (object or array) and then cloning all the nested arrays and objects between the root object/array and the inserted values. So the whole state is not deep cloned automatically, only the necessary arrays and objects are cloned to make the function perform as fast as possible.
 
@@ -66,3 +76,3 @@ ## Install
 
-`reduxCreateState(state, [...insert])`
+### `reduxCreateState(state, [...insert])`
 
@@ -75,4 +85,4 @@ **Parameters**
   * Optional.
-  * You can provide any number of insert operations which will be applied to the new state. These operations do not mutate the current state object.
-  * A single insert operation is defined with an array consisting of two items. The first item is the inserted value's path and the second item is the actual value. The path is just a string where each path step (object key) is separated with a dot (e.g. 'foo.bar.baz'). You can also use an array index as path step by prefixing the key with octothorpe (e.g. 'items.#1').
+  * You can provide any number of insert operations which will be applied to the new state. These operations do not mutate the current state object/array.
+  * A single insert operation is defined with an array which consists of two items. The first item is the insert's path and the second item is the insert's value. The path is just a string where each path step (object key) is separated with a dot (e.g. `'foo.bar.baz'`). You can also use an array index as path step by prefixing the key with octothorpe (e.g. `'foo.bar.items.#1'`).
   * If the insert path does not exist it will be created. Every existing step in the path will be cloned.
@@ -83,6 +93,93 @@ * If the insert operation's value is a function it will be called and it's return value will be set as the insert path's value. The function receives the current value (already cloned if object or array) as it's first argument and the parent object/array as it's second argument (also already cloned).
 
-Returns a new state object.
+Returns a new state object or array, depending on the provided state.
 
+## Examples
+
+Here are some examples for common use cases. All the examples assume that you have imported the library as `createState`:
+```javascript
+import createState from 'redux-create-state';
+```
+
+**Update deeply nested object**
+
+```javascript
+const state = {a: {b: { c: 'foo' } } };
+const newState = createState(state, ['a.b.c', 'bar']);
+console.log(newState);
+// => {a: {b: { c: 'bar' } } }
+```
+
+**Create deeply nested object**
+
+```javascript
+const state = {};
+const newState = createState(state, ['a.b.c', 'foo']);
+console.log(newState);
+// => {a: {b: { c: 'foo' } } }
+```
+
+**Create a deeply nested object which has an array in it's path**
+
+```javascript
+const state = {};
+const newState = createState(state, ['a.b.#0.c', 'foo']);
+console.log(newState);
+// => {a: {b: [ {c: 'foo'} ] } }
+```
+
+**Update an existing array item**
+
+```javascript
+const state = {items: ['foo', 'bar']};
+const newState = createState(state, ['items.#1', 'baz']);
+console.log(newState);
+// => {items: ['foo', 'baz']}
+```
+
+**Append and prepend items to an array**
+
+```javascript
+const state = {items: ['foo', 'bar']};
+const newState = createState(state, ['items', (items) => {
+  items.unshift('start');
+  items.push('end');
+  return items;
+}]);
+console.log(newState);
+// => {items: ['start', 'foo', 'bar', 'end']}
+```
+
+**Remove items from an array**
+
+```javascript
+const state = {items: ['foo', 'bar', 'baz']};
+const newState = createState(state, ['items', (items) => {
+  items.splice(1, 1);
+  return items;
+}]);
+console.log(newState);
+// => {items: ['foo', 'baz']}
+```
+
+**Do multiple modifications**
+
+```javascript
+const state = {items: ['foo', 'bar']};
+const newState = createState(state,
+  ['items.#1', 'baz'],
+  ['foo.bar', 'baz']
+);
+console.log(newState);
+// => {
+//   items: ['foo', 'baz'],
+//   foo: {bar: 'baz'}
+// }
+```
+
+## Alternatives
+
+As always, there's a [swarm of awesome alternatives](https://github.com/markerikson/redux-ecosystem-links/blob/master/immutable-data.md#immutable-update-utilities) for you to pick from.
+
 ## License
 
 Copyright © 2017 Niklas Rämö. Licensed under **[the MIT license](LICENSE.md)**.

redux-create-state.js

 /*!
- * redux-create-state v0.1.0
+ * redux-create-state v1.0.0
  * https://github.com/niklasramo/mezr
@@ -4,0 +4,0 @@ * Copyright (c) 2017 Niklas Rämö <[e-mail]>

redux-create-state.min.js

 /*!
- * redux-create-state v0.1.0
+ * redux-create-state v1.0.0
  * https://github.com/niklasramo/mezr
@@ -4,0 +4,0 @@ * Copyright (c) 2017 Niklas Rämö <[e-mail]>

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

159435

increased by1.52%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

183

increased by112.79%

No dependency changes