@tanstack/db 0.4.19 → 0.5.0

package/src/query/builder/index.ts

@@ -469,11 +469,11 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
 
     const opts: CompareOptions =
       typeof options === `string`
-        ? { direction: options, nulls: `first`, stringSort: `locale` }
+        ? { direction: options, nulls: `first` }
         : {
             direction: options.direction ?? `asc`,
             nulls: options.nulls ?? `first`,
-            stringSort: options.stringSort ?? `locale`,
+            stringSort: options.stringSort,
             locale:
               options.stringSort === `locale` ? options.locale : undefined,
             localeOptions:

package/src/query/builder/types.ts

@@ -1,5 +1,5 @@
 import type { CollectionImpl } from "../../collection/index.js"
-import type { SingleResult } from "../../types.js"
+import type { SingleResult, StringCollationConfig } from "../../types.js"
 import type {
   Aggregate,
   BasicExpression,
@@ -303,26 +303,7 @@ export type OrderByCallback<TContext extends Context> = (
 export type OrderByOptions = {
   direction?: OrderByDirection
   nulls?: `first` | `last`
-} & StringSortOpts
-
-/**
- * StringSortOpts - Options for string sorting behavior
- *
- * This discriminated union allows for two types of string sorting:
- * - **Lexical**: Simple character-by-character comparison (default)
- * - **Locale**: Locale-aware sorting with optional customization
- *
- * The union ensures that locale options are only available when locale sorting is selected.
- */
-export type StringSortOpts =
-  | {
-      stringSort?: `lexical`
-    }
-  | {
-      stringSort?: `locale`
-      locale?: string
-      localeOptions?: object
-    }
+} & StringCollationConfig
 
 /**
  * CompareOptions - Final resolved options for comparison operations
@@ -331,12 +312,9 @@ export type StringSortOpts =
  * to their concrete values. Unlike OrderByOptions, all fields are required
  * since defaults have been applied.
  */
-export type CompareOptions = {
+export type CompareOptions = StringCollationConfig & {
   direction: OrderByDirection
   nulls: `first` | `last`
-  stringSort: `lexical` | `locale`
-  locale?: string
-  localeOptions?: object
 }
 
 /**
@@ -530,6 +508,20 @@ export type RefLeaf<T = any> = { readonly [RefBrand]?: T }
 type WithoutRefBrand<T> =
   T extends Record<string, any> ? Omit<T, typeof RefBrand> : T
 
+/**
+ * PreserveSingleResultFlag - Conditionally includes the singleResult flag
+ *
+ * This helper type ensures the singleResult flag is only added to the context when it's
+ * explicitly true. It uses a non-distributive conditional (tuple wrapper) to prevent
+ * unexpected behavior when TFlag is a union type.
+ *
+ * @template TFlag - The singleResult flag value to check
+ * @returns { singleResult: true } if TFlag is true, otherwise {}
+ */
+type PreserveSingleResultFlag<TFlag> = [TFlag] extends [true]
+  ? { singleResult: true }
+  : {}
+
 /**
  * MergeContextWithJoinType - Creates a new context after a join operation
  *
@@ -551,6 +543,7 @@ type WithoutRefBrand<T> =
  * - `hasJoins`: Set to true
  * - `joinTypes`: Updated to track this join type
  * - `result`: Preserved from previous operations
+ * - `singleResult`: Preserved only if already true (via PreserveSingleResultFlag)
  */
 export type MergeContextWithJoinType<
   TContext extends Context,
@@ -574,8 +567,7 @@ export type MergeContextWithJoinType<
     [K in keyof TNewSchema & string]: TJoinType
   }
   result: TContext[`result`]
-  singleResult: TContext[`singleResult`] extends true ? true : false
-}
+} & PreserveSingleResultFlag<TContext[`singleResult`]>
 
 /**
  * ApplyJoinOptionalityToMergedSchema - Applies optionality rules when merging schemas

package/src/query/compiler/evaluators.ts

@@ -3,10 +3,33 @@ import {
   UnknownExpressionTypeError,
   UnknownFunctionError,
 } from "../../errors.js"
-import { normalizeValue } from "../../utils/comparison.js"
+import { areValuesEqual, normalizeValue } from "../../utils/comparison.js"
 import type { BasicExpression, Func, PropRef } from "../ir.js"
 import type { NamespacedRow } from "../../types.js"
 
+/**
+ * Helper function to check if a value is null or undefined (represents UNKNOWN in 3-valued logic)
+ */
+function isUnknown(value: any): boolean {
+  return value === null || value === undefined
+}
+
+/**
+ * Converts a 3-valued logic result to a boolean for use in WHERE/HAVING filters.
+ * In SQL, UNKNOWN (null) values in WHERE clauses exclude rows, matching false behavior.
+ *
+ * @param result - The 3-valued logic result: true, false, or null (UNKNOWN)
+ * @returns true only if result is explicitly true, false otherwise
+ *
+ * Truth table:
+ * - true → true (include row)
+ * - false → false (exclude row)
+ * - null (UNKNOWN) → false (exclude row, matching SQL behavior)
+ */
+export function toBooleanPredicate(result: boolean | null): boolean {
+  return result === true
+}
+
 /**
  * Compiled expression evaluator function type
  */
