Update inline docs + small fixes (#243)

Author: KyleAMathews

.changeset/full-chicken-lick.md

@@ -0,0 +1,8 @@
+---
+"@tanstack/db-collections": patch
+"@tanstack/react-db": patch
+"@tanstack/vue-db": patch
+"@tanstack/db": patch
+---
+
+Improve jsdocs

README.md

@@ -50,7 +50,7 @@ Sync data into collections:
 ```ts
 import { createQueryCollection } from "@tanstack/db-collections"
 
-const todoCollection = createQueryCollection<Todo>({
+const todoCollection = createQueryCollection({
   queryKey: ["todos"],
   queryFn: async () => fetch("/api/todos"),
   getKey: (item) => item.id,
@@ -62,10 +62,13 @@ Use live queries in your components:
 
 ```tsx
 import { useLiveQuery } from "@tanstack/react-db"
+import { eq } from "@tanstack/db"
 
 const Todos = () => {
   const { data: todos } = useLiveQuery((query) =>
-    query.from({ todoCollection }).where("@completed", "=", false)
+    query
+      .from({ todos: todoCollection })
+      .where(({ todos }) => eq(todos.completed, false))
   )
 
   return <List items={todos} />

docs/overview.md

@@ -163,10 +163,12 @@ You can also use:
 
 #### Collection schemas
 
-All collections optionally support a `schema`.
+All collections optionally (though strongly recommended) support adding a `schema`.
 
 If provided, this must be a [Standard Schema](https://standardschema.dev) compatible schema instance, such as a [Zod](https://zod.dev) or [Effect](https://effect.website/docs/schema/introduction/) schema.
 
+The collection will use the schema to do client-side validation of optimistic mutations.
+
 The collection will use the schema for its type so if you provide a schema, you can't also pass in an explicit
 type (e.g. `createCollection<Todo>()`).
 
@@ -639,7 +641,7 @@ import { queryCollectionOptions } from "@tanstack/db-collections"
 
 // Load data into collections using TanStack Query.
 // It's common to define these in a `collections` module.
-const todoCollection = createCollection<Todo>(queryCollectionOptions({
+const todoCollection = createCollection(queryCollectionOptions({
   queryKey: ["todos"],
   queryFn: async () => fetch("/api/todos"),
   getKey: (item) => item.id,
@@ -652,7 +654,7 @@ const todoCollection = createCollection<Todo>(queryCollectionOptions({
   }
   // also add onUpdate, onDelete as needed.
 }))
-const listCollection = createCollection<TodoList>(queryCollectionOptions({
+const listCollection = createCollection(queryCollectionOptions({
   queryKey: ["todo-lists"],
   queryFn: async () => fetch("/api/todo-lists"),
   getKey: (item) => item.id,
@@ -704,7 +706,7 @@ import type { Collection } from '@tanstack/db'
 import type { MutationFn, PendingMutation, createCollection } from '@tanstack/react-db'
 import { electricCollectionOptions } from '@tanstack/db-collections'
 
-export const todoCollection = createCollection(electricCollectionOptions<Todo>({
+export const todoCollection = createCollection(electricCollectionOptions({
   id: 'todos',
   schema: todoSchema,
   // Electric syncs data using "shapes". These are filtered views

examples/react/todo/CHANGELOG.md

@@ -115,7 +115,6 @@
   When `collection.insert()`, `.update()`, or `.delete()` are called outside of an explicit transaction (i.e., not within `useOptimisticMutation`), the library now automatically creates a single-operation transaction and invokes the corresponding handler to persist the change.
 
   Key changes:
-
   - **`@tanstack/db`**: The `Collection` class now supports `onInsert`, `onUpdate`, and `onDelete` in its configuration. Direct calls to mutation methods will throw an error if the corresponding handler is not defined.
   - **`@tanstack/db-collections`**:
     - `queryCollectionOptions` now accepts the new handlers and will automatically `refetch` the collection's query after a handler successfully completes. This behavior can be disabled if the handler returns `{ refetch: false }`.
@@ -127,7 +126,6 @@
   ***
 
   The documentation and the React Todo example application have been significantly refactored to adopt the new direct persistence handler pattern as the primary way to perform mutations.
-
   - The `README.md` and `docs/overview.md` files have been updated to de-emphasize `useOptimisticMutation` for simple writes. They now showcase the much simpler API of calling `collection.insert()` directly and defining persistence logic in the collection's configuration.
   - The React Todo example (`examples/react/todo/src/App.tsx`) has been completely overhauled. All instances of `useOptimisticMutation` have been removed and replaced with the new `onInsert`, `onUpdate`, and `onDelete` handlers, resulting in cleaner and more concise code.
 

examples/react/todo/README.md

@@ -3,7 +3,6 @@
 ## How to run
 
 - Go to the root of the repository and run:
-
   - `pnpm install`
   - `pnpm build`
 

examples/react/todo/package.json

@@ -4,17 +4,16 @@
   "version": "0.0.23",
   "dependencies": {
     "@tanstack/db-collections": "^0.0.21",
-    "@tanstack/query-core": "^5.75.7",
+    "@tanstack/query-core": "^5.81.5",
     "@tanstack/react-db": "^0.0.17",
     "cors": "^2.8.5",
     "drizzle-orm": "^0.40.1",
     "drizzle-zod": "^0.7.0",
     "express": "^4.19.2",
-    "postgres": "^3.4.5",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tailwindcss": "^4.0.17",
-    "zod": "^3.24.2"
+    "postgres": "^3.4.7",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tailwindcss": "^4.1.11"
   },
   "devDependencies": {
     "@eslint/js": "^9.22.0",
@@ -27,8 +26,8 @@
     "@types/react-dom": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",
-    "@vitejs/plugin-react": "^4.3.4",
-    "concurrently": "^9.1.2",
+    "@vitejs/plugin-react": "^4.6.0",
+    "concurrently": "^9.2.0",
     "dotenv": "^16.3.1",
     "drizzle-kit": "^0.30.5",
     "eslint": "^9.22.0",