@webkrafters/react-observable-context 1.0.0 → 1.1.1

package/README.md

@@ -14,7 +14,9 @@ The React-Observable-Context package exports only **2** modules namely: the **cr
 
 `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. Supply the context to its `context` prop and the initial state to its `value` prop as is customary to React::Provider.
+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` props <i>(discussed in the prehooks section below)</i>.
+
+<i><u>Note:</u></i> the Provider `context` prop is not updateable. Once set, all further updates to this prop are ignored.
 
 The context's `store` exposes **4** methods for interacting with the context's internal state namely:
 
@@ -26,6 +28,16 @@ The context's `store` exposes **4** methods for interacting with the context's i
 
 * **subscribe**: (listener: (newValue: PartialState\<State\>, oldValue: PartialState\<State\>) => void) => ***UnsubscribeFunction***
 
+### Prehooks
+
+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.
+
+* **resetState**: (state: {current: State, original: State}) => boolean
+
+* **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.
+
 ## Usage
 
 <i><u>context.js</u></i>
@@ -34,33 +46,58 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	const ObservableContext = createContext();
     export default ObservableContext;
 
+<i><u>reset.js</u></i>
+
+    import React, { useContext } from 'react';
+
+	import ObservableContext from './context';
+	
+	const Reset = () => {
+		
+		const { resetState } = useContext( ObservableContext );
+		
+		useEffect(() => console.log( 'Reset component rendered.....' ));
+		
+		return ( <button onClick={ resetState }>reset context</button> );
+	};
+	Reset.displayName = 'Reset';
+
+    export default Reset;
+
 <i><u>tally-display.js</u></i>
 
     import React, { useContext, useEffect, useState } from 'react';
 
 	import ObservableContext from './context';
+
+	import Reset from './reset';
     
     const TallyDisplay = () => {
     
 	    const { getState, subscribe } = useContext( ObservableContext );
     
-	    const [ , setUpdateTs ] = useState();
+	    const [ , tripRender ] = useState( false );
 	    
 	    useEffect(() => subscribe( newValue => {
 		    [ 'color', 'price', 'type' ].some( k => k in newValue ) &&
-		    setUpdateTs( Date.now() );
+		    tripRender( s => !s );
 	    }), []);
 	    
 	    useEffect(() => console.log( 'TallyDisplay component rendered.....' ));
     
 	    return (
-		    <table>
-			    <tbody>
-				    <tr><td><label>Type:</label></td><td>{ getState( s => s.type ) }</td></tr>
-				    <tr><td><label>Color:</label></td><td>{ getState( s => s.color ) }</td></tr>
-				    <tr><td><label>Price:</label></td><td>{ getState( s => s.price ).toFixed( 2 ) }</td></tr>
-			    </tbody>
-			</table>
+			<div>
+				<table>
+					<tbody>
+						<tr><td><label>Type:</label></td><td>{ getState( s => s.type ) }</td></tr>
+						<tr><td><label>Color:</label></td><td>{ getState( s => s.color ) }</td></tr>
+						<tr><td><label>Price:</label></td><td>{ getState( s => s.price ).toFixed( 2 ) }</td></tr>
+					</tbody>
+				</table>
+				<div style={{ textAlign: 'right' }}>
+					<Reset />
+				</div>
+			</div>
 		);
     };
     TallyDisplay.displayName = 'TallyDisplay';
@@ -130,11 +167,11 @@ The context's `store` exposes **4** methods for interacting with the context's i
     
 	    const store = useContext( ObservableContext );
 	    
-	    const [ , setUpdateTs ] = useState();
+	    const [ , tripRender ] = useState( false );
 	    
 	    useEffect(() => store.subscribe( newValue => {
 		    ( 'color' in newValue || 'type' in newValue ) &&
-		    setUpdateTs( Date.now() );
+		    tripRender( s => !s );
 	    } ), []);
 	    
 	    useEffect(() => console.log( 'ProductDescription component rendered.....' ));
@@ -192,7 +229,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
     import ProductDescription from './product-description';
     import TallyDisplay from './tally-display';
     
