fix: add 128-byte threshold to prevent large Uint8Array string duplication

Applied the same 128-byte threshold to normalizeValue() as used in
the hashing function. This prevents creating giant strings in memory
when indexing large Uint8Arrays (> 128 bytes).

Arrays larger than 128 bytes will fall back to reference equality,
which is acceptable as the fix is primarily for ID use cases (ULIDs
are 16 bytes, UUIDs are 16 bytes).

Added test coverage to verify the threshold behavior works as expected.

Author: claude

packages/db/src/utils/comparison.ts

@@ -126,6 +126,14 @@ function areUint8ArraysEqual(a: Uint8Array, b: Uint8Array): boolean {
   return true
 }
 
+/**
+ * Threshold for normalizing Uint8Arrays to string representations.
+ * Arrays larger than this will use reference equality to avoid memory overhead.
+ * 128 bytes is enough for common ID formats (ULIDs are 16 bytes, UUIDs are 16 bytes)
+ * while avoiding excessive string allocation for large binary data.
+ */
+const UINT8ARRAY_NORMALIZE_THRESHOLD = 128
+
 /**
  * Normalize a value for comparison and Map key usage
  * Converts values that can't be directly compared or used as Map keys
@@ -143,9 +151,14 @@ export function normalizeValue(value: any): any {
     value instanceof Uint8Array
 
   if (isUint8Array) {
-    // Convert to a string representation that can be used as a Map key
-    // Use a special prefix to avoid collisions with user strings
-    return `__u8__${Array.from(value).join(`,`)}`
+    // Only normalize small arrays to avoid memory overhead for large binary data
+    if (value.byteLength <= UINT8ARRAY_NORMALIZE_THRESHOLD) {
+      // Convert to a string representation that can be used as a Map key
+      // Use a special prefix to avoid collisions with user strings
+      return `__u8__${Array.from(value).join(`,`)}`
+    }
+    // For large arrays, fall back to reference equality
+    // Users working with large binary data should use a derived key if needed
   }
 
   return value

packages/db/tests/integration/uint8array-id-comparison.test.ts

@@ -78,4 +78,62 @@ describe(`Uint8Array ID comparison (user reproduction)`, () => {
     expect(resultByName).toBeDefined()
     expect(resultByName?.name).toBe(makeItemName(selectedItemIndex))
   })
+
+  it(`should use reference equality for large Uint8Arrays (> 128 bytes)`, async () => {
+    // Create a large Uint8Array (> 128 bytes) that should use reference equality
+    const largeId = new Uint8Array(200).fill(42)
+
+    interface LargeItem {
+      id: Uint8Array
+      name: string
+    }
+
+    const data: Array<LargeItem> = [
+      { id: largeId, name: `Large Item` },
+      { id: new Uint8Array(200).fill(99), name: `Other Large Item` },
+    ]
+
+    const collection = createCollection(
+      mockSyncCollectionOptions<LargeItem>({
+        id: `large-uint8array-test`,
+        getKey: (item) => item.name,
+        initialData: data,
+        autoIndex: `eager`,
+      })
+    )
+
+    // Query with the exact same reference - this should work
+    const queryWithSameRef = createLiveQueryCollection((q) =>
+      q
+        .from({ item: collection })
+        .where(({ item }) => eq(item.id, largeId))
+        .findOne()
+    )
+
+    await queryWithSameRef.preload()
+    const resultWithSameRef = Array.from(queryWithSameRef.entries())[0]?.[1]
+
+    // Should find the item because we're using the same reference
+    expect(resultWithSameRef).toBeDefined()
+    expect(resultWithSameRef?.name).toBe(`Large Item`)
+
+    // Query with a different instance but same content - this will NOT work
+    // because large arrays use reference equality
+    const differentInstance = new Uint8Array(200).fill(42)
+    const queryWithDifferentRef = createLiveQueryCollection((q) =>
+      q
+        .from({ item: collection })
+        .where(({ item }) => eq(item.id, differentInstance))
+        .findOne()
+    )
+
+    await queryWithDifferentRef.preload()
+    const resultWithDifferentRef = Array.from(
+      queryWithDifferentRef.entries()
+    )[0]?.[1]
+
+    // Should NOT find the item because large arrays use reference equality
+    // This is expected behavior to avoid memory overhead
+    expect(resultWithDifferentRef).toBeUndefined()
+  })
 })