Query Driven Sync with On-Demand Collection Loading

.changeset/all-meals-follow.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add optional compareOptions to collection configuration.

.changeset/legal-cooks-sink.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db-ivm": patch
+---
+
+Fix bug with setWindow on ordered queries that have no limit.

.changeset/light-phones-flash.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add predicate comparison and merging utilities (isWhereSubset, intersectWherePredicates, unionWherePredicates, and related functions) to support predicate push-down in collection sync operations, enabling efficient tracking of loaded data ranges and preventing redundant server requests. Includes performance optimizations for large primitive IN predicates and full support for Date objects in equality, range, and IN clause comparisons.

.changeset/open-cups-lose.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add support for orderBy and limit in currentStateAsChanges function

.changeset/silent-trains-tell.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/query-db-collection": patch
+---
+
+Handle pushed-down predicates

.changeset/tender-carpets-cheat.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/electric-db-collection": patch
+---
+
+Handle predicates that are pushed down.

.changeset/two-lamps-wave.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Adds an onDeduplicate callback on the DeduplicatedLoadSubset class which is called when a loadSubset call is deduplicated

docs/reference/classes/DeduplicatedLoadSubset.md

@@ -0,0 +1,120 @@
+---
+id: DeduplicatedLoadSubset
+title: DeduplicatedLoadSubset
+---
+
+# Class: DeduplicatedLoadSubset
+
+Defined in: [packages/db/src/query/subset-dedupe.ts:34](https://github.com/TanStack/db/blob/main/packages/db/src/query/subset-dedupe.ts#L34)
+
+Deduplicated wrapper for a loadSubset function.
+Tracks what data has been loaded and avoids redundant calls by applying
+subset logic to predicates.
+
+## Param
+
+The options for the DeduplicatedLoadSubset
+
+## Param
+
+The underlying loadSubset function to wrap
+
+## Param
+
+An optional callback function that is invoked when a loadSubset call is deduplicated.
+                             If the call is deduplicated because the requested data is being loaded by an inflight request,
+                             then this callback is invoked when the inflight request completes successfully and the data is fully loaded.
+                             This callback is useful if you need to track rows per query, in which case you can't ignore deduplicated calls
+                             because you need to know which rows were loaded for each query.
+
+## Example
+
+```ts
+const dedupe = new DeduplicatedLoadSubset({ loadSubset: myLoadSubset, onDeduplicate: (opts) => console.log(`Call was deduplicated:`, opts) })
+
+// First call - fetches data
+await dedupe.loadSubset({ where: gt(ref('age'), val(10)) })
+
+// Second call - subset of first, returns true immediately
+await dedupe.loadSubset({ where: gt(ref('age'), val(20)) })
+
+// Clear state to start fresh
+dedupe.reset()
+```
+
+## Constructors
+
+### Constructor
+
+```ts
+new DeduplicatedLoadSubset(opts): DeduplicatedLoadSubset;
+```
+
+Defined in: [packages/db/src/query/subset-dedupe.ts:67](https://github.com/TanStack/db/blob/main/packages/db/src/query/subset-dedupe.ts#L67)
+
+#### Parameters
+
+##### opts
+
+###### loadSubset
+
+(`options`) => `true` \| `Promise`\<`void`\>
+
+###### onDeduplicate?
+
+(`options`) => `void`
+
+#### Returns
+
+`DeduplicatedLoadSubset`
+
+## Methods
+
+### loadSubset()
+
+```ts
+loadSubset(options): true | Promise<void>;
+```
+
+Defined in: [packages/db/src/query/subset-dedupe.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/query/subset-dedupe.ts#L85)
+
+Load a subset of data, with automatic deduplication based on previously
+loaded predicates and in-flight requests.
+
+This method is auto-bound, so it can be safely passed as a callback without
+losing its `this` context (e.g., `loadSubset: dedupe.loadSubset` in a sync config).
+
+#### Parameters
+
+##### options
+
+[`LoadSubsetOptions`](../../type-aliases/LoadSubsetOptions.md)
+
+The predicate options (where, orderBy, limit)
+
+#### Returns
+
+`true` \| `Promise`\<`void`\>
+
+true if data is already loaded, or a Promise that resolves when data is loaded
+
+***
+
+### reset()
+
+```ts
+reset(): void;
+```
+
+Defined in: [packages/db/src/query/subset-dedupe.ts:198](https://github.com/TanStack/db/blob/main/packages/db/src/query/subset-dedupe.ts#L198)
+
+Reset all tracking state.
+Clears the history of loaded predicates and in-flight calls.
+Use this when you want to start fresh, for example after clearing the underlying data store.
+
+Note: Any in-flight requests will still complete, but they will not update the tracking
+state after the reset. This prevents old requests from repopulating cleared state.
+
+#### Returns
+
+`void`

docs/reference/electric-db-collection/functions/electricCollectionOptions.md

@@ -11,7 +11,7 @@ title: electricCollectionOptions
 function electricCollectionOptions<T>(config): CollectionConfig<InferSchemaOutput<T>, string | number, T, UtilsRecord> & object;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:254](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L254)
+Defined in: [packages/electric-db-collection/src/electric.ts:277](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L277)
 
 Creates Electric collection options for use with a standard Collection
 
@@ -43,7 +43,7 @@ Collection options with utilities
 function electricCollectionOptions<T>(config): CollectionConfig<T, string | number, never, UtilsRecord> & object;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:265](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L265)
+Defined in: [packages/electric-db-collection/src/electric.ts:288](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L288)
 
 Creates Electric collection options for use with a standard Collection
 

docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md

@@ -5,13 +5,13 @@ title: ElectricCollectionConfig
 
 # Interface: ElectricCollectionConfig\<T, TSchema\>
 
-Defined in: [packages/electric-db-collection/src/electric.ts:80](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L80)
+Defined in: [packages/electric-db-collection/src/electric.ts:102](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L102)
 
 Configuration interface for Electric collection options
 
 ## Extends
 
-- `Omit`\<`BaseCollectionConfig`\<`T`, `string` \| `number`, `TSchema`, `UtilsRecord`, `any`\>, `"onInsert"` \| `"onUpdate"` \| `"onDelete"`\>
+- `Omit`\<`BaseCollectionConfig`\<`T`, `string` \| `number`, `TSchema`, `UtilsRecord`, `any`\>, `"onInsert"` \| `"onUpdate"` \| `"onDelete"` \| `"syncMode"`\>
 
 ## Type Parameters
 
@@ -35,7 +35,7 @@ The schema type for validation
 optional onDelete: (params) => Promise<MatchingStrategy>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:185](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L185)
+Defined in: [packages/electric-db-collection/src/electric.ts:208](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L208)
 
 Optional asynchronous handler function called before a delete operation
 
@@ -87,7 +87,7 @@ onDelete: async ({ transaction, collection }) => {
 optional onInsert: (params) => Promise<MatchingStrategy>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:128](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L128)
+Defined in: [packages/electric-db-collection/src/electric.ts:151](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L151)
 
 Optional asynchronous handler function called before an insert operation
 
@@ -150,7 +150,7 @@ onInsert: async ({ transaction, collection }) => {
 optional onUpdate: (params) => Promise<MatchingStrategy>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:157](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L157)
+Defined in: [packages/electric-db-collection/src/electric.ts:180](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L180)
 
 Optional asynchronous handler function called before an update operation
 
@@ -203,6 +203,16 @@ onUpdate: async ({ transaction, collection }) => {
 shapeOptions: ShapeStreamOptions<GetExtensions<T>>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:90](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L90)
+Defined in: [packages/electric-db-collection/src/electric.ts:112](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L112)
 
 Configuration options for the ElectricSQL ShapeStream
+
+***
+
+### syncMode?
+
+```ts
+optional syncMode: ElectricSyncMode;
+```
+
+Defined in: [packages/electric-db-collection/src/electric.ts:113](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L113)

docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md

@@ -5,7 +5,7 @@ title: ElectricCollectionUtils
 
 # Interface: ElectricCollectionUtils\<T\>
 
-Defined in: [packages/electric-db-collection/src/electric.ts:237](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L237)
+Defined in: [packages/electric-db-collection/src/electric.ts:260](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L260)
 
 Electric collection utilities type
 
@@ -33,7 +33,7 @@ Electric collection utilities type
 awaitMatch: AwaitMatchFn<T>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:240](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L240)
