doc: Add Zod codecs community parsers (#1097)

Author: franky47

packages/docs/content/docs/parsers/community/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Community",
-  "pages": ["tanstack-table", "effect-schema"]
+  "pages": ["tanstack-table", "effect-schema", "zod-codecs"]
 }

packages/docs/content/docs/parsers/community/zod-codecs.demo.tsx

@@ -0,0 +1,116 @@
+'use client'
+
+import { CodeBlock } from '@/src/components/code-block.client'
+import { QuerySpy } from '@/src/components/query-spy'
+import { Button } from '@/src/components/ui/button'
+import { Input } from '@/src/components/ui/input'
+import { Label } from '@/src/components/ui/label'
+import { Dices } from 'lucide-react'
+import { useQueryState } from 'nuqs'
+import { userJsonBase64Parser } from './zod-codecs.lib'
+import { ZodCodecsDemoSkeleton } from './zod-codecs.skeleton'
+
+export function ZodCodecsDemo() {
+  const [user, setUser] = useQueryState(
+    'user',
+    userJsonBase64Parser.withDefault({
+      name: 'John Doe',
+      age: 42
+    })
+  )
+
+  const handleReset = () => {
+    setUser({
+      name: 'John Doe',
+      age: 42
+    })
+  }
+
+  const handleRandomize = () => {
+    const names = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank']
+    const randomName = names[Math.floor(Math.random() * names.length)]
+    const randomAge = Math.floor(Math.random() * 50) + 18
+    setUser({
+      name: randomName,
+      age: randomAge
+    })
+  }
+
+  return (
+    <ZodCodecsDemoSkeleton>
+      <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+        <div className="space-y-2">
+          <Label htmlFor="user-name">Name</Label>
+          <Input
+            id="user-name"
+            value={user.name}
+            placeholder="Enter your name..."
+            onChange={e => setUser(old => ({ ...old, name: e.target.value }))}
+          />
+        </div>
+        <div className="space-y-2">
+          <Label htmlFor="user-age">Age</Label>
+          <Input
+            id="user-age"
+            type="number"
+            min="1"
+            max="120"
+            value={user.age}
+            onChange={e =>
+              setUser(old => ({
+                ...old,
+                age: Number(e.target.valueAsNumber) || 0
+              }))
+            }
+          />
+        </div>
+      </div>
+
+      <div className="flex gap-2">
+        <Button onClick={handleRandomize}>
+          <Dices size={18} className="mr-2 inline-block" role="presentation" />
+          Randomize
+        </Button>
+        <Button onClick={handleReset} variant="outline">
+          Clear
+        </Button>
+      </div>
+
+      <div className="space-y-4">
+        <div>
+          <div className="mb-2 flex items-center gap-2">
+            <Label className="text-sm font-medium">Encoded in the URL:</Label>
+          </div>
+          <QuerySpy keepKeys={['user']} />
+        </div>
+        <div>
+          <Label className="text-sm font-medium">Current Data:</Label>
+          <CodeBlock
+            code={JSON.stringify(user, null, 2)}
+            lang="json"
+            className="mt-2"
+            allowCopy={false}
+          />
+        </div>
+        <div className="not-prose">
+          <strong className="mt-4 mb-2">How it works</strong>
+          <p className="text-muted-foreground mt-2 mb-2 text-sm">
+            On write (updating the URL):
+          </p>
+          <p>
+            <ol className="text-muted-foreground ml-2 list-inside list-decimal space-y-1 text-sm">
+              <li>User object is JSON stringified</li>
+              <li>JSON string is encoded as UTF-8 bytes</li>
+              <li>Bytes are encoded as base64url string</li>
+              <li>Result is stored in the URL query parameter</li>
+            </ol>
+            <p className="text-muted-foreground mt-2 text-sm">
+              On read, the process is reversed to decode the URL string back
+              into the original object.
+            </p>
+          </p>
+        </div>
+      </div>
+    </ZodCodecsDemoSkeleton>
+  )
+}

packages/docs/content/docs/parsers/community/zod-codecs.lib.ts

