Throw a clear error when anything other than an object with an collection is passed to "from" (#875)

* Improve error message when invalid source type is passed to .from()

Fixes #873

The issue was that users were getting a confusing error message when
passing a string (or other invalid type) to the .from() method instead
of an object with a collection.

For example:
```javascript
// Incorrect usage
q.from("conversations")  // String instead of object

// Correct usage
q.from({ conversations: conversationsCollection })
```

When a string was passed, Object.keys("conversations") would return
an array of character indices ['0', '1', ...], which has length > 1,
triggering the "Only one source is allowed in the from clause" error.
This was misleading because the real issue was passing a string instead
of an object.

Changes:
- Added validation to check if the source is a plain object before
  checking its key count
- Improved error message to explicitly state the expected format with
  an example: .from({ alias: collection })
- Added comprehensive tests for various invalid input types (string,
  null, array, undefined)

The new error message is:
"Invalid source for from clause: Expected an object with a single
key-value pair like { alias: collection }. For example:
.from({ todos: todosCollection }). Got: string \"conversations\""

* Refactor error validation to use positive checks

Simplified the validation logic in _createRefForSource to use positive
checks instead of negative checks:
- Check if it's a valid object (handles null/undefined via try-catch)
- Check if it's an array (arrays pass Object.keys but aren't valid)
- Check if it has exactly one key
- Check if keys look like numeric indices (indicates string was passed)

This approach is cleaner and handles all edge cases including when
callers bypass TypeScript's type checks with 'as any'.

Also added a changeset documenting the improvement.

* Move error messages to dedicated error class

Addresses code review feedback by creating InvalidSourceTypeError
class in errors.ts and using it consistently across all validation
cases instead of duplicating error message strings.

Changes:
- Added InvalidSourceTypeError class to errors.ts that takes context
  and type parameters
- Updated _createRefForSource to use InvalidSourceTypeError in all
  four validation cases (null/undefined, array, empty object, string)
- Updated tests to expect InvalidSourceTypeError instead of
  QueryBuilderError
- This eliminates string duplication and makes error messages
  consistent across .from() and .join() methods

---------

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

.changeset/improve-from-clause-error-messages.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Improved error messages when invalid source types are passed to `.from()` or `.join()` methods. When users mistakenly pass a string, null, array, or other invalid type instead of an object with a collection, they now receive a clear, actionable error message with an example of the correct usage (e.g., `.from({ todos: todosCollection })`).

packages/db/src/errors.ts

@@ -360,6 +360,15 @@ export class InvalidSourceError extends QueryBuilderError {
   }
 }
 
+export class InvalidSourceTypeError extends QueryBuilderError {
+  constructor(context: string, type: string) {
+    super(
+      `Invalid source for ${context}: Expected an object with a single key-value pair like { alias: collection }. ` +
+        `For example: .from({ todos: todosCollection }). Got: ${type}`
+    )
+  }
+}
+
 export class JoinConditionMustBeEqualityError extends QueryBuilderError {
   constructor() {
     super(`Join condition must be an equality expression`)

packages/db/src/query/builder/index.ts

@@ -10,6 +10,7 @@ import {
 } from "../ir.js"
 import {
   InvalidSourceError,
+  InvalidSourceTypeError,
   JoinConditionMustBeEqualityError,
   OnlyOneSourceAllowedError,
   QueryMustHaveFromClauseError,
@@ -60,13 +61,38 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     source: TSource,
     context: string
   ): [string, CollectionRef | QueryRef] {
-    if (Object.keys(source).length !== 1) {
+    // Validate source is a plain object (not null, array, string, etc.)
+    // We use try-catch to handle null/undefined gracefully
+    let keys: Array<string>
+    try {
+      keys = Object.keys(source)
+    } catch {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const type = source === null ? `null` : `undefined`
+      throw new InvalidSourceTypeError(context, type)
+    }
+
+    // Check if it's an array (arrays pass Object.keys but aren't valid sources)
+    if (Array.isArray(source)) {
+      throw new InvalidSourceTypeError(context, `array`)
+    }
+
+    // Validate exactly one key
+    if (keys.length !== 1) {
+      if (keys.length === 0) {
+        throw new InvalidSourceTypeError(context, `empty object`)
+      }
+      // Check if it looks like a string was passed (has numeric keys)
+      if (keys.every((k) => !isNaN(Number(k)))) {
+        throw new InvalidSourceTypeError(context, `string`)
+      }
       throw new OnlyOneSourceAllowedError(context)
     }
 
-    const alias = Object.keys(source)[0]!
+    const alias = keys[0]!
     const sourceValue = source[alias]
 
+    // Validate the value is a Collection or QueryBuilder
     let ref: CollectionRef | QueryRef
 
     if (sourceValue instanceof CollectionImpl) {

packages/db/tests/query/builder/from.test.ts

@@ -3,6 +3,7 @@ import { CollectionImpl } from "../../../src/collection/index.js"
 import { Query, getQueryIR } from "../../../src/query/builder/index.js"
 import { eq } from "../../../src/query/builder/functions.js"
 import {
+  InvalidSourceTypeError,
   OnlyOneSourceAllowedError,
   QueryMustHaveFromClauseError,
 } from "../../../src/errors"
@@ -108,4 +109,60 @@ describe(`QueryBuilder.from`, () => {
       } as any)
     }).toThrow(OnlyOneSourceAllowedError)
   })
+
+  it(`throws helpful error when passing a string instead of an object`, () => {
+    const builder = new Query()
+
+    expect(() => {
+      builder.from(`employees` as any)
+    }).toThrow(InvalidSourceTypeError)
+
+    expect(() => {
+      builder.from(`employees` as any)
+    }).toThrow(
+      /Invalid source for from clause: Expected an object with a single key-value pair/
+    )
+  })
+
+  it(`throws helpful error when passing null`, () => {
+    const builder = new Query()
+
+    expect(() => {
+      builder.from(null as any)
+    }).toThrow(InvalidSourceTypeError)
+
+    expect(() => {
+      builder.from(null as any)
+    }).toThrow(
+      /Invalid source for from clause: Expected an object with a single key-value pair/
+    )
+  })
+
+  it(`throws helpful error when passing an array`, () => {
+    const builder = new Query()
+
+    expect(() => {
+      builder.from([employeesCollection] as any)
+    }).toThrow(InvalidSourceTypeError)
+
+    expect(() => {
+      builder.from([employeesCollection] as any)
+    }).toThrow(
+      /Invalid source for from clause: Expected an object with a single key-value pair/
+    )
+  })
+
+  it(`throws helpful error when passing undefined`, () => {
+    const builder = new Query()
+
+    expect(() => {
+      builder.from(undefined as any)
+    }).toThrow(InvalidSourceTypeError)
+
+    expect(() => {
+      builder.from(undefined as any)
+    }).toThrow(
+      /Invalid source for from clause: Expected an object with a single key-value pair/
+    )
+  })
 })