+Defined in: [packages/electric-db-collection/src/electric.ts:263](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L263)
 
 ***
 
@@ -43,4 +43,4 @@ Defined in: [packages/electric-db-collection/src/electric.ts:240](https://github
 awaitTxId: AwaitTxIdFn;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:239](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L239)
+Defined in: [packages/electric-db-collection/src/electric.ts:262](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L262)

docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md

@@ -9,7 +9,7 @@ title: AwaitTxIdFn
 type AwaitTxIdFn = (txId, timeout?) => Promise<boolean>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:224](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L224)
+Defined in: [packages/electric-db-collection/src/electric.ts:247](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L247)
 
 Type for the awaitTxId utility function
 

docs/reference/electric-db-collection/type-aliases/Txid.md

@@ -9,6 +9,6 @@ title: Txid
 type Txid = number;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:42](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L42)
+Defined in: [packages/electric-db-collection/src/electric.ts:46](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L46)
 
 Type representing a transaction ID in ElectricSQL

docs/reference/functions/createCollection.md

@@ -11,7 +11,7 @@ title: createCollection
 function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & NonSingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:130](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L130)
+Defined in: [packages/db/src/collection/index.ts:131](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L131)
 
 Creates a new Collection instance with the given configuration
 
@@ -120,7 +120,7 @@ const todos = createCollection({
 function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & SingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:143](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L143)
+Defined in: [packages/db/src/collection/index.ts:144](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L144)
 
 Creates a new Collection instance with the given configuration
 
@@ -229,7 +229,7 @@ const todos = createCollection({
 function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & NonSingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:157](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L157)
+Defined in: [packages/db/src/collection/index.ts:158](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L158)
 
 Creates a new Collection instance with the given configuration
 
@@ -338,7 +338,7 @@ const todos = createCollection({
 function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & SingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:170](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L170)
+Defined in: [packages/db/src/collection/index.ts:171](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L171)
 
 Creates a new Collection instance with the given configuration
 

docs/reference/functions/isLimitSubset.md

@@ -0,0 +1,43 @@
+---
+id: isLimitSubset
+title: isLimitSubset
+---
+
+# Function: isLimitSubset()
+
+```ts
+function isLimitSubset(subset, superset): boolean;
+```
+
+Defined in: [packages/db/src/query/predicate-utils.ts:768](https://github.com/TanStack/db/blob/main/packages/db/src/query/predicate-utils.ts#L768)
+
+Check if one limit is a subset of another.
+Returns true if the subset limit requirements are satisfied by the superset limit.
+
+## Parameters
+
+### subset
+
+The limit requirement to check
+
+`number` | `undefined`
+
+### superset
+
+The limit that might satisfy the requirement
+
+`number` | `undefined`
+
+## Returns
+
+`boolean`
+
+true if subset is satisfied by superset
+
+## Example
+
+```ts
+isLimitSubset(10, 20) // true (requesting 10 items when 20 are available)
+isLimitSubset(20, 10) // false (requesting 20 items when only 10 are available)
+isLimitSubset(10, undefined) // true (requesting 10 items when unlimited are available)
+```