Add a useSearchParam hook which returns a handle for reading/updating indvidual query params

[pyramid-scheme-ceo]

I know I can't be the only one who doesn't particularly love the approach for updating query params in react-router at the moment, so I'm proposing a useSearchParam hook which returns an accessor for a single search param at a time.

The value of the property is read and updated through the .current property. Implementation-wise, it is essentially a wrapper around the existing useSearchParams hook.

Note:
This is my first contribution to this repository, so just writing up this proposal first to see if it's useful and would potentially be included before going into more effort with the actual implementation, tests, PR, etc.

Example usage:

import { useSearchParam } from 'react-router-dom';

export const MyTable: () => {
  const page = useSearchParam('page', 'number', { defaultValue: 1 });
  const showDeleted = useSearchParam('showDeleted', 'boolean');
  const searchPhrase = useSearchParam('q', 'string');

  // react-query or however else you query your data
  const { data, isLoading } = useQuery({
    queryKey: ['my-data', page.current, showDeleted.current, searchPhrase.current],
    queryFn: service.getData(page.current, showDeleted.current, searchPhrase.current),
  });

  return (
    <div className="container">
      <div className="toolbar">
        <input type="checkbox" value="showDeleted" onChange={e => showDeleted.current = e.target.checked} />
        <input type="text" value={searchPhrase.current} onChange={e => searchPhrase.current = e.target.value} />
      </div>
      <table>
        ...
      </table>
      <PageSelector page={page.current} onChange={val => page.current = val} />
    </div>
  );
}

Work-in-progress implementation:

type SearchParamType = 'string' | 'number';
type SearchParam<T> = { current: T | null };
type ParamTypeMappings = { 'string': string, 'number': number };
type UseSearchParamConfiguration<T> = {
  defaultValue?: T;
};

function useSearchParam<T extends SearchParamType>(key: string, type: T, configuration?: UseSearchParamConfiguration<T>): SearchParam<ParamTypeMappings[T]> {
  const [searchParams, setSearchParams] = useSearchParams();

  switch (type) {
    case 'string':
      return {
        get current(): ParamTypeMappings[T] {
          return (searchParams.has(key) ? searchParams.get(key) : configuration?.defaultValue || null) as string | null as ParamTypeMappings[T];
        },
        set current(value: ParamTypeMappings[T]) {
          setSearchParams((prev) => new URLSearchParams({
            ...Object.fromEntries(prev),
            [key]: value as string,
          }));
        },
      };

    case 'number':
      return {
        get current(): ParamTypeMappings[T] {
          const value = searchParams.has(key) ? searchParams.get(key) : configuration?.defaultValue || null;
          if (value && Number.isFinite(value)) {
            return (Number.isInteger(value) ? parseInt(value) : parseFloat(value)) as number as ParamTypeMappings[T];
          }

          return null as unknown as ParamTypeMappings[T];
        },
        set current(value: ParamTypeMappings[T]) {
          setSearchParams((prev) => new URLSearchParams({
            ...Object.fromEntries(prev),
            [key]: (value as number).toString(),
          }));
        },
      }

    default:
      throw new Error('Unexpected search param type');
  }
}

[pyramid-scheme-ceo]

Fyi did some more work - here's the implementation with a bit more of a focus on extensibility now:

/**
 * Valid types for search parameters.
 */
type SearchParamType = 'date' | 'number' | 'number[]' | 'string';

/**
 * Mappings from names of types (from the SearchParamType type) to their actual TS types.
 */
type ParamTypeMappings = {
    'date': Date,
    'number': number,
    'number[]': number[],
    'string': string,
};

/**
 * Configuration for the useSearchParam hook.
 */
type UseSearchParamConfiguration<T extends SearchParamType> = {
    /**
     * Default value for the parameter.
     */
    defaultValue?: ParamTypeMappings[T],

    /**
     * Any keys in the search parameters which should be changed whenever this value is changed, along with the value
     * it should be changed to. E.g. for resetting page number whenever a filter is changed, etc.
     */
    onChange?: Record<string, string>,
};

type ParamReader = (param: string) => ParamTypeMappings[SearchParamType] | null;
type ParamWriter = (newValue: ParamTypeMappings[keyof ParamTypeMappings]) => string | null;

const readers: Record<SearchParamType, ParamReader> = {
    'date': param => new Date(param),
    'number': param => Number.isNaN(param) ? null : (Number.isInteger(parseFloat(param)) ? parseInt(param, 10) : parseFloat(param)),
    'number[]': param => param ? param.split('|').filter(x => !Number.isNaN(x)).map(x => Number.isInteger(parseFloat(x)) ? parseInt(x, 10) : parseFloat(x)) : [],
    'string': param => param,
};

const writers: Record<SearchParamType, ParamWriter> = {
    'date': (newValue: Date) => newValue.toISOString(),
    'number': (newValue: number) => newValue.toString(),
    'number[]': (newValue: number[]) => newValue.map(x => x.toString(10)).join('|'),
    'string': (newValue: string) => newValue,
};

export function useSearchParam<T extends SearchParamType>(key: string, type: T): { current: ParamTypeMappings[T] | null };
export function useSearchParam<T extends SearchParamType>(key: string, type: T, configuration: UseSearchParamConfiguration<T>): { current: ParamTypeMappings[T] };
export function useSearchParam<T extends SearchParamType>(key: string, type: T, configuration?: UseSearchParamConfiguration<T>): { current: ParamTypeMappings[T] } {
    const [searchParams, setSearchParams] = useSearchParams();

    return {
        get current(): ParamTypeMappings[T] {
            const currentValue = searchParams.has(key) ? searchParams.get(key) : configuration?.defaultValue?.toString() || null;
            
            return currentValue === null
                ? configuration?.defaultValue || null
                : readers[type](currentValue) as ParamTypeMappings[T];
        },
        set current(value: ParamTypeMappings[T]) {
            setSearchParams((prev) => new URLSearchParams({
                ...Object.fromEntries(prev),
                ...(configuration?.onChange || {}),
                [key]: writers[type](value),
            }));
        }
    }
}

...And some examples where I've started implementing it in an app:

    const text = useSearchParam('q', 'string', { defaultValue: '', onChange: { page: '1' } });
    const active = useSearchParam('active', 'string', { defaultValue: 'yes', onChange: { page: '1' } });
    const deleted = useSearchParam('deleted', 'string', { defaultValue: 'no', onChange: { page: '1' } });
    const countryId = useSearchParam('cid', 'number', { defaultValue: 0, onChange: { page: '1' } });
    const sortBy = useSearchParam('sortBy', 'string', { defaultValue: 'name', onChange: { page: '1' } });
    const sortOrder = useSearchParam('sortOrder', 'number', { defaultValue: SortOrder.Ascending, onChange: { page: '1' } });
    const page = useSearchParam('page', 'number', { defaultValue: 1 });

[pyramid-scheme-ceo]

Closing in favour of #11180