@tanstack/db 0.0.27 → 0.0.29

package/src/local-storage.ts

@@ -1,3 +1,11 @@
+import {
+  InvalidStorageDataFormatError,
+  InvalidStorageObjectFormatError,
+  NoStorageAvailableError,
+  NoStorageEventApiError,
+  SerializationError,
+  StorageKeyRequiredError,
+} from "./errors"
 import type {
   CollectionConfig,
   DeleteMutationFnParams,
@@ -136,10 +144,9 @@ function validateJsonSerializable(value: any, operation: string): void {
   try {
     JSON.stringify(value)
   } catch (error) {
-    throw new Error(
-      `Cannot ${operation} item because it cannot be JSON serialized: ${
-        error instanceof Error ? error.message : String(error)
-      }`
+    throw new SerializationError(
+      operation,
+      error instanceof Error ? error.message : String(error)
     )
   }
 }
@@ -204,7 +211,7 @@ export function localStorageCollectionOptions<
 
   // Validate required parameters
   if (!config.storageKey) {
-    throw new Error(`[LocalStorageCollection] storageKey must be provided.`)
+    throw new StorageKeyRequiredError()
   }
 
   // Default to window.localStorage if no storage is provided
@@ -213,9 +220,7 @@ export function localStorageCollectionOptions<
     (typeof window !== `undefined` ? window.localStorage : null)
 
   if (!storage) {
-    throw new Error(
-      `[LocalStorageCollection] No storage available. Please provide a storage option or ensure window.localStorage is available.`
-    )
+    throw new NoStorageAvailableError()
   }
 
   // Default to window for storage events if not provided
@@ -223,9 +228,7 @@ export function localStorageCollectionOptions<
     config.storageEventApi || (typeof window !== `undefined` ? window : null)
 
   if (!storageEventApi) {
-    throw new Error(
-      `[LocalStorageCollection] No storage event API available. Please provide a storageEventApi option or ensure window is available.`
-    )
+    throw new NoStorageEventApiError()
   }
 
   // Track the last known state to detect changes
@@ -471,15 +474,11 @@ function loadFromStorage<T extends object>(
           const storedItem = value as StoredItem<T>
           dataMap.set(key, storedItem)
         } else {
-          throw new Error(
-            `[LocalStorageCollection] Invalid data format in storage key "${storageKey}" for key "${key}".`
-          )
+          throw new InvalidStorageDataFormatError(storageKey, key)
         }
       })
     } else {
-      throw new Error(
-        `[LocalStorageCollection] Invalid data format in storage key "${storageKey}". Expected object format.`
-      )
+      throw new InvalidStorageObjectFormatError(storageKey)
     }
 
     return dataMap

package/src/query/builder/functions.ts

@@ -265,3 +265,17 @@ export function max(
 ): Aggregate<number> {
   return new Aggregate(`max`, [toExpression(arg)])
 }
+
+/**
+ * List of comparison function names that can be used with indexes
+ */
+export const comparisonFunctions = [
+  `eq`,
+  `gt`,
+  `gte`,
+  `lt`,
+  `lte`,
+  `in`,
+  `like`,
+  `ilike`,
+] as const

package/src/query/builder/index.ts

@@ -1,5 +1,12 @@
 import { CollectionImpl } from "../../collection.js"
 import { CollectionRef, QueryRef } from "../ir.js"
+import {
+  InvalidSourceError,
+  JoinConditionMustBeEqualityError,
+  OnlyOneSourceAllowedError,
+  QueryMustHaveFromClauseError,
+  SubQueryMustHaveFromClauseError,
+} from "../../errors.js"
 import { createRefProxy, isRefProxy, toExpression } from "./ref-proxy.js"
 import type { NamespacedRow } from "../../types.js"
 import type {
@@ -45,7 +52,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     context: string
   ): [string, CollectionRef | QueryRef] {
     if (Object.keys(source).length !== 1) {
-      throw new Error(`Only one source is allowed in the ${context}`)
+      throw new OnlyOneSourceAllowedError(context)
     }
 
     const alias = Object.keys(source)[0]!
@@ -58,13 +65,11 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     } else if (sourceValue instanceof BaseQueryBuilder) {
       const subQuery = sourceValue._getQuery()
       if (!(subQuery as Partial<QueryIR>).from) {
-        throw new Error(
-          `A sub query passed to a ${context} must have a from clause itself`
-        )
+        throw new SubQueryMustHaveFromClauseError(context)
       }
       ref = new QueryRef(subQuery, alias)
     } else {
-      throw new Error(`Invalid source`)
+      throw new InvalidSourceError()
     }
 
     return [alias, ref]
