@tanstack/db 0.3.1 → 0.4.0

package/src/query/compiler/joins.ts

@@ -16,8 +16,9 @@ import {
   UnsupportedJoinSourceTypeError,
   UnsupportedJoinTypeError,
 } from "../../errors.js"
-import { findIndexForField } from "../../utils/index-optimization.js"
 import { ensureIndexForField } from "../../indexes/auto-index.js"
+import { PropRef } from "../ir.js"
+import { inArray } from "../builder/functions.js"
 import { compileExpression } from "./evaluators.js"
 import { compileQuery, followRef } from "./index.js"
 import type { OrderByOptimizationInfo } from "./order-by.js"
@@ -25,19 +26,18 @@ import type {
   BasicExpression,
   CollectionRef,
   JoinClause,
-  PropRef,
   QueryIR,
   QueryRef,
 } from "../ir.js"
 import type { IStreamBuilder, JoinType } from "@tanstack/db-ivm"
-import type { Collection } from "../../collection.js"
+import type { Collection } from "../../collection/index.js"
 import type {
   KeyedStream,
   NamespacedAndKeyedStream,
   NamespacedRow,
 } from "../../types.js"
 import type { QueryCache, QueryMapping } from "./types.js"
-import type { BaseIndex } from "../../indexes/base-index.js"
+import type { CollectionSubscription } from "../../collection/subscription.js"
 
 export type LoadKeysFn = (key: Set<string | number>) => void
 export type LazyCollectionCallbacks = {
@@ -58,6 +58,7 @@ export function processJoins(
   cache: QueryCache,
   queryMapping: QueryMapping,
   collections: Record<string, Collection>,
+  subscriptions: Record<string, CollectionSubscription>,
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
@@ -76,6 +77,7 @@ export function processJoins(
       cache,
       queryMapping,
       collections,
+      subscriptions,
       callbacks,
       lazyCollections,
       optimizableOrderByCollections,
@@ -99,6 +101,7 @@ function processJoin(
   cache: QueryCache,
   queryMapping: QueryMapping,
   collections: Record<string, Collection>,
+  subscriptions: Record<string, CollectionSubscription>,
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
@@ -113,6 +116,7 @@ function processJoin(
     joinClause.from,
     allInputs,
     collections,
+    subscriptions,
     callbacks,
     lazyCollections,
     optimizableOrderByCollections,
@@ -215,8 +219,6 @@ function processJoin(
       const activePipeline =
         activeCollection === `main` ? mainPipeline : joinedPipeline
 
-      let index: BaseIndex<string | number> | undefined
-
       const lazyCollectionJoinExpr =
         activeCollection === `main`
           ? (joinedExpr as PropRef)
@@ -238,50 +240,33 @@ function processJoin(
         )
       }
 
-      let deoptimized = false
-
       const activePipelineWithLoading: IStreamBuilder<
         [key: unknown, [originalKey: string, namespacedRow: NamespacedRow]]
       > = activePipeline.pipe(
         tap((data) => {
-          if (deoptimized) {
-            return
-          }
+          const lazyCollectionSubscription = subscriptions[lazyCollection.id]
 
-          // Find the index for the path we join on
-          // we need to find the index inside the map operator
-          // because the indexes are only available after the initial sync
-          // so we can't fetch it during compilation
-          index ??= findIndexForField(
-            followRefCollection.indexes,
-            followRefResult.path
-          )
-
-          // The `callbacks` object is passed by the liveQueryCollection to the compiler.
-          // It contains a function to lazy load keys for each lazy collection
-          // as well as a function to switch back to a regular collection
-          // (useful when there's no index for available for lazily loading the collection)
-          const collectionCallbacks = callbacks[lazyCollection.id]
-          if (!collectionCallbacks) {
+          if (!lazyCollectionSubscription) {
             throw new Error(
-              `Internal error: callbacks for collection are missing in join pipeline. Make sure the live query collection sets them before running the pipeline.`
+              `Internal error: subscription for collection is missing in join pipeline. Make sure the live query collection sets the subscription before running the pipeline.`
             )
           }
 
-          const { loadKeys, loadInitialState } = collectionCallbacks
-
-          if (index && index.supports(`in`)) {
-            // Use the index to fetch the PKs of the rows in the lazy collection
-            // that match this row from the active collection based on the value of the joinKey
-            const joinKeys = data.getInner().map(([[joinKey]]) => joinKey)
-            const matchingKeys = index.lookup(`in`, joinKeys)
-            // Inform the lazy collection that those keys need to be loaded
-            loadKeys(matchingKeys)
-          } else {
-            // We can't optimize the join because there is no index for the join key
-            // on the lazy collection, so we load the initial state
-            deoptimized = true
-            loadInitialState()
+          if (lazyCollectionSubscription.hasLoadedInitialState()) {
+            // Entire state was already loaded because we deoptimized the join
+            return
+          }
+
+          const joinKeys = data.getInner().map(([[joinKey]]) => joinKey)
+          const lazyJoinRef = new PropRef(followRefResult.path)
+          const loaded = lazyCollectionSubscription.requestSnapshot({
+            where: inArray(lazyJoinRef, joinKeys),
+            optimizedOnly: true,
+          })
+
+          if (!loaded) {
+            // Snapshot wasn't sent because it could not be loaded from the indexes
+            lazyCollectionSubscription.requestSnapshot()
           }
         })
       )
@@ -397,6 +382,7 @@ function processJoinSource(
   from: CollectionRef | QueryRef,
   allInputs: Record<string, KeyedStream>,
   collections: Record<string, Collection>,
+  subscriptions: Record<string, CollectionSubscription>,
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazyCollections: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
@@ -420,6 +406,7 @@ function processJoinSource(
         originalQuery,
         allInputs,
         collections,
+        subscriptions,
         callbacks,
         lazyCollections,
         optimizableOrderByCollections,

package/src/query/compiler/order-by.ts

@@ -11,7 +11,7 @@ import type { OrderByClause, QueryIR, Select } from "../ir.js"
 import type { NamespacedAndKeyedStream, NamespacedRow } from "../../types.js"
 import type { IStreamBuilder, KeyValue } from "@tanstack/db-ivm"
 import type { BaseIndex } from "../../indexes/base-index.js"
-import type { Collection } from "../../collection.js"
+import type { Collection } from "../../collection/index.js"
 
 export type OrderByOptimizationInfo = {
   offset: number

package/src/query/ir.ts

@@ -3,7 +3,7 @@ This is the intermediate representation of the query.
 */
 
 import type { CompareOptions } from "./builder/types"
-import type { CollectionImpl } from "../collection"
+import type { CollectionImpl } from "../collection/index.js"
 import type { NamespacedRow } from "../types"
 
 export interface QueryIR {

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

@@ -2,9 +2,10 @@ import { D2, output } from "@tanstack/db-ivm"
 import { compileQuery } from "../compiler/index.js"
 import { buildQuery, getQueryIR } from "../builder/index.js"
 import { CollectionSubscriber } from "./collection-subscriber.js"
+import type { CollectionSubscription } from "../../collection/subscription.js"
 import type { RootStreamBuilder } from "@tanstack/db-ivm"
 import type { OrderByOptimizationInfo } from "../compiler/order-by.js"
-import type { Collection } from "../../collection.js"
+import type { Collection } from "../../collection/index.js"
 import type {
   CollectionConfig,
   KeyedStream,
@@ -41,6 +42,8 @@ export class CollectionConfigBuilder<
 
   private readonly compare?: (val1: TResult, val2: TResult) => number
 
+  private isGraphRunning = false
+
   private graphCache: D2 | undefined
   private inputsCache: Record<string, RootStreamBuilder<unknown>> | undefined
   private pipelineCache: ResultStream | undefined
@@ -48,6 +51,8 @@ export class CollectionConfigBuilder<
     | Map<string, BasicExpression<boolean>>
     | undefined
 
+  // Map of collection ID to subscription
+  readonly subscriptions: Record<string, CollectionSubscription> = {}
   // Map of collection IDs to functions that load keys for that lazy collection
   lazyCollectionsCallbacks: Record<string, LazyCollectionCallbacks> = {}
   // Set of collection IDs that are lazy collections
@@ -104,25 +109,41 @@ export class CollectionConfigBuilder<
     syncState: FullSyncState,
     callback?: () => boolean
   ) {
-    const { begin, commit, markReady } = config
+    if (this.isGraphRunning) {
+      // no nested runs of the graph
+      // which is possible if the `callback`
+      // would call `maybeRunGraph` e.g. after it has loaded some more data
+      return
+    }
 
-    // We only run the graph if all the collections are ready
-    if (
-      this.allCollectionsReadyOrInitialCommit() &&
-      syncState.subscribedToAllCollections
-    ) {
-      syncState.graph.run()
-      const ready = callback?.() ?? true
-      // On the initial run, we may need to do an empty commit to ensure that
-      // the collection is initialized
-      if (syncState.messagesCount === 0) {
-        begin()
-        commit()
-      }
-      // Mark the collection as ready after the first successful run
-      if (ready && this.allCollectionsReady()) {
-        markReady()
+    this.isGraphRunning = true
+
+    try {
+      const { begin, commit, markReady } = config
+
+      // We only run the graph if all the collections are ready
+      if (
+        this.allCollectionsReadyOrInitialCommit() &&
+        syncState.subscribedToAllCollections
+      ) {
+        while (syncState.graph.pendingWork()) {
+          syncState.graph.run()
+          callback?.()
+        }
+
+        // On the initial run, we may need to do an empty commit to ensure that
+        // the collection is initialized
+        if (syncState.messagesCount === 0) {
+          begin()
+          commit()
+        }
+        // Mark the collection as ready after the first successful run
+        if (this.allCollectionsReady()) {
+          markReady()
+        }
       }
+    } finally {
+      this.isGraphRunning = false
     }
   }
 
@@ -189,6 +210,7 @@ export class CollectionConfigBuilder<
       this.query,
       this.inputsCache as Record<string, KeyedStream>,
       this.collections,
+      this.subscriptions,
       this.lazyCollectionsCallbacks,
       this.lazyCollections,
       this.optimizableOrderByCollections
@@ -320,17 +342,21 @@ export class CollectionConfigBuilder<
           syncState,
           this
         )
-        collectionSubscriber.subscribe()
 
-        const loadMore =
-          collectionSubscriber.loadMoreIfNeeded.bind(collectionSubscriber)
+        const subscription = collectionSubscriber.subscribe()
+        this.subscriptions[collectionId] = subscription
+
+        const loadMore = collectionSubscriber.loadMoreIfNeeded.bind(
+          collectionSubscriber,
+          subscription
+        )
 
         return loadMore
       }
     )
 
     const loadMoreDataCallback = () => {
-      loaders.map((loader) => loader()) // .every((doneLoading) => doneLoading)
+      loaders.map((loader) => loader())
       return true
     }
 

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

@@ -1,21 +1,18 @@
 import { MultiSet } from "@tanstack/db-ivm"
-import { createFilterFunctionFromExpression } from "../../change-events.js"
 import { convertToBasicExpression } from "../compiler/expressions.js"
 import type { FullSyncState } from "./types.js"
 import type { MultiSetArray, RootStreamBuilder } from "@tanstack/db-ivm"
-import type { Collection } from "../../collection.js"
+import type { Collection } from "../../collection/index.js"
 import type { ChangeMessage, SyncConfig } from "../../types.js"
 import type { Context, GetResult } from "../builder/types.js"
 import type { BasicExpression } from "../ir.js"
 import type { CollectionConfigBuilder } from "./collection-config-builder.js"
+import type { CollectionSubscription } from "../../collection/subscription.js"
 
 export class CollectionSubscriber<
   TContext extends Context,
   TResult extends object = GetResult<TContext>,
 > {
-  // Keep track of the keys we've sent (needed for join and orderBy optimizations)
-  private sentKeys = new Set<string | number>()
-
   // Keep track of the biggest value we've sent so far (needed for orderBy optimization)
   private biggest: any = undefined
 
@@ -27,7 +24,7 @@ export class CollectionSubscriber<
     private collectionConfigBuilder: CollectionConfigBuilder<TContext, TResult>
   ) {}
 
-  subscribe() {
+  subscribe(): CollectionSubscription {
     const collectionAlias = findCollectionAlias(
       this.collectionId,
       this.collectionConfigBuilder.query
@@ -43,7 +40,7 @@ export class CollectionSubscriber<
 
       if (whereExpression) {
         // Use index optimization for this collection
-        this.subscribeToChanges(whereExpression)
+        return this.subscribeToChanges(whereExpression)
       } else {
         // This should not happen - if we have a whereClause but can't create whereExpression,
         // it indicates a bug in our optimization logic
@@ -54,25 +51,34 @@ export class CollectionSubscriber<
       }
     } else {
       // No WHERE clause for this collection, use regular subscription
-      this.subscribeToChanges()
+      return this.subscribeToChanges()
     }
   }
 
   private subscribeToChanges(whereExpression?: BasicExpression<boolean>) {
-    let unsubscribe: () => void
-    if (this.collectionConfigBuilder.lazyCollections.has(this.collectionId)) {
-      unsubscribe = this.subscribeToMatchingChanges(whereExpression)
-    } else if (
+    let subscription: CollectionSubscription
+    if (
       Object.hasOwn(
         this.collectionConfigBuilder.optimizableOrderByCollections,
         this.collectionId
       )
     ) {
-      unsubscribe = this.subscribeToOrderedChanges(whereExpression)
+      subscription = this.subscribeToOrderedChanges(whereExpression)
     } else {
-      unsubscribe = this.subscribeToAllChanges(whereExpression)
+      // If the collection is lazy then we should not include the initial state
+      const includeInitialState =
+        !this.collectionConfigBuilder.lazyCollections.has(this.collectionId)
+
+      subscription = this.subscribeToMatchingChanges(
+        whereExpression,
+        includeInitialState
+      )
+    }
+    const unsubscribe = () => {
+      subscription.unsubscribe()
     }
     this.syncState.unsubscribeCallbacks.add(unsubscribe)
+    return subscription
   }
 
   private sendChangesToPipeline(
@@ -101,153 +107,38 @@ export class CollectionSubscriber<
     )
   }
 
-  // Wraps the sendChangesToPipeline function
-  // in order to turn `update`s into `insert`s
-  // for keys that have not been sent to the pipeline yet
-  // and filter out deletes for keys that have not been sent
-  private sendVisibleChangesToPipeline = (
-    changes: Array<ChangeMessage<any, string | number>>,
-    loadedInitialState: boolean
-  ) => {
-    if (loadedInitialState) {
-      // There was no index for the join key
-      // so we loaded the initial state
-      // so we can safely assume that the pipeline has seen all keys
-      return this.sendChangesToPipeline(changes)
-    }
-
-    const newChanges = []
-    for (const change of changes) {
-      let newChange = change
-      if (!this.sentKeys.has(change.key)) {
-        if (change.type === `update`) {
-          newChange = { ...change, type: `insert` }
-        } else if (change.type === `delete`) {
-          // filter out deletes for keys that have not been sent
-          continue
-        }
-        this.sentKeys.add(change.key)
-      }
-      newChanges.push(newChange)
-    }
-
-    return this.sendChangesToPipeline(newChanges)
-  }
-
-  private loadKeys(
-    keys: Iterable<string | number>,
-    filterFn: (item: object) => boolean
-  ) {
-    const changes: Array<ChangeMessage<any, string | number>> = []
-    for (const key of keys) {
-      // Only load the key once
-      if (this.sentKeys.has(key)) continue
-
-      const value = this.collection.get(key)
-      if (value !== undefined && filterFn(value)) {
-        this.sentKeys.add(key)
-        changes.push({ type: `insert`, key, value })
-      }
-    }
-    if (changes.length > 0) {
-      this.sendChangesToPipeline(changes)
-    }
-  }
-
-  private subscribeToAllChanges(
-    whereExpression: BasicExpression<boolean> | undefined
-  ) {
-    const sendChangesToPipeline = this.sendChangesToPipeline.bind(this)
-    const unsubscribe = this.collection.subscribeChanges(
-      sendChangesToPipeline,
-      {
-        includeInitialState: true,
-        ...(whereExpression ? { whereExpression } : undefined),
-      }
-    )
-    return unsubscribe
-  }
-
   private subscribeToMatchingChanges(
-    whereExpression: BasicExpression<boolean> | undefined
+    whereExpression: BasicExpression<boolean> | undefined,
+    includeInitialState: boolean = false
   ) {
-    // Flag to indicate we have send to whole initial state of the collection
-    // to the pipeline, this is set when there are no indexes that can be used
-    // to filter the changes and so the whole state was requested from the collection
-    let loadedInitialState = false
-
-    // Flag to indicate that we have started sending changes to the pipeline.
-    // This is set to true by either the first call to `loadKeys` or when the
-    // query requests the whole initial state in `loadInitialState`.
-    // Until that point we filter out all changes from subscription to the collection.
-    let sendChanges = false
-
-    const sendVisibleChanges = (
+    const sendChanges = (
       changes: Array<ChangeMessage<any, string | number>>
     ) => {
-      // We filter out changes when sendChanges is false to ensure that we don't send
-      // any changes from the live subscription until the join operator requests either
-      // the initial state or its first key. This is needed otherwise it could receive
-      // changes which are then later subsumed by the initial state (and that would
-      // lead to weird bugs due to the data being received twice).
-      this.sendVisibleChangesToPipeline(
-        sendChanges ? changes : [],
-        loadedInitialState
-      )
+      this.sendChangesToPipeline(changes)
     }
 
-    const unsubscribe = this.collection.subscribeChanges(sendVisibleChanges, {
+    const subscription = this.collection.subscribeChanges(sendChanges, {
+      includeInitialState,
       whereExpression,
     })
 
-    // Create a function that loads keys from the collection
-    // into the query pipeline on demand
-    const filterFn = whereExpression
-      ? createFilterFunctionFromExpression(whereExpression)
-      : () => true
-    const loadKs = (keys: Set<string | number>) => {
-      sendChanges = true
-      return this.loadKeys(keys, filterFn)
-    }
-
-    // Store the functions to load keys and load initial state in the `lazyCollectionsCallbacks` map
-    // This is used by the join operator to dynamically load matching keys from the lazy collection
-    // or to get the full initial state of the collection if there's no index for the join key
-    this.collectionConfigBuilder.lazyCollectionsCallbacks[this.collectionId] = {
-      loadKeys: loadKs,
-      loadInitialState: () => {
-        // Make sure we only load the initial state once
-        if (loadedInitialState) return
-        loadedInitialState = true
-        sendChanges = true
-
-        const changes = this.collection.currentStateAsChanges({
-          whereExpression,
-        })
-        this.sendChangesToPipeline(changes)
-      },
-    }
-    return unsubscribe
+    return subscription
   }
 
   private subscribeToOrderedChanges(
     whereExpression: BasicExpression<boolean> | undefined
   ) {
-    const { offset, limit, comparator, dataNeeded } =
+    const { offset, limit, comparator, dataNeeded, index } =
       this.collectionConfigBuilder.optimizableOrderByCollections[
         this.collectionId
       ]!
 
-    // 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[
-    this.loadNextItems(offset + limit)
-
     const sendChangesInRange = (
       changes: Iterable<ChangeMessage<any, string | number>>
     ) => {
       // Split live updates into a delete of the old value and an insert of the new value
       // and filter out changes that are bigger than the biggest value we've sent so far
-      // because they can't affect the topK
+      // because they can't affect the topK (and if later we need more data, we will dynamically load more data)
       const splittedChanges = splitUpdates(changes)
       let filteredChanges = splittedChanges
       if (dataNeeded!() === 0) {
@@ -261,25 +152,31 @@ export class CollectionSubscriber<
           this.biggest
         )
       }
-      this.sendChangesToPipeline(
-        filteredChanges,
-        this.loadMoreIfNeeded.bind(this)
-      )
+
+      this.sendChangesToPipelineWithTracking(filteredChanges, subscription)
     }
 
     // Subscribe to changes and only send changes that are smaller than the biggest value we've sent so far
     // values that are bigger don't need to be sent because they can't affect the topK
-    const unsubscribe = this.collection.subscribeChanges(sendChangesInRange, {
+    const subscription = this.collection.subscribeChanges(sendChangesInRange, {
       whereExpression,
     })
 
-    return unsubscribe
+    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,
+    })
+
+    return subscription
   }
 
   // This function is called by maybeRunGraph
   // after each iteration of the query pipeline
   // to ensure that the orderBy operator has enough data to work with
-  loadMoreIfNeeded() {
+  loadMoreIfNeeded(subscription: CollectionSubscription) {
     const orderByInfo =
       this.collectionConfigBuilder.optimizableOrderByCollections[
         this.collectionId
@@ -287,7 +184,7 @@ export class CollectionSubscriber<
 
     if (!orderByInfo) {
       // This query has no orderBy operator
-      // so there's no data to load, just return true
+      // so there's no data to load
       return true
     }
 
@@ -304,32 +201,31 @@ export class CollectionSubscriber<
     // `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()
-    let noMoreNextItems = false
     if (n > 0) {
-      const loadedItems = this.loadNextItems(n)
-      noMoreNextItems = loadedItems === 0
+      this.loadNextItems(n, subscription)
     }
-
-    // Indicate that we're done loading data if we didn't need to load more data
-    // or there's no more data to load
-    return n === 0 || noMoreNextItems
+    return true
   }
 
   private sendChangesToPipelineWithTracking(
-    changes: Iterable<ChangeMessage<any, string | number>>
+    changes: Iterable<ChangeMessage<any, string | number>>,
+    subscription: CollectionSubscription
   ) {
     const { comparator } =
       this.collectionConfigBuilder.optimizableOrderByCollections[
         this.collectionId
       ]!
     const trackedChanges = this.trackSentValues(changes, comparator)
-    this.sendChangesToPipeline(trackedChanges, this.loadMoreIfNeeded.bind(this))
+    this.sendChangesToPipeline(
+      trackedChanges,
+      this.loadMoreIfNeeded.bind(this, subscription)
+    )
   }
 
   // Loads the next `n` items from the collection
   // starting from the biggest item it has sent
-  private loadNextItems(n: number) {
-    const { valueExtractorForRawRow, index } =
+  private loadNextItems(n: number, subscription: CollectionSubscription) {
+    const { valueExtractorForRawRow } =
       this.collectionConfigBuilder.optimizableOrderByCollections[
         this.collectionId
       ]!
@@ -338,13 +234,10 @@ export class CollectionSubscriber<
       ? valueExtractorForRawRow(biggestSentRow)
       : biggestSentRow
     // Take the `n` items after the biggest sent value
-    const nextOrderedKeys = index.take(n, biggestSentValue)
-    const nextInserts: Array<ChangeMessage<any, string | number>> =
-      nextOrderedKeys.map((key) => {
-        return { type: `insert`, key, value: this.collection.get(key) }
-      })
-    this.sendChangesToPipelineWithTracking(nextInserts)
-    return nextInserts.length
+    subscription.requestLimitedSnapshot({
+      limit: n,
+      minValue: biggestSentValue,
+    })
   }
 
   private getWhereClauseFromAlias(
@@ -363,8 +256,6 @@ export class CollectionSubscriber<
     comparator: (a: any, b: any) => number
   ) {
     for (const change of changes) {
-      this.sentKeys.add(change.key)
-
       if (!this.biggest) {
         this.biggest = change.value
       } else if (comparator(this.biggest, change.value) < 0) {
@@ -427,7 +318,11 @@ function sendChangesToInput(
       multiSetArray.push([[key, change.value], -1])
     }
   }
-  input.sendData(new MultiSet(multiSetArray))
+
+  if (multiSetArray.length !== 0) {
+    input.sendData(new MultiSet(multiSetArray))
+  }
+
   return multiSetArray.length
 }
 
@@ -463,7 +358,7 @@ function* filterChanges<
 }
 
 /**
- * Filters changes to only include those that are smaller than the provided max value
+ * Filters changes to only include those that are smaller or equal to the provided max value
  * @param changes - Iterable of changes to filter
  * @param comparator - Comparator function to use for filtering
  * @param maxValue - Range to filter changes within (range boundaries are exclusive)