@@ -145,7 +168,12 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const a = normalizeValue(argA(data))
         const b = normalizeValue(argB(data))
-        return a === b
+        // In 3-valued logic, any comparison with null/undefined returns UNKNOWN
+        if (isUnknown(a) || isUnknown(b)) {
+          return null
+        }
+        // Use areValuesEqual for proper Uint8Array/Buffer comparison
+        return areValuesEqual(a, b)
       }
     }
     case `gt`: {
@@ -154,6 +182,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const a = argA(data)
         const b = argB(data)
+        // In 3-valued logic, any comparison with null/undefined returns UNKNOWN
+        if (isUnknown(a) || isUnknown(b)) {
+          return null
+        }
         return a > b
       }
     }
@@ -163,6 +195,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const a = argA(data)
         const b = argB(data)
+        // In 3-valued logic, any comparison with null/undefined returns UNKNOWN
+        if (isUnknown(a) || isUnknown(b)) {
+          return null
+        }
         return a >= b
       }
     }
@@ -172,6 +208,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const a = argA(data)
         const b = argB(data)
+        // In 3-valued logic, any comparison with null/undefined returns UNKNOWN
+        if (isUnknown(a) || isUnknown(b)) {
+          return null
+        }
         return a < b
       }
     }
@@ -181,6 +221,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const a = argA(data)
         const b = argB(data)
+        // In 3-valued logic, any comparison with null/undefined returns UNKNOWN
+        if (isUnknown(a) || isUnknown(b)) {
+          return null
+        }
         return a <= b
       }
     }
@@ -188,25 +232,67 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
     // Boolean operators
     case `and`:
       return (data) => {
+        // 3-valued logic for AND:
+        // - false AND anything = false (short-circuit)
+        // - null AND false = false
+        // - null AND anything (except false) = null
+        // - anything (except false) AND null = null
+        // - true AND true = true
+        let hasUnknown = false
         for (const compiledArg of compiledArgs) {
-          if (!compiledArg(data)) {
+          const result = compiledArg(data)
+          if (result === false) {
             return false
           }
+          if (isUnknown(result)) {
+            hasUnknown = true
+          }
+        }
+        // If we got here, no operand was false
+        // If any operand was null, return null (UNKNOWN)
+        if (hasUnknown) {
+          return null
         }
+
         return true
       }
     case `or`:
       return (data) => {
+        // 3-valued logic for OR:
+        // - true OR anything = true (short-circuit)
+        // - null OR anything (except true) = null
+        // - false OR false = false
+        let hasUnknown = false
         for (const compiledArg of compiledArgs) {
-          if (compiledArg(data)) {
+          const result = compiledArg(data)
+          if (result === true) {
             return true
           }
+          if (isUnknown(result)) {
+            hasUnknown = true
+          }
+        }
+        // If we got here, no operand was true
+        // If any operand was null, return null (UNKNOWN)
+        if (hasUnknown) {
+          return null
         }
+
         return false
       }
     case `not`: {
       const arg = compiledArgs[0]!
-      return (data) => !arg(data)
+      return (data) => {
+        // 3-valued logic for NOT:
+        // - NOT null = null
+        // - NOT true = false
+        // - NOT false = true
+        const result = arg(data)
+        if (isUnknown(result)) {
+          return null
+        }
+        return !result
+      }
     }
 
     // Array operators
@@ -216,6 +302,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const value = valueEvaluator(data)
         const array = arrayEvaluator(data)
+        // In 3-valued logic, if the value is null/undefined, return UNKNOWN
+        if (isUnknown(value)) {
+          return null
+        }
         if (!Array.isArray(array)) {
           return false
         }
@@ -230,6 +320,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const value = valueEvaluator(data)
         const pattern = patternEvaluator(data)
+        // In 3-valued logic, if value or pattern is null/undefined, return UNKNOWN
+        if (isUnknown(value) || isUnknown(pattern)) {
+          return null
+        }
         return evaluateLike(value, pattern, false)
       }
     }