@@ -166,7 +171,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
       left = onExpression.args[0]!
       right = onExpression.args[1]!
     } else {
-      throw new Error(`Join condition must be an equality expression`)
+      throw new JoinConditionMustBeEqualityError()
     }
 
     const joinClause: JoinClause = {
@@ -725,7 +730,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
 
   _getQuery(): QueryIR {
     if (!this.query.from) {
-      throw new Error(`Query must have a from clause`)
+      throw new QueryMustHaveFromClauseError()
     }
     return this.query as QueryIR
   }

package/src/query/builder/ref-proxy.ts

@@ -10,6 +10,71 @@ export interface RefProxy<T = any> {
   readonly __type: T
 }
 
+/**
+ * Type for creating a RefProxy for a single row/type without namespacing
+ * Used in collection indexes and where clauses
+ */
+export type SingleRowRefProxy<T> =
+  T extends Record<string, any>
+    ? {
+        [K in keyof T]: T[K] extends Record<string, any>
+          ? SingleRowRefProxy<T[K]> & RefProxy<T[K]>
+          : RefProxy<T[K]>
+      } & RefProxy<T>
+    : RefProxy<T>
+
+/**
+ * Creates a proxy object that records property access paths for a single row
+ * Used in collection indexes and where clauses
+ */
+export function createSingleRowRefProxy<
+  T extends Record<string, any>,
+>(): SingleRowRefProxy<T> {
+  const cache = new Map<string, any>()
+
+  function createProxy(path: Array<string>): any {
+    const pathKey = path.join(`.`)
+    if (cache.has(pathKey)) {
+      return cache.get(pathKey)
+    }
+
+    const proxy = new Proxy({} as any, {
+      get(target, prop, receiver) {
+        if (prop === `__refProxy`) return true
+        if (prop === `__path`) return path
+        if (prop === `__type`) return undefined // Type is only for TypeScript inference
+        if (typeof prop === `symbol`) return Reflect.get(target, prop, receiver)
+
+        const newPath = [...path, String(prop)]
+        return createProxy(newPath)
+      },
+
+      has(target, prop) {
+        if (prop === `__refProxy` || prop === `__path` || prop === `__type`)
+          return true
+        return Reflect.has(target, prop)
+      },
+
+      ownKeys(target) {
+        return Reflect.ownKeys(target)
+      },
+
+      getOwnPropertyDescriptor(target, prop) {
+        if (prop === `__refProxy` || prop === `__path` || prop === `__type`) {
+          return { enumerable: false, configurable: true }
+        }
+        return Reflect.getOwnPropertyDescriptor(target, prop)
+      },
+    })
+
+    cache.set(pathKey, proxy)
+    return proxy
+  }
+
+  // Return the root proxy that starts with an empty path
+  return createProxy([]) as SingleRowRefProxy<T>
+}
+
 /**
  * Creates a proxy object that records property access paths
  * Used in callbacks like where, select, etc. to create type-safe references

package/src/query/compiler/evaluators.ts

@@ -1,3 +1,8 @@
+import {
+  EmptyReferencePathError,
+  UnknownExpressionTypeError,
+  UnknownFunctionError,
+} from "../../errors.js"
 import type { BasicExpression, Func, PropRef } from "../ir.js"
 import type { NamespacedRow } from "../../types.js"
 
@@ -6,11 +11,37 @@ import type { NamespacedRow } from "../../types.js"
  */
 export type CompiledExpression = (namespacedRow: NamespacedRow) => any
 
+/**
+ * Compiled single-row expression evaluator function type
+ */
+export type CompiledSingleRowExpression = (item: Record<string, unknown>) => any
+
 /**
  * Compiles an expression into an optimized evaluator function.
  * This eliminates branching during evaluation by pre-compiling the expression structure.
  */
 export function compileExpression(expr: BasicExpression): CompiledExpression {
+  const compiledFn = compileExpressionInternal(expr, false)
+  return compiledFn as CompiledExpression
+}
+
+/**
+ * Compiles a single-row expression into an optimized evaluator function.
+ */
+export function compileSingleRowExpression(
+  expr: BasicExpression
+): CompiledSingleRowExpression {
+  const compiledFn = compileExpressionInternal(expr, true)
+  return compiledFn as CompiledSingleRowExpression
+}
+
+/**
+ * Internal unified expression compiler that handles both namespaced and single-row evaluation
+ */
+function compileExpressionInternal(
+  expr: BasicExpression,
+  isSingleRow: boolean
+): (data: any) => any {
   switch (expr.type) {
     case `val`: {
       // For constant values, return a function that just returns the value
@@ -19,17 +50,17 @@ export function compileExpression(expr: BasicExpression): CompiledExpression {
     }
 
     case `ref`: {
-      // For references, pre-compile the property path navigation
-      return compileRef(expr)
+      // For references, compile based on evaluation mode
+      return isSingleRow ? compileSingleRowRef(expr) : compileRef(expr)
     }
 
     case `func`: {
-      // For functions, pre-compile the function and its arguments
-      return compileFunction(expr)
+      // For functions, use the unified compiler
+      return compileFunction(expr, isSingleRow)
     }
 
     default:
-      throw new Error(`Unknown expression type: ${(expr as any).type}`)
+      throw new UnknownExpressionTypeError((expr as any).type)
   }
 }
 
@@ -40,7 +71,7 @@ function compileRef(ref: PropRef): CompiledExpression {
   const [tableAlias, ...propertyPath] = ref.path
 
   if (!tableAlias) {
-    throw new Error(`Reference path cannot be empty`)
+    throw new EmptyReferencePathError()
   }
 
   // Pre-compile the property path navigation
@@ -75,74 +106,95 @@ function compileRef(ref: PropRef): CompiledExpression {
 }
 
 /**
- * Compiles a function expression into an optimized evaluator
+ * Compiles a reference expression for single-row evaluation
+ */
+function compileSingleRowRef(ref: PropRef): CompiledSingleRowExpression {
+  const propertyPath = ref.path
+
+  // This function works for all path lengths including empty path
+  return (item) => {
+    let value: any = item
+    for (const prop of propertyPath) {
+      if (value == null) {
+        return value
+      }
+      value = value[prop]
+    }
+    return value
+  }
+}
+
+/**
+ * Compiles a function expression for both namespaced and single-row evaluation
  */
-function compileFunction(func: Func): CompiledExpression {
-  // Pre-compile all arguments
-  const compiledArgs = func.args.map(compileExpression)
+function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
+  // Pre-compile all arguments using the appropriate compiler
+  const compiledArgs = func.args.map((arg) =>
+    compileExpressionInternal(arg, isSingleRow)
+  )
 
   switch (func.name) {
     // Comparison operators
     case `eq`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return a === b
       }
     }
     case `gt`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return a > b
       }
     }
     case `gte`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return a >= b
       }
     }
     case `lt`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return a < b
       }
     }
     case `lte`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return a <= b
       }
     }
 
     // Boolean operators
     case `and`:
