feat: Spy on all query changes

Whether internal or external, and specify the source in the callback
along with the new value.

Add query spy component to all pages for browsers
where changes in the URL are not easily visible (eg: on mobile).

src/app/demos/layout.tsx

@@ -1,4 +1,4 @@
-import { DemoPageLayout } from '../../layouts/demo-page'
+import { DemoPageLayout } from '../../components/demo-page-layout'
 
 export const metadata = {
   title: 'next-usequerystate demos'

src/app/demos/subscribeToQueryUpdates/page.tsx

@@ -14,7 +14,7 @@ export default function BuilderPatternDemoPage() {
   )
 
   React.useEffect(() => {
-    const off = subscribeToQueryUpdates(search =>
+    const off = subscribeToQueryUpdates(({ search }) =>
       console.log(search.toString())
     )
     return off

src/app/e2e/app/layout.tsx

@@ -0,0 +1,14 @@
+import { QuerySpy } from '../../../components/query-spy'
+
+export default function E2EPageLayout({
+  children
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <>
+      <QuerySpy />
+      {children}
+    </>
+  )
+}

src/layouts/demo-page.tsx → src/components/demo-page-layout.tsx

@@ -1,9 +1,11 @@
 import Link from 'next/link'
+import { QuerySpy } from './query-spy'
 
 export function DemoPageLayout({ children }: { children: React.ReactNode }) {
   return (
     <main>
       <Link href="/">⬅️ Home</Link>
+      <QuerySpy />
       {children}
     </main>
   )

src/components/query-spy.tsx

@@ -0,0 +1,49 @@
+'use client'
+
+import { useSearchParams } from 'next/navigation'
+import React from 'react'
+import { subscribeToQueryUpdates } from '../../dist'
+
+export const QuerySpy: React.FC = () => {
+  const initialSearchParams = useSearchParams()
+  const [search, setSearch] = React.useState<URLSearchParams>(() => {
+    if (typeof location !== 'object') {
+      // SSR
+      const out = new URLSearchParams()
+      if (!initialSearchParams) {
+        return out
+      }
+      for (const [key, value] of initialSearchParams) {
+        out.set(key, value)
+      }
+      return out
+    } else {
+      return new URLSearchParams(location.search)
+    }
+  })
+
+  React.useLayoutEffect(
+    () => subscribeToQueryUpdates(({ search }) => setSearch(search)),
+    []
+  )
+  const qs = search.toString()
+
+  return (
+    <pre
+      aria-label="Querystring spy"
+      aria-description="For browsers where the query is hard to see (eg: on mobile)"
+      style={{
+        padding: '4px 6px',
+        border: 'solid 1px gray',
+        borderRadius: '4px',
+        overflow: 'auto'
+      }}
+    >
+      {qs ? (
+        '?' + qs
+      ) : (
+        <span style={{ fontStyle: 'italic' }}>{'<empty query>'}</span>
+      )}
+    </pre>
+  )
+}

src/lib/index.ts

@@ -4,5 +4,6 @@ export type { HistoryOptions, Options } from './defs'
 export * from './deprecated'
 export * from './parsers'
 export { subscribeToQueryUpdates } from './sync'
+export type { QueryUpdateNotificationArgs, QueryUpdateSource } from './sync'
 export * from './useQueryState'
 export * from './useQueryStates'

src/lib/sync.ts

@@ -2,18 +2,24 @@ import Mitt from 'mitt'
 
 export const SYNC_EVENT_KEY = Symbol('__nextUseQueryState__SYNC__')
 export const NOSYNC_MARKER = '__nextUseQueryState__NO_SYNC__'
-export const NOTIFY_EVENT_KEY = Symbol('__nextUseQueryState__NOTIFY__')
+const NOTIFY_EVENT_KEY = Symbol('__nextUseQueryState__NOTIFY__')
+
+export type QueryUpdateSource = 'internal' | 'external'
+export type QueryUpdateNotificationArgs = {
+  search: URLSearchParams
+  source: QueryUpdateSource
+}
 
 type EventMap = {
   [SYNC_EVENT_KEY]: URLSearchParams
-  [NOTIFY_EVENT_KEY]: URLSearchParams
+  [NOTIFY_EVENT_KEY]: QueryUpdateNotificationArgs
   [key: string]: any
 }
 
 export const emitter = Mitt<EventMap>()
 
 export function subscribeToQueryUpdates(
-  callback: (search: URLSearchParams) => void
+  callback: (args: QueryUpdateNotificationArgs) => void
 ) {
   emitter.on(NOTIFY_EVENT_KEY, callback)
   return () => emitter.off(NOTIFY_EVENT_KEY, callback)
@@ -30,17 +36,20 @@ if (!patched && typeof window === 'object') {
       title: string,
       url?: string | URL | null
     ) {
+      if (!url) {
+        // Null URL is only used for state changes,
+        // we're not interested in reacting to those.
+        __DEBUG__ &&
+          console.debug(`history.${method}(null) (${title}) %O`, state)
+        return original(state, title, url)
+      }
+      const source = title === NOSYNC_MARKER ? 'internal' : 'external'
+      const search = new URL(url, location.origin).searchParams
       __DEBUG__ &&
-        console.debug(
-          `history.${method}(${url}) (${
-            title === NOSYNC_MARKER ? 'internal' : 'external'
-          }) %O`,
-          state
-        )
+        console.debug(`history.${method}(${url}) (${source}) %O`, state)
       // If someone else than our hooks have updated the URL,
       // send out a signal for them to sync their internal state.
-      if (title !== NOSYNC_MARKER && url) {
-        const search = new URL(url, location.origin).searchParams
+      if (source === 'external') {
         __DEBUG__ && console.debug(`Triggering sync with ${search.toString()}`)
         // Here we're delaying application to next tick to avoid:
         // `Warning: useInsertionEffect must not schedule updates.`
@@ -52,8 +61,16 @@ if (!patched && typeof window === 'object') {
         // have been applied by then, we're also sending the
         // parsed query string to the hooks so they don't need
         // to rely on the URL being up to date.
-        setTimeout(() => emitter.emit(SYNC_EVENT_KEY, search), 0)
+        setTimeout(() => {
+          emitter.emit(SYNC_EVENT_KEY, search)
+          emitter.emit(NOTIFY_EVENT_KEY, { search, source })
+        }, 0)
+      } else {
+        setTimeout(() => {
+          emitter.emit(NOTIFY_EVENT_KEY, { search, source })
+        }, 0)
       }
+
       return original(state, title === NOSYNC_MARKER ? '' : title, url)
     }
   }

src/lib/update-queue.ts

@@ -1,5 +1,5 @@
 import { Options, Router } from './defs'
-import { NOSYNC_MARKER, NOTIFY_EVENT_KEY, emitter } from './sync'
+import { NOSYNC_MARKER } 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
@@ -131,7 +131,6 @@ function flushUpdateQueue(router: Router) {
         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(

src/pages/demos/pages/server-side-counter.tsx

@@ -1,6 +1,6 @@
 import type { GetServerSideProps, InferGetServerSidePropsType } from 'next'
 import { parseAsInteger, useQueryState } from '../../../../dist'
-import { DemoPageLayout } from '../../../layouts/demo-page'
+import { DemoPageLayout } from '../../../components/demo-page-layout'
 
 export default function ServerSideCounterPage({
   counter: serverSideCounter