Callback to inform about loadSubset deduplication

.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

packages/db/src/query/subset-dedupe.ts

@@ -12,8 +12,14 @@ import type { LoadSubsetOptions } from "../types.js"
  * Tracks what data has been loaded and avoids redundant calls by applying
  * subset logic to predicates.
  *
+ * @param loadSubset - The underlying loadSubset function to wrap
+ * @param onDeduplicate - 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
- * const dedupe = new DeduplicatedLoadSubset(myLoadSubset)
+ * const dedupe = new DeduplicatedLoadSubset(myLoadSubset, (opts) => console.log(`Call was deduplicated:`, opts))
  *
  * // First call - fetches data
  * await dedupe.loadSubset({ where: gt(ref('age'), val(10)) })
@@ -30,6 +36,11 @@ export class DeduplicatedLoadSubset {
     options: LoadSubsetOptions
   ) => true | Promise<void>
 
+  // An optional callback function that is invoked when a loadSubset call is deduplicated.
+  private readonly onDeduplicate:
+    | ((options: LoadSubsetOptions) => void)
+    | undefined
+
   // Combined where predicate for all unlimited calls (no limit)
   private unlimitedWhere: BasicExpression<boolean> | undefined = undefined
 
@@ -53,9 +64,11 @@ export class DeduplicatedLoadSubset {
   private generation = 0
 
   constructor(
-    loadSubset: (options: LoadSubsetOptions) => true | Promise<void>
+    loadSubset: (options: LoadSubsetOptions) => true | Promise<void>,
+    onDeduplicate?: (options: LoadSubsetOptions) => void
   ) {
     this._loadSubset = loadSubset
+    this.onDeduplicate = onDeduplicate
   }
 
   /**
@@ -71,13 +84,15 @@ export class DeduplicatedLoadSubset {
   loadSubset = (options: LoadSubsetOptions): true | Promise<void> => {
     // If we've loaded all data, everything is covered
     if (this.hasLoadedAllData) {
+      this.onDeduplicate?.(options)
       return true
     }
 
     // Check against unlimited combined predicate
     // If we've loaded all data matching a where clause, we don't need to refetch subsets
     if (this.unlimitedWhere !== undefined && options.where !== undefined) {
       if (isWhereSubset(options.where, this.unlimitedWhere)) {
+        this.onDeduplicate?.(options)
         return true // Data already loaded via unlimited call
       }
     }
@@ -89,6 +104,7 @@ export class DeduplicatedLoadSubset {
       )
 
       if (alreadyLoaded) {
+        this.onDeduplicate?.(options)
         return true // Already loaded
       }
     }
@@ -103,7 +119,10 @@ export class DeduplicatedLoadSubset {
       // An in-flight call will load data that covers this request
       // Return the same promise so this caller waits for the data to load
       // The in-flight promise already handles tracking updates when it completes
-      return matchingInflight.promise
+      const prom = matchingInflight.promise
+      // Call `onDeduplicate` when the inflight request has loaded the data
+      prom.then(() => this.onDeduplicate?.(options)).catch() // ignore errors
+      return prom
     }
 
     // Not fully covered by existing data

packages/db/tests/predicate-utils.test.ts → packages/db/tests/query/predicate-utils.test.ts

@@ -6,10 +6,14 @@ import {
   isWhereSubset,
   minusWherePredicates,
   unionWherePredicates,
-} from "../src/query/predicate-utils"
-import { Func, PropRef, Value } from "../src/query/ir"
-import type { BasicExpression, OrderBy, OrderByClause } from "../src/query/ir"
-import type { LoadSubsetOptions } from "../src/types"
+} from "../../src/query/predicate-utils"
+import { Func, PropRef, Value } from "../../src/query/ir"
+import type {
+  BasicExpression,
+  OrderBy,
+  OrderByClause,
+} from "../../src/query/ir"
+import type { LoadSubsetOptions } from "../../src/types"
 
 // Helper functions to build expressions more easily
 function ref(path: string | Array<string>): PropRef {

packages/db/tests/subset-dedupe.test.ts → packages/db/tests/query/subset-dedupe.test.ts

@@ -1,12 +1,12 @@
-import { describe, expect, it } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 import {
   DeduplicatedLoadSubset,
   cloneOptions,
-} from "../src/query/subset-dedupe"
-import { Func, PropRef, Value } from "../src/query/ir"
-import { minusWherePredicates } from "../src/query/predicate-utils"
-import type { BasicExpression, OrderBy } from "../src/query/ir"
-import type { LoadSubsetOptions } from "../src/types"
+} from "../../src/query/subset-dedupe"
+import { Func, PropRef, Value } from "../../src/query/ir"
+import { minusWherePredicates } from "../../src/query/predicate-utils"
+import type { BasicExpression, OrderBy } from "../../src/query/ir"
+import type { LoadSubsetOptions } from "../../src/types"
 
 // Helper functions to build expressions more easily
 function ref(path: string | Array<string>): PropRef {
@@ -559,4 +559,152 @@ describe(`createDeduplicatedLoadSubset`, () => {
       */
     })
   })