@@ -0,0 +1,102 @@
+import { createParser } from 'nuqs/server'
+import { z } from 'zod'
+
+function createZodCodecParser<
+  Input extends z.ZodCoercedString<string> | z.ZodPipe<any, any>,
+  Output extends z.ZodType
+>(
+  codec: z.ZodCodec<Input, Output> | z.ZodPipe<Input, Output>,
+  eq: (a: z.output<Output>, b: z.output<Output>) => boolean = (a, b) => a === b
+) {
+  return createParser<z.output<Output>>({
+    parse(query) {
+      return codec.parse(query)
+    },
+    serialize(value) {
+      return codec.encode(value)
+    },
+    eq
+  })
+}
+
+// --
+
+// All parsers from the Zod docs:
+const jsonCodec = <T extends z.core.$ZodType>(schema: T) =>
+  z.codec(z.string(), schema, {
+    decode: (jsonString, ctx) => {
+      try {
+        return JSON.parse(jsonString)
+      } catch (err: any) {
+        ctx.issues.push({
+          code: 'invalid_format',
+          format: 'json',
+          input: jsonString,
+          message: err.message
+        })
+        return z.NEVER
+      }
+    },
+    encode: value => JSON.stringify(value)
+  })
+
+const base64urlToBytes = z.codec(z.base64url(), z.instanceof(Uint8Array), {
+  decode: base64urlString => z.util.base64urlToUint8Array(base64urlString),
+  encode: bytes => z.util.uint8ArrayToBase64url(bytes)
+})
+
+const utf8ToBytes = z.codec(z.string(), z.instanceof(Uint8Array), {
+  decode: str => new TextEncoder().encode(str),
+  encode: bytes => new TextDecoder().decode(bytes)
+})
+const bytesToUtf8 = invertCodec(utf8ToBytes)
+
+// --
+
+function invertCodec<A extends z.ZodType, B extends z.ZodType>(
+  codec: z.ZodCodec<A, B>
+): z.ZodCodec<B, A> {
+  return z.codec<B, A>(codec.out, codec.in, {
+    decode(value, ctx) {
+      try {
+        return codec.encode(value)
+      } catch (err) {
+        ctx.issues.push({
+          code: 'invalid_format',
+          format: 'invert.decode',
+          input: String(value),
+          message: err instanceof z.ZodError ? err.message : String(err)
+        })
+        return z.NEVER
+      }
+    },
+    encode(value, ctx) {
+      try {
+        return codec.decode(value)
+      } catch (err) {
+        ctx.issues.push({
+          code: 'invalid_format',
+          format: 'invert.encode',
+          input: String(value),
+          message: err instanceof z.ZodError ? err.message : String(err)
+        })
+        return z.NEVER
+      }
+    }
+  })
+}
+
+// --
+
+const userSchema = z.object({
+  name: z.string(),
+  age: z.number()
+})
+
+// Composition always wins.
+const codec = base64urlToBytes.pipe(bytesToUtf8).pipe(jsonCodec(userSchema))
+
+export const userJsonBase64Parser = createZodCodecParser(
+  codec,
+  (a, b) => a === b || (a.name === b.name && a.age === b.age)
+)

packages/docs/content/docs/parsers/community/zod-codecs.mdx

