[bug]: Failed to construct 'URLSearchParams' when using nuqs with SortingState in TanStack Router

[epenflow]

Describe the bug

When using nuqs along side tanstack router/start to manage table state, attempting to update a sorting state results in runtime error Failed to construct 'URLSearchParams': Cannot convert object to primitive value. This appears to be serialization mismatch.

How to reproduce

How to reproduce

1. Repo
2. Setup a project with @tanstack/start and nuqs
3. Define a search paramater using getSortingStateParser()
4. Attempt to update the sort state
5. Observe the console error when the router attempts to sync the state to the URL

Link to reproduction

https://github.com/epenflow/sorting

Additional information

Expected behavior

The sorting state should serialized into a query string and successfully synchronized with the URL via tanstack router

Actual behavior

The application crashes with the following error
Failed to construct 'URLSearchParams': Cannot convert object to primitive value

[epenflow]

Tanstack router custom useDataTable hooks

'use client'

import { useDebouncedCallback } from '@tanstack/react-pacer'
import type {
  ColumnFiltersState,
  ColumnSizingState,
  PaginationState,
  RowSelectionState,
  SortingState,
  TableOptions,
  TableState,
  Updater,
  VisibilityState,
} from '@tanstack/react-table'
import {
  functionalUpdate,
  getCoreRowModel,
  getFacetedMinMaxValues,
  getFacetedRowModel,
  getFacetedUniqueValues,
  getFilteredRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
} from '@tanstack/react-table'
import { useCallback, useMemo, useState } from 'react'

import { useSearchState } from '#/hooks/use-search-state'
import type { DataTableQueryKeys } from './data-table-type'

const PAGE_KEY = 'page'
const PER_PAGE_KEY = 'perPage'
const SORT_KEY = 'sort'
const FILTERS_KEY = 'filters'
const JOIN_OPERATOR_KEY = 'joinoperator'
// const ARRAY_SEPARATOR = ',';
const DEBOUNCE_MS = 300

type Props<TData> = Omit<
  TableOptions<TData>,
  | 'state'
  | 'pageCount'
  | 'getCoreRowModel'
  | 'manualFiltering'
  | 'manualPagination'
  | 'manualSorting'
> &
  Partial<{
    initialState: Partial<TableState>
    queryKeys: Partial<DataTableQueryKeys>
    history: 'push' | 'replace'
    debounceMs: number
  }> &
  Required<Pick<TableOptions<TData>, 'pageCount'>>

