useClearableState.ts

import { useCallback, useState, useMemo } from 'react';

/**
 * Custom React hook to manage state with clearable functionality.
 *
 * @template ValueType The type of the state value.
 * @template ClearType The type representing the cleared value.
 *
 * @param {ValueType | ClearType} initialValue - The initial value of the state.
 * @param {ClearType} clearValue - The value to which the state will be cleared.
 *
 * @returns {{value: ValueType | ClearType, setValue: function, clear: function} | [ValueType | ClearType, function, function]} Either an object API or array API.
 *
 * @example
 * // Using Object API
 * const { value, setValue, clear } = useClearableState(0, undefined);
 * setValue(10);  // value becomes 10
 * clear();       // value becomes undefined
 *
 * @example
 * // Using Array API
 * const [value, setValue, clear] = useClearableState('initial', '');
 * setValue('updated'); // value becomes 'updated'
 * clear();             // value becomes ''
 */
export function useClearableState<ValueType = unknown, ClearType = unknown>(
  initialValue: ValueType | ClearType,
  clearValue: ClearType
) {
  const [value, setValue] = useState<ValueType | ClearType>(initialValue);

  const clear = useCallback(() => {
    setValue(clearValue);
  }, [clearValue]);

  // Create an object and array API that are combined into a single return value
  const combinedApi = useMemo(() => {
    const arrApi = [value, setValue, clear] as const;
    const objApi = {
      value,
      setValue,
      clear,
    };

    return Object.assign(arrApi, objApi);
  }, [clear, value]);

  return combinedApi;
}

/**
 * Custom React hook to manage state with a nullable initial value.
 *
 * @template ValueType The type of the state value.
 *
 * @param {ValueType | null} [initialValue=null] - The initial value of the state.
 *
 * @returns {{value: ValueType | null, setValue: function, clear: function} | [ValueType | null, function, function]} Either an object API or array API.
 *
 * @example
 * // Using Object API
 * const { value, setValue, clear } = useNullableState(10);
 * setValue(5);  // value becomes 5
 * clear();      // value becomes null
 *
 * @example
 * // Using Array API
 * const [value, setValue, clear] = useNullableState('initial');
 * setValue('updated'); // value becomes 'updated'
 * clear();             // value becomes null
 */
export function useNullableState<ValueType = unknown>(
  initialValue: ValueType | null = null
) {
  return useClearableState<ValueType, null>(initialValue, null);
}

/**
 * Custom React hook to manage a nullable number state with clearable functionality.
 *
 * @param {number | null} [initialValue=null] - The initial value of the state.
 *
 * @returns {object|array} Either an object API or array API:
 *
 * Object API:
 * - value: {number | null} The current value of the state.
 * - setValue: {function(newValue: number | null)} Function to set the value.
 * - clear: {function()} Function to clear the value.
 *
 * Array API:
 * - 0: {number | null} The current value of the state.
 * - 1: {function(newValue: number | null)} Function to set the value.
 * - 2: {function()} Function to clear the value.
 *
 * @example
 * const { value, setValue, clear } = useNullableNumber(10);
 * setValue(5); // value becomes 5
 * clear();        // value becomes null
 */
export function useNullableNumber(initialValue: number | null = null) {
  return useNullableState<number>(initialValue);
}

/**
 * Custom React hook to manage a string state that can be cleared to an empty string.
 *
 * @param {string} [initialValue=''] - The initial value of the state.
 *
 * @returns {object|array} Either an object API or array API:
 *
 * Object API:
 * - value: {string | ''} The current value of the state.
 * - setValue: {function(newValue: string | '')} Function to set the value.
 * - clear: {function()} Function to clear the value.
 *
 * Array API:
 * - 0: {string | ''} The current value of the state.
 * - 1: {function(newValue: string | '')} Function to set the value.
 * - 2: {function()} Function to clear the value.
 *
 * @example
 * const { value, setValue, clear } = useEmptyableString('Hello');
 * setValue('World'); // value becomes 'World'
 * clear();           // value becomes ''
 */
export function useEmptyableString(initialValue = '') {
  return useClearableState(initialValue, '');
}