-      return (namespacedRow) => {
+      return (data) => {
         for (const compiledArg of compiledArgs) {
-          if (!compiledArg(namespacedRow)) {
+          if (!compiledArg(data)) {
             return false
           }
         }
         return true
       }
     case `or`:
-      return (namespacedRow) => {
+      return (data) => {
         for (const compiledArg of compiledArgs) {
-          if (compiledArg(namespacedRow)) {
+          if (compiledArg(data)) {
             return true
           }
         }
@@ -150,16 +202,16 @@ function compileFunction(func: Func): CompiledExpression {
       }
     case `not`: {
       const arg = compiledArgs[0]!
-      return (namespacedRow) => !arg(namespacedRow)
+      return (data) => !arg(data)
     }
 
     // Array operators
     case `in`: {
       const valueEvaluator = compiledArgs[0]!
       const arrayEvaluator = compiledArgs[1]!
-      return (namespacedRow) => {
-        const value = valueEvaluator(namespacedRow)
-        const array = arrayEvaluator(namespacedRow)
+      return (data) => {
+        const value = valueEvaluator(data)
+        const array = arrayEvaluator(data)
         if (!Array.isArray(array)) {
           return false
         }
@@ -171,18 +223,18 @@ function compileFunction(func: Func): CompiledExpression {
     case `like`: {
       const valueEvaluator = compiledArgs[0]!
       const patternEvaluator = compiledArgs[1]!
-      return (namespacedRow) => {
-        const value = valueEvaluator(namespacedRow)
-        const pattern = patternEvaluator(namespacedRow)
+      return (data) => {
+        const value = valueEvaluator(data)
+        const pattern = patternEvaluator(data)
         return evaluateLike(value, pattern, false)
       }
     }
     case `ilike`: {
       const valueEvaluator = compiledArgs[0]!
       const patternEvaluator = compiledArgs[1]!
-      return (namespacedRow) => {
-        const value = valueEvaluator(namespacedRow)
-        const pattern = patternEvaluator(namespacedRow)
+      return (data) => {
+        const value = valueEvaluator(data)
+        const pattern = patternEvaluator(data)
         return evaluateLike(value, pattern, true)
       }
     }
@@ -190,22 +242,22 @@ function compileFunction(func: Func): CompiledExpression {
     // String functions
     case `upper`: {
       const arg = compiledArgs[0]!
-      return (namespacedRow) => {
-        const value = arg(namespacedRow)
+      return (data) => {
+        const value = arg(data)
         return typeof value === `string` ? value.toUpperCase() : value
       }
     }
     case `lower`: {
       const arg = compiledArgs[0]!
-      return (namespacedRow) => {
-        const value = arg(namespacedRow)
+      return (data) => {
+        const value = arg(data)
         return typeof value === `string` ? value.toLowerCase() : value
       }
     }
     case `length`: {
       const arg = compiledArgs[0]!
-      return (namespacedRow) => {
-        const value = arg(namespacedRow)
+      return (data) => {
+        const value = arg(data)
         if (typeof value === `string`) {
           return value.length
         }
@@ -216,10 +268,10 @@ function compileFunction(func: Func): CompiledExpression {
       }
     }
     case `concat`:
-      return (namespacedRow) => {
+      return (data) => {
         return compiledArgs
           .map((evaluator) => {
-            const arg = evaluator(namespacedRow)
+            const arg = evaluator(data)
             try {
               return String(arg ?? ``)
             } catch {
@@ -233,9 +285,9 @@ function compileFunction(func: Func): CompiledExpression {
           .join(``)
       }
     case `coalesce`:
-      return (namespacedRow) => {
+      return (data) => {
         for (const evaluator of compiledArgs) {
-          const value = evaluator(namespacedRow)
+          const value = evaluator(data)
           if (value !== null && value !== undefined) {
             return value
           }
@@ -247,43 +299,43 @@ function compileFunction(func: Func): CompiledExpression {
     case `add`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return (a ?? 0) + (b ?? 0)
       }
     }
     case `subtract`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return (a ?? 0) - (b ?? 0)
       }
     }
     case `multiply`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         return (a ?? 0) * (b ?? 0)
       }
     }
     case `divide`: {
       const argA = compiledArgs[0]!
       const argB = compiledArgs[1]!
-      return (namespacedRow) => {
-        const a = argA(namespacedRow)
-        const b = argB(namespacedRow)
+      return (data) => {
+        const a = argA(data)
+        const b = argB(data)
         const divisor = b ?? 0
         return divisor !== 0 ? (a ?? 0) / divisor : null
       }
     }
 
     default:
-      throw new Error(`Unknown function: ${func.name}`)
+      throw new UnknownFunctionError(func.name)
   }
 }
 

package/src/query/compiler/expressions.ts

@@ -0,0 +1,92 @@
+import { Func, PropRef, Value } from "../ir.js"
+import type { BasicExpression } 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`,
+])
+
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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
+ */
+export function convertToBasicExpression(
+  whereClause: BasicExpression<boolean>,
+  collectionAlias: string
+): BasicExpression<boolean> | null {
+  const tpe = whereClause.type
+  if (tpe === `val`) {
+    return new Value(whereClause.value)
+  } else if (tpe === `ref`) {
+    const path = whereClause.path
+    if (Array.isArray(path)) {
+      if (path[0] === collectionAlias && path.length > 1) {
+        // Remove the table alias from the path for single-collection queries
+        return new PropRef(path.slice(1))
+      } else if (path.length === 1 && path[0] !== undefined) {
+        // Single field reference
+        return new PropRef([path[0]])
+      }
+    }
+    // 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(
+        arg as BasicExpression<boolean>,
+        collectionAlias
+      )
+      if (convertedArg == null) {
+        return null
+      }
+      args.push(convertedArg)
+    }
+    return new Func(whereClause.name, args)
+  }
+}