test/utils/test-utils.ts (1)

488-488: Return a consistent Promise shape

Early-returning Promise.resolve() changes the inferred return type to Promise<void | unknown[]>. Prefer returning an empty array for consistency with the Promise.all(...) branch.

-    if (!connections || connections.length === 0) return Promise.resolve()
+    if (!connections?.length) return Promise.resolve([])

src/data-source/BaseDataSourceOptions.ts (1)

218-236: Broaden JSDoc scope beyond “find operations”

This option applies to all where-capable operations (find, query builders, repository/manager update/delete/soft-delete). Update the description to avoid under-scoping.

-    /**
-     * Controls how null and undefined values are handled in find operations.
-     */
+    /**
+     * Controls how null and undefined values are handled in where conditions across all TypeORM operations
+     * (e.g. find options, QueryBuilder, repository and entity manager methods).
+     */

docs/docs/data-source/2-data-source-options.md (1)

89-95: Use precise SQL phrasing (“IS NULL” predicate)

“Transforms null to SQL NULL” can be misread. Suggest “emits an IS NULL condition” for accuracy.

-        -   `'sql-null'` - transforms null to SQL NULL
+        -   `'sql-null'` - emits an `IS NULL` condition

docs/docs/data-source/5-null-and-undefined-handling.md (2)

13-16: Avoid committing to future default changes without consensus

The note states the behavior “will be changing” in future versions. Unless this is an agreed roadmap, soften to a recommendation without asserting a committed change.

-:::note
-The current behavior will be changing in future versions of TypeORM,
-we recommend setting both `null` and `undefined` behaviors to throw to prepare for these changes
-:::
+:::note
+For maximum safety, we recommend setting both `null` and `undefined` behaviors to `'throw'`.
+Future versions may change defaults.
+:::

---

85-98: Align terminology with SQL (“IS NULL”)

Mirror the phrasing used elsewhere: “emits an IS NULL condition” rather than “transformed into SQL NULL”.

- JavaScript `null` values are transformed into SQL `NULL` conditions:
+ JavaScript `null` values emit an `IS NULL` condition:

test/functional/null-undefined-handling/entity/Post.ts (1)

21-23: Consider explicit onDelete to match nullable relation intent.

Adding onDelete: "SET NULL" ensures FK behavior aligns with Post.category being nullable across drivers.

-    @ManyToOne(() => Category, { nullable: true })
+    @ManyToOne(() => Category, { nullable: true, onDelete: "SET NULL" })

test/functional/null-undefined-handling/query-builders.ts (1)

389-438: Add a nested undefined relation case to lock in semantics.

Edge case currently untested: category: { id: undefined } when undefined is 'throw'. Suggest adding to ensure nested handling throws (or is ignored) consistently.

+        it("should throw when nested relation id is undefined and undefined='throw'", async () => {
+            for (const connection of connections) {
+                try {
+                    await connection
+                        .createQueryBuilder(Post, "post")
+                        .where({ category: { id: undefined } as any })
+                        .getMany()
+                    expect.fail("Expected query to throw an error")
+                } catch (error) {
+                    expect(error).to.be.instanceOf(TypeORMError)
+                    expect(error.message).to.include("Undefined value encountered")
+                }
+            }
+        })

test/functional/null-undefined-handling/find-options.ts (1)

354-357: Make message assertions resilient (use include, not exact).

Tests currently assert full error strings; minor text changes will cause false negatives. Prefer .to.include on a stable substring.

-                    expect(error.message).to.equal(
-                        "Undefined value encountered in property 'post.text' of the find operation. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.",
-                    )
+                    expect(error.message).to.include("Undefined value encountered")
...
-                    expect(error.message).to.equal(
-                        "Undefined value encountered in property 'Post.text' of the find operation. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.",
-                    )
+                    expect(error.message).to.include("Undefined value encountered")
...
-                    expect(error.message).to.equal(
-                        "Undefined value encountered in property 'Post.text' of the find operation. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.",
-                    )
+                    expect(error.message).to.include("Undefined value encountered")
...
-                    expect(error.message).to.equal(
-                        "Null value encountered in property 'post.text' of the find operation. To match with SQL NULL, the IsNull() operator must be used. Set 'invalidWhereValuesBehavior.null' to 'ignore' or 'sql-null' in connection options to skip or handle null values.",
-                    )
+                    expect(error.message).to.include("Null value encountered")
...
-                    expect(error.message).to.equal(
-                        "Null value encountered in property 'Post.text' of the find operation. To match with SQL NULL, the IsNull() operator must be used. Set 'invalidWhereValuesBehavior.null' to 'ignore' or 'sql-null' in connection options to skip or handle null values.",
-                    )
+                    expect(error.message).to.include("Null value encountered")
...
-                    expect(error.message).to.equal(
-                        "Null value encountered in property 'Post.text' of the find operation. To match with SQL NULL, the IsNull() operator must be used. Set 'invalidWhereValuesBehavior.null' to 'ignore' or 'sql-null' in connection options to skip or handle null values.",
-                    )
+                    expect(error.message).to.include("Null value encountered")
...
-                        expect(error.message).to.equal(
-                            "Undefined value encountered in property 'post.category.id' of the find operation. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.",
-                        )
+                        expect(error.message).to.include("Undefined value encountered")
...
-                        expect(error.message).to.equal(
-                            "Undefined value encountered in property 'Post.category' of the find operation. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.",
-                        )
+                        expect(error.message).to.include("Undefined value encountered")
...
-                        expect(error.message).to.equal(
-                            "Undefined value encountered in property 'Post.category' of the find operation. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.",
-                        )
+                        expect(error.message).to.include("Undefined value encountered")

