Feature: Add useArray hook

packages/usehooks-ts/src/index.ts

@@ -31,3 +31,4 @@ export * from './useTimeout'
 export * from './useToggle'
 export * from './useUnmount'
 export * from './useWindowSize'
+export * from './useArray'

packages/usehooks-ts/src/useArray/index.ts

@@ -0,0 +1 @@
+export * from './useArray'

packages/usehooks-ts/src/useArray/useArray.demo.tsx

@@ -0,0 +1,16 @@
+import { useArray } from './useArray'
+
+export default function Component() {
+  const { array, length, addOne, removeOne } = useArray<number>()
+
+  return <div>
+    {
+      array.map((value, index) => <div>
+          <p>Value: {value}</p>
+          <button onClick={() => removeOne(index)} />
+        </div>
+      )
+    }
+    <button onClick={() => addOne(length)}/>
+  </div>
+}

packages/usehooks-ts/src/useArray/useArray.md

@@ -0,0 +1,3 @@
+An abstraction to play with an array.
+
+This hook provides utility functions to handle an array.

packages/usehooks-ts/src/useArray/useArray.test.ts

@@ -0,0 +1,234 @@
+import { act, renderHook } from '@testing-library/react'
+
+import { useArray } from './useArray'
+
+describe('useArray()', () => {
+  it('should use the default array', () => {
+    const { result } = renderHook(() => useArray())
+    const { array, length } = result.current
+
+    expect(array).toStrictEqual([])
+    expect(length).toBe(0)
+  })
+
+  it('should use the given array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+    const { array, length } = result.current
+
+    expect(array).toStrictEqual(['a', 'b', 'c'])
+    expect(length).toBe(3)
+  })
+
+  it('should add one element in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.addOne('d')
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c', 'd'])
+    expect(result.current.length).toBe(4)
+  })
+
+  it('should add many elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.addMany(['d', 'e'])
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c', 'd', 'e'])
+    expect(result.current.length).toBe(5)
+  })
+
+  it('should setOne element in the array (updateOne)', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.setOne({ index: 0, change: 'd' })
+    })
+
+    expect(result.current.array).toStrictEqual(['d', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should setOne element in the array (addOne)', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.setOne({ index: 4, change: 'd' })
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c', 'd'])
+    expect(result.current.length).toBe(4)
+  })
+
+  it('should setMany elements in the array (update)', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.setMany([{ index: 0, change: 'd' }, { index: 1, change: 'e' }])
+    })
+
+    expect(result.current.array).toStrictEqual(['d', 'e', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should setMany elements in the array (add)', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.setMany([{ index: 4, change: 'd' }, { index: 5, change: 'e' }])
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c', 'd', 'e'])
+    expect(result.current.length).toBe(5)
+  })
+
+  it('should setMany elements in the array (add and update)', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.setMany([{ index: 0, change: 'd' }, { index: 4, change: 'e' }])
+    })
+
+    expect(result.current.array).toStrictEqual(['d', 'b', 'c', 'e'])
+    expect(result.current.length).toBe(4)
+  })
+
+  it('should setAll elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.setAll(['d', 'e'])
+    })
+
+    expect(result.current.array).toStrictEqual(['d', 'e'])
+    expect(result.current.length).toBe(2)
+  })
+
+  it('should removeOne element in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.removeOne(0)
+    })
+
+    expect(result.current.array).toStrictEqual(['b', 'c'])
+    expect(result.current.length).toBe(2)
+  })
+
+  it('should not removeOne element in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.removeOne(3)
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should removeMany elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.removeMany([0, 1])
+    })
+
+    expect(result.current.array).toStrictEqual(['c'])
+    expect(result.current.length).toBe(1)
+  })
+
+  it('should not removeMany elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.removeMany([3, 4])
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should removeAll elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.removeAll()
+    })
+
+    expect(result.current.array).toStrictEqual([])
+    expect(result.current.length).toBe(0)
+  })
+
+  it('should updateOne element in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.updateOne({ index: 0, change: 'd' })
+    })
+
+    expect(result.current.array).toStrictEqual(['d', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should not updateOne element in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.updateOne({ index: 5, change: 'd' })
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should updateMany elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.updateMany([{ index: 0, change: 'd' }, { index: 1, change: 'e' }])
+    })
+
+    expect(result.current.array).toStrictEqual(['d', 'e', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should reset the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.addMany(['d', 'e'])
+      result.current.reset()
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should not updateMany element in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    act(() => {
+      result.current.updateMany([{ index: 4, change: 'd' }, { index: 5, change: 'e' }])
+    })
+
+    expect(result.current.array).toStrictEqual(['a', 'b', 'c'])
+    expect(result.current.length).toBe(3)
+  })
+
+  it('should select elements in the array', () => {
+    const { result } = renderHook(() => useArray(['a', 'b', 'c']))
+
+    expect(result.current.select()).toStrictEqual(['a', 'b', 'c'])
+
+    expect(result.current.select((element) => element === 'a')).toStrictEqual(['a'])
+    expect(result.current.some((element) => element === 'a')).toBeTruthy()
+
+    expect(result.current.select((element) => element === 'd')).toStrictEqual([])
+    expect(result.current.some((element) => element === 'd')).toBeFalsy()
+  })
+
+})
+

