@raegen/react-use-prev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikola Pavlovic
+
+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,98 @@
+# @raegen/react-use-prev
+
+The `usePrevious` hook that's actually correct when you **render** the previous value.
+
+```ts
+import { usePrev } from '@raegen/react-use-prev';
+
+const prev = usePrev(value);
+```
+
+Returns the previous *distinct* value of `value`: the value as of the most recent commit
+at which `Object.is` saw it change. Correct, rendered immediately, pure, and with no extra
+render.
+
+## Why another one?
+
+Every popular `usePrevious` is wrong in a different way when you display the previous value,
+not just diff it inside an effect:
+
+| Property | react-use `usePrevious` | ref-in-effect | usehooks-ts¹ | **`usePrev`** |
+|---|:---:|:---:|:---:|:---:|
+| Correct previous-*distinct* value | ❌ collapses | ✅ | ✅ | ✅ |
+| Rendered immediately (no lag) | ❌ wrong value | ❌ one behind | ✅ | ✅ |
+| No ref mutation during render | ✅ | ✅ | ❌ | ✅ |
+| Self-delivering (no extra trigger needed) | ❌ | ❌ | n/a | ✅ |
+| No extra render | ✅ | ✅ | ✅ | ✅ |
+
+¹ usehooks-ts `usePrevious` and react-use `usePreviousDistinct` share the same mechanism
+(refs mutated during render), so they share the same failure mode: impure under StrictMode
+and concurrent rendering.
+
+- **react-use `usePrevious`** returns "value at last render," so any unrelated re-render
+  collapses the previous value into the current one.
+- **The ref-in-effect pattern** renders one transition behind: the ref is advanced *after*
+  the render that needed it, and a ref write schedules no re-render.
+- **usehooks-ts** tracks the value correctly but mutates refs *during render*, which breaks
+  the rules of React under StrictMode double-invocation and concurrent rendering.
+
+`usePrev` reads a local ref during render (never mutates one there) and advances it only in a
+post-commit effect. The read-time fallback returns the soon-to-be-previous value on the
+transition render, so the correct value is on screen immediately with no extra render.
+
+## Install
+
+```sh
+npm install @raegen/react-use-prev
+```
+
+`react` is a peer dependency (`>=16.8`). Works with React 16.8 through 19.
+
+## Usage
+
+```tsx
+import { usePrev } from '@raegen/react-use-prev';
+
+function Price({ amount }: { amount: number }) {
+  const prevAmount = usePrev(amount);
+  const direction = prevAmount === undefined ? null : amount > prevAmount ? '▲' : '▼';
+  return <span>{amount} {direction}</span>;
+}
+```
+
+Provide a second argument to set the first-render value (otherwise it's `undefined`):
+
+```ts
+const prev = usePrev(value, value); // first render returns the current value instead of undefined
+```
+
+## The invariant
+
+> On every committed render, `usePrev` returns the value held at the previous commit where
+> `Object.is(value, previousValue)` was `false` — or `initialValue` (default `undefined`)
+> before any such change.
+
+## Types
+
+```ts
+function usePrev<T>(value: T): T | undefined;        // no initial value
+function usePrev<T>(value: T, initialValue: T): T;   // with an initial value
+```
+
+The first render returns `initialValue`, so without one the return type is `T | undefined`;
+with one it's `T`.
+
+## Gotchas
+
+**Comparison is `Object.is`** — the same comparison React uses for dependency arrays. If you
+pass a referentially-unstable value (a fresh object/array literal every render), every render
+counts as a change, exactly as it would in a `useEffect` dependency array. Pass primitives or
+memoized values. A custom comparator (for deep/structural equality) is planned for a future
+release.
+
+**It's a client hook.** Like any hook using `useEffect`, call it from a Client Component.
+Its first render is deterministic (`initialValue`), so it hydrates without a mismatch.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var react = require('react');
+
+// src/usePrev.ts
+function usePrev(value, initialValue) {
+  const ref = react.useRef({
+    previous: initialValue,
+    current: value
+  });
+  const { previous, current } = ref.current;
+  react.useEffect(() => {
+    ref.current = {
+      previous: ref.current.current,
+      current: value
+    };
+  }, [value]);
+  return !Object.is(current, value) ? current : previous;
+}
+
+exports.usePrev = usePrev;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/usePrev.ts"],"names":["useRef","useEffect"],"mappings":";;;;;AAgDO,SAAS,OAAA,CAAW,OAAU,YAAA,EAAkB;AACrD,EAAA,MAAM,MAAMA,YAAA,CAAgD;AAAA,IAC1D,QAAA,EAAU,YAAA;AAAA,IACV,OAAA,EAAS;AAAA,GACV,CAAA;AAED,EAAA,MAAM,EAAE,QAAA,EAAU,OAAA,EAAQ,GAAI,GAAA,CAAI,OAAA;AAElC,EAAAC,eAAA,CAAU,MAAM;AACd,IAAA,GAAA,CAAI,OAAA,GAAU;AAAA,MACZ,QAAA,EAAU,IAAI,OAAA,CAAQ,OAAA;AAAA,MACtB,OAAA,EAAS;AAAA,KACX;AAAA,EACF,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAEV,EAAA,OAAO,CAAC,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,KAAK,IAAI,OAAA,GAAU,QAAA;AAChD","file":"index.cjs","sourcesContent":["import { useEffect, useRef } from 'react';\n\n/**\n * Returns the previous *distinct* value of `value` — the value as of the most\n * recent commit at which `Object.is` saw it change.\n *\n * Why this exists: the common `usePrevious` implementations are each wrong in a\n * different way when you *render* the previous value.\n *   - react-use `usePrevious` returns \"value at last render\", so any unrelated\n *     re-render collapses previous into current.\n *   - The ref-in-effect pattern renders one transition behind (the ref is\n *     advanced after the render that needed it, and a ref write schedules no\n *     re-render).\n *   - usehooks-ts / react-use `usePreviousDistinct` track the value correctly\n *     but mutate a ref *during render*, which is impure under StrictMode and\n *     concurrent rendering.\n *\n * `usePrev` is correct, renders the right value immediately, adds no extra\n * render, and never mutates a ref during render.\n *\n * Invariant: on every committed render it returns the value held at the\n * previous commit where `Object.is(value, prevValue)` was false (or\n * `initialValue` before any such change).\n *\n * Mechanism (the read-time fallback is the trick):\n *\n *   render | value | ref @ render | !Object.is(cur,value) | returns | effect sets ref\n *   -------+-------+--------------+-----------------------+---------+----------------\n *   mount  |   A   | {prev:init,  |        false           |  init   | {prev:A, cur:A}\n *          |       |  cur:A}      |                        |         |\n *   A -> B |   B   | {prev:A,     |         true           |   A     | {prev:A, cur:B}\n *          |       |  cur:A}      |                        |         |\n *   (rerun)|   B   | {prev:A,     |        false           |   A     | (dep [value] same)\n *          |       |  cur:B}      |                        |         |\n *   B -> C |   C   | {prev:A,     |         true           |   B     | {prev:B, cur:C}\n *          |       |  cur:B}      |                        |         |\n *\n * Note: comparison is `Object.is`, exactly like a React dependency array. If\n * you pass a referentially-unstable value (a fresh object/array each render),\n * every render counts as a change — pass primitives or memoized values, or\n * wait for the custom-comparator option in a future release.\n *\n * @param value        the value to track\n * @param initialValue the value returned on the first render; defaults to\n *                      `undefined` (classic `usePrevious` behavior)\n */\nexport function usePrev<T>(value: T): T | undefined;\nexport function usePrev<T>(value: T, initialValue: T): T;\nexport function usePrev<T>(value: T, initialValue?: T) {\n  const ref = useRef<{ previous: T | undefined; current: T }>({\n    previous: initialValue,\n    current: value,\n  });\n\n  const { previous, current } = ref.current;\n\n  useEffect(() => {\n    ref.current = {\n      previous: ref.current.current,\n      current: value,\n    };\n  }, [value]);\n\n  return !Object.is(current, value) ? current : previous;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+/**
+ * Returns the previous *distinct* value of `value` — the value as of the most
+ * recent commit at which `Object.is` saw it change.
+ *
+ * Why this exists: the common `usePrevious` implementations are each wrong in a
+ * different way when you *render* the previous value.
+ *   - react-use `usePrevious` returns "value at last render", so any unrelated
+ *     re-render collapses previous into current.
+ *   - The ref-in-effect pattern renders one transition behind (the ref is
+ *     advanced after the render that needed it, and a ref write schedules no
+ *     re-render).
+ *   - usehooks-ts / react-use `usePreviousDistinct` track the value correctly
+ *     but mutate a ref *during render*, which is impure under StrictMode and
+ *     concurrent rendering.
+ *
+ * `usePrev` is correct, renders the right value immediately, adds no extra
+ * render, and never mutates a ref during render.
+ *
+ * Invariant: on every committed render it returns the value held at the
+ * previous commit where `Object.is(value, prevValue)` was false (or
+ * `initialValue` before any such change).
+ *
+ * Mechanism (the read-time fallback is the trick):
+ *
+ *   render | value | ref @ render | !Object.is(cur,value) | returns | effect sets ref
+ *   -------+-------+--------------+-----------------------+---------+----------------
+ *   mount  |   A   | {prev:init,  |        false           |  init   | {prev:A, cur:A}
+ *          |       |  cur:A}      |                        |         |
+ *   A -> B |   B   | {prev:A,     |         true           |   A     | {prev:A, cur:B}
+ *          |       |  cur:A}      |                        |         |
+ *   (rerun)|   B   | {prev:A,     |        false           |   A     | (dep [value] same)
+ *          |       |  cur:B}      |                        |         |
+ *   B -> C |   C   | {prev:A,     |         true           |   B     | {prev:B, cur:C}
+ *          |       |  cur:B}      |                        |         |
+ *
+ * Note: comparison is `Object.is`, exactly like a React dependency array. If
+ * you pass a referentially-unstable value (a fresh object/array each render),
+ * every render counts as a change — pass primitives or memoized values, or
+ * wait for the custom-comparator option in a future release.
+ *
+ * @param value        the value to track
+ * @param initialValue the value returned on the first render; defaults to
+ *                      `undefined` (classic `usePrevious` behavior)
+ */
+declare function usePrev<T>(value: T): T | undefined;
+declare function usePrev<T>(value: T, initialValue: T): T;
+
+export { usePrev };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Returns the previous *distinct* value of `value` — the value as of the most
+ * recent commit at which `Object.is` saw it change.
+ *
+ * Why this exists: the common `usePrevious` implementations are each wrong in a
+ * different way when you *render* the previous value.
+ *   - react-use `usePrevious` returns "value at last render", so any unrelated
+ *     re-render collapses previous into current.
+ *   - The ref-in-effect pattern renders one transition behind (the ref is
+ *     advanced after the render that needed it, and a ref write schedules no
+ *     re-render).
+ *   - usehooks-ts / react-use `usePreviousDistinct` track the value correctly
+ *     but mutate a ref *during render*, which is impure under StrictMode and
+ *     concurrent rendering.
+ *
+ * `usePrev` is correct, renders the right value immediately, adds no extra
+ * render, and never mutates a ref during render.
+ *
+ * Invariant: on every committed render it returns the value held at the
+ * previous commit where `Object.is(value, prevValue)` was false (or
+ * `initialValue` before any such change).
+ *
+ * Mechanism (the read-time fallback is the trick):
+ *
+ *   render | value | ref @ render | !Object.is(cur,value) | returns | effect sets ref
+ *   -------+-------+--------------+-----------------------+---------+----------------
+ *   mount  |   A   | {prev:init,  |        false           |  init   | {prev:A, cur:A}
+ *          |       |  cur:A}      |                        |         |
+ *   A -> B |   B   | {prev:A,     |         true           |   A     | {prev:A, cur:B}
+ *          |       |  cur:A}      |                        |         |
+ *   (rerun)|   B   | {prev:A,     |        false           |   A     | (dep [value] same)
+ *          |       |  cur:B}      |                        |         |
+ *   B -> C |   C   | {prev:A,     |         true           |   B     | {prev:B, cur:C}
+ *          |       |  cur:B}      |                        |         |
+ *
+ * Note: comparison is `Object.is`, exactly like a React dependency array. If
+ * you pass a referentially-unstable value (a fresh object/array each render),
+ * every render counts as a change — pass primitives or memoized values, or
+ * wait for the custom-comparator option in a future release.
+ *
+ * @param value        the value to track
+ * @param initialValue the value returned on the first render; defaults to
+ *                      `undefined` (classic `usePrevious` behavior)
+ */
+declare function usePrev<T>(value: T): T | undefined;
+declare function usePrev<T>(value: T, initialValue: T): T;
+
+export { usePrev };

package/dist/index.js

@@ -0,0 +1,21 @@
+import { useRef, useEffect } from 'react';
+
+// src/usePrev.ts
+function usePrev(value, initialValue) {
+  const ref = useRef({
+    previous: initialValue,
+    current: value
+  });
+  const { previous, current } = ref.current;
+  useEffect(() => {
+    ref.current = {
+      previous: ref.current.current,
+      current: value
+    };
+  }, [value]);
+  return !Object.is(current, value) ? current : previous;
+}
+
+export { usePrev };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/usePrev.ts"],"names":[],"mappings":";;;AAgDO,SAAS,OAAA,CAAW,OAAU,YAAA,EAAkB;AACrD,EAAA,MAAM,MAAM,MAAA,CAAgD;AAAA,IAC1D,QAAA,EAAU,YAAA;AAAA,IACV,OAAA,EAAS;AAAA,GACV,CAAA;AAED,EAAA,MAAM,EAAE,QAAA,EAAU,OAAA,EAAQ,GAAI,GAAA,CAAI,OAAA;AAElC,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,GAAA,CAAI,OAAA,GAAU;AAAA,MACZ,QAAA,EAAU,IAAI,OAAA,CAAQ,OAAA;AAAA,MACtB,OAAA,EAAS;AAAA,KACX;AAAA,EACF,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAEV,EAAA,OAAO,CAAC,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,KAAK,IAAI,OAAA,GAAU,QAAA;AAChD","file":"index.js","sourcesContent":["import { useEffect, useRef } from 'react';\n\n/**\n * Returns the previous *distinct* value of `value` — the value as of the most\n * recent commit at which `Object.is` saw it change.\n *\n * Why this exists: the common `usePrevious` implementations are each wrong in a\n * different way when you *render* the previous value.\n *   - react-use `usePrevious` returns \"value at last render\", so any unrelated\n *     re-render collapses previous into current.\n *   - The ref-in-effect pattern renders one transition behind (the ref is\n *     advanced after the render that needed it, and a ref write schedules no\n *     re-render).\n *   - usehooks-ts / react-use `usePreviousDistinct` track the value correctly\n *     but mutate a ref *during render*, which is impure under StrictMode and\n *     concurrent rendering.\n *\n * `usePrev` is correct, renders the right value immediately, adds no extra\n * render, and never mutates a ref during render.\n *\n * Invariant: on every committed render it returns the value held at the\n * previous commit where `Object.is(value, prevValue)` was false (or\n * `initialValue` before any such change).\n *\n * Mechanism (the read-time fallback is the trick):\n *\n *   render | value | ref @ render | !Object.is(cur,value) | returns | effect sets ref\n *   -------+-------+--------------+-----------------------+---------+----------------\n *   mount  |   A   | {prev:init,  |        false           |  init   | {prev:A, cur:A}\n *          |       |  cur:A}      |                        |         |\n *   A -> B |   B   | {prev:A,     |         true           |   A     | {prev:A, cur:B}\n *          |       |  cur:A}      |                        |         |\n *   (rerun)|   B   | {prev:A,     |        false           |   A     | (dep [value] same)\n *          |       |  cur:B}      |                        |         |\n *   B -> C |   C   | {prev:A,     |         true           |   B     | {prev:B, cur:C}\n *          |       |  cur:B}      |                        |         |\n *\n * Note: comparison is `Object.is`, exactly like a React dependency array. If\n * you pass a referentially-unstable value (a fresh object/array each render),\n * every render counts as a change — pass primitives or memoized values, or\n * wait for the custom-comparator option in a future release.\n *\n * @param value        the value to track\n * @param initialValue the value returned on the first render; defaults to\n *                      `undefined` (classic `usePrevious` behavior)\n */\nexport function usePrev<T>(value: T): T | undefined;\nexport function usePrev<T>(value: T, initialValue: T): T;\nexport function usePrev<T>(value: T, initialValue?: T) {\n  const ref = useRef<{ previous: T | undefined; current: T }>({\n    previous: initialValue,\n    current: value,\n  });\n\n  const { previous, current } = ref.current;\n\n  useEffect(() => {\n    ref.current = {\n      previous: ref.current.current,\n      current: value,\n    };\n  }, [value]);\n\n  return !Object.is(current, value) ? current : previous;\n}\n"]}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@raegen/react-use-prev",
+  "version": "0.1.0",
+  "description": "The correct usePrevious: renders the previous distinct value immediately, purely, with no extra render.",
+  "keywords": [
+    "react",
+    "hook",
+    "hooks",
+    "use-previous",
+    "usePrevious",
+    "previous",
+    "previous-value",
+    "usePrev",
+    "react-hooks"
+  ],
+  "license": "MIT",
+  "author": "raegen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raegen/react-use-prev.git"
+  },
+  "homepage": "https://github.com/raegen/react-use-prev#readme",
+  "bugs": {
+    "url": "https://github.com/raegen/react-use-prev/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint:pkg": "publint && attw --pack .",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.4",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "jsdom": "^25.0.1",
+    "publint": "^0.3.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}