feat: react-query-next-experimental package

packages/react-query-devtools/vitest.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
-    name: 'react-query-persist-client',
+    name: 'react-query-devtools',
     dir: './src',
     watch: false,
     setupFiles: ['test-setup.ts'],

packages/react-query-next-experimental/.eslintrc.cjs

@@ -0,0 +1,16 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {
+  extends: ['plugin:react/recommended', 'plugin:react-hooks/recommended'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: './tsconfig.eslint.json',
+  },
+  rules: {
+    'react/jsx-key': ['error', { checkFragmentShorthand: true }],
+    'react-hooks/exhaustive-deps': 'error',
+  },
+}
+
+module.exports = config

packages/react-query-next-experimental/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tanstack/react-query-next-experimental",
+  "version": "5.0.0-alpha.67",
+  "description": "Hydration utils for React Query in the NextJs app directory",
+  "author": "tannerlinsley",
+  "license": "MIT",
+  "repository": "tanstack/query",
+  "homepage": "https://tanstack.com/query",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "types": "build/lib/index.d.ts",
+  "main": "build/lib/index.legacy.cjs",
+  "module": "build/lib/index.legacy.js",
+  "exports": {
+    ".": {
+      "types": "./build/lib/index.d.ts",
+      "import": "./build/lib/index.js",
+      "require": "./build/lib/index.cjs",
+      "default": "./build/lib/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "build/lib/*",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rimraf ./build && rimraf ./coverage",
+    "test:eslint": "eslint --ext .ts,.tsx ./src",
+    "test:types": "tsc --noEmit",
+    "test:lib": "vitest run --coverage --passWithNoTests",
+    "test:lib:dev": "pnpm run test:lib --watch",
+    "test:build": "publint --strict",
+    "build": "pnpm build:rollup && pnpm build:types",
+    "build:rollup": "rollup --config rollup.config.js",
+    "build:types": "tsc --emitDeclarationOnly"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "workspace:*",
+    "@types/react": "^18.2.4",
+    "@types/react-dom": "^18.2.4",
+    "next": "^13.4.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-error-boundary": "^3.1.4"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "workspace:*",
+    "next": "^13.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}

packages/react-query-next-experimental/rollup.config.js

@@ -0,0 +1,12 @@
+// @ts-check
+
+import { defineConfig } from 'rollup'
+import { buildConfigs } from '../../scripts/getRollupConfig.js'
+
+export default defineConfig(
+  buildConfigs({
+    name: 'react-query-next-experimental',
+    outputFile: 'index',
+    entryFile: './src/index.ts',
+  }),
+)

packages/react-query-next-experimental/src/HydrationStreamProvider.tsx

@@ -0,0 +1,194 @@
+'use client'
+
+import { useServerInsertedHTML } from 'next/navigation'
+import * as React from 'react'
+
+const serializedSymbol = Symbol('serialized')
+
+interface DataTransformer {
+  serialize(object: any): any
+  deserialize(object: any): any
+}
+
+type Serialized<TData> = unknown & {
+  [serializedSymbol]: TData
+}
+
+interface TypedDataTransformer<TData> {
+  serialize: (obj: TData) => Serialized<TData>
+  deserialize: (obj: Serialized<TData>) => TData
+}
+
+interface HydrationStreamContext<TShape> {
+  id: string
+  stream: {
+    /**
+     * **Server method**
+     * Push a new entry to the stream
+     * Will be ignored on the client
+     */
+    push: (...shape: TShape[]) => void
+  }
+}
+
+export interface HydrationStreamProviderProps<TShape> {
+  children: React.ReactNode
+  /**
+   * Optional transformer to serialize/deserialize the data
+   * Example devalue, superjson et al
+   */
+  transformer?: DataTransformer
+  /**
+   * **Client method**
+   * Called in the browser when new entries are received
+   */
+  onEntries: (entries: TShape[]) => void
+  /**
+   * **Server method**
+   * onFlush is called on the server when the cache is flushed
+   */
+  onFlush?: () => TShape[]
+}
+
+export function createHydrationStreamProvider<TShape>() {
+  const context = React.createContext<HydrationStreamContext<TShape>>(
+    null as any,
+  )
+  /**
+
+   * 1. (Happens on server): `useServerInsertedHTML()` is called **on the server** whenever a `Suspense`-boundary completes
+   *    - This means that we might have some new entries in the cache that needs to be flushed
+   *    - We pass these to the client by inserting a `<script>`-tag where we do `window[id].push(serializedVersionOfCache)`
+   * 2. (Happens in browser) In `useEffect()`:
+   *   - We check if `window[id]` is set to an array and call `push()` on all the entries which will call `onEntries()` with the new entries
+   *   - We replace `window[id]` with a `push()`-method that will be called whenever new entries are received
+   **/
+  function UseClientHydrationStreamProvider(props: {
+    children: React.ReactNode
+    /**
+     * Optional transformer to serialize/deserialize the data
+     * Example devalue, superjson et al
+     */
+    transformer?: DataTransformer
+    /**
+     * **Client method**
+     * Called in the browser when new entries are received
+     */
+    onEntries: (entries: TShape[]) => void
+    /**
+     * **Server method**
+     * onFlush is called on the server when the cache is flushed
+     */
+    onFlush?: () => TShape[]
+  }) {
+    // unique id for the cache provider
+    const id = `_${React.useId()}`
+    const idJSON = JSON.stringify(id)
+
+    const [transformer] = React.useState(
+      () =>
+        (props.transformer ?? {
+          // noop
+          serialize: (obj: any) => obj,
+          deserialize: (obj: any) => obj,
+        }) as unknown as TypedDataTransformer<TShape>,
+    )
+
+    // <server stuff>
+    const [stream] = React.useState<TShape[]>(() => {
+      if (typeof window !== 'undefined') {
+        return {
+          push() {
+            // no-op on the client
+          },
+        } as unknown as TShape[]
+      }
+      return []
+    })
+    const count = React.useRef(0)
+    const onDehydrateRef = React.useRef(props.onFlush)
+    onDehydrateRef.current = props.onFlush
+    useServerInsertedHTML(() => {
+      // This only happens on the server
+      stream.push(...(onDehydrateRef.current?.() ?? []))
+
+      if (!stream.length) {
+        return null
+      }
+      // console.log(`pushing ${stream.length} entries`)
+      const serializedCacheArgs = stream
+        .map((entry) => transformer.serialize(entry))
+        .map((entry) => JSON.stringify(entry))
+        .join(',')
+
+      // Flush stream
+      stream.length = 0
+
+      const html: string[] = [
+        `window[${idJSON}] = window[${idJSON}] || [];`,
+        `window[${idJSON}].push(${serializedCacheArgs});`,
+      ]
+      return (
+        <script
+          key={count.current++}
+          dangerouslySetInnerHTML={{
+            __html: html.join(''),
+          }}
+        />
+      )
+    })
+    // </server stuff>
+
+    // <client stuff>
+    const onEntriesRef = React.useRef(props.onEntries)
+    onEntriesRef.current = props.onEntries
+
+    // Client: consume cache:
+    const onEntries = React.useCallback(
+      (...serializedEntries: Serialized<TShape>[]) => {
+        const entries = serializedEntries.map((serialized) =>
+          transformer.deserialize(serialized),
+        )
+        onEntriesRef.current(entries)
+      },
+      [transformer],
+    )
+
+    React.useEffect(() => {
+      const win = window as any
+      // Register cache consumer
+      const stream: Array<Serialized<TShape>> = win[id] ?? []
+
+      if (!Array.isArray(stream)) {
+        throw new Error(`${id} seem to have been registered twice`)
+      }
+      onEntries(...stream)
+
+      // Register our own consumer
+      win[id] = {
+        push: onEntries,
+      }
+
+      return () => {
+        // Cleanup after unmount
+        win[id] = {
+          push() {
+            // no-op
+          },
+        }
+      }
+    }, [id, onEntries])
+    // </client stuff>
+
+    return (
+      <context.Provider value={{ stream, id }}>
+        {props.children}
+      </context.Provider>
+    )
+  }
+
+  return {
+    Provider: UseClientHydrationStreamProvider,
+    context,
+  }
+}

