Merge pull request #22 from react-restart/new-effects

New effects

Author: jquense

src/useCallbackRef.ts

@@ -21,6 +21,8 @@ import { useState } from 'react'
  *
  * return <div ref={attachRef} />
  * ```
+ *
+ * @category refs
  */
 export default function useCallbackRef<TValue = unknown>(): [
   TValue | null,

src/useImmediateUpdateEffect.ts

@@ -14,6 +14,8 @@ import useStableMemo from './useStableMemo'
  *     setValue(value)
  *   }, [value])
  * ```
+ *
+ * @category effects
  */
 function useImmediateUpdateEffect(effect: () => void, deps: DependencyList) {
   const firstRef = useRef(true)

src/useIsomorphicEffect.ts

@@ -14,5 +14,7 @@ const isDOM = typeof document !== 'undefined'
  * Only useful to avoid the console warning.
  *
  * PREFER `useEffect` UNLESS YOU KNOW WHAT YOU ARE DOING.
+ *
+ * @category effects
  */
 export default isDOM || isReactNative ? useLayoutEffect : useEffect

src/useMergedRefs.ts

@@ -33,6 +33,7 @@ export function mergeRefs<T>(refA?: Ref<T> | null, refB?: Ref<T> | null) {
  *
  * @param refA A Callback or mutable Ref
  * @param refB A Callback or mutable Ref
+ * @category refs
  */
 function useMergedRefs<T>(refA?: Ref<T> | null, refB?: Ref<T> | null) {
   return useMemo(() => mergeRefs(refA, refB), [refA, refB])

src/useMountEffect.ts

@@ -0,0 +1,24 @@
+import { useEffect, EffectCallback } from 'react'
+
+/**
+ * Run's an effect on mount, and is cleaned up on unmount. Generally
+ * useful for interop with non-react plugins or components
+ *
+ * ```ts
+ *  useMountEffect(() => {
+ *    const plugin = $.myPlugin(ref.current)
+ *
+ *    return () => {
+ *      plugin.destroy()
+ *    }
+ *  })
+ * ```
+ * @param effect An effect to run on mount
+ *
+ *  @category effects
+ */
+function useMountEffect(effect: EffectCallback) {
+  return useEffect(effect, [])
+}
+
+export default useMountEffect

src/useRefWithInitialValueFactory.ts

@@ -0,0 +1,25 @@
+import { useRef } from 'react'
+
+const dft: any = Symbol('default value sigil')
+
+/**
+ * Exactly the same as `useRef` except that the initial value is set via a
+ * factroy function. Useful when the default is relatively costly to construct.
+ *
+ *  ```ts
+ *  const ref = useRefWithInitialValueFactory<ExpensiveValue>(() => constructExpensiveValue())
+ *
+ *  ```
+ *
+ * @param initialValueFactory A factory function returning the ref's default value
+ * @category refs
+ */
+export default function useRefWithInitialValueFactory<T>(
+  initialValueFactory: () => T,
+) {
+  const ref = useRef<T>(dft)
+  if (ref.current === dft) {
+    ref.current = initialValueFactory()
+  }
+  return ref
+}

src/useUpdateEffect.ts

@@ -0,0 +1,34 @@
+import { useEffect, EffectCallback, DependencyList, useRef } from 'react'
+
+/**
+ * Runs an effect only when the dependencies have changed, skipping the
+ * initial "on mount" run. Caution, if the dependency list never changes,
+ * the effect is **never run**
+ *
+ * ```ts
+ *  const ref = useRef<HTMLInput>(null);
+ *
+ *  // focuses an element only if the focus changes, and not on mount
+ *  useUpdateEffect(() => {
+ *    const element = ref.current?.children[focusedIdx] as HTMLElement
+ *
+ *    element?.focus()
+ *
+ *  }, [focusedIndex])
+ * ```
+ * @param effect An effect to run on mount
+ *
+ * @category effects
+ */
+function useUpdateEffect(fn: EffectCallback, deps: DependencyList) {
+  const isFirst = useRef(true)
+  useEffect(() => {
+    if (isFirst.current) {
+      isFirst.current = false
+      return
+    }
+    return fn()
+  }, deps)
+}
+
+export default useUpdateEffect

src/useUpdatedRef.ts

@@ -4,6 +4,7 @@ import { useRef } from 'react'
  * Returns a ref that is immediately updated with the new value
  *
  * @param value The Ref value
+ * @category refs
  */
 export default function useUpdatedRef<T>(value: T) {
   const valueRef = useRef<T>(value)

src/useWillUnmount.ts

@@ -5,6 +5,7 @@ import { useEffect } from 'react'
  * Attach a callback that fires when a component unmounts
  *
  * @param fn Handler to run when the component unmounts
+ * @category effects
  */
 export default function useWillUnmount(fn: () => void) {
   const onUnmount = useUpdatedRef(fn)

test/useImmediateUpdateEffect.test.tsx

@@ -2,7 +2,7 @@ import useImmediateUpdateEffect from '../src/useImmediateUpdateEffect'
 import { renderHook } from './helpers'
 
 describe('useImmediateUpdateEffect', () => {
-  it('should return a function that returns mount state', () => {
+  it('should run update after value changes', () => {
     const spy = jest.fn()
 
     const [, wrapper] = renderHook(