test: add comprehensive tests for BTreeIndex undefined value handling by KyleAMathews · Pull Request #1200 · TanStack/db

KyleAMathews · 2026-01-29T16:34:52Z

Summary

Adds comprehensive unit tests to verify the sentinel mechanism introduced in #1191 that fixes the infinite loop issue (#1186). These tests ensure the fix remains robust with 20 test cases covering all edge cases.

Test Coverage

Core Disambiguation

take vs takeFromStart - Verifies take(n, undefined) returns items after the key undefined, while takeFromStart(n) starts from the beginning
takeReversed vs takeReversedFromEnd - Same disambiguation for reverse iteration

Multiple Undefined Values

Storage, retrieval, and removal of multiple items with undefined indexed values
Iteration past multiple undefined values correctly

Ordering

Sort order of undefined relative to numbers, strings, and null values
Custom comparator receives actual undefined, not the sentinel string

Lookups & Queries

equalityLookup(undefined) - Lookup behavior for undefined values
inArrayLookup with undefined - Array lookups containing undefined
rangeQuery with undefined bounds - Explicit { from: undefined } vs omitted parameter

Operations

update transitioning to/from undefined - Verifies index correctness when values change between defined and undefined states
valueMapData getter - Verifies denormalization in returned Map (sentinel not exposed)

Approach

Tests directly exercise the BTreeIndex class methods with explicit undefined values to verify:

The sentinel (UNDEFINED_SENTINEL) correctly distinguishes "start from beginning" vs "key is undefined"
User-facing APIs never expose the sentinel string
Custom comparators receive actual undefined values

Verification

pnpm --filter @tanstack/db test -- --run btree-index-undefined-values

All 20 tests pass.

Files Changed

File	Changes
`packages/db/tests/btree-index-undefined-values.test.ts`	+296 lines of unit tests

Relates to #1191, #1186

🤖 Generated with Claude Code

Add unit tests to verify the sentinel mechanism that distinguishes "start from beginning" from "the key is literally undefined": - take(n, undefined) vs takeFromStart(n) disambiguation - takeReversed(n, undefined) vs takeReversedFromEnd(n) - Multiple items with undefined indexed values - Ordering of undefined relative to numbers, strings, and null - rangeQuery with explicit undefined bounds vs omitted parameter - Custom comparator receives actual undefined, not sentinel - equalityLookup(undefined) behavior - valueMapData getter returns denormalized keys Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

changeset-bot · 2026-01-29T16:34:57Z

⚠️ No Changeset found

Latest commit: 8ccf798

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2026-01-29T16:36:37Z

More templates

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1200

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1200

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1200

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1200

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1200

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1200

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1200

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1200

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1200

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1200

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1200

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1200

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1200

commit: 8ccf798

github-actions · 2026-01-29T16:37:16Z

Size Change: 0 B

Total Size: 92 kB

ℹ️ View Unchanged