packages/react-query-next-experimental/src/ReactQueryStreamedHydration.tsx

@@ -0,0 +1,89 @@
+'use client'
+
+import type { ContextOptions, DehydratedState } from '@tanstack/react-query'
+import { dehydrate, hydrate, useQueryClient } from '@tanstack/react-query'
+import * as React from 'react'
+import type { HydrationStreamProviderProps } from './HydrationStreamProvider'
+import { createHydrationStreamProvider } from './HydrationStreamProvider'
+
+const stream = createHydrationStreamProvider<DehydratedState>()
+
+/**
+ * This component is responsible for:
+ * - hydrating the query client on the server
+ * - dehydrating the query client on the server
+ */
+export function ReactQueryStreamedHydration(props: {
+  children: React.ReactNode
+  context?: ContextOptions['context']
+  transformer?: HydrationStreamProviderProps<DehydratedState>['transformer']
+}) {
+  const queryClient = useQueryClient({
+    context: props.context,
+  })
+
+  // <server only>
+  const isSubscribed = React.useRef(false)
+  /**
+   * We need to track which queries were added/updated during the render
+   */
+  const [trackedKeys] = React.useState(() => new Set<string>())
+  /**
+   * Track which queries were already passed to the client so we don't pass them again
+   */
+  // const [passedKeys] = useState(() => new Set<string>());
+
+  const cache = queryClient.getQueryCache()
+
+  if (typeof window === 'undefined' && !isSubscribed.current) {
+    // Do we need to care about unsubscribing? I don't think so to be honest
+    cache.subscribe((event) => {
+      switch (event.type) {
+        case 'added':
+        case 'updated':
+          // console.log('tracking', event.query.queryHash, 'b/c of a', event.type)
+          trackedKeys.add(event.query.queryHash)
+      }
+    })
+  }
+  // </server only>
+
+  return (
+    <stream.Provider
+      // Happens on server:
+      onFlush={() => {
+        /**
+         * Dehydrated state of the client where we only include the queries that were added/updated since the last flush
+         */
+        const dehydratedState = dehydrate(queryClient, {
+          shouldDehydrateQuery(query) {
+            const shouldDehydrate =
+              trackedKeys.has(query.queryHash) &&
+              // !passedKeys.has(query.queryHash) &&
+              query.state.status !== 'loading'
+
+            // passedKeys.add(query.queryHash);
+            return shouldDehydrate
+          },
+        })
+        trackedKeys.clear()
+
+        if (!dehydratedState.queries.length) {
+          return []
+        }
+
+        return [dehydratedState]
+      }}
+      // Happens in browser:
+      onEntries={(entries) => {
+        for (const hydratedState of entries) {
+          hydrate(queryClient, hydratedState)
+        }
+      }}
+      // Handle BigInts etc using superjson
+      transformer={props.transformer}
+    >
+      {props.children}
+    </stream.Provider>
+  )
+}

packages/react-query-next-experimental/src/index.ts

@@ -0,0 +1 @@
+export { ReactQueryStreamedHydration } from './ReactQueryStreamedHydration'

packages/react-query-next-experimental/test-setup.ts

@@ -0,0 +1,7 @@
+import { act } from '@testing-library/react'
+import { notifyManager } from '@tanstack/react-query'
+
+// Wrap notifications with act to make sure React knows about React Query updates
+notifyManager.setNotifyFunction((fn) => {
+  act(fn)
+})

packages/react-query-next-experimental/tsconfig.eslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".eslintrc.cjs", "rollup.config.js"]
+}