@tanstack/db 0.5.1 → 0.5.3

package/src/local-storage.ts

@@ -152,6 +152,43 @@ function generateUuid(): string {
   return crypto.randomUUID()
 }
 
+/**
+ * Encodes a key (string or number) into a storage-safe string format.
+ * This prevents collisions between numeric and string keys by prefixing with type information.
+ *
+ * Examples:
+ *   - number 1 → "n:1"
+ *   - string "1" → "s:1"
+ *   - string "n:1" → "s:n:1"
+ *
+ * @param key - The key to encode (string or number)
+ * @returns Type-prefixed string that is safe for storage
+ */
+function encodeStorageKey(key: string | number): string {
+  if (typeof key === `number`) {
+    return `n:${key}`
+  }
+  return `s:${key}`
+}
+
+/**
+ * Decodes a storage key back to its original form.
+ * This is the inverse of encodeStorageKey.
+ *
+ * @param encodedKey - The encoded key from storage
+ * @returns The original key (string or number)
+ */
+function decodeStorageKey(encodedKey: string): string | number {
+  if (encodedKey.startsWith(`n:`)) {
+    return Number(encodedKey.slice(2))
+  }
+  if (encodedKey.startsWith(`s:`)) {
+    return encodedKey.slice(2)
+  }
+  // Fallback for legacy data without encoding
+  return encodedKey
+}
+
 /**
  * Creates an in-memory storage implementation that mimics the StorageApi interface
  * Used as a fallback when localStorage is not available (e.g., server-side rendering)
@@ -365,7 +402,7 @@ export function localStorageCollectionOptions(
       // Convert Map to object format for storage
       const objectData: Record<string, StoredItem<any>> = {}
       dataMap.forEach((storedItem, key) => {
-        objectData[String(key)] = storedItem
+        objectData[encodeStorageKey(key)] = storedItem
       })
       const serialized = parser.stringify(objectData)
       storage.setItem(config.storageKey, serialized)
@@ -415,12 +452,11 @@ export function localStorageCollectionOptions(
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
       // Use the engine's pre-computed key for consistency
-      const key = mutation.key
       const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
-      lastKnownData.set(key, storedItem)
+      lastKnownData.set(mutation.key, storedItem)
     })
 
     // Save to storage
@@ -450,12 +486,11 @@ export function localStorageCollectionOptions(
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
       // Use the engine's pre-computed key for consistency
-      const key = mutation.key
       const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
-      lastKnownData.set(key, storedItem)
+      lastKnownData.set(mutation.key, storedItem)
     })
 
     // Save to storage
@@ -480,8 +515,7 @@ export function localStorageCollectionOptions(
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
       // Use the engine's pre-computed key for consistency
-      const key = mutation.key
-      lastKnownData.delete(key)
+      lastKnownData.delete(mutation.key)
     })
 
     // Save to storage
@@ -547,8 +581,6 @@ export function localStorageCollectionOptions(
     // Apply each mutation
     for (const mutation of collectionMutations) {
       // Use the engine's pre-computed key to avoid key derivation issues
-      const key = mutation.key
-
       switch (mutation.type) {
         case `insert`:
         case `update`: {
@@ -556,11 +588,11 @@ export function localStorageCollectionOptions(
             versionKey: generateUuid(),
             data: mutation.modified,
           }
-          lastKnownData.set(key, storedItem)
+          lastKnownData.set(mutation.key, storedItem)
           break
         }
         case `delete`: {
-          lastKnownData.delete(key)
+          lastKnownData.delete(mutation.key)
           break
         }
       }
@@ -616,7 +648,7 @@ function loadFromStorage<T extends object>(
       parsed !== null &&
       !Array.isArray(parsed)
     ) {
-      Object.entries(parsed).forEach(([key, value]) => {
+      Object.entries(parsed).forEach(([encodedKey, value]) => {
         // Runtime check to ensure the value has the expected StoredItem structure
         if (
           value &&
@@ -625,9 +657,10 @@ function loadFromStorage<T extends object>(
           `data` in value
         ) {
           const storedItem = value as StoredItem<T>
-          dataMap.set(key, storedItem)
+          const decodedKey = decodeStorageKey(encodedKey)
+          dataMap.set(decodedKey, storedItem)
         } else {
-          throw new InvalidStorageDataFormatError(storageKey, key)
+          throw new InvalidStorageDataFormatError(storageKey, encodedKey)
         }
       })
     } else {

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>>
 }