@webkrafters/react-observable-context 4.7.3 → 4.7.5

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-	<img alt="Eagle Eye" height="150px" src="eagle-eye.png" width="250px" />
+	<img alt="Eagle Eye" height="150px" src="/docs/public/img/logo.png" width="250px" />
 </p>
 <p align="center">
 	<a href="https://typescriptlang.org">
@@ -23,10 +23,10 @@
 # React-Observable-Context [Eagle Eye]
 
 <ul>
-	<li> Update-friendly context.</li>
-	<li> A context bearing an observable consumer <a href="#store">store</a>.</li>
-	<li> Recognizes <b>negative array indexing</b>. Please see <a href="#property-path">Property Path</a> and <code>store.setState</code> <a href="#indexing">Indexing</a>.</li>
-	<li> Only re-renders subscribing components (<a href="#client">clients</a>) on context state changes.</li>
+	<li> Auto-immutable update-friendly context. See <a href="https://eagleeyejs.org/concepts/store/setstate"><code>store.setState</code></a>.</li>
+	<li> A context bearing an observable consumer <a href="https://eagleeyejs.org/concepts/store">store</a>.</li>
+	<li> Recognizes <b>negative array indexing</b>. Please see <a href="https://eagleeyejs.org/concepts/property-path">Property Path</a> and <code>store.setState</code> <a href="https://eagleeyejs.org/concepts/store/setstate#indexing">Indexing</a>.</li>
+	<li> Only re-renders subscribing components (<a href="https://eagleeyejs.org/concepts/client">clients</a>) on context state changes.</li>
 	<li> Subscribing component decides which context state properties' changes to trigger its update.</li>
 </ul>
 
@@ -34,7 +34,7 @@
 
 **Moniker:** Eagle Eye
 
