@webkrafters/react-observable-context 1.1.4 → 2.0.0

package/README.md

@@ -12,13 +12,17 @@ npm install --save @webkrafters/react-observable-context
 
 ## API
 
-The React-Observable-Context package exports only **2** modules namely: the **createContext** method and the **Provider** component.
+The React-Observable-Context package exports **3** modules namely: the **createContext** method, the **useContext** hook and the **Provider** component.
 
-`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 funtion returning a store-bearing context. Pass the context to the React::useContext() parameter to obtain the context's `store`.
 
-The `Provider` can immediately be used as-is anywhere the React-Observable-Context is required. It accepts **3** props and the customary Provider `children` prop. Supply the context to its `context` prop; the initial state to the customary Provider `value` prop; and the optional `prehooks` prop <i>(discussed in the prehooks section below)</i>.
+* **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 names to watch. Change in any of the referenced properties automatically triggers a render of the component calling this hook.  
 
-<i><u>Note:</u></i> the Provider `context` prop is not updateable. Once set, all further updates to this prop are not recorded.
+* **Provider** can immediately be used as-is anywhere the React-Observable-Context is required. It accepts **3** props and the customary Provider `children` prop. Supply the context to its `context` prop; the initial state to the customary Provider `value` prop; and the optional `prehooks` prop <i>(discussed in the prehooks section below)</i>.
+
+***<u>Note:</u>*** the Provider `context` prop is not updateable. Once set, all further updates to this prop are not recorded.
+
+### The Store
 
 The context's `store` exposes **4** methods for interacting with the context's internal state namely:
 
@@ -38,7 +42,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 * **setState**: (newChanges: PartialState\<State\>) => boolean
 
-***usecase***: 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 OR `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. 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.
 
 ## Usage
 
@@ -50,7 +54,9 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 <i><u>reset.js</u></i>
 
-    import React, { useContext } from 'react';
+    import React, { useEffect } from 'react';
+
+	import { useContext } from '@webkrafters/react-observable-context';
 
 	import ObservableContext from './context';
 	
@@ -68,22 +74,19 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 <i><u>tally-display.js</u></i>
 
-    import React, { useContext, useEffect, useState } from 'react';
+    import React, { useEffect } from 'react';
+
+	import { useContext } from '@webkrafters/react-observable-context';
 
 	import ObservableContext from './context';
 
 	import Reset from './reset';
     
-    const TallyDisplay = () => {
+    const CONTEXT_KEYS = [ 'color', 'price', 'type' ];
     
-	    const { getState, subscribe } = useContext( ObservableContext );
+    const TallyDisplay = () => {
     
-	    const [ , tripRender ] = useState( false );
-	    
-	    useEffect(() => subscribe( newValue => {
-		    [ 'color', 'price', 'type' ].some( k => k in newValue ) &&
-		    tripRender( s => !s );
-	    }), []);
+	    const { getState } = useContext( ObservableContext, CONTEXT_KEYS );
 	    
 	    useEffect(() => console.log( 'TallyDisplay component rendered.....' ));
     
@@ -108,7 +111,9 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 <i><u>editor.js</u></i>
 
-    import React, { useCallback, useContext, useEffect, useRef } from 'react';
+    import React, { useCallback, useEffect, useRef } from 'react';
+
+	import { useContext } from '@webkrafters/react-observable-context';
 
 	import ObservableContext from './context';
     
@@ -152,7 +157,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 				    { ' ' }
 				    <button onClick={ updateType }>update type</button>
 			    </div>
-		    </fieldset>    
+		    </fieldset>
 	    );
 	};
     Editor.displayName = 'Editor';
@@ -161,20 +166,17 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 <i><u>product-description.js</u></i>
 
-    import React, { useContext, useEffect, useState } from 'react';
+    import React, { useEffect } from 'react';
+
+	import { useContext } from '@webkrafters/react-observable-context';
 
 	import ObservableContext from './context';
