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,15 @@ import type { LoadSubsetOptions } from "../types.js"
  * Tracks what data has been loaded and avoids redundant calls by applying
  * subset logic to predicates.
  *
+ * @param opts - The options for the DeduplicatedLoadSubset
+ * @param opts.loadSubset - The underlying loadSubset function to wrap
+ * @param opts.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({ loadSubset: myLoadSubset, onDeduplicate: (opts) => console.log(`Call was deduplicated:`, opts) })
  *
  * // First call - fetches data
  * await dedupe.loadSubset({ where: gt(ref('age'), val(10)) })
@@ -30,6 +37,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
 
@@ -52,10 +64,12 @@ export class DeduplicatedLoadSubset {
   // check if their captured generation matches before updating tracking state
   private generation = 0
 
-  constructor(
+  constructor(opts: {
     loadSubset: (options: LoadSubsetOptions) => true | Promise<void>
-  ) {
-    this._loadSubset = loadSubset
+    onDeduplicate?: (options: LoadSubsetOptions) => void
+  }) {
+    this._loadSubset = opts.loadSubset
+    this.onDeduplicate = opts.onDeduplicate
   }
 
   /**
@@ -71,13 +85,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 +105,7 @@ export class DeduplicatedLoadSubset {
       )
 
       if (alreadyLoaded) {
+        this.onDeduplicate?.(options)
         return true // Already loaded
       }
     }
@@ -103,7 +120,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 {