@@ -0,0 +1,68 @@
+---
+title: Zod codecs
+description: Using Zod codecs for (de)serialisation in custom nuqs parser
+---
+
+Since `zod@^4.1`, you can use [codecs](https://zod.dev/codecs)
+to add bidirectional serialisation / deserialisation to your validation schemas:
+
+```ts
+import { z } from 'zod'
+
+// Similar to parseAsTimestamp in nuqs:
+const dateTimestampCodec = z.codec(z.string().regex(/^\d+$/), z.date(), {
+  decode: (query) => new Date(parseInt(query)),
+  encode: (date) => date.valueOf().toFixed()
+})
+```
+
+## Demo
+
+<iframe
+  src="https://www.youtube-nocookie.com/embed/k4lWvklUxUE"
+  title="YouTube video player"
+  frameBorder="0"
+  allow="autoplay; encrypted-media; picture-in-picture; web-share"
+  referrerPolicy="strict-origin-when-cross-origin"
+  allowFullScreen
+  className='aspect-video w-full max-w-2xl mx-auto mb-8'
+/>
+
+import { ZodCodecsDemo } from './zod-codecs.demo'
+import { ZodCodecsDemoSkeleton } from './zod-codecs.skeleton'
+import { Suspense } from 'react'
+
+<Suspense fallback={(
+  <ZodCodecsDemoSkeleton className='animate-pulse'>
+    <div className='h-32 bg-muted/25 rounded-md flex items-center justify-center text-sm text-muted-foreground'>
+      Loading demo…
+    </div>
+  </ZodCodecsDemoSkeleton>
+)}>
+  <ZodCodecsDemo/>
+</Suspense>
+
+import { ZodCodecsSource } from './zod-codecs.source'
+
+Source code:
+
+<ZodCodecsSource/>
+
+## Refinements
+
+The cool part is being able to add string constraints to the first type in a codec.
+It has to be rooted as a string data type (because that's what the URL
+will give us), but you can add **refinements**:
+
+```ts
+z.codec(z.uuid(), ...)
+z.codec(z.email(), ...)
+z.codec(z.base64url(), ...)
+```
+
+See the [complete list](https://zod.dev/api?id=string-formats) of string-based
+refinements you can use.
+
+<Callout title="Caveats" type="warning">
+  As stated in the Zod docs, you [cannot use transforms in codecs](https://zod.dev/codecs#transforms).
+</Callout>

packages/docs/content/docs/parsers/community/zod-codecs.skeleton.tsx

@@ -0,0 +1,28 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle
+} from '@/src/components/ui/card'
+import { cn } from '@/src/lib/utils'
+import type { ComponentProps } from 'react'
+
+export function ZodCodecsDemoSkeleton({
+  children,
+  className,
+  ...props
+}: ComponentProps<'div'>) {
+  return (
+    <Card className={cn('border-dashed py-4', className)} {...props}>
+      <CardHeader className="px-4">
+        <CardTitle className="text-xl">Zod Codecs Demo</CardTitle>
+        <CardDescription>
+          This demo shows how Zod codecs can transform complex data structures
+          into URL-safe strings using base64url encoding and JSON serialization.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-6 px-4">{children}</CardContent>
+    </Card>
+  )
+}

packages/docs/content/docs/parsers/community/zod-codecs.source.tsx

@@ -0,0 +1,9 @@
+import { CodeBlock } from '@/src/components/code-block'
+import { readFile } from 'node:fs/promises'
+
+export async function ZodCodecsSource() {
+  const filePath =
+    process.cwd() + '/content/docs/parsers/community/zod-codecs.lib.ts'
+  const source = await readFile(filePath, 'utf8')
+  return <CodeBlock code={source.trim()} />
+}

packages/docs/package.json

@@ -61,7 +61,7 @@
     "tailwind-merge": "^3.3.1",
     "tailwindcss": "^4.1.12",
     "tailwindcss-animate": "^1.0.7",
-    "zod": "^4.0.17"
+    "zod": "^4.1.5"
   },
   "devDependencies": {
     "@shikijs/transformers": "^3.11.0",

packages/docs/src/app/(pages)/stats/lib/npm.ts

@@ -1,9 +1,11 @@
 import dayjs from 'dayjs'
 import isoWeek from 'dayjs/plugin/isoWeek'
+import minMax from 'dayjs/plugin/minMax'
 import 'server-only'
 import { z } from 'zod'
 
 dayjs.extend(isoWeek)
+dayjs.extend(minMax)
 
 export type Datum = {
   date: string
@@ -60,11 +62,24 @@ async function getLastNDays(pkg: string, n: number): Promise<Datum[]> {
   }
 }
 
+async function getPackageCreationDate(pkg: string): Promise<dayjs.Dayjs> {
+  const npmStatsEpoch = dayjs('2015-01-10')
+  try {
+    const res = await get<{ time: Record<string, string> }>(
+      `https://registry.npmjs.org/${pkg}`
+    )
+    return dayjs.max(npmStatsEpoch, dayjs(res.time.created))
+  } catch (e) {
+    console.error(e)
+    return npmStatsEpoch
+  }
+}
+
 async function getAllTime(pkg: string): Promise<number> {
   let downloads: number = 0
-  const now = dayjs()
-  let start = dayjs('2015-01-10') // NPM stats epoch
+  let start = dayjs(await getPackageCreationDate(pkg))
   let end = start.add(18, 'month')
+  const now = dayjs()
   while (start.isBefore(now)) {
     const url = `https://api.npmjs.org/downloads/range/${start.format(
       'YYYY-MM-DD'