v0.0.3: cursor-based paginated collections (paginatedCollectionOptions + useListView)

Author: doeixd

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.3] - 2026-06-03
+
+### Added
+
+- `paginatedCollectionOptions()` for cursor-based paginated TanStack DB collections (`@doeixd/tanstackstart-db/pagination`)
+  - Forward, backward, or bidirectional pagination via `direction`
+  - `loadNextPage()` / `loadPreviousPage()` / `refetchFirstPage()` utilities
+  - Built-in deduplication by `getKey`
+  - `useListView()` React hook with reactive `[items, loadNext, loadPrevious, state]` tuple
+  - `useRefetchPaginated()` for stable refresh callbacks
+  - New subpath export `./pagination` in `package.json`
+- Tests: 9 new integration tests for `paginatedCollectionOptions` (initial sync, loadNext, loadPrevious, dedup, refetch, errors, no-op)
+
 ## [0.0.2] - 2026-06-03
 
 ### Added
@@ -38,5 +51,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - SSR hydration with confirmed-state snapshots
 - Testing utilities: memory DBs, fixtures, mocks, render helpers
 
+[0.0.3]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.3
 [0.0.2]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.2
 [0.0.1]: https://github.com/doeixd/tanstackstart-db/releases/tag/v0.0.1

README.md

@@ -501,6 +501,84 @@ const PostTitle = createDbComponent(db)
   .render(({ post }) => <h2>{post.title}</h2>);
 ```
 
+## Pagination
+
+`@doeixd/tanstackstart-db/pagination` provides cursor-based pagination built on
+top of TanStack DB collections. Define a paginated collection once, then use
+`useListView` to load pages incrementally with automatic cursor tracking and
+reactive re-renders.
+
+```tsx
+import { createCollection } from "@tanstack/db";
+import { paginatedCollectionOptions, useListView } from "@doeixd/tanstackstart-db/pagination";
+
+const CommentView = db.view("comment", { id: true, body: true, createdAt: true });
+
+const comments = createCollection(
+  paginatedCollectionOptions({
+    id: "post-comments",
+    getKey: (c) => c.id,
+    pageSize: 10,
+    cursor: "id",
+    direction: "both",
+    fetchPage: async ({ after, before, limit }) => {
+      const params = new URLSearchParams();
+      if (after !== undefined) params.set("after", String(after));
+      if (before !== undefined) params.set("before", String(before));
+      params.set("limit", String(limit));
+      const response = await fetch(`/api/comments?${params}`);
+      return response.json();
+    },
+  }),
+);
+
+function PostComments() {
+  const [items, loadNext, loadPrevious, state] = useListView({
+    collection: comments,
+    view: CommentView,
+  });
+
+  return (
+    <div>
+      {loadPrevious && (
+        <button onClick={loadPrevious} disabled={state.isLoadingPrevious}>
+          Load older
+        </button>
+      )}
+      {items.map((comment) => (
+        <CommentCard key={comment.id} comment={comment} />
+      ))}
+      {loadNext && (
+        <button onClick={loadNext} disabled={state.isLoadingNext}>
+          Load newer
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+The `useListView` hook returns a tuple of `[items, loadNext, loadPrevious, state]`:
+
+- `items` - all currently loaded items projected through the view, reactively updated
+- `loadNext` - function to load the next page, or `undefined` if no more pages or a load is in flight
+- `loadPrevious` - function to load the previous page (only present for `direction: "backward"` or `"both"`), or `undefined` if at the start or a load is in flight
+- `state` - pagination state including `hasNextPage`, `hasPreviousPage`, `isLoadingNext`, `isLoadingPrevious`, `error`, `totalCount`, `loadedCount`
+
+Items are deduplicated by `getKey`, so calling `loadNextPage` twice with the
+same cursor is safe. Use `useRefetchPaginated(collection)` to get a stable
+refetch callback for refresh buttons (clears all loaded data and re-fetches
+the first page).
+
+The collection exposes all pagination primitives via `collection.utils`:
+
+- `loadNextPage()` - fetch the next page
+- `loadPreviousPage()` - fetch the previous page (undefined for forward-only)
+- `refetchFirstPage()` - clear all data and re-fetch the first page
+- `subscribe(callback)` - subscribe to pagination state changes
+- `getState()` - get the current pagination state snapshot
+- `getCollection()` - get the underlying collection instance
+
 ## DB file routes
 
 The main application-level value of the React entrypoint is its DB file-route

package.json

@@ -1,12 +1,15 @@
 {
   "name": "@doeixd/tanstackstart-db",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Typed schema, view, query, action, route, and hydration helpers for TanStack DB.",
   "keywords": [
     "crud",
+    "cursor",
     "database",
     "hydration",
+    "infinite-scroll",
     "optimistic",
+    "pagination",
     "react",
     "schema",
     "ssr",
@@ -32,6 +35,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./local-storage-collection": "./dist/local-storage-collection.mjs",
+    "./pagination": "./dist/pagination.mjs",
     "./query-collection": "./dist/query-collection.mjs",
     "./react": "./dist/react.mjs",
     "./schema": "./dist/schema.mjs",