function useDataTable<TData>({
  columns,
  queryKeys,
  initialState,
  history = 'replace',
  pageCount = -1,
  debounceMs = DEBOUNCE_MS,
  onRowSelectionChange: onRowSelectionChangePrimitive,
  ...props
}: Props<TData>) {
  const pageKey = queryKeys?.page ?? PAGE_KEY
  const perPageKey = queryKeys?.perPage ?? PER_PAGE_KEY
  const sortKey = queryKeys?.sort ?? SORT_KEY
  const filtersKey = queryKeys?.filters ?? FILTERS_KEY
  const joinOperatorKey = queryKeys?.joinOperator ?? JOIN_OPERATOR_KEY

  const isHistoryPush = history === 'push'

  /**
   * Local UI State (Non-URL)
   */
  const [rowSelection, setRowSelection] = useState<RowSelectionState>(
    () => initialState?.rowSelection ?? {},
  )
  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(
    () => initialState?.columnVisibility ?? {},
  )
  const [columnSizing, setColumnSizing] = useState<ColumnSizingState>(
    () => initialState?.columnSizing ?? {},
  )

  const onRowSelectionChange = useCallback(
    (updater: Updater<RowSelectionState>) => {
      const next = functionalUpdate(updater, rowSelection)

      void setRowSelection(next)
      void onRowSelectionChangePrimitive?.(next)
    },
    [rowSelection, setRowSelection, onRowSelectionChangePrimitive],
  )

  /**
   * Sorting state, derived and handler
   */

  const [sortingQuery, setSortingQuery] = useSearchState<
    any,
    any,
    false,
    string,
    SortingState
  >({
    strict: false,
    key: sortKey,
    initial: initialState?.sorting ?? [],
  })

  const [sorting, setSorting] = useState<SortingState>(
    () => sortingQuery ?? initialState?.sorting ?? [],
  )

  const debouncedSortingQuery = useDebouncedCallback(
    (value: SortingState) => {
      setSortingQuery(value, isHistoryPush)
    },
    { wait: debounceMs },
  )

  const onSortingChange = useCallback(
    (updater: Updater<SortingState>) => {
      const next = functionalUpdate(updater, sorting)

      void setSorting(next)
      void debouncedSortingQuery(next)
    },
    [sorting, setSorting, debouncedSortingQuery],
  )

  /**
   * Pagination state, derived and handler
   */

  const [pageQuery, setPageQuery] = useSearchState<
    any,
    any,
    false,
    string,
    number
  >({
    strict: false,
    key: pageKey,
    initial: initialState?.pagination?.pageIndex ?? 1,
  })

  const [perPageQuery, setPerPageQuery] = useSearchState<
    any,
    any,
    false,
    string,
    number
  >({
    strict: false,
    key: perPageKey,
    initial: initialState?.pagination?.pageSize ?? 10,
  })

  const pagination: PaginationState = useMemo(
    () => ({
      pageIndex: (pageQuery ?? 1) - 1,
      pageSize: perPageQuery ?? 10,
    }),
    [pageQuery, perPageQuery],
  )

  const onPaginationChange = useCallback(
    (updater: Updater<PaginationState>) => {
      const next = functionalUpdate(updater, pagination)

      void setPageQuery(next.pageIndex + 1, isHistoryPush)
      void setPerPageQuery(next.pageSize, isHistoryPush)
    },
    [pagination, setPageQuery, setPerPageQuery],
  )

  /**
   * Column filter state, derived and handler
   */

  const filterableColumns = useMemo(() => {
    return new Set(
      columns
        .filter((column) => column.enableColumnFilter)
        .map((column) => column.id)
        .filter(Boolean),
    )
  }, [columns])

  const [columnFiltersQuery, setColumnFiltersQuery] = useSearchState<
    any,
    any,
    false,
    string,
    ColumnFiltersState
  >({
    strict: false,
    key: filtersKey,
    initial: initialState?.columnFilters ?? [],
  })

  const debouncedColumnFiltersQuery = useDebouncedCallback(
    (values: ColumnFiltersState) => {
      void setPageQuery(1, isHistoryPush)
      void setColumnFiltersQuery(values, isHistoryPush)
    },
    {
      wait: debounceMs,
    },
  )

  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>(
    () => columnFiltersQuery ?? [],
  )

  const onColumnFiltersChange = useCallback(
    (updater: Updater<ColumnFiltersState>) => {
      const next = functionalUpdate(updater, columnFilters)

      const filters = next.filter((filter) => filterableColumns?.has(filter.id))

      void setColumnFilters(filters)
      void debouncedColumnFiltersQuery(filters)
    },
    [columnFilters, filterableColumns, debouncedColumnFiltersQuery],
  )

  // eslint-disable-next-line react-hooks/incompatible-library
  const table = useReactTable({
    ...props,
    columns,
    initialState,
    pageCount,
    state: {
      sorting,
      pagination,
      columnVisibility,
      rowSelection,
      columnFilters,
      columnSizing,
    },
    onSortingChange,
    onPaginationChange,
    onColumnFiltersChange,
    onRowSelectionChange,
    onColumnVisibilityChange: setColumnVisibility,
    onColumnSizingChange: setColumnSizing,
    getCoreRowModel: getCoreRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFacetedRowModel: getFacetedRowModel(),
    getFacetedUniqueValues: getFacetedUniqueValues(),
    getFacetedMinMaxValues: getFacetedMinMaxValues(),
    manualSorting: true,
    manualPagination: true,
    manualFiltering: true,
    enableRowSelection: true,
    meta: {
      ...props.meta,
      queryKeys: {
        page: pageKey,
        perPage: perPageKey,
        sort: sortKey,
        filters: filtersKey,
        joinOperator: joinOperatorKey,
      },
    },
  })

  return { table, debounceMs }
}
export { useDataTable as default }

/**
 *
 * @see https://discord.com/channels/719702312431386674/1371522361936842912
 *  
 */

import {
  type AnyRouter,
  type RegisteredRouter,
  useRouter,
  useSearch,
  type ValidateId,
} from '@tanstack/react-router'
import { useLayoutEffect, useMemo } from 'react'

type ConstrainLiteral<T, TConstraint, TDefault = TConstraint> =
  | (T & TConstraint)
  | TDefault

type SearchSchema<
  TRouter extends AnyRouter,
  TFrom extends keyof TRouter['routesById'],
> = keyof TRouter['routesById'][TFrom]['types']['searchSchema']

type AnyKey<TRouter extends AnyRouter, TKey extends string> = ConstrainLiteral<
  TKey,
  string &
    {
      [K in keyof TRouter['routesById']]: SearchSchema<TRouter, K>
    }[keyof TRouter['routesById']]
>

