@raf-query/react 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,8 +1,18 @@
 # Changelog
 
+## [0.1.8](https://github.com/KATT/raf-query/compare/0.1.7...0.1.8) (2026-10-13)
+
+### Features
+
+* **examples:** infinite scroll, root dev scripts, readable request names; README and tests cover pagination and infinite scroll ([#37](https://github.com/KATT/raf-query/issues/37)) ([2c3bed6](https://github.com/KATT/raf-query/commit/2c3bed630fd08d0a59686a6f5f14aecba1ff2e1b))
+
+## [0.1.7](https://github.com/KATT/raf-query/compare/0.1.6...0.1.7) (2026-10-13)
+
+- validate search params with a zod schema in the README ([#36](https://github.com/KATT/raf-query/issues/36)) ([9142236](https://github.com/KATT/raf-query/commit/9142236f611deb0fdf9db5f7e2847bccad89e841))
+
 ## [0.1.6](https://github.com/KATT/raf-query/compare/0.1.5...0.1.6) (2026-10-12)
 
-* one file per decision, and alternatives in the PR template ([#34](https://github.com/KATT/raf-query/issues/34)) ([e60d30b](https://github.com/KATT/raf-query/commit/e60d30bc99452eec7178fa2a6c7598987fe5254c)), references [#24](https://github.com/KATT/raf-query/issues/24) [#25](https://github.com/KATT/raf-query/issues/25) [#26](https://github.com/KATT/raf-query/issues/26) [#27](https://github.com/KATT/raf-query/issues/27) [#28](https://github.com/KATT/raf-query/issues/28) [#33](https://github.com/KATT/raf-query/issues/33) [#26](https://github.com/KATT/raf-query/issues/26) [#N](https://github.com/KATT/raf-query/issues/N) [#26](https://github.com/KATT/raf-query/issues/26) [#16](https://github.com/KATT/raf-query/issues/16) [#23](https://github.com/KATT/raf-query/issues/23) [#31](https://github.com/KATT/raf-query/issues/31) [#19](https://github.com/KATT/raf-query/issues/19) [#28](https://github.com/KATT/raf-query/issues/28) [#33](https://github.com/KATT/raf-query/issues/33)
+- one file per decision, and alternatives in the PR template ([#34](https://github.com/KATT/raf-query/issues/34)) ([e60d30b](https://github.com/KATT/raf-query/commit/e60d30bc99452eec7178fa2a6c7598987fe5254c)), references [#24](https://github.com/KATT/raf-query/issues/24) [#25](https://github.com/KATT/raf-query/issues/25) [#26](https://github.com/KATT/raf-query/issues/26) [#27](https://github.com/KATT/raf-query/issues/27) [#28](https://github.com/KATT/raf-query/issues/28) [#33](https://github.com/KATT/raf-query/issues/33) [#26](https://github.com/KATT/raf-query/issues/26) [#N](https://github.com/KATT/raf-query/issues/N) [#26](https://github.com/KATT/raf-query/issues/26) [#16](https://github.com/KATT/raf-query/issues/16) [#23](https://github.com/KATT/raf-query/issues/23) [#31](https://github.com/KATT/raf-query/issues/31) [#19](https://github.com/KATT/raf-query/issues/19) [#28](https://github.com/KATT/raf-query/issues/28) [#33](https://github.com/KATT/raf-query/issues/33)
 
 ## [0.1.5](https://github.com/KATT/raf-query/compare/0.1.4...0.1.5) (2026-10-12)
 

package/README.md

@@ -273,18 +273,70 @@ Paging controls: `fetchNextPage()`, `fetchPreviousPage()`, `hasNextPage`, `hasPr
 
 On the server, `ensure` and `fetch` load the first page. Pass `{ pages: n }` as a third argument to load more up front; the option is only accepted for paged factories.
 
+### Infinite scroll
+
+Infinite scroll is the same paged query with an automatic "Load more". A ref callback watches the button and presses it when it nears the viewport. Unmount the button while a page loads: it watches again when it remounts, so it keeps loading while it stays in reach. Its place is taken by skeletons the size of the incoming page, so the loaded rows replace them without moving anything below.
+
+```tsx
+function Comments(props: { handle: QueryHandle<typeof commentsQuery> }) {
+	const [pagesPromise, comments] = useQuery(commentsQuery, props.handle);
+	const data = use(pagesPromise);
+
+	return (
+		<>
+			{data.pages
+				.flatMap((page) => page.items)
+				.map((comment) => (
+					<Comment key={comment.id} {...comment} />
+				))}
+			{comments.isFetchingNextPage ? <CommentSkeletons /> : null}
+			{comments.hasNextPage && !comments.isFetchingNextPage ? (
+				<button
+					onClick={() => comments.fetchNextPage()}
+					ref={(button) => {
+						if (button === null) return;
+						const observer = new IntersectionObserver(
+							(entries) => {
+								if (entries.some((entry) => entry.isIntersecting)) {
+									observer.disconnect();
+									comments.fetchNextPage();
+								}
+							},
+							{ rootMargin: "0px 0px 300px 0px" },
+						);
+						observer.observe(button);
+						return () => observer.disconnect();
+					}}
+				>
+					Load more
+				</button>
+			) : null}
+		</>
+	);
+}
+```
+
+Pagination and infinite scroll differ in where the page lives:
+
+- **Pagination**: the page is a search param and part of the input, so each page is its own query and the URL links to it ([below](#when-the-url-changes)).
+- **Infinite scroll**: filters and sort are search params, and pages are loaded into one paged query per input. Changing a filter starts a new list from its first page.
+
+The [examples](examples/) load their issue list and comments by infinite scroll.
+
 ### When the URL changes
 
 Filters, sort order, and pagination are search params. The loader turns them into the query's input, so every navigation starts the right query and the component only ever reads the handle it was given:
 
 ```tsx
-type PostsSearch = { sort: "newest" | "oldest"; page: number };
+import { z } from "zod";
+
+const PostsSearch = z.object({
+	sort: z.enum(["newest", "oldest"]).default("newest"),
+	page: z.int().positive().default(1),
+});
 
 export const Route = createFileRoute("/posts")({
-	validateSearch: (search): PostsSearch => ({
-		sort: search.sort === "oldest" ? "oldest" : "newest",
-		page: Number(search.page ?? 1),
-	}),
+	validateSearch: PostsSearch,
 	loaderDeps: (args) => args.search,
 	loader: (args) => ({
 		posts: args.context.queryClient.prefetch(postsQuery, args.deps),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -40,7 +40,7 @@
     "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "dependencies": {
-    "@raf-query/core": "0.1.6",
+    "@raf-query/core": "0.1.8",
     "effect": "^4.0.1"
   },
   "peerDependencies": {