@tanstack/db 0.5.20 → 0.5.22

package/dist/esm/types.d.ts

@@ -247,7 +247,14 @@ export type SyncConfigRes = {
 export interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     sync: (params: {
         collection: Collection<T, TKey, any, any, any>;
-        begin: () => void;
+        /**
+         * Begin a new sync transaction.
+         * @param options.immediate - When true, the transaction will be processed immediately
+         *   even if there are persisting user transactions. Used by manual write operations.
+         */
+        begin: (options?: {
+            immediate?: boolean;
+        }) => void;
         write: (message: ChangeMessageOrDeleteKeyMessage<T, TKey>) => void;
         commit: () => void;
         markReady: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db",
-  "version": "0.5.20",
+  "version": "0.5.22",
   "description": "A reactive client store for building super fast apps on sync",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -39,7 +39,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/pacer-lite": "^0.2.0",
-    "@tanstack/db-ivm": "0.1.16"
+    "@tanstack/db-ivm": "0.1.17"
   },
   "peerDependencies": {
     "typescript": ">=4.7"

package/src/collection/lifecycle.ts

@@ -180,8 +180,10 @@ export class CollectionLifecycleManager<
 
     const gcTime = this.config.gcTime ?? 300000 // 5 minutes default
 
-    // If gcTime is 0, GC is disabled
-    if (gcTime === 0) {
+    // If gcTime is 0, negative, or non-finite (Infinity, -Infinity, NaN), GC is disabled.
+    // Note: setTimeout with Infinity coerces to 0 via ToInt32, causing immediate GC,
+    // so we must explicitly check for non-finite values here.
+    if (gcTime <= 0 || !Number.isFinite(gcTime)) {
       return
     }
 

package/src/collection/state.ts

@@ -25,6 +25,12 @@ interface PendingSyncedTransaction<
     upserts: Map<TKey, T>
     deletes: Set<TKey>
   }
+  /**
+   * When true, this transaction should be processed immediately even if there
+   * are persisting user transactions. Used by manual write operations (writeInsert,
+   * writeUpdate, writeDelete, writeUpsert) which need synchronous updates to syncedData.
+   */
+  immediate?: boolean
 }
 
 export class CollectionStateManager<
@@ -437,13 +443,17 @@ export class CollectionStateManager<
       committedSyncedTransactions,
       uncommittedSyncedTransactions,
       hasTruncateSync,
+      hasImmediateSync,
     } = this.pendingSyncedTransactions.reduce(
       (acc, t) => {
         if (t.committed) {
           acc.committedSyncedTransactions.push(t)
-          if (t.truncate === true) {
+          if (t.truncate) {
             acc.hasTruncateSync = true
           }
+          if (t.immediate) {
+            acc.hasImmediateSync = true
+          }
         } else {
           acc.uncommittedSyncedTransactions.push(t)
         }
@@ -457,10 +467,21 @@ export class CollectionStateManager<
           PendingSyncedTransaction<TOutput, TKey>
         >,
         hasTruncateSync: false,
+        hasImmediateSync: false,
       },
     )
 
-    if (!hasPersistingTransaction || hasTruncateSync) {
+    // Process committed transactions if:
+    // 1. No persisting user transaction (normal sync flow), OR
+    // 2. There's a truncate operation (must be processed immediately), OR
+    // 3. There's an immediate transaction (manual writes must be processed synchronously)
+    //
+    // Note: When hasImmediateSync or hasTruncateSync is true, we process ALL committed
+    // sync transactions (not just the immediate/truncate ones). This is intentional for
+    // ordering correctness: if we only processed the immediate transaction, earlier
+    // non-immediate transactions would be applied later and could overwrite newer state.
+    // Processing all committed transactions together preserves causal ordering.
+    if (!hasPersistingTransaction || hasTruncateSync || hasImmediateSync) {
       // Set flag to prevent redundant optimistic state recalculations
       this.isCommittingSyncTransactions = true
 

package/src/collection/sync.ts

@@ -88,11 +88,12 @@ export class CollectionSyncManager<
       const syncRes = normalizeSyncFnResult(
         this.config.sync.sync({
           collection: this.collection,
-          begin: () => {
+          begin: (options?: { immediate?: boolean }) => {
             this.state.pendingSyncedTransactions.push({
               committed: false,
               operations: [],
               deletedKeys: new Set(),
+              immediate: options?.immediate,
             })
           },
           write: (
@@ -149,6 +150,7 @@ export class CollectionSyncManager<
                   throw new DuplicateKeySyncError(key, this.id, {
                     hasCustomGetKey: internal?.hasCustomGetKey ?? false,
                     hasJoins: internal?.hasJoins ?? false,
+                    hasDistinct: internal?.hasDistinct ?? false,
                   })
                 }
               }

package/src/errors.ts

@@ -172,12 +172,28 @@ export class DuplicateKeySyncError extends CollectionOperationError {
   constructor(
     key: string | number,
     collectionId: string,
-    options?: { hasCustomGetKey?: boolean; hasJoins?: boolean },
+    options?: {
+      hasCustomGetKey?: boolean
+      hasJoins?: boolean
+      hasDistinct?: boolean
+    },
   ) {
     const baseMessage = `Cannot insert document with key "${key}" from sync because it already exists in the collection "${collectionId}"`
 
-    // Provide enhanced guidance when custom getKey is used with joins
-    if (options?.hasCustomGetKey && options.hasJoins) {
+    // Provide enhanced guidance when custom getKey is used with distinct
+    if (options?.hasCustomGetKey && options.hasDistinct) {
+      super(
+        `${baseMessage}. ` +
+          `This collection uses a custom getKey with .distinct(). ` +
+          `The .distinct() operator deduplicates by the ENTIRE selected object (standard SQL behavior), ` +
+          `but your custom getKey extracts only a subset of fields. This causes multiple distinct rows ` +
+          `(with different values in non-key fields) to receive the same key. ` +
+          `To fix this, either: (1) ensure your SELECT only includes fields that uniquely identify each row, ` +
+          `(2) use .groupBy() with min()/max() aggregates to select one value per group, or ` +
+          `(3) remove the custom getKey to use the default key behavior.`,
+      )
+    } else if (options?.hasCustomGetKey && options.hasJoins) {
+      // Provide enhanced guidance when custom getKey is used with joins
       super(
         `${baseMessage}. ` +
           `This collection uses a custom getKey with joined queries. ` +

package/src/query/builder/functions.ts

@@ -53,10 +53,10 @@ type ExtractType<T> =
 // Helper type to determine aggregate return type based on input nullability
 type AggregateReturnType<T> =
   ExtractType<T> extends infer U
-    ? U extends number | undefined | null | Date | bigint
+    ? U extends number | undefined | null | Date | bigint | string
       ? Aggregate<U>
-      : Aggregate<number | undefined | null | Date | bigint>
-    : Aggregate<number | undefined | null | Date | bigint>
+      : Aggregate<number | undefined | null | Date | bigint | string>
+    : Aggregate<number | undefined | null | Date | bigint | string>
 
 // Helper type to determine string function return type based on input nullability
 type StringFunctionReturnType<T> =

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

@@ -353,20 +353,28 @@ function getAggregateFunction(aggExpr: Aggregate) {
   const valueExtractor = ([, namespacedRow]: [string, NamespacedRow]) => {
     const value = compiledExpr(namespacedRow)
     // Ensure we return a number for numeric aggregate functions
-    return typeof value === `number` ? value : value != null ? Number(value) : 0
+    if (typeof value === `number`) {
+      return value
+    }
+    return value != null ? Number(value) : 0
   }
 
-  // Create a value extractor function for the expression to aggregate
-  const valueExtractorWithDate = ([, namespacedRow]: [
+  // Create a value extractor function for min/max that preserves comparable types
+  const valueExtractorForMinMax = ([, namespacedRow]: [
     string,
     NamespacedRow,
   ]) => {
     const value = compiledExpr(namespacedRow)
-    return typeof value === `number` || value instanceof Date
-      ? value
-      : value != null
-        ? Number(value)
-        : 0
+    // Preserve strings, numbers, Dates, and bigints for comparison
+    if (
+      typeof value === `number` ||
+      typeof value === `string` ||
+      typeof value === `bigint` ||
+      value instanceof Date
+    ) {
+      return value
+    }
+    return value != null ? Number(value) : 0
   }
 
   // Create a raw value extractor function for the expression to aggregate
@@ -383,9 +391,9 @@ function getAggregateFunction(aggExpr: Aggregate) {
     case `avg`:
       return avg(valueExtractor)
     case `min`:
-      return min(valueExtractorWithDate)
+      return min(valueExtractorForMinMax)
     case `max`:
-      return max(valueExtractorWithDate)
+      return max(valueExtractorForMinMax)
     default:
       throw new UnsupportedAggregateFunctionError(aggExpr.name)
   }
@@ -394,20 +402,15 @@ function getAggregateFunction(aggExpr: Aggregate) {
 /**
  * Transforms expressions to replace aggregate functions with references to computed values.
  *
- * This function is used in both ORDER BY and HAVING clauses to transform expressions that reference:
- * 1. Aggregate functions (e.g., `max()`, `count()`) - replaces with references to computed aggregates in SELECT
- * 2. SELECT field references via $selected namespace (e.g., `$selected.latestActivity`) - validates and passes through unchanged
- *
- * For aggregate expressions, it finds matching aggregates in the SELECT clause and replaces them with
- * PropRef([resultAlias, alias]) to reference the computed aggregate value.
+ * For aggregate expressions, finds matching aggregates in the SELECT clause and replaces them
+ * with PropRef([resultAlias, alias]) to reference the computed aggregate value.
  *
- * For ref expressions using the $selected namespace, it validates that the field exists in the SELECT clause
- * and passes them through unchanged (since $selected is already the correct namespace). All other ref expressions
- * are passed through unchanged (treating them as table column references).
+ * Ref expressions (table columns and $selected fields) and value expressions are passed through unchanged.
+ * Function expressions are recursively transformed.
  *
  * @param havingExpr - The expression to transform (can be aggregate, ref, func, or val)
  * @param selectClause - The SELECT clause containing aliases and aggregate definitions
- * @param resultAlias - The namespace alias for SELECT results (default: '$selected', used for aggregate references)
+ * @param resultAlias - The namespace alias for SELECT results (default: '$selected')
  * @returns A transformed BasicExpression that references computed values instead of raw expressions
  */
 export function replaceAggregatesByRefs(
@@ -439,41 +442,11 @@ export function replaceAggregatesByRefs(
       return new Func(funcExpr.name, transformedArgs)
     }
 
-    case `ref`: {
-      const refExpr = havingExpr
-      const path = refExpr.path
-
-      if (path.length === 0) {
-        // Empty path - pass through
-        return havingExpr as BasicExpression
-      }
-
-      // Check if this is a $selected reference
-      if (path.length > 0 && path[0] === `$selected`) {
-        // Extract the field path after $selected
-        const fieldPath = path.slice(1)
-
-        if (fieldPath.length === 0) {
-          // Just $selected without a field - pass through unchanged
-          return havingExpr as BasicExpression
-        }
-
-        // Verify the field exists in SELECT clause
-        const alias = fieldPath.join(`.`)
-        if (alias in selectClause) {
-          // Pass through unchanged - $selected is already the correct namespace
-          return havingExpr as BasicExpression
-        }
-
-        // Field doesn't exist in SELECT - this is an error, but we'll pass through for now
-        // (Could throw an error here in the future)
-        return havingExpr as BasicExpression
-      }
-
-      // Not a $selected reference - this is a table column reference, pass through unchanged
-      // SELECT fields should only be accessed via $selected namespace
+    case `ref`:
+      // Ref expressions are passed through unchanged - they reference either:
+      // - $selected fields (which are already in the correct namespace)
+      // - Table column references (which remain valid)
       return havingExpr as BasicExpression
-    }
 
     case `val`:
       // Return as-is

package/src/query/live/collection-config-builder.ts

@@ -227,6 +227,7 @@ export class CollectionConfigBuilder<
           getBuilder: () => this,
           hasCustomGetKey: !!this.config.getKey,
           hasJoins: this.hasJoins(this.query),
+          hasDistinct: !!this.query.distinct,
         },
       },
     }

package/src/query/live/internal.ts

@@ -12,4 +12,5 @@ export type LiveQueryInternalUtils = {
   getBuilder: () => CollectionConfigBuilder<any, any>
   hasCustomGetKey: boolean
   hasJoins: boolean
+  hasDistinct: boolean
 }

package/src/strategies/queueStrategy.ts

@@ -6,9 +6,15 @@ import type { Transaction } from '../transactions'
  * Creates a queue strategy that processes all mutations in order with proper serialization.
  *
  * Unlike other strategies that may drop executions, queue ensures every
- * mutation is processed sequentially. Each transaction commit completes before
+ * mutation is attempted sequentially. Each transaction commit completes before
  * the next one starts. Useful when data consistency is critical and
- * every operation must complete in order.
+ * every operation must be attempted in order.
+ *
+ * **Error handling behavior:**
+ * - If a mutation fails, it is NOT automatically retried - the transaction transitions to "failed" state
+ * - Failed mutations surface their error via `transaction.isPersisted.promise` (which will reject)
+ * - Subsequent mutations continue processing - a single failure does not block the queue
+ * - Each mutation is independent; there is no all-or-nothing transaction semantics
  *
  * @param options - Configuration for queue behavior (FIFO/LIFO, timing, size limits)
  * @returns A queue strategy instance

package/src/types.ts

@@ -328,7 +328,12 @@ export interface SyncConfig<
 > {
   sync: (params: {
     collection: Collection<T, TKey, any, any, any>
-    begin: () => void
+    /**
+     * Begin a new sync transaction.
+     * @param options.immediate - When true, the transaction will be processed immediately
+     *   even if there are persisting user transactions. Used by manual write operations.
+     */
+    begin: (options?: { immediate?: boolean }) => void
     write: (message: ChangeMessageOrDeleteKeyMessage<T, TKey>) => void
     commit: () => void
     markReady: () => void