@webkrafters/react-observable-context 2.1.6 → 2.1.8

package/README.md

@@ -1,26 +1,30 @@
 # React-Observable-Context
 
-A context bearing an observable consumer store. State changes within the store's internal state are only broadcasted to components subscribed to the store. In this way, the `React-Observable-Context` prevents repeated automatic re-renderings of entire component trees resulting from ***context*** state changes.
+A context bearing an observable consumer store.
 
-**React::memo** *(and PureComponents)* remain the go-to solution for the repeated automatic re-renderings of entire component trees resulting from ***component*** state changes. 
+**Name:** React-Observable-Context
 
-_**Recommendation:**_ For optimum performance, consider wrapping in **React::memo** most components using this package's ***useContext*** function either directly or through another React hook. This will protect such components and their descendants from unrelated cascading render operations.
+**Usage:** Please see [Usage](#usage) section
 
-***Exempt*** from the recommendation are certain components such as those wrapped in the `React-Redux::connect()` Higher Order Component (HOC). Such HOC provides similar cascade-render protections to wrapped components and their descendants. 
+**Install:**\
+npm i -S @webkrafters/react-observable-context\
+npm install --save @webkrafters/react-observable-context
+
+# Intro
 
-<hr />
+State changes within the store's internal state are only broadcasted to components subscribed to the store. In this way, the `React-Observable-Context` prevents repeated automatic re-renderings of entire component trees resulting from ***context*** state changes.
 
-<h3><u>Install</u></h3>
+**React::memo** *(and PureComponents)* remain the go-to solution for the repeated automatic re-renderings of entire component trees resulting from ***component*** state changes. 
 
-npm i -S @webkrafters/react-observable-context
+_**Recommendation:**_ For optimum performance, consider wrapping in **React::memo** most components using this package's ***useContext*** function either directly or through another React hook. This will protect such components and their descendants from unrelated cascading render operations.
 
-npm install --save @webkrafters/react-observable-context
+***Exempt*** from the recommendation are certain components such as those wrapped in the `React-Redux::connect()` Higher Order Component (HOC). Such HOC provides similar cascade-render protections to wrapped components and their descendants. 
 
-## API
+# API
 
 The React-Observable-Context package exports **4** modules namely: the **createContext** method, the **useContext** hook, the **Provider** component and the **UsageError** class.
 
-* **createContext** is a zero-parameter funtion returning a store-bearing context. Pass the context to the React::useContext() parameter to obtain the context's `store`.
+* **createContext** is a zero-parameter function returning a store-bearing context. Pass the context to the useContext() parameter to obtain the context's `store`.
 
 * **useContext** is analogous to React::useContext hook but returns the context store and takes a second parameter named ***watchedKeys***. The `watchedKeys` parameter is a list of state object property paths to watch. A change in any of the referenced properties automatically triggers a render of the component calling this hook.
 
@@ -30,7 +34,7 @@ The React-Observable-Context package exports **4** modules namely: the **createC
 
 ***<u>Note:</u>*** the Provider `context` prop is not updateable. Once set, all further updates to this prop are not recorded.
 
-### The Store
+## The Store
 
 The context's `store` exposes **4** methods for interacting with the context's internal state namely:
 
@@ -38,23 +42,29 @@ The context's `store` exposes **4** methods for interacting with the context's i
 
 * **resetState**: VoidFunction // resets the state to the Provider initial `value` prop.
 
-* **setState**: (changes: PartialState\<State\>) => void // sets only new/changed top level properties.
+* **setState**: (changes: PartialState\<State\>) => void // sets only new/changed state slices.\
+***Do this:*** `setState({stateKey0: changes0[, ...]});`\
+***Not this:*** `setState({stateKey0: {...state.stateKey0, ...changes0}[, ...]});`
 
 * **subscribe**: (listener: (newValue: PartialState\<State\>, oldValue: PartialState\<State\>) => void) => ***UnsubscribeFunction***
 
-### Prehooks
+## Prehooks
+
+ Prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates.
 
-The context's store update operation adheres to **2** user supplied prehooks when present. Otherwise, the update operation proceeds normally to completion. They are named **resetState** and **setState** after the store update methods which utilize them.
+ The context store **2** update operations each adhere to its own user specified prehook when present. Otherwise, the update operation proceeds normally to completion. Thus, there are **2** prehooks named **resetState** and **setState** - after the store update methods they support.
+ 
+ Each prehook returns a **boolean** value (`true` to continue AND `false` to abort the update operation). The prehook may modify (i.e. sanitize, transform, transpose) the argument to accurately reflect the intended update value. This is done by mutating part of the argument which holds the next `nextUpdate` values.
 
-* **resetState**: (state: {current: State, original: State}) => boolean
+* **resetState**: (state: {current: State, original: State}) => boolean // ***`state.original`*** holds the `nextUpdate` values.
 
-* **setState**: (newChanges: PartialState\<State\>) => boolean
+* **setState**: (newChanges: PartialState\<State\>) => boolean // ***`newChanges`*** holds the `nextUpdate` values.
 
-***<u>Use case:</u>*** prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates. The prehook returns a **boolean** value (`true` to continue AND `false` to abort the update operation). The prehook may mutate (i.e. sanitize, transform, transpose) its argument values to accurately reflect the intended update value.
+***<u>Use case:</u>*** prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates.
 
-## Usage
+# Usage
 
-<i><u>context.js</u></i>
+### <u>*context.js*</u>
 
     import React from 'react';
 
@@ -81,14 +91,14 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 	export default ObservableContext;
 
-<i><u>index.js</i></b>
+### <u>*index.js*</u>
 
     import React from 'react';
     import ReactDOM from 'react-dom';
     import App from './app';
     ReactDOM.render(<App />, document.getElementById('root'));
 
-<i><u>app.js</u></i>
+### <u>*app.js*</u>
 
     import React, { useCallback, useState } from 'react';
 	import Product from './product';
@@ -122,7 +132,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	App.displayName = 'App';
 	export default App;
 
-<i><u>product.js</u></i>
+### <u>*product.js*</u>
 
 	import React, { useCallback, useEffect, useState } from 'react';
 	import { ObservableContextProvider } from './context';
@@ -167,7 +177,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	Product.displayName = 'Product';
 	export default Product;
 
-<i><u>editor.js</u></i>
+### <u>*editor.js*</u>
 
     import React, { memo, useCallback, useEffect, useRef } from 'react';
 	import { useObservableContext } from './context';
@@ -210,7 +220,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	Editor.displayName = 'Editor';
 	export default Editor;
 
-<i><u>price-sticker.js</u></i>
+### <u>*price-sticker.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -227,7 +237,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	PriceSticker.displayName = 'PriceSticker';
 	export default PriceSticker;
 
-<i><u>product-description.js</u></i>
+### <u>*product-description.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -246,7 +256,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	ProductDescription.displayName = 'ProductDescription';
 	export default ProductDescription;
 
-<i><u>tally-display.js</u></i>
+### <u>*tally-display.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -273,7 +283,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	TallyDisplay.displayName = 'TallyDisplay';
 	export default TallyDisplay;
 
-<i><u>reset.js</u></i>
+### <u>*reset.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -286,6 +296,6 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 	export default Reset;
 
 
-## License
+# License
 
 MIT

package/package.json

@@ -79,5 +79,5 @@
     "test:watch": "eslint --fix && jest --updateSnapshot --watchAll"
   },
   "types": "dist/index.d.ts",
-  "version": "2.1.6"
+  "version": "2.1.8"
 }