@webkrafters/react-observable-context 4.6.2 → 4.7.1

package/README.md

@@ -24,9 +24,9 @@
 
 <ul>
 	<li> Update-friendly context.</li>
-	<li> A context bearing an observable consumer [store](#store).</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 ([clients](#client)) on context state changes.</li>
+	<li> Only re-renders subscribing components (<a href="#client">clients</a>) on context state changes.</li>
 	<li> Subscribing component decides which context state properties' changes to trigger its update.</li>
 </ul>
 
@@ -418,13 +418,13 @@ The `React.Observable.Context` context `store` is the client's portal into the c
 	<li>
 		<p style="margin: 0 0 0 10px">
 			<a href="#store-resetstate"><b>resetState:</b></a> 
-			<code style="margin-left: 5px">(propertyPaths?: Array<string>) => void // resets slices of state referenced by the property paths to their initial values.</code>
+			<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: PartialState<State>) => void // merges only new/changed state slices.</code>
+			<code style="margin-left: 5px">(changes: Changes&lt;State&gt;) => void // merges only new/changed state slices.</code>
 		</p>
 	</li>
 </ol>
@@ -437,14 +437,29 @@ The `React.Observable.Context` context `store` is the client's portal into the c
 <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>.</blockquote>
-New updates are merged into state by default. To overwrite 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({stateKey0: {...state.stateKey0, ...changes0}[, ...]});</code>
-<h3 id="indexing"><b><i><u>Indexing</u></i></b></h3>
-Existing array state property can be overridden with a new array.<br />
-Use the indexed object to update array content at indexes.<br />
-Indexed object recognizes negative indexing. See additional <a href="#neg-idx-tip">tip</a> below.<br />
+
+<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 `indexing`. 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
@@ -573,7 +588,7 @@ store.setState({ a: { [ PUSH_TAG ]: [{ n: 5 }] } }) // assigning a '@@PUSH' comm
 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 replacment value)</i>