-**Usage:** Please see <b><a href="#getting-started">Getting Started</a></b>.
+**Usage:** Please see <b><a href="https://eagleeyejs.org/getting-started">Getting Started</a></b>.
 
 **Demo:** [Play with the app on codesandbox](https://codesandbox.io/s/github/webKrafters/react-observable-context-app)\
 If sandbox fails to load app, please refresh dependencies on its lower left.
@@ -43,700 +43,10 @@ If sandbox fails to load app, please refresh dependencies on its lower left.
 npm i -S @webkrafters/react-observable-context\
 npm install --save @webkrafters/react-observable-context
 
-May also see <b><a href="#changes">What's Changed?</a></b>.
+May also see <b><a href="https://eagleeyejs.org/history/features">What's Changed?</a></b>
 
-<h1 id="toc">Table of Contents</h1>
-
-<a href="#intro">Intro</a><br /><a href="#getting-started">Getting Started</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#create-context-usage">Creating context</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#provider-usage">Setting up the Provider</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#connect-usage">Consuming context (hoc method)</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#usecontext-usage">Consuming context (hook with memo method)</a><br />
-<a href="#api">API</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#connect">Connect HoC</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#create-context">CreateContext Function</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#usage-error">UsageError Exception</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#usecontext">UseContext Hook</a><br />
-<a href="#concepts">Concepts</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#client">Client</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#prehooks">Prehooks</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#property-path">Property Path</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#fullstate-selectorkey"><b>@@STATE</b></a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#provider">Provider</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#selector-map">Selector Map</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#storage">Storage</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#store">Store</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#store-resetstate">Reset State</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#store-setstate">Set State</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#batched-update">Batched Update</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#indexing">Array Indexing</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#setstate-tags">Using Tag Commands</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#clear-tag-usage"><b>@@CLEAR</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#delete-tag-usage"><b>@@DELETE</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#move-tag-usage"><b>@@MOVE</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#push-tag-usage"><b>@@PUSH</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#replace-tag-usage"><b>@@REPLACE</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#set-tag-usage"><b>@@SET</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#splice-tag-usage"><b>@@SPLICE</b> Usage Example</a><br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#set-state-with-tags">Combination Usage Example</a><br />
-<a href="#changes">What's Changed?</a><br />
-<a href="#license">License</a><br />
-
-# Intro
-
-A context bearing an observable consumer [store](#store) whose internal state is <u><b>immutable</b></u> and <u><b>private</b></u>. State changes within the store's internal state are only broadcasted to components (the [clients](#client)) 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.
-
-<h1 id="getting-started">Getting Started</h1>
-
-<i><b><u>index.js</u></b></i>
-
-```jsx
-import React from 'react';
-import ReactDOM from 'react-dom';
-import App from './app';
-
-ReactDOM.render( <App />, document.getElementById( 'root' ) );
-```
-
-<i><b><u>app.js</u></b></i>
-
-```jsx
-import React, { useEffect, useState } from 'react';
-import ProviderDeno from './provider-demo';
-
-const MILLIS_PER_MINUTE = 6e4;
-
-let numCreated = 0;
-
-const App = () => {
-  const [ age, updateAge ] = useState( 0 );
-  const [ testNumber ] = useState( () => ++numCreated );
-
-  useEffect(() => {
-    const t = setTimeout(
-      () => updateAge( age => age + 1 ),
-      MILLIS_PER_MINUTE
-    ); 
-    return () => clearTimeout( t );
-  }, [ age ]);
-
-  return (
-    <div>
-      <h2>App instance #: { testNumber }</H2>
-      <ProviderDeno ageInMinutes={ age } />
-    </div>
-  );
-}
-export default App;
-```
-
-<i id="create-context-usage"><u><b>context.js</b></u></i>
-
-```jsx
-import { createContext } from '@webkrafters/react-observable-context';
-export default createContext();
-```
-
-<i id="provider-usage"><b><u>provider-demo.js</u></b></i>
-
-```jsx
-import React, { useEffect, useState } from 'react';
-import ObservableContext from './context';
-import Ui from './ui';
-
-const createInitialState = c = ({
-  a: { b: { c, x: { y: { z: [ 2022 ] } } } }
-});
-
-const ProviderDemo = ({ ageInMinutes: c = 0 }) => {
-	
-  const [ value, setValue ] = useState(() => createInitialState( c ));
-
-  useEffect(() => {
-    // similar to `store.setState`, use the following to update
-    // only the changed slice of the context internal state.
-    // Please use the `Set State` link in the TOC for more details.
-    setValue({ a: { b: { c } } }); // OR
-    // setValue({ a: { b: { c: { '@@REPLACE': c } } } });
-    // Do not do the following: it will override the context internal state.
-    // setValue({ ...value, a: { ...value.a, b: { ...value.a.b, c } } });
-  }, [ c ]);
-
-  return (
-    <ObservableContext.Provider value={ value }>
-      <Ui />
-    </ObservableContext.Provider>
-  );
-};
-ProviderDemo.displayName = 'ProviderDemo';
-
-export default ProviderDemo;
-```
-
-<i id="connect-usage"><u><b>ui.js</b></u> (connect method)</i>
-
-```jsx
-import React, { useCallback, useEffect } from 'react';
-import { connect } from '@webkrafters/react-observable-context';
-import ObservableContext from './context';
-
-export const YearText = ({ data }) => ( <div>Year: { data.year }</div> );
-
-export const YearInput = ({ data, resetState, setState }) => {
-  const onChange = useCallback( e => setState({
-    a: { b: { x: { y: { z: { 0: e.target.value } } } } }
-  }), [ setState ]);
-
-  useEffect(() => {
-    data.year > 2049 && resetState([ 'a.b.c' ]);
-  }, [ data.year ]);
-  
-  return ( <div>Year: <input type="number" onChange={ onChange } /></div> );
-};
-
-const withConnector = connect( ObservablContext, { year: 'a.b.x.y.z[0]' } );
-const Client1 = withConnector( YearText );
-const Client2 = withConnector( YearInput );
-
-const Ui = () => (
-  <div>
-    <Client1 />
-    <Client2 />
-  </div>
-);
-
-export default Ui;
-```
-
-<i id="usecontext-usage"><u><b>ui.js</b></u> (useContext with memo method)</i>
-
-```jsx
-import React, { memo, useCallback, useEffect } from 'react';
-import { useContext } from '@webkrafters/react-observable-context';
-import ObservableContext from './context';
-
-const selectorMap = { year: 'a.b.x.y.z[0]' };
-
-const Client1 = memo(() => { // memoize to prevent 'no-change' renders from the parent.
-  const { data } = useContext( ObservableContext, selectorMap );
-  return ( <div>Year: { data.year }</div> );
-});
-
-const Client2 = memo(() => { // memoize to prevent 'no-change' renders from the parent.
-  const { data, setState, resetState } = useContext( ObservableContext, selectorMap );
-
-  const onChange = useCallback( e => setState({
-    a: { b: { x: { y: { z: { 0: e.target.value } } } } }
-  }), [ setState ]);
-
-  useEffect(() => {
-    data.year > 2049 && resetState([ 'a.b.c' ]);
-  }, [ data.year ]);
-
-  return ( <div>Year: <input type="number" onChange={ onChange } /></div> );
-});
-
-const Ui = () => (
-  <div>
-    <Client1 />
-    <Client2 />
-  </div>
-);
-
-export default Ui;
-```
-
-# API
-
-The React-Observable-Context module exports named constants and the following **4** main entities namely:
-<ol>
-	<li style="padding-bottom: 5px">
-		<p style="margin: 0 0 5px 5px">
-			<b id="connect">connect</b>
-			<p style="margin: -5px 0 0 5px">
-				<span style="margin: 5px 10px 0 0">-</span>is a function taking a <code>React-Observable-Context</code> context object and an optional <a href="#selector-map">selector map</a> parameters; and returning a reusable connector function.<br />
-				<span style="margin: 5px 10px 0 0">-</span>The connector function takes a client as a parameter and returns an HOC.<br />
-				<span style="margin: 5px 10px 0 0">-</span>Any client using similar context object and selector map may be passed to this connector.<br />
-				<span style="margin: 5px 10px 0 0">-</span>The HOC injects the context <a href="#store">store</a> to the client and handles all of the context usage requirements.<br />
-				<span style="margin: 5px 10px 0 0">-</span>The injected <a href="#store">store</a> monitors changes in the underlying state slices referenced by the selector map.<br />
-				<span style="margin: 5px 10px 0 0">-</span>A change in any of the referenced state slices automatically triggers an update of the related <code>store.data</code> property and a subsequent render of the client.<br />
-				<span style="margin: 5px 10px 0 0">-</span>Any prop name conflicts between injected <a href="#store">store properties</a> and the client's own props are resolved in favor of the client's own props.
-			</p>
-		</p>
-	</li>
-	<li style="padding-bottom: 5px">
-		<p style="margin: 0 0 5px 5px">
-			<b id="create-context">createContext</b> is a zero-parameter function returning a <code>React-Observable-Context</code> object. This object is the store-bearing context. To access the context's <a href="#store">store</a>, pass the context as a <code>context</code> parameter to either the <a href="#connect">connect</a> function or the <a href="#usecontext">useContext</a> hook.
-		</p>
-	</li>
-	<li style="padding-bottom: 5px">
-		<p style="margin: 0 0 5px 5px">
-			<b id="usage-error">UsageError</b> class is the Error type reported for attempts to access this context's store outside of its Provider component tree.
-		</p>
-	</li>
-	<li>
-		<p style="margin: 0 0 5px 5px">
-			<b id="usecontext">useContext</b>
-			<p style="margin: -5px 0 0 5px">
-				<span style="margin: 5px 10px 0 0">-</span>is a hook taking a <code>React-Observable-Context</code> context object and an optional <a href="#selector-map">selector map</a> parameters; and returning the context <a href="#store">store</a>.<br />
-				<span style="margin: 5px 10px 0 0">-</span>The injected <a href="#store">store</a> monitors changes in the underlying state slices referenced by the selector map.<br />
-				<span style="margin: 5px 10px 0 0">-</span>A change in any of the referenced state slices automatically triggers an update of the related <code>store.data</code> property and a subsequent render of the client.<br />
-				<span style="margin: 5px 10px 0 0">-</span>The <a href="#connect">connect</a> function is axiomatically the more conducive method for consuming this conetxt.<br />
-				<span style="margin: 5px 10px 0 0">-</span>In certain user-specific cases, direct access to this hook may be preferrable.<br />
-				<span style="margin: 5px 10px 0 0">-</span>In such cases, it is advisable to wrap the client in a <code>React.memo</code>.
-			</p>
-		</p>
-	</li>
-</ol>
-
-# Concepts
-
-## Client
-A client is any component consuming the observable context. A client consumes the context either by using the <code>React-Observable-Context <a href="#usecontext">useContext</a></code> hook or by embedding itself within the connector returned by the <code>React-Observable-Context <a href="#connect">connect</a></code> function.
-
-## Prehooks
- Prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates. The context store obtains its prehooks via its context [Provider's](#provider) `prehooks` optional prop.
-
- The context store **2** update operations each adhere to its own user-defined 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.
- <ol>
-	<li>
-		<p style="margin: 0 0 5px 10px">
-			<b>resetState:</b> 
-			<code style="margin: 10px 5px">(resetData: PartialState&lt;State&gt;, state: {current: State, original: State}) => boolean;</code> // <b><i><code>resetData</code></i></b> holds the <code>nextUpdate</code> values.
-		</p>
-	</li>
-	<li>
-		<p style="margin: 0 0 5px 10px">
-			<b>setState:</b> 
-			<code style="margin: 10px 5px">(newChanges: PartialState&lt;State&gt;) => boolean;</code> // <b><i><code>newChanges</code></i></b> holds the <code>nextUpdate</code> values.
-		</p>
-	</li>
- </ol>
-
-***<u>Use case:</u>*** prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates.
-
-<h2 id="property-path">Property path</h2>
-A property path is a dot-notation string leading to a specific property within an object.<br />
-<code>React-Observable-Context</code> recognizes any property path abiding by the <b><i><u>Lodash</u></i></b> property path specifications. Such property paths may also contain negative integers.<br /><br />
-
-<b>Negative</b> integer (<i>-N</i>) in a property path indicates an array index derived at runtime by counting `abs(-N)` steps backward from array length.<br />
-
-<b id="property-path-example">Ex. Given the following object:</b>
-
-```jsx
-{ a: { c: { e: 5, f: [ 0, 2, 4 ] } } }
-```
-The property path `a.c.e` accesses the `e=5` property.<br />
-Either of the property paths `a.c.f.1`, `a.c.f.-2`, `a.c.f[1]` and `a.c.f[-2]` is a valid property path to access the `[1]=2` property.<br />
-A special property path [@@STATE](#fullstate-selectorkey) may be used to access the full given object.<br />
-
-<strong id="fullstate-selectorkey"><u>@@STATE</u></strong> is a special property path to access the full state object as a single slice.<br />
-:warning: <b><i>Caution:</i></b> When this property path exists in a <a href="#selector-map">selector map</a>, any change in the state object results in an update of its <a href="#store"><code>store.data</code></a> and a subsequent render of its client(s).
-
-## Provider
-The Provider component is a property of the `React-Observable-Context` context object. As a `React.context` based provider, it accepts the customary `children` and `value` props. It also accepts **2** optional props: <a href="#prehooks"><code>prehooks</code></a> and <a href="#storage"><code>storage</code></a>.
-
-External direct access to the context store may be obtained via the `ref` attribute. Please see a [Provider Usage](#provider-usage) sample. 
-
-Routinely, the `value` prop is initialized with the full initial state. It may only be updated with parts of the state which are changing. Please see a [Provider Usage](#provider-usage) sample. 
-
-<h2 id="selector-map">Selector Map</h2>
-A selector map is an object holding key:value pairs.<br />
-<i><b>An array of <a href="#property-path">property paths</a> is also acceptable:</b> indexes serve as keys for this purpose.</i><br />
-<span style="margin-right: 10px">-</span><code>key</code> refers to an arbitrary name to be assigned to a given property in the <a href="#store"><code>store.data</code></a>.<br />
-<span style="margin-right: 10px">-</span><code>value</code> refers to the <a href="#property-path">property path</a> leading to a state slice whose value will be assigned to and observed by this <a href="#store"><code>store.data</code></a> property.<br />
-<span style="margin-right: 10px">-</span>A special '<a href="#fullstate-selectorkey">@@STATE</a>' value may be used to access and observe the full state object.<br />
-
-<strong id="selector-map-example">Example:</strong>
-
-```jsx
-// Given the following state object:
-const state = {
-  a: 1, b: 2, c: 3, d: {
-    e: 5,
-    f: [ 6, {
-      x: 7,
-      y: 8,
-      z: 9
-   } ]
-  }
-};
-
-/* --------------------------------------------- */
-/* a client observing the following selector map */
-/* --------------------------------------------- */
-const selectorMap = {
-  all: '@@STATE',
-  myData: 'd',
-  secondFElement: 'd.f[1]'
-};
-
-// will receive the following store data
-store.data = {
-  all: state,
-  myData: state.d,
-  secondFElement: state.d.f[1]
-};
-
-/* --------------------------------------------------- */
-/* a client observing the following property path list */
-/* --------------------------------------------------- */
-const propertyPaths = [ '@@STATE', 'd', 'd.f[1]' ];
-
-// will receive the following store data
-store.data = {
-  0: state,
-  1: state.d,
-  2: state.d.f[1]
-};
-
-```
-
-## Storage
-The `React.Observable.Context` context allows for a user-defined Storage object to be provided for maintaining the integrity of the initial context state at a location of the user's choosing. This, it accepts, via its Provider's `storage` optional prop. The context defaults to `window.sessionstorage` in supporting environments. Otherwise, it defaults to its own internal memory-based storage.
-
-A valid storage object is of the type: `IStorage<State>` implementing the following **4** methods:
-<ol>
-	<li><code style="margin-left: 10px">clone: (data: State) => State; // expects a state clone</code></li>
-	<li><code style="margin-left: 10px">getItem: (key: string) => State;</code></li>
-	<li><code style="margin-left: 10px">removeItem: (key: string) => void;</code></li>
-	<li><code style="margin-left: 10px">setItem: (key: string, data: State) => void;</code></li>
-</ol>
-
-## Store
-The `React.Observable.Context` context `store` is the client's portal into the context's underlying state. It exposes **3** properties namely:
-<ol>
-	<li>
-		<p style="margin: 0 0 0 10px">
-			<b>data:</b> 
-			<span style="margin-left: 5px">
-				which is an object holding resolved state slices as declared in the selector map. <a href="#selector-map-example">See selector map to store data example here</a>
-			</span>
-		</p>
-	</li>
-	<li>
-		<p style="margin: 0 0 0 10px">
-			<a href="#store-resetstate"><b>resetState:</b></a> 
-			<code style="margin-left: 5px">(propertyPaths?: Array&lt;string&gt;) => void // resets slices of state referenced by the property paths to their initial values.</code>
-		</p>
-	</li>
-	<li>
-		<p style="margin: 0 0 0 10px">
-			<a href="#store-setstate"><b>setState:</b></a> 
-			<code style="margin-left: 5px">(changes: Changes&lt;State&gt;) => void // merges only new/changed state slices.</code>
-		</p>
-	</li>
-</ol>
-<h3 id="store-resetstate"><code>store.resetState</code> Usage</h3>
-<span style="margin: 5px 10px 0 0">-</span>Resets slices of state to their initial state values as desired.<br />
-<span style="margin: 5px 10px 0 0">-</span>Accepts an array of property paths referencing the desired slices of state to reset.<br />
-<span style="margin: 5px 10px 0 0">-</span>Performs a total state reset when <code>'@@STATE'</code> is present in the property paths array.<br />
-<span style="margin: 5px 10px 0 0">-</span>Resets state slices referenced by the calling client's selector map when invoked with 0 arguments.<br />
-<span style="margin: 5px 10px 0 16px">-</span>Performs a total state reset when <code>'@@STATE'</code> is present in the calling client's selector map.<br />
-<span style="margin: 5px 10px 0 0">-</span>Performs no state reset when a client with no selector map invokes this method with 0 arguments.
-
-<h3 id="store-setstate" style="margin-top:10px"><code>store.setState</code> Usage</h3>
-
-<blockquote>[This store's] internal state is <u><b>immutable</b></u> and <u><b>private</b></u>.<br />Direct mutation attempts on its properties have no effect.</blockquote>
-New updates are merged into state by default. So only supply the exact changes to be merged <b><i>(i.e. do not spread the new state changes into the current state as is commonly done in React development)</i></b>. And to overwrite a slice of state, use the <a href="#setstate-tags">tag</a> command.<br />
-:warning: <b><i>Do this:</i></b> <code>setState({stateKey0: changes0});</code><br />
-:warning: <b><i>Not this:</i></b> <code>setState({...state, stateKey0: {...state.stateKey0, ...changes0}});</code><br />
-
-<h3 id="batched-update"><i><u>Batched update</u></i></h3>
-provides a way to update the state as a transaction of several state changes. This can be achieved by collecting a series of state changes in an array and passing that array as an argument to the <code>store.setState</code> method. The state changes are resolved sequentially from <code>index 0</code> to the <code>last index</code>. <a href="#client">Clients</a> are only notified at batched update completion.<br />
-:warning: <b><i>Do this:</i></b> <code>setState([<br />
-&nbsp;&nbsp;&nbsp;&nbsp;{stateKey0: changes0},<br />
-&nbsp;&nbsp;&nbsp;&nbsp;{stateKey1: changes1},<br />
-&nbsp;&nbsp;&nbsp;&nbsp;// et cetera ... et cetera<br />
-]);</code><br />
-:warning: <b><i>Not this:</i></b> <code>setState([<br />
-&nbsp;&nbsp;&nbsp;&nbsp;{...state, stateKey0: {...state.stateKey0, ...changes0}},<br />
-&nbsp;&nbsp;&nbsp;&nbsp;{...state, stateKey1: {...state.stateKey1, ...changes1}},<br />
-&nbsp;&nbsp;&nbsp;&nbsp;// et cetera ... et cetera<br />
-]);</code>
-
-<h3 id="indexing"><i><u>Indexing</u></i></h3>
-Traditionally, array state properties are updated by a new array replacement. This overwrites the existing state property.<br />
-Hence the need for <code>indexing</code>. Indexing provides a mechanism for updating array state properties at specific indexes using an indexed state change object.<br />
-The store also recognizes and resolves negative indexes when present in the indexed state change object. See additional <a href="#neg-idx-tip">tip</a> below.<br />
-<strong>Example:</strong>
-
-```jsx
-// Given the following array bearing state object:
-const state = { a: { b: [ { x: 7, y: 8, z: 9 } ] }, j: 10 };
-
-// The following will override the existing array.
-store.setState({ a: { b: [ { y: 30 }, 22 ] } });
-// updates the state to: { a: { b: [ { y: 30 }, 22 ] }, j: 10 };
-
-// The followinng will update the existing array at indexes.
-store.setState({ a: { b: { 0: { y: 30 }, 1: 22 } } });
-// updates the state to: { a: { b: [ { x: 7, y: 30, z: 9 }, 22 ] }, j: 10 };
-
-// The followinng will update the existing array at indexes.
-store.setState({ a: { b: { '-1': { y: 30 }, 1: 22 } } });
-// updates the state to: { a: { b: [ { x: 7, y: 30, z: 9 }, 22 ] }, j: 10 };
-
-// The previous 2 statements are functionally equivalent to the following:
-const [ first, second, ...rest ] = state.a.b;
-store.setState({ ...state, a: { ...state.a, b: [ { ...first, y: 30 }, 22, ...rest ] } });
-// Refrain from doing this, please!
-```
-:warning: <b id="neg-idx-tip"><i>Tip:</i></b> Negative indexing pointing at an out-of-bounds index is ignored.
-
-<h3 id="setstate-tags"><b><i><u>Overwriting state using tag commands</u></i></b></h3>
-By default, <code>store.setState</code> recursively merges new changes into current state.<br />
-To overwrite current state slices with new values, <b>7</b> tag commands have been provided:
-<ol>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@CLEAR:</i></b> sets state slice to its corresponding empty value</span></li>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@DELETE:</i></b> removes plain object properties and array items</span></li>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@MOVE:</i></b> moves array elements</span></li>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@PUSH:</i></b> pushes new items into an array</span></li>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@REPLACE:</i></b> replaces property values</span></li>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@SET:</i></b> sets property values</span></li>
-	<li><span style="margin-left: 10px"><b style="margin-right: 6px"><i>@@SPLICE:</i></b> splices array items</span></li>
-</ol>
-<b>Examples:</b><br /><br />
-
-<i id="clear-tag-usage"><b>@@CLEAR:</b> (takes no arguments)</i>
-
-```jsx
-import { CLEAR_TAG } from '@webkrafters/react-observable-context'; // CLEAR_TAG = "@@CLEAR"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10
-};
-
-/* empties the state; sets state = {} */
-store.setState( CLEAR_TAG ) // or store.setState({ [ CLEAR_TAG ]: <anything> })
-
-/* empties the value at state.a.b; sets state.a.b = [] */
-store.setState({ a: { b: CLEAR_TAG } }) // or store.setState({ a: { b: { [ CLEAR_TAG ]: <anything> } } })
-
-/* empties the value at state.a.j; sets state.a.j = null */
-store.setState({ a: { j: CLEAR_TAG } }) // or store.setState({ a: { j: { [ CLEAR_TAG ]: <anything> } } })
-
-/* empties the value at state.a.b[ 0 ]; sets state.a.b = [{}] */
-store.setState({ a: { b: [ CLEAR_TAG ] } }) // or store.setState({ a: { b: [ { [ CLEAR_TAG ]: <anything> } ] } })
-
-/* empties the value at state.a.b[0]; sets state.a.b = [{}, state.a.b[1]] */
-store.setState({ a: { b: [ CLEAR_TAG, state.a.b[1] ] } }) // or store.setState({ a: { b: [ { [ CLEAR_TAG ]: <anything> }, state.a.b[1] ] } })
-
-/* empties the value at state.a.b[0]; sets state.a.b = [{}, a.b[1]] using indexing (RECOMMENDED) */
-store.setState({ a: { b: { 0: CLEAR_TAG } } }) // or store.setState({ a: { b: { 0: { [ CLEAR_TAG ]: <anything> } } } })
-```
-
-<i id="delete-tag-usage"><b>@@DELETE:</b> (takes an array argument listing property keys to delete)</i>
-
-```jsx
-import { DELETE_TAG } from '@webkrafters/react-observable-context'; // DELETE_TAG = "@@DELETE"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10
-};
-
-store.setState({ [ DELETE_TAG ]: [ 'a' ] }) // removes state.a; sets state = {j: 10}
-
-store.setState({ a: { [ DELETE_TAG ]: [ 'b' ] } }) // removes state.a.b; sets state.a = {}
-
-/* removes state.a.b[0]; leaving state.a.b = [{ x: 17, y: 18, z: 19 }] */
-store.setState({ a: { b: { [ DELETE_TAG ]: [ 0 ] } } }) // or store.setState({ a: { b: { [ DELETE_TAG ]: [ -2 ] } } })
-
-/* removes `x` and `z` properties from state.a.b[1]; sets state.a.b = [{ x: 7, y: 8, z: 9 }, {y: 18}] */
-store.setState({ a: { b: [ state.a.b[ 0 ], { [ DELETE_TAG ]: [ 'x', 'z' ] } ] } })
-
-/* removes `x` and `z` properties from state.a.b[1]; sets state.a.b = [{ x: 7, y: 8, z: 9 }, {y: 18}] using indexing (RECOMMENDED) */
-store.setState({ a: { b: { 1: { [ DELETE_TAG ]: [ 'x', 'z' ] } } } })
-```
-
-<i id="move-tag-usage"><b>@@MOVE:</b> (takes an array argument listing: -/+fromIndex, -/+toIndex and optional +numItems?. numItems = 1 by default)</i>
-
-```jsx
-import { MOVE_TAG } from '@webkrafters/react-observable-context'; // MOVE_TAG = "@@MOVE"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10,
-  q: [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
-};
-
-store.setState({ a: { [ MOVE_TAG ]: [ 0, 1 ] } }) // assigning a '@@MOVE' command to a non-array property has no effect.
-
-/* moves state.a.b[0] into index 1; leaving state.a.b = [{ x: 17, y: 18, z: 19 }, { x: 7, y: 8, z: 9 }] */
-store.setState({ a: { b: { [ MOVE_TAG ]: [ 0, 1 ] } } }) // or store.setState({ a: { b: { [ MOVE_TAG ]: [ -2, -1 ] } } })
-
-/* moves state.q[4] - [7] into indexes 1 - 4; leaving state.q = [ 1, 5, 6, 7, 8, 2, 3, 4, 9 ] */
-store.setState({ a: { q: { [ MOVE_TAG ]: [ 4, 1, 4 ] } } }) // or store.setState({ a: { q: { [ MOVE_TAG ]: [ -5, -8, 4 ] } } })
-```
-
-<i id="push-tag-usage"><b>@@PUSH:</b> (takes an array argument listing new values to append)</i>
-
-```jsx
-import { PUSH_TAG } from '@webkrafters/react-observable-context'; // PUSH_TAG = "@@PUSH"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10
-};
-
-store.setState({ a: { [ PUSH_TAG ]: [{ n: 5 }] } }) // assigning a '@@PUSH' command to a non-array property has no effect.
-
-/* appends 2 new items into state.a.b; leaving state.a.b = [...state.a.b, { x: 27, y: 28, z: 29 }, { x: 37, y: 38, z: 39 }] */
-store.setState({ a: { b: { [ PUSH_TAG ]: [{ x: 27, y: 28, z: 29 }, { x: 37, y: 38, z: 39 }] } } })
-```
-
-<i id="replace-tag-usage"><b>@@REPLACE:</b> (takes an argument holding the replacement value)</i>
-
-```jsx
-import { REPLACE_TAG } from '@webkrafters/react-observable-context'; // REPLACE_TAG = "@@REPLACE"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10
-};
-
-store.setState({ [ REPLACE_TAG ]: { a: 'Demo', j: 17 } }) // rewrites state to { a: 'Demo', j: 17 };
-
-store.setState({ a: { [ REPLACE_TAG ]: { message: 'Testing...' } } }) // rewrites state.a to { message: 'Testing...' }
-
-/* rewrites state.a.b[1] to { x: 97, y: 98, z: 99 }; leaving state.a.b = [{ x: 7, y: 8, z: 9 }, { x: 97, y: 98, z: 99 }] */
-store.setState({ a: { b: [ state.a.b[ 0 ], { [ REPLACE_TAG ]: { x: 97, y: 98, z: 99 } } ] } })
-
-/* rewrites state.a.b[1] to { x: 97, y: 98, z: 99 }; leaving state.a.b = [{ x: 7, y: 8, z: 9 }, { x: 97, y: 98, z: 99 }] using indexing (RECOMMENDED) */
-store.setState({ a: { b: { 1: { [ REPLACE_TAG ]: { x: 97, y: 98, z: 99 } } } } })
-```
-
-<i id="set-tag-usage"><b>@@SET:</b> (takes an argument holding either the replacment value or a compute function returning the replacement value)</i>
-
-```jsx
-/*
- This tag is for handling edge cases only. Please use sparingly. In most cases, store.setState with or without any of the other tags is sufficient and most efficient.
- 
- This and the '@@REPLACE' tags are functionally equivalent when used with a replacement value argument.
- 
- Be aware that the compute function argument may be `undefined` for properties which do not yet exist in the state.
-*/
-
-import { SET_TAG } from '@webkrafters/react-observable-context'; // SET_TAG = "@@SET"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10
-};
-
-store.setState({ [ SET_TAG ]: currentValue => ({ ...currentValue, a: 'Demo', j: 17 }) }) // rewrites state to { ...state, a: 'Demo', j: 17 };
-
-store.setState({ a: { [ SET_TAG ]: currentValue => ({ ...currentValue, message: 'Testing...' }) } }) // rewrites state.a to { ...state, message: 'Testing...' }
-
-/* rewrites state.a.b[1] to { x: 97, y: 98, z: 99 }; leaving state.a.b = [{ x: 7, y: 8, z: 9 }, { x: 97, y: 98, z: 99 }] */
-store.setState({ a: { b: [ state.a.b[ 0 ], { [ SET_TAG ]: currentValue => ({ ...currentValue, x: 97, y: 98, z: 99 }) } ] } })
-
-/* rewrites state.a.b[1] to { x: 97, y: 98, z: 99 }; leaving state.a.b = [{ x: 7, y: 8, z: 9 }, { x: 97, y: 98, z: 99 }] using indexing (RECOMMENDED) */
-store.setState({ a: { b: { 1: { [ SET_TAG ]: currentValue => ({ ...currentValue, x: 97, y: 98, z: 99 }) } } } })
-```
-
-<i id="splice-tag-usage"><b>@@SPLICE:</b> (takes an array argument listing: -/+fromIndex, +deleteCount and optional ...newItems? newItems = ...[] by default)</i>
-
-```jsx
-import { SPLICE_TAG } from '@webkrafters/react-observable-context'; // SPLICE_TAG = "@@SPLICE"
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10,
-  q: [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
-};
-
-store.setState({ a: { [ SPLICE_TAG ]: [ 0, 1 ] } }) // assigning a '@@SPLICE' command to a non-array property has no effect.
-
-/* removes state.a.b[0]; leaving state.a.b = [{ x: 17, y: 18, z: 19 }] */
-store.setState({ a: { b: { [ SPLICE_TAG ]: [ 0, 1 ] } } }) // or store.setState({ a: { b: { [ SPLICE_TAG ]: [ -2, -1 ] } } })
-
-/* replaces state.q[4] - [7] with 2 items; leaving state.q = [ 1, 2, 3, 4, 33, 88, 9 ] */
-store.setState({ a: { q: { [ SPLICE_TAG ]: [ 4, 4, 33, 88 ] } } }) // or store.setState({ a: { q: { [ SPLICE_TAG ]: [ -5, 4, 33, 88 ] } } })
-```
-
-<h3 id="set-state-with-tags"><b><i>Combination Usage:</i></b></h3>
-
-These tags may be used in combination with the default usage where all top-level tag command results in property are sequentially merged into state followed by the merging of the rest of the property changes.
-
-<strong>Example:</strong>
-
-```jsx
-import * as ctx from '@webkrafters/react-observable-context';
-
-const state = {
-  a: { b: [{ x: 7, y: 8, z: 9 }, { x: 17, y: 18, z: 19 }] },
-  j: 10,
-  q: [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
-};
-
-store.setState({
-  a: {
-    b: {
-      /* evaluated 1st */ [ ctx.DELETE_TAG ]: [ 0 ], // upon deleting state.a.b[0] -> state.a.b[1] becomes the new state.a.b[0]
-      /* evaluated 3rd */ 0: ctx.CLEAR_TAG, // clear the new state.a.b[0]
-      /* evaluated 4th */ 2: { x: 47, y: 48, z: 49 }, // add new item at state.a.b[2],
-      /* evaluated 2md */ [ ctx.PUSH_TAG ]: [{ x: 107, y: 108, z: 109 }] // appends state.a.b[1]
-    }
-  },
-  j: { [ ctx.SET_TAG ]: currentValue => currentValue < 10 ? currentValue : 0 },
-  q: {
-    /* evaluated 1st */ [ ctx.MOVE_TAG ]: [ 5, 3, 2 ],
-    /* evaluated 2md */ 12: 11
-  }
-})
-// => {
-//  a: { b: [{}, { x: 107, y: 108, z: 109 }, { x: 47, y: 48, z: 49 }] },
-//  j: 0,
-//  q: [ 1, 2, 3, 6, 7, 4, 5, 8, 9, <empty>, <empty>, <empty>, 11 ]
-// }
-```
-
-<h1 id="changes">What's Changed?</h1>
-
-<table>
-	<thead><tr><th>v4.7.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td><a href="#store-setstate"><code>store.setState</code></a> can now accept an array of updates for gurranteed orderly processing.</td></tr>
-	</tbody>
-	<thead><tr><th>v4.6.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td><a href="#store-resetstate"><code>store.resetState</code></a> can now update reset current state even when initial state does not exist. Formerly, a resetState call on a non-existent initial state had no effect.</td></tr>
-	</tbody>
-	<thead><tr><th>v4.5.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td><a href="#setstate-tags">Tags</a> to update non-existent state slices are now recognized. <b>Previously,</b> they had resulted in no-ops. <b>From now on,</b> they will result in new default slices matching the result of the given tag operation.</td></tr>
-	</tbody>
-	<thead><tr><th>v4.4.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td>Returns <code>undefined</code> for selector map pointing at a non-existent state slice. <i>(Previously returned <code>null</code>)</i>.</td></tr>
-	</tbody>
-	<thead><tr><th>v4.3.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td>Added <code>React.Ref</code> forwarding to <code>connect</code>ed hoc client components.</td></tr>
-	</tbody>
-	<thead><tr><th>v4.1.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td>Added new setState <a href="#setstate-tags">tags</a> to facilitate state update operations.</td></tr>
-		<tr><td><b>2.</b></td><td>Added negative indexing capabilities.</td></tr>
-		<tr><td><b>3.</b></td><td>Exposing the store via its Context Provider <code>ref</code> attribute.</td></tr>
-		<tr><td><b>4.</b></td><td>Exporting crucial constants such as <b>@@STATE</b> and setState <a href="#setstate-tags">tags</a> such as <b>@@CLEAR</b>, <b>@@MOVE</b> etc.</td></tr>
-	</tbody>
-	<thead><tr><th>v4.0.0</th></tr></thead>
-	<tbody>
-		<tr><td><b>1.</b></td><td>Added the <a href="#connect"><code>connect</code></a> function to facilitate the encapsulated context-usage method.</td></tr>
-		<tr><td><b>2.</b></td><td>Added stronger support for deeply nested state structure. See <a href="#store-setstate"><code>store.setState</code></a></td></tr>
-		<tr><td><b>3.</b></td><td>Replaced the <a href="#usecontext"><code>useContext</code></a> watchedKeys array parameter with a <a href="#selector-map"><code>selectorMap</code></a> object.</td></tr>
-		<tr><td><b>4.</b></td><td>Removed the necessity for direct store subscription.</td></tr>
-		<tr><td><b>5.</b></td><td><a href="#store-resetstate"><code>store.resetState</code></a> can now take a <a href="#property-path">property path</a> array targeting which state slices to reset.</td></tr>
-		<tr><td><b>6.</b></td><td>Context provider accepts an optional <a href="#storage">storage</a> prop for memorizing initial state.</td></tr>
-		<tr><td><b>7.</b></td><td>Removed the need for <code>store.getState</code>. <code>store.data</code> now holds the state slices used at the client. Changes in any of the slices held by the <code>store.data</code> are automatically updated as they occur. The client is immediately notified of the update.</td></tr>
-	</tbody>
-</table>
+## Please see full documentation here:
+**[eagleeyejs.org](https://eagleeyejs.org)**
 
 # License
 

package/package.json

@@ -1,7 +1,8 @@
 {
+  "alias": "eagle eye context",
   "author": "Stephen Isienyi <stephen.isienyi@webkrafting.com>",
   "bugs": {
-    "url": "https://github.com/webKrafters/react-observable-context/issues"
+    "url": "https://github.com/webKrafters/eagleeye/issues"
   },
   "contributors": [
     "steveswork <stephen.isienyi@gmail.com> (https://github.com/steveswork)"
@@ -79,7 +80,7 @@
     "dist/constants.js",
     "dist/constants.d.ts"
   ],
-  "homepage": "https://github.com/webKrafters/react-observable-context#readme",
+  "homepage": "https://eagleeyejs.org",
   "jest": {
     "collectCoverageFrom": [
       "src/**/*.js"
@@ -96,6 +97,7 @@
   "keywords": [
     "connect",
     "context",
+    "eagle eye",
     "hoc",
     "hooks",
     "observable",
@@ -122,7 +124,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/webKrafters/react-observable-context.git"
+    "url": "git+https://github.com/webKrafters/eagleeye.git"
   },
   "scripts": {
     "build": "eslint --fix && rm -rf dist && babel src -d dist --ignore '**/*.test.js' && tsc",
@@ -133,5 +135,5 @@
     "test:watch": "eslint --fix && jest --updateSnapshot --watchAll"
   },
   "types": "dist/main/index.d.ts",
-  "version": "4.7.3"
+  "version": "4.7.5"
 }