Also applies to: 369-371, 383-385, 641-643, 655-657, 671-673, 692-694, 708-709, 723-724

src/query-builder/SelectQueryBuilder.ts (4)

4308-4336: Undefined/null gating reads well; tiny perf nit.

You recompute behaviors per key. Consider caching behaviors once per buildWhere call; low impact.

-                if (parameterValue === undefined) {
-                    const undefinedBehavior =
-                        this.connection.options.invalidWhereValuesBehavior
-                            ?.undefined || "ignore"
+                if (parameterValue === undefined) {
+                    const undefinedBehavior =
+                        this.connection.options.invalidWhereValuesBehavior?.undefined ?? "ignore"

---

4411-4426: Remove unreachable throw in relation null branch.

When parameterValue === null, the earlier null-behavior block already throws/continues; only 'sql-null' falls through. The 'throw' here is dead code.

-                    if (where[key] === null) {
+                    if (where[key] === null) {
                         const nullBehavior =
                             this.connection.options.invalidWhereValuesBehavior
                                 ?.null || "ignore"
                         if (nullBehavior === "sql-null") {
                             andConditions.push(
                                 `${alias}.${propertyPath} IS NULL`,
                             )
-                        } else if (nullBehavior === "throw") {
-                            throw new TypeORMError(
-                                `Null value encountered in property '${alias}.${key}' of the find operation. ` +
-                                    `Set 'invalidWhereValuesBehavior.null' to 'ignore' or 'sql-null' in connection options to skip or handle null values.`,
-                            )
                         }
                         // 'ignore' behavior falls through to continue
                         continue
                     }

---

4430-4437: Undefined='throw' is bypassed for nested relation objects with all-undefined props.

Current logic silently skips category: { id: undefined }. If undefined='throw', this should probably throw (mirroring top-level behavior).

-                    if (typeof where[key] === "object") {
-                        const allAllUndefined = Object.keys(where[key]).every(
-                            (k) => where[key][k] === undefined,
-                        )
-                        if (allAllUndefined) {
-                            continue
-                        }
-                    }
+                    if (typeof where[key] === "object") {
+                        const keys = Object.keys(where[key] as any)
+                        const allUndef = keys.length > 0 && keys.every((k) => (where[key] as any)[k] === undefined)
+                        if (allUndef) {
+                            const undefinedBehavior =
+                                this.connection.options.invalidWhereValuesBehavior?.undefined ?? "ignore"
+                            if (undefinedBehavior === "throw") {
+                                throw new TypeORMError(
+                                    `Undefined value encountered in property '${alias}.${propertyPath}.id' of the find operation. ` +
+                                        `Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.`,
+                                )
+                            }
+                            continue
+                        }
+                    }

---

4355-4371: Minor ordering tweak: unwrap Equal() before null check.

If Equal(null) is used, unwrapping first makes the subsequent null-path (IS NULL/behavior) explicit and consistent.

-                    if (parameterValue === null) {
-                        andConditions.push(`${aliasPath} IS NULL`)
-                        continue
-                    }
-
-                    // todo: we need to handle other operators as well?
-                    if (InstanceChecker.isEqualOperator(where[key])) {
-                        parameterValue = where[key].value
-                    }
+                    // Unwrap Equal() first
+                    if (InstanceChecker.isEqualOperator(where[key])) {
+                        parameterValue = where[key].value
+                    }
+                    if (parameterValue === null) {
+                        andConditions.push(`${aliasPath} IS NULL`)
+                        continue
+                    }

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro