@tanstack/db 0.5.2 → 0.5.3

package/dist/esm/types.d.ts

@@ -89,7 +89,26 @@ export type NonEmptyArray<T> = [T, ...Array<T>];
  * Utility type for a Transaction with at least one mutation
  * This is used internally by the Transaction.commit method
  */
-export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Transaction<T> & {
+export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Omit<Transaction<T>, `mutations`> & {
+    /**
+     * We must omit the `mutations` property from `Transaction<T>` before intersecting
+     * because TypeScript intersects property types when the same property appears on
+     * both sides of an intersection.
+     *
+     * Without `Omit`:
+     * - `Transaction<T>` has `mutations: Array<PendingMutation<T>>`
+     * - The intersection would create: `Array<PendingMutation<T>> & NonEmptyArray<PendingMutation<T, TOperation>>`
+     * - When mapping over this array, TypeScript widens `TOperation` from the specific literal
+     *   (e.g., `"delete"`) to the union `OperationType` (`"insert" | "update" | "delete"`)
+     * - This causes `PendingMutation<T, OperationType>` to evaluate the conditional type
+     *   `original: TOperation extends 'insert' ? {} : T` as `{} | T` instead of just `T`
+     *
+     * With `Omit`:
+     * - We remove `mutations` from `Transaction<T>` first
+     * - Then add back `mutations: NonEmptyArray<PendingMutation<T, TOperation>>`
+     * - TypeScript can properly narrow `TOperation` to the specific literal type
+     * - This ensures `mutation.original` is correctly typed as `T` (not `{} | T`) when mapping
+     */
     mutations: NonEmptyArray<PendingMutation<T, TOperation>>;
 };
 export interface TransactionConfig<T extends object = Record<string, unknown>> {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/pacer": "^0.16.3",

package/src/query/compiler/expressions.ts

@@ -2,61 +2,26 @@ import { Func, PropRef, Value } from "../ir.js"
 import type { BasicExpression, OrderBy } from "../ir.js"
 
 /**
- * Functions supported by the collection index system.
- * These are the only functions that can be used in WHERE clauses
- * that are pushed down to collection subscriptions for index optimization.
- */
-export const SUPPORTED_COLLECTION_FUNCS = new Set([
-  `eq`,
-  `gt`,
-  `lt`,
-  `gte`,
-  `lte`,
-  `and`,
-  `or`,
-  `in`,
-  `isNull`,
-  `isUndefined`,
-  `not`,
-])
-
-/**
- * Determines if a WHERE clause can be converted to collection-compatible BasicExpression format.
- * This checks if the expression only uses functions supported by the collection index system.
+ * Normalizes a WHERE clause expression by removing table aliases from property references.
  *
- * @param whereClause - The WHERE clause to check
- * @returns True if the clause can be converted for collection index optimization
- */
-export function isConvertibleToCollectionFilter(
-  whereClause: BasicExpression<boolean>
-): boolean {
-  const tpe = whereClause.type
-  if (tpe === `func`) {
-    // Check if this function is supported
-    if (!SUPPORTED_COLLECTION_FUNCS.has(whereClause.name)) {
-      return false
-    }
-    // Recursively check all arguments
-    return whereClause.args.every((arg) =>
-      isConvertibleToCollectionFilter(arg as BasicExpression<boolean>)
-    )
-  }
-  return [`val`, `ref`].includes(tpe)
-}
-
-/**
- * Converts a WHERE clause to BasicExpression format compatible with collection indexes.
- * This function creates proper BasicExpression class instances that the collection
- * index system can understand.
+ * This function recursively traverses an expression tree and creates new BasicExpression
+ * instances with normalized paths. The main transformation is removing the collection alias
+ * from property reference paths (e.g., `['user', 'id']` becomes `['id']` when `collectionAlias`
+ * is `'user'`), which is needed when converting query-level expressions to collection-level
+ * expressions for subscriptions.
  *
- * @param whereClause - The WHERE clause to convert
- * @param collectionAlias - The alias of the collection being filtered
- * @returns The converted BasicExpression or null if conversion fails
+ * @param whereClause - The WHERE clause expression to normalize
+ * @param collectionAlias - The alias of the collection being filtered (to strip from paths)
+ * @returns A new BasicExpression with normalized paths
+ *
+ * @example
+ * // Input: ref with path ['user', 'id'] where collectionAlias is 'user'
+ * // Output: ref with path ['id']
  */
-export function convertToBasicExpression(
+export function normalizeExpressionPaths(
   whereClause: BasicExpression<boolean>,
   collectionAlias: string
-): BasicExpression<boolean> | null {
+): BasicExpression<boolean> {
   const tpe = whereClause.type
   if (tpe === `val`) {
     return new Value(whereClause.value)
@@ -74,42 +39,29 @@ export function convertToBasicExpression(
     // Fallback for non-array paths
     return new PropRef(Array.isArray(path) ? path : [String(path)])
   } else {
-    // Check if this function is supported
-    if (!SUPPORTED_COLLECTION_FUNCS.has(whereClause.name)) {
-      return null
-    }
     // Recursively convert all arguments
     const args: Array<BasicExpression> = []
     for (const arg of whereClause.args) {
-      const convertedArg = convertToBasicExpression(
+      const convertedArg = normalizeExpressionPaths(
         arg as BasicExpression<boolean>,
         collectionAlias
       )
-      if (convertedArg == null) {
-        return null
-      }
       args.push(convertedArg)
     }
     return new Func(whereClause.name, args)
   }
 }
 
-export function convertOrderByToBasicExpression(
+export function normalizeOrderByPaths(
   orderBy: OrderBy,
   collectionAlias: string
 ): OrderBy {
   const normalizedOrderBy = orderBy.map((clause) => {
-    const basicExp = convertToBasicExpression(
+    const basicExp = normalizeExpressionPaths(
       clause.expression,
       collectionAlias
     )
 
-    if (!basicExp) {
-      throw new Error(
-        `Failed to convert orderBy expression to a basic expression: ${clause.expression}`
-      )
-    }
-
     return {
       ...clause,
       expression: basicExp,

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

@@ -1,9 +1,8 @@
 import { MultiSet } from "@tanstack/db-ivm"
 import {
-  convertOrderByToBasicExpression,
-  convertToBasicExpression,
+  normalizeExpressionPaths,
+  normalizeOrderByPaths,
 } from "../compiler/expressions.js"
-import { WhereClauseConversionError } from "../../errors.js"
 import type { MultiSetArray, RootStreamBuilder } from "@tanstack/db-ivm"
 import type { Collection } from "../../collection/index.js"
 import type { ChangeMessage } from "../../types.js"
@@ -41,13 +40,8 @@ export class CollectionSubscriber<
     const whereClause = this.getWhereClauseForAlias()
 
     if (whereClause) {
-      const whereExpression = convertToBasicExpression(whereClause, this.alias)
-
-      if (whereExpression) {
-        return this.subscribeToChanges(whereExpression)
-      }
-
-      throw new WhereClauseConversionError(this.collectionId, this.alias)
+      const whereExpression = normalizeExpressionPaths(whereClause, this.alias)
+      return this.subscribeToChanges(whereExpression)
     }
 
     return this.subscribeToChanges()
@@ -199,10 +193,7 @@ export class CollectionSubscriber<
     subscription.setOrderByIndex(index)
 
     // Normalize the orderBy clauses such that the references are relative to the collection
-    const normalizedOrderBy = convertOrderByToBasicExpression(
-      orderBy,
-      this.alias
-    )
+    const normalizedOrderBy = normalizeOrderByPaths(orderBy, this.alias)
 
     // 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[
@@ -289,10 +280,7 @@ export class CollectionSubscriber<
       : biggestSentRow
 
     // Normalize the orderBy clauses such that the references are relative to the collection
-    const normalizedOrderBy = convertOrderByToBasicExpression(
-      orderBy,
-      this.alias
-    )
+    const normalizedOrderBy = normalizeOrderByPaths(orderBy, this.alias)
 
     // Take the `n` items after the biggest sent value
     subscription.requestLimitedSnapshot({

package/src/query/optimizer.ts

@@ -131,7 +131,6 @@ import {
   getWhereExpression,
   isResidualWhere,
 } from "./ir.js"
-import { isConvertibleToCollectionFilter } from "./compiler/expressions.js"
 import type { BasicExpression, From, QueryIR, Select, Where } from "./ir.js"
 
 /**
@@ -248,14 +247,10 @@ function extractSourceWhereClauses(
   const groupedClauses = groupWhereClauses(analyzedClauses)
 
   // Only include single-source clauses that reference collections directly
-  // and can be converted to BasicExpression format for collection indexes
   for (const [sourceAlias, whereClause] of groupedClauses.singleSource) {
     // Check if this source alias corresponds to a collection reference
     if (isCollectionReference(query, sourceAlias)) {
-      // Check if the WHERE clause can be converted to collection-compatible format
-      if (isConvertibleToCollectionFilter(whereClause)) {
-        sourceWhereClauses.set(sourceAlias, whereClause)
-      }
+      sourceWhereClauses.set(sourceAlias, whereClause)
     }
   }
 

package/src/types.ts

@@ -139,7 +139,26 @@ export type NonEmptyArray<T> = [T, ...Array<T>]
 export type TransactionWithMutations<
   T extends object = Record<string, unknown>,
   TOperation extends OperationType = OperationType,
-> = Transaction<T> & {
+> = Omit<Transaction<T>, `mutations`> & {
+  /**
+   * We must omit the `mutations` property from `Transaction<T>` before intersecting
+   * because TypeScript intersects property types when the same property appears on
+   * both sides of an intersection.
+   *
+   * Without `Omit`:
+   * - `Transaction<T>` has `mutations: Array<PendingMutation<T>>`
+   * - The intersection would create: `Array<PendingMutation<T>> & NonEmptyArray<PendingMutation<T, TOperation>>`
+   * - When mapping over this array, TypeScript widens `TOperation` from the specific literal
+   *   (e.g., `"delete"`) to the union `OperationType` (`"insert" | "update" | "delete"`)
+   * - This causes `PendingMutation<T, OperationType>` to evaluate the conditional type
+   *   `original: TOperation extends 'insert' ? {} : T` as `{} | T` instead of just `T`
+   *
+   * With `Omit`:
+   * - We remove `mutations` from `Transaction<T>` first
+   * - Then add back `mutations: NonEmptyArray<PendingMutation<T, TOperation>>`
+   * - TypeScript can properly narrow `TOperation` to the specific literal type
+   * - This ensures `mutation.original` is correctly typed as `T` (not `{} | T`) when mapping
+   */
   mutations: NonEmptyArray<PendingMutation<T, TOperation>>
 }