@dr.pogodin/react-global-state 0.6.4 → 0.6.5

package/README.md

@@ -257,5 +257,82 @@ of some, or all async data at the server side.
     }
     ```
 
+### Frequently Asked Questions
+
+- _Does React Global State library avoid unnecessary component re-renders when values updated in the global state are irrelevant to those components?_
+
+  Yes, it does avoid unnecessary re-renders of the component tree. A component
+  relying on `some.path` in the global state is re-rendered only when the value
+  at this path, or its sub-path has changed; _i.e._ it will be re-rendered if
+  the value at `some.path` has changed, and it will be re-rendered if the value
+  at `some.path.sub.path` has changed.
+
+- _How would you describe your use case compared to another React global state library, e.g. [Valtio](https://www.npmjs.com/package/valtio)?_
+
+  1.  React Global State is designed to follow the standard React API as close
+      as possible. _E.g._ if some component relies on the local state:
+      ```jsx
+      const [value, setValue] = useState(initialState);
+      ```
+      to move that value to the global state (or _vice versa_) one only needs to
+      replace the hook with
+      ```jsx
+      const [value, setValue] = useGlobalState(path, initialState);
+      ```
+      The [useGlobalState()] hook takes care to follow all edge cases of the
+      standard [useState()]: `setValue` setter identity is stable (does not
+      change on re-renders), functional updates and lazy initial state are
+      supported.
+
+      Other libraries tend to re-invent the wheel, introducing their own APIs,
+      which (i) should be learned and understood; (ii) do complicate migration
+      of components between the local and global state, should it be needed in
+      a course of app development / prototyping.
+
+  2.  When it comes to async data in the global state other libraries tend to
+      offer only a very basic supported, often relying on experimental or internal
+      React mechanics.
+
+      React Global State, [useAsyncData()] and [useAsyncCollection()] hooks in
+      particular, implements async data fetching and management features: when
+      multiple components use these hooks to load async data to the same global
+      state path the library takes care to do the actual loading just once, and
+      then keep the data without reloading until their age reaches (configurable)
+      max age. There is an automated garbage collection of expired, non-used
+      async data from the global state; there is server-side rendering (SSR)
+      support, with suggested high-level setup taking care that all async data
+      loaded using [useAsyncData()] and [useAsyncCollection()] hooks will be
+      automatically loaded and used in server-side renders (still allowing to
+      opt-out of that for individual hooks, and timeout server-side fetching of
+      data that take too long to arrive, in which case the library will fetch
+      such data client-side). It does not rely on experimental React APIs to
+      achieve its functionality, it only uses current public APIs.
+
+      For me the support of async data fetching into the global state and their
+      further management with out-of-the-box SSR support was the primary
+      motivation to create React Global State. There are many other global state
+      React libraries, but I was not able to find any that would cover the async
+      data handling with that ease I believed was possible. The secondary
+      motivation was that existing global state libraries either had
+      the shortcoming of unnecessary component re-renders when data irrelevant
+      to them where updated in the global state, or introduced their
+      own APIs, where following the standard React APIs for local state looks
+      to me a way more convenient approach.
+
+- _Is React Global State library production ready (considering the current version number 0.y.z)?_
+
+  Yes. I personally use it in production for all my commercial and personal
+  React projects for over an year. I just don't feel like to call it v1 until
+  a reasonable adoption by 3rd party developers, and any API improvements that
+  may come out of community experience.
+
 [Library Reference](https://dr.pogodin.studio/docs/react-global-state/index.html) •
 [Blog Article](https://dr.pogodin.studio/dev-blog/the-global-state-in-react-designed-right)
+
+[useAsyncCollection()]: https://dr.pogodin.studio/docs/react-global-state/docs/api/hooks/useasynccollection
+[useAsyncData()]: https://dr.pogodin.studio/docs/react-global-state/docs/api/hooks/useasyncdata
+[useGlobalState()]: https://dr.pogodin.studio/docs/react-global-state/docs/api/hooks/useglobalstate
+[useState()]: https://reactjs.org/docs/hooks-reference.html#usestate
+
+[functional updates]: https://reactjs.org/docs/hooks-reference.html#functional-updates
+[lazy initial state]: https://reactjs.org/docs/hooks-reference.html#functional-updates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr.pogodin/react-global-state",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Hook-based global state for React",
   "main": "index.js",
   "scripts": {
@@ -27,31 +27,32 @@
   "bugs": {
     "url": "https://github.com/birdofpreyru/react-global-state.git/issues"
   },
-  "homepage": "https://dr.pogodin.studio/dev-blog/the-global-state-in-react-designed-right",
+  "homepage": "https://dr.pogodin.studio/docs/react-global-state/index.html",
   "dependencies": {
-    "@babel/runtime": "^7.15.4",
+    "@babel/runtime": "^7.16.3",
     "lodash": "^4.17.21",
     "uuid": "^8.3.2"
   },
   "devDependencies": {
-    "@babel/cli": "^7.15.7",
-    "@babel/core": "^7.15.8",
-    "@babel/node": "^7.15.8",
-    "@babel/plugin-transform-runtime": "^7.15.8",
-    "@babel/preset-env": "^7.15.8",
-    "@babel/preset-react": "^7.14.5",
-    "babel-eslint": "^10.1.0",
-    "babel-jest": "^27.3.1",
+    "@babel/cli": "^7.16.0",
+    "@babel/core": "^7.16.0",
+    "@babel/eslint-parser": "^7.16.3",
+    "@babel/eslint-plugin": "^7.14.5",
+    "@babel/node": "^7.16.0",
+    "@babel/plugin-transform-runtime": "^7.16.4",
+    "@babel/preset-env": "^7.16.4",
+    "@babel/preset-react": "^7.16.0",
+    "babel-jest": "^27.4.2",
     "babel-plugin-module-resolver": "^4.1.0",
-    "eslint": "^7.32.0",
-    "eslint-config-airbnb": "^18.2.1",
+    "eslint": "^8.4.1",
+    "eslint-config-airbnb": "^19.0.2",
     "eslint-import-resolver-babel-module": "^5.3.1",
-    "eslint-plugin-import": "^2.25.2",
-    "eslint-plugin-jest": "^25.2.2",
-    "eslint-plugin-jsx-a11y": "^6.4.1",
-    "eslint-plugin-react": "^7.26.1",
-    "eslint-plugin-react-hooks": "^4.2.0",
-    "jest": "^27.3.1",
+    "eslint-plugin-import": "^2.25.3",
+    "eslint-plugin-jest": "^25.3.0",
+    "eslint-plugin-jsx-a11y": "^6.5.1",
+    "eslint-plugin-react": "^7.27.1",
+    "eslint-plugin-react-hooks": "^4.3.0",
+    "jest": "^27.4.3",
     "jsdoc": "^3.6.7",
     "mockdate": "^3.0.5",
     "pretty": "^2.0.0",