@tanstack/db 0.4.18 → 0.4.20

package/src/collection/sync.ts

@@ -9,6 +9,7 @@ import {
   SyncTransactionAlreadyCommittedWriteError,
 } from "../errors"
 import { deepEquals } from "../utils"
+import { LIVE_QUERY_INTERNAL } from "../query/live/internal.js"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type {
   ChangeMessage,
@@ -21,6 +22,7 @@ import type { CollectionImpl } from "./index.js"
 import type { CollectionStateManager } from "./state"
 import type { CollectionLifecycleManager } from "./lifecycle"
 import type { CollectionEventsManager } from "./events.js"
+import type { LiveQueryCollectionUtils } from "../query/live/collection-config-builder.js"
 
 export class CollectionSyncManager<
   TOutput extends object = Record<string, unknown>,
@@ -127,7 +129,13 @@ export class CollectionSyncManager<
                   // throwing a duplicate-key error during reconciliation.
                   messageType = `update`
                 } else {
-                  throw new DuplicateKeySyncError(key, this.id)
+                  const utils = this.config
+                    .utils as Partial<LiveQueryCollectionUtils>
+                  const internal = utils[LIVE_QUERY_INTERNAL]
+                  throw new DuplicateKeySyncError(key, this.id, {
+                    hasCustomGetKey: internal?.hasCustomGetKey ?? false,
+                    hasJoins: internal?.hasJoins ?? false,
+                  })
                 }
               }
             }

package/src/errors.ts

@@ -160,10 +160,26 @@ export class DuplicateKeyError extends CollectionOperationError {
 }
 
 export class DuplicateKeySyncError extends CollectionOperationError {
-  constructor(key: string | number, collectionId: string) {
-    super(
-      `Cannot insert document with key "${key}" from sync because it already exists in the collection "${collectionId}"`
-    )
+  constructor(
+    key: string | number,
+    collectionId: string,
+    options?: { hasCustomGetKey?: boolean; hasJoins?: 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) {
+      super(
+        `${baseMessage}. ` +
+          `This collection uses a custom getKey with joined queries. ` +
+          `Joined queries can produce multiple rows with the same key when relationships are not 1:1. ` +
+          `Consider: (1) using a composite key in your getKey function (e.g., \`\${item.key1}-\${item.key2}\`), ` +
+          `(2) ensuring your join produces unique rows per key, or (3) removing the custom getKey ` +
+          `to use the default composite key behavior.`
+      )
+    } else {
+      super(baseMessage)
+    }
   }
 }
 

package/src/local-storage.ts

@@ -346,16 +346,6 @@ export function localStorageCollectionOptions(
     lastKnownData
   )
 
-  /**
-   * Manual trigger function for local sync updates
-   * Forces a check for storage changes and updates the collection if needed
-   */
-  const triggerLocalSync = () => {
-    if (sync.manualTrigger) {
-      sync.manualTrigger()
-    }
-  }
-
   /**
    * Save data to storage
    * @param dataMap - Map of items with version tracking to save to storage
@@ -413,24 +403,24 @@ export function localStorageCollectionOptions(
     }
 
     // Always persist to storage
-    // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
-
+    // Use lastKnownData (in-memory cache) instead of reading from storage
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
-      const key = config.getKey(mutation.modified)
+      // Use the engine's pre-computed key for consistency
+      const key = mutation.key
       const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
-      currentData.set(key, storedItem)
+      lastKnownData.set(key, storedItem)
     })
 
     // Save to storage
-    saveToStorage(currentData)
+    saveToStorage(lastKnownData)
 
-    // Manually trigger local sync since storage events don't fire for current tab
-    triggerLocalSync()
+    // Confirm mutations through sync interface (moves from optimistic to synced state)
+    // without reloading from storage
+    sync.confirmOperationsSync(params.transaction.mutations)
 
     return handlerResult
   }
@@ -448,24 +438,24 @@ export function localStorageCollectionOptions(
     }
 
     // Always persist to storage
-    // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
-
+    // Use lastKnownData (in-memory cache) instead of reading from storage
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
-      const key = config.getKey(mutation.modified)
+      // Use the engine's pre-computed key for consistency
+      const key = mutation.key
       const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
-      currentData.set(key, storedItem)
+      lastKnownData.set(key, storedItem)
     })
 
     // Save to storage
-    saveToStorage(currentData)
+    saveToStorage(lastKnownData)
 
-    // Manually trigger local sync since storage events don't fire for current tab
-    triggerLocalSync()
+    // Confirm mutations through sync interface (moves from optimistic to synced state)
+    // without reloading from storage
+    sync.confirmOperationsSync(params.transaction.mutations)
 
     return handlerResult
   }
@@ -478,21 +468,20 @@ export function localStorageCollectionOptions(
     }
 
     // Always persist to storage
-    // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
-
+    // Use lastKnownData (in-memory cache) instead of reading from storage
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
-      // For delete operations, mutation.original contains the full object
-      const key = config.getKey(mutation.original)
-      currentData.delete(key)
+      // Use the engine's pre-computed key for consistency
+      const key = mutation.key
+      lastKnownData.delete(key)
     })
 
     // Save to storage
-    saveToStorage(currentData)
+    saveToStorage(lastKnownData)
 
-    // Manually trigger local sync since storage events don't fire for current tab
-    triggerLocalSync()
+    // Confirm mutations through sync interface (moves from optimistic to synced state)
+    // without reloading from storage
+    sync.confirmOperationsSync(params.transaction.mutations)
 
     return handlerResult
   }
@@ -546,13 +535,7 @@ export function localStorageCollectionOptions(
       }
     }
 
-    // Load current data from storage
-    const currentData = loadFromStorage<Record<string, unknown>>(
-      config.storageKey,
-      storage,
-      parser
-    )
-
+    // Use lastKnownData (in-memory cache) instead of reading from storage
     // Apply each mutation
     for (const mutation of collectionMutations) {
       // Use the engine's pre-computed key to avoid key derivation issues
@@ -565,18 +548,18 @@ export function localStorageCollectionOptions(
             versionKey: generateUuid(),
             data: mutation.modified,
           }
-          currentData.set(key, storedItem)
+          lastKnownData.set(key, storedItem)
           break
         }
         case `delete`: {
-          currentData.delete(key)
+          lastKnownData.delete(key)
           break
         }
       }
     }
 
     // Save to storage
-    saveToStorage(currentData)
+    saveToStorage(lastKnownData)
 
     // Confirm the mutations in the collection to move them from optimistic to synced state
     // This writes them through the sync interface to make them "synced" instead of "optimistic"

package/src/query/builder/types.ts

@@ -530,6 +530,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 +565,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 +589,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/live/collection-config-builder.ts

@@ -9,6 +9,8 @@ import { transactionScopedScheduler } from "../../scheduler.js"
 import { getActiveTransaction } from "../../transactions.js"
 import { CollectionSubscriber } from "./collection-subscriber.js"
 import { getCollectionBuilder } from "./collection-registry.js"
+import { LIVE_QUERY_INTERNAL } from "./internal.js"
+import type { LiveQueryInternalUtils } from "./internal.js"
 import type { WindowOptions } from "../compiler/index.js"
 import type { SchedulerContextId } from "../../scheduler.js"
 import type { CollectionSubscription } from "../../collection/subscription.js"
@@ -35,7 +37,6 @@ import type { AllCollectionEvents } from "../../collection/events.js"
 
 export type LiveQueryCollectionUtils = UtilsRecord & {
   getRunCount: () => number
-  getBuilder: () => CollectionConfigBuilder<any, any>
   /**
    * Sets the offset and limit of an ordered query.
    * Is a no-op if the query is not ordered.
@@ -49,6 +50,7 @@ export type LiveQueryCollectionUtils = UtilsRecord & {
    * @returns The current window settings, or `undefined` if the query is not windowed
    */
   getWindow: () => { offset: number; limit: number } | undefined
+  [LIVE_QUERY_INTERNAL]: LiveQueryInternalUtils
 }
 
 type PendingGraphRun = {
@@ -173,6 +175,25 @@ export class CollectionConfigBuilder<
     this.compileBasePipeline()
   }
 
