Add useLatestRef() and useLayoutLatestRef()

docs/useLatest.md

@@ -4,6 +4,8 @@ React state hook that returns the latest state as described in the [React hooks
 
 This is mostly useful to get access to the latest value of some props or state inside an asynchronous callback, instead of that value at the time the callback was created from.
 
+Note: This hook updates the ref value during rendering, and is therefore potentially unsafe. Use `useLatestRef()` if you want to safely access the latest value. For more information, see "Pitfall" section of [React `useRef()` docs](https://react.dev/reference/react/useRef).
+
 ## Usage
 
 ```jsx

docs/useLatestRef.md

@@ -0,0 +1,40 @@
+# `useLatestRef`
+
+React state hook that stores the latest version of a value.
+
+This can be used to access the latest ("fresh") value of some props or state inside an event handler or `useEffect()` without specifying the value in a dependency array.
+
+Since this hook updates the ref with a `useEffect()`, the ref value may be outdated ("stale") when accessed in a `useLayoutEffect()` or during rendering. If you need to access the latest value in a `useLayoutEffect()`, use `useLayoutLatestRef()` instead. Do not access the ref value during rendering as it is [considered a bad practice](https://react.dev/learn/referencing-values-with-refs#best-practices-for-refs).
+
+This is similar to `useLatest()` but safe from the concurrency issues that `useLatest()` may suffer from. For more information, see "Pitfall" section of [React `useRef()` docs](https://react.dev/reference/react/useRef).
+
+## Usage
+
+```jsx
+import { useLatestRef } from "react-use";
+
+const Demo = () => {
+  const [count, setCount] = React.useState(0);
+  const latestCount = useLatestRef(count);
+
+  function handleAlertClick() {
+    setTimeout(() => {
+      alert(`Latest count value: ${latestCount.current}`);
+    }, 3000);
+  }
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>Click me</button>
+      <button onClick={handleAlertClick}>Show alert</button>
+    </div>
+  );
+};
+```
+
+## Reference
+
+```ts
+const latestRef = useLatestRef(someValue);
+```

docs/useLayoutLatestRef.md

@@ -0,0 +1,38 @@
+# `useLayoutLatestRef`
+
+React state hook that stores the latest version of a value.
+
+This can be used to access the latest ("fresh") value of some props or state inside an event handler or `useLayoutEffect()` without specifying the value in a dependency array.
+
+This hook is similar to `useLatestRef()` except that it provide the latest value even when the ref is accessed in a `useLayoutEffect()`.
+
+## Usage
+
+```jsx
+import { useLayoutLatestRef } from "react-use";
+
+const Demo = () => {
+  const [count, setCount] = React.useState(0);
+  const latestCount = useLayoutLatestRef(count);
+
+  function handleAlertClick() {
+    setTimeout(() => {
+      alert(`Latest count value: ${latestCount.current}`);
+    }, 3000);
+  }
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>Click me</button>
+      <button onClick={handleAlertClick}>Show alert</button>
+    </div>
+  );
+};
+```
+
+## Reference
+
+```ts
+const latestRef = useLayoutLatestRef(someValue);
+```

src/index.ts

@@ -43,6 +43,8 @@ export { default as createBreakpoint } from './factory/createBreakpoint';
 export { default as useKeyPress } from './useKeyPress';
 export { default as useKeyPressEvent } from './useKeyPressEvent';
 export { default as useLatest } from './useLatest';
+export { default as useLatestRef } from './useLatestRef';
+export { default as useLayoutLatestRef } from './useLayoutLatestRef';
 export { default as useLifecycles } from './useLifecycles';
 export { default as useList } from './useList';
 export { default as useLocalStorage } from './useLocalStorage';

src/useLatest.ts

@@ -1,5 +1,8 @@
 import { useRef } from 'react';
 
+/**
+ * @deprecated Use `useLatestRef` instead
+ */
 const useLatest = <T>(value: T): { readonly current: T } => {
   const ref = useRef(value);
   ref.current = value;

src/useLatestRef.ts

@@ -0,0 +1,11 @@
+import { useEffect, useRef } from 'react';
+
+const useLatestRef = <T>(value: T): { readonly current: T } => {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+};
+
+export default useLatestRef;

src/useLayoutLatestRef.ts

@@ -0,0 +1,11 @@
+import { useLayoutEffect, useRef } from 'react';
+
+const useLatestRef = <T>(value: T): { readonly current: T } => {
+  const ref = useRef(value);
+  useLayoutEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+};
+
+export default useLatestRef;

stories/useLatestRef.story.tsx

@@ -0,0 +1,28 @@
+import { storiesOf } from '@storybook/react';
+import * as React from 'react';
+import { useLatestRef } from '../src';
+import ShowDocs from './util/ShowDocs';
+
+const Demo = () => {
+  const [count, setCount] = React.useState(0);
+  const latestCount = useLatestRef(count);
+  const timeoutMs = 3000;
+
+  function handleAlertClick() {
+    setTimeout(() => {
+      alert(`Latest count value: ${latestCount.current}`);
+    }, timeoutMs);
+  }
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>Click me</button>
+      <button onClick={handleAlertClick}>Show alert in {timeoutMs / 1000}s</button>
+    </div>
+  );
+};
+
+storiesOf('State/useLatestRef', module)
+  .add('Docs', () => <ShowDocs md={require('../docs/useLatestRef.md')} />)
+  .add('Demo', () => <Demo />);

stories/useLayoutLatestRef.story.tsx

@@ -0,0 +1,28 @@
+import { storiesOf } from '@storybook/react';
+import * as React from 'react';
+import { useLayoutLatestRef } from '../src';
+import ShowDocs from './util/ShowDocs';
+
+const Demo = () => {
+  const [count, setCount] = React.useState(0);
+  const latestCount = useLayoutLatestRef(count);
+  const timeoutMs = 3000;
+
+  function handleAlertClick() {
+    setTimeout(() => {
+      alert(`Latest count value: ${latestCount.current}`);
+    }, timeoutMs);
+  }
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>Click me</button>
+      <button onClick={handleAlertClick}>Show alert in {timeoutMs / 1000}s</button>
+    </div>
+  );
+};
+
+storiesOf('State/useLayoutLatestRef', module)
+  .add('Docs', () => <ShowDocs md={require('../docs/useLayoutLatestRef.md')} />)
+  .add('Demo', () => <Demo />);

tests/useLatestRef.test.ts

@@ -0,0 +1,23 @@
+import { renderHook } from '@testing-library/react-hooks';
+import useLatestRef from '../src/useLatestRef';
+
+const setUp = () => renderHook(({ state }) => useLatestRef(state), { initialProps: { state: 0 } });
+
+it('should return a ref with the latest value on initial render', () => {
+  const { result } = setUp();
+
+  expect(result.current).toEqual({ current: 0 });
+});
+
+it('should always return a ref with the latest value after each update', () => {
+  const { result, rerender } = setUp();
+
+  rerender({ state: 2 });
+  expect(result.current).toEqual({ current: 2 });
+
+  rerender({ state: 4 });
+  expect(result.current).toEqual({ current: 4 });
+
+  rerender({ state: 6 });
+  expect(result.current).toEqual({ current: 6 });
+});

tests/useLayoutLatestRef.test.ts

@@ -0,0 +1,24 @@
+import { renderHook } from '@testing-library/react-hooks';
+import useLayoutLatestRef from '../src/useLayoutLatestRef';
+
+const setUp = () =>
+  renderHook(({ state }) => useLayoutLatestRef(state), { initialProps: { state: 0 } });
+
+it('should return a ref with the latest value on initial render', () => {
+  const { result } = setUp();
+
+  expect(result.current).toEqual({ current: 0 });
+});
+
+it('should always return a ref with the latest value after each update', () => {
+  const { result, rerender } = setUp();
+
+  rerender({ state: 2 });
+  expect(result.current).toEqual({ current: 2 });
+
+  rerender({ state: 4 });
+  expect(result.current).toEqual({ current: 4 });
+
+  rerender({ state: 6 });
+  expect(result.current).toEqual({ current: 6 });
+});