feat: Add loader feature

[franky47]

While we have the cache feature in Next.js app router to parse the incoming searchParams page prop and provide it to the rest of the RSC tree (via React's cache function, which is a hack but not the subject of this PR), other frameworks lacked the ability to parse an incoming request's search params and get the same kind of type-safe object back (without the caching part).

This PR introduces the createLoader function, a factory that takes in a search params descriptor object (a "parsers map" as we call it internally), and returns a load function. That function can then process a lot of different kinds of inputs:

• URL object
• Request object
• URLSearchParams object
• A string, whether of a fully qualified URL, or just the search part
• A record of key/values as what Next.js usually gives us (Record<string, string | string[] | undefined>)

Example usage in Remix / React Router's loaders:

import { createLoader, parseAsInteger } from 'nuqs/server' // can also be imported from 'nuqs' in non-RSC frameworks

const searchParams = {
  pageIndex: parseAsInteger.withDefault(1),
  pageSize: parseAsInteger.withDefault(10)
}

const loadSearchParams = createLoader(searchParams, { 
  urlKeys: {
    pageIndex: 'page',
    pageSize: 'limit'
  }
})

// When called from /path?page=2&limit=50
export function loader({ request }: LoaderFunctionArgs) {
  const { pageIndex, pageSize } = loadSearchParams(request)
  // ^? { pageIndex: 2, pageSize: 50 }
  return fetchData(pageIndex, pageSize) 
}

Compatibility

• React Routers & Remix loaders (using a Request object)
• Next.js pages router getServerSideProps (needs a test)
• Next.js app router searchParams prop (async in Next 15 -> good for PPR)
• Next.js API routes

Tasks

• Add docs

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuqs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 27, 2024 8:49pm

[pkg-pr-new]

Open in Stackblitz

npm i https://pkg.pr.new/nuqs@818

commit: 828445e

[github-actions]

🎉 This PR is included in version 2.3.0-beta.2 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