Update overview w/ Query-Driven Sync and other features/arguments (#812)

* Enhance overview.md with blog post content and Query-Driven Sync

Updates the overview documentation to better reflect the content and
features from the two DB blog posts (0.1 and 0.5):

- Add compelling "Option C" narrative explaining the architecture
  problem TanStack DB solves (view-specific APIs vs load-everything)

- Document Query-Driven Sync feature from 0.5 release:
  - Three sync modes: eager, on-demand, progressive
  - How component queries automatically become API calls
  - Request optimization (collapsing, delta loading, join batching)

- Add concrete performance numbers: ~0.7ms updates for 100k items
  on M1 Pro, demonstrating truly instantaneous optimistic updates

- Expand sync engine benefits section:
  - Easy real-time updates without WebSocket plumbing
  - Automatic side-effects and cache invalidation
  - Efficient delta updates enabling "load everything once" pattern

These changes bridge the gap between the technical reference docs
and the compelling narrative from the blog posts, helping developers
understand both why TanStack DB exists and how to use it effectively.

* Add end-user benefit emphasis: apps stay fast regardless of data size

Highlights that apps can't get sluggish due to too much data, with
queries over 100k+ rows completing in under a millisecond. This makes
the end-user experience benefit clear early in the documentation.

* Refine introduction with clearer problem-solution framing

Rewrites the introduction to:
- Lead with the problems TanStack DB solves (endpoint sprawl,
  client performance, network on interaction path)
- Emphasize the end-user benefit upfront: interactions feel
  instantaneous, app stays fast regardless of data volume
- Present the "new way" as numbered benefits rather than
  "Option C" framing
- More action-oriented and benefit-focused language

This makes the value proposition clearer and more compelling
for developers evaluating TanStack DB.

* Update README.md to match new overview.md messaging

Aligns README with the refined overview.md framing:
- Changes "client-first" to "client" to match new terminology
- Adopts problem-solution framing (avoid endpoint sprawl,
  optimize client performance, take network off interaction path)
- Emphasizes end-user benefit: app stays fast regardless of data
- More action-oriented and benefit-focused language

Keeps README concise while maintaining consistency with docs.

* Update packages/db/README.md with new messaging

Aligns the core package README with the refined messaging:
- Updates tagline to "The reactive client store for your API"
- Adds "solves the problems of building fast, modern apps"
- Rewrites bullet points to focus on problem-solution framing:
  - Avoid endpoint sprawl (vs building custom endpoints)
  - Blazing fast queries (app stays fast regardless of data)
  - Instant interactions (network off interaction path)
  - Fine-grained reactivity (minimize re-rendering)

Makes the npm package description more benefit-oriented.

---------

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

README.md

@@ -37,14 +37,15 @@
 
 > Tanstack DB is currently in BETA. See [the release post](https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query) for more details.
 
-The reactive client-first store for your API.
+The reactive client store for your API.
 
-Stop building custom endpoints for every view. TanStack DB lets you query your data however your components need it—with a blazing-fast local query engine, real-time reactivity, and instant optimistic updates:
+TanStack DB solves the problems of building fast, modern apps, helping you:
 
-- Sub-millisecond live queries with joins & aggregates
-- Fine-grained reactivity to minimize re-rendering
-- Optimistic mutations with automatic rollback
-- Works with REST, sync engines, or any data source
+- Avoid endpoint sprawl and network waterfalls by loading data into normalized collections
+- Optimise client performance with sub-millisecond live queries and real-time reactivity
+- Take the network off the interaction path with instant optimistic writes
+
+Data loading is optimized. Interactions feel instantaneous. Your backend stays simple and your app stays blazing fast. No matter how much data you load.
 
 <a href="https://tanstack.com/db" style="font-weight:bold" >Read the docs →</a>
 <br />

docs/overview.md

@@ -7,7 +7,28 @@ id: overview
 
 Welcome to the TanStack DB documentation.
 
-TanStack DB is the reactive client-first store for your API. Stop building custom endpoints for every view—TanStack DB lets you query your data however your components need it, with a blazing-fast local query engine, real-time reactivity, and instant optimistic updates.
+TanStack DB is the reactive client store for your API. It solves the problems of building fast, modern apps, helping you:
+
+- avoid endpoint sprawl and network waterfalls by loading data into normalized collections
+- optimise client performance with sub-millisecond live queries and real-time reactivity
+- take the network off the interaction path with instant optimistic writes
+
+Data loading is optimized. Interactions feel instantaneous. Your backend stays simple and your app stays blazing fast. No matter how much data you load.
+
+## Remove the complexity from building fast, modern apps
+
+TanStack DB lets you query your data however your components need it, with a blazing-fast local query engine, real-time reactivity and instant optimistic updates.
+
+Instead of choosing between the least of two evils:
+
+1. **view-specific APIs** - complicating your backend and leading to network waterfalls
+2. **load everything and filter** - leading to slow loads and sluggish client performance
+
+TanStack DB enables a new way:
+
+3. **normalized collections** - keep your backend simple
+4. **query-driven sync** - optimizes your data loading
+5. **sub-millisecond live queries** - keep your app fast and responsive
 
 It extends TanStack Query with collections, live queries and optimistic mutations, working seamlessly with REST APIs, sync engines, or any data source.
 
@@ -71,11 +92,41 @@ Collections can be populated in many ways, including:
 
 Once you have your data in collections, you can query across them using live queries in your components.
 
+#### Sync Modes
+
+Collections support three sync modes to optimize data loading:
+
+- **Eager mode** (default): Loads entire collection upfront. Best for <10k rows of mostly static data like user preferences or small reference tables.
+- **On-demand mode**: Loads only what queries request. Best for large datasets (>50k rows), search interfaces, and catalogs where most data won't be accessed.
+- **Progressive mode**: Loads query subset immediately, syncs full dataset in background. Best for collaborative apps needing instant first paint AND sub-millisecond queries.
+
+With on-demand mode, your component's query becomes the API call:
+
+```tsx
+const productsCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['products'],
+    queryFn: async (ctx) => {
+      // Query predicates passed automatically in ctx.meta
+      const params = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
+      return api.getProducts(params) // e.g., GET /api/products?category=electronics&price_lt=100
+    },
+    syncMode: 'on-demand', // ← Enable query-driven sync
+  })
+)
+```
+
+TanStack DB automatically collapses duplicate requests, performs delta loading when expanding queries, optimizes joins into minimal batched requests, and respects your TanStack Query cache policies. You often end up with _fewer_ network requests than custom view-specific APIs.
+
+See the [Query Collection documentation](../collections/query-collection.md#queryfn-and-predicate-push-down) for full predicate mapping details.
+
 ### Using live queries
 
 Live queries are used to query data out of collections. Live queries are reactive: when the underlying data changes in a way that would affect the query result, the result is incrementally updated and returned from the query, triggering a re-render.
 
-TanStack DB live queries are implemented using [d2ts](https://github.com/electric-sql/d2ts), a Typescript implementation of differential dataflow. This allows the query results to update _incrementally_ (rather than by re-running the whole query). This makes them blazing fast, usually sub-millisecond, even for highly complex queries.
+TanStack DB live queries are implemented using [d2ts](https://github.com/electric-sql/d2ts), a TypeScript implementation of differential dataflow. This allows the query results to update _incrementally_ (rather than by re-running the whole query). This makes them blazing fast, usually sub-millisecond, even for highly complex queries.
+
+**Performance:** Updating one row in a sorted 100,000-item collection completes in ~0.7ms on an M1 Pro MacBook—fast enough that optimistic updates feel truly instantaneous, even with complex queries and large datasets.
 
 Live queries support joins across collections. This allows you to:
 
@@ -412,6 +463,16 @@ This pattern allows you to extend an existing TanStack Query application, or any
 
 One of the most powerful ways of using TanStack DB is with a sync engine, for a fully local-first experience with real-time sync. This allows you to incrementally adopt sync into an existing app, whilst still handling writes with your existing API.
 
+#### Why Sync Engines?
+
+While TanStack DB works great with REST APIs, sync engines provide powerful benefits:
+
+- **Easy real-time updates**: No WebSocket plumbing—write to your database and changes stream automatically to all clients
+- **Automatic side-effects**: When a mutation triggers cascading changes across tables, all affected data syncs automatically without manual cache invalidation
+- **Efficient delta updates**: Only changed rows cross the wire, making it practical to load large datasets client-side
+
+This pattern enables the "load everything once" approach that makes apps like Linear and Figma feel instant.
+
 Here, we illustrate this pattern using [ElectricSQL](https://electric-sql.com) as the sync engine.
 
 ```tsx

packages/db/README.md

@@ -1,8 +1,8 @@
 # @tanstack/db
 
-**A reactive client store for building super fast apps on sync**
+**The reactive client store for your API**
 
-TanStack DB extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
+TanStack DB solves the problems of building fast, modern apps. It extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥
 
 <p>
   <a href="https://x.com/intent/post?text=TanStack%20DB&url=https://tanstack.com/db">
@@ -21,14 +21,14 @@ TanStack DB extends TanStack Query with collections, live queries and optimistic
 
 ## 💥 Visit the [TanStack/db](https://github.com/TanStack/db) repo for docs and details!
 
-- 🔥 **blazing fast query engine**<br />
-  for sub-millisecond live queries &mdash; even for complex queries with joins and aggregates
-- 🎯 **fine-grained reactivity**<br />
-  to minimize component re-rendering
-- 💪 **robust transaction primitives**<br />
-  for easy optimistic mutations with sync and lifecycle support
-- 🌟 **normalized data**<br />
-  to keep your backend simple
+- 🚀 **Avoid endpoint sprawl**<br />
+  Load data into normalized collections instead of building custom endpoints for every view
+- 🔥 **Blazing fast queries**<br />
+  Sub-millisecond live queries with joins & aggregates—your app stays fast no matter how much data you load
+- ⚡ **Instant interactions**<br />
+  Take the network off the interaction path with optimistic writes that feel instantaneous
+- 🎯 **Fine-grained reactivity**<br />
+  Minimize component re-rendering with precise updates
 
 ---