@take-out/hooks 0.0.28

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './useClickOutside'
+export * from './useDebouncePrepend'
+export * from './useDeepMemoizedObject'
+export * from './useDeferredBoolean'
+export * from './useEffectOnceGlobally'
+export * from './useIsMounted'
+export * from './useLastValue'
+export * from './useLastValueIf'
+export * from './useMemoizedObjectList'
+export * from './useMemoStable'
+export * from './useThrottle'
+export * from './useWarnIfDepsChange'
+export * from './useWarnIfMemoChangesOften'

package/src/useClickOutside.ts

@@ -0,0 +1,34 @@
+import { useEffect } from 'react'
+import { isWeb, type TamaguiElement } from 'tamagui'
+
+type UseClickOutsideProps = {
+  ref: React.RefObject<TamaguiElement | null>
+  active: boolean
+  onClickOutside?: () => void
+}
+
+export const useClickOutside = ({
+  ref,
+  active,
+  onClickOutside,
+}: UseClickOutsideProps) => {
+  useEffect(() => {
+    if (!isWeb) return
+    if (!active) return
+    if (!onClickOutside) return
+
+    const handleClickOutside = (e: MouseEvent) => {
+      const node = ref.current as HTMLElement
+      if (!node) return
+      if (!(e.target instanceof HTMLElement)) return
+      if (!node.contains(e.target)) {
+        onClickOutside()
+      }
+    }
+
+    document.addEventListener('click', handleClickOutside)
+    return () => {
+      document.removeEventListener('click', handleClickOutside)
+    }
+  }, [ref, active, onClickOutside])
+}

package/src/useDebouncePrepend.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { debounce } from 'tamagui'
+
+export function useDebouncePrepend<T extends readonly { id: any }[]>(
+  list: T,
+  delay: number
+): T {
+  const [current, setCurrent] = useState(list)
+  const [previous, setPrevious] = useState(list)
+  const [pendingUpdate, setPendingUpdate] = useState<T | null>(null)
+
+  const debouncedUpdate = useMemo(() => {
+    return debounce((newList: T) => {
+      setCurrent(newList)
+      setPendingUpdate(null)
+    }, delay)
+  }, [delay])
+
+  const updateState = useCallback(
+    (newList: T) => {
+      setCurrent((prevCurrent) => {
+        // If there's a pending update, use the most recent list
+        const currentList = pendingUpdate || prevCurrent
+
+        // Check if we're prepending by comparing with the actual previous state
+        const isPrepending =
+          newList.length > previous.length && newList[0]?.id !== previous[0]?.id
+
+        if (isPrepending) {
+          // Cancel any existing debounced update
+          debouncedUpdate.cancel()
+          setPendingUpdate(newList)
+          debouncedUpdate(newList)
+          return currentList // Keep current state until debounced update fires
+        }
+
+        // Immediate update for non-prepending changes
+        debouncedUpdate.cancel()
+        setPendingUpdate(null)
+        return newList
+      })
+    },
+    [previous, pendingUpdate, debouncedUpdate]
+  )
+
+  useEffect(() => {
+    if (list === previous) {
+      return
+    }
+
+    // Update previous state
+    setPrevious(list)
+
+    // Update current state with concurrent safety
+    updateState(list)
+
+    return () => {
+      debouncedUpdate.cancel()
+    }
+  }, [list, previous, updateState, debouncedUpdate])
+
+  return current
+}

package/src/useDeepMemoizedObject.test.ts