+
+  describe(`onDeduplicate callback`, () => {
+    it(`should call onDeduplicate when all data already loaded`, async () => {
+      let callCount = 0
+      const mockLoadSubset = () => {
+        callCount++
+        return Promise.resolve()
+      }
+
+      const onDeduplicate = vi.fn()
+      const deduplicated = new DeduplicatedLoadSubset(
+        mockLoadSubset,
+        onDeduplicate
+      )
+
+      // Load all data
+      await deduplicated.loadSubset({})
+      expect(callCount).toBe(1)
+
+      // Any subsequent request should be deduplicated
+      const subsetOptions = { where: gt(ref(`age`), val(10)) }
+      const result = await deduplicated.loadSubset(subsetOptions)
+      expect(result).toBe(true)
+      expect(callCount).toBe(1)
+      expect(onDeduplicate).toHaveBeenCalledTimes(1)
+      expect(onDeduplicate).toHaveBeenCalledWith(subsetOptions)
+    })
+
+    it(`should call onDeduplicate when unlimited superset already loaded`, async () => {
+      let callCount = 0
+      const mockLoadSubset = () => {
+        callCount++
+        return Promise.resolve()
+      }
+
+      const onDeduplicate = vi.fn()
+      const deduplicated = new DeduplicatedLoadSubset(
+        mockLoadSubset,
+        onDeduplicate
+      )
+
+      // First call loads a broader set
+      await deduplicated.loadSubset({ where: gt(ref(`age`), val(10)) })
+      expect(callCount).toBe(1)
+
+      // Second call is a subset of the first; should dedupe and call callback
+      const subsetOptions = { where: gt(ref(`age`), val(20)) }
+      const result = await deduplicated.loadSubset(subsetOptions)
+      expect(result).toBe(true)
+      expect(callCount).toBe(1)
+      expect(onDeduplicate).toHaveBeenCalledTimes(1)
+      expect(onDeduplicate).toHaveBeenCalledWith(subsetOptions)
+    })
+
+    it(`should call onDeduplicate for limited subset requests`, async () => {
+      let callCount = 0
+      const mockLoadSubset = () => {
+        callCount++
+        return Promise.resolve()
+      }
+
+      const onDeduplicate = vi.fn()
+      const deduplicated = new DeduplicatedLoadSubset(
+        mockLoadSubset,
+        onDeduplicate
+      )
+
+      const orderBy1: OrderBy = [
+        {
+          expression: ref(`age`),
+          compareOptions: {
+            direction: `asc`,
+            nulls: `last`,
+            stringSort: `lexical`,
+          },
+        },
+      ]
+
+      // First limited call
+      await deduplicated.loadSubset({
+        where: gt(ref(`age`), val(10)),
+        orderBy: orderBy1,
+        limit: 10,
+      })
+      expect(callCount).toBe(1)
+
+      // Second limited call is a subset (stricter where and smaller limit)
+      const subsetOptions = {
+        where: gt(ref(`age`), val(20)),
+        orderBy: orderBy1,
+        limit: 5,
+      }
+      const result = await deduplicated.loadSubset(subsetOptions)
+      expect(result).toBe(true)
+      expect(callCount).toBe(1)
+      expect(onDeduplicate).toHaveBeenCalledTimes(1)
+      expect(onDeduplicate).toHaveBeenCalledWith(subsetOptions)
+    })
+
+    it(`should delay onDeduplicate until covering in-flight request completes`, async () => {
+      let resolveFirst: (() => void) | undefined
+      let callCount = 0
+      const firstPromise = new Promise<void>((resolve) => {
+        resolveFirst = () => resolve()
+      })
+
+      // First call will remain in-flight until we resolve it
+      let first = true
+      const mockLoadSubset = (_options: LoadSubsetOptions) => {
+        callCount++
+        if (first) {
+          first = false
+          return firstPromise
+        }
+        return Promise.resolve()
+      }
+
+      const onDeduplicate = vi.fn()
+      const deduplicated = new DeduplicatedLoadSubset(
+        mockLoadSubset,
+        onDeduplicate
+      )
+
+      // Start a broad in-flight request
+      const inflightOptions = { where: gt(ref(`age`), val(10)) }
+      const inflight = deduplicated.loadSubset(inflightOptions)
+      expect(inflight).toBeInstanceOf(Promise)
+      expect(callCount).toBe(1)
+
+      // Issue a subset request while first is still in-flight
+      const subsetOptions = { where: gt(ref(`age`), val(20)) }
+      const subsetPromise = deduplicated.loadSubset(subsetOptions)
+      expect(subsetPromise).toBeInstanceOf(Promise)
+
+      // onDeduplicate should NOT have fired yet
+      expect(onDeduplicate).not.toHaveBeenCalled()
+
+      // Complete the first request
+      resolveFirst?.()
+
+      // Wait for the subset promise to settle (which chains the first)
+      await subsetPromise
+
+      // Now the callback should have been called exactly once, with the subset options
+      expect(onDeduplicate).toHaveBeenCalledTimes(1)
+      expect(onDeduplicate).toHaveBeenCalledWith(subsetOptions)
+    })
+  })
 })