use-synchronized-state 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rhorge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# A React hook that creates a synchronized state with a reactive value in react (fixing the Cascading updates issue)
+
+## Highlights
+- Offers a hook called useSyncState
+- Removes the cascading update problem
+- Same api as useState
+- No extra dependencies
+- Written in react with typescript
+- Typescript support
+- Small bundle size
+
+## Install
+
+```sh
+    yarn add use-synchronized-state
+```
+or
+```sh
+    npm install use-synchronized-state
+```
+
+## Usage
+
+```typescript
+import { Dispatch, SetStateAction, useState } from 'react';
+import { useSyncState } from 'use-synchronized-state';
+
+function ParentComponent() {
+  const [parentState, setParentState] = useState(0);
+  
+  return (
+    <ChildComponent parentState={parentState} />
+  );
+}
+
+function ChildComponent({ parentState }: { parentState: number }) {
+  // this syncState is synchronized with parentState (has the same api as useState)
+  const [syncState, setSyncState] = useSyncState(parentState);
+  // ...
+}
+```
+
+## Description
+This hook creates a synchronized state while avoiding the cascading updates issue. 
+In our case, synchronized means:
+- When there is a change in the reactive value that we synchronize our state with,
+the returned state changes to the same value, but it can also change independently when the returned setState is called.
+
+  
+### Let's see a small example
+
+```typescript
+import { Dispatch, SetStateAction, useState } from 'react';
+
+function ParentComponent() {
+  const [parentState, setParentState] = useState(0);
+  
+  return (
+    <ChildComponent parentState={parentState} />
+  );
+}
+
+function ChildComponent({ parentState }: { parentState: number }) {
+  const [unsyncState, setUnsyncState] = useState(parentState);
+  // ...
+}
+```
+
+In the above example, we have a simple component structure: a parent component that renders a child component
+(passing its state and setter function).
+
+When the child component mounts (is rendered for the first time), the unsyncState state have the same 
+value as the parentState prop (or the parentState state, which is passed as a prop).
+
+Now if the parentState changes (by calling its setParentState setter), the parentState prop will change accordingly,
+but the value of the unsyncState will not (because the state is only initialized when the component mounts). 
+
+What can we do in the following situation?
+
+The first thing that comes to mind is to do something like this: 
+
+```typescript
+function ChildComponent({ parentState }: { parentState: number }) {
+  const [syncState, setSyncState] = useState(parentState);
+
+  useEffect(() => {
+    setSyncState(parentState)
+  }, [parentState]);
+  // ...
+}
+```
+
+This is doing its job, but we now have another problem called "cascading updates" (which will be spotted by the 
+React Performance tracks). You can read the docs at the following link
+https://react.dev/reference/dev-tools/react-performance-tracks#cascading-updates.
+
+To explain why this happens, we first have to know that React fiber algorithm has two phases: the render phase and
+the commit phase. All you need to know, to understand the issue, is that React will call useEffect after the entire
+virtual dom is rendered. 
+
+So, in our case, after the first render will complete parentState and syncState will have both the value 0
+(the initial value of parentState). Setting parentState to a new value (let's say 1), React will render the 
+ChildComponent with the parentState props as 1, but the syncState will still have the previous value 0.
+Once the useEffect runs, setting the syncState to 1, we will have another render that has both values equal to 1. 
+This is the cascading updates problem in all its glory, instead of having one render, you ended up having two 
+(having also a performance penalty).
+
+
+What react docs tell us to do in this case can be found here 
+https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes.
+I have changed the above example to match it. It still rerenders the ChildComponent twice, which still causes a 
+performance penalty, is hard to reason about and works only for states defined in the same component 
+(if syncSate was a prop, it wouldn't work).
+
+```typescript
+function ChildComponent({ parentState }: { parentState: number }) {
+  const [syncState, setSyncState] = useState(parentState);
+
+  // Better: Adjust the state while rendering
+  const [prevState, setPrevState] = useState(parentState);
+  if (items !== prevItems) {
+    setPrevState(parentState);
+    setSyncState(parentState);
+  }
+  // ...
+}
+```
+
+The 'use-synchronized-state' hook fixes all these issues by synchronizing the values in the same and only render. In the bellow example, 
+if the reactive value changes (for example setParentState(1) is called), both parentState and syncState will have
+the same value from the first render (after the setParentState) and there will be no additional render (only the needed one).
+
+
+```typescript
+import { useSyncState } from 'use-synchronized-state';
+
+function ChildComponent({ parentState }: { parentState: number }) {
+  const [syncState, setSyncState] = useSyncState(parentState);
+  // ...
+}
+```
+
+## License
+MIT
+
+
+
+

package/dist/index.cjs

@@ -0,0 +1 @@
+var react=require("react");function useSyncState(e){var r=react.useState(e)[1],t=react.useRef(e),c=react.useRef(e),c=(c.current!==e&&(c.current=e,t.current=e),react.useCallback(function(e){t.current=e instanceof Function?e(t.current):e,r(t.current)},[t]));return[t.current,c]}exports.useSyncState=useSyncState;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Dispatch, SetStateAction } from 'react';
+/**
+ * This hook creates a synchronized state while avoiding the cascading update issue.
+ * In our case, synchronized means that when there is a change in propsState,
+ * the returned state changes to the same value,
+ * but it can also change independently when the returned setState is called.
+ * @param propsState - a reactive value (e.g. state, props) with which our returned state will synchronize
+ * Returns the exact same output as useState: [state, setState], where state is the synchronized state with the propsState
+ */
+export declare function useSyncState<T>(propsState: T): [T, Dispatch<SetStateAction<T>>];

package/dist/index.mjs

@@ -0,0 +1 @@
+import{useState,useRef,useCallback}from"react";function useSyncState(e){var t=useState(e)[1],r=useRef(e),u=useRef(e),u=(u.current!==e&&(u.current=e,r.current=e),useCallback(function(e){r.current=e instanceof Function?e(r.current):e,t(r.current)},[r]));return[r.current,u]}export{useSyncState};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "use-synchronized-state",
+  "version": "1.0.0",
+  "description": "A React hook that creates a synchronized state with a reactive value in react (fixing the Cascading updates issue)",
+  "author": "rhorge",
+  "license": "MIT",
+  "repository": "https://github.com/rhorge/use-synchronized-state",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.mjs"
+  },
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=8",
+    "npm": ">=5"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "start": "rollup -c -w",
+    "test": "jest"
+  },
+  "jest": {
+    "transform": {
+      ".(ts|tsx)": "ts-jest"
+    },
+    "testRegex": "(/__tests__/.*|\\.(test|spec))\\.(ts|tsx|js)$",
+    "moduleFileExtensions": [
+      "ts",
+      "tsx",
+      "js"
+    ],
+    "modulePathIgnorePatterns": [
+      "<rootDir>/dist/"
+    ]
+  },
+  "peerDependencies": {
+    "react": ">= 16.8.0",
+    "react-dom": ">= 16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/react-hooks": "^3.4.1",
+    "@types/jest": "^26.0.7",
+    "@types/react": "^16.3.13",
+    "@types/react-dom": "^16.0.5",
+    "babel-core": "^6.26.3",
+    "babel-runtime": "^6.26.0",
+    "eslint-plugin-react-hooks": "^4.0.8",
+    "jest": "^26.1.0",
+    "react": "^16.12.0",
+    "react-dom": "^16.12.0",
+    "react-test-renderer": "^16.13.1",
+    "rollup": "^4.22.4",
+    "rollup-plugin-typescript2": "^0.25.3",
+    "rollup-plugin-uglify": "^6.0.4",
+    "ts-jest": "^26.1.3",
+    "typescript": "^3.8.3"
+  },
+  "files": [
+    "dist/*",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "keywords": [
+    "react",
+    "react hooks",
+    "typescript",
+    "npm"
+  ]
+}