feat: Add Standard Schema interface (#965)

Author: franky47

CONTRIBUTING.md

@@ -15,18 +15,20 @@ This monorepo contains:
 - The source code for the `nuqs` NPM package, in [`packages/nuqs`](./packages/nuqs).
 - A Next.js app under [`packages/docs`](./packages/docs) that serves the documentation and as a playground deployed at <https://nuqs.47ng.com>
 - Test benches for [end-to-end tests](./packages/e2e) for each supported framework, driven by Cypress
+- Examples of integration with other tools.
 
 When running `next dev`, this will:
 
 - Build the library and watch for changes using [`tsup`](https://tsup.egoist.dev/)
 - Start the docs app, which will be available at <http://localhost:3000>.
 - Start the end-to-end test benches:
-  - http://localhost:3001 - Next.js
-  - http://localhost:3002 - React SPA
-  - http://localhost:3003 - Remix
-  - http://localhost:3006 - React Router v6
-  - http://localhost:3007 - React Router v7
+  - http://localhost:3001 - [Next.js](./packages/e2e/next)
+  - http://localhost:3002 - [React SPA](./packages/e2e/react)
+  - http://localhost:3003 - [Remix](./packages/e2e/remix)
+  - http://localhost:3006 - [React Router v6](./packages/e2e/react-router/v6)
+  - http://localhost:3007 - [React Router v7](./packages/e2e/react-router/v7)
 - Start the examples:
+  - http://localhost:4000 - [tRPC](./packages/examples/trpc)
   - http://localhost:4001 - [Next.js - App router](./packages/examples/next-app)
 
 ## Testing

README.md

@@ -285,45 +285,6 @@ export default () => {
 }
 ```
 
-### Using parsers in Server Components
-
-> Note: see the [Accessing searchParams in server components](#accessing-searchparams-in-server-components)
-> section for a more user-friendly way to achieve type-safety.
-
-If you wish to parse the searchParams in server components, you'll need to
-import the parsers from `nuqs/server`, which doesn't include
-the `"use client"` directive.
-
-You can then use the `parseServerSide` method:
-
-```tsx
-import { parseAsInteger } from 'nuqs/server'
-
-type PageProps = {
-  searchParams: {
-    counter?: string | string[]
-  }
-}
-
-const counterParser = parseAsInteger.withDefault(1)
-
-export default function ServerPage({ searchParams }: PageProps) {
-  const counter = counterParser.parseServerSide(searchParams.counter)
-  console.log('Server side counter: %d', counter)
-  return (
-    ...
-  )
-}
-```
-
-See the [server-side parsing demo](<./packages/docs/src/app/playground/(demos)/pagination>)
-for a live example showing how to reuse parser configurations between
-client and server code.
-
-> Note: parsers **don't validate** your data. If you expect positive integers
-> or JSON-encoded objects of a particular shape, you'll need to feed the result
-> of the parser to a schema validation library, like [Zod](https://zod.dev).
-
 ## Default value
 
 When the query string is not present in the URL, the default behaviour is to
@@ -642,6 +603,10 @@ const { q, page } = loadSearchParams('?q=hello&page=2')
 
 It accepts various types of inputs (strings, URL, URLSearchParams, Request, Promises, etc.). [Read more](https://nuqs.47ng.com/docs/server-side#loaders)
 
+See the [server-side parsing demo](<./packages/docs/src/app/playground/(demos)/pagination>)
+for a live example showing how to reuse parser configurations between
+client and server code.
+
 ## Accessing searchParams in Server Components
 
 If you wish to access the searchParams in a deeply nested Server Component
@@ -930,25 +895,62 @@ export const metadata: Metadata = {
 If however the query string is defining what content the page is displaying
 (eg: YouTube's watch URLs, like `https://www.youtube.com/watch?v=dQw4w9WgXcQ`),
 your canonical URL should contain relevant query strings, and you can still
-use `useQueryState` to read it:
+use your parsers to read it, and to serialize the canonical URL:
 
 ```ts
 // page.tsx
 import type { Metadata, ResolvingMetadata } from 'next'
-import { useQueryState } from 'nuqs'
-import { parseAsString } from 'nuqs/server'
+import { notFound } from 'next/navigation'
+import {
+  createParser,
+  parseAsString,
+  createLoader,
+  createSerializer,
+  type SearchParams,
+  type UrlKeys
+} from 'nuqs/server'
+
+const youTubeVideoIdRegex = /^[^"&?\/\s]{11}$/i
+const youTubeSearchParams = {
+  videoId: createParser({
+    parse(query) {
+      if (!youTubeVideoIdRegex.test(query)) {
+        return null
+      }
+      return query
+    },
+    serialize(videoId) {
+      return videoId
+    }
+  })
+}
+const youTubeUrlKeys: UrlKeys<typeof youTubeSearchParams> = {
+  videoId: 'v'
+}
+const loadYouTubeSearchParams = createLoader(youTubeSearchParams, {
+  urlKeys: youTubeUrlKeys
+})
+const serializeYouTubeSearchParams = createSerializer(youTubeSearchParams, {
+  urlKeys: youTubeUrlKeys
+})
+
+// --
 
 type Props = {
-  searchParams: { [key: string]: string | string[] | undefined }
+  searchParams: Promise<SearchParams>
 }
 
 export async function generateMetadata({
   searchParams
 }: Props): Promise<Metadata> {
-  const videoId = parseAsString.parseServerSide(searchParams.v)
+  const { videoId } = await loadYouTubeSearchParams(searchParams)
+  if (!videoId) {
+    notFound()
+  }
   return {
     alternates: {
-      canonical: `/watch?v=${videoId}`
+      canonical: serializeYouTubeSearchParams('/watch', { videoId })
+      // /watch?v=dQw4w9WgXcQ
     }
   }
 }

packages/docs/content/docs/parsers/built-in.mdx

@@ -253,10 +253,11 @@ parseAsArrayOf(parseAsInteger, ';')
 
 If primitive types are not enough, you can encode JSON in the query string.
 
-Pass it a validation function to validate and infer the type of the parsed data,
-like a [Zod](https://zod.dev) schema:
+Pass it a [Standard Schema](https://standardschema.dev) (eg: a Zod schema)
+to validate and infer the type of the parsed data:
 
 ```ts
+// [!code word:parseAsJson]
 import { parseAsJson } from 'nuqs'
 import { z } from 'zod'
 
@@ -266,10 +267,9 @@ const schema = z.object({
   worksWith: z.array(z.string())
 })
 
-// This parser is a function, don't forget to call it with the parse function
-// as an argument.
-// [!code word:parseAsJson()]
-const [json, setJson] = useQueryState('json', parseAsJson(schema.parse))
+// This parser is a function, don't forget to call it
+// with your schema as an argument.
+const [json, setJson] = useQueryState('json', parseAsJson(schema))
 
 setJson({
   pkg: 'nuqs',
@@ -282,8 +282,25 @@ setJson({
   <JsonParserDemo />
 </Suspense>
 
-Using other validation libraries is possible, as long as they throw an error
-when the data is invalid (eg: Valibot, Yup, etc).
+Using other validation libraries is possible: `parseAsJson{:ts}` accepts
+any Standard Schema compatible input (eg: ArkType, Valibot),
+or a custom validation function (eg: Yup, Joi, etc):
+
+```ts
+import { object, string, number } from 'yup';
+
+let userSchema = object({
+  name: string().required(),
+  age: number().required().positive().integer(),
+});
+
+parseAsJson(userSchema.validateSync)
+```
+
+<Callout title="Note">
+  Validation functions must either throw an error or
+  return `null{:ts}` for invalid data. Only **synchronous** validation is supported.
+</Callout>
 
 ## Using parsers server-side
 

packages/docs/content/docs/parsers/demos.tsx

@@ -388,10 +388,7 @@ const jsonParserSchema = z.object({
 })
 
 export function JsonParserDemo() {
-  const [value, setValue] = useQueryState(
-    'json',
-    parseAsJson(jsonParserSchema.parse)
-  )
+  const [value, setValue] = useQueryState('json', parseAsJson(jsonParserSchema))
   return (
     <DemoContainer demoKey="json" className="items-start">
       <pre className="flex-1 rounded-md border bg-background p-2 text-sm text-zinc-500">

packages/docs/content/docs/seo.mdx

@@ -22,42 +22,67 @@ export const metadata: Metadata = {
 If however the query string is defining what content the page is displaying
 (eg: YouTube's watch URLs, like `https://www.youtube.com/watch?v=dQw4w9WgXcQ`),
 your canonical URL should contain relevant query strings, and you can still
-use your parsers to read it:
+use your parsers to read it, and to serialize the canonical URL.
 
 ```ts title="/app/watch/page.tsx"
 import type { Metadata, ResolvingMetadata } from 'next'
 import { notFound } from "next/navigation";
-import { createParser, parseAsString, type SearchParams } from 'nuqs/server'
+import {
+  createParser,
+  parseAsString,
+  createLoader,
+  createSerializer,
+  type SearchParams,
+  type UrlKeys
+} from 'nuqs/server'
 
-type Props = {
-  searchParams: Promise<SearchParams>
-}
-
-// Normally you'd reuse custom parsers across your application,
-// but for this example we'll define it here.
 const youTubeVideoIdRegex = /^[^"&?\/\s]{11}$/i
-const parseAsYouTubeVideoId = createParser({
-  parse(query) {
-    if (!youTubeVideoIdRegex.test(query)) {
-      return null
+const youTubeSearchParams = {
+  videoId: createParser({
+    parse(query) {
+      if (!youTubeVideoIdRegex.test(query)) {
+        return null
+      }
+      return query
+    },
+    serialize(videoId) {
+      return videoId
     }
-    return query
-  },
-  serialize(videoId) {
-    return videoId
+  })
+}
+const youTubeUrlKeys: UrlKeys<typeof youTubeSearchParams> = {
+  videoId: 'v'
+}
+const loadYouTubeSearchParams = createLoader(
+  youTubeSearchParams,
+  {
+    urlKeys: youTubeUrlKeys
   }
-})
+)
+const serializeYouTubeSearchParams = createSerializer(
+  youTubeSearchParams,
+  {
+    urlKeys: youTubeUrlKeys
+  }
+)
+
+// --
+
+type Props = {
+  searchParams: Promise<SearchParams>
+}
 
 export async function generateMetadata({
   searchParams
 }: Props): Promise<Metadata> {
-  const videoId = parseAsYouTubeVideoId.parseServerSide((await searchParams).v)
+  const { videoId } = await loadYouTubeSearchParams(searchParams)
   if (!videoId) {
     notFound()
   }
   return {
     alternates: {
-      canonical: `/watch?v=${videoId}`
+      canonical: serializeYouTubeSearchParams('/watch', { videoId })
+      // /watch?v=dQw4w9WgXcQ
     }
   }
 }

packages/docs/content/docs/server-side.mdx

@@ -121,6 +121,26 @@ The loader function will accept the following input types to parse search params
 - A `Record<string, string | string[] | undefined>{:ts}` (eg: `{ foo: 'bar' }{:ts}`)
 - A `Promise{:ts}` of any of the above, in which case it also returns a Promise.
 
+### Strict mode
+
+If a search param contains an invalid value for the associated parser (eg: `?count=banana` for `parseAsInteger{:ts}`),
+the default behaviour is to return the [default value](/docs/basic-usage#default-values) if specified, or `null{:ts}` otherwise.
+
+You can turn on **strict mode** to instead throw an error on invalid values when running the loader:
+
+```ts
+const loadSearchParams = createLoader({
+  count: parseAsInteger.withDefault(0)
+})
+
+// Default: will return { count: 0 }
+loadSearchParams('?count=banana')
+
+// Strict mode: will throw an error
+loadSearchParams('?count=banana', { strict: true })
+// [nuqs] Error while parsing query `banana` for key `count`
+```
+
 ## Cache
 
 <Callout>
@@ -202,7 +222,8 @@ import { Server } from './server'
 import { Client } from './client'
 
 export default async function Page({ searchParams }) {
-  await coordinatesCache.parse(searchParams)
+  // Note: you can also use strict mode here:
+  await coordinatesCache.parse(searchParams, { strict: true })
   return (
     <>
       <Server />