@webkrafters/react-observable-context 2.1.12 → 3.0.0-rc.0

package/README.md

@@ -2,7 +2,7 @@
 
 A context bearing an observable consumer [store](#store).\
 Only re-renders subscribing components on context state change.\
-Subscribing component decides which context state properties' change trigger its update.
+Subscribing component decides which context state properties' change to trigger its update.
 
 **Name:** React-Observable-Context
 
@@ -18,23 +18,23 @@ A context bearing an observable consumer [store](#store). State changes within t
 
 **React::memo** *(and PureComponents)* remain the go-to solution for the repeated automatic re-renderings of entire component trees resulting from ***component*** state changes. 
 
-***Recommendation:*** For optimum performance, consider wrapping in **React::memo** most components using this package's ***useContext*** function either directly or through another React hook. This will protect such components and their descendants from unrelated cascading render operations.
+***Recommendation:*** For optimum performance, consider wrapping in **React::memo** most components using this module's ***useContext*** hook either directly or through another React hook. This will protect such components and their descendants from unrelated cascading render operations.
 
 ***Exempt*** from the recommendation are certain components such as those wrapped in the `React-Redux::connect()` Higher Order Component (HOC). Such HOC provides similar cascade-render protections to wrapped components and their descendants. 
 
 # API
 
-The React-Observable-Context package exports **4** modules namely: the **createContext** method, the **useContext** hook, the **Provider** component and the **UsageError** class.
+The React-Observable-Context module contains **3** exports namely: the **createContext** function, the **useContext** hook and the **UsageError** class.
 
 * **createContext** is a zero-parameter function returning a store-bearing context. Pass the context as a `context` parameter to the [useContext()](#usecontext) to obtain the context's [store](#store).
 
-* <b id="usecontext">useContext</b> is analogous to React::useContext hook but returns the context store and takes a second parameter named ***watchedKeys***. The `watchedKeys` parameter is a list of state object property paths to watch. A change in any of the referenced properties automatically triggers a render of the component calling this hook.
-
-* **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](#prehooks) section below)</i>.
+* <b id="usecontext">useContext</b> is analogous to React::useContext hook but returns the context store and takes a second parameter named ***watchedKeys***. The `watchedKeys` parameter is a list of state object property paths to watch. A change in any of the referenced properties automatically triggers a render of the component using this hook.
 
 * **UsageError** class is the Error type reported for attempts to access this context's store outside of its Provider component tree.
 
-***<u>Note:</u>*** the Provider `context` prop is not updateable. Once set, all further updates to this prop are not recorded.
+## Provider
+
+The Provider component is a property of the `context`. It can immediately be used as-is anywhere the React-Observable-Context is required. It accepts the customary `children` and `value` props, and an optional `prehooks` prop <i>(discussed in the [prehooks](#prehooks) subsection below)</i>.
 
 ## Store
 
@@ -69,35 +69,16 @@ The context's `store` exposes **4** methods for interacting with the context's i
 ### <u>*context.js*</u>
 
     import React from 'react';
-
-	import {
-		createContext,
-		Provider,
-		useContext
-	} from '@webkrafters/react-observable-context';
-	
-	export const ObservableContext = createContext();
-
-	export const ObservableContextProvider = ({ children, prehooks, value }) => (
-		<Provider
-			context={ ObservableContext }
-			prehooks={ prehooks }
-			value={ value }
-		>
-			{ children }
-		</Provider>
-	);
-	ObservableContextProvider.displayName = 'ObservableContextProvider';
-
+	import { createContext, useContext } from '@webkrafters/react-observable-context';
+	const ObservableContext = createContext();
 	export const useObservableContext = watchedKeys => useContext( ObservableContext, watchedKeys );
-
 	export default ObservableContext;
 
 ### <u>*index.js*</u>
 
     import React from 'react';
     import ReactDOM from 'react-dom';
-    import App from './app';
+    import App from './app';s
     ReactDOM.render(<App />, document.getElementById('root'));
 
 ### <u>*app.js*</u>
@@ -137,7 +118,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 ### <u>*product.js*</u>
 
 	import React, { useCallback, useEffect, useState } from 'react';
-	import { ObservableContextProvider } from './context';
+	import ObservableContext from './context';
 	import Editor from './editor';
 	import PriceSticker from './price-sticker';
 	import ProductDescription from './product-description';
@@ -158,7 +139,7 @@ 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>
-				<ObservableContextProvider
+				<ObservableContext.Provider
 					prehooks={ updateHooks }
 					value={ state }
 				>
@@ -172,7 +153,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 					</div>
 					<ProductDescription />
 					<PriceSticker />
-				</ObservableContextProvider>
+				</ObservableContext.Provider>
 			</div>
 		);
 	};

package/dist/index.d.ts

@@ -2,23 +2,6 @@ export class UsageError extends Error {
 }
 export function createContext<T_1 extends State>(): import("react").Context<Store<T_1>>;
 export function useContext<T_1 extends State>(context: import("react").Context<Store<T_1>>, watchedKeys?: (string | keyof T_1)[]): Store<T_1>;
-/**
- * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
- *
- * @type {FC<{
- * 		children?: ReactNode,
- * 		context: ObservableContext<T>,
- * 		prehooks?: Prehooks<T>
- * 		value: PartialState<T>
- * }>}
- * @template {State} T
- */
-export const Provider: FC<{
-    children?: ReactNode;
-    context: ObservableContext<T>;
-    prehooks?: Prehooks<T>;
-    value: PartialState<T>;
-}>;
 export type ObservableContext<T_1 extends State> = 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;
@@ -45,5 +28,6 @@ export type Store<T_1 extends State> = {
 export type Unsubscribe = VoidFunction;
 export type ReactNode = import("react").ReactNode;
 export type FC<P = {}> = import("react").FC<P>;
+export type Provider<T_1> = import("react").Provider<T>;
 export type Context<T_1> = import("react").Context<T>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useContext = exports.createContext = exports.UsageError = exports.Provider = void 0;
+exports.useContext = exports.createContext = exports.UsageError = void 0;
 var _react = _interopRequireWildcard(require("react"));
 var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
 var _lodash2 = _interopRequireDefault(require("lodash.has"));
@@ -43,75 +43,27 @@ var UsageError = /*#__PURE__*/function (_Error) {
   }
   return _createClass(UsageError);
 }( /*#__PURE__*/_wrapNativeSuper(Error));
-/** @type {OptionalTask} */
-exports.UsageError = UsageError;
-var reportNonReactUsage = function reportNonReactUsage() {
-  throw new UsageError('Detected usage outside of this context\'s Provider component tree. Please apply the exported Provider component');
-};
-
 /**
  * @param {T} state
  * @return {PartialState<T>}
  * @template {State} T
  */
+exports.UsageError = UsageError;
 var defaultSelector = function defaultSelector(state) {
   return state;
 };
 
-/**
- * @returns {ObservableContext<T>}
- * @template {State} T
- */
-var createContext = function createContext() {
-  return /*#__PURE__*/(0, _react.createContext)({
-    getState: reportNonReactUsage,
-    resetState: reportNonReactUsage,
-    setState: reportNonReactUsage,
-    subscribe: reportNonReactUsage
-  });
-};
-
-/**
- * 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<string|keyof T>} [watchedKeys = []] A list of state object property paths 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] : [];
-  /** @type {Store<T>} */
-  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.useContext = useContext;
 var defaultPrehooks = Object.freeze({});
+
+/** @type {OptionalTask} */
+var reportNonReactUsage = function reportNonReactUsage() {
+  throw new UsageError('Detected usage outside of this context\'s Provider component tree. Please apply the exported Provider component');
+};
 var _setState = function () {
   var initDiff = function initDiff(propKey, changed, replaced) {
     changed[propKey] = {};
@@ -180,101 +132,28 @@ var usePrehooksRef = function usePrehooksRef(prehooks) {
   return prehooksRef;
 };
 
-/** @type {FC<{child: ReactNode}>} */
-var ChildMemo = function () {
-  var useNodeMemo = function useNodeMemo(node) {
-    var nodeRef = (0, _react.useRef)(node);
-    if (!(0, _lodash4["default"])((0, _lodash6["default"])(nodeRef.current, '_owner'), (0, _lodash6["default"])(node, '_owner'))) {
-      nodeRef.current = node;
-    }
-    return nodeRef.current;
-  };
-  var ChildMemo = /*#__PURE__*/(0, _react.memo)(function (_ref) {
-    var child = _ref.child;
-    return child;
-  });
-  ChildMemo.displayName = 'ObservableContext.Provider.Internal.Guardian.ChildMemo';
-  var Guardian = function Guardian(_ref2) {
-    var child = _ref2.child;
-    return /*#__PURE__*/_react["default"].createElement(ChildMemo, {
-      child: useNodeMemo(child)
-    });
-  };
-  Guardian.displayName = 'ObservableContext.Provider.Internal.Guardian';
-  return Guardian;
-}();
-
-/** @type {(children: ReactNode) => ReactNode} */
-var memoizeImmediateChildTree = function memoizeImmediateChildTree(children) {
-  return _react.Children.map(children, function (child) {
-    var _child$props;
-    if (_typeof(child.type) === 'object' && 'compare' in child.type) {
-      return child;
-    }
-    if ((_child$props = child.props) !== null && _child$props !== void 0 && _child$props.children) {
-      child = /*#__PURE__*/(0, _react.cloneElement)(child, (0, _lodash6["default"])(child.props, 'children'), memoizeImmediateChildTree(child.props.children));
-    }
-    return /*#__PURE__*/_react["default"].createElement(ChildMemo, {
-      child: child
-    });
-  });
-};
-
-/**
-* @type {FC<{
-* 		children?: ReactNode,
-* 		context: ObservableContext<T>,
-* 		value: Store<T>
-* }>}
-* @template {State} T
-*/
-var ProviderInternal = function ProviderInternal(_ref3) {
-  var children = _ref3.children,
-    StoreContext = _ref3.context,
-    value = _ref3.value;
-  return /*#__PURE__*/_react["default"].createElement(StoreContext.Provider, {
-    value: value
-  }, memoizeImmediateChildTree(children));
-};
-ProviderInternal.displayName = 'ObservableContext.Provider.Internal';
-
 /**
- * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
- *
- * @type {FC<{
- * 		children?: ReactNode,
- * 		context: ObservableContext<T>,
- * 		prehooks?: Prehooks<T>
- * 		value: PartialState<T>
- * }>}
+ * @param {Prehooks<T>} prehooks
+ * @param {T} value
+ * @returns {Store<T>}
  * @template {State} T
  */
-var Provider = function Provider(_ref4) {
-  var _ref4$children = _ref4.children,
-    children = _ref4$children === void 0 ? null : _ref4$children,
-    context = _ref4.context,
-    _ref4$prehooks = _ref4.prehooks,
-    prehooks = _ref4$prehooks === void 0 ? defaultPrehooks : _ref4$prehooks,
-    value = _ref4.value;
+var useStore = function useStore(prehooks, value) {
   var prehooksRef = usePrehooksRef(prehooks);
   var initialState = (0, _react.useRef)(value);
 
   /** @type {[Set<Listener<T>>, Function]} */
-  var _useState3 = (0, _react.useState)(function () {
+  var _useState = (0, _react.useState)(function () {
       return new Set();
     }),
-    _useState4 = _slicedToArray(_useState3, 1),
-    listeners = _useState4[0];
+    _useState2 = _slicedToArray(_useState, 1),
+    listeners = _useState2[0];
   /** @type {[T, Function]} */
-  var _useState5 = (0, _react.useState)(function () {
+  var _useState3 = (0, _react.useState)(function () {
       return (0, _lodash["default"])(value);
     }),
-    _useState6 = _slicedToArray(_useState5, 1),
-    state = _useState6[0];
-  /** @type {ObservableContext<T>} */
-  var _useState7 = (0, _react.useState)(context),
-    _useState8 = _slicedToArray(_useState7, 1),
-    StoreContext = _useState8[0];
+    _useState4 = _slicedToArray(_useState3, 1),
+    state = _useState4[0];
 
   /** @type {Listener<T>} */
   var onChange = function onChange(newValue, oldValue) {
@@ -317,7 +196,7 @@ var Provider = function Provider(_ref4) {
   }, [value]);
 
   /** @type {[Store<T>, Function]} */
-  var _useState9 = (0, _react.useState)(function () {
+  var _useState5 = (0, _react.useState)(function () {
       return {
         getState: getState,
         resetState: resetState,
@@ -325,15 +204,148 @@ var Provider = function Provider(_ref4) {
         subscribe: subscribe
       };
     }),
-    _useState10 = _slicedToArray(_useState9, 1),
-    store = _useState10[0];
-  return /*#__PURE__*/_react["default"].createElement(ProviderInternal, {
-    context: StoreContext,
-    value: store
-  }, children);
+    _useState6 = _slicedToArray(_useState5, 1),
+    store = _useState6[0];
+  return store;
+};
+
+/** @type {FC<{child: ReactNode}>} */
+var ChildMemo = function () {
+  var useNodeMemo = function useNodeMemo(node) {
+    var nodeRef = (0, _react.useRef)(node);
+    if (!(0, _lodash4["default"])((0, _lodash6["default"])(nodeRef.current, '_owner'), (0, _lodash6["default"])(node, '_owner'))) {
+      nodeRef.current = node;
+    }
+    return nodeRef.current;
+  };
+  var ChildMemo = /*#__PURE__*/(0, _react.memo)(function (_ref) {
+    var child = _ref.child;
+    return child;
+  });
+  ChildMemo.displayName = 'ObservableContext.Provider.Internal.Guardian.ChildMemo';
+  var Guardian = function Guardian(_ref2) {
+    var child = _ref2.child;
+    return /*#__PURE__*/_react["default"].createElement(ChildMemo, {
+      child: useNodeMemo(child)
+    });
+  };
+  Guardian.displayName = 'ObservableContext.Provider.Internal.Guardian';
+  return Guardian;
+}();
+
+/** @type {(children: ReactNode) => ReactNode} */
+var memoizeImmediateChildTree = function memoizeImmediateChildTree(children) {
+  return _react.Children.map(children, function (child) {
+    var _child$props;
+    if (_typeof(child.type) === 'object' && 'compare' in child.type) {
+      return child;
+    } // memo element
+    if ((_child$props = child.props) !== null && _child$props !== void 0 && _child$props.children) {
+      child = /*#__PURE__*/(0, _react.cloneElement)(child, (0, _lodash6["default"])(child.props, 'children'), memoizeImmediateChildTree(child.props.children));
+    }
+    return /*#__PURE__*/_react["default"].createElement(ChildMemo, {
+      child: child
+    });
+  });
+};
+
+/**
+ * @type {FC<{
+ * 		children?: ReactNode,
+ * 		provider: ObservableContext<T>["Provider"],
+ * 		value: Store<T>
+ * }>}
+ * @template {State} T
+ */
+var ProviderInternal = function ProviderInternal(_ref3) {
+  var children = _ref3.children,
+    Provider = _ref3.provider,
+    value = _ref3.value;
+  return /*#__PURE__*/_react["default"].createElement(Provider, {
+    value: value
+  }, memoizeImmediateChildTree(children));
+};
+ProviderInternal.displayName = 'ObservableContext.Provider.Internal';
+
+/**
+ * @param {Provider<Store<T>>} Provider
+ */
+var makeObservable = function makeObservable(Provider) {
+  /**
+   * Note: `context` prop is not updateable. Furtther updates to this prop are ignored.
+   *
+   * @type {FC<{
+   * 		children?: ReactNode,
+   * 		context: ObservableContext<T>,
+   * 		prehooks?: Prehooks<T>
+   * 		value: PartialState<T>
+   * }>}
+   * @template {State} T
+   */
+  var Observable = function Observable(_ref4) {
+    var _ref4$children = _ref4.children,
+      children = _ref4$children === void 0 ? null : _ref4$children,
+      _ref4$prehooks = _ref4.prehooks,
+      prehooks = _ref4$prehooks === void 0 ? defaultPrehooks : _ref4$prehooks,
+      value = _ref4.value;
+    return /*#__PURE__*/_react["default"].createElement(ProviderInternal, {
+      provider: Provider,
+      value: useStore(prehooks, value)
+    }, children);
+  };
+  Observable.displayName = 'ObservableContext.Provider';
+  return Observable;
+};
+
+/**
+ * @returns {ObservableContext<T>}
+ * @template {State} T
+ */
+var createContext = function createContext() {
+  var Context = /*#__PURE__*/(0, _react.createContext)({
+    getState: reportNonReactUsage,
+    resetState: reportNonReactUsage,
+    setState: reportNonReactUsage,
+    subscribe: reportNonReactUsage
+  });
+  var provider = Context.Provider;
+  Context.Provider = makeObservable(provider);
+  return Context;
+};
+
+/**
+ * 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<string|keyof T>} [watchedKeys = []] A list of state object property paths 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] : [];
+  /** @type {Store<T>} */
+  var store = (0, _react.useContext)(context);
+  var _useState7 = (0, _react.useState)(false),
+    _useState8 = _slicedToArray(_useState7, 2),
+    tripRender = _useState8[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;
 };
-exports.Provider = Provider;
-Provider.displayName = 'ObservableContext.Provider';
 
 /**
  * @typedef {Context<Store<T>>} ObservableContext
@@ -389,7 +401,13 @@ Provider.displayName = 'ObservableContext.Provider';
  * @template [P={}]
  */
 
+/**
+ * @typedef {import("react").Provider<T>} Provider
+ * @template T
+ */
+
 /**
  * @typedef {import("react").Context<T>} Context
  * @template T
- */
+ */
+exports.useContext = useContext;

package/package.json

@@ -81,5 +81,5 @@
     "test:watch": "eslint --fix && jest --updateSnapshot --watchAll"
   },
   "types": "dist/index.d.ts",
-  "version": "2.1.12"
+  "version": "3.0.0-rc.0"
 }