@tanstack/db 0.4.16 → 0.4.18

package/src/query/compiler/index.ts

@@ -3,6 +3,7 @@ import { optimizeQuery } from "../optimizer.js"
 import {
   CollectionInputNotFoundError,
   DistinctRequiresSelectError,
+  DuplicateAliasInSubqueryError,
   HavingRequiresGroupByError,
   LimitOffsetRequireOrderByError,
   UnsupportedFromTypeError,
@@ -99,6 +100,11 @@ export function compileQuery(
     return cachedResult
   }
 
+  // Validate the raw query BEFORE optimization to check user's original structure.
+  // This must happen before optimization because the optimizer may create internal
+  // subqueries (e.g., for predicate pushdown) that reuse aliases, which is fine.
+  validateQueryStructure(rawQuery)
+
   // Optimize the query before compilation
   const { optimizedQuery: query, sourceWhereClauses } = optimizeQuery(rawQuery)
 
@@ -375,6 +381,74 @@ export function compileQuery(
   return compilationResult
 }
 
+/**
+ * Collects aliases used for DIRECT collection references (not subqueries).
+ * Used to validate that subqueries don't reuse parent query collection aliases.
+ * Only direct CollectionRef aliases matter - QueryRef aliases don't cause conflicts.
+ */
+function collectDirectCollectionAliases(query: QueryIR): Set<string> {
+  const aliases = new Set<string>()
+
+  // Collect FROM alias only if it's a direct collection reference
+  if (query.from.type === `collectionRef`) {
+    aliases.add(query.from.alias)
+  }
+
+  // Collect JOIN aliases only for direct collection references
+  if (query.join) {
+    for (const joinClause of query.join) {
+      if (joinClause.from.type === `collectionRef`) {
+        aliases.add(joinClause.from.alias)
+      }
+    }
+  }
+
+  return aliases
+}
+
+/**
+ * Validates the structure of a query and its subqueries.
+ * Checks that subqueries don't reuse collection aliases from parent queries.
+ * This must be called on the RAW query before optimization.
+ */
+function validateQueryStructure(
+  query: QueryIR,
+  parentCollectionAliases: Set<string> = new Set()
+): void {
+  // Collect direct collection aliases from this query level
+  const currentLevelAliases = collectDirectCollectionAliases(query)
+
+  // Check if any current alias conflicts with parent aliases
+  for (const alias of currentLevelAliases) {
+    if (parentCollectionAliases.has(alias)) {
+      throw new DuplicateAliasInSubqueryError(
+        alias,
+        Array.from(parentCollectionAliases)
+      )
+    }
+  }
+
+  // Combine parent and current aliases for checking nested subqueries
+  const combinedAliases = new Set([
+    ...parentCollectionAliases,
+    ...currentLevelAliases,
+  ])
+
+  // Recursively validate FROM subquery
+  if (query.from.type === `queryRef`) {
+    validateQueryStructure(query.from.query, combinedAliases)
+  }
+
+  // Recursively validate JOIN subqueries
+  if (query.join) {
+    for (const joinClause of query.join) {
+      if (joinClause.from.type === `queryRef`) {
+        validateQueryStructure(joinClause.from.query, combinedAliases)
+      }
+    }
+  }
+}
+
 /**
  * Processes the FROM clause, handling direct collection references and subqueries.
  * Populates `aliasToCollectionId` and `aliasRemapping` for per-alias subscription tracking.

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

@@ -179,13 +179,11 @@ export function processOrderBy(
           orderByOptimizationInfo
 
         setSizeCallback = (getSize: () => number) => {
-          optimizableOrderByCollections[followRefCollection.id] = {
-            ...optimizableOrderByCollections[followRefCollection.id]!,
-            dataNeeded: () => {
+          optimizableOrderByCollections[followRefCollection.id]![`dataNeeded`] =
+            () => {
               const size = getSize()
               return Math.max(0, orderByOptimizationInfo!.limit - size)
-            },
-          }
+            }
         }
       }
     }

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

@@ -73,29 +73,33 @@ export class CollectionSubscriber<
       )
     }
 
+    const trackLoadPromise = () => {
+      // 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!,
+        })
+        this.collectionConfigBuilder.liveQueryCollection!._sync.trackLoadPromise(
+          promise
+        )
+      }
+    }
+
+    // It can be that we are not yet subscribed when the first `loadSubset` call happens (i.e. the initial query).
+    // So we also check the status here and if it's `loadingSubset` then we track the load promise
+    if (subscription.status === `loadingSubset`) {
+      trackLoadPromise()
+    }
+
     // Subscribe to subscription status changes to propagate loading state
     const statusUnsubscribe = subscription.on(`status:change`, (event) => {
-      // TODO: For now we are setting this loading state whenever the subscription
-      // status changes to 'loadingSubset'. But we have discussed it only happening
-      // when the the live query has it's offset/limit changed, and that triggers the
-      // subscription to request a snapshot. This will require more work to implement,
-      // and builds on https://github.com/TanStack/db/pull/663 which this PR
-      // does not yet depend on.
       if (event.status === `loadingSubset`) {
-        // 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!,
-          })
-          this.collectionConfigBuilder.liveQueryCollection!._sync.trackLoadPromise(
-            promise
-          )
-        }
+        trackLoadPromise()
       } else {
         // status is 'ready'
         const deferred = this.subscriptionLoadingPromises.get(subscription)
@@ -176,30 +180,14 @@ export class CollectionSubscriber<
     whereExpression: BasicExpression<boolean> | undefined,
     orderByInfo: OrderByOptimizationInfo
   ) {
-    const { orderBy, offset, limit, comparator, dataNeeded, index } =
-      orderByInfo
+    const { orderBy, offset, limit, index } = orderByInfo
 
     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 (and if later we need more data, we will dynamically load more data)
       const splittedChanges = splitUpdates(changes)
-      let filteredChanges = splittedChanges
-      if (dataNeeded && dataNeeded() === 0) {
-        // If the topK is full [..., maxSentValue] then we do not need to send changes > maxSentValue
-        // because they can never make it into the topK.
-        // However, if the topK isn't full yet, we need to also send changes > maxSentValue
-        // because they will make it into the topK
-        filteredChanges = filterChangesSmallerOrEqualToMax(
-          splittedChanges,
-          comparator,
-          this.biggest
-        )
-      }
-
-      this.sendChangesToPipelineWithTracking(filteredChanges, subscription)
+      this.sendChangesToPipelineWithTracking(splittedChanges, subscription)
     }
 
     // Subscribe to changes and only send changes that are smaller than the biggest value we've sent so far
@@ -395,37 +383,3 @@ function* splitUpdates<
     }
   }
 }
-
-function* filterChanges<
-  T extends object = Record<string, unknown>,
-  TKey extends string | number = string | number,
->(
-  changes: Iterable<ChangeMessage<T, TKey>>,
-  f: (change: ChangeMessage<T, TKey>) => boolean
-): Generator<ChangeMessage<T, TKey>> {
-  for (const change of changes) {
-    if (f(change)) {
-      yield change
-    }
-  }
-}
-
-/**
- * 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)
- * @returns Iterable of changes that fall within the range
- */
-function* filterChangesSmallerOrEqualToMax<
-  T extends object = Record<string, unknown>,
-  TKey extends string | number = string | number,
->(
-  changes: Iterable<ChangeMessage<T, TKey>>,
-  comparator: (a: any, b: any) => number,
-  maxValue: any
-): Generator<ChangeMessage<T, TKey>> {
-  yield* filterChanges(changes, (change) => {
-    return !maxValue || comparator(change.value, maxValue) <= 0
-  })
-}

package/src/strategies/debounceStrategy.ts

@@ -14,7 +14,10 @@ import type { Transaction } from "../transactions"
  *
  * @example
  * ```ts
- * const mutate = useSerializedTransaction({
+ * const mutate = usePacedMutations({
+ *   onMutate: (value) => {
+ *     collection.update(id, draft => { draft.value = value })
+ *   },
  *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },

package/src/strategies/throttleStrategy.ts

@@ -16,7 +16,10 @@ import type { Transaction } from "../transactions"
  * @example
  * ```ts
  * // Throttle slider updates to every 200ms
- * const mutate = useSerializedTransaction({
+ * const mutate = usePacedMutations({
+ *   onMutate: (volume) => {
+ *     settingsCollection.update('volume', draft => { draft.value = volume })
+ *   },
  *   mutationFn: async ({ transaction }) => {
  *     await api.updateVolume(transaction.mutations)
  *   },
@@ -27,7 +30,10 @@ import type { Transaction } from "../transactions"
  * @example
  * ```ts
  * // Throttle with leading and trailing execution
- * const mutate = useSerializedTransaction({
+ * const mutate = usePacedMutations({
+ *   onMutate: (data) => {
+ *     collection.update(id, draft => { Object.assign(draft, data) })
+ *   },
  *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },

package/src/transactions.ts

@@ -1,4 +1,5 @@
 import { createDeferred } from "./deferred"
+import "./duplicate-instance-check"
 import {
   MissingMutationFunctionError,
   TransactionAlreadyCompletedRollbackError,
@@ -244,7 +245,9 @@ class Transaction<T extends object = Record<string, unknown>> {
 
   /**
    * Execute collection operations within this transaction
-   * @param callback - Function containing collection operations to group together
+   * @param callback - Function containing collection operations to group together. If the
+   * callback returns a Promise, the transaction context will remain active until the promise
+   * settles, allowing optimistic writes after `await` boundaries.
    * @returns This transaction for chaining
    * @example
    * // Group multiple operations
@@ -287,6 +290,7 @@ class Transaction<T extends object = Record<string, unknown>> {
     }
 
     registerTransaction(this)
+
     try {
       callback()
     } finally {

package/src/utils/type-guards.ts

@@ -0,0 +1,12 @@
+/**
+ * Type guard to check if a value is promise-like (has a `.then` method)
+ * @param value - The value to check
+ * @returns True if the value is promise-like, false otherwise
+ */
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    !!value &&
+    (typeof value === `object` || typeof value === `function`) &&
+    typeof (value as { then?: unknown }).then === `function`
+  )
+}