+<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"
@@ -623,7 +638,7 @@ store.setState({ a: { b: [ state.a.b[ 0 ], { [ SET_TAG ]: currentValue => ({ ...
 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 argumenst listing: -/+fromIndex, +deleteCount and optional ...newItems? newItems = ...[] by default)</i>
+<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"
@@ -683,6 +698,10 @@ store.setState({
 <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>

package/dist/main/hooks/use-state-manager/index.js

@@ -25,7 +25,7 @@ var useStateManager = function useStateManager(initStateValue) {
     _useState4 = _slicedToArray(_useState3, 1),
     cache = _useState4[0];
   var select = (0, _react.useCallback)(cache.get.bind(cache), []);
-  var stateWatch = (0, _react.useCallback)(cache.watchSource.bind(cache), []);
+  var stateWatch = (0, _react.useCallback)(cache.atomize.bind(cache), []);
   var unlink = (0, _react.useCallback)(function (clientId) {
     return cache.unlinkClient(clientId);
   }, []);

package/dist/main/hooks/use-store/index.d.ts

@@ -4,7 +4,7 @@ export namespace deps {
 }
 export default useStore;
 export type IStorage<T extends import("../../../types").State> = import("../../../types").IStorage<T>;
-export type UpdatePayload<T extends import("../../../types").State> = import("../../../types").UpdatePayload<PartialState<T>>;
+export type Changes<T extends import("../../../types").State> = import("../../../types").Changes<T>;
 export type PartialState<T extends import("../../../types").State> = import('../../../types').PartialState<T>;
 export type Prehooks<T extends import("../../../types").State> = import("../../../types").Prehooks<T>;
 export type StoreInternal<T extends import("../../../types").State> = import("../../../types").StoreInternal<T>;

package/dist/main/index.js

@@ -116,8 +116,9 @@ var useContext = function useContext(context) {
     try {
       for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
         var path = _step2.value;
-        if (data[selectorMapInverse[path]] !== state[path]) {
-          data[selectorMapInverse[path]] = state[path];
+        var dPath = selectorMapInverse[path];
+        if (data[dPath] !== state[path]) {
+          data[dPath] = state[path];
           hasChanges = true;
         }
       }
@@ -134,7 +135,8 @@ var useContext = function useContext(context) {
   }, []);
   _react["default"].useEffect(function () {
     if ((0, _lodash["default"])(_renderKeys)) {
-      !(0, _lodash2["default"])({}, data) && setData({});
+      var _default = {};
+      !(0, _lodash2["default"])(_default, data) && setData(_default);
       return;
     }
     for (var selectorKey in data) {

package/dist/main/set-state/index.d.ts

@@ -25,8 +25,7 @@ export type HasRoot<K extends import("../../types").KeyType = string, T> = K ext
 };
 export type KeyType = import("../../types").KeyType;
 export type Listener<T extends import("../../types").State> = import("../../types").Listener<T>;
-export type UpdatePayload<T> = import("../../types").UpdatePayload<T>;
-export type PartialState<T extends import("../../types").State> = import("../../types").PartialState<T>;
+export type Changes<T> = import("../../types").Changes<T>;
 export type State = import("../../types").State;
 export type Stats = import("../../types").UpdateStats;
-declare function setState<T extends import("../../types").State>(state: T, changes: UpdatePayload<import("../../types").PartialState<T>>, onStateChange?: Listener<T>): void;
+declare function setState<T extends import("../../types").State>(state: T, changes: Changes<T>, onStateChange?: Listener<T>): void;

package/dist/main/set-state/index.js

@@ -11,6 +11,7 @@ function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "functio
 function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || _typeof(obj) !== "object" && typeof obj !== "function") { return { "default": obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj["default"] = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
 function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) { return typeof obj; } : function (obj) { return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }, _typeof(obj); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
 function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
 function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
 function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
@@ -182,11 +183,29 @@ function setState(state, changes, onStateChange) {
   var stats = {
     hasChanges: false
   };
-  var changeRequest = {
-    state: (0, _utils.clonedeep)(changes)
-  };
-  set({
-    state: state
-  }, changeRequest, stats);
+  if (!Array.isArray(changes)) {
+    set({
+      state: state
+    }, {
+      state: (0, _utils.clonedeep)(changes)
+    }, stats);
+  } else {
+    var _iterator = _createForOfIteratorHelper(changes),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var _cGroup = _step.value;
+        set({
+          state: state
+        }, {
+          state: (0, _utils.clonedeep)(_cGroup)
+        }, stats);
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+  }
   stats.hasChanges && (onStateChange === null || onStateChange === void 0 ? void 0 : onStateChange(changes));
 }

package/dist/model/accessor-cache/index.d.ts

@@ -3,10 +3,10 @@ export type Listener<T extends import("../../types").State> = import("../../type
 export type State = import("../../types").State;
 declare class AccessorCache<T extends import("../../types").State> {
     constructor(origin: T);
+    atomize(changes: import("../../types").Changes<T>): void;
     get(clientId: string, ...propertyPaths: string[]): {
         [propertyPaths: string]: Readonly<any>;
     };
     unlinkClient(clientId: string): void;
-    watchSource(changes: import("../../types").Changes<T>): void;
     #private;
 }

package/dist/model/accessor-cache/index.js

@@ -55,9 +55,50 @@ var AccessorCache = function () {
     _classPrivateFieldSet(this, _origin, origin);
   }
   _createClass(AccessorCache, [{
+    key: "atomize",
+    value: function atomize(originChanges) {
+      var accessors = _classPrivateFieldGet(this, _accessors);
+      var atoms = _classPrivateFieldGet(this, _atoms);
+      var updatedPaths = [];
+      for (var path in atoms) {
+        var _classPrivateMethodGe = _classPrivateMethodGet(this, _getOriginAt, _getOriginAt2).call(this, path),
+          exists = _classPrivateMethodGe.exists,
+          newAtomVal = _classPrivateMethodGe.value;
+        if (path !== _constants.FULL_STATE_SELECTOR && exists && (newAtomVal === null || newAtomVal === undefined)) {
+          if (!Array.isArray(originChanges)) {
+            if (!(0, _utils.getProperty)(originChanges, path).trail.length) {
+              continue;
+            }
+          } else {
+            var found = false;
+            for (var i = originChanges.length; i--;) {
+              if ((0, _utils.getProperty)(originChanges, "".concat(i, ".").concat(path)).trail.length) {
+                found = true;
+                break;
+              }
+            }
+            if (!found) {
+              continue;
+            }
+          }
+        }
+        if ((0, _lodash2["default"])(newAtomVal, atoms[path].value)) {
+          continue;
+        }
+        atoms[path].setValue(newAtomVal);
+        updatedPaths.push(path);
+      }
+      if (!updatedPaths.length) {
+        return;
+      }
+      for (var k in accessors) {
+        var _accessors$k$outdated;
+        (_accessors$k$outdated = accessors[k].outdatedPaths).push.apply(_accessors$k$outdated, updatedPaths);
+      }
+    }
+  }, {
     key: "get",
-    value:
-    function get(clientId) {
+    value: function get(clientId) {
       for (var _len = arguments.length, propertyPaths = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
         propertyPaths[_key - 1] = arguments[_key];
       }
@@ -96,30 +137,6 @@ var AccessorCache = function () {
         delete accessors[k];
       }
     }
-  }, {
-    key: "watchSource",
-    value: function watchSource(originChanges) {
-      var accessors = _classPrivateFieldGet(this, _accessors);
-      var atoms = _classPrivateFieldGet(this, _atoms);
-      var updatedPaths = [];
-      for (var path in atoms) {
-        var _classPrivateMethodGe = _classPrivateMethodGet(this, _getOriginAt, _getOriginAt2).call(this, path),
-          exists = _classPrivateMethodGe.exists,
-          newAtomVal = _classPrivateMethodGe.value;
-        if (path !== _constants.FULL_STATE_SELECTOR && exists && (newAtomVal === null || newAtomVal === 'undefined') && !(0, _utils.getProperty)(originChanges, path).trail.length || (0, _lodash2["default"])(newAtomVal, atoms[path].value)) {
-          continue;
-        }
-        atoms[path].setValue(newAtomVal);
-        updatedPaths.push(path);
-      }
-      if (!updatedPaths.length) {
-        return;
-      }
-      for (var k in accessors) {
-        var _accessors$k$outdated;
-        (_accessors$k$outdated = accessors[k].outdatedPaths).push.apply(_accessors$k$outdated, updatedPaths);
-      }
-    }
   }]);
   return AccessorCache;
 }();

package/dist/types.d.ts

@@ -53,10 +53,11 @@ export type Store<T extends State, SELECTOR_MAP extends BaseSelectorMap<T> = Bas
     resetState: (propertyPaths?: string[]) => void;
     setState: (changes: Changes<T>) => void;
 };
-export type Changes<T extends State> = UpdatePayload<PartialState<T>>;
+export type Changes<T extends State> = UpdatePayload<PartialState<T>> | UpdatePayloadArray<PartialState<T>>;
 export type UpdateStats = {
     hasChanges: boolean;
 };
+export type UpdatePayloadArray<T> = Array<UpdatePayload<T>>;
 export type UpdatePayload<T> = "@@CLEAR" | T | ClearCommand | DeleteCommand<T> | MoveCommand | PushCommand | ReplaceCommand | SetCommand<T> | SpliceCommand | { [K in keyof T]?: UpdatePayload<T[K]>; };
 export type ClearCommand = {
     "@@CLEAR": any;

package/dist/utils/index.d.ts

@@ -5,6 +5,8 @@ export function mapPathsToObject<T extends {
     [x: string]: any;
 }>(source: T, propertyPaths: Array<string>, transform?: Tranform): { [K in keyof T]?: any; };
 export function clonedeep<T, R>(value: T): R;
-export const getProperty: any;
+export const getProperty: typeof get;
 export const stringToDotPath: (path: string) => string;
-export type Tranform = (property: any) => T;
+export type Tranform<T = any> = (property: PropertyInfo) => T;
+export type PropertyInfo = import("@webkrafters/get-property").PropertyInfo;
+import get from "@webkrafters/get-property";

package/package.json

@@ -7,7 +7,7 @@
     "steveswork <stephen.isienyi@gmail.com> (https://github.com/steveswork)"
   ],
   "dependencies": {
-    "@webkrafters/get-property": "^1.1.1",
+    "@webkrafters/get-property": "^1.1.2",
     "lodash.clonedeepwith": "^4.5.0",
     "lodash.isboolean": "^3.0.3",
     "lodash.isempty": "^4.4.0",
@@ -133,5 +133,5 @@
     "test:watch": "eslint --fix && jest --updateSnapshot --watchAll"
   },
   "types": "dist/main/index.d.ts",
-  "version": "4.6.2"
+  "version": "4.7.1"
 }