@tanstack/db 0.4.19 → 0.4.20

package/dist/esm/query/live/collection-registry.d.ts

@@ -1,7 +1,7 @@
 import { Collection } from '../../collection/index.js';
 import { CollectionConfigBuilder } from './collection-config-builder.js';
 /**
- * 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

package/dist/esm/query/live/collection-registry.js

@@ -1,6 +1,7 @@
+import { LIVE_QUERY_INTERNAL } from "./internal.js";
 const collectionBuilderRegistry = /* @__PURE__ */ new WeakMap();
 function getBuilderFromConfig(config) {
-  return config.utils?.getBuilder?.();
+  return config.utils?.[LIVE_QUERY_INTERNAL]?.getBuilder?.();
 }
 function registerCollectionBuilder(collection, builder) {
   collectionBuilderRegistry.set(collection, builder);

package/dist/esm/query/live/collection-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"collection-registry.js","sources":["../../../../src/query/live/collection-registry.ts"],"sourcesContent":["import type { Collection } from \"../../collection/index.js\"\nimport type { CollectionConfigBuilder } from \"./collection-config-builder.js\"\n\nconst collectionBuilderRegistry = new WeakMap<\n  Collection<any, any, any>,\n  CollectionConfigBuilder<any, any>\n>()\n\n/**\n * Retrieves the builder attached to a config object via its utils.getBuilder() method.\n *\n * @param config - The collection config object\n * @returns The attached builder, or `undefined` if none exists\n */\nexport function getBuilderFromConfig(\n  config: object\n): CollectionConfigBuilder<any, any> | undefined {\n  return (config as any).utils?.getBuilder?.()\n}\n\n/**\n * Registers a builder for a collection in the global registry.\n * Used to detect when a live query depends on another live query,\n * enabling the scheduler to ensure parent queries run first.\n *\n * @param collection - The collection to register the builder for\n * @param builder - The builder that produces this collection\n */\nexport function registerCollectionBuilder(\n  collection: Collection<any, any, any>,\n  builder: CollectionConfigBuilder<any, any>\n): void {\n  collectionBuilderRegistry.set(collection, builder)\n}\n\n/**\n * Retrieves the builder registered for a collection.\n * Used to discover dependencies when a live query subscribes to another live query.\n *\n * @param collection - The collection to look up\n * @returns The registered builder, or `undefined` if none exists\n */\nexport function getCollectionBuilder(\n  collection: Collection<any, any, any>\n): CollectionConfigBuilder<any, any> | undefined {\n  return collectionBuilderRegistry.get(collection)\n}\n"],"names":[],"mappings":"AAGA,MAAM,gDAAgC,QAAA;AAW/B,SAAS,qBACd,QAC+C;AAC/C,SAAQ,OAAe,OAAO,aAAA;AAChC;AAUO,SAAS,0BACd,YACA,SACM;AACN,4BAA0B,IAAI,YAAY,OAAO;AACnD;AASO,SAAS,qBACd,YAC+C;AAC/C,SAAO,0BAA0B,IAAI,UAAU;AACjD;"}
+{"version":3,"file":"collection-registry.js","sources":["../../../../src/query/live/collection-registry.ts"],"sourcesContent":["import { LIVE_QUERY_INTERNAL } from \"./internal.js\"\nimport type { Collection } from \"../../collection/index.js\"\nimport type { CollectionConfigBuilder } from \"./collection-config-builder.js\"\n\nconst collectionBuilderRegistry = new WeakMap<\n  Collection<any, any, any>,\n  CollectionConfigBuilder<any, any>\n>()\n\n/**\n * Retrieves the builder attached to a config object via its internal utils.\n *\n * @param config - The collection config object\n * @returns The attached builder, or `undefined` if none exists\n */\nexport function getBuilderFromConfig(\n  config: object\n): CollectionConfigBuilder<any, any> | undefined {\n  return (config as any).utils?.[LIVE_QUERY_INTERNAL]?.getBuilder?.()\n}\n\n/**\n * Registers a builder for a collection in the global registry.\n * Used to detect when a live query depends on another live query,\n * enabling the scheduler to ensure parent queries run first.\n *\n * @param collection - The collection to register the builder for\n * @param builder - The builder that produces this collection\n */\nexport function registerCollectionBuilder(\n  collection: Collection<any, any, any>,\n  builder: CollectionConfigBuilder<any, any>\n): void {\n  collectionBuilderRegistry.set(collection, builder)\n}\n\n/**\n * Retrieves the builder registered for a collection.\n * Used to discover dependencies when a live query subscribes to another live query.\n *\n * @param collection - The collection to look up\n * @returns The registered builder, or `undefined` if none exists\n */\nexport function getCollectionBuilder(\n  collection: Collection<any, any, any>\n): CollectionConfigBuilder<any, any> | undefined {\n  return collectionBuilderRegistry.get(collection)\n}\n"],"names":[],"mappings":";AAIA,MAAM,gDAAgC,QAAA;AAW/B,SAAS,qBACd,QAC+C;AAC/C,SAAQ,OAAe,QAAQ,mBAAmB,GAAG,aAAA;AACvD;AAUO,SAAS,0BACd,YACA,SACM;AACN,4BAA0B,IAAI,YAAY,OAAO;AACnD;AASO,SAAS,qBACd,YAC+C;AAC/C,SAAO,0BAA0B,IAAI,UAAU;AACjD;"}

package/dist/esm/query/live/internal.d.ts

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

package/dist/esm/query/live/internal.js

@@ -0,0 +1,5 @@
+const LIVE_QUERY_INTERNAL = Symbol(`liveQueryInternal`);
+export {
+  LIVE_QUERY_INTERNAL
+};
+//# sourceMappingURL=internal.js.map

package/dist/esm/query/live/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sources":["../../../../src/query/live/internal.ts"],"sourcesContent":["import type { CollectionConfigBuilder } from \"./collection-config-builder.js\"\n\n/**\n * Symbol for accessing internal utilities that should not be part of the public API\n */\nexport const LIVE_QUERY_INTERNAL = Symbol(`liveQueryInternal`)\n\n/**\n * Internal utilities for live queries, accessible via Symbol\n */\nexport type LiveQueryInternalUtils = {\n  getBuilder: () => CollectionConfigBuilder<any, any>\n  hasCustomGetKey: boolean\n  hasJoins: boolean\n}\n"],"names":[],"mappings":"AAKO,MAAM,sBAAsB,OAAO,mBAAmB;"}

package/dist/esm/types.d.ts

@@ -22,9 +22,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>;
 /**
  *
  * @remarks `update` and `insert` are both represented as `Partial<T>`, but changes for `insert` could me made more precise by inferring the schema input type. In practice, this has almost 0 real world impact so it's not worth the added type complexity.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/pacer": "^0.1.0",

package/src/collection/index.ts

@@ -189,9 +189,9 @@ export function createCollection(
     options
   )
 
-  // Copy utils to both top level and .utils namespace
+  // Attach utils to collection
   if (options.utils) {
-    collection.utils = { ...options.utils }
+    collection.utils = options.utils
   } else {
     collection.utils = {}
   }

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/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>
 
 /**
  *