Open History to see the last commit
1---
2id: BasicIndex
3title: BasicIndex
4---
5
6Defined in: [packages/db/src/indexes/basic-index.ts:37](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L37)
7
8Basic index using Map + sorted Array.
9
10- Map for O(1) equality lookups
11- Sorted Array for O(log n) range queries via binary search
12- O(n) updates to maintain sort order
13
14Simpler and smaller than BTreeIndex, good for read-heavy workloads.
15Use BTreeIndex for write-heavy workloads with large collections.
16
17## Extends
18
19- [`BaseIndex`](BaseIndex.md)\<`TKey`\>
20
21## Type Parameters
22
23### TKey
24
25`TKey` *extends* `string` \| `number` = `string` \| `number`
26
27## Constructors
28
29### Constructor
30
31```ts
32new BasicIndex<TKey>(
33 id,
34 expression,
35 name?,
36options?): BasicIndex<TKey>;
37```
38
39Defined in: [packages/db/src/indexes/base-index.ts:158](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L158)
40
41#### Parameters
42
43##### id
44
45`number`
46
47##### expression
48
49[`BasicExpression`](../@tanstack/namespaces/IR/type-aliases/BasicExpression.md)
50
51##### name?
52
53`string`
54
55##### options?
56
57`any`
58
59#### Returns
60
61`BasicIndex`\<`TKey`\>
62
63#### Inherited from
64
65[`BaseIndex`](BaseIndex.md).[`constructor`](BaseIndex.md#constructor)
66
67## Properties
68
69### compareFn()
70
71```ts
72protected readonly compareFn: (a, b) => number;
73```
74
75Defined in: [packages/db/src/indexes/base-index.ts:149](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L149)
76
77Orders indexed values. Every result is checked, because a custom
78comparator or custom collation may be supplied by the user.
79
80#### Parameters
81
82##### a
83
84`any`
85
86##### b
87
88`any`
89
90#### Returns
91
92`number`
93
94#### Inherited from
95
96[`BaseIndex`](BaseIndex.md).[`compareFn`](BaseIndex.md#comparefn)
97
98***
99
100### compareOptions
101
102```ts
103protected readonly compareOptions: CompareOptions;
104```
105
106Defined in: [packages/db/src/indexes/base-index.ts:144](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L144)
107
108#### Inherited from
109
110[`BaseIndex`](BaseIndex.md).[`compareOptions`](BaseIndex.md#compareoptions)
111
112***
113
114### expression
115
116```ts
117readonly expression: BasicExpression;
118```
119
120Defined in: [packages/db/src/indexes/base-index.ts:142](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L142)
121
122#### Inherited from
123
124[`BaseIndex`](BaseIndex.md).[`expression`](BaseIndex.md#expression)
125
126***
127
128### hasCustomComparator
129
130```ts
131protected readonly hasCustomComparator: boolean;
132```
133
134Defined in: [packages/db/src/indexes/base-index.ts:155](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L155)
135
136A user-supplied comparator's ordering may not match the WHERE evaluator's
137relational operators.
138
139#### Inherited from
140
141[`BaseIndex`](BaseIndex.md).[`hasCustomComparator`](BaseIndex.md#hascustomcomparator)
142
143***
144
145### id
146
147```ts
148readonly id: number;
149```
150
151Defined in: [packages/db/src/indexes/base-index.ts:140](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L140)
152
153#### Inherited from
154
155[`BaseIndex`](BaseIndex.md).[`id`](BaseIndex.md#id)
156
157***
158
159### name?
160
161```ts
162readonly optional name: string;
163```
164
165Defined in: [packages/db/src/indexes/base-index.ts:141](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L141)
166
167#### Inherited from
168
169[`BaseIndex`](BaseIndex.md).[`name`](BaseIndex.md#name)
170
171***
172
173### supportedOperations
174
175```ts
176readonly supportedOperations: Set<"eq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "ilike">;
177```
178
179Defined in: [packages/db/src/indexes/base-index.ts:143](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L143)
180
181#### Inherited from
182
183[`BaseIndex`](BaseIndex.md).[`supportedOperations`](BaseIndex.md#supportedoperations)
184
185## Accessors
186
187### keyCount
188
189#### Get Signature
190
191```ts
192get keyCount(): number;
193```
194
195Defined in: [packages/db/src/indexes/basic-index.ts:234](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L234)
196
197Gets the number of indexed keys
198
199##### Returns
200
201`number`
202
203#### Overrides
204
205[`BaseIndex`](BaseIndex.md).[`keyCount`](BaseIndex.md#keycount)
206
207***
208
209### supportsOrderOptimization
210
211#### Get Signature
212
213```ts
214get supportsOrderOptimization(): boolean;
215```
216
217Defined in: [packages/db/src/indexes/base-index.ts:259](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L259)
218
219Whether a query can use this index for its declared ordered prefix.
220
221##### Returns
222
223`boolean`
224
225Whether a query can use this index for its declared ordered prefix.
226
227#### Inherited from
228
229[`BaseIndex`](BaseIndex.md).[`supportsOrderOptimization`](BaseIndex.md#supportsorderoptimization)
230
231***
232
233### supportsRangeOptimization
234
235#### Get Signature
236
237```ts
238get supportsRangeOptimization(): boolean;
239```
240
241Defined in: [packages/db/src/indexes/base-index.ts:255](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L255)
242
243Whether range lookups (gt/gte/lt/lte) on this index can be trusted to
244return every matching key. Range traversal relies on the index ordering, so
245it is unsafe when the index uses a custom comparator, whose order may not
246match the WHERE evaluator's relational operators. Callers must fall back to
247a full scan when this is `false`.
248
249##### Returns
250
251`boolean`
252
253#### Inherited from
254
255[`BaseIndex`](BaseIndex.md).[`supportsRangeOptimization`](BaseIndex.md#supportsrangeoptimization)
256
257## Methods
258
259### add()
260
261```ts
262add(key, item): void;
263```
264
265Defined in: [packages/db/src/indexes/basic-index.ts:51](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L51)
266
267Adds a value to the index
268
269#### Parameters
270
271##### key
272
273`TKey`
274
275##### item
276
277`any`
278
279#### Returns
280
281`void`
282
283#### Overrides
284
285[`BaseIndex`](BaseIndex.md).[`add`](BaseIndex.md#add)
286
287***
288
289### addRangeValue()
290
291```ts
292protected addRangeValue(value): void;
293```
294
295Defined in: [packages/db/src/indexes/base-index.ts:277](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L277)
296
297#### Parameters
298
299##### value
300
301`unknown`
302
303#### Returns
304
305`void`
306
307#### Inherited from
308
309[`BaseIndex`](BaseIndex.md).[`addRangeValue`](BaseIndex.md#addrangevalue)
310
311***
312
313### build()
314
315```ts
316build(entries): void;
317```
318
319Defined in: [packages/db/src/indexes/basic-index.ts:182](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L182)
320
321Builds the index from a collection of entries
322
323#### Parameters
324
325##### entries
326
327`Iterable`\<\[`TKey`, `any`\]\>
328
329#### Returns
330
331`void`
332
333#### Overrides
334
335[`BaseIndex`](BaseIndex.md).[`build`](BaseIndex.md#build)
336
337***
338
339### canOptimizeRangeFor()
340
341```ts
342canOptimizeRangeFor(value): boolean;
343```
344
345Defined in: [packages/db/src/indexes/base-index.ts:299](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L299)
346
347Whether the live values in this index share the predicate operand's
348relational domain. Mixed domains can sort differently in the index and
349WHERE evaluator, which can make a range lookup omit matching rows.
350
351#### Parameters
352
353##### value
354
355`unknown`
356
357#### Returns
358
359`boolean`
360
361#### Inherited from
362
363[`BaseIndex`](BaseIndex.md).[`canOptimizeRangeFor`](BaseIndex.md#canoptimizerangefor)
364
365***
366
367### clear()
368
369```ts
370clear(): void;
371```
372
373Defined in: [packages/db/src/indexes/basic-index.ts:213](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L213)
374
375Clears all data from the index
376
377#### Returns
378
379`void`
380
381#### Overrides
382
383[`BaseIndex`](BaseIndex.md).[`clear`](BaseIndex.md#clear)
384
385***
386
387### clearRangeValues()
388
389```ts
390protected clearRangeValues(): void;
391```
392
393Defined in: [packages/db/src/indexes/base-index.ts:295](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L295)
394
395#### Returns
396
397`void`
398
399#### Inherited from
400
401[`BaseIndex`](BaseIndex.md).[`clearRangeValues`](BaseIndex.md#clearrangevalues)
402
403***
404
405### equalityLookup()
406
407```ts
408equalityLookup(value): Set<TKey>;
409```
410
411Defined in: [packages/db/src/indexes/basic-index.ts:241](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L241)
412
413Performs an equality lookup - O(1)
414
415#### Parameters
416
417##### value
418
419`any`
420
421#### Returns
422
423`Set`\<`TKey`\>
424
425#### Overrides
426
427[`BaseIndex`](BaseIndex.md).[`equalityLookup`](BaseIndex.md#equalitylookup)
428
429***
430
431### evaluateAddedValue()
432
433```ts
434protected evaluateAddedValue(key, item): any;
435```
436
437Defined in: [packages/db/src/indexes/base-index.ts:374](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L374)
438
439The indexed value of a row being added. A throwing expression fails the write.
440
441#### Parameters
442
443##### key
444
445`TKey`
446
447##### item
448
449`any`
450
451#### Returns
452
453`any`
454
455#### Inherited from
456
457[`BaseIndex`](BaseIndex.md).[`evaluateAddedValue`](BaseIndex.md#evaluateaddedvalue)
458
459***
460
461### evaluateIndexExpression()
462
463```ts
464protected evaluateIndexExpression(item): any;
465```
466
467Defined in: [packages/db/src/indexes/base-index.ts:367](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L367)
468
469#### Parameters
470
471##### item
472
473`any`
474
475#### Returns
476
477`any`
478
479#### Inherited from
480
481[`BaseIndex`](BaseIndex.md).[`evaluateIndexExpression`](BaseIndex.md#evaluateindexexpression)
482
483***
484
485### exactBucketKeys()
486
487```ts
488protected exactBucketKeys(value): Iterable<TKey, any, any> | undefined;
489```
490
491Defined in: [packages/db/src/indexes/base-index.ts:205](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L205)
492
493#### Parameters
494
495##### value
496
497`any`
498
499#### Returns
500
501`Iterable`\<`TKey`, `any`, `any`\> \| `undefined`
502
503#### Inherited from
504
505[`BaseIndex`](BaseIndex.md).[`exactBucketKeys`](BaseIndex.md#exactbucketkeys)
506
507***
508
509### inArrayLookup()
510
511```ts
512inArrayLookup(values): Set<TKey>;
513```
514
515Defined in: [packages/db/src/indexes/base-index.ts:228](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L228)
516
517Combine exact buckets without copying each bucket first.
518
519#### Parameters
520
521##### values
522
523`any`[]
524
525#### Returns
526
527`Set`\<`TKey`\>
528
529#### Inherited from
530
531[`BaseIndex`](BaseIndex.md).[`inArrayLookup`](BaseIndex.md#inarraylookup)
532
533***
534
535### initialize()
536
537```ts
538protected initialize(_options?): void;
539```
540
541Defined in: [packages/db/src/indexes/base-index.ts:365](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L365)
542
543#### Parameters
544
545##### \_options?
546
547`any`
548
549#### Returns
550
551`void`
552
553#### Inherited from
554
555[`BaseIndex`](BaseIndex.md).[`initialize`](BaseIndex.md#initialize)
556
557***
558
559### lookup()
560
561```ts
562lookup(operation, value): Set<TKey>;
563```
564
565Defined in: [packages/db/src/indexes/basic-index.ts:221](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L221)
566
567#### Parameters
568
569##### operation
570
571`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
572
573##### value
574
575`any`
576
577#### Returns
578
579`Set`\<`TKey`\>
580
581#### Overrides
582
583[`BaseIndex`](BaseIndex.md).[`lookup`](BaseIndex.md#lookup)
584
585***
586
587### lookupSupportedOperation()
588
589```ts
590protected lookupSupportedOperation(operation, value): Set<TKey> | undefined;
591```
592
593Defined in: [packages/db/src/indexes/base-index.ts:211](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L211)
594
595#### Parameters
596
597##### operation
598
599`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
600
601##### value
602
603`any`
604
605#### Returns
606
607`Set`\<`TKey`\> \| `undefined`
608
609#### Inherited from
610
611[`BaseIndex`](BaseIndex.md).[`lookupSupportedOperation`](BaseIndex.md#lookupsupportedoperation)
612
613***
614
615### matchesCompareOptions()
616
617```ts
618matchesCompareOptions(compareOptions): boolean;
619```
620
621Defined in: [packages/db/src/indexes/base-index.ts:321](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L321)
622
623Checks if the compare options match the index's compare options.
624The direction is ignored because the index can be reversed if the direction is different.
625
626#### Parameters
627
628##### compareOptions
629
630`CompareOptions`
631
632#### Returns
633
634`boolean`
635
636#### Inherited from
637
638[`BaseIndex`](BaseIndex.md).[`matchesCompareOptions`](BaseIndex.md#matchescompareoptions)
639
640***
641
642### matchesDirection()
643
644```ts
645matchesDirection(direction): boolean;
646```
647
648Defined in: [packages/db/src/indexes/base-index.ts:361](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L361)
649
650Checks if the index matches the provided direction.
651
652#### Parameters
653
654##### direction
655
656[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md)
657
658#### Returns
659
660`boolean`
661
662#### Inherited from
663
664[`BaseIndex`](BaseIndex.md).[`matchesDirection`](BaseIndex.md#matchesdirection)
665
666***
667
668### matchesField()
669
670```ts
671matchesField(fieldPath): boolean;
672```
673
674Defined in: [packages/db/src/indexes/base-index.ts:309](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L309)
675
676#### Parameters
677
678##### fieldPath
679
680`string`[]
681
682#### Returns
683
684`boolean`
685
686#### Inherited from
687
688[`BaseIndex`](BaseIndex.md).[`matchesField`](BaseIndex.md#matchesfield)
689
690***
691
692### rangeQuery()
693
694```ts
695rangeQuery(options): Set<TKey>;
696```
697
698Defined in: [packages/db/src/indexes/basic-index.ts:249](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L249)
699
700Performs a range query using binary search - O(log n + m)
701
702#### Parameters
703
704##### options
705
706[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}`
707
708#### Returns
709
710`Set`\<`TKey`\>
711
712#### Overrides
713
714[`BaseIndex`](BaseIndex.md).[`rangeQuery`](BaseIndex.md#rangequery)
715
716***
717
718### rangeQueryReversed()
719
720```ts
721rangeQueryReversed(options): Set<TKey>;
722```
723
724Defined in: [packages/db/src/indexes/base-index.ts:237](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L237)
725
726#### Parameters
727
728##### options
729
730[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}`
731
732#### Returns
733
734`Set`\<`TKey`\>
735
736#### Inherited from
737
738[`BaseIndex`](BaseIndex.md).[`rangeQueryReversed`](BaseIndex.md#rangequeryreversed)
739
740***
741
742### remove()
743
744```ts
745remove(key, item): void;
746```
747
748Defined in: [packages/db/src/indexes/basic-index.ts:88](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L88)
749
750Removes a value from the index
751
752#### Parameters
753
754##### key
755
756`TKey`
757
758##### item
759
760`any`
761
762#### Returns
763
764`void`
765
766#### Overrides
767
768[`BaseIndex`](BaseIndex.md).[`remove`](BaseIndex.md#remove)
769
770***
771
772### removeRangeValue()
773
774```ts
775protected removeRangeValue(value): void;
776```
777
778Defined in: [packages/db/src/indexes/base-index.ts:286](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L286)
779
780#### Parameters
781
782##### value
783
784`unknown`
785
786#### Returns
787
788`void`
789
790#### Inherited from
791
792[`BaseIndex`](BaseIndex.md).[`removeRangeValue`](BaseIndex.md#removerangevalue)
793
794***
795
796### supports()
797
798```ts
799supports(operation): boolean;
800```
801
802Defined in: [packages/db/src/indexes/base-index.ts:251](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L251)
803
804#### Parameters
805
806##### operation
807
808`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
809
810#### Returns
811
812`boolean`
813
814#### Inherited from
815
816[`BaseIndex`](BaseIndex.md).[`supports`](BaseIndex.md#supports)
817
818***
819
820### take()
821
822```ts
823take(
824 n,
825 from,
826 filterFn?): TKey[];
827```
828
829Defined in: [packages/db/src/indexes/basic-index.ts:313](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L313)
830
831Returns the next n items in sorted order
832
833#### Parameters
834
835##### n
836
837`number`
838
839##### from
840
841`any`
842
843##### filterFn?
844
845(`key`) => `boolean`
846
847#### Returns
848
849`TKey`[]
850
851#### Overrides
852
853[`BaseIndex`](BaseIndex.md).[`take`](BaseIndex.md#take)
854
855***
856
857### takeFromStart()
858
859```ts
860takeFromStart(n, filterFn?): TKey[];
861```
862
863Defined in: [packages/db/src/indexes/basic-index.ts:360](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L360)
864
865Returns the first n items in sorted order (from the start)
866
867#### Parameters
868
869##### n
870
871`number`
872
873##### filterFn?
874
875(`key`) => `boolean`
876
877#### Returns
878
879`TKey`[]
880
881#### Overrides
882
883[`BaseIndex`](BaseIndex.md).[`takeFromStart`](BaseIndex.md#takefromstart)
884
885***
886
887### takeReversed()
888
889```ts
890takeReversed(
891 n,
892 from,
893 filterFn?): TKey[];
894```
895
896Defined in: [packages/db/src/indexes/basic-index.ts:334](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L334)
897
898Returns the next n items in reverse sorted order
899
900#### Parameters
901
902##### n
903
904`number`
905
906##### from
907
908`any`
909
910##### filterFn?
911
912(`key`) => `boolean`
913
914#### Returns
915
916`TKey`[]
917
918#### Overrides
919
920[`BaseIndex`](BaseIndex.md).[`takeReversed`](BaseIndex.md#takereversed)
921
922***
923
924### takeReversedFromEnd()
925
926```ts
927takeReversedFromEnd(n, filterFn?): TKey[];
928```
929
930Defined in: [packages/db/src/indexes/basic-index.ts:367](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L367)
931
932Returns the first n items in reverse sorted order (from the end)
933
934#### Parameters
935
936##### n
937
938`number`
939
940##### filterFn?
941
942(`key`) => `boolean`
943
944#### Returns
945
946`TKey`[]
947
948#### Overrides
949
950[`BaseIndex`](BaseIndex.md).[`takeReversedFromEnd`](BaseIndex.md#takereversedfromend)
951
952***
953
954### update()
955
956```ts
957update(
958 key,
959 oldItem,
960 newItem): void;
961```
962
963Defined in: [packages/db/src/indexes/basic-index.ts:148](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L148)
964
965Updates a value in the index
966
967#### Parameters
968
969##### key
970
971`TKey`
972
973##### oldItem
974
975`any`
976
977##### newItem
978
979`any`
980
981#### Returns
982
983`void`
984
985#### Overrides
986
987[`BaseIndex`](BaseIndex.md).[`update`](BaseIndex.md#update)