From f4817f54e56a1a5253d40d121ea55079344ef28e Mon Sep 17 00:00:00 2001
From: Francois Best <github@francoisbest.com>
Date: Sun, 10 Sep 2023 21:51:35 +0200
Subject: [PATCH] feat: Single app/pages implementation

After some tests, it turns out the implementation relying
on the next router works in both pages and app directories,
with the usual SSR/hydration caveats of the pages router.

- Add demos
- Export individual parsers and deprecate the queryTypes object
- Allow hook-level and setState-level options overrides
- Add subscribeToQueryUpdates hook for easier component testing
- Add options to the parsers builder pattern
---
 README.md                                     | 224 +++++---
 app.d.ts                                      |   7 -
 cypress.config.ts                             |   3 +-
 next.config.mjs                               |  10 +
 package.json                                  |  24 +-
 pages.d.ts                                    |   7 -
 src/app/app/useQueryState/page.tsx            |  19 +-
 src/app/app/useQueryStates/page.tsx           |  16 +-
 src/app/demos/batching/page.tsx               |  40 ++
 src/app/demos/builder-pattern/page.tsx        |  34 ++
 .../demos/subscribeToQueryUpdates/page.tsx    |  37 ++
 src/app/layout.tsx                            |   4 +
 src/app/page.tsx                              |  21 +-
 src/lib/defs.ts                               | 481 ++++++++++--------
 src/lib/index.app.ts                          |   5 -
 src/lib/index.pages.ts                        |   6 -
 src/lib/index.ts                              |   5 +-
 src/lib/pages/pagesRouterDefs.ts              |   5 -
 src/lib/pages/useQueryState.ts                | 280 ----------
 src/lib/pages/useQueryStates.ts               | 146 ------
 src/lib/sync.ts                               |   9 +
 src/lib/update-queue.ts                       |  74 ++-
 src/lib/{app => }/useQueryState.ts            |  69 +--
 src/lib/{app => }/useQueryStates.ts           |  50 +-
 src/pages/pages/useQueryState/index.tsx       |   2 +-
 src/pages/pages/useQueryStates/index.tsx      |   2 +-
 .../{pages => compat}/useQueryState.test-d.ts |  10 +-
 .../{app => compat}/useQueryStates.test-d.ts  |   2 +-
 src/tests/{app => }/useQueryState.test-d.ts   |  95 +++-
 .../{pages => }/useQueryStates.test-d.ts      |  23 +-
 30 files changed, 814 insertions(+), 896 deletions(-)
 delete mode 100644 app.d.ts
 create mode 100644 next.config.mjs
 delete mode 100644 pages.d.ts
 create mode 100644 src/app/demos/batching/page.tsx
 create mode 100644 src/app/demos/builder-pattern/page.tsx
 create mode 100644 src/app/demos/subscribeToQueryUpdates/page.tsx
 delete mode 100644 src/lib/index.app.ts
 delete mode 100644 src/lib/index.pages.ts
 delete mode 100644 src/lib/pages/pagesRouterDefs.ts
 delete mode 100644 src/lib/pages/useQueryState.ts
 delete mode 100644 src/lib/pages/useQueryStates.ts
 rename src/lib/{app => }/useQueryState.ts (79%)
 rename src/lib/{app => }/useQueryStates.ts (76%)
 rename src/tests/{pages => compat}/useQueryState.test-d.ts (96%)
 rename src/tests/{app => compat}/useQueryStates.test-d.ts (95%)
 rename src/tests/{app => }/useQueryState.test-d.ts (67%)
 rename src/tests/{pages => }/useQueryStates.test-d.ts (78%)

diff --git a/README.md b/README.md
index 8fa3d5b8..765527e9 100644
--- a/README.md
+++ b/README.md
@@ -10,27 +10,25 @@ useQueryState hook for Next.js - Like React.useState, but stored in the URL quer
 
 ## Features
 
-- 🧘‍♀️ Simple: the URL is the source of truth.
+- 🧘‍♀️ Simple: the URL is the source of truth
 - 🕰 Replace history or append to use the Back button to navigate state updates