type FromKey<
  TRouter extends AnyRouter,
  TFrom extends string,
  TKey extends string,
> = ConstrainLiteral<
  TKey,
  string & SearchSchema<TRouter, TFrom & keyof TRouter['routesById']>
>

type Params<
  TRouter extends AnyRouter,
  TFrom extends string,
  TStrict extends boolean,
  TKey extends string,
  TValue,
> = TStrict extends false
  ? {
      from?: never
      strict: TStrict
      key: AnyKey<TRouter, TKey>
      initial?: TValue
    }
  : {
      from: ValidateId<TRouter, TFrom>
      strict?: TStrict
      key: FromKey<TRouter, TFrom, TKey>
      initial?: TValue
    }

type ValueFrom<
  TRouter extends AnyRouter,
  TFrom,
  TStrict extends boolean,
  TKey extends string,
> = TStrict extends false
  ?
      | undefined
      | {
          [K in keyof TRouter['routesById']]: TKey extends keyof TRouter['routesById'][K]['types']['searchSchema']
            ? TRouter['routesById'][K]['types']['searchSchema'][TKey]
            : never
        }[keyof TRouter['routesById']]
  : TRouter['routesById'][TFrom &
      keyof TRouter['routesById']]['types']['searchSchema'][TKey]

export function useSearchState<
  TRouter extends AnyRouter = RegisteredRouter,
  TFrom extends string = string,
  TStrict extends boolean = true,
  TKey extends string = string,
  TValue = ValueFrom<TRouter, TFrom, TStrict, TKey>,
>({
  from,
  strict,
  initial,
  key,
}: Params<TRouter, TFrom, TStrict, TKey, NoInfer<TValue>>): readonly [
  state: TValue,
  setState: (
    value: TValue | ((prev: TValue) => TValue),
    push_state?: boolean,
  ) => void,
] {
  // state
  const select = useMemo(() => getter.bind(null, key), [key])
  const state = useSearch({
    from,
    select,
    strict,
  }) as TValue

  // setState
  const router = useRouter()
  const setState = useMemo(
    () => (setter<TValue>).bind(null, router, key),
    [router, key],
  )

  // initial value
  useLayoutEffect(() => {
    if (initial !== undefined && state === undefined) {
      setState(initial)
    }
  }, [])

  return [state, setState]
}

function getter(key: string, state: object) {
  // @ts-expect-error -- no need to strictly type this internal function
  return state[key]
}

const store = Symbol('search accumulator')
const push = Symbol('push accumulator')

function setter<T>(
  router: AnyRouter & { [store]?: object | null; [push]?: boolean | null },
  key: string,
  value: T | ((prev: T) => T),
  push_state?: boolean,
) {
  const prev = router[store] || router.state.location.search
  const next = {
    ...prev,
    [key]:
      typeof value === 'function'
        ? // @ts-expect-error -- no need to strictly type this internal function
          value(prev[key])
        : value,
  }

  if (next[key] === prev[key]) return

  router[store] = next
  const replace = !(router[push] ||= push_state)
  void router.navigate({
    hash: router.state.location.hash,
    replace,
    search: next,
    to: router.state.location.pathname,
  })
  /**
   * We temporarily store the search state in the router object
   * so that multiple calls to setState in the same tick will
   * accumulate changes in the same object instead of overwriting.
   *
   * We use a Symbol to avoid conflicts with other properties
   * that we don't own.
   *
   * After a tick, we nullify the property to avoid memory leaks,
   * and to ensure that the next setState call will start from
   * the current search state.
   */
  Promise.resolve().then(() => {
    router[store] = null
    router[push] = null
  })
}

[Maskoe]

This is an issue with the nuqs tanstack adapter. It cannot deal with arrays of objects. 47ng/nuqs#1127

You can get around this by changing the sorting parser in parser.ts to

export const sortParser: Parser<ExtendedColumnSort<any>[]> = {
	parse: (v): ExtendedColumnSort<any>[] => {
		if (!v) return [];
		const [id, dir] = v.split(":");
		if (!id) return [];
		return [{ id, desc: dir === "desc" } as ExtendedColumnSort<any>];
	},
	serialize: (v) => {
		const first = v[0];
		if (!first) return null;
		return `${first.id}:${first.desc ? "desc" : "asc"}`;
	},
};

and then use it in use-data-table.ts like here

const [sorting, setSorting] = useSearchParam(sortKey, sortParser, {
		defaultValue: initialState?.sorting ?? [],
		debounceMs,
	});

No guarantees, i didnt use it long. I had a clanker move the entire thing from nuqs to tanstacks navigate and it seems to work. I am still testing that one tho.