Filename	Size
`./packages/db/dist/esm/collection/change-events.js`	1.39 kB
`./packages/db/dist/esm/collection/changes.js`	1.22 kB
`./packages/db/dist/esm/collection/events.js`	388 B
`./packages/db/dist/esm/collection/index.js`	3.32 kB
`./packages/db/dist/esm/collection/indexes.js`	1.1 kB
`./packages/db/dist/esm/collection/lifecycle.js`	1.75 kB
`./packages/db/dist/esm/collection/mutations.js`	2.34 kB
`./packages/db/dist/esm/collection/state.js`	3.49 kB
`./packages/db/dist/esm/collection/subscription.js`	3.71 kB
`./packages/db/dist/esm/collection/sync.js`	2.41 kB
`./packages/db/dist/esm/deferred.js`	207 B
`./packages/db/dist/esm/errors.js`	4.7 kB
`./packages/db/dist/esm/event-emitter.js`	748 B
`./packages/db/dist/esm/index.js`	2.69 kB
`./packages/db/dist/esm/indexes/auto-index.js`	742 B
`./packages/db/dist/esm/indexes/base-index.js`	766 B
`./packages/db/dist/esm/indexes/btree-index.js`	2.17 kB
`./packages/db/dist/esm/indexes/lazy-index.js`	1.1 kB
`./packages/db/dist/esm/indexes/reverse-index.js`	538 B
`./packages/db/dist/esm/local-only.js`	837 B
`./packages/db/dist/esm/local-storage.js`	2.1 kB
`./packages/db/dist/esm/optimistic-action.js`	359 B
`./packages/db/dist/esm/paced-mutations.js`	496 B
`./packages/db/dist/esm/proxy.js`	3.75 kB
`./packages/db/dist/esm/query/builder/functions.js`	733 B
`./packages/db/dist/esm/query/builder/index.js`	4.09 kB
`./packages/db/dist/esm/query/builder/ref-proxy.js`	1.05 kB
`./packages/db/dist/esm/query/compiler/evaluators.js`	1.42 kB
`./packages/db/dist/esm/query/compiler/expressions.js`	430 B
`./packages/db/dist/esm/query/compiler/group-by.js`	1.81 kB
`./packages/db/dist/esm/query/compiler/index.js`	2.02 kB
`./packages/db/dist/esm/query/compiler/joins.js`	2.07 kB
`./packages/db/dist/esm/query/compiler/order-by.js`	1.45 kB
`./packages/db/dist/esm/query/compiler/select.js`	1.06 kB
`./packages/db/dist/esm/query/expression-helpers.js`	1.43 kB
`./packages/db/dist/esm/query/ir.js`	673 B
`./packages/db/dist/esm/query/live-query-collection.js`	360 B
`./packages/db/dist/esm/query/live/collection-config-builder.js`	5.43 kB
`./packages/db/dist/esm/query/live/collection-registry.js`	264 B
`./packages/db/dist/esm/query/live/collection-subscriber.js`	2.42 kB
`./packages/db/dist/esm/query/live/internal.js`	145 B
`./packages/db/dist/esm/query/optimizer.js`	2.56 kB
`./packages/db/dist/esm/query/predicate-utils.js`	2.97 kB
`./packages/db/dist/esm/query/subset-dedupe.js`	921 B
`./packages/db/dist/esm/scheduler.js`	1.3 kB
`./packages/db/dist/esm/SortedMap.js`	1.3 kB
`./packages/db/dist/esm/strategies/debounceStrategy.js`	247 B
`./packages/db/dist/esm/strategies/queueStrategy.js`	428 B
`./packages/db/dist/esm/strategies/throttleStrategy.js`	246 B
`./packages/db/dist/esm/transactions.js`	2.9 kB
`./packages/db/dist/esm/utils.js`	924 B
`./packages/db/dist/esm/utils/browser-polyfills.js`	304 B
`./packages/db/dist/esm/utils/btree.js`	5.61 kB
`./packages/db/dist/esm/utils/comparison.js`	952 B
`./packages/db/dist/esm/utils/cursor.js`	457 B
`./packages/db/dist/esm/utils/index-optimization.js`	1.51 kB
`./packages/db/dist/esm/utils/type-guards.js`	157 B

_{compressed-size-action::db-package-size}

github-actions · 2026-01-29T16:37:54Z

Size Change: 0 B

Total Size: 3.7 kB

ℹ️ View Unchanged

Filename	Size
`./packages/react-db/dist/esm/index.js`	225 B
`./packages/react-db/dist/esm/useLiveInfiniteQuery.js`	1.17 kB
`./packages/react-db/dist/esm/useLiveQuery.js`	1.34 kB
`./packages/react-db/dist/esm/useLiveSuspenseQuery.js`	559 B
`./packages/react-db/dist/esm/usePacedMutations.js`	401 B

_{compressed-size-action::react-db-package-size}

Add tests suggested by PR review: - inArrayLookup with undefined values in the lookup array - update operation transitioning to/from undefined values - take iteration past multiple undefined values Also includes code simplification from review: - Added createIndex helper function - Consolidated verbose assertions - Improved type safety (unknown vs any) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

kevin-dp

These unit tests are a great addition. We just need to rename that test file.

Rename btree-index-undefined-key-infinite-loop.test.ts to btree-index-undefined-values.test.ts since the tests now cover comprehensive undefined value handling, not just the infinite loop fix. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

kevin-dp approved these changes Jan 29, 2026

View reviewed changes

KyleAMathews merged commit 12917e0 into main Jan 29, 2026
7 checks passed

KyleAMathews deleted the kyle/add-btree-undefined-tests branch January 29, 2026 17:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

test: add comprehensive tests for BTreeIndex undefined value handling#1200

test: add comprehensive tests for BTreeIndex undefined value handling#1200
KyleAMathews merged 3 commits intomainfrom
kyle/add-btree-undefined-tests

KyleAMathews commented Jan 29, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 29, 2026 •

edited

Loading

Uh oh!

kevin-dp left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

KyleAMathews commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Coverage

Core Disambiguation

Multiple Undefined Values

Ordering

Lookups & Queries

Operations

Approach

Verification

Files Changed

Uh oh!

changeset-bot bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kevin-dp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

KyleAMathews commented Jan 29, 2026 •

edited

Loading

changeset-bot bot commented Jan 29, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 29, 2026 •

edited

Loading

github-actions bot commented Jan 29, 2026 •

edited

Loading

github-actions bot commented Jan 29, 2026 •

edited

Loading