+  /**
+   * Recursively checks if a query or any of its subqueries contains joins
+   */
+  private hasJoins(query: QueryIR): boolean {
+    // Check if this query has joins
+    if (query.join && query.join.length > 0) {
+      return true
+    }
+
+    // Recursively check subqueries in the from clause
+    if (query.from.type === `queryRef`) {
+      if (this.hasJoins(query.from.query)) {
+        return true
+      }
+    }
+
+    return false
+  }
+
   getConfig(): CollectionConfigSingleRowOption<TResult> & {
     utils: LiveQueryCollectionUtils
   } {
@@ -192,9 +213,13 @@ export class CollectionConfigBuilder<
       singleResult: this.query.singleResult,
       utils: {
         getRunCount: this.getRunCount.bind(this),
-        getBuilder: () => this,
         setWindow: this.setWindow.bind(this),
         getWindow: this.getWindow.bind(this),
+        [LIVE_QUERY_INTERNAL]: {
+          getBuilder: () => this,
+          hasCustomGetKey: !!this.config.getKey,
+          hasJoins: this.hasJoins(this.query),
+        },
       },
     }
   }

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

@@ -1,3 +1,4 @@
+import { LIVE_QUERY_INTERNAL } from "./internal.js"
 import type { Collection } from "../../collection/index.js"
 import type { CollectionConfigBuilder } from "./collection-config-builder.js"
 
@@ -7,7 +8,7 @@ const collectionBuilderRegistry = new WeakMap<
 >()
 
 /**
- * Retrieves the builder attached to a config object via its utils.getBuilder() method.
+ * Retrieves the builder attached to a config object via its internal utils.
  *
  * @param config - The collection config object
  * @returns The attached builder, or `undefined` if none exists
@@ -15,7 +16,7 @@ const collectionBuilderRegistry = new WeakMap<
 export function getBuilderFromConfig(
   config: object
 ): CollectionConfigBuilder<any, any> | undefined {
-  return (config as any).utils?.getBuilder?.()
+  return (config as any).utils?.[LIVE_QUERY_INTERNAL]?.getBuilder?.()
 }
 
 /**

package/src/query/live/internal.ts

@@ -0,0 +1,15 @@
+import type { CollectionConfigBuilder } from "./collection-config-builder.js"
+
+/**
+ * Symbol for accessing internal utilities that should not be part of the public API
+ */
+export const LIVE_QUERY_INTERNAL = Symbol(`liveQueryInternal`)
+
+/**
+ * Internal utilities for live queries, accessible via Symbol
+ */
+export type LiveQueryInternalUtils = {
+  getBuilder: () => CollectionConfigBuilder<any, any>
+  hasCustomGetKey: boolean
+  hasJoins: boolean
+}

package/src/types.ts

@@ -35,9 +35,9 @@ export type TransactionState = `pending` | `persisting` | `completed` | `failed`
 export type Fn = (...args: Array<any>) => any
 
 /**
- * A record of utility functions that can be attached to a collection
+ * A record of utilities (functions or getters) that can be attached to a collection
  */
-export type UtilsRecord = Record<string, Fn>
+export type UtilsRecord = Record<string, any>
 
 /**
  *