feat: atomWithQueries

README.md

@@ -9,6 +9,7 @@
 - [Incremental Adoption](#incremental-adoption)
 - [Exported Functions](#exported-functions)
   - [atomWithQuery](#atomwithquery-usage)
+  - [atomWithQueries](#atomwithqueries-usage)
   - [atomWithInfiniteQuery](#atomwithinfinitequery-usage)
   - [atomWithMutation](#atomwithmutation-usage)
   - [atomWithMutationState](#atomwithmutationstate-usage)
@@ -56,6 +57,7 @@ You can incrementally adopt `jotai-tanstack-query` in your app. It's not an all
 ### Exported functions
 
 - `atomWithQuery` for [useQuery](https://tanstack.com/query/v5/docs/react/reference/useQuery)
+- `atomWithQueries` for [useQueries](https://tanstack.com/query/v5/docs/react/reference/useQueries)
 - `atomWithInfiniteQuery` for [useInfiniteQuery](https://tanstack.com/query/v5/docs/react/reference/useInfiniteQuery)
 - `atomWithMutation` for [useMutation](https://tanstack.com/query/v5/docs/react/reference/useMutation)
 - `atomWithSuspenseQuery` for [useSuspenseQuery](https://tanstack.com/query/v5/docs/react/reference/useSuspenseQuery)
@@ -98,6 +100,103 @@ const UserData = () => {
 }
 ```
 
+### atomWithQueries usage
+
+`atomWithQueries` creates a new atom that implements parallel queries from TanStack Query. It allows you to run multiple queries concurrently and optionally combine their results.
+
+There are two ways to use `atomWithQueries`:
+
+#### Basic usage - Returns an array of query atoms
+
+```jsx
+import { atom, useAtom } from 'jotai'
+import { atomWithQueries } from 'jotai-tanstack-query'
+
+const userIdsAtom = atom([1, 2, 3])
+
+const UsersData = () => {
+  const [userIds] = useAtom(userIdsAtom)
+
+  const userQueryAtoms = atomWithQueries({
+    queries: userIds.map((id) => () => ({
+      queryKey: ['user', id],
+      queryFn: async ({ queryKey: [, userId] }) => {
+        const res = await fetch(
+          `https://jsonplaceholder.typicode.com/users/${userId}`
+        )
+        return res.json()
+      },
+    })),
+  })
+
+  return (
+    <div>
+      {userQueryAtoms.map((queryAtom, index) => (
+        <UserData key={index} queryAtom={queryAtom} />
+      ))}
+    </div>
+  )
+}
+
+const UserData = ({ queryAtom }) => {
+  const [{ data, isPending, isError }] = useAtom(queryAtom)
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error</div>
+
+  return (
+    <div>
+      {data.name} - {data.email}
+    </div>
+  )
+}
+```
+
+#### Advanced usage - Combine multiple query results
+
+```jsx
+import { atom, useAtom } from 'jotai'
+import { atomWithQueries } from 'jotai-tanstack-query'
+
+const userIdsAtom = atom([1, 2, 3])
+
+const CombinedUsersData = () => {
+  const [userIds] = useAtom(userIdsAtom)
+
+  const combinedUsersDataAtom = atomWithQueries({
+    queries: userIds.map((id) => () => ({
+      queryKey: ['user', id],
+      queryFn: async ({ queryKey: [, userId] }) => {
+        const res = await fetch(
+          `https://jsonplaceholder.typicode.com/users/${userId}`
+        )
+        return res.json()
+      },
+    })),
+    combine: (results) => ({
+      data: results.map((result) => result.data),
+      isPending: results.some((result) => result.isPending),
+      isError: results.some((result) => result.isError),
+    }),
+  })
+
+  const [{ data, isPending, isError }] = useAtom(combinedUsersDataAtom)
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error</div>
+
+  return (
+    <div>
+      {data.map((user) => (
+        <div key={user.id}>
+          {user.name} - {user.email}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
 ### atomWithInfiniteQuery usage
 
 `atomWithInfiniteQuery` is very similar to `atomWithQuery`, however it is for an `InfiniteQuery`, which is used for data that is meant to be paginated. You can [read more about Infinite Queries here](https://tanstack.com/query/v5/docs/guides/infinite-queries).

examples/01_typescript/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@tanstack/query-core": "latest",
     "jotai": "latest",
-    "jotai-tanstack-query": "latest",
+    "jotai-tanstack-query": "../../",
     "react": "latest",
     "react-dom": "latest"
   },

examples/02_typescript_suspense/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@tanstack/query-core": "latest",
     "jotai": "latest",
-    "jotai-tanstack-query": "latest",
+    "jotai-tanstack-query": "../../",
     "react": "latest",
     "react-dom": "latest"
   },

examples/03_infinite/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@tanstack/query-core": "latest",
     "jotai": "latest",
-    "jotai-tanstack-query": "latest",
+    "jotai-tanstack-query": "../../",
     "react": "latest",
     "react-dom": "latest"
   },

examples/04_infinite_suspense/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@tanstack/query-core": "latest",
     "jotai": "latest",
-    "jotai-tanstack-query": "latest",
+    "jotai-tanstack-query": "../../",
     "react": "latest",
     "react-dom": "latest"
   },

examples/05_mutation/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@tanstack/query-core": "latest",
     "jotai": "latest",
-    "jotai-tanstack-query": "latest",
+    "jotai-tanstack-query": "../../",
     "react": "latest",
     "react-dom": "latest"
   },

examples/06_refetch/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@tanstack/query-core": "latest",
     "jotai": "latest",
-    "jotai-tanstack-query": "latest",
+    "jotai-tanstack-query": "../../",
     "react": "latest",
     "react-dom": "latest"
   },

examples/07_queries/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>jotai-tanstack-query example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

examples/07_queries/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "jotai-tanstack-query-example",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {
+    "@tanstack/query-core": "latest",
+    "jotai": "latest",
+    "jotai-tanstack-query": "../../",
+    "react": "latest",
+    "react-dom": "latest"
+  },
+  "devDependencies": {
+    "@types/react": "latest",
+    "@types/react-dom": "latest",
+    "@vitejs/plugin-react": "latest",
+    "typescript": "latest",
+    "vite": "latest"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}

examples/07_queries/src/App.tsx

@@ -0,0 +1,150 @@
+import React from 'react'
+import { Atom, atom } from 'jotai'
+import { useAtom } from 'jotai/react'
+import { type AtomWithQueryResult, atomWithQueries } from 'jotai-tanstack-query'
+
+const userIdsAtom = atom([1, 2, 3])
+
+interface User {
+  id: number
+  name: string
+  email: string
+}
+
+const UsersData = () => {
+  const [userIds] = useAtom(userIdsAtom)
+
+  const userQueryAtoms = atomWithQueries<User>({
+    queries: userIds.map((id) => () => ({
+      queryKey: ['user', id],
+      queryFn: async ({ queryKey: [, userId] }) => {
+        const res = await fetch(
+          `https://jsonplaceholder.typicode.com/users/${userId}`
+        )
+        return res.json()
+      },
+    })),
+  })
+  return (
+    <div>
+      <h3>Users: </h3>
+      <div>
+        {userQueryAtoms.map((queryAtom, index) => (
+          <Data key={index} queryAtom={queryAtom} />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+const CombinedUsersData = () => {
+  const [userIds] = useAtom(userIdsAtom)
+
+  const combinedUsersDataAtom = atomWithQueries<{
+    data: User[]
+    isPending: boolean
+    isError: boolean
+  }>({
+    queries: userIds.map((id) => () => ({
+      queryKey: ['user', id],
+      queryFn: async ({ queryKey: [, userId] }) => {
+        const res = await fetch(
+          `https://jsonplaceholder.typicode.com/users/${userId}`
+        )
+        return res.json()
+      },
+    })),
+    combine: (results) => {
+      return {
+        data: results.map((result) => result.data as User),
+        isPending: results.some((result) => result.isPending),
+        isError: results.some((result) => result.isError),
+      }
+    },
+  })
+
+  return (
+    <div>
+      <h3>Users: (combinedQueries)</h3>
+      <div>
+        <CombinedData queryAtom={combinedUsersDataAtom} />
+      </div>
+    </div>
+  )
+}
+
+const CombinedData = ({
+  queryAtom,
+}: {
+  queryAtom: Atom<{
+    data: User[]
+    isPending: boolean
+    isError: boolean
+  }>
+}) => {
+  const [{ data, isPending, isError }] = useAtom(queryAtom)
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error</div>
+
+  return (
+    <div>
+      {data.map((user) => (
+        <UserDisplay key={user.id} user={user} />
+      ))}
+    </div>
+  )
+}
+
+const Data = ({
+  queryAtom,
+}: {
+  queryAtom: Atom<AtomWithQueryResult<User>>
+}) => {
+  const [{ data, isPending, isError }] = useAtom(queryAtom)
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error</div>
+
+  return <UserDisplay user={data} />
+}
+
+const UserDisplay = ({ user }: { user: User }) => {
+  return (
+    <div>
+      <div>ID: {user.id}</div>
+      <strong>{user.name}</strong> - {user.email}
+    </div>
+  )
+}
+
+const Controls = () => {
+  const [userIds, setUserIds] = useAtom(userIdsAtom)
+
+  return (
+    <div>
+      <div>User IDs: {userIds.join(', ')} </div>
+      <button
+        onClick={() =>
+          setUserIds(
+            Array.from({ length: 3 }, () => Math.floor(Math.random() * 10) + 1)
+          )
+        }>
+        Random
+      </button>
+    </div>
+  )
+}
+
+const App = () => {
+  return (
+    <div>
+      <Controls />
+      <UsersData />
+      <hr />
+      <CombinedUsersData />
+    </div>
+  )
+}
+
+export default App

examples/07_queries/src/index.tsx

@@ -0,0 +1,8 @@
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+const ele = document.getElementById('app')
+if (ele) {
+  createRoot(ele).render(React.createElement(App))
+}

examples/07_queries/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}