Typed searchParams and partial updating of searchParams

[pyramid-scheme-ceo]

What is the new or updated feature that you are suggesting?

A modified version of the useSearchParams hook that accepts a generic type argument and a parser method argument, allowing for strongly typed search params and partially updating search params.

Why should this feature be included?

The partial updating of searchParams is the main thing that's painful at the moment. The syntax of

setSearchParams(prev => {
  prev.set('key', value.toString());
  ... 
  return prev;
});

is just a bit verbose, and also requires you to think about converting everything to strings.

I've taken inspiration from the new tanstack router project and implemented a typed approach to search params, based on having a parser (e.g. yup, zod, or your own method) and a generic type argument.

Example usage

// my-list.tsx

const searchParamSchema = yup.object({
  text: yup.string().default(''),
  deleted: yup.mixed<'yes' | 'no' | 'any'>().default('no'),
  page: yup.number().default(1),
});

export const MyList: FC = () => {
  const [searchParams, setSearchParams] = useSearchParams<yup.InferType<typeof searchParamSchema>>({
    parser: searchParamsSchema.cast,
    paramConfiguration: {
      text: { key: 'q' }, // Allows custom mappings to URL params
    },
  });

  const { text, deleted, page } = searchParams; // Fully-typed, text: string, deleted: yes | no | any, page: number

  const handleSearchTextChange = (newValue: string) => {
    setSearchParams({ text: newValue, page: 1 }); // Can update multiple things at the same time
  };

  const handlePageChange = (newPage: number) => {
    setSearchParams({ page: newPage }); // Only allows a number-type value
  };

  return (
    <Table>
      ...
    </Table>
  );
};

[pyramid-scheme-ceo]

Here's a WIP implementation of the above for any feedback, have been using it already in other projects - would just be nice to have it integrated into the library itself 🙂

// search-params.helper.ts

import { useSearchParams as useSearchParamsBase } from 'react-router-dom';

type PropertyConfiguration = {
    /**
     * Custom URL key to use for the parameter if different to the name used in the type argument, e.g. for shorthand
     * parameter names, etc.
     */
    key?: string;

    /**
     * Require if the parameter is an array of any kind. Specifies the character/s which should be used to separate
     * the individual elements within the URL.
     */
    listSeparator?: string;
};

type UseSearchParamsConfig<T> = {
    /**
     * The search params parser. A method that accepts an object with string or string-array values and converts it
     * to the desired type.
     */
    parser: (input: Record<string, string | string[]>) => T,

    /**
     * Optional configuration for individual parameters.
     */
    paramConfiguration?: {
        [K in keyof T]?: PropertyConfiguration
    },
};

export function useSearchParams<T>(config: UseSearchParamsConfig<T>): [T, (newValues: Partial<T>) => void] {
    const [searchParams, setSearchParams] = useSearchParamsBase();
    const arrayKeys = (Object.keys(config.paramConfiguration || {}) as (keyof T)[])
        .filter(k => !!config.paramConfiguration?.[k]?.listSeparator);

    const extractSearchParamValue = (searchParamKey: string, key: keyof T): string | string[] => {
        const rawValue = Object.fromEntries(searchParams)[searchParamKey];
        return arrayKeys.includes(key)
            ? (rawValue ? rawValue.split(config.paramConfiguration?.[key]?.listSeparator) : [])
            : rawValue;
    }
    
    const currentValues = Object.keys(Object.fromEntries(searchParams))
        .reduce((prev, curr) => {
            const keyOverride = (Object.keys(config.paramConfiguration || {}) as (keyof T)[])
                .find(k => config.paramConfiguration[k].key === curr);
            
            return ({
                ...prev,
                [keyOverride || curr]: extractSearchParamValue(curr, keyOverride || curr as keyof T),
            });
        }, {} as Record<string, string | string[]>);

    const updateParams = (newValues: Partial<T>) => {
        setSearchParams(prev => new URLSearchParams({
            ...Object.fromEntries(prev),
            ...(Object.keys(newValues) as (keyof T)[]).reduce((prev, curr) => ({
                    ...prev,
                    [config.paramConfiguration?.[curr]?.key || curr]: arrayKeys.includes(curr)
                        ? (newValues[curr] as any[]).join(config.paramConfiguration?.[curr]?.listSeparator)
                        : isDate(newValues[curr]) ? (newValues[curr] as Date).toISOString() : newValues[curr],
                }), {} as Partial<T>
            ),
        }));
    };

    return [config.parser(currentValues), updateParams];
}

[YuriiKorovko]

@pyramid-scheme-ceo Hi, how would you remove a single parameter?