Fix localStorage collections for numeric IDs (#845)

* test: add regression tests for issue #397 (update/delete targeting)

Adds comprehensive test coverage for issue #397 which reported that
update() and delete() operations on localStorage collections were
targeting the wrong items.

Investigation findings:
- Bug was fixed by PR #760 (Nov 5, 2025) which changed from using
  config.getKey() to mutation.key for consistency
- All tests pass, unable to reproduce the reported issue
- Likely that recent commenter is using an outdated package version

Test Coverage Added:
- Test for updating correct item with multiple items present
- Test for deleting correct item with multiple items present
- Both tests verify collection state AND localStorage persistence

Also includes detailed investigation report (INVESTIGATION_397.md)
documenting the analysis, timeline, and recommendations.

Related: #397, #760

* fix: resolve localStorage numeric ID key type mismatch (issue #397)

Fixes #397 - Update and delete operations on localStorage collections
now work correctly with numeric IDs.

## Root Cause

When using numeric IDs with localStorage collections, a type mismatch
occurred between numeric keys (e.g., 1, 2, 3) and string keys from
localStorage (e.g., "1", "2", "3").

The issue manifested when:
1. Data was loaded from localStorage (keys become strings via JSON.parse)
2. User performed update/delete with numeric ID
3. JavaScript Map lookup failed: Map.has(1) !== Map.has("1")

## The Fix

Convert all mutation.key values to strings before using with lastKnownData
Map, ensuring consistency with localStorage's string-only keys.

Changed in packages/db/src/local-storage.ts:
- Line 419 (wrappedOnInsert): const key = String(mutation.key)
- Line 455 (wrappedOnUpdate): const key = String(mutation.key)
- Line 486 (wrappedOnDelete): const key = String(mutation.key)
- Line 554 (acceptMutations): const key = String(mutation.key)

## Test Coverage

Added 6 comprehensive test cases in packages/db/tests/local-storage.test.ts:

Bug #397 test suite (lines 1618-1985):
- String ID tests (baseline/regression)
- Numeric ID tests (direct operations)
- Numeric ID tests after loading from storage (critical case)

All 43 tests pass ✅

## Impact

- ✅ Fully backward compatible (string IDs unchanged)
- ✅ Numeric IDs now work correctly
- ✅ No breaking changes to API

## Documentation

- BUG_FIX_397.md: Detailed technical explanation
- INVESTIGATION_397.md: Complete investigation report

Closes #397

* chore: add changeset for numeric ID localStorage fix

- Remove investigation documentation files
- Add changeset for patch release

* test: add test for numeric/string ID collision behavior

Documents that numeric ID 1 and string ID "1" will collide in
localStorage due to JSON's string-only object keys. Last write wins.

This is expected behavior and a fundamental localStorage limitation.

* refactor: use __number__ prefix for numeric keys instead of String()

Improves fix for issue #397 to prevent collision between numeric and
string IDs (e.g., numeric 1 vs string "1").

Approach:
- Numeric keys: prefixed with "__number__" → __number__1
- String keys: kept as-is → "1", "first"

Benefits:
- ✅ Fixes numeric ID bug (original issue #397)
- ✅ Prevents numeric/string ID collision
- ✅ Maintains backward compatibility for string IDs
- ✅ All 44 tests passing

Related: #397

* chore: update changeset to focus on original bug

Reworded to emphasize the actual bug (numeric IDs not working)
rather than collision prevention as the main issue.

* test: rename test suite to remove issue number reference

Changed 'Bug #397: update/delete targeting wrong item' to
'numeric and string ID handling' to be more descriptive and
issue-agnostic.

* fix: implement proper type-safe encoding for localStorage keys

- Replace __number__ prefix with type-safe n: and s: encoding scheme
- Extract encoding/decoding logic into helper functions (encodeStorageKey, decodeStorageKey)
- Prevents all possible collisions between numeric and string keys
- Add test case for collision prevention between numeric 1 and string 'n:1'
- Update all tests to use new encoding format

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

* test: update localStorage tests for type-safe encoding

Update all localStorage collection tests to match the new type-safe
key encoding format that prevents collisions between numeric and
string IDs.

Changes:
- Update test assertions to use encoded keys ("s:1" for string "1")
- Update test data setup to use encoded keys in storage
- Fix verifyConsistency helper to decode storage keys properly
- All 17 failing tests now correctly expect the encoded format

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

* fix: update acceptMutations tests to use encoded storage keys

Tests were expecting unencoded keys (e.g., 'tx-1') but the new type-safe
encoding stores string keys with the 's:' prefix (e.g., 's:tx-1').

Updated 6 test cases to access parsed storage with correct encoded keys.

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

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Kevin <[email protected]>

Author: 4 people

.changeset/fix-numeric-id-localStorage.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Fix localStorage collections to properly handle numeric and string IDs without collisions. Previously, operations could target the wrong item when using numeric IDs (e.g., `id: 1`, `id: 2`) after the page reloaded, due to a type mismatch between numeric keys in memory and stringified keys from localStorage. Keys are now encoded with type prefixes (`n:` for numbers, `s:` for strings) to prevent all possible collisions between different key types.

packages/db/src/local-storage.ts

@@ -152,6 +152,43 @@ function generateUuid(): string {
   return crypto.randomUUID()
 }
 
+/**
+ * Encodes a key (string or number) into a storage-safe string format.
+ * This prevents collisions between numeric and string keys by prefixing with type information.
+ *
+ * Examples:
+ *   - number 1 → "n:1"
+ *   - string "1" → "s:1"
+ *   - string "n:1" → "s:n:1"
+ *
+ * @param key - The key to encode (string or number)
+ * @returns Type-prefixed string that is safe for storage
+ */
+function encodeStorageKey(key: string | number): string {
+  if (typeof key === `number`) {
+    return `n:${key}`
+  }
+  return `s:${key}`
+}
+
+/**
+ * Decodes a storage key back to its original form.
+ * This is the inverse of encodeStorageKey.
+ *
+ * @param encodedKey - The encoded key from storage
+ * @returns The original key (string or number)
+ */
+function decodeStorageKey(encodedKey: string): string | number {
+  if (encodedKey.startsWith(`n:`)) {
+    return Number(encodedKey.slice(2))
+  }
+  if (encodedKey.startsWith(`s:`)) {
+    return encodedKey.slice(2)
+  }
+  // Fallback for legacy data without encoding
+  return encodedKey
+}
+
 /**
  * Creates an in-memory storage implementation that mimics the StorageApi interface
  * Used as a fallback when localStorage is not available (e.g., server-side rendering)
@@ -365,7 +402,7 @@ export function localStorageCollectionOptions(
       // Convert Map to object format for storage
       const objectData: Record<string, StoredItem<any>> = {}
       dataMap.forEach((storedItem, key) => {
-        objectData[String(key)] = storedItem
+        objectData[encodeStorageKey(key)] = storedItem
       })
       const serialized = parser.stringify(objectData)
       storage.setItem(config.storageKey, serialized)
@@ -415,12 +452,11 @@ export function localStorageCollectionOptions(
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
       // Use the engine's pre-computed key for consistency
-      const key = mutation.key
       const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
-      lastKnownData.set(key, storedItem)
+      lastKnownData.set(mutation.key, storedItem)
     })
 
     // Save to storage
@@ -450,12 +486,11 @@ export function localStorageCollectionOptions(
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
       // Use the engine's pre-computed key for consistency
-      const key = mutation.key
       const storedItem: StoredItem<any> = {
         versionKey: generateUuid(),
         data: mutation.modified,
       }
-      lastKnownData.set(key, storedItem)
+      lastKnownData.set(mutation.key, storedItem)
     })
 
     // Save to storage
@@ -480,8 +515,7 @@ export function localStorageCollectionOptions(
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
       // Use the engine's pre-computed key for consistency
-      const key = mutation.key
-      lastKnownData.delete(key)
+      lastKnownData.delete(mutation.key)
     })
 
     // Save to storage
@@ -547,20 +581,18 @@ export function localStorageCollectionOptions(
     // Apply each mutation
     for (const mutation of collectionMutations) {
       // Use the engine's pre-computed key to avoid key derivation issues
-      const key = mutation.key
-
       switch (mutation.type) {
         case `insert`:
         case `update`: {
           const storedItem: StoredItem<Record<string, unknown>> = {
             versionKey: generateUuid(),
             data: mutation.modified,
           }
-          lastKnownData.set(key, storedItem)
+          lastKnownData.set(mutation.key, storedItem)
           break
         }
         case `delete`: {
-          lastKnownData.delete(key)
+          lastKnownData.delete(mutation.key)
           break
         }
       }
@@ -616,7 +648,7 @@ function loadFromStorage<T extends object>(
       parsed !== null &&
       !Array.isArray(parsed)
     ) {
-      Object.entries(parsed).forEach(([key, value]) => {
+      Object.entries(parsed).forEach(([encodedKey, value]) => {
         // Runtime check to ensure the value has the expected StoredItem structure
         if (
           value &&
@@ -625,9 +657,10 @@ function loadFromStorage<T extends object>(
           `data` in value
         ) {
           const storedItem = value as StoredItem<T>
-          dataMap.set(key, storedItem)
+          const decodedKey = decodeStorageKey(encodedKey)
+          dataMap.set(decodedKey, storedItem)
         } else {
-          throw new InvalidStorageDataFormatError(storageKey, key)
+          throw new InvalidStorageDataFormatError(storageKey, encodedKey)
         }
       })
     } else {