feat: add pop, shift, unshift, push to useArray

refactoring: reuse of Actions types in object version
docs: added new APIs to the docs

Author: RIP21

README-ARRAY.md

@@ -104,7 +104,10 @@ const [todos, actions] = useArray([]);
 
 Actions:
 
-- `add`
+- `push`
+- `unshift`
+- `pop`
+- `shift`
 - `clear`
 - `removeIndex`
 - `removeById` - if array consists of objects with some specific `id` that you pass
@@ -130,7 +133,7 @@ const [anotherMap, anotherMapActions] = useMap(new Map([["key", "value"]]));
 Actions:
 
 - `set`
-- `remove`
+- `delete`
 - `clear`
 - `initialize` - applies tuples or map instances
 - `setValue`

README.md

@@ -163,7 +163,10 @@ const todos = useArray([]);
 
 Methods:
 
-- `add`
+- `push` - similar to native doesn't return length tho
+- `unshift` - similar to native doesn't return length tho
+- `pop` - similar to native doesn't return element tho
+- `shift` - similar to native doesn't return element tho
 - `clear`
 - `removeIndex`
 - `removeById` - if array consists of objects with some specific `id` that you pass
@@ -189,7 +192,7 @@ const { value: anotherValue, remove } = useMap(new Map([["key", "value"]]));
 Actions:
 
 - `set`
-- `remove`
+- `delete`
 - `clear`
 - `initialize` - applies tuples or map instances
 - `setValue`

src/array/index.test.ts

@@ -165,7 +165,7 @@ describe('useArray array', () => {
     const [, actions] = result.current;
     expect(result.current[0].length).toBe(0);
 
-    act(() => actions.add('test'));
+    act(() => actions.push('test'));
 
     expect(result.current[0].length).toBe(1);
   });
@@ -236,7 +236,7 @@ describe('useArray array', () => {
       const [, originalActionsReference] = result.current;
       expect(result.current[1]).toBe(originalActionsReference);
       // when
-      act(() => originalActionsReference.add(1));
+      act(() => originalActionsReference.push(1));
       // then
       expect(originalActionsReference).toBe(result.current[1]);
     });
@@ -317,14 +317,14 @@ describe('useMap array', () => {
     });
   });
 
