@o/hooks 0.16.19-canary.1790165522484

package/src/useDeepMemoizedObject.test.ts

@@ -0,0 +1,344 @@
+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
+}

package/src/useEffectOnceGlobally.ts

@@ -0,0 +1,41 @@
+import { useEffect } from 'react'
+
+const executedKeys = new Set<string>()
+
+type WithId = { id: string }
+
+type KeyType<T> = string | string[] | WithId | WithId[] | readonly WithId[] | undefined
+
+/**
+ * Hook that ensures an effect only runs once globally across all component instances
+ * Uses a key (or array of keys) to determine if the effect has already been executed
+ */
+export function useEffectOnceGlobally<T extends KeyType<T>>(
+  key: T,
+  callback: T extends undefined ? () => void : (value: NonNullable<T>) => void
+) {
+  const keyString = !key
+    ? undefined
+    : typeof key === 'string'
+      ? key
+      : Array.isArray(key)
+        ? typeof key[0] === 'string'
+          ? (key as string[]).sort().join('')
+          : (key as readonly WithId[])
+              .map((item) => item.id)
+              .sort()
+              .join('')
+        : (key as WithId).id
+
+  useEffect(() => {
+    if (!keyString || executedKeys.has(keyString)) {
+      return
+    }
+    executedKeys.add(keyString)
+    if (key !== undefined) {
+      ;(callback as (value: NonNullable<T>) => void)(key as NonNullable<T>)
+    } else {
+      ;(callback as () => void)()
+    }
+  }, [keyString, callback, key])
+}

package/src/useEvent.ts

@@ -0,0 +1,7 @@
+import { useCallback, useRef } from 'react'
+
+export function useEvent<T extends (...args: any[]) => any>(fn: T): T {
+  const ref = useRef(fn)
+  ref.current = fn
+  return useCallback((...args: Parameters<T>) => ref.current(...args), []) as T
+}

package/src/useIsMounted.ts

@@ -0,0 +1,11 @@
+import { useEffect, useState } from 'react'
+
+export const useIsMounted = () => {
+  const [state, setState] = useState(false)
+
+  useEffect(() => {
+    setState(true)
+  }, [])
+
+  return state
+}

package/src/useLastValue.ts

@@ -0,0 +1,5 @@
+import { useLastValueIf } from './useLastValueIf'
+
+export function useLastValue<T>(value: T): T | undefined {
+  return useLastValueIf(value, true)
+}

package/src/useLastValueIf.ts

@@ -0,0 +1,15 @@
+import { useRef } from 'react'
+
+export function useLastValueIf<T>(value: T, keepLast = true): T | undefined {
+  // sorted [newest, older]
+  const lastTwoValuesRef = useRef<(T | undefined)[]>([])
+
+  const [latest] = lastTwoValuesRef.current
+  if (keepLast) {
+    if (latest !== value) {
+      lastTwoValuesRef.current = [value, latest]
+    }
+  }
+
+  return lastTwoValuesRef.current[1]
+}

package/src/useMemoStable.ts

@@ -0,0 +1,25 @@
+import { useMemo } from 'react'
+
+import { useWarnIfDepsChange } from './useWarnIfDepsChange'
+
+// create a useMemo that can log when it changes too often
+// useful for development
+
+export interface UseMemoStableOptions {
+  maxChanges?: number
+  ignoreIndexBefore?: number
+  name: string
+}
+
+export function useMemoStable<Value, T extends readonly unknown[]>(
+  getValue: () => Value,
+  deps: T,
+  options: UseMemoStableOptions = {
+    name: `(untitled)`,
+  }
+): Value {
+  useWarnIfDepsChange(deps, options)
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useMemo(getValue, deps)
+}