+
+	const CONTEXT_KEYS = [ 'color', 'type' ];
     
     const ProductDescription = () => {
     
-	    const store = useContext( ObservableContext );
-	    
-	    const [ , tripRender ] = useState( false );
-	    
-	    useEffect(() => store.subscribe( newValue => {
-		    ( 'color' in newValue || 'type' in newValue ) &&
-		    tripRender( s => !s );
-	    } ), []);
+	    const store = useContext( ObservableContext, CONTEXT_KEYS );
 	    
 	    useEffect(() => console.log( 'ProductDescription component rendered.....' ));
 	    
@@ -193,25 +195,23 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 
 <i><u>price-sticker.js</u></i>
 
-    import React, { useContext, useEffect, useState } from 'react';
+    import React, { useEffect } from 'react';
+
+	import { useContext } from '@webkrafters/react-observable-context';
 
 	import ObservableContext from './context';
+
+	const CONTEXT_KEYS  = [ 'price' ];
     
     const PriceSticker = () => {
     
-	    const store = useContext( ObservableContext );
-	    
-	    const [ price, setPrice ] = useState(() => store.getState( s => s.price ));
-    
-	    useEffect(() => store.subscribe( newValue => {
-		    'price' in newValue && setPrice( newValue.price );
-	    } ), []);
+	    const { getState } = useContext( ObservableContext, CONTEXT_KEYS );
 	    
 	    useEffect(() => console.log( 'PriceSticker component rendered.....' ));
 	    
 	    return (
 		    <div style={{ fontSize: 36, fontWeight: 800 }}>
-			    ${ price.toFixed( 2 ) }
+			    ${ getState( s  =>  s.price ).toFixed( 2 ) }
 		    </div>
 	    );
     };
@@ -251,11 +251,11 @@ The context's store update operation adheres to **2** user supplied prehooks whe
 			    <div style={{ marginBottom: 10 }}>
 				    <label>$ <input onKeyUp={ overridePricing } placeholder="override price here..."/></label>
 			    </div>
-			<Provider
-				context={ ObservableContext }
-				prehooks={ prehooks }
-				value={ state }
-			>
+				<Provider
+					context={ ObservableContext }
+					prehooks={ prehooks }
+					value={ state }
+				>
 				    <div style={{
 					    borderBottom: '1px solid #333',
 					    marginBottom: 10,
@@ -286,7 +286,7 @@ The context's store update operation adheres to **2** user supplied prehooks whe
     
 	    const updateType = useCallback( e => setProductType( e.target.value ), [] );
 		
-		const prehooks = React.useMemo(() => ({
+		const prehooks = useMemo(() => ({
 			resetState: ( ...args ) => {
 				console.log( 'resetting state with >>>> ', JSON.stringify( args ) );
 				return true;

package/dist/index.d.ts

@@ -1,24 +1,25 @@
 export class UsageError extends Error {
 }
-export function createContext<T_1 extends State>(): import("react").Context<Store<T_1>>;
+export function createContext<T_1 extends State>(): React.Context<Store<T_2>>;
+export function useContext<T_1 extends State>(context: React.Context<Store<T_2>>, watchedKeys?: (keyof T_1)[]): Store<T_1>;
 /**
  * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
  *
- * @type {import("react").FC<{
- * 		children?: import("react").ReactNode,
+ * @type {React.FC<{
+ * 		children?: React.ReactNode,
  * 		context: ObservableContext<T>,
  * 		prehooks?: Prehooks<T>
- * 		value: T
+ * 		value: PartialState<T>
  * }>}
  * @template {State} T
  */
-export const Provider: import("react").FC<{
-    children?: import("react").ReactNode;
-    context: ObservableContext<T>;
+export const Provider: React.FC<{
+    children?: React.ReactNode;
+    context: React.Context<Store<T_1>>;
     prehooks?: Prehooks<T>;
-    value: T;
+    value: PartialState<T>;
 }>;
-export type ObservableContext<T_1 extends State> = import("react").Context<Store<T>>;
+export type ObservableContext<T_1 extends State> = React.Context<Store<T>>;
 export type OptionalTask<F = void> = F extends void ? () => never : F;
 export type Listener<T_1 extends State> = (newValue: PartialState<T>, oldValue: PartialState<T>) => void;
 export type State = {

package/dist/index.js

@@ -4,10 +4,11 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.createContext = exports.UsageError = exports.Provider = void 0;
+exports.useContext = exports.createContext = exports.UsageError = exports.Provider = void 0;
 var _react = _interopRequireWildcard(require("react"));
 var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
-var _lodash2 = _interopRequireDefault(require("lodash.isempty"));
+var _lodash2 = _interopRequireDefault(require("lodash.has"));
+var _lodash3 = _interopRequireDefault(require("lodash.isempty"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
 function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
 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; }
@@ -67,12 +68,45 @@ var createContext = function createContext() {
   });
 };
 
+/**
+ * Actively monitors the store and triggers component re-render if any of the watched keys in the state objects changes
+ *
+ * @param {ObservableContext<T>} context
+ * @param {Array<keyof T>} [watchedKeys = []] Names of state properties to watch. A change in any of the referenced properties results in this component render.
+ * @returns {Store<T>}
+ * @template {State} T
+ */
+exports.createContext = createContext;
+var useContext = function useContext(context) {
+  var watchedKeys = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+  var store = (0, _react.useContext)(context);
+  var _useState = (0, _react.useState)(false),
+    _useState2 = _slicedToArray(_useState, 2),
+    tripRender = _useState2[1];
+  var watched = (0, _react.useMemo)(function () {
+    return Array.isArray(watchedKeys) ? Array.from(new Set(watchedKeys)) : [];
+  }, [watchedKeys]);
+  (0, _react.useEffect)(function () {
+    if (!watched.length) {
+      return;
+    }
+    return store.subscribe(function (newChanges) {
+      watched.some(function (w) {
+        return (0, _lodash2["default"])(newChanges, w);
+      }) && tripRender(function (s) {
+        return !s;
+      });
+    });
+  }, [watched]);
+  return store;
+};
+
 /**
  * @readonly
  * @type {Prehooks<T>}
  * @template {State} T
  */
-exports.createContext = createContext;
+exports.useContext = useContext;
 var defaultPrehooks = Object.freeze({});
 
 /**
@@ -94,7 +128,7 @@ var _setState = function _setState(state, newState, onStateChange) {
     state[k] = newState[k];
     newChanges[k] = newState[k];
   }
-  !(0, _lodash2["default"])(newChanges) && onStateChange(newChanges, replacedValue);
+  !(0, _lodash3["default"])(newChanges) && onStateChange(newChanges, replacedValue);
 };
 
 /**
@@ -112,11 +146,11 @@ var usePrehooksRef = function usePrehooksRef(prehooks) {
 /**
  * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
  *
- * @type {import("react").FC<{
- * 		children?: import("react").ReactNode,
+ * @type {React.FC<{
+ * 		children?: React.ReactNode,
  * 		context: ObservableContext<T>,
  * 		prehooks?: Prehooks<T>
- * 		value: T
+ * 		value: PartialState<T>
  * }>}
  * @template {State} T
  */
@@ -131,21 +165,21 @@ var Provider = function Provider(_ref) {
   var initialState = (0, _react.useRef)(value);
 
   /** @type {[Set<Listener<T>>, Function]} */
-  var _useState = (0, _react.useState)(function () {
+  var _useState3 = (0, _react.useState)(function () {
       return new Set();
     }),
-    _useState2 = _slicedToArray(_useState, 1),
-    listeners = _useState2[0];
+    _useState4 = _slicedToArray(_useState3, 1),
+    listeners = _useState4[0];
   /** @type {[T, Function]} */
-  var _useState3 = (0, _react.useState)(function () {
+  var _useState5 = (0, _react.useState)(function () {
       return (0, _lodash["default"])(value);
     }),
-    _useState4 = _slicedToArray(_useState3, 1),
-    state = _useState4[0];
-  /** @type {ObservableContext<T>} */
-  var _useState5 = (0, _react.useState)(context),
     _useState6 = _slicedToArray(_useState5, 1),
-    StoreContext = _useState6[0];
+    state = _useState6[0];
+  /** @type {ObservableContext<T>} */
+  var _useState7 = (0, _react.useState)(context),
+    _useState8 = _slicedToArray(_useState7, 1),
+    StoreContext = _useState8[0];
 
   /** @type {Listener<T>} */
   var onChange = function onChange(newValue, oldValue) {
@@ -187,7 +221,7 @@ var Provider = function Provider(_ref) {
   }, [value]);
 
   /** @type {[Store<T>, Function]} */
-  var _useState7 = (0, _react.useState)(function () {
+  var _useState9 = (0, _react.useState)(function () {
       return {
         getState: getState,
         resetState: resetState,
@@ -195,8 +229,8 @@ var Provider = function Provider(_ref) {
         subscribe: subscribe
       };
     }),
-    _useState8 = _slicedToArray(_useState7, 1),
-    store = _useState8[0];
+    _useState10 = _slicedToArray(_useState9, 1),
+    store = _useState10[0];
   return /*#__PURE__*/_react["default"].createElement(StoreContext.Provider, {
     value: store
   }, children);
@@ -205,7 +239,7 @@ exports.Provider = Provider;
 Provider.displayName = 'ObservableContext.Provider';
 
 /**
- * @typedef {import("react").Context<Store<T>>} ObservableContext
+ * @typedef {React.Context<Store<T>>} ObservableContext
  * @template {State} T
  */
 

package/package.json

@@ -1,79 +1,80 @@
-{
-  "author": "Stephen Isienyi <stephen.isienyi@webkrafting.com>",
-  "bugs": {
-    "url": "https://github.com/steveswork/react-observable-context/issues"
-  },
-  "contributors": [
-    "steveswork <stephen.isienyi@webkrafting.com> (https://github.com/steveswork)"
-  ],
-  "dependencies": {
-    "@types/react": "^18.0.17",
-    "lodash.clonedeep": "^4.5.0",
-    "lodash.isempty": "^4.4.0",
-    "react": "^18.2.0"
-  },
-  "description": "Observable react context - prevents an automatic total component tree tear-down and re-rendering during context updates.",
-  "devDependencies": {
-    "@babel/cli": "^7.17.0",
-    "@babel/core": "^7.12.10",
-    "@babel/node": "^7.12.10",
-    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.18.6",
-    "@babel/plugin-transform-runtime": "^7.17.0",
-    "@babel/preset-env": "^7.12.11",
-    "@babel/preset-react": "^7.18.6",
-    "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^13.4.0",
-    "@testing-library/user-event": "^14.4.3",
-    "@types/jest-cli": "^24.3.0",
-    "babel-jest": "^26.6.3",
-    "babel-loader": "^8.2.5",
-    "eslint": "^7.15.0",
-    "eslint-config-standard": "^16.0.2",
-    "eslint-plugin-import": "^2.22.1",
-    "eslint-plugin-jest": "^24.1.3",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^4.2.1",
-    "eslint-plugin-react": "^7.31.11",
-    "eslint-plugin-standard": "^5.0.0",
-    "jest-cli": "^26.6.3",
-    "react-dom": "^18.2.0",
-    "react-performance-testing": "^2.0.0",
-    "typescript": "^4.8.2"
-  },
-  "files": [
-    "dist/index.js",
-    "dist/index.d.ts",
-    "index",
-    "package.json"
-  ],
-  "homepage": "https://github.com/steveswork/react-observable-context#readme",
-  "jest": {
-    "transform": {
-      "\\.[jt]sx?$": "babel-jest"
-    }
-  },
-  "keywords": [
-    "context",
-    "react-hooks",
-    "react-context",
-    "react",
-    "useContext"
-  ],
-  "license": "MIT",
-  "main": "index.js",
-  "name": "@webkrafters/react-observable-context",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/steveswork/react-observable-context.git"
-  },
-  "scripts": {
-    "build": "eslint --fix && rm -rf dist && babel src -d dist && npx -p typescript tsc",
-    "test": "eslint --fix && jest",
-    "test:watch": "eslint --fix && jest --watchAll"
-  },
-  "types": "dist/index.d.ts",
-  "version": "1.1.4"
-}
+{
+  "author": "Stephen Isienyi <stephen.isienyi@webkrafting.com>",
+  "bugs": {
+    "url": "https://github.com/steveswork/react-observable-context/issues"
+  },
+  "contributors": [
+    "steveswork <stephen.isienyi@webkrafting.com> (https://github.com/steveswork)"
+  ],
+  "dependencies": {
+    "@types/react": "^18.0.17",
+    "lodash.clonedeep": "^4.5.0",
+    "lodash.has": "^4.5.2",
+    "lodash.isempty": "^4.4.0",
+    "react": "^18.2.0"
+  },
+  "description": "Observable react context - prevents an automatic total component tree tear-down and re-rendering during context updates.",
+  "devDependencies": {
+    "@babel/cli": "^7.17.0",
+    "@babel/core": "^7.12.10",
+    "@babel/node": "^7.12.10",
+    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.18.6",
+    "@babel/plugin-transform-runtime": "^7.17.0",
+    "@babel/preset-env": "^7.12.11",
+    "@babel/preset-react": "^7.18.6",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^13.4.0",
+    "@testing-library/user-event": "^14.4.3",
+    "@types/jest-cli": "^24.3.0",
+    "babel-jest": "^26.6.3",
+    "babel-loader": "^8.2.5",
+    "eslint": "^7.15.0",
+    "eslint-config-standard": "^16.0.2",
+    "eslint-plugin-import": "^2.22.1",
+    "eslint-plugin-jest": "^24.1.3",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^4.2.1",
+    "eslint-plugin-react": "^7.31.11",
+    "eslint-plugin-standard": "^5.0.0",
+    "jest-cli": "^26.6.3",
+    "react-dom": "^18.2.0",
+    "react-performance-testing": "^2.0.0",
+    "typescript": "^4.8.2"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "index",
+    "package.json"
+  ],
+  "homepage": "https://github.com/steveswork/react-observable-context#readme",
+  "jest": {
+    "transform": {
+      "\\.[jt]sx?$": "babel-jest"
+    }
+  },
+  "keywords": [
+    "context",
+    "react-hooks",
+    "react-context",
+    "react",
+    "useContext"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "name": "@webkrafters/react-observable-context",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steveswork/react-observable-context.git"
+  },
+  "scripts": {
+    "build": "eslint --fix && rm -rf dist && babel src -d dist && npx -p typescript tsc",
+    "test": "eslint --fix && jest",
+    "test:watch": "eslint --fix && jest --watchAll"
+  },
+  "types": "dist/index.d.ts",
+  "version": "2.0.0"
+}