-    const Product = ({ type }) => {
+    const Product = ({ prehooks = undefined, type }) => {
 	    
 	    const [ state, setState ] = useState(() => ({
 		    color: 'Burgundy',
@@ -212,7 +249,11 @@ The context's `store` exposes **4** methods for interacting with the context's i
 			    <div style={{ marginBottom: 10 }}>
 				    <label>$ <input onKeyUp={ overridePricing } placeholder="override price here..."/></label>
 			    </div>
-			    <Provider context={ ObservableContext } value={ state }>
+			<Provider
+				context={ ObservableContext }
+				prehooks={ prehooks }
+				value={ state }
+			>
 				    <div style={{
 					    borderBottom: '1px solid #333',
 					    marginBottom: 10,
@@ -233,7 +274,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 
 <i><u>app.js</u></i>
 
-    import React, { useCallback, useState } from 'react';
+    import React, { useCallback, useMemo, useState } from 'react';
     
     import Product from './product';
     
@@ -242,6 +283,17 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	    const [ productType, setProductType ] = useState( 'Calculator' );
     
 	    const updateType = useCallback( e => setProductType( e.target.value ), [] );
+		
+		const prehooks = React.useMemo(() => ({
+			resetState: ( ...args ) => {
+				console.log( 'resetting state with >>>> ', JSON.stringify( args ) );
+				return true;
+			},
+			setState: ( ...args ) => {
+				console.log( 'setting state with >>>> ', JSON.stringify( args ) );
+				return true;
+			}
+		}), []);
     
 	    return (
 		    <div className="App">
@@ -250,10 +302,9 @@ The context's `store` exposes **4** methods for interacting with the context's i
 			    <div style={{ marginBottom: 10 }}>
 				    <label>Type: <input onKeyUp={ updateType } placeholder="override product type here..." /></label>
 			    </div>
-			    <Product type={ productType } />
+			    <Product prehooks={ prehooks } type={ productType } />
 		    </div>
 	    );
-	    
     };
     App.displayName = 'App';
     

package/dist/index.d.ts

@@ -1,30 +1,41 @@
 export class UsageError extends Error {
 }
-export function createContext<T extends State>(): import("react").Context<Store<T>>;
+export function createContext<T_1 extends State>(): import("react").Context<Store<T_1>>;
 /**
+ * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
+ *
  * @type {import("react").FC<{
  * 		children?: import("react").ReactNode,
  * 		context: ObservableContext<T>,
+ * 		prehooks?: Prehooks<T>
  * 		value: T
  * }>}
  * @template {State} T
  */
 export const Provider: import("react").FC<{
     children?: import("react").ReactNode;
-    context: import("react").Context<Store<T>>;
+    context: ObservableContext<T>;
+    prehooks?: Prehooks<T>;
     value: T;
 }>;
-export type ObservableContext<T extends State> = import("react").Context<Store<T>>;
+export type ObservableContext<T_1 extends State> = import("react").Context<Store<T>>;
 export type OptionalTask<F = void> = F extends void ? () => never : F;
-export type Listener<T extends State> = (newValue: PartialState<T>, oldValue: PartialState<T>) => void;
+export type Listener<T_1 extends State> = (newValue: PartialState<T>, oldValue: PartialState<T>) => void;
 export type State = {
     [x: string]: any;
 };
-export type PartialState<T extends State> = {
+export type PartialState<T_1 extends State> = {
     [x: string]: any;
 } & { [K in keyof T]?: T[K]; };
-export type Selector<T extends State> = (state: T) => any;
-export type Store<T extends State> = {
+export type Selector<T_1 extends State> = (state: T) => any;
+export type Prehooks<T_1 extends State> = {
+    resetState?: (state: {
+        current: T;
+        original: T;
+    }) => boolean;
+    setState?: (newChanges: PartialState<T>) => boolean;
+};
+export type Store<T_1 extends State> = {
     getState: (selector?: Selector<T>) => any;
     resetState: OptionalTask<VoidFunction>;
     setState: (changes: PartialState<T>) => void;

package/dist/index.js

@@ -6,7 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.createContext = exports.UsageError = exports.Provider = void 0;
 var _react = _interopRequireWildcard(require("react"));
-var _lodash = _interopRequireDefault(require("lodash.isempty"));
+var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
+var _lodash2 = _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; }
@@ -66,61 +67,96 @@ var createContext = function createContext() {
 };
 
 /**
+ * @readonly
+ * @type {Prehooks<T>}
+ * @template {State} T
+ */
+exports.createContext = createContext;
+var defaultPrehooks = Object.freeze({});
+
+/**
+ * @param {T} state
+ * @param {PartialState<T>} newState
+ * @param {Listener<T>} onStateChange
+ * @template {State} T
+ */
+var _setState = function _setState(state, newState, onStateChange) {
+  /** @type {PartialState<T>} */
+  var newChanges = {};
+  /** @type {PartialState<T>} */
+  var replacedValue = {};
+  for (var k in newState) {
+    if (state[k] === newState[k]) {
+      continue;
+    }
+    replacedValue[k] = state[k];
+    state[k] = newState[k];
+    newChanges[k] = newState[k];
+  }
+  !(0, _lodash2["default"])(newChanges) && onStateChange(newChanges, replacedValue);
+};
+
+/**
+ * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
+ *
  * @type {import("react").FC<{
  * 		children?: import("react").ReactNode,
  * 		context: ObservableContext<T>,
+ * 		prehooks?: Prehooks<T>
  * 		value: T
  * }>}
  * @template {State} T
  */
-exports.createContext = createContext;
 var Provider = function Provider(_ref) {
   var _ref$children = _ref.children,
     children = _ref$children === void 0 ? null : _ref$children,
     context = _ref.context,
+    _ref$prehooks = _ref.prehooks,
+    prehooks = _ref$prehooks === void 0 ? defaultPrehooks : _ref$prehooks,
     value = _ref.value;
-  var valueRef = (0, _react.useRef)(value);
-  /** @type {ObservableContext<T>} */
-  var _useState = (0, _react.useState)(context),
+  var prehooksRef = (0, _react.useRef)(prehooks);
+  var initialState = (0, _react.useRef)(value);
+
+  /** @type {[T, Function]} */
+  var _useState = (0, _react.useState)(function () {
+      return (0, _lodash["default"])(value);
+    }),
     _useState2 = _slicedToArray(_useState, 1),
-    StoreContext = _useState2[0];
+    state = _useState2[0];
   /** @type {[Set<Listener<T>>, Function]} */
   var _useState3 = (0, _react.useState)(function () {
       return new Set();
     }),
     _useState4 = _slicedToArray(_useState3, 1),
     listeners = _useState4[0];
+
   /** @type {Listener<T>} */
   var onChange = function onChange(newValue, oldValue) {
     return listeners.forEach(function (listener) {
       return listener(newValue, oldValue);
     });
   };
+
   /** @type {Store<T>["getState"]} */
   var getState = (0, _react.useCallback)(function () {
     var selector = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : defaultSelector;
-    return selector(valueRef.current);
+    return selector(state);
   }, []);
+
   /** @type {Store<T>["resetState"]} */
   var resetState = (0, _react.useCallback)(function () {
-    return setState(value);
+    var original = (0, _lodash["default"])(initialState.current);
+    (!('resetState' in prehooksRef.current) || prehooksRef.current.resetState({
+      current: (0, _lodash["default"])(state),
+      original: original
+    })) && _setState(state, original, onChange);
   }, []);
+
   /** @type {Store<T>["setState"]} */
   var setState = (0, _react.useCallback)(function (changes) {
-    /** @type {PartialState<T>} */
-    var newChanges = {};
-    /** @type {PartialState<T>} */
-    var replacedValue = {};
-    for (var k in changes) {
-      if (valueRef.current[k] === changes[k]) {
-        continue;
-      }
-      replacedValue[k] = valueRef.current[k];
-      valueRef.current[k] = changes[k];
-      newChanges[k] = changes[k];
-    }
-    !(0, _lodash["default"])(newChanges) && onChange(newChanges, replacedValue);
+    (!('setState' in prehooksRef.current) || prehooksRef.current.setState(changes)) && _setState(state, changes, onChange);
   }, []);
+
   /** @type {Store<T>["subscribe"]} */
   var subscribe = (0, _react.useCallback)(function (listener) {
     listeners.add(listener);
@@ -129,9 +165,13 @@ var Provider = function Provider(_ref) {
     };
   }, []);
   (0, _react.useEffect)(function () {
-    return setState(value);
+    return setState((0, _lodash["default"])(value));
   }, [value]);
+  (0, _react.useEffect)(function () {
+    prehooksRef.current = prehooks;
+  }, [prehooks]);
   /** @type {[Store<T>, Function]} */
+
   var _useState5 = (0, _react.useState)(function () {
       return {
         getState: getState,
@@ -142,6 +182,10 @@ var Provider = function Provider(_ref) {
     }),
     _useState6 = _slicedToArray(_useState5, 1),
     store = _useState6[0];
+  /** @type {ObservableContext<T>} */
+  var _useState7 = (0, _react.useState)(context),
+    _useState8 = _slicedToArray(_useState7, 1),
+    StoreContext = _useState8[0];
   return /*#__PURE__*/_react["default"].createElement(StoreContext.Provider, {
     value: store
   }, children);
@@ -176,6 +220,14 @@ Provider.displayName = 'ObservableContext.Provider';
  * @template {State} T
  */
 
+/**
+ * @typedef {{
+ * 		resetState?: (state: { current: T, original: T}) => boolean,
+ * 		setState?: (newChanges: PartialState<T>) => boolean
+ * }} Prehooks
+ * @template {State} T
+ */
+
 /**
  * @typedef {{
  *   getState: OptionalTask<(selector?: Selector<T>) => *>,

package/package.json

@@ -8,6 +8,7 @@
   ],
   "dependencies": {
     "@types/react": "^18.0.17",
+    "lodash.clonedeep": "^4.5.0",
     "lodash.isempty": "^4.4.0",
     "react": "^18.2.0"
   },
@@ -74,5 +75,5 @@
     "test:watch": "eslint --fix && jest --watchAll"
   },
   "types": "dist/index.d.ts",
-  "version": "1.0.0"
+  "version": "1.1.1"
 }