From 59e4b07951787ce9420a7eec3245e0d4c271ba10 Mon Sep 17 00:00:00 2001
From: Tomas Zijdemans <tomas.zijdemans@vipps.no>
Date: Sat, 7 Feb 2026 09:06:38 +0100
Subject: [PATCH 1/2] docs(assert): add a note about unreliable equality

---
 assert/equal.ts      | 6 ++++++
 assert/equals.ts     | 6 +++---
 assert/not_equals.ts | 4 ++++
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/assert/equal.ts b/assert/equal.ts
index ce66424d2c07..65e0600ee89c 100644
--- a/assert/equal.ts
+++ b/assert/equal.ts
@@ -89,10 +89,16 @@ function sameValueZero(a: unknown, b: unknown) {
 /**
  * Deep equality comparison used in assertions.
  *
+ * Note: Types whose state is not exposed as enumerable properties, such as
+ * `Blob`, `ReadableStream`, `Request`, and `Response`, may produce unreliable
+ * results. For `Blob` and `File`, compare via `Blob.bytes()` instead.
+ *
  * @param a The actual value
  * @param b The expected value
  * @returns `true` if the values are deeply equal, `false` otherwise
  *
+ * @throws {TypeError} If either value is a `WeakMap` or `WeakSet`.
+ *
  * @example Usage
  * ```ts
  * import { equal } from "@std/assert/equal";
diff --git a/assert/equals.ts b/assert/equals.ts
index e1a077a81686..4e45ccd7e4a3 100644
--- a/assert/equals.ts
+++ b/assert/equals.ts
@@ -15,9 +15,9 @@ import { AssertionError } from "./assertion_error.ts";
  * Type parameter can be specified to ensure values under comparison have the
  * same type.
  *
- * Note: When comparing `Blob` objects, you should first convert them to
- * `Uint8Array` using the `Blob.bytes()` method and then compare their
- * contents.
+ * Note: Types whose state is not exposed as enumerable properties, such as
+ * `Blob`, `ReadableStream`, `Request`, and `Response`, may produce unreliable
+ * results. For `Blob` and `File`, compare via `Blob.bytes()` instead.
  *
  * @example Usage
  * ```ts ignore
diff --git a/assert/not_equals.ts b/assert/not_equals.ts
index 07164446f645..c41e8e89c36e 100644
--- a/assert/not_equals.ts
+++ b/assert/not_equals.ts
@@ -11,6 +11,10 @@ import { format } from "@std/internal/format";
  *
  * Type parameter can be specified to ensure values under comparison have the same type.
  *
+ * Note: Types whose state is not exposed as enumerable properties, such as
+ * `Blob`, `ReadableStream`, `Request`, and `Response`, may produce unreliable
+ * results. For `Blob` and `File`, compare via `Blob.bytes()` instead.
+ *
  * @example Usage
  * ```ts ignore
  * import { assertNotEquals } from "@std/assert";

From adcc8e6ad2084fadf8bf20e04d04373b8b5c46a2 Mon Sep 17 00:00:00 2001
From: Tomas Zijdemans <tomas.zijdemans@vipps.no>
Date: Sat, 7 Feb 2026 20:05:57 +0100
Subject: [PATCH 2/2] Improve doc

---
 assert/equal.ts      | 8 +++++---
 assert/equals.ts     | 8 +++++---
 assert/not_equals.ts | 8 +++++---
 3 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/assert/equal.ts b/assert/equal.ts
index 65e0600ee89c..97aaabfe699a 100644
--- a/assert/equal.ts
+++ b/assert/equal.ts
@@ -89,9 +89,11 @@ function sameValueZero(a: unknown, b: unknown) {
 /**
  * Deep equality comparison used in assertions.
  *
- * Note: Types whose state is not exposed as enumerable properties, such as
- * `Blob`, `ReadableStream`, `Request`, and `Response`, may produce unreliable
- * results. For `Blob` and `File`, compare via `Blob.bytes()` instead.
+ * This function is based on value equality, but for some cases (such as data
+ * that can only be read asynchronously or function properties) value equality
+ * is not possible to determine. In such cases, reference equality is used
+ * instead, which may cause false negatives for objects such as `Blob`s or
+ * `Request`s.
  *
  * @param a The actual value
  * @param b The expected value
diff --git a/assert/equals.ts b/assert/equals.ts
index 4e45ccd7e4a3..b8370584425b 100644
--- a/assert/equals.ts
+++ b/assert/equals.ts
@@ -15,9 +15,11 @@ import { AssertionError } from "./assertion_error.ts";
  * Type parameter can be specified to ensure values under comparison have the
  * same type.
  *
- * Note: Types whose state is not exposed as enumerable properties, such as
- * `Blob`, `ReadableStream`, `Request`, and `Response`, may produce unreliable
- * results. For `Blob` and `File`, compare via `Blob.bytes()` instead.
+ * Note: This function is based on value equality, but for some cases (such as
+ * data that can only be read asynchronously or function properties) value
+ * equality is not possible to determine. In such cases, reference equality is
+ * used instead, which may cause false negatives for objects such as `Blob`s or
+ * `Request`s.
  *
  * @example Usage
  * ```ts ignore
diff --git a/assert/not_equals.ts b/assert/not_equals.ts
index c41e8e89c36e..12a26234d07b 100644
--- a/assert/not_equals.ts
+++ b/assert/not_equals.ts
@@ -11,9 +11,11 @@ import { format } from "@std/internal/format";
  *
  * Type parameter can be specified to ensure values under comparison have the same type.
  *
- * Note: Types whose state is not exposed as enumerable properties, such as
- * `Blob`, `ReadableStream`, `Request`, and `Response`, may produce unreliable
- * results. For `Blob` and `File`, compare via `Blob.bytes()` instead.
+ * Note: This function is based on value equality, but for some cases (such as
+ * data that can only be read asynchronously or function properties) value
+ * equality is not possible to determine. In such cases, reference equality is
+ * used instead, which may cause false negatives for objects such as `Blob`s or
+ * `Request`s.
  *
  * @example Usage
  * ```ts ignore