docs: add use-singleton

Author: SukkaW

docs/src/pages/_meta.json

@@ -46,6 +46,7 @@
   "use-is-client": {},
   "use-isomorphic-layout-effect": {},
   "use-retimer": {},
+  "use-singleton": {},
   "use-stable-handler-only-when-you-know-what-you-are-doing-or-you-will-be-fired": {
     "title": "useStableHandler"
   },

docs/src/pages/use-singleton.mdx

@@ -0,0 +1,59 @@
+---
+title: useSingleton
+---
+
+# useSingleton
+
+import ExportMetaInfo from '../components/export-meta-info';
+
+<ExportMetaInfo />
+
+The React documentation's ["Avoiding recreating the ref contents" pattern](https://react.dev/reference/react/useRef#avoiding-recreating-the-ref-contents) as a hook.
+
+**Before:**
+
+```tsx
+function Video() {
+  const playerRef = useRef(null);
+  if (playerRef.current === null) {
+    playerRef.current = new VideoPlayer();
+  }
+  // ...
+```
+
+**After:**
+
+```tsx
+function Video() {
+  const playerRef = useSingleton(() => new VideoPlayer());
+  // ...
+```
+
+## Usage
+
+```tsx copy
+import { useCallback, useEffect } from 'react';
+import { useSingleton } from 'foxact/use-singleton';
+
+interface VideoProps {
+  videoSrc: string;
+}
+
+function Video({ videoSrc }: VideoProps) {
+  const playerRef = useSingleton(() => new VideoPlayer());
+
+  // callback ref to attach the player to the video element
+  const videoElementCallbackRef = useCallback((el: HTMLVideoElement | null) => {
+    if (el) {
+      playerRef.current.attach(el);
+      playerRef.current.load(videoSrc);
+    } else {
+      playerRef.current.destroy();
+    }
+  }, [videoSrc]);
+
+  return <video ref={videoElementCallbackRef} />;
+}
+```
+
+

src/use-singleton/index.ts

@@ -6,17 +6,16 @@ export interface SingletonRefObject<T> {
   readonly current: T
 }
 
+/** @see https://foxact.skk.moe/use-singleton */
 export const useSingleton = <T>(initializor: () => T): SingletonRefObject<T> => {
   const r = useRef<T>();
-
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- it will be undefined only on first render
   if (!r.current) {
     r.current = initializor();
   }
 
   // We are using singleton approach here, to prevent repeated initialization.
   // The value will only be written by the hook during the first render and it
-  // should not be written by anyone else
+  // should not be written by anyone else anymore
   // @ts-expect-error -- see above
   return r;
 };