@@ -239,6 +333,10 @@ function compileFunction(func: Func, isSingleRow: boolean): (data: any) => any {
       return (data) => {
         const value = valueEvaluator(data)
         const pattern = patternEvaluator(data)
+        // In 3-valued logic, if value or pattern is null/undefined, return UNKNOWN
+        if (isUnknown(value) || isUnknown(pattern)) {
+          return null
+        }
         return evaluateLike(value, pattern, true)
       }
     }

package/src/query/compiler/expressions.ts

@@ -15,6 +15,9 @@ export const SUPPORTED_COLLECTION_FUNCS = new Set([
   `and`,
   `or`,
   `in`,
+  `isNull`,
+  `isUndefined`,
+  `not`,
 ])
 
 /**

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

@@ -6,7 +6,7 @@ import {
   UnknownHavingExpressionTypeError,
   UnsupportedAggregateFunctionError,
 } from "../../errors.js"
-import { compileExpression } from "./evaluators.js"
+import { compileExpression, toBooleanPredicate } from "./evaluators.js"
 import type {
   Aggregate,
   BasicExpression,
@@ -140,7 +140,7 @@ export function processGroupBy(
           filter(([, row]) => {
             // Create a namespaced row structure for HAVING evaluation
             const namespacedRow = { result: (row as any).__select_results }
-            return compiledHaving(namespacedRow)
+            return toBooleanPredicate(compiledHaving(namespacedRow))
           })
         )
       }
@@ -153,7 +153,7 @@ export function processGroupBy(
           filter(([, row]) => {
             // Create a namespaced row structure for functional HAVING evaluation
             const namespacedRow = { result: (row as any).__select_results }
-            return fnHaving(namespacedRow)
+            return toBooleanPredicate(fnHaving(namespacedRow))
           })
         )
       }
@@ -288,7 +288,7 @@ export function processGroupBy(
         filter(([, row]) => {
           // Create a namespaced row structure for functional HAVING evaluation
           const namespacedRow = { result: (row as any).__select_results }
-          return fnHaving(namespacedRow)
+          return toBooleanPredicate(fnHaving(namespacedRow))
         })
       )
     }

package/src/query/compiler/index.ts

@@ -9,7 +9,7 @@ import {
   UnsupportedFromTypeError,
 } from "../../errors.js"
 import { PropRef, Value as ValClass, getWhereExpression } from "../ir.js"
-import { compileExpression } from "./evaluators.js"
+import { compileExpression, toBooleanPredicate } from "./evaluators.js"
 import { processJoins } from "./joins.js"
 import { processGroupBy } from "./group-by.js"
 import { processOrderBy } from "./order-by.js"
@@ -195,7 +195,7 @@ export function compileQuery(
       const compiledWhere = compileExpression(whereExpression)
       pipeline = pipeline.pipe(
         filter(([_key, namespacedRow]) => {
-          return compiledWhere(namespacedRow)
+          return toBooleanPredicate(compiledWhere(namespacedRow))
         })
       )
     }
@@ -206,7 +206,7 @@ export function compileQuery(
     for (const fnWhere of query.fnWhere) {
       pipeline = pipeline.pipe(
         filter(([_key, namespacedRow]) => {
-          return fnWhere(namespacedRow)
+          return toBooleanPredicate(fnWhere(namespacedRow))
         })
       )
     }

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

@@ -5,10 +5,15 @@ import { ensureIndexForField } from "../../indexes/auto-index.js"
 import { findIndexForField } from "../../utils/index-optimization.js"
 import { compileExpression } from "./evaluators.js"
 import { replaceAggregatesByRefs } from "./group-by.js"
+import type { CompareOptions } from "../builder/types.js"
 import type { WindowOptions } from "./types.js"
 import type { CompiledSingleRowExpression } from "./evaluators.js"
 import type { OrderBy, OrderByClause, QueryIR, Select } from "../ir.js"
-import type { NamespacedAndKeyedStream, NamespacedRow } from "../../types.js"
+import type {
+  CollectionLike,
+  NamespacedAndKeyedStream,
+  NamespacedRow,
+} from "../../types.js"
 import type { IStreamBuilder, KeyValue } from "@tanstack/db-ivm"
 import type { IndexInterface } from "../../indexes/base-index.js"
 import type { Collection } from "../../collection/index.js"
@@ -50,9 +55,10 @@ export function processOrderBy(
       selectClause,
       `__select_results`
     )
+
     return {
       compiledExpression: compileExpression(clauseWithoutAggregates),
-      compareOptions: clause.compareOptions,
+      compareOptions: buildCompareOptions(clause, collection),
     }
   })
 
@@ -87,7 +93,7 @@ export function processOrderBy(
       const arrayA = a as Array<unknown>
       const arrayB = b as Array<unknown>
       for (let i = 0; i < orderByClause.length; i++) {
-        const clause = orderByClause[i]!
+        const clause = compiledOrderBy[i]!
         const compareFn = makeComparator(clause.compareOptions)
         const result = compareFn(arrayA[i], arrayB[i])
         if (result !== 0) {
@@ -99,7 +105,7 @@ export function processOrderBy(
 
     // Single property comparison
     if (orderByClause.length === 1) {
-      const clause = orderByClause[0]!
+      const clause = compiledOrderBy[0]!
       const compareFn = makeComparator(clause.compareOptions)
       return compareFn(a, b)
     }
@@ -127,12 +133,13 @@ export function processOrderBy(
 
       const followRefCollection = followRefResult.collection
       const fieldName = followRefResult.path[0]
+      const compareOpts = buildCompareOptions(clause, followRefCollection)
       if (fieldName) {
         ensureIndexForField(
           fieldName,
           followRefResult.path,
           followRefCollection,
-          clause.compareOptions,
+          compareOpts,
           compare
         )
       }
@@ -153,9 +160,9 @@ export function processOrderBy(
 
       const index: IndexInterface<string | number> | undefined =
         findIndexForField(
-          followRefCollection.indexes,
+          followRefCollection,
           followRefResult.path,
-          clause.compareOptions
+          compareOpts
         )
 
       if (index && index.supports(`gt`)) {
@@ -217,3 +224,22 @@ export function processOrderBy(
     // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format
   )
 }
+
+/**
+ * Builds a comparison configuration object that uses the values provided in the orderBy clause.
+ * If no string sort configuration is provided it defaults to the collection's string sort configuration.
+ */
+export function buildCompareOptions(
+  clause: OrderByClause,
+  collection: CollectionLike<any, any>
+): CompareOptions {
+  if (clause.compareOptions.stringSort !== undefined) {
+    return clause.compareOptions
+  }
+
+  return {
+    ...collection.compareOptions,
+    direction: clause.compareOptions.direction,
+    nulls: clause.compareOptions.nulls,
+  }
+}