-- ⚡️ Built-in converters for common object types (number, float, boolean, Date)
+- ⚡️ Built-in parsers for common object types (number, float, boolean, Date, and [more](#parsing))
 - ♊️ Linked querystrings with `useQueryStates`
-- 🔀 Supports both the app router (in client components only) and pages router
+- 🔀 _(beta)_ Supports both the app router (in client components only) and pages router
 
 ## Installation
 
 ```shell
+$ pnpm add next-usequerystate
 $ yarn add next-usequerystate
-or
 $ npm install next-usequerystate
 ```
 
 ## Usage
 
-> Note: all code samples assume you're using the pages router.
->
-> Jump to the [app router documentation](#app-router).
-
 ```tsx
+'use client' // app router: only works in client components
+
 import { useQueryState } from 'next-usequerystate'
 
 export default () => {
@@ -68,19 +66,29 @@ Example outputs for our hello world example:
 If your state type is not a string, you must pass a parsing function in the
 second argument object.
 
-We provide helpers for common and more advanced object types:
+We provide parsers for common and more advanced object types:
 
 ```ts
-import { queryTypes } from 'next-usequerystate'
+import {
+  parseAsString,
+  parseAsInteger,
+  parseAsFloat,
+  parseAsBoolean,
+  parseAsTimestamp,
+  parseAsIsoDateTime,
+  parseAsArrayOf,
+  parseAsJson,
+  parseAsStringEnum
+} from 'next-usequerystate'
 
 useQueryState('tag') // defaults to string
-useQueryState('count', queryTypes.integer)
-useQueryState('brightness', queryTypes.float)
-useQueryState('darkMode', queryTypes.boolean)
-useQueryState('after', queryTypes.timestamp) // state is a Date
-useQueryState('date', queryTypes.isoDateTime) // state is a Date
-useQueryState('array', queryTypes.array(queryTypes.integer)) // state is number[]
-useQueryState('json', queryTypes.json<Point>()) // state is a Point
+useQueryState('count', parseAsInteger)
+useQueryState('brightness', parseAsFloat)
+useQueryState('darkMode', parseAsBoolean)
+useQueryState('after', parseAsTimestamp) // state is a Date
+useQueryState('date', parseAsIsoDateTime) // state is a Date
+useQueryState('array', parseAsArrayOf(parseAsInteger)) // state is number[]
+useQueryState('json', parseAsJson<Point>()) // state is a Point
 
 // Enums (string-based only)
 enum Direction {
@@ -92,8 +100,7 @@ enum Direction {
 
 const [direction, setDirection] = useQueryState(
   'direction',
-  queryTypes
-    .stringEnum<Direction>(Object.values(Direction)) // pass a list of allowed values
+  parseAsStringEnum<Direction>(Object.values(Direction)) // pass a list of allowed values
     .withDefault(Direction.up)
 )
 ```
@@ -116,10 +123,10 @@ export default () => {
 Example: simple counter stored in the URL:
 
 ```tsx
-import { useQueryState, queryTypes } from 'next-usequerystate'
+import { useQueryState, parseAsInteger } from 'next-usequerystate'
 
 export default () => {
-  const [count, setCount] = useQueryState('count', queryTypes.integer)
+  const [count, setCount] = useQueryState('count', parseAsInteger)
   return (
     <>
       <pre>count: {count}</pre>
@@ -143,10 +150,7 @@ tedious.
 You can specify a default value to be returned in this case:
 
 ```ts
-const [count, setCount] = useQueryState(
-  'count',
-  queryTypes.integer.withDefault(0)
-)
+const [count, setCount] = useQueryState('count', parseAsInteger.withDefault(0))
 
 const increment = () => setCount(c => c + 1) // c will never be null
 const decrement = () => setCount(c => c - 1) // c will never be null
@@ -159,7 +163,9 @@ URL.
 Setting the state to `null` will remove the key in the query string and set the
 state to the default value.
 
-## History options
+## Options
+
+### History
 
 By default, state updates are done by replacing the current history entry with
 the updated query when state changes.
@@ -181,35 +187,114 @@ useQueryState('foo', { history: 'push' })
 
 Any other value for the `history` option will fallback to the default.
 
-## Multiple Queries
+You can also override the history mode when calling the state updater function:
+
+```ts
+const [query, setQuery] = useQueryState('q', { history: 'push' })
+
+// This overrides the hook declaration setting:
+setQuery(null, { history: 'replace' })
+```
+
+### Shallow
+
+By default, query state updates are done in a _client-first_ manner: there are
+no network calls to the server.
 
-> Note: If using the app router, you don't need to await the state updates.
+This uses the `shallow` option of the Next.js router set to `true`.
 
-Because the Next.js router has asynchronous methods, if you want to do multiple
-query updates in one go, you'll have to `await` them, otherwise the latter will
-overwrite the updates of the former:
+To opt-in to query updates notifying the server (to re-run `getServerSideProps`
+in the pages router and re-render Server Components on the pages router),
+you can set `shallow` to `false`:
+
+```ts
+const [state, setState] = useQueryState('foo', { shallow: false })
+
+// You can also pass the option on calls to setState:
+setState('bar', { shallow: false })
+```
+
+### Scroll
+
+The Next.js router scrolls to the top of the page on navigation updates,
+which may not be desirable when updating the query string with local state.
+
+Query state updates won't scroll to the top of the page by default, but you
+can opt-in to this behaviour (which was the default up to 1.8.0):
+
+```ts
+const [state, setState] = useQueryState('foo', { scroll: true })
+
+// You can also pass the option on calls to setState:
+setState('bar', { scroll: true })
+```
+
+## Composing parsers, default value & options
+
+You can use a builder pattern to facilitate specifying all of those things:
+
+```ts
+useQueryState(
+  'counter',
+  parseAsInteger
+    .withOptions({
+      history: 'push',
+      shallow: false
+    })
+    .withDefault(0)
+)
+```
+
+Note: `withDefault` must always come **after** `withOptions` to ensure proper
+type safety (providing a non-nullable state type).
+
+## Multiple Queries (batching)
+
+You can call as many state update function as needed in a single event loop
+tick, and they will be applied to the URL asynchronously:
 
 ```ts
 const MultipleQueriesDemo = () => {
-  const [lat, setLat] = useQueryState('lat', queryTypes.float)
-  const [lng, setLng] = useQueryState('lng', queryTypes.float)
-  const randomCoordinates = React.useCallback(async () => {
-    await setLat(Math.random() * 180 - 90)
-    await setLng(Math.random() * 360 - 180)
+  const [lat, setLat] = useQueryState('lat', parseAsFloat)
+  const [lng, setLng] = useQueryState('lng', parseAsFloat)
+  const randomCoordinates = React.useCallback(() => {
+    setLat(Math.random() * 180 - 90)
+    setLng(Math.random() * 360 - 180)
   }, [])
 }
 ```
 
+<!-- todo: All promises of a single update should be the same reference.
+
+If you wish to know when the URL has been updated, you can await the
+first returned Promise, which gives you the updated URLSearchParameters
+object:
+
+```ts
+const randomCoordinates = React.useCallback(() => {
+  // Always return the first promise
+  const promise = setLat(42)
+  // Queue up more state updates **synchronously**
+  setLng(12)
+  return promise
+}, [])
+
+randomCoordinates().then((search: URLSearchParams) => {
+  search.get('lat') // 42
+  search.get('lng') // 12, has been queued and batch-updated
+})
+``` -->
+
 For query keys that should always move together, you can use `useQueryStates`
-with an object containing each key's type:
+with an object containing each key's type, for a better DX:
 
 ```ts
-import { useQueryStates, queryTypes } from 'next-usequerystate'
+import { useQueryStates, parseAsFloat } from 'next-usequerystate'
 
 const [coordinates, setCoordinates] = useQueryStates(
   {
-    lat: queryTypes.float.withDefault(45.18),
-    lng: queryTypes.float.withDefault(5.72)
+    lat: parseAsFloat.withDefault(45.18),
+    lng: parseAsFloat.withDefault(5.72)
   },
   {
     history: 'push'
@@ -219,62 +304,41 @@ const [coordinates, setCoordinates] = useQueryStates(
 const { lat, lng } = coordinates
 
 // Set all (or a subset of) the keys in one go:
-await setCoordinates({
+const search = await setCoordinates({
   lat: Math.random() * 180 - 90,
   lng: Math.random() * 360 - 180
 })
 ```
 
-## Transition Options
-
-> Note: this feature is only available for the pages router.
-
-By default, Next.js will scroll to the top of the page when changing things in the URL.
-
-To prevent this, `router.push()` and `router.replace()` have a third optional
-parameter to control transitions, which can be passed on the state setter here:
-
-```ts
-const [name, setName] = useQueryState('name')
+## Caveats
 
-setName('Foo', {
-  scroll: false,
-  shallow: true // Don't run getStaticProps / getServerSideProps / getInitialProps
-})
-```
+Because the Next.js pages router is not available in an SSR context, this
+hook will always return `null` (or the default value if supplied) on SSR/SSG.
 
-## App router
+This limitation doesn't apply to the app router.
 
-This hook can be used with the app router in Next.js 13+, but
-**only in client components**.
+### Lossy serialization
 
-Next.js doesn't allow obtaining querystring parameters from server components.
+If your serializer loses precision or doesn't accurately represent
+the underlying state value, you will lose this precision when
+reloading the page or restoring state from the URL (eg: on navigation).
 
-The API is the same for both hooks, but you'll need to change your imports to:
+Example:
 
 ```ts
-import {
-  useQueryState,
-  useQueryStates,
-  queryTypes
-} from 'next-usequerystate/app' // <- note the /app here
-```
-
-In an later major version, the default import will stop pointing to the pages
-router implementation and switch to the app router (probably when Next.js
-starts marking the pages router as deprecated).
-
-In order to lock your usage of the hook to the pages router, you can change your
-imports to the following:
+const geoCoordParser = {
+  parse: parseFloat,
+  serialize: v => v.toFixed(4) // Loses precision
+}
 
-```ts
-import { useQueryState } from 'next-usequerystate/pages'
+const [lat, setLat] = useQueryState('lat', geoCoordParser)
 ```
 
-## Caveats
+Here, setting a latitude of 1.23456789 will render a URL query string
+of `lat=1.2345`, while the internal `lat` state will be correctly
+set to 1.23456789.
 
-Because the Next.js router is not available in an SSR context, this
-hook will always return `null` (or the default value if supplied) on SSR/SSG.
+Upon reloading the page, the state will be incorrectly set to 1.2345.
 
 ## License
 
diff --git a/app.d.ts b/app.d.ts
deleted file mode 100644
index aae85bba..00000000
--- a/app.d.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-// This file is needed for projects that have `moduleResolution` set to `node`
-// in their tsconfig.json to be able to `import {} from 'next-usequerystate/app'`.
-// Other module resolutions strategies will look for the `exports` in `package.json`,
-// but with `node`, TypeScript will look for a .d.ts file with that name at the
-// root of the package.
-
-export * from './dist/app'
diff --git a/cypress.config.ts b/cypress.config.ts
index 92d96aa6..85f57aef 100644
--- a/cypress.config.ts
+++ b/cypress.config.ts
@@ -1,8 +1,9 @@
 import { defineConfig } from 'cypress'
+import nextConfig from './next.config.mjs'
 
 export default defineConfig({
   e2e: {
-    baseUrl: 'http://localhost:3000',
+    baseUrl: `http://localhost:3000${nextConfig.basePath ?? ''}`,
     video: false,
     fixturesFolder: false,
     supportFile: false,
diff --git a/next.config.mjs b/next.config.mjs
new file mode 100644
index 00000000..1ddf4c0f
--- /dev/null
+++ b/next.config.mjs
@@ -0,0 +1,10 @@
+// @ts-check
+
+/**
+ * @type {import('next').NextConfig}
+ */
+const config = {
+  // basePath: '/basePath'
+}
+
+export default config
diff --git a/package.json b/package.json
index 24b5da1c..1facba1c 100644
--- a/package.json
+++ b/package.json
@@ -25,9 +25,7 @@
   },
   "files": [
     "dist/",
-    "useQueryState.gif",
-    "app.d.ts",
-    "pages.d.ts"
+    "useQueryState.gif"
   ],
   "type": "module",
   "sideEffects": false,
@@ -39,30 +37,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "types": "./dist/index.d.ts"
-    },
-    "./app": {
-      "import": "./dist/app.js",
-      "require": "./dist/app.cjs",
-      "types": "./dist/app.d.ts"
-    },
-    "./pages": {
-      "import": "./dist/pages.js",
-      "require": "./dist/pages.cjs",
-      "types": "./dist/pages.d.ts"
     }
   },
   "tsup": {
-    "entry": {
-      "index": "src/lib/index.ts",
-      "pages": "src/lib/index.pages.ts",
-      "app": "src/lib/index.app.ts"
-    }
+    "entry": [
+      "src/lib/index.ts"
+    ]
   },
   "scripts": {
     "dev": "run-p dev:*",
     "dev:build": "tsup --format esm --dts --watch",
     "dev:next": "next dev",
-    "build": "tsup --clean --format esm,cjs --dts",
+    "build": "tsup --clean --dts --format esm,cjs",
     "test": "run-p test:types test:e2e:ci",
     "test:types": "tsd",
     "test:e2e:ci": "run-p --race test:e2e:next:start cypress:run",
diff --git a/pages.d.ts b/pages.d.ts
deleted file mode 100644
index 80e79f48..00000000
--- a/pages.d.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-// This file is needed for projects that have `moduleResolution` set to `node`
-// in their tsconfig.json to be able to `import {} from 'next-usequerystate/pages'`.
-// Other module resolutions strategies will look for the `exports` in `package.json`,
-// but with `node`, TypeScript will look for a .d.ts file with that name at the
-// root of the package.
-
-export * from './dist/pages'
diff --git a/src/app/app/useQueryState/page.tsx b/src/app/app/useQueryState/page.tsx
index db567754..9a317424 100644
--- a/src/app/app/useQueryState/page.tsx
+++ b/src/app/app/useQueryState/page.tsx
@@ -3,13 +3,20 @@
 import Link from 'next/link'
 import { useRouter } from 'next/navigation'
 import React from 'react'
-import { queryTypes, useQueryState } from '../../../../dist/app'
+import {
+  parseAsBoolean,
+  parseAsFloat,
+  parseAsInteger,
+  parseAsString,
+  useQueryState
+} from '../../../../dist'
 
 export default function IntegrationPage() {
   const [numPanes, setNumPanes] = React.useState(1)
   return (
     <main>
-      <h1>useQueryState</h1>
+      <Link href="/">⬅️ Home</Link>
+      <h1>useQueryState integration test</h1>
       <nav>
         <button onClick={() => setNumPanes(n => n + 1)}>+</button>
         <button onClick={() => setNumPanes(n => n - 1)}>-</button>
@@ -77,7 +84,7 @@ const StringSection = () => {
 }
 
 const IntSection = () => {
-  const [int, setInt] = useQueryState('int', queryTypes.integer)
+  const [int, setInt] = useQueryState('int', parseAsInteger)
   return (
     <section>
       <h2>Integer</h2>
@@ -96,7 +103,7 @@ const IntSection = () => {
 }
 
 const FloatSection = () => {
-  const [float, setFloat] = useQueryState('float', queryTypes.float)
+  const [float, setFloat] = useQueryState('float', parseAsFloat)
   return (
     <section>
       <h2>Float</h2>
@@ -130,7 +137,7 @@ const FloatSection = () => {
 }
 
 const BoolSection = () => {
-  const [bool, setBool] = useQueryState('bool', queryTypes.boolean)
+  const [bool, setBool] = useQueryState('bool', parseAsBoolean)
   return (
     <section>
       <h2>Boolean</h2>
@@ -148,7 +155,7 @@ const BoolSection = () => {
 const TextSection = () => {
   const [text, setText] = useQueryState(
     'text',
-    queryTypes.string.withDefault('Hello, world!')
+    parseAsString.withDefault('Hello, world!')
   )
   return (
     <section>
diff --git a/src/app/app/useQueryStates/page.tsx b/src/app/app/useQueryStates/page.tsx
index 15d0110f..2b171a79 100644
--- a/src/app/app/useQueryStates/page.tsx
+++ b/src/app/app/useQueryStates/page.tsx
@@ -1,13 +1,19 @@
 'use client'
 
-import { queryTypes, useQueryStates } from '../../../../dist/app'
+import {
+  parseAsBoolean,
+  parseAsFloat,
+  parseAsInteger,
+  parseAsString,
+  useQueryStates
+} from '../../../../dist'
 
 const IntegrationPage = () => {
   const [state, setState] = useQueryStates({
-    string: queryTypes.string,
-    int: queryTypes.integer,
-    float: queryTypes.float,
-    bool: queryTypes.boolean
+    string: parseAsString,
+    int: parseAsInteger,
+    float: parseAsFloat,
+    bool: parseAsBoolean
   })
   return (
     <>
diff --git a/src/app/demos/batching/page.tsx b/src/app/demos/batching/page.tsx
new file mode 100644
index 00000000..42414826
--- /dev/null
+++ b/src/app/demos/batching/page.tsx
@@ -0,0 +1,40 @@
+'use client'
+
+import Link from 'next/link'
+import { useQueryState } from '../../../../dist'
+import { parseAsFloat } from '../../../lib'
+
+const parser = parseAsFloat.withDefault(0)
+
+export default function BuilderPatternDemoPage() {
+  const [lat, setLat] = useQueryState('lat', parser)
+  const [lng, setLng] = useQueryState('lng', parser)
+
+  const latStr = lat.toString().split('.')
+  const lngStr = lng.toString().split('.')
+
+  return (
+    <main>
+      <Link href="/">⬅️ Home</Link>
+      <h1>Batching</h1>
+      <button
+        onClick={async () => {
+          // Call as many state updates as needed in the same event loop tick,
+          // and they will be asynchronously batched into one update.
+          setLat(Math.random() * 180 - 90)
+          setLng(Math.random() * 360 - 180)
+        }}
+      >
+        Random coordinate
+      </button>
+      <pre>
+        <code>
+          {/* Aligning the decimals */}
+          Lat {latStr[0].padStart(4) + '.' + latStr[1]}
+          {'\n'}
+          Lng {lngStr[0].padStart(4) + '.' + lngStr[1]}
+        </code>
+      </pre>
+    </main>
+  )
+}
diff --git a/src/app/demos/builder-pattern/page.tsx b/src/app/demos/builder-pattern/page.tsx
new file mode 100644
index 00000000..9f2a8776
--- /dev/null
+++ b/src/app/demos/builder-pattern/page.tsx
@@ -0,0 +1,34 @@
+'use client'
+
+import Link from 'next/link'
+import { parseAsInteger, useQueryState } from '../../../../dist'
+
+export default function BuilderPatternDemoPage() {
+  const [counter, setCounter] = useQueryState(
+    'counter',
+    parseAsInteger
+      .withOptions({
+        history: 'push',
+        shallow: false,
+        scroll: true
+      })
+      .withDefault(0)
+  )
+
+  return (
+    <main>
+      <Link href="/">⬅️ Home</Link>
+      <h1>Builder pattern</h1>
+      <button onClick={() => setCounter(x => x - 1)}>-</button>
+      <button onClick={() => setCounter(x => x + 1)}>+</button>
+      <button onClick={() => setCounter(null)}>Reset</button>
+      <p>{counter}</p>
+      <p>
+        <em>
+          History is pushed, network requests are sent and scroll restoration is
+          enabled.
+        </em>
+      </p>
+    </main>
+  )
+}
diff --git a/src/app/demos/subscribeToQueryUpdates/page.tsx b/src/app/demos/subscribeToQueryUpdates/page.tsx
new file mode 100644
index 00000000..fab08d86
--- /dev/null
+++ b/src/app/demos/subscribeToQueryUpdates/page.tsx
@@ -0,0 +1,37 @@
+'use client'
+
+import Link from 'next/link'
+import React from 'react'
+import {
+  parseAsInteger,
+  subscribeToQueryUpdates,
+  useQueryState
+} from '../../../../dist'
+
+export default function BuilderPatternDemoPage() {
+  const [counter, setCounter] = useQueryState(
+    'counter',
+    parseAsInteger.withDefault(0)
+  )
+
+  React.useEffect(() => {
+    const off = subscribeToQueryUpdates(search =>
+      console.log(search.toString())
+    )
+    return off
+  }, [])
+
+  return (
+    <main>
+      <Link href="/">⬅️ Home</Link>
+      <h1>subscribeToQueryUpdates</h1>
+      <button onClick={() => setCounter(x => x - 1)}>-</button>
+      <button onClick={() => setCounter(x => x + 1)}>+</button>
+      <button onClick={() => setCounter(null)}>Reset</button>
+      <p>{counter}</p>
+      <p>
+        <em>Check the console</em>
+      </p>
+    </main>
+  )
+}
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index d71a2dac..701f0355 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,5 +1,9 @@
 import React from 'react'
 
+export const metadata = {
+  title: 'next-usequerystate playground'
+}
+
 export default function RootLayout({
   children
 }: {
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 8fa2aff9..815e771e 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,9 +1,26 @@
 import Link from 'next/link'
 
+const demos = ['builder-pattern', 'subscribeToQueryUpdates', 'batching']
+
 export default function IndexPage() {
   return (
     <main>
-      <h2>App router</h2>
+      <h1>next-usequerystate playground</h1>
+      <h2>Demos</h2>
+      <ul>
+        {demos.map(path => (
+          <li key={path}>
+            <Link href={`/demos/${path}`}>{path}</Link>
+          </li>
+        ))}
+      </ul>
+      <p>
+        <em>All demos use the app router.</em>
+      </p>
+      <hr />
+      <h2>End-to-end integration tests</h2>
+      <p>⚠️ Don't change these routes without updating integration tests.</p>
+      <h3>App router</h3>
       <ul>
         <li>
           <Link href="/app/useQueryState">[static] useQueryState</Link>
@@ -22,7 +39,7 @@ export default function IndexPage() {
           </Link>
         </li>
       </ul>
-      <h2>Pages router</h2>
+      <h3>Pages router</h3>
       <ul>
         <li>
           <Link href="/pages/useQueryState">[static] useQueryState</Link>
diff --git a/src/lib/defs.ts b/src/lib/defs.ts
index 3c2e8325..e4948db7 100644
--- a/src/lib/defs.ts
+++ b/src/lib/defs.ts
@@ -1,238 +1,313 @@
-export type HistoryOptions = 'replace' | 'push'
-
-export type Nullable<T> = {
-  [K in keyof T]: T[K] | null
-}
-
-export type Serializers<T> = {
-  parse: (value: string) => T | null
-  serialize?: (value: T) => string
-}
-
-export type SerializersWithDefaultFactory<T> = Serializers<T> & {
-  withDefault: (defaultValue: T) => Serializers<T> & {
-    readonly defaultValue: T
-  }
-}
+import { useRouter } from 'next/navigation'
 
-export type QueryTypeMap = Readonly<{
-  string: SerializersWithDefaultFactory<string>
-  integer: SerializersWithDefaultFactory<number>
-  float: SerializersWithDefaultFactory<number>
-  boolean: SerializersWithDefaultFactory<boolean>
+export type Router = ReturnType<typeof useRouter>
 
-  /**
-   * Querystring encoded as the number of milliseconds since epoch,
-   * and returned as a Date object.
-   */
-  timestamp: SerializersWithDefaultFactory<Date>
-
-  /**
-   * Querystring encoded as an ISO-8601 string (UTC),
-   * and returned as a Date object.
-   */
-  isoDateTime: SerializersWithDefaultFactory<Date>
+export type HistoryOptions = 'replace' | 'push'
 
+export type Options = {
   /**
-   * String-based enums provide better type-safety for known sets of values.
-   * You will need to pass the stringEnum function a list of your enum values
-   * in order to validate the query string. Anything else will return `null`,
-   * or your default value if specified.
-   *
-   * Example:
-   * ```ts
-   * enum Direction {
-   *   up = 'UP',
-   *   down = 'DOWN',
-   *   left = 'LEFT',
-   *   right = 'RIGHT'
-   * }
-   *
-   * const [direction, setDirection] = useQueryState(
-   *   'direction',
-   *   queryTypes
-   *     .stringEnum<Direction>(Object.values(Direction))
-   *     .withDefault(Direction.up)
-   * )
-   * ```
+   * How the query update affects page history
    *
-   * Note: the query string value will be the value of the enum, not its name
-   * (example above: `direction=UP`).
-   *
-   * @param validValues The values you want to accept
+   * `push` will create a new history entry, allowing to use the back/forward
+   * buttons to navigate state updates.
+   * `replace` (default) will keep the current history point and only replace
+   * the query string.
    */
-  stringEnum<Enum extends string>(
-    validValues: Enum[]
-  ): SerializersWithDefaultFactory<Enum>
+  history?: HistoryOptions
 
   /**
-   * Encode any object shape into the querystring value as JSON.
-   * Value is URI-encoded for safety, so it may not look nice in the URL.
-   * Note: you may want to use `useQueryStates` for finer control over
-   * multiple related query keys.
+   * Scroll to top after a query state update
    *
-   * @param parser optional parser (eg: Zod schema) to validate after JSON.parse
+   * Defaults to `false`, unlike the Next.js router page navigation methods.
    */
-  json<T>(parser?: (value: unknown) => T): SerializersWithDefaultFactory<T>
+  scroll?: boolean
 
   /**
-   * A comma-separated list of items.
-   * Items are URI-encoded for safety, so they may not look nice in the URL.
+   * Shallow mode (true by default) keeps query states update client-side only,
+   * meaning there won't be calls to the server.
    *
-   * @param itemSerializers Serializers for each individual item in the array
-   * @param separator The character to use to separate items (default ',')
+   * Setting it to `false` will trigger a network request to the server with
+   * the updated querystring.
    */
-  array<ItemType>(
-    itemSerializers: Serializers<ItemType>,
-    separator?: string
-  ): SerializersWithDefaultFactory<ItemType[]>
-}>
-
-export const queryTypes: QueryTypeMap = {
-  string: {
-    parse: v => v,
-    serialize: v => `${v}`,
-    withDefault(defaultValue) {
-      return {
-        ...this,
-        defaultValue
-      }
-    }
-  },
-  integer: {
-    parse: v => {
-      const int = parseInt(v)
-      if (Number.isNaN(int)) {
-        return null
+  shallow?: boolean
+}
+
+export type Nullable<T> = {
+  [K in keyof T]: T[K] | null
+}
+
+// Parsers defs ----------------------------------------------------------------
+
+export type Parser<T> = {
+  parse: (value: string) => T | null
+  serialize?: (value: T) => string
+}
+
+export type ParserBuilder<T> = Parser<T> &
+  Options & {
+    /**
+     * Set history type, shallow routing and scroll restoration options
+     * at the hook declaration level.
+     *
+     * Note that you can override those options in individual calls to the
+     * state updater function.
+     */
+    withOptions(
+      options: Options
+    ): Parser<T> & Readonly<Options> & Pick<ParserBuilder<T>, 'withDefault'>
+
+    /**
+     * Specifying a default value makes the hook state non-nullable when the
+     * query is missing from the URL.
+     *
+     * Note: if you wish to specify options as well, you need to call
+     * `withOptions` **before** `withDefault`.
+     *
+     * @param defaultValue
+     */
+    withDefault(defaultValue: NonNullable<T>): Parser<T> &
+      Options & {
+        readonly defaultValue: NonNullable<T>
       }
-      return int
-    },
-    serialize: v => Math.round(v).toFixed(),
+  }
+
+/**
+ * Wrap a set of parse/serialize functions into a builder pattern parser
+ * you can pass to one of the hooks, making its default value type safe.
+ */
+export function createParser<T>(parser: Parser<T>): ParserBuilder<T> {
+  return {
+    ...parser,
     withDefault(defaultValue) {
       return {
         ...this,
         defaultValue
       }
-    }
-  },
-  float: {
-    parse: v => {
-      const float = parseFloat(v)
-      if (Number.isNaN(float)) {
-        return null
-      }
-      return float
     },
-    serialize: v => v.toString(),
-    withDefault(defaultValue) {
+    withOptions(options: Options) {
       return {
         ...this,
-        defaultValue
+        ...options
       }
     }
-  },
-  boolean: {
-    parse: v => v === 'true',
-    serialize: v => (Boolean(v) ? 'true' : 'false'),
-    withDefault(defaultValue) {
-      return {
-        ...this,
-        defaultValue
-      }
+  }
+}
+
+// Parsers implementations -----------------------------------------------------
+
+export const parseAsString = createParser({
+  parse: v => v,
+  serialize: v => `${v}`
+})
+
+export const parseAsInteger = createParser({
+  parse: v => {
+    const int = parseInt(v)
+    if (Number.isNaN(int)) {
+      return null
     }
+    return int
   },
-  timestamp: {
-    parse: v => new Date(parseInt(v)),
-    serialize: (v: Date) => v.valueOf().toString(),
-    withDefault(defaultValue) {
-      return {
-        ...this,
-        defaultValue
-      }
+  serialize: v => Math.round(v).toFixed()
+})
+
+export const parseAsFloat = createParser({
+  parse: v => {
+    const float = parseFloat(v)
+    if (Number.isNaN(float)) {
+      return null
     }
+    return float
   },
-  isoDateTime: {
-    parse: v => new Date(v),
-    serialize: (v: Date) => v.toISOString(),
-    withDefault(defaultValue) {
-      return {
-        ...this,
-        defaultValue
+  serialize: v => v.toString()
+})
+
+export const parseAsBoolean = createParser({
+  parse: v => v === 'true',
+  serialize: v => (Boolean(v) ? 'true' : 'false')
+})
+
+/**
+ * Querystring encoded as the number of milliseconds since epoch,
+ * and returned as a Date object.
+ */
+export const parseAsTimestamp = createParser({
+  parse: v => new Date(parseInt(v)),
+  serialize: (v: Date) => v.valueOf().toString()
+})
+
+/**
+ * Querystring encoded as an ISO-8601 string (UTC),
+ * and returned as a Date object.
+ */
+export const parseAsIsoDateTime = createParser({
+  parse: v => new Date(v),
+  serialize: (v: Date) => v.toISOString()
+})
+
+/**
+ * String-based enums provide better type-safety for known sets of values.
+ * You will need to pass the stringEnum function a list of your enum values
+ * in order to validate the query string. Anything else will return `null`,
+ * or your default value if specified.
+ *
+ * Example:
+ * ```ts
+ * enum Direction {
+ *   up = 'UP',
+ *   down = 'DOWN',
+ *   left = 'LEFT',
+ *   right = 'RIGHT'
+ * }
+ *
+ * const [direction, setDirection] = useQueryState(
+ *   'direction',
+ *   queryTypes
+ *     .stringEnum<Direction>(Object.values(Direction))
+ *     .withDefault(Direction.up)
+ * )
+ * ```
+ *
+ * Note: the query string value will be the value of the enum, not its name
+ * (example above: `direction=UP`).
+ *
+ * @param validValues The values you want to accept
+ */
+export function parseAsStringEnum<Enum extends string>(validValues: Enum[]) {
+  return createParser({
+    parse: (query: string) => {
+      const asEnum = query as unknown as Enum
+      if (validValues.includes(asEnum)) {
+        return asEnum
       }
-    }
-  },
-  stringEnum<Enum extends string>(validValues: Enum[]) {
-    return {
-      parse: (query: string) => {
-        const asEnum = query as unknown as Enum
-        if (validValues.includes(asEnum)) {
-          return asEnum
+      return null
+    },
+    serialize: (value: Enum) => value.toString()
+  })
+}
+
+/**
+ * Encode any object shape into the querystring value as JSON.
+ * Value is URI-encoded for safety, so it may not look nice in the URL.
+ * Note: you may want to use `useQueryStates` for finer control over
+ * multiple related query keys.
+ *
+ * @param parser optional parser (eg: Zod schema) to validate after JSON.parse
+ */
+export function parseAsJson<T>(parser?: (value: unknown) => T) {
+  return createParser({
+    parse: query => {
+      try {
+        const obj = JSON.parse(decodeURIComponent(query))
+        if (typeof parser === 'function') {
+          return parser(obj)
+        } else {
+          return obj as T
         }
+      } catch {
         return null
-      },
-      serialize: (value: Enum) => value.toString(),
-      withDefault(defaultValue) {
-        return {
-          ...this,
-          defaultValue
-        }
       }
-    }
-  },
-  json<T>(parser?: (value: unknown) => T) {
-    return {
-      parse: query => {
-        try {
-          const obj = JSON.parse(decodeURIComponent(query))
-          if (typeof parser === 'function') {
-            return parser(obj)
-          } else {
-            return obj as T
-          }
-        } catch {
-          return null
-        }
-      },
-      serialize: value => encodeURIComponent(JSON.stringify(value)),
-      withDefault(defaultValue) {
-        return {
-          ...this,
-          defaultValue
-        }
-      }
-    }
-  },
-  array(itemSerializers, separator = ',') {
-    return {
-      parse: query => {
-        type ItemType = NonNullable<ReturnType<typeof itemSerializers.parse>>
-        if (query === '') {
-          // Empty query should not go through the split/map/filter logic,
-          // see https://github.com/47ng/next-usequerystate/issues/329
-          return [] as ItemType[]
-        }
-        return query
-          .split(separator)
-          .map(item => decodeURIComponent(item))
-          .map(itemSerializers.parse)
-          .filter(value => value !== null && value !== undefined) as ItemType[]
-      },
-      serialize: values =>
-        values
-          .map<string>(value => {
-            if (itemSerializers.serialize) {
-              return itemSerializers.serialize(value)
-            }
-            return `${value}`
-          })
-          .map(encodeURIComponent)
-          .join(separator),
-      withDefault(defaultValue) {
-        return {
-          ...this,
-          defaultValue
-        }
+    },
+    serialize: value => encodeURIComponent(JSON.stringify(value))
+  })
+}
+
+/**
+ * A comma-separated list of items.
+ * Items are URI-encoded for safety, so they may not look nice in the URL.
+ *
+ * @param itemParser Parser for each individual item in the array
+ * @param separator The character to use to separate items (default ',')
+ */
+export function parseAsArrayOf<ItemType>(
+  itemParser: Parser<ItemType>,
+  separator = ','
+) {
+  // todo: Handle default item values and make return type non-nullable
+  return createParser({
+    parse: query => {
+      if (query === '') {
+        // Empty query should not go through the split/map/filter logic,
+        // see https://github.com/47ng/next-usequerystate/issues/329
+        return [] as ItemType[]
       }
-    }
-  }
+      return query
+        .split(separator)
+        .map(item => decodeURIComponent(item))
+        .map(itemParser.parse)
+        .filter(value => value !== null && value !== undefined) as ItemType[]
+    },
+    serialize: values =>
+      values
+        .map<string>(value => {
+          if (itemParser.serialize) {
+            return itemParser.serialize(value)
+          }
+          return `${value}`
+        })
+        .map(encodeURIComponent)
+        .join(separator)
+  })
 }
+
+// Compatibility layer ---------------------------------------------------------
+
+/**
+ * @deprecated renamed to Parser
+ */
+export type Serializers<T> = Parser<T>
+
+/**
+ * @deprecated renamed to ParserBuilder.
+ * You should probably use `createParser` instead.
+ */
+export type SerializersWithDefaultFactory<T> = ParserBuilder<T>
+
+/**
+ * @deprecated use individual `parseAsXyz` imports instead.
+ */
+export const queryTypes = {
+  /**
+   * @deprecated use `parseAsString` instead.
+   */
+  string: parseAsString,
+  /**
+   * @deprecated use `parseAsInteger` instead.
+   */
+  integer: parseAsInteger,
+  /**
+   * @deprecated use `parseAsFloat` instead.
+   */
+  float: parseAsFloat,
+  /**
+   * @deprecated use `parseAsBoolean` instead.
+   */
+  boolean: parseAsBoolean,
+  /**
+   * @deprecated use `parseAsTimestamp` instead.
+   */
+  timestamp: parseAsTimestamp,
+  /**
+   * @deprecated use `parseAsIsoDateTime` instead.
+   */
+  isoDateTime: parseAsIsoDateTime,
+  /**
+   * @deprecated use `parseAsStringEnum` instead.
+   */
+  stringEnum: parseAsStringEnum,
+  /**
+   * @deprecated use `parseAsJson` instead.
+   */
+  json: parseAsJson,
+  /**
+   * @deprecated use `parseAsArrayOf` instead.
+   */
+  array: parseAsArrayOf
+} as const
+
+queryTypes.integer
+
+/**
+ * @deprecated use individual `parseAsXyz` imports instead
+ */
+export type QueryTypeMap = typeof queryTypes
diff --git a/src/lib/index.app.ts b/src/lib/index.app.ts
deleted file mode 100644
index 97fff580..00000000
--- a/src/lib/index.app.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-'use client'
-
-export * from './app/useQueryState'
-export * from './app/useQueryStates'
-export * from './defs'
diff --git a/src/lib/index.pages.ts b/src/lib/index.pages.ts
deleted file mode 100644
index 88eda80d..00000000
--- a/src/lib/index.pages.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-'use client'
-
-export * from './defs'
-export * from './pages/pagesRouterDefs'
-export * from './pages/useQueryState'
-export * from './pages/useQueryStates'
diff --git a/src/lib/index.ts b/src/lib/index.ts
index ae4c29fe..c1d01ba2 100644
--- a/src/lib/index.ts
+++ b/src/lib/index.ts
@@ -1,3 +1,6 @@
 'use client'
 
-export * from './index.pages'
+export * from './defs'
+export { subscribeToQueryUpdates } from './sync'
+export * from './useQueryState'
+export * from './useQueryStates'
diff --git a/src/lib/pages/pagesRouterDefs.ts b/src/lib/pages/pagesRouterDefs.ts
deleted file mode 100644
index 0710ac01..00000000
--- a/src/lib/pages/pagesRouterDefs.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import type { Router } from 'next/router'
-
-// Next.js does not export the TransitionsOption interface,
-// but we can get it from where it's used:
-export type TransitionOptions = Parameters<Router['push']>[2]
diff --git a/src/lib/pages/useQueryState.ts b/src/lib/pages/useQueryState.ts
deleted file mode 100644
index 93e2a6dc..00000000
--- a/src/lib/pages/useQueryState.ts
+++ /dev/null
@@ -1,280 +0,0 @@
-import { useRouter } from 'next/router'
-import React from 'react'
-import type { HistoryOptions, Serializers } from '../defs'
-import type { TransitionOptions } from './pagesRouterDefs'
-
-export interface UseQueryStateOptions<T> extends Serializers<T> {
-  /**
-   * The operation to use on state updates. Defaults to `replace`.
-   */
-  history?: HistoryOptions
-}
-
-export type UseQueryStateReturn<Parsed, Default> = [
-  Default extends undefined
-    ? Parsed | null // value can't be null if default is specified
-    : Parsed,
-  (
-    value:
-      | null
-      | Parsed
-      | ((
-          old: Default extends Parsed ? Parsed : Parsed | null
-        ) => Parsed | null),
-    transitionOptions?: TransitionOptions
-  ) => Promise<boolean>
-]
-
-// Overload type signatures ----------------------------------------------------
-// Note: the order of declaration matters (from the most specific to the least).
-
-/**
- * React state hook synchronized with a URL query string in Next.js
- *
- * This variant is used when providing a default value. This will make
- * the returned state non-nullable when the query is not present in the URL.
- * (the default value will be returned instead).
- *
- * _Note: the URL will **not** be updated with the default value if the query
- * is missing._
- *
- * Setting the value to `null` will clear the query in the URL, and return
- * the default value as state.
- *
- * Example usage:
- * ```ts
- *   const [count, setCount] = useQueryState(
- *     'count',
- *     queryTypes.integer.defaultValue(0)
- *   )
- *
- *   const increment = () => setCount(oldCount => oldCount + 1)
- *   const decrement = () => setCount(oldCount => oldCount - 1)
- *   const clearCountQuery = () => setCount(null)
- * ```
- * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), default value and optional history mode.
- */
-export function useQueryState<T>(
-  key: string,
-  options: UseQueryStateOptions<T> & { defaultValue: T }
-): UseQueryStateReturn<
-  NonNullable<ReturnType<typeof options.parse>>,
-  typeof options.defaultValue
->
-
-/**
- * React state hook synchronized with a URL query string in Next.js
- *
- * If the query is missing in the URL, the state will be `null`.
- *
- * Example usage:
- * ```ts
- *   // Blog posts filtering by tag
- *   const [tag, selectTag] = useQueryState('tag')
- *   const filteredPosts = posts.filter(post => tag ? post.tag === tag : true)
- *   const clearTag = () => selectTag(null)
- * ```
- * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), and optional history mode.
- */
-export function useQueryState<T>(
-  key: string,
-  options: UseQueryStateOptions<T>
-): UseQueryStateReturn<NonNullable<ReturnType<typeof options.parse>>, undefined>
-
-/**
- * Default type string, limited options & default value
- */
-export function useQueryState(
-  key: string,
-  options: {
-    history?: HistoryOptions
-    defaultValue: string
-  }
-): UseQueryStateReturn<string, typeof options.defaultValue>
-
-/**
- * React state hook synchronized with a URL query string in Next.js
- *
- * If the query is missing in the URL, the state will be `null`.
- *
- * Note: by default the state type is a `string`. To use different types,
- * check out the `queryTypes` helpers:
- * ```ts
- *   const [date, setDate] = useQueryState(
- *     'date',
- *     queryTypes.isoDateTime.withDefault(new Date('2021-01-01'))
- *   )
- *
- *   const setToNow = () => setDate(new Date())
- *   const addOneHour = () => {
- *     setDate(oldDate => new Date(oldDate.valueOf() + 3600_000))
- *   }
- * ```
- * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), and optional history mode.
- */
-export function useQueryState(
-  key: string,
-  options: Pick<UseQueryStateOptions<string>, 'history'>
-): UseQueryStateReturn<string, undefined>
-
-/**
- * React state hook synchronized with a URL query string in Next.js
- *
- * If the query is missing in the URL, the state will be `null`.
- *
- * Note: by default the state type is a `string`. To use different types,
- * check out the `queryTypes` helpers:
- * ```ts
- *   const [date, setDate] = useQueryState(
- *     'date',
- *     queryTypes.isoDateTime.withDefault(new Date('2021-01-01'))
- *   )
- *
- *   const setToNow = () => setDate(new Date())
- *   const addOneHour = () => {
- *     setDate(oldDate => new Date(oldDate.valueOf() + 3600_000))
- *   }
- * ```
- * @param key The URL query string key to bind to
- */
-export function useQueryState(
-  key: string
-): UseQueryStateReturn<string, undefined>
-
-/**
- * React state hook synchronized with a URL query string in Next.js
- *
- * If used without a `defaultValue` supplied in the options, and the query is
- * missing in the URL, the state will be `null`.
- *
- * ### Behaviour with default values:
- *
- * _Note: the URL will **not** be updated with the default value if the query
- * is missing._
- *
- * Setting the value to `null` will clear the query in the URL, and return
- * the default value as state.
- *
- * Example usage:
- * ```ts
- *   // Blog posts filtering by tag
- *   const [tag, selectTag] = useQueryState('tag')
- *   const filteredPosts = posts.filter(post => tag ? post.tag === tag : true)
- *   const clearTag = () => selectTag(null)
- *
- *   // With default values
- *
- *   const [count, setCount] = useQueryState(
- *     'count',
- *     queryTypes.integer.defaultValue(0)
- *   )
- *
- *   const increment = () => setCount(oldCount => oldCount + 1)
- *   const decrement = () => setCount(oldCount => oldCount - 1)
- *   const clearCountQuery = () => setCount(null)
- *
- *   // --
- *
- *   const [date, setDate] = useQueryState(
- *     'date',
- *     queryTypes.isoDateTime.withDefault(new Date('2021-01-01'))
- *   )
- *
- *   const setToNow = () => setDate(new Date())
- *   const addOneHour = () => {
- *     setDate(oldDate => new Date(oldDate.valueOf() + 3600_000))
- *   }
- * ```
- * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), optional default value and history mode.
- */
-export function useQueryState<T = string>(
-  key: string,
-  {
-    history = 'replace',
-    parse = x => x as unknown as T,
-    serialize = String,
-    defaultValue = undefined
-  }: Partial<UseQueryStateOptions<T>> & { defaultValue?: T } = {
-    history: 'replace',
-    parse: x => x as unknown as T,
-    serialize: String,
-    defaultValue: undefined
-  }
-) {
-  const router = useRouter()
-
-  // Memoizing the update function has the advantage of making it
-  // immutable as long as `history` stays the same.
-  // It reduces the amount of reactivity needed to update the state.
-  const updateUrl = React.useMemo(
-    () => (history === 'push' ? router.push : router.replace),
-    [history]
-  )
-
-  const getValue = React.useCallback((): T | null => {
-    if (typeof window === 'undefined') {
-      // Not available in an SSR context
-      return null
-    }
-    const query = new URLSearchParams(window.location.search)
-    const value = query.get(key)
-    return value !== null ? parse(value) : null
-  }, [])
-
-  // Update the state value only when the relevant key changes.
-  // Because we're not calling getValue in the function argument
-  // of React.useMemo, but instead using it as the function to call,
-  // there is no need to pass it in the dependency array.
-  const value = React.useMemo(getValue, [router.query[key]])
-
-  const update = React.useCallback(
-    (
-      stateUpdater: React.SetStateAction<T | null>, // todo: This is wrong now
-      transitionOptions?: TransitionOptions
-    ) => {
-      const isUpdaterFunction = (
-        input: any
-      ): input is (prevState: T | null) => T | null => {
-        return typeof input === 'function'
-      }
-
-      // Resolve the new value based on old value & updater
-      const oldValue = getValue() ?? defaultValue ?? null
-      const newValue = isUpdaterFunction(stateUpdater)
-        ? stateUpdater(oldValue)
-        : stateUpdater
-      // We can't rely on router.query here to avoid causing
-      // unnecessary renders when other query parameters change.
-      // URLSearchParams is already polyfilled by Next.js
-      const query = new URLSearchParams(window.location.search)
-      if (newValue === null) {
-        // Don't leave value-less keys hanging
-        query.delete(key)
-      } else {
-        query.set(key, serialize(newValue))
-      }
-      const search = query.toString()
-      const hash = window.location.hash
-      return updateUrl?.call(
-        router,
-        {
-          pathname: router.pathname,
-          hash,
-          search
-        },
-        {
-          pathname: window.location.pathname,
-          hash,
-          search
-        },
-        transitionOptions
-      )
-    },
-    [key, updateUrl]
-  )
-  return [value ?? defaultValue ?? null, update]
-}
diff --git a/src/lib/pages/useQueryStates.ts b/src/lib/pages/useQueryStates.ts
deleted file mode 100644
index 3e153264..00000000
--- a/src/lib/pages/useQueryStates.ts
+++ /dev/null
@@ -1,146 +0,0 @@
-import { useRouter } from 'next/router'
-import React from 'react'
-import type { HistoryOptions, Nullable, Serializers } from '../defs'
-import type { TransitionOptions } from './pagesRouterDefs'
-
-type KeyMapValue<Type> = Serializers<Type> & {
-  defaultValue?: Type
-}
-
-export type UseQueryStatesKeysMap<Map = any> = {
-  [Key in keyof Map]: KeyMapValue<Map[Key]>
-}
-
-export interface UseQueryStatesOptions {
-  /**
-   * The operation to use on state updates. Defaults to `replace`.
-   */
-  history: HistoryOptions
-}
-
-export type Values<T extends UseQueryStatesKeysMap> = {
-  [K in keyof T]: T[K]['defaultValue'] extends NonNullable<
-    ReturnType<T[K]['parse']>
-  >
-    ? NonNullable<ReturnType<T[K]['parse']>>
-    : ReturnType<T[K]['parse']> | null
-}
-
-type UpdaterFn<T extends UseQueryStatesKeysMap> = (
-  old: Values<T>
-) => Partial<Nullable<Values<T>>>
-
-export type SetValues<T extends UseQueryStatesKeysMap> = (
-  values: Partial<Nullable<Values<T>>> | UpdaterFn<T>,
-  transitionOptions?: TransitionOptions
-) => Promise<boolean>
-
-export type UseQueryStatesReturn<T extends UseQueryStatesKeysMap> = [
-  Values<T>,
-  SetValues<T>
-]
-
-/**
- * Synchronise multiple query string arguments to React state in Next.js
- *
- * @param keys - An object describing the keys to synchronise and how to
- *               serialise and parse them.
- *               Use `queryTypes.(string|integer|float)` for quick shorthands.
- */
-export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
-  keys: KeyMap,
-  { history = 'replace' }: Partial<UseQueryStatesOptions> = {}
-): UseQueryStatesReturn<KeyMap> {
-  const router = useRouter()
-
-  type V = Values<KeyMap>
-
-  // Memoizing the update function has the advantage of making it
-  // immutable as long as `history` stays the same.
-  // It reduces the amount of reactivity needed to update the state.
-  const updateUrl = React.useMemo(
-    () => (history === 'push' ? router.push : router.replace),
-    [history]
-  )
-
-  const getValues = React.useCallback((): V => {
-    if (typeof window === 'undefined') {
-      // Not available in an SSR context, return all null (or default if available)
-      return Object.keys(keys).reduce((obj, key) => {
-        const { defaultValue } = keys[key as keyof KeyMap]
-        return {
-          ...obj,
-          [key]: defaultValue ?? null
-        }
-      }, {} as V)
-    }
-    const query = new URLSearchParams(window.location.search)
-    return Object.keys(keys).reduce((values, key) => {
-      const { parse, defaultValue } = keys[key as keyof KeyMap]
-      const value = query.get(key)
-      const parsed =
-        value !== null
-          ? parse(value) ?? defaultValue ?? null
-          : defaultValue ?? null
-      return {
-        ...values,
-        [key]: parsed
-      }
-    }, {} as V)
-  }, [keys])
-
-  // Update the state values only when the relevant keys change.
-  // Because we're not calling getValues in the function argument
-  // of React.useMemo, but instead using it as the function to call,
-  // there is no need to pass it in the dependency array.
-  const values = React.useMemo(
-    getValues,
-    Object.keys(keys).map(key => router.query[key])
-  )
-
-  const update = React.useCallback<SetValues<KeyMap>>(
-    (stateUpdater, transitionOptions) => {
-      const isUpdaterFunction = (input: any): input is UpdaterFn<KeyMap> => {
-        return typeof input === 'function'
-      }
-
-      // Resolve the new values based on old values & updater
-      const oldValues = getValues()
-      const newValues = isUpdaterFunction(stateUpdater)
-        ? stateUpdater(oldValues)
-        : stateUpdater
-      // We can't rely on router.query here to avoid causing
-      // unnecessary renders when other query parameters change.
-      // URLSearchParams is already polyfilled by Next.js
-      const query = new URLSearchParams(window.location.search)
-
-      Object.keys(newValues).forEach(key => {
-        const newValue = newValues[key]
-        if (newValue === null) {
-          query.delete(key)
-        } else if (newValue !== undefined) {
-          const { serialize = String } = keys[key]
-          query.set(key, serialize(newValue))
-        }
-      })
-      const search = query.toString()
-      const hash = window.location.hash
-      return updateUrl?.call(
-        router,
-        {
-          pathname: router.pathname,
-          hash,
-          search
-        },
-        {
-          pathname: window.location.pathname,
-          hash,
-          search
-        },
-        transitionOptions
-      )
-    },
-    [keys, updateUrl]
-  )
-  return [values, update]
-}
diff --git a/src/lib/sync.ts b/src/lib/sync.ts
index da2c8e8a..60773554 100644
--- a/src/lib/sync.ts
+++ b/src/lib/sync.ts
@@ -3,14 +3,23 @@ import React from 'react'
 
 export const SYNC_EVENT_KEY = Symbol('__nextUseQueryState__SYNC__')
 export const NOSYNC_MARKER = '__nextUseQueryState__NO_SYNC__'
+export const NOTIFY_EVENT_KEY = Symbol('__nextUseQueryState__NOTIFY__')
 
 type EventMap = {
   [SYNC_EVENT_KEY]: URLSearchParams
+  [NOTIFY_EVENT_KEY]: URLSearchParams
   [key: string]: any
 }
 
 export const emitter = Mitt<EventMap>()
 
+export function subscribeToQueryUpdates(
+  callback: (search: URLSearchParams) => void
+) {
+  emitter.on(NOTIFY_EVENT_KEY, callback)
+  return () => emitter.off(NOTIFY_EVENT_KEY, callback)
+}
+
 let patched = false
 
 export function usePatchedHistory() {
diff --git a/src/lib/update-queue.ts b/src/lib/update-queue.ts
index 3f7a4be7..29aa0ed0 100644
--- a/src/lib/update-queue.ts
+++ b/src/lib/update-queue.ts
@@ -1,5 +1,5 @@
-import { HistoryOptions } from './defs'
-import { NOSYNC_MARKER } from './sync'
+import { Options, Router } from './defs'
+import { NOSYNC_MARKER, NOTIFY_EVENT_KEY, emitter } from './sync'
 
 // 50ms between calls to the history API seems to satisfy Chrome and Firefox.
 // Safari remains annoying with at most 100 calls in 30 seconds. #wontfix
@@ -8,7 +8,7 @@ const FLUSH_RATE_LIMIT_MS = 50
 type UpdateQueueItem = {
   key: string
   value: string | null
-  history: HistoryOptions
+  options: Options
 }
 
 let updateQueue: UpdateQueueItem[] = []
@@ -18,12 +18,12 @@ export function enqueueQueryStringUpdate<Value>(
   key: string,
   value: Value | null,
   serialize: (value: Value) => string,
-  history: HistoryOptions
+  options: Options
 ) {
   const queueItem: UpdateQueueItem = {
     key,
     value: value === null ? null : serialize(value),
-    history
+    options
   }
   // console.debug('Pushing to queue %O', queueItem)
   updateQueue.push(queueItem)
@@ -39,7 +39,7 @@ export function enqueueQueryStringUpdate<Value>(
  *
  * @returns a Promise to the URLSearchParams that have been applied.
  */
-export function flushToURL() {
+export function flushToURL(router: Router) {
   return new Promise<URLSearchParams>((resolve, reject) => {
     const now = performance.now()
     const timeSinceLastFlush = now - lastFlushTimestamp
@@ -50,7 +50,7 @@ export function flushToURL() {
     // console.debug('Scheduling flush in %f ms', flushInMs)
     setTimeout(() => {
       lastFlushTimestamp = performance.now()
-      const search = flushUpdateQueue()
+      const search = flushUpdateQueue(router)
       if (!search) {
         reject()
       } else {
@@ -60,7 +60,7 @@ export function flushToURL() {
   })
 }
 
-function flushUpdateQueue() {
+function flushUpdateQueue(router: Router) {
   const search = new URLSearchParams(window.location.search)
   if (updateQueue.length === 0) {
     return search
@@ -70,40 +70,62 @@ function flushUpdateQueue() {
   updateQueue = []
   // console.debug('Flushing queue %O', items)
 
-  // By default, history mode is set to 'replace',
-  // unless at least one item is set to 'push',
-  // in which case push takes precedence.
-  let history: HistoryOptions = 'replace'
+  const options: Required<Options> = {
+    history: 'replace',
+    scroll: false,
+    shallow: true
+  }
   for (const item of items) {
     if (item.value === null) {
       search.delete(item.key)
     } else {
       search.set(item.key, item.value)
     }
-    if (item.history === 'push') {
-      history = 'push'
+    // Any item can override an option for the whole batch of updates
+    if (item.options.history === 'push') {
+      options.history = 'push'
+    }
+    if (item.options.scroll) {
+      options.scroll = true
+    }
+    if (item.options.shallow === false) {
+      options.shallow = false
     }
   }
   const query = search.toString()
   const path = window.location.pathname
   const hash = window.location.hash
-  const updateUrl =
-    history === 'push' ? window.history.pushState : window.history.replaceState
 
   // If the querystring is empty, add the pathname to clear it out,
   // otherwise using a relative URL works just fine.
+  // todo: Does it when using the router with `shallow: false` on dynamic paths?
   const url = query ? `?${query}${hash}` : `${path}${hash}`
   try {
-    updateUrl.call(
-      window.history,
-      window.history.state,
-      // Our own updates have a marker to prevent syncing
-      // when the URL changes (we've already sync'd them up
-      // via `emitter.emit(key, newValue)` above, without
-      // going through the parsers).
-      NOSYNC_MARKER,
-      url
-    )
+    if (options.shallow) {
+      const updateUrl =
+        options.history === 'push'
+          ? window.history.pushState
+          : window.history.replaceState
+      updateUrl.call(
+        window.history,
+        window.history.state,
+        // Our own updates have a marker to prevent syncing
+        // when the URL changes (we've already sync'd them up
+        // via `emitter.emit(key, newValue)` above, without
+        // going through the parsers).
+        NOSYNC_MARKER,
+        url
+      )
+      if (options.scroll) {
+        window.scrollTo(0, 0)
+      }
+    } else {
+      // Call the Next.js router to perform a network request
+      const updateUrl =
+        options.history === 'push' ? router.push : router.replace
+      updateUrl.call(router, url, { scroll: options.scroll })
+    }
+    emitter.emit(NOTIFY_EVENT_KEY, search)
     return search
   } catch (error) {
     console.error(
diff --git a/src/lib/app/useQueryState.ts b/src/lib/useQueryState.ts
similarity index 79%
rename from src/lib/app/useQueryState.ts
rename to src/lib/useQueryState.ts
index 48642ec0..b1c97554 100644
--- a/src/lib/app/useQueryState.ts
+++ b/src/lib/useQueryState.ts
@@ -1,15 +1,10 @@
-import { useSearchParams } from 'next/navigation'
+import { useRouter, useSearchParams } from 'next/navigation'
 import React from 'react'
-import type { HistoryOptions, Serializers } from '../defs'
-import { SYNC_EVENT_KEY, emitter, usePatchedHistory } from '../sync'
-import { enqueueQueryStringUpdate, flushToURL } from '../update-queue'
+import type { Options, Parser } from './defs'
+import { SYNC_EVENT_KEY, emitter, usePatchedHistory } from './sync'
+import { enqueueQueryStringUpdate, flushToURL } from './update-queue'
 
-export interface UseQueryStateOptions<T> extends Serializers<T> {
-  /**
-   * The operation to use on state updates. Defaults to `replace`.
-   */
-  history?: HistoryOptions
-}
+export interface UseQueryStateOptions<T> extends Parser<T>, Options {}
 
 export type UseQueryStateReturn<Parsed, Default> = [
   Default extends undefined
@@ -21,7 +16,8 @@ export type UseQueryStateReturn<Parsed, Default> = [
       | Parsed
       | ((
           old: Default extends Parsed ? Parsed : Parsed | null
-        ) => Parsed | null)
+        ) => Parsed | null),
+    options?: Options
   ) => Promise<URLSearchParams>
 ]
 
@@ -54,7 +50,7 @@ export type UseQueryStateReturn<Parsed, Default> = [
  *   const clearCountQuery = () => setCount(null)
  * ```
  * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), default value and optional history mode.
+ * @param options - Parser (defines the state data type), default value and optional history mode.
  */
 export function useQueryState<T>(
   key: string,
@@ -77,7 +73,7 @@ export function useQueryState<T>(
  *   const clearTag = () => selectTag(null)
  * ```
  * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), and optional history mode.
+ * @param options - Parser (defines the state data type), and optional history mode.
  */
 export function useQueryState<T>(
   key: string,
@@ -89,8 +85,7 @@ export function useQueryState<T>(
  */
 export function useQueryState(
   key: string,
-  options: {
-    history?: HistoryOptions
+  options: Options & {
     defaultValue: string
   }
 ): UseQueryStateReturn<string, typeof options.defaultValue>
@@ -114,11 +109,11 @@ export function useQueryState(
  *   }
  * ```
  * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), and optional history mode.
+ * @param options - Parser (defines the state data type), and optional history mode.
  */
 export function useQueryState(
   key: string,
-  options: Pick<UseQueryStateOptions<string>, 'history'>
+  options: Pick<UseQueryStateOptions<string>, keyof Options>
 ): UseQueryStateReturn<string, undefined>
 
 /**
@@ -190,33 +185,37 @@ export function useQueryState(
  *   }
  * ```
  * @param key The URL query string key to bind to
- * @param options - Serializers (defines the state data type), optional default value and history mode.
+ * @param options - Parser (defines the state data type), optional default value and history mode.
  */
 export function useQueryState<T = string>(
   key: string,
   {
     history = 'replace',
+    shallow = true,
+    scroll = false,
     parse = x => x as unknown as T,
     serialize = String,
     defaultValue = undefined
   }: Partial<UseQueryStateOptions<T>> & { defaultValue?: T } = {
     history: 'replace',
+    scroll: false,
+    shallow: true,
     parse: x => x as unknown as T,
     serialize: String,
     defaultValue: undefined
   }
 ) {
   usePatchedHistory()
+  const router = useRouter()
   // Not reactive, but available on the server and on page load
   const initialSearchParams = useSearchParams()
-  const [internalState, setInternalState] = React.useState(() => {
-    if (typeof window !== 'object') {
-      // SSR
-      const value = initialSearchParams?.get(key) ?? null
-      return value === null ? null : parse(value)
-    }
-    // Components mounted way after page load must use the current URL value
-    const value = new URLSearchParams(window.location.search).get(key) ?? null
+  const [internalState, setInternalState] = React.useState<T | null>(() => {
+    const value =
+      typeof window !== 'object'
+        ? // SSR
+          initialSearchParams?.get(key) ?? null
+        : // Components mounted after page load must use the current URL value
+          new URLSearchParams(window.location.search).get(key) ?? null
     return value === null ? null : parse(value)
   })
   // console.debug(`render ${key}: ${internalState}`)
@@ -238,17 +237,17 @@ export function useQueryState<T = string>(
   }, [key])
 
   const update = React.useCallback(
-    (stateUpdater: React.SetStateAction<T | null>) => {
+    (stateUpdater: React.SetStateAction<T | null>, options: Options = {}) => {
       const isUpdaterFunction = (
         input: any
       ): input is (prevState: T | null) => T | null => {
         return typeof input === 'function'
       }
 
-      // Resolve the new value based on old value & updater
-      const search = new URLSearchParams(window.location.search)
       let newValue: T | null = null
       if (isUpdaterFunction(stateUpdater)) {
+        // Resolve the new value based on old value & updater
+        const search = new URLSearchParams(window.location.search)
         const serialized = search.get(key) ?? null
         const oldValue =
           serialized === null
@@ -261,11 +260,15 @@ export function useQueryState<T = string>(
 
       // Sync all hooks state (including this one)
       emitter.emit(key, newValue)
-
-      enqueueQueryStringUpdate(key, newValue, serialize, history)
-      return flushToURL()
+      enqueueQueryStringUpdate(key, newValue, serialize, {
+        // Call-level options take precedence over hook declaration options.
+        history: options.history ?? history,
+        shallow: options.shallow ?? shallow,
+        scroll: options.scroll ?? scroll
+      })
+      return flushToURL(router)
     },
-    [key, history]
+    [key, history, shallow, scroll]
   )
   return [internalState ?? defaultValue ?? null, update]
 }
diff --git a/src/lib/app/useQueryStates.ts b/src/lib/useQueryStates.ts
similarity index 76%
rename from src/lib/app/useQueryStates.ts
rename to src/lib/useQueryStates.ts
index ef4dbcbb..2a3e505e 100644
--- a/src/lib/app/useQueryStates.ts
+++ b/src/lib/useQueryStates.ts
@@ -1,10 +1,14 @@
-import { ReadonlyURLSearchParams, useSearchParams } from 'next/navigation'
+import {
+  ReadonlyURLSearchParams,
+  useRouter,
+  useSearchParams
+} from 'next/navigation'
 import React from 'react'
-import type { HistoryOptions, Nullable, Serializers } from '../defs'
-import { SYNC_EVENT_KEY, emitter, usePatchedHistory } from '../sync'
-import { enqueueQueryStringUpdate, flushToURL } from '../update-queue'
+import type { Nullable, Options, Parser } from './defs'
+import { SYNC_EVENT_KEY, emitter, usePatchedHistory } from './sync'
+import { enqueueQueryStringUpdate, flushToURL } from './update-queue'
 
-type KeyMapValue<Type> = Serializers<Type> & {
+type KeyMapValue<Type> = Parser<Type> & {
   defaultValue?: Type
 }
 
@@ -12,12 +16,7 @@ export type UseQueryStatesKeysMap<Map = any> = {
   [Key in keyof Map]: KeyMapValue<Map[Key]>
 }
 
-export interface UseQueryStatesOptions {
-  /**
-   * The operation to use on state updates. Defaults to `replace`.
-   */
-  history: HistoryOptions
-}
+export interface UseQueryStatesOptions extends Options {}
 
 export type Values<T extends UseQueryStatesKeysMap> = {
   [K in keyof T]: T[K]['defaultValue'] extends NonNullable<
@@ -32,8 +31,9 @@ type UpdaterFn<T extends UseQueryStatesKeysMap> = (
 ) => Partial<Nullable<Values<T>>>
 
 export type SetValues<T extends UseQueryStatesKeysMap> = (
-  values: Partial<Nullable<Values<T>>> | UpdaterFn<T>
-) => void
+  values: Partial<Nullable<Values<T>>> | UpdaterFn<T>,
+  options?: Options
+) => Promise<URLSearchParams>
 
 export type UseQueryStatesReturn<T extends UseQueryStatesKeysMap> = [
   Values<T>,
@@ -46,14 +46,19 @@ export type UseQueryStatesReturn<T extends UseQueryStatesKeysMap> = [
  * @param keys - An object describing the keys to synchronise and how to
  *               serialise and parse them.
  *               Use `queryTypes.(string|integer|float)` for quick shorthands.
- * @param options - Optional history mode.
+ * @param options - Optional history mode, shallow routing and scroll restoration options.
  */
 export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
   keyMap: KeyMap,
-  { history = 'replace' }: Partial<UseQueryStatesOptions> = {}
+  {
+    history = 'replace',
+    scroll = false,
+    shallow = true
+  }: Partial<UseQueryStatesOptions> = {}
 ): UseQueryStatesReturn<KeyMap> {
   type V = Values<KeyMap>
   usePatchedHistory()
+  const router = useRouter()
   // Not reactive, but available on the server and on page load
   const initialSearchParams = useSearchParams()
   const [internalState, setInternalState] = React.useState<V>(() => {
@@ -61,7 +66,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       // SSR
       return parseMap(keyMap, initialSearchParams ?? new URLSearchParams())
     }
-    // Components mounted way after page load must use the current URL value
+    // Components mounted after page load must use the current URL value
     return parseMap(keyMap, new URLSearchParams(window.location.search))
   })
 
@@ -95,7 +100,7 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
   }, [keyMap])
 
   const update = React.useCallback<SetValues<KeyMap>>(
-    stateUpdater => {
+    (stateUpdater, options = {}) => {
       const isUpdaterFunction = (input: any): input is UpdaterFn<KeyMap> => {
         return typeof input === 'function'
       }
@@ -113,11 +118,16 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
       for (const [key, value] of Object.entries(newState)) {
         const { serialize } = keyMap[key]
         emitter.emit(key, value)
-        enqueueQueryStringUpdate(key, value, serialize ?? String, history)
+        enqueueQueryStringUpdate(key, value, serialize ?? String, {
+          // Call-level options take precedence over hook declaration options.
+          history: options.history ?? history,
+          shallow: options.shallow ?? shallow,
+          scroll: options.scroll ?? scroll
+        })
       }
-      return flushToURL()
+      return flushToURL(router)
     },
-    [keyMap, history]
+    [keyMap, history, shallow, scroll]
   )
   return [internalState, update]
 }
diff --git a/src/pages/pages/useQueryState/index.tsx b/src/pages/pages/useQueryState/index.tsx
index 406e81d6..b48ae6e6 100644
--- a/src/pages/pages/useQueryState/index.tsx
+++ b/src/pages/pages/useQueryState/index.tsx
@@ -3,7 +3,7 @@
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
 import React from 'react'
-import { queryTypes, useQueryState } from '../../../../dist/app'
+import { queryTypes, useQueryState } from '../../../../dist'
 
 const IntegrationPage = () => {
   const [string, setString] = useQueryState('string')
diff --git a/src/pages/pages/useQueryStates/index.tsx b/src/pages/pages/useQueryStates/index.tsx
index 448052c2..0139468c 100644
--- a/src/pages/pages/useQueryStates/index.tsx
+++ b/src/pages/pages/useQueryStates/index.tsx
@@ -1,6 +1,6 @@
 'use client'
 
-import { queryTypes, useQueryStates } from '../../../../dist/pages'
+import { queryTypes, useQueryStates } from '../../../../dist'
 
 const IntegrationPage = () => {
   const [state, setState] = useQueryStates({
diff --git a/src/tests/pages/useQueryState.test-d.ts b/src/tests/compat/useQueryState.test-d.ts
similarity index 96%
rename from src/tests/pages/useQueryState.test-d.ts
rename to src/tests/compat/useQueryState.test-d.ts
index bfd2e48f..30d93dfa 100644
--- a/src/tests/pages/useQueryState.test-d.ts
+++ b/src/tests/compat/useQueryState.test-d.ts
@@ -1,5 +1,5 @@
 import { expectError, expectNotAssignable, expectType } from 'tsd'
-import { queryTypes, useQueryState } from '../../../dist/pages'
+import { queryTypes, useQueryState } from '../../../dist'
 
 // By default, queries have a `string` state, nullable (when no query parameter is present)
 {
@@ -7,8 +7,8 @@ import { queryTypes, useQueryState } from '../../../dist/pages'
   expectType<string | null>(state)
   setState('bar')
   setState(old => old?.toUpperCase() ?? null)
-  const out = await setState('bar')
-  expectType<boolean>(out)
+  const search = await setState('bar')
+  expectType<URLSearchParams>(search)
 }
 
 // Accept only a single `history` option
@@ -17,8 +17,8 @@ import { queryTypes, useQueryState } from '../../../dist/pages'
   expectType<string | null>(state)
   setState('bar')
   setState(old => old?.toUpperCase() ?? null)
-  const out = await setState('bar')
-  expectType<boolean>(out)
+  const search = await setState('bar')
+  expectType<URLSearchParams>(search)
 }
 
 // Supported query types
diff --git a/src/tests/app/useQueryStates.test-d.ts b/src/tests/compat/useQueryStates.test-d.ts
similarity index 95%
rename from src/tests/app/useQueryStates.test-d.ts
rename to src/tests/compat/useQueryStates.test-d.ts
index 8c149fa1..eafc14a5 100644
--- a/src/tests/app/useQueryStates.test-d.ts
+++ b/src/tests/compat/useQueryStates.test-d.ts
@@ -1,5 +1,5 @@
 import { expectError, expectNotAssignable, expectType } from 'tsd'
-import { queryTypes, useQueryStates } from '../../../dist/app'
+import { queryTypes, useQueryStates } from '../../../dist'
 
 {
   const [states, setStates] = useQueryStates(
diff --git a/src/tests/app/useQueryState.test-d.ts b/src/tests/useQueryState.test-d.ts
similarity index 67%
rename from src/tests/app/useQueryState.test-d.ts
rename to src/tests/useQueryState.test-d.ts
index 5f3b033f..36b8de53 100644
--- a/src/tests/app/useQueryState.test-d.ts
+++ b/src/tests/useQueryState.test-d.ts
@@ -1,5 +1,13 @@
 import { expectError, expectNotAssignable, expectType } from 'tsd'
-import { queryTypes, useQueryState } from '../../../dist/app'
+import {
+  parseAsBoolean,
+  parseAsFloat,
+  parseAsInteger,
+  parseAsIsoDateTime,
+  parseAsString,
+  parseAsTimestamp,
+  useQueryState
+} from '../../dist'
 
 // By default, queries have a `string` state, nullable (when no query parameter is present)
 {
@@ -7,6 +15,8 @@ import { queryTypes, useQueryState } from '../../../dist/app'
   expectType<string | null>(state)
   setState('bar')
   setState(old => old?.toUpperCase() ?? null)
+  const search = await setState('bar')
+  expectType<URLSearchParams>(search)
 }
 
 // Accept only a single `history` option
@@ -15,62 +25,61 @@ import { queryTypes, useQueryState } from '../../../dist/app'
   expectType<string | null>(state)
   setState('bar')
   setState(old => old?.toUpperCase() ?? null)
+  const search = await setState('bar')
+  expectType<URLSearchParams>(search)
 }
 
 // Supported query types
 {
-  const [state] = useQueryState('string', queryTypes.string)
+  const [state] = useQueryState('string', parseAsString)
   expectType<string | null>(state)
 }
 {
-  const [state] = useQueryState('integer', queryTypes.integer)
+  const [state] = useQueryState('integer', parseAsInteger)
   expectType<number | null>(state)
 }
 {
-  const [state] = useQueryState('float', queryTypes.float)
+  const [state] = useQueryState('float', parseAsFloat)
   expectType<number | null>(state)
 }
 {
-  const [state] = useQueryState('boolean', queryTypes.boolean)
+  const [state] = useQueryState('boolean', parseAsBoolean)
   expectType<boolean | null>(state)
 }
 {
-  const [state] = useQueryState('boolean', queryTypes.timestamp)
+  const [state] = useQueryState('boolean', parseAsTimestamp)
   expectType<Date | null>(state)
 }
 {
-  const [state] = useQueryState('boolean', queryTypes.isoDateTime)
+  const [state] = useQueryState('boolean', parseAsIsoDateTime)
   expectType<Date | null>(state)
 }
 
 // With default values, state is no longer nullable
 {
-  const [state] = useQueryState('string', queryTypes.string.withDefault('foo'))
+  const [state] = useQueryState('string', parseAsString.withDefault('foo'))
   expectType<string>(state)
   expectNotAssignable<null>(state)
 }
 {
-  const [state] = useQueryState('integer', queryTypes.integer.withDefault(0))
+  const [state] = useQueryState('integer', parseAsInteger.withDefault(0))
   expectType<number>(state)
   expectNotAssignable<null>(state)
 }
 {
-  const [state] = useQueryState('float', queryTypes.float.withDefault(0))
+  const [state] = useQueryState('float', parseAsFloat.withDefault(0))
   expectType<number>(state)
   expectNotAssignable<null>(state)
 }
 {
-  const [state] = useQueryState(
-    'boolean',
-    queryTypes.boolean.withDefault(false)
-  )
+  const [state] = useQueryState('boolean', parseAsBoolean.withDefault(false))
   expectType<boolean>(state)
   expectNotAssignable<null>(state)
 }
 {
   const [state] = useQueryState(
     'boolean',
-    queryTypes.timestamp.withDefault(new Date())
+    parseAsTimestamp.withDefault(new Date())
   )
   expectType<Date>(state)
   expectNotAssignable<null>(state)
@@ -78,7 +87,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 {
   const [state] = useQueryState(
     'boolean',
-    queryTypes.isoDateTime.withDefault(new Date())
+    parseAsIsoDateTime.withDefault(new Date())
   )
   expectType<Date>(state)
   expectNotAssignable<null>(state)
@@ -87,7 +96,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 // Default value can be spread in:
 {
   const [state] = useQueryState('string', {
-    ...queryTypes.string,
+    ...parseAsString,
     defaultValue: 'foo'
   })
   expectType<string>(state)
@@ -95,7 +104,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 }
 {
   const [state] = useQueryState('integer', {
-    ...queryTypes.integer,
+    ...parseAsInteger,
     defaultValue: 0
   })
   expectType<number>(state)
@@ -103,7 +112,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 }
 {
   const [state] = useQueryState('float', {
-    ...queryTypes.float,
+    ...parseAsFloat,
     defaultValue: 0
   })
   expectType<number>(state)
@@ -111,7 +120,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 }
 {
   const [state] = useQueryState('boolean', {
-    ...queryTypes.boolean,
+    ...parseAsBoolean,
     defaultValue: false
   })
   expectType<boolean>(state)
@@ -119,7 +128,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 }
 {
   const [state] = useQueryState('boolean', {
-    ...queryTypes.timestamp,
+    ...parseAsTimestamp,
     defaultValue: new Date()
   })
   expectType<Date>(state)
@@ -127,14 +136,14 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 }
 {
   const [state] = useQueryState('boolean', {
-    ...queryTypes.isoDateTime,
+    ...parseAsIsoDateTime,
     defaultValue: new Date()
   })
   expectType<Date>(state)
   expectNotAssignable<null>(state)
 }
 
-// Custom serializers --
+// Custom parsers --
 {
   const [hex] = useQueryState('foo', {
     parse: input => parseInt(input, 16)
@@ -188,7 +197,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
   })
 }
 {
-  const [, set] = useQueryState('foo', queryTypes.integer)
+  const [, set] = useQueryState('foo', parseAsInteger)
   set(null)
   set(old => {
     expectType<number | null>(old)
@@ -196,7 +205,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
   })
 }
 {
-  const [, set] = useQueryState('foo', queryTypes.float.withDefault(0.2))
+  const [, set] = useQueryState('foo', parseAsFloat.withDefault(0.2))
   set(null)
   set(old => {
     expectType<number>(old) // We know it's not null here
@@ -226,7 +235,39 @@ import { queryTypes, useQueryState } from '../../../dist/app'
   })
 }
 
-// Expect errors on misuse
+// Extend the parser with a builder pattern
+{
+  expectType<number | null>(useQueryState('foo', parseAsInteger)[0])
+  expectType<number | null>(
+    useQueryState('foo', parseAsInteger.withOptions({}))[0]
+  )
+  expectType<number>(useQueryState('foo', parseAsInteger.withDefault(0))[0])
+  expectNotAssignable<null>(
+    useQueryState('foo', parseAsInteger.withDefault(0))[0]
+  )
+  expectType<number>(
+    useQueryState(
+      'foo',
+      parseAsInteger.withOptions({ scroll: true }).withDefault(1)
+    )[0]
+  )
+  expectNotAssignable<null>(
+    useQueryState(
+      'foo',
+      parseAsInteger.withOptions({ scroll: true }).withDefault(1)
+    )[0]
+  )
+
+  expectError(() => {
+    // Can't set withOptions after withDefault
+    useQueryState(
+      'foo',
+      parseAsInteger.withDefault(1).withOptions({ scroll: true })
+    )
+  })
+}
+
+// Expect errors on misuse -----------------------------------------------------
 {
   expectError(() => {
     useQueryState('foo', {
@@ -245,7 +286,7 @@ import { queryTypes, useQueryState } from '../../../dist/app'
 // Set state to undefined
 {
   const [, setFoo] = useQueryState('foo')
-  const [, setBar] = useQueryState('bar', queryTypes.string.withDefault('egg'))
+  const [, setBar] = useQueryState('bar', parseAsString.withDefault('egg'))
   expectError(() => setFoo(undefined))
   expectError(() => setBar(undefined))
   expectError(() => setFoo(() => undefined))
diff --git a/src/tests/pages/useQueryStates.test-d.ts b/src/tests/useQueryStates.test-d.ts
similarity index 78%
rename from src/tests/pages/useQueryStates.test-d.ts
rename to src/tests/useQueryStates.test-d.ts
index 1ea7278e..655bc8ff 100644
--- a/src/tests/pages/useQueryStates.test-d.ts
+++ b/src/tests/useQueryStates.test-d.ts
@@ -1,13 +1,20 @@
 import { expectError, expectNotAssignable, expectType } from 'tsd'
-import { queryTypes, useQueryStates } from '../../lib/index.pages'
+import {
+  parseAsBoolean,
+  parseAsFloat,
+  parseAsInteger,
+  parseAsIsoDateTime,
+  parseAsString,
+  useQueryStates
+} from '../../dist'
 
 {
   const [states, setStates] = useQueryStates(
     {
-      a: queryTypes.string,
-      b: queryTypes.integer,
-      c: queryTypes.float,
-      d: queryTypes.boolean
+      a: parseAsString,
+      b: parseAsInteger,
+      c: parseAsFloat,
+      d: parseAsBoolean
     },
     {
       history: 'push'
@@ -27,15 +34,13 @@ import { queryTypes, useQueryStates } from '../../lib/index.pages'
     ...old,
     d: !old.d
   }))
-  const out = await setStates({ b: 42 })
-  expectType<boolean>(out)
 }
 
 // With default values, state is no longer nullable
 {
   const [states, setStates] = useQueryStates({
-    hasDefault: queryTypes.string.withDefault('foo'),
-    doesNot: queryTypes.isoDateTime
+    hasDefault: parseAsString.withDefault('foo'),
+    doesNot: parseAsIsoDateTime
   })
   expectType<{
     hasDefault: string