packages/usehooks-ts/src/useArray/useArray.ts

@@ -0,0 +1,120 @@
+import { useCallback, useMemo, useState } from 'react'
+
+import type { Dispatch, SetStateAction } from 'react'
+
+/**
+ * Represents the type for the update of an element at a specific index in the array.
+ */
+type Update<T> = { index: number, change: T }
+
+/** The useArray return type. */
+type UseArrayReturnType<T> = {
+  /** The current array state value. */
+  array: Array<T>
+  /** Function to set the array state directly. */
+  setArray: Dispatch<SetStateAction<Array<T>>>
+  /** Length of the array state value. */
+  length: number
+  /** Function to add one element in the array state value. */
+  addOne: (element: T) => void
+  /** Function to add many elements in the array state value. */
+  addMany: (elements: Array<T>) => void
+  /** Function to update or add one element in the array state value. */
+  setOne: (element: Update<T>) => void
+  /** Function to update or add many elements in the array state value. */
+  setMany: (elements: Array<Update<T>>) => void
+  /** Function to replace all elements in the array state value.*/
+  setAll: (elements: Array<T>) => void
+  /** Function to remove one element in the array state value. */
+  removeOne: (index: number) => void
+  /** Function to remove many elements in the array state value. */
+  removeMany: (indexes: Array<number>) => void
+  /** Function to remove all elements in the array state value. */
+  removeAll: () => void
+  /** Function to update one element in the array state value. */
+  updateOne: (element: Update<T>) => void
+  /** Function to update many elements in the array state value. */
+  updateMany: (elements: Array<Update<T>>) => void
+  /** Function to reset the array state value with the feault value. */
+  reset: () => void
+  /** Function to return some elements of the array state value. */
+  select: (predicate?: (element: T, index: number, array: Array<T>) => unknown) => Array<T>
+  /** Function to return determine if elements of the array state value are presents or not. */
+  some: (predicate: (element: T, index: number, array: Array<T>) => unknown) => Boolean
+}
+
+/**
+ * Custom hook that handles array state with useful utility functions.
+ * @param {Array<T>} [defaultArray] - The initial value for the array state (default is `[]`).
+ * @returns {UseArrayReturnType} An object containing the array state value and utility functions to manipulate the state.
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-array)
+ * @example
+ * ```tsx
+ * const { array, setArray } = useArray<string>(['a', 'b', 'c']);
+ *
+ * console.log(value); // ['a', 'b', 'c']
+ * ```
+ */
+export function useArray<T>(
+  defaultArray?: Array<T>,
+): UseArrayReturnType<T> {
+  const [array, setArray] = useState(defaultArray || [])
+  const length = useMemo(() => array.length, [array])
+
+  const addOne = useCallback((element: T) => setArray([...array, element]), [array, setArray])
+
+  const addMany = useCallback((elements: Array<T>) => setArray([...array, ...elements]), [array, setArray])
+
+  const removeOne = useCallback((index: number) => setArray(array.filter((_, i) => i !== index)), [array, setArray])
+
+  const removeMany = useCallback((indexes: Array<number>) => setArray(array.filter((_, i) => !indexes.includes(i))), [array, setArray])
+
+  const removeAll = useCallback(() => setArray([]), [setArray])
+
+  const updateOne = useCallback(({ index, change}: Update<T>) => setArray(array.map((e, i) => index === i ? change : e)), [array, setArray])
+
+  const updateMany = useCallback((elements: Array<Update<T>>) => {
+    const newArray = [...array]
+    elements.forEach(({ index, change }) => {
+      if (!!array[index]) {
+        newArray[index] = change
+      }
+    })
+    setArray(newArray)
+  }, [array, setArray])
+
+  const setOne = useCallback(({ index, change }: Update<T>) => !!array[index] ? updateOne({ index, change }) : addOne(change), [array, updateOne, addOne])
+
+  const setMany = useCallback((elements: Array<Update<T>>) => {
+    const newArray = [...array]
+    elements.forEach(({ index, change }) => !!array[index] ? newArray[index] = change : newArray.push(change))
+    setArray(newArray)
+  }, [array, setArray])
+
+  const setAll = useCallback((elements: Array<T>) => setArray(elements), [setArray])
+
+  const reset = useCallback(() => setArray(defaultArray || []), [])
+
+  const select = useCallback((predicate?: (element: T, index: number, array: Array<T>) => unknown) => !!predicate ? array.filter(predicate) : array, [array])
+
+  const some = useCallback((predicate: (element: T, index: number, array: Array<T>) => unknown) => array.some(predicate), [array])
+
+  return {
+    array,
+    length,
+    setArray,
+    addOne,
+    addMany,
+    setOne,
+    setMany,
+    setAll,
+    removeOne,
+    removeMany,
+    removeAll,
+    updateOne,
+    updateMany,
+    reset,
+    select,
+    some
+  }
+}