@@ -0,0 +1,343 @@
+import { describe, expect, it } from 'vitest'
+import { deepMemoize, type Options } from './useDeepMemoizedObject'
+
+function testMemoization<T>(
+  initialValue: T,
+  options?: Options
+): { current: T; update: (value: T) => void } {
+  let previousValue = initialValue
+
+  return {
+    get current() {
+      return previousValue
+    },
+    update(value: T) {
+      previousValue = deepMemoize(
+        value,
+        previousValue,
+        [],
+        options?.immutableToNestedChanges
+      )
+    },
+  }
+}
+
+describe('useDeepMemoizedObject', () => {
+  it('should preserve identity for unchanged primitives', () => {
+    const hook = testMemoization(42)
+    const firstResult = hook.current
+    hook.update(42)
+    expect(hook.current).toBe(firstResult)
+  })
+
+  it('should preserve identity for unchanged objects', () => {
+    const obj = { a: 1, b: 2 }
+    const hook = testMemoization(obj)
+    const firstResult = hook.current
+    hook.update({ a: 1, b: 2 })
+    expect(hook.current).toBe(firstResult)
+  })
+
+  it('should preserve identity for unchanged arrays', () => {
+    const arr = [1, 2, 3]
+    const hook = testMemoization(arr)
+    const firstResult = hook.current
+    hook.update([1, 2, 3])
+    expect(hook.current).toBe(firstResult)
+  })
+
+  it('should handle nested object changes correctly', () => {
+    const initial = {
+      server: {
+        id: 1,
+        channels: [
+          { id: 1, name: 'general' },
+          { id: 2, name: 'random' },
+          { id: 3, name: 'tech' },
+        ],
+      },
+    }
+
+    const hook = testMemoization(initial)
+    const firstResult = hook.current
+
+    const updated = {
+      server: {
+        id: 1,
+        channels: [
+          { id: 1, name: 'general-updated' },
+          { id: 2, name: 'random' },
+          { id: 3, name: 'tech' },
+        ],
+      },
+    }
+
+    hook.update(updated)
+    const secondResult = hook.current
+
+    expect(secondResult).not.toBe(firstResult)
+    expect(secondResult.server).not.toBe(firstResult.server)
+    expect(secondResult.server.channels).not.toBe(firstResult.server.channels)
+    expect(secondResult.server.channels[0]).not.toBe(firstResult.server.channels[0])
+    expect(secondResult.server.channels[1]).toBe(firstResult.server.channels[1])
+    expect(secondResult.server.channels[2]).toBe(firstResult.server.channels[2])
+  })
+
+  it('should handle deep nested changes in arrays', () => {
+    const initial = {
+      server: {
+        channels: [
+          {
+            id: 1,
+            messages: [
+              { id: 1, text: 'hi' },
+              { id: 2, text: 'hello' },
+              {
+                id: 3,
+                text: 'world',
+                reactions: [
+                  { emoji: '👍', count: 1 },
+                  { emoji: '❤️', count: 2 },
+                  { emoji: '😂', count: 3, updatedAt: '2024-01-01' },
+                  { emoji: '🎉', count: 4 },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    }
+
+    const hook = testMemoization(initial)
+    const firstResult = hook.current
+
+    const updated = JSON.parse(JSON.stringify(initial))
+    updated.server.channels[0].messages[2].reactions[2].updatedAt = '2024-01-02'
+
+    hook.update(updated)
+    const secondResult = hook.current
+
+    expect(secondResult).not.toBe(firstResult)
+    expect(secondResult.server).not.toBe(firstResult.server)
+    expect(secondResult.server.channels).not.toBe(firstResult.server.channels)
+    expect(secondResult.server.channels[0]).not.toBe(firstResult.server.channels[0])
+    expect(secondResult.server.channels[0]!.messages).not.toBe(
+      firstResult.server.channels[0]!.messages
+    )
+
+    expect(secondResult.server.channels[0]!.messages[0]).toBe(
+      firstResult.server.channels[0]!.messages[0]
+    )
+    expect(secondResult.server.channels[0]!.messages[1]).toBe(
+      firstResult.server.channels[0]!.messages[1]
+    )
+    expect(secondResult.server.channels[0]!.messages[2]).not.toBe(
+      firstResult.server.channels[0]!.messages[2]
+    )
+
+    expect(secondResult.server.channels[0]!.messages[2]!.reactions).not.toBe(
+      firstResult.server.channels[0]!.messages[2]!.reactions
+    )
+    expect(secondResult.server.channels[0]!.messages[2]!.reactions![0]).toBe(
+      firstResult.server.channels[0]!.messages[2]!.reactions![0]
+    )
+    expect(secondResult.server.channels[0]!.messages[2]!.reactions![1]).toBe(
+      firstResult.server.channels[0]!.messages[2]!.reactions![1]
+    )
+    expect(secondResult.server.channels[0]!.messages[2]!.reactions![2]).not.toBe(
+      firstResult.server.channels[0]!.messages[2]!.reactions![2]
+    )
+    expect(secondResult.server.channels[0]!.messages[2]!.reactions![3]).toBe(
+      firstResult.server.channels[0]!.messages[2]!.reactions![3]
+    )
+  })
+
+  it('should respect immutableToNestedChanges option', () => {
+    const initial = {
+      server: {
+        id: 1,
+        channels: [
+          {
+            id: 1,
+            messages: [
+              { id: 1, text: 'hi' },
+              { id: 2, text: 'hello' },
+              { id: 3, text: 'world' },
+              { id: 4, text: 'foo' },
+              { id: 5, text: 'bar' },
+              {
+                id: 6,
+                text: 'baz',
+                reactions: [
+                  { emoji: '👍', count: 1 },
+                  { emoji: '❤️', count: 2 },
+                  { emoji: '😂', count: 3, updatedAt: '2024-01-01' },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    }
+
+    const hook = testMemoization(initial, {
+      immutableToNestedChanges: {
+        server: true,
+        'server.channels.0': true,
+      },
+    })
+
+    const firstResult = hook.current
+    // Save original references before mutation
+    const originalChannels = firstResult.server.channels
+    const originalChannel0 = firstResult.server.channels[0]
+    const originalMessages = firstResult.server.channels[0]!.messages
+    const originalMessage5 = firstResult.server.channels[0]!.messages[5]
+    const originalReactions = firstResult.server.channels[0]!.messages[5]!.reactions
+
+    const updated = JSON.parse(JSON.stringify(initial))
+    updated.server.channels[0].messages[5].reactions[2].updatedAt = '2024-01-02'
+
+    hook.update(updated)
+    const secondResult = hook.current
+
+    expect(secondResult).not.toBe(firstResult)
+    // server object should be the same reference
+    expect(secondResult.server).toBe(firstResult.server)
+    // channels array should be different (new array)
+    expect(secondResult.server.channels).not.toBe(originalChannels)
+    // channels[0] should be the same (marked as immutable)
+    expect(secondResult.server.channels[0]).toBe(originalChannel0)
+    // But its messages array should be different
+    expect(secondResult.server.channels[0]!.messages).not.toBe(originalMessages)
+    expect(secondResult.server.channels[0]!.messages[5]).not.toBe(originalMessage5)
+    expect(secondResult.server.channels[0]!.messages[5]!.reactions).not.toBe(
+      originalReactions
+    )
+    // Verify the actual change was applied
+    expect(secondResult.server.channels[0]!.messages[5]!.reactions![2]!.updatedAt).toBe(
+      '2024-01-02'
+    )
+  })
+
+  it('should handle adding new properties to objects', () => {
+    const initial = { a: 1, b: 2 }
+    const hook = testMemoization(initial)
+    const firstResult = hook.current
+    const updated = { a: 1, b: 2, c: 3 }
+
+    hook.update(updated)
+    expect(hook.current).not.toBe(firstResult)
+    expect(hook.current).toEqual(updated)
+  })
+
+  it('should handle array length changes', () => {
+    const initial = [1, 2, 3]
+    const hook = testMemoization(initial)
+    const firstResult = hook.current
+    hook.update([1, 2, 3, 4])
+    expect(hook.current).not.toBe(firstResult)
+    expect(hook.current).toEqual([1, 2, 3, 4])
+  })
+
+  it('should handle null and undefined values', () => {
+    const nullHook = testMemoization(null as any)
+    expect(nullHook.current).toBe(null)
+
+    nullHook.update(undefined as any)
+    expect(nullHook.current).toBe(undefined)
+
+    nullHook.update({ a: null, b: undefined })
+    const objResult = nullHook.current as any
+    expect(objResult.a).toBe(null)
+    expect(objResult.b).toBe(undefined)
+  })
+
+  it('should preserve array items when only one changes', () => {
+    const initial = [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
+      { id: 3, name: 'Charlie' },
+    ]
+
+    const hook = testMemoization(initial)
+    const firstResult = hook.current
+
+    const updated = [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bobby' },
+      { id: 3, name: 'Charlie' },
+    ]
+
+    hook.update(updated)
+    const secondResult = hook.current
+
+    expect(secondResult).not.toBe(firstResult)
+    expect(secondResult[0]).toBe(firstResult[0])
+    expect(secondResult[1]).not.toBe(firstResult[1])
+    expect(secondResult[2]).toBe(firstResult[2])
+  })
+
+  it('should handle complex immutableToNestedChanges patterns', () => {
+    const initial = {
+      app: {
+        settings: {
+          theme: 'dark',
+          language: 'en',
+          nested: {
+            deep: {
+              value: 1,
+            },
+          },
+        },
+      },
+    }
+
+    const hook = testMemoization(initial, {
+      immutableToNestedChanges: {
+        'app.settings': true,
+      },
+    })
+
+    const firstResult = hook.current
+    const originalSettings = firstResult.app.settings
+    const originalNested = firstResult.app.settings.nested
+    const originalDeep = firstResult.app.settings.nested.deep
+
+    const updated = JSON.parse(JSON.stringify(initial))
+    updated.app.settings.nested.deep.value = 2
+
+    hook.update(updated)
+    const secondResult = hook.current
+
+    expect(secondResult).not.toBe(firstResult)
+    expect(secondResult.app).not.toBe(firstResult.app)
+    // settings should be the same (marked as immutable)
+    expect(secondResult.app.settings).toBe(originalSettings)
+    // These should also be the same since settings is immutable and contains them
+    expect(secondResult.app.settings.nested).toBe(originalNested)
+    expect(secondResult.app.settings.nested.deep).toBe(originalDeep)
+    // But the value should have been mutated
+    expect(secondResult.app.settings.nested.deep.value).toBe(2)
+  })
+
+  it('should handle mixed arrays with objects and primitives', () => {
+    const initial = [1, 'string', { id: 1, name: 'object' }, [1, 2, 3], null, undefined]
+
+    const hook = testMemoization(initial)
+    const firstResult = hook.current
+
+    const updated = [1, 'string', { id: 1, name: 'updated' }, [1, 2, 3], null, undefined]
+
+    hook.update(updated)
+    const secondResult = hook.current
+
+    expect(secondResult).not.toBe(firstResult)
+    expect(secondResult[0]).toBe(1)
+    expect(secondResult[1]).toBe('string')
+    expect(secondResult[2]).not.toBe(firstResult[2])
+    expect(secondResult[3]).toBe(firstResult[3])
+    expect(secondResult[4]).toBe(null)
+    expect(secondResult[5]).toBe(undefined)
+  })
+})

package/src/useDeepMemoizedObject.ts

@@ -0,0 +1,231 @@
+import { useRef } from 'react'
+
+export type ImmutableToNestedChanges = Record<string, boolean>
+
+export interface Options {
+  immutableToNestedChanges?: ImmutableToNestedChanges
+}
+
+export function shouldBeImmutable(
+  path: string[],
+  immutableToNestedChanges?: ImmutableToNestedChanges
+): boolean {
+  if (!immutableToNestedChanges) return false
+
+  const currentPath = path.join('.')
+  for (const pattern in immutableToNestedChanges) {
+    if (immutableToNestedChanges[pattern] && currentPath === pattern) {
+      return true
+    }
+  }
+  return false
+}
+
+interface MemoResult<T> {
+  value: T
+  hasChanges: boolean
+  hasImmutableMutation: boolean
+}
+
+function deepMutateInPlace<T>(target: T, source: T): void {
+  if (
+    typeof target !== 'object' ||
+    target === null ||
+    typeof source !== 'object' ||
+    source === null
+  ) {
+    return
+  }
+
+  if (Array.isArray(target) && Array.isArray(source)) {
+    // For arrays, replace contents
+    ;(target as any[]).length = 0
+    ;(target as any[]).push(...(source as any[]))
+    return
+  }
+
+  // For objects, recursively mutate
+  for (const key in source as any) {
+    const targetValue = (target as any)[key]
+    const sourceValue = (source as any)[key]
+
+    if (
+      typeof sourceValue === 'object' &&
+      sourceValue !== null &&
+      typeof targetValue === 'object' &&
+      targetValue !== null
+    ) {
+      // Recursively mutate nested objects/arrays
+      deepMutateInPlace(targetValue, sourceValue)
+    } else {
+      // Replace primitive values or null/undefined
+      ;(target as any)[key] = sourceValue
+    }
+  }
+}
+
+function deepMemoizeWithTracking<T>(
+  current: T,
+  previous: T,
+  path: string[],
+  immutableToNestedChanges?: ImmutableToNestedChanges,
+  parentIsImmutable: boolean = false
+): MemoResult<T> {
+  if (current === previous) {
+    return { value: previous, hasChanges: false, hasImmutableMutation: false }
+  }
+
+  if (typeof current !== 'object' || current === null) {
+    return { value: current, hasChanges: true, hasImmutableMutation: false }
+  }
+
+  if (typeof previous !== 'object' || previous === null) {
+    return { value: current, hasChanges: true, hasImmutableMutation: false }
+  }
+
+  const isCurrentImmutable = shouldBeImmutable(path, immutableToNestedChanges)
+  const shouldMutateInPlace = isCurrentImmutable || parentIsImmutable
+
+  if (Array.isArray(current)) {
+    if (!Array.isArray(previous)) {
+      return { value: current, hasChanges: true, hasImmutableMutation: false }
+    }
+    if (current.length !== previous.length) {
+      return { value: current, hasChanges: true, hasImmutableMutation: false }
+    }
+
+    let hasChanges = false
+    let hasImmutableMutation = false
+    const memoizedArray: any[] = []
+
+    for (let i = 0; i < current.length; i++) {
+      const itemPath = [...path, String(i)]
+      // Pass down whether the parent is immutable BUT arrays are special
+      // Items in arrays can be immutable themselves, but arrays should never be mutated in place
+      const result = deepMemoizeWithTracking(
+        current[i],
+        previous[i],
+        itemPath,
+        immutableToNestedChanges,
+        false
+      )
+      memoizedArray[i] = result.value
+      if (result.hasChanges) {
+        hasChanges = true
+      }
+      if (result.hasImmutableMutation) {
+        hasImmutableMutation = true
+      }
+    }
+
+    // Arrays are NEVER immutable themselves, always create new array if contents changed OR if there were immutable mutations
+    if (hasChanges || hasImmutableMutation) {
+      return { value: memoizedArray as T, hasChanges: true, hasImmutableMutation: false }
+    }
+    return { value: previous, hasChanges: false, hasImmutableMutation: false }
+  }
+
+  const currentKeys = Object.keys(current)
+  const previousKeys = Object.keys(previous)
+
+  if (currentKeys.length !== previousKeys.length) {
+    return { value: current, hasChanges: true, hasImmutableMutation: false }
+  }
+
+  const keysMatch = currentKeys.every((key) => key in previous)
+  if (!keysMatch) {
+    return { value: current, hasChanges: true, hasImmutableMutation: false }
+  }
+
+  let hasChanges = false
+  let hasImmutableMutation = false
+  const memoizedObject: any = {}
+
+  for (const key of currentKeys) {
+    const propPath = [...path, key]
+    const currentValue = (current as any)[key]
+    const previousValue = (previous as any)[key]
+
+    // Pass down whether this object is immutable
+    const result = deepMemoizeWithTracking(
+      currentValue,
+      previousValue,
+      propPath,
+      immutableToNestedChanges,
+      shouldMutateInPlace
+    )
+
+    memoizedObject[key] = result.value
+    if (result.hasChanges) {
+      hasChanges = true
+    }
+    if (result.hasImmutableMutation) {
+      hasImmutableMutation = true
+    }
+  }
+
+  if (shouldMutateInPlace && (hasChanges || hasImmutableMutation)) {
+    // This object is immutable - keep the same reference but update properties
+    // Deep mutate the previous object in place
+    if (parentIsImmutable) {
+      // If parent is already immutable, we're nested and need to mutate everything in place
+      deepMutateInPlace(previous, current)
+    } else {
+      // Just mutate the direct properties
+      for (const key of currentKeys) {
+        ;(previous as any)[key] = memoizedObject[key]
+      }
+    }
+    // Return that this was an immutable mutation
+    return { value: previous, hasChanges: false, hasImmutableMutation: true }
+  }
+
+  if (hasChanges || hasImmutableMutation) {
+    return { value: memoizedObject, hasChanges: true, hasImmutableMutation: false }
+  }
+
+  return { value: previous, hasChanges: false, hasImmutableMutation: false }
+}
+
+export function deepMemoize<T>(
+  current: T,
+  previous: T,
+  path: string[] = [],
+  immutableToNestedChanges?: ImmutableToNestedChanges
+): T {
+  const result = deepMemoizeWithTracking(
+    current,
+    previous,
+    path,
+    immutableToNestedChanges,
+    false
+  )
+
+  // If root has immutable mutation but no changes, we need to force a new reference
+  if (path.length === 0 && result.hasImmutableMutation && !result.hasChanges) {
+    // The root itself was immutable and mutated, or contains immutable mutations
+    // We need to ensure the root reference changes
+    if (Array.isArray(result.value)) {
+      return [...result.value] as T
+    } else if (typeof result.value === 'object' && result.value !== null) {
+      return { ...result.value }
+    }
+  }
+
+  return result.value
+}
+
+export function useDeepMemoizedObject<T>(value: T, options?: Options): T {
+  const previousValueRef = useRef<T>(value)
+
+  const memoizedValue = deepMemoize(
+    value,
+    previousValueRef.current,
+    [],
+    options?.immutableToNestedChanges
+  )
+
+  previousValueRef.current = memoizedValue
+
+  return memoizedValue
+}

package/src/useDeferredBoolean.tsx

@@ -0,0 +1,15 @@
+import { useState, startTransition, useEffect } from 'react'
+
+export const useDeferredBoolean = (inVal: boolean): boolean => {
+  const [val, setVal] = useState(inVal)
+
+  useEffect(() => {
+    if (val !== inVal) {
+      startTransition(() => {
+        setVal(inVal)
+      })
+    }
+  }, [inVal, val])
+
+  return val
+}