-  describe('remove', () => {
+  describe('delete', () => {
     it('should delete existing value', () => {
       // given
       const { result } = renderHook(() => useMap<number, string>([[1, 'existing']]));
       const [, actions] = result.current;
       expect(result.current[0].get(1)).toBe('existing');
       // when
-      act(() => actions.remove(1));
+      act(() => actions.delete(1));
       // then
       expect(result.current[0].get(1)).toBeUndefined();
     });

src/array/useArray.ts

@@ -3,7 +3,11 @@ import { UseStateful } from '../useStateful';
 
 export type UseArrayActions<T> = {
   setValue: UseStateful<T[]>['setValue'];
-  add: (value: T) => void;
+  add: (value: T | T[]) => void;
+  push: (value: T | T[]) => void;
+  pop: () => void;
+  shift: () => void;
+  unshift: (value: T | T[]) => void;
   clear: () => void;
   move: (from: number, to: number) => void;
   removeById: (id: T extends { id: string } ? string : T extends { id: number } ? number : unknown) => void;
@@ -13,7 +17,12 @@ export type UseArray<T = any> = [T[], UseArrayActions<T>];
 
 export function useArray<T = any>(initial: T[]): UseArray<T> {
   const [value, setValue] = useState(initial);
-  const add = useCallback(a => setValue(v => [...v, a]), []);
+  const push = useCallback(a => {
+    setValue(v => [...v, ...(Array.isArray(a) ? a : [a])]);
+  }, []);
+  const unshift = useCallback(a => setValue(v => [...(Array.isArray(a) ? a : [a]), ...v]), []);
+  const pop = useCallback(() => setValue(v => v.slice(0, -1)), []);
+  const shift = useCallback(() => setValue(v => v.slice(1)), []);
   const move = useCallback(
     (from: number, to: number) =>
       setValue(it => {
@@ -41,14 +50,17 @@ export function useArray<T = any>(initial: T[]): UseArray<T> {
   const actions = useMemo(
     () => ({
       setValue,
-      add,
-      push: add,
+      add: push,
+      unshift,
+      push,
       move,
       clear,
       removeById,
       removeIndex,
+      pop,
+      shift,
     }),
-    [add, clear, move, removeById, removeIndex],
+    [push, unshift, move, clear, removeById, removeIndex, pop, shift],
   );
   return [value, actions];
 }

src/array/useMap.ts

@@ -1,14 +1,18 @@
 import { Dispatch, SetStateAction, useCallback, useMemo, useState } from 'react';
 
 export type MapOrEntries<K, V> = Map<K, V> | [K, V][];
-export type UseMapFunctions<K, V> = {
+export type UseMapActions<K, V> = {
   setValue: Dispatch<SetStateAction<Map<K, V>>>;
   remove: (keyToRemove: K) => void;
+  delete: (keyToRemove: K) => void;
   set: (key: K, value: V) => void;
   clear: Map<K, V>['clear'];
   initialize: (pairsOrMap: MapOrEntries<K, V>) => void;
 };
-export type UseMap<K, V> = [Map<K, V>, UseMapFunctions<K, V>];
+
+export type UseMapFunctions<K, V> = UseMapActions<K, V>; // TODO: Remove on the next major release
+
+export type UseMap<K, V> = [Map<K, V>, UseMapActions<K, V>];
 
 export function useMap<K, V>(initialState: MapOrEntries<K, V> = new Map()): UseMap<K, V> {
   const [map, setMap] = useState(Array.isArray(initialState) ? new Map(initialState) : initialState);

src/index.test.ts

@@ -135,12 +135,14 @@ describe('useSetState', () => {
 });
 
 describe('useArray', () => {
-  it('should add item', () => {
+  it('should push item', () => {
     const { result } = renderHook(() => useArray<string>([]));
-    const { add } = result.current;
+    const { push } = result.current;
     expect(result.current.value.length).toBe(0);
 
-    act(() => add('test'));
+    act(() => {
+      push('test');
+    });
 
     expect(result.current.value.length).toBe(1);
   });
@@ -208,12 +210,14 @@ describe('useArray', () => {
     it('should keep actions reference equality after value change', () => {
       // given
       const { result } = renderHook(() => useArray<any>([]));
-      const { add } = result.current;
-      expect(result.current.add).toBe(add);
+      const { push } = result.current;
+      expect(result.current.push).toBe(push);
       // when
-      act(() => add(1));
+      act(() => {
+        push(1);
+      });
       // then
-      expect(add).toBe(result.current.add);
+      expect(push).toBe(result.current.push);
     });
   });
 });
@@ -292,14 +296,14 @@ describe('useMap', () => {
     });
   });
 
-  describe('remove', () => {
+  describe('delete', () => {
     it('should delete existing value', () => {
       // given
       const { result } = renderHook(() => useMap<number, string>([[1, 'existing']]));
-      const { remove } = result.current;
+      const { delete: aDelete } = result.current;
       expect(result.current.value.get(1)).toBe('existing');
       // when
-      act(() => remove(1));
+      act(() => aDelete(1));
       // then
       expect(result.current.value.get(1)).toBeUndefined();
     });

src/useArray.ts

@@ -1,14 +1,8 @@
 import { useMemo } from 'react';
 import { UseStateful } from './useStateful';
-import useArrayArray from './array/useArray';
+import useArrayArray, { UseArrayActions } from './array/useArray';
 
-export type UseArray<T> = UseStateful<T[]> & {
-  add: (value: T) => void;
-  clear: () => void;
-  move: (from: number, to: number) => void;
-  removeById: (id: T extends { id: string } ? string : T extends { id: number } ? number : unknown) => void;
-  removeIndex: (index: number) => void;
-};
+export type UseArray<T> = UseStateful<T[]> & UseArrayActions<T>;
 
 export function useArray<T = any>(initial: T[]): UseArray<T> {
   const [value, actions] = useArrayArray(initial);

src/useBoolean.ts

@@ -1,14 +1,8 @@
-import * as React from 'react';
-import { SetStateAction, useMemo } from 'react';
-import useBooleanArray from './array/useBoolean';
+import { useMemo } from 'react';
+import useBooleanArray, { UseBooleanActions } from './array/useBoolean';
+import { UseStateful } from './useStateful';
 
-export type UseBoolean = {
-  value: boolean;
-  setValue: React.Dispatch<SetStateAction<boolean>>;
-  toggle: () => void;
-  setTrue: () => void;
-  setFalse: () => void;
-};
+export type UseBoolean = UseStateful<boolean> & UseBooleanActions;
 
 export function useBoolean(initial: boolean): UseBoolean {
   const [value, actions] = useBooleanArray(initial);

src/useMap.ts

@@ -1,14 +1,9 @@
 import { useMemo } from 'react';
 import { UseStateful } from './useStateful';
-import useMapArray from './array/useMap';
+import useMapArray, { UseMapActions } from './array/useMap';
 
 export type MapOrEntries<K, V> = Map<K, V> | [K, V][];
-export type UseMap<K, V> = UseStateful<Map<K, V>> & {
-  remove: (keyToRemove: K) => void;
-  set: (key: K, value: V) => void;
-  clear: Map<K, V>['clear'];
-  initialize: (pairsOrMap: MapOrEntries<K, V>) => void;
-};
+export type UseMap<K, V> = UseStateful<Map<K, V>> & UseMapActions<K, V>
 
 export function useMap<K, V>(initialState: MapOrEntries<K, V> = new Map()): UseMap<K, V> {
   const [map, actions] = useMapArray(initialState);

src/useNumber.ts

@@ -1,11 +1,8 @@
 import { useMemo } from 'react';
 import { UseStateful } from './useStateful';
-import useNumberArray from './array/useNumber';
+import useNumberArray, { UseNumberActions } from './array/useNumber';
 
-export type UseNumber = UseStateful<number> & {
-  increase: (value?: number) => void;
-  decrease: (value?: number) => void;
-};
+export type UseNumber = UseStateful<number> & UseNumberActions;
 
 export function useNumber(
   initial: number,