@tanstack/db 0.5.24 → 0.5.25

package/src/indexes/btree-index.ts

@@ -1,6 +1,10 @@
 import { compareKeys } from '@tanstack/db-ivm'
 import { BTree } from '../utils/btree.js'
-import { defaultComparator, normalizeValue } from '../utils/comparison.js'
+import {
+  defaultComparator,
+  denormalizeUndefined,
+  normalizeForBTree,
+} from '../utils/comparison.js'
 import { BaseIndex } from './base-index.js'
 import type { CompareOptions } from '../query/builder/types.js'
 import type { BasicExpression } from '../query/ir.js'
@@ -29,7 +33,7 @@ export interface RangeQueryOptions {
  * This maintains items in sorted order and provides efficient range operations
  */
 export class BTreeIndex<
-  TKey extends string | number = string | number,
+  TKey extends string | number | undefined = string | number | undefined,
 > extends BaseIndex<TKey> {
   public readonly supportedOperations = new Set<IndexOperation>([
     `eq`,
@@ -55,7 +59,16 @@ export class BTreeIndex<
     options?: any,
   ) {
     super(id, expression, name, options)
-    this.compareFn = options?.compareFn ?? defaultComparator
+
+    // Get the base compare function
+    const baseCompareFn = options?.compareFn ?? defaultComparator
+
+    // Wrap it to denormalize sentinels before comparison
+    // This ensures UNDEFINED_SENTINEL is converted back to undefined
+    // before being passed to the baseCompareFn (which can be user-provided and is unaware of the UNDEFINED_SENTINEL)
+    this.compareFn = (a: any, b: any) =>
+      baseCompareFn(denormalizeUndefined(a), denormalizeUndefined(b))
+
     if (options?.compareOptions) {
       this.compareOptions = options!.compareOptions
     }
@@ -78,7 +91,7 @@ export class BTreeIndex<
     }
 
     // Normalize the value for Map key usage
-    const normalizedValue = normalizeValue(indexedValue)
+    const normalizedValue = normalizeForBTree(indexedValue)
 
     // Check if this value already exists
     if (this.valueMap.has(normalizedValue)) {
@@ -111,7 +124,7 @@ export class BTreeIndex<
     }
 
     // Normalize the value for Map key usage
-    const normalizedValue = normalizeValue(indexedValue)
+    const normalizedValue = normalizeForBTree(indexedValue)
 
     if (this.valueMap.has(normalizedValue)) {
       const keySet = this.valueMap.get(normalizedValue)!
@@ -207,7 +220,7 @@ export class BTreeIndex<
    * Performs an equality lookup
    */
   equalityLookup(value: any): Set<TKey> {
-    const normalizedValue = normalizeValue(value)
+    const normalizedValue = normalizeForBTree(value)
     return new Set(this.valueMap.get(normalizedValue) ?? [])
   }
 
@@ -219,10 +232,15 @@ export class BTreeIndex<
     const { from, to, fromInclusive = true, toInclusive = true } = options
     const result = new Set<TKey>()
 
-    const normalizedFrom = normalizeValue(from)
-    const normalizedTo = normalizeValue(to)
-    const fromKey = normalizedFrom ?? this.orderedEntries.minKey()
-    const toKey = normalizedTo ?? this.orderedEntries.maxKey()
+    // Check if from/to were explicitly provided (even if undefined)
+    // vs not provided at all (should use min/max key)
+    const hasFrom = `from` in options
+    const hasTo = `to` in options
+
+    const fromKey = hasFrom
+      ? normalizeForBTree(from)
+      : this.orderedEntries.minKey()
+    const toKey = hasTo ? normalizeForBTree(to) : this.orderedEntries.maxKey()
 
     this.orderedEntries.forRange(
       fromKey,
@@ -250,29 +268,43 @@ export class BTreeIndex<
    */
   rangeQueryReversed(options: RangeQueryOptions = {}): Set<TKey> {
     const { from, to, fromInclusive = true, toInclusive = true } = options
+    const hasFrom = `from` in options
+    const hasTo = `to` in options
+
+    // Swap from/to for reversed query, respecting explicit undefined values
     return this.rangeQuery({
-      from: to ?? this.orderedEntries.maxKey(),
-      to: from ?? this.orderedEntries.minKey(),
+      from: hasTo ? to : this.orderedEntries.maxKey(),
+      to: hasFrom ? from : this.orderedEntries.minKey(),
       fromInclusive: toInclusive,
       toInclusive: fromInclusive,
     })
   }
 
+  /**
+   * Internal method for taking items from the index.
+   * @param n - The number of items to return
+   * @param nextPair - Function to get the next pair from the BTree
+   * @param from - Already normalized! undefined means "start from beginning/end", sentinel means "start from the key undefined"
+   * @param filterFn - Optional filter function
+   * @param reversed - Whether to reverse the order of keys within each value
+   */
   private takeInternal(
     n: number,
     nextPair: (k?: any) => [any, any] | undefined,
-    from?: any,
+    from: any,
     filterFn?: (key: TKey) => boolean,
     reversed: boolean = false,
   ): Array<TKey> {
     const keysInResult: Set<TKey> = new Set()
     const result: Array<TKey> = []
     let pair: [any, any] | undefined
-    let key = normalizeValue(from)
+    let key = from // Use as-is - it's already normalized by the caller
 
     while ((pair = nextPair(key)) !== undefined && result.length < n) {
       key = pair[0]
-      const keys = this.valueMap.get(key)
+      const keys = this.valueMap.get(key) as
+        | Set<Exclude<TKey, undefined>>
+        | undefined
       if (keys && keys.size > 0) {
         // Sort keys for deterministic order, reverse if needed
         const sorted = Array.from(keys).sort(compareKeys)
@@ -291,29 +323,60 @@ export class BTreeIndex<
   }
 
   /**
-   * Returns the next n items after the provided item or the first n items if no from item is provided.
+   * Returns the next n items after the provided item.
    * @param n - The number of items to return
-   * @param from - The item to start from (exclusive). Starts from the smallest item (inclusive) if not provided.
-   * @returns The next n items after the provided key. Returns the first n items if no from item is provided.
+   * @param from - The item to start from (exclusive).
+   * @returns The next n items after the provided key.
    */
-  take(n: number, from?: any, filterFn?: (key: TKey) => boolean): Array<TKey> {
+  take(n: number, from: any, filterFn?: (key: TKey) => boolean): Array<TKey> {
     const nextPair = (k?: any) => this.orderedEntries.nextHigherPair(k)
-    return this.takeInternal(n, nextPair, from, filterFn)
+    // Normalize the from value
+    const normalizedFrom = normalizeForBTree(from)
+    return this.takeInternal(n, nextPair, normalizedFrom, filterFn)
   }
 
   /**
-   * Returns the next n items **before** the provided item (in descending order) or the last n items if no from item is provided.
+   * Returns the first n items from the beginning.
    * @param n - The number of items to return
-   * @param from - The item to start from (exclusive). Starts from the largest item (inclusive) if not provided.
-   * @returns The next n items **before** the provided key. Returns the last n items if no from item is provided.
+   * @param filterFn - Optional filter function
+   * @returns The first n items
+   */
+  takeFromStart(n: number, filterFn?: (key: TKey) => boolean): Array<TKey> {
+    const nextPair = (k?: any) => this.orderedEntries.nextHigherPair(k)
+    // Pass undefined to mean "start from beginning" (BTree's native behavior)
+    return this.takeInternal(n, nextPair, undefined, filterFn)
+  }
+
+  /**
+   * Returns the next n items **before** the provided item (in descending order).
+   * @param n - The number of items to return
+   * @param from - The item to start from (exclusive). Required.
+   * @returns The next n items **before** the provided key.
    */
   takeReversed(
     n: number,
-    from?: any,
+    from: any,
+    filterFn?: (key: TKey) => boolean,
+  ): Array<TKey> {
+    const nextPair = (k?: any) => this.orderedEntries.nextLowerPair(k)
+    // Normalize the from value
+    const normalizedFrom = normalizeForBTree(from)
+    return this.takeInternal(n, nextPair, normalizedFrom, filterFn, true)
+  }
+
+  /**
+   * Returns the last n items from the end.
+   * @param n - The number of items to return
+   * @param filterFn - Optional filter function
+   * @returns The last n items
+   */
+  takeReversedFromEnd(
+    n: number,
     filterFn?: (key: TKey) => boolean,
   ): Array<TKey> {
     const nextPair = (k?: any) => this.orderedEntries.nextLowerPair(k)
-    return this.takeInternal(n, nextPair, from, filterFn, true)
+    // Pass undefined to mean "start from end" (BTree's native behavior)
+    return this.takeInternal(n, nextPair, undefined, filterFn, true)
   }
 
   /**
@@ -323,7 +386,7 @@ export class BTreeIndex<
     const result = new Set<TKey>()
 
     for (const value of values) {
-      const normalizedValue = normalizeValue(value)
+      const normalizedValue = normalizeForBTree(value)
       const keys = this.valueMap.get(normalizedValue)
       if (keys) {
         keys.forEach((key) => result.add(key))
@@ -341,17 +404,25 @@ export class BTreeIndex<
   get orderedEntriesArray(): Array<[any, Set<TKey>]> {
     return this.orderedEntries
       .keysArray()
-      .map((key) => [key, this.valueMap.get(key) ?? new Set()])
+      .map((key) => [
+        denormalizeUndefined(key),
+        this.valueMap.get(key) ?? new Set(),
+      ])
   }
 
   get orderedEntriesArrayReversed(): Array<[any, Set<TKey>]> {
-    return this.takeReversed(this.orderedEntries.size).map((key) => [
-      key,
+    return this.takeReversedFromEnd(this.orderedEntries.size).map((key) => [
+      denormalizeUndefined(key),
       this.valueMap.get(key) ?? new Set(),
     ])
   }
 
   get valueMapData(): Map<any, Set<TKey>> {
-    return this.valueMap
+    // Return a new Map with denormalized keys
+    const result = new Map<any, Set<TKey>>()
+    for (const [key, value] of this.valueMap) {
+      result.set(denormalizeUndefined(key), value)
+    }
+    return result
   }
 }

package/src/indexes/reverse-index.ts

@@ -36,18 +36,29 @@ export class ReverseIndex<
     return this.originalIndex.rangeQuery(options)
   }
 
-  take(n: number, from?: any, filterFn?: (key: TKey) => boolean): Array<TKey> {
+  take(n: number, from: any, filterFn?: (key: TKey) => boolean): Array<TKey> {
     return this.originalIndex.takeReversed(n, from, filterFn)
   }
 
+  takeFromStart(n: number, filterFn?: (key: TKey) => boolean): Array<TKey> {
+    return this.originalIndex.takeReversedFromEnd(n, filterFn)
+  }
+
   takeReversed(
     n: number,
-    from?: any,
+    from: any,
     filterFn?: (key: TKey) => boolean,
   ): Array<TKey> {
     return this.originalIndex.take(n, from, filterFn)
   }
 
+  takeReversedFromEnd(
+    n: number,
+    filterFn?: (key: TKey) => boolean,
+  ): Array<TKey> {
+    return this.originalIndex.takeFromStart(n, filterFn)
+  }
+
   get orderedEntriesArray(): Array<[any, Set<TKey>]> {
     return this.originalIndex.orderedEntriesArrayReversed
   }

package/src/query/live/collection-config-builder.ts

@@ -830,17 +830,16 @@ export class CollectionConfigBuilder<
       return
     }
 
+    const subscribedToAll = this.currentSyncState?.subscribedToAllCollections
+    const allReady = this.allCollectionsReady()
+    const isLoading = this.liveQueryCollection?.isLoadingSubset
     // Mark ready when:
     // 1. All subscriptions are set up (subscribedToAllCollections)
     // 2. All source collections are ready
     // 3. The live query collection is not loading subset data
     // This prevents marking the live query ready before its data is processed
     // (fixes issue where useLiveQuery returns isReady=true with empty data)
-    if (
-      this.currentSyncState?.subscribedToAllCollections &&
-      this.allCollectionsReady() &&
-      !this.liveQueryCollection?.isLoadingSubset
-    ) {
+    if (subscribedToAll && allReady && !isLoading) {
       markReady()
     }
   }

package/src/query/live/collection-subscriber.ts

@@ -1,4 +1,4 @@
-import { MultiSet } from '@tanstack/db-ivm'
+import { MultiSet, serializeValue } from '@tanstack/db-ivm'
 import {
   normalizeExpressionPaths,
   normalizeOrderByPaths,
@@ -26,6 +26,11 @@ export class CollectionSubscriber<
   // Keep track of the biggest value we've sent so far (needed for orderBy optimization)
   private biggest: any = undefined
 
+  // Track the most recent ordered load request key (cursor + window).
+  // This avoids infinite loops from cached data re-writes while still allowing
+  // window moves or new keys at the same cursor value to trigger new requests.
+  private lastLoadRequestKey: string | undefined
+
   // Track deferred promises for subscription loading states
   private subscriptionLoadingPromises = new Map<
     CollectionSubscription,
@@ -37,6 +42,11 @@ export class CollectionSubscriber<
   // can potentially send the same item to D2 multiple times.
   private sentToD2Keys = new Set<string | number>()
 
+  // Direct load tracking callback for ordered path (set during subscribeToOrderedChanges,
+  // used by loadNextItems for subsequent requestLimitedSnapshot calls)
+  private orderedLoadSubsetResult?: (result: Promise<void> | true) => void
+  private pendingOrderedLoadPromise: Promise<void> | undefined
+
   constructor(
     private alias: string,
     private collectionId: string,
@@ -58,35 +68,29 @@ export class CollectionSubscriber<
   private subscribeToChanges(whereExpression?: BasicExpression<boolean>) {
     const orderByInfo = this.getOrderByInfo()
 
-    // Track load promises using subscription from the event (avoids circular dependency)
-    const trackLoadPromise = (subscription: CollectionSubscription) => {
-      // Guard against duplicate transitions
-      if (!this.subscriptionLoadingPromises.has(subscription)) {
-        let resolve: () => void
-        const promise = new Promise<void>((res) => {
-          resolve = res
-        })
-
-        this.subscriptionLoadingPromises.set(subscription, {
-          resolve: resolve!,
-        })
+    // Direct load promise tracking: pipes loadSubset results straight to the
+    // live query collection, avoiding the multi-hop deferred promise chain that
+    // can break under microtask timing (e.g., queueMicrotask in TanStack Query).
+    const trackLoadResult = (result: Promise<void> | true) => {
+      if (result instanceof Promise) {
         this.collectionConfigBuilder.liveQueryCollection!._sync.trackLoadPromise(
-          promise,
+          result,
         )
       }
     }
 
     // Status change handler - passed to subscribeChanges so it's registered
-    // BEFORE any snapshot is requested, preventing race conditions
+    // BEFORE any snapshot is requested, preventing race conditions.
+    // Used as a fallback for status transitions not covered by direct tracking
+    // (e.g., truncate-triggered reloads that call trackLoadSubsetPromise directly).
     const onStatusChange = (event: SubscriptionStatusChangeEvent) => {
       const subscription = event.subscription as CollectionSubscription
       if (event.status === `loadingSubset`) {
-        trackLoadPromise(subscription)
+        this.ensureLoadingPromise(subscription)
       } else {
         // status is 'ready'
         const deferred = this.subscriptionLoadingPromises.get(subscription)
         if (deferred) {
-          // Clear the map entry FIRST (before resolving)
           this.subscriptionLoadingPromises.delete(subscription)
           deferred.resolve()
         }
@@ -100,6 +104,7 @@ export class CollectionSubscriber<
         whereExpression,
         orderByInfo,
         onStatusChange,
+        trackLoadResult,
       )
     } else {
       // If the source alias is lazy then we should not include the initial state
@@ -117,14 +122,13 @@ export class CollectionSubscriber<
     // Check current status after subscribing - if status is 'loadingSubset', track it.
     // The onStatusChange listener will catch the transition to 'ready'.
     if (subscription.status === `loadingSubset`) {
-      trackLoadPromise(subscription)
+      this.ensureLoadingPromise(subscription)
     }
 
     const unsubscribe = () => {
       // If subscription has a pending promise, resolve it before unsubscribing
       const deferred = this.subscriptionLoadingPromises.get(subscription)
       if (deferred) {
-        // Clear the map entry FIRST (before resolving)
         this.subscriptionLoadingPromises.delete(subscription)
         deferred.resolve()
       }
@@ -197,13 +201,49 @@ export class CollectionSubscriber<
       this.sendChangesToPipeline(changes)
     }
 
-    // Create subscription with onStatusChange - listener is registered before snapshot
-    // Note: For non-ordered queries (no limit/offset), we use trackLoadSubsetPromise: false
-    // which is the default behavior in subscribeChanges
+    // Get the query's orderBy and limit to pass to loadSubset.
+    // Only include orderBy when it is scoped to this alias and uses simple refs,
+    // to avoid leaking cross-collection paths into backend-specific compilers.
+    const { orderBy, limit, offset } = this.collectionConfigBuilder.query
+    const effectiveLimit =
+      limit !== undefined && offset !== undefined ? limit + offset : limit
+    const normalizedOrderBy = orderBy
+      ? normalizeOrderByPaths(orderBy, this.alias)
+      : undefined
+    const canPassOrderBy =
+      normalizedOrderBy?.every((clause) => {
+        const exp = clause.expression
+        if (exp.type !== `ref`) {
+          return false
+        }
+        const path = exp.path
+        return Array.isArray(path) && path.length === 1
+      }) ?? false
+    const orderByForSubscription = canPassOrderBy
+      ? normalizedOrderBy
+      : undefined
+    const limitForSubscription = canPassOrderBy ? effectiveLimit : undefined
+
+    // Track loading via the loadSubset promise directly.
+    // requestSnapshot uses trackLoadSubsetPromise: false (needed for truncate handling),
+    // so we use onLoadSubsetResult to get the promise and track it ourselves.
+    const onLoadSubsetResult = includeInitialState
+      ? (result: Promise<void> | true) => {
+          if (result instanceof Promise) {
+            this.collectionConfigBuilder.liveQueryCollection!._sync.trackLoadPromise(
+              result,
+            )
+          }
+        }
+      : undefined
+
     const subscription = this.collection.subscribeChanges(sendChanges, {
       ...(includeInitialState && { includeInitialState }),
       whereExpression,
       onStatusChange,
+      orderBy: orderByForSubscription,
+      limit: limitForSubscription,
+      onLoadSubsetResult,
     })
 
     return subscription
@@ -213,17 +253,39 @@ export class CollectionSubscriber<
     whereExpression: BasicExpression<boolean> | undefined,
     orderByInfo: OrderByOptimizationInfo,
     onStatusChange: (event: SubscriptionStatusChangeEvent) => void,
+    onLoadSubsetResult: (result: Promise<void> | true) => void,
   ): CollectionSubscription {
     const { orderBy, offset, limit, index } = orderByInfo
 
+    // Store the callback so loadNextItems can also use direct tracking.
+    // Track in-flight ordered loads to avoid issuing redundant requests while
+    // a previous snapshot is still pending.
+    const handleLoadSubsetResult = (result: Promise<void> | true) => {
+      if (result instanceof Promise) {
+        this.pendingOrderedLoadPromise = result
+        result.finally(() => {
+          if (this.pendingOrderedLoadPromise === result) {
+            this.pendingOrderedLoadPromise = undefined
+          }
+        })
+      }
+      onLoadSubsetResult(result)
+    }
+
+    this.orderedLoadSubsetResult = handleLoadSubsetResult
+
     // Use a holder to forward-reference subscription in the callback
     const subscriptionHolder: { current?: CollectionSubscription } = {}
 
     const sendChangesInRange = (
       changes: Iterable<ChangeMessage<any, string | number>>,
     ) => {
+      const changesArray = Array.isArray(changes) ? changes : [...changes]
+
+      this.trackSentValues(changesArray, orderByInfo.comparator)
+
       // Split live updates into a delete of the old value and an insert of the new value
-      const splittedChanges = splitUpdates(changes)
+      const splittedChanges = splitUpdates(changesArray)
       this.sendChangesToPipelineWithTracking(
         splittedChanges,
         subscriptionHolder.current!,
@@ -243,6 +305,8 @@ export class CollectionSubscriber<
     // and allow re-inserts of previously sent keys
     const truncateUnsubscribe = this.collection.on(`truncate`, () => {
       this.biggest = undefined
+      this.lastLoadRequestKey = undefined
+      this.pendingOrderedLoadPromise = undefined
       this.sentToD2Keys.clear()
     })
 
@@ -254,26 +318,27 @@ export class CollectionSubscriber<
     // Normalize the orderBy clauses such that the references are relative to the collection
     const normalizedOrderBy = normalizeOrderByPaths(orderBy, this.alias)
 
-    // Trigger the snapshot request - onStatusChange listener is already registered
+    // Trigger the snapshot request — use direct load tracking (trackLoadSubsetPromise: false)
+    // to pipe the loadSubset result straight to the live query collection. This bypasses
+    // the subscription status → onStatusChange → deferred promise chain which is fragile
+    // under microtask timing (e.g., queueMicrotask delays in TanStack Query observers).
     if (index) {
       // We have an index on the first orderBy column - use lazy loading optimization
-      // This works for both single-column and multi-column orderBy:
-      // - Single-column: index provides exact ordering
-      // - Multi-column: index provides ordering on first column, secondary sort in memory
       subscription.setOrderByIndex(index)
 
-      // Load the first `offset + limit` values from the index
-      // i.e. the K items from the collection that fall into the requested range: [offset, offset + limit[
       subscription.requestLimitedSnapshot({
         limit: offset + limit,
         orderBy: normalizedOrderBy,
+        trackLoadSubsetPromise: false,
+        onLoadSubsetResult: handleLoadSubsetResult,
       })
     } else {
       // No index available (e.g., non-ref expression): pass orderBy/limit to loadSubset
-      // so the sync layer can optimize if the backend supports it
       subscription.requestSnapshot({
         orderBy: normalizedOrderBy,
         limit: offset + limit,
+        trackLoadSubsetPromise: false,
+        onLoadSubsetResult: handleLoadSubsetResult,
       })
     }
 
@@ -301,6 +366,11 @@ export class CollectionSubscriber<
       return true
     }
 
+    if (this.pendingOrderedLoadPromise) {
+      // Wait for in-flight ordered loads to resolve before issuing another request.
+      return true
+    }
+
     // `dataNeeded` probes the orderBy operator to see if it needs more data
     // if it needs more data, it returns the number of items it needs
     const n = dataNeeded()
@@ -320,8 +390,6 @@ export class CollectionSubscriber<
       return
     }
 
-    const trackedChanges = this.trackSentValues(changes, orderByInfo.comparator)
-
     // Cache the loadMoreIfNeeded callback on the subscription using a symbol property.
     // This ensures we pass the same function instance to the scheduler each time,
     // allowing it to deduplicate callbacks when multiple changes arrive during a transaction.
@@ -335,7 +403,7 @@ export class CollectionSubscriber<
       this.loadMoreIfNeeded.bind(this, subscription)
 
     this.sendChangesToPipeline(
-      trackedChanges,
+      changes,
       subscriptionWithLoader[loadMoreCallbackSymbol],
     )
   }
@@ -357,12 +425,25 @@ export class CollectionSubscriber<
       : undefined
 
     // Normalize to array format for minValues
-    const minValues =
-      extractedValues !== undefined
-        ? Array.isArray(extractedValues)
-          ? extractedValues
-          : [extractedValues]
-        : undefined
+    let minValues: Array<unknown> | undefined
+    if (extractedValues !== undefined) {
+      minValues = Array.isArray(extractedValues)
+        ? extractedValues
+        : [extractedValues]
+    }
+
+    const loadRequestKey = this.getLoadRequestKey({
+      minValues,
+      offset,
+      limit: n,
+    })
+
+    // Skip if we already requested a load for this cursor+window.
+    // This prevents infinite loops from cached data re-writes while still allowing
+    // window moves (offset/limit changes) to trigger new requests.
+    if (this.lastLoadRequestKey === loadRequestKey) {
+      return
+    }
 
     // Normalize the orderBy clauses such that the references are relative to the collection
     const normalizedOrderBy = normalizeOrderByPaths(orderBy, this.alias)
@@ -373,8 +454,13 @@ export class CollectionSubscriber<
       orderBy: normalizedOrderBy,
       limit: n,
       minValues,
-      offset,
+      // Omit offset so requestLimitedSnapshot can advance the offset based on
+      // the number of rows already loaded (supports offset-based backends).
+      trackLoadSubsetPromise: false,
+      onLoadSubsetResult: this.orderedLoadSubsetResult,
     })
+
+    this.lastLoadRequestKey = loadRequestKey
   }
 
   private getWhereClauseForAlias(): BasicExpression<boolean> | undefined {
@@ -397,22 +483,59 @@ export class CollectionSubscriber<
     return undefined
   }
 
-  private *trackSentValues(
-    changes: Iterable<ChangeMessage<any, string | number>>,
+  private trackSentValues(
+    changes: Array<ChangeMessage<any, string | number>>,
     comparator: (a: any, b: any) => number,
-  ) {
+  ): void {
     for (const change of changes) {
+      if (change.type === `delete`) {
+        continue
+      }
+
+      const isNewKey = !this.sentToD2Keys.has(change.key)
+
       // Only track inserts/updates for cursor positioning, not deletes
-      if (change.type !== `delete`) {
-        if (!this.biggest) {
-          this.biggest = change.value
-        } else if (comparator(this.biggest, change.value) < 0) {
-          this.biggest = change.value
-        }
+      if (!this.biggest) {
+        this.biggest = change.value
+        this.lastLoadRequestKey = undefined
+      } else if (comparator(this.biggest, change.value) < 0) {
+        this.biggest = change.value
+        this.lastLoadRequestKey = undefined
+      } else if (isNewKey) {
+        // New key with same orderBy value - allow another load if needed
+        this.lastLoadRequestKey = undefined
       }
+    }
+  }
 
-      yield change
+  private ensureLoadingPromise(subscription: CollectionSubscription) {
+    if (this.subscriptionLoadingPromises.has(subscription)) {
+      return
     }
+
+    let resolve: () => void
+    const promise = new Promise<void>((res) => {
+      resolve = res
+    })
+
+    this.subscriptionLoadingPromises.set(subscription, {
+      resolve: resolve!,
+    })
+    this.collectionConfigBuilder.liveQueryCollection!._sync.trackLoadPromise(
+      promise,
+    )
+  }
+
+  private getLoadRequestKey(options: {
+    minValues: Array<unknown> | undefined
+    offset: number
+    limit: number
+  }): string {
+    return serializeValue({
+      minValues: options.minValues ?? null,
+      offset: options.offset,
+      limit: options.limit,
+    })
   }
 }