Open History to see the last commit
1---
2id: BasicIndex
3title: BasicIndex
4---
5
6Defined in: [packages/db/src/indexes/basic-index.ts:44](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L44)
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:140](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L140)
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:131](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L131)
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:126](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L126)
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:124](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L124)
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:137](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L137)
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:122](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L122)
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:123](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L123)
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/basic-index.ts:47](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L47)
180
181#### Overrides
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:260](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L260)
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### supportsRangeOptimization
210
211#### Get Signature
212
213```ts
214get supportsRangeOptimization(): boolean;
215```
216
217Defined in: [packages/db/src/indexes/base-index.ts:206](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L206)
218
219Whether range lookups (gt/gte/lt/lte) on this index can be trusted to
220return every matching key. Range traversal relies on the index ordering, so
221it is unsafe when the index uses a custom comparator, whose order may not
222match the WHERE evaluator's relational operators. Callers must fall back to
223a full scan when this is `false`.
224
225##### Returns
226
227`boolean`
228
229#### Inherited from
230
231[`BaseIndex`](BaseIndex.md).[`supportsRangeOptimization`](BaseIndex.md#supportsrangeoptimization)
232
233## Methods
234
235### add()
236
237```ts
238add(key, item): void;
239```
240
241Defined in: [packages/db/src/indexes/basic-index.ts:68](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L68)
242
243Adds a value to the index
244
245#### Parameters
246
247##### key
248
249`TKey`
250
251##### item
252
253`any`
254
255#### Returns
256
257`void`
258
259#### Overrides
260
261[`BaseIndex`](BaseIndex.md).[`add`](BaseIndex.md#add)
262
263***
264
265### addRangeValue()
266
267```ts
268protected addRangeValue(value): void;
269```
270
271Defined in: [packages/db/src/indexes/base-index.ts:210](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L210)
272
273#### Parameters
274
275##### value
276
277`unknown`
278
279#### Returns
280
281`void`
282
283#### Inherited from
284
285[`BaseIndex`](BaseIndex.md).[`addRangeValue`](BaseIndex.md#addrangevalue)
286
287***
288
289### build()
290
291```ts
292build(entries): void;
293```
294
295Defined in: [packages/db/src/indexes/basic-index.ts:187](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L187)
296
297Builds the index from a collection of entries
298
299#### Parameters
300
301##### entries
302
303`Iterable`\<\[`TKey`, `any`\]\>
304
305#### Returns
306
307`void`
308
309#### Overrides
310
311[`BaseIndex`](BaseIndex.md).[`build`](BaseIndex.md#build)
312
313***
314
315### canOptimizeRangeFor()
316
317```ts
318canOptimizeRangeFor(value): boolean;
319```
320
321Defined in: [packages/db/src/indexes/base-index.ts:232](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L232)
322
323Whether the live values in this index share the predicate operand's
324relational domain. Mixed domains can sort differently in the index and
325WHERE evaluator, which can make a range lookup omit matching rows.
326
327#### Parameters
328
329##### value
330
331`unknown`
332
333#### Returns
334
335`boolean`
336
337#### Inherited from
338
339[`BaseIndex`](BaseIndex.md).[`canOptimizeRangeFor`](BaseIndex.md#canoptimizerangefor)
340
341***
342
343### clear()
344
345```ts
346clear(): void;
347```
348
349Defined in: [packages/db/src/indexes/basic-index.ts:215](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L215)
350
351Clears all data from the index
352
353#### Returns
354
355`void`
356
357#### Overrides
358
359[`BaseIndex`](BaseIndex.md).[`clear`](BaseIndex.md#clear)
360
361***
362
363### clearRangeValues()
364
365```ts
366protected clearRangeValues(): void;
367```
368
369Defined in: [packages/db/src/indexes/base-index.ts:228](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L228)
370
371#### Returns
372
373`void`
374
375#### Inherited from
376
377[`BaseIndex`](BaseIndex.md).[`clearRangeValues`](BaseIndex.md#clearrangevalues)
378
379***
380
381### equalityLookup()
382
383```ts
384equalityLookup(value): Set<TKey>;
385```
386
387Defined in: [packages/db/src/indexes/basic-index.ts:267](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L267)
388
389Performs an equality lookup - O(1)
390
391#### Parameters
392
393##### value
394
395`any`
396
397#### Returns
398
399`Set`\<`TKey`\>
400
401#### Overrides
402
403[`BaseIndex`](BaseIndex.md).[`equalityLookup`](BaseIndex.md#equalitylookup)
404
405***
406
407### evaluateAddedValue()
408
409```ts
410protected evaluateAddedValue(key, item): any;
411```
412
413Defined in: [packages/db/src/indexes/base-index.ts:307](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L307)
414
415The indexed value of a row being added. A throwing expression fails the write.
416
417#### Parameters
418
419##### key
420
421`TKey`
422
423##### item
424
425`any`
426
427#### Returns
428
429`any`
430
431#### Inherited from
432
433[`BaseIndex`](BaseIndex.md).[`evaluateAddedValue`](BaseIndex.md#evaluateaddedvalue)
434
435***
436
437### evaluateIndexExpression()
438
439```ts
440protected evaluateIndexExpression(item): any;
441```
442
443Defined in: [packages/db/src/indexes/base-index.ts:300](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L300)
444
445#### Parameters
446
447##### item
448
449`any`
450
451#### Returns
452
453`any`
454
455#### Inherited from
456
457[`BaseIndex`](BaseIndex.md).[`evaluateIndexExpression`](BaseIndex.md#evaluateindexexpression)
458
459***
460
461### inArrayLookup()
462
463```ts
464inArrayLookup(values): Set<TKey>;
465```
466
467Defined in: [packages/db/src/indexes/basic-index.ts:437](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L437)
468
469Performs an IN array lookup - O(k) where k is values.length
470
471#### Parameters
472
473##### values
474
475`any`[]
476
477#### Returns
478
479`Set`\<`TKey`\>
480
481#### Overrides
482
483[`BaseIndex`](BaseIndex.md).[`inArrayLookup`](BaseIndex.md#inarraylookup)
484
485***
486
487### initialize()
488
489```ts
490protected initialize(_options?): void;
491```
492
493Defined in: [packages/db/src/indexes/basic-index.ts:63](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L63)
494
495#### Parameters
496
497##### \_options?
498
499[`BasicIndexOptions`](../interfaces/BasicIndexOptions.md)
500
501#### Returns
502
503`void`
504
505#### Overrides
506
507[`BaseIndex`](BaseIndex.md).[`initialize`](BaseIndex.md#initialize)
508
509***
510
511### lookup()
512
513```ts
514lookup(operation, value): Set<TKey>;
515```
516
517Defined in: [packages/db/src/indexes/basic-index.ts:225](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L225)
518
519Performs a lookup operation
520
521#### Parameters
522
523##### operation
524
525`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
526
527##### value
528
529`any`
530
531#### Returns
532
533`Set`\<`TKey`\>
534
535#### Overrides
536
537[`BaseIndex`](BaseIndex.md).[`lookup`](BaseIndex.md#lookup)
538
539***
540
541### matchesCompareOptions()
542
543```ts
544matchesCompareOptions(compareOptions): boolean;
545```
546
547Defined in: [packages/db/src/indexes/base-index.ts:254](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L254)
548
549Checks if the compare options match the index's compare options.
550The direction is ignored because the index can be reversed if the direction is different.
551
552#### Parameters
553
554##### compareOptions
555
556`CompareOptions`
557
558#### Returns
559
560`boolean`
561
562#### Inherited from
563
564[`BaseIndex`](BaseIndex.md).[`matchesCompareOptions`](BaseIndex.md#matchescompareoptions)
565
566***
567
568### matchesDirection()
569
570```ts
571matchesDirection(direction): boolean;
572```
573
574Defined in: [packages/db/src/indexes/base-index.ts:294](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L294)
575
576Checks if the index matches the provided direction.
577
578#### Parameters
579
580##### direction
581
582[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md)
583
584#### Returns
585
586`boolean`
587
588#### Inherited from
589
590[`BaseIndex`](BaseIndex.md).[`matchesDirection`](BaseIndex.md#matchesdirection)
591
592***
593
594### matchesField()
595
596```ts
597matchesField(fieldPath): boolean;
598```
599
600Defined in: [packages/db/src/indexes/base-index.ts:242](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L242)
601
602#### Parameters
603
604##### fieldPath
605
606`string`[]
607
608#### Returns
609
610`boolean`
611
612#### Inherited from
613
614[`BaseIndex`](BaseIndex.md).[`matchesField`](BaseIndex.md#matchesfield)
615
616***
617
618### rangeQuery()
619
620```ts
621rangeQuery(options): Set<TKey>;
622```
623
624Defined in: [packages/db/src/indexes/basic-index.ts:275](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L275)
625
626Performs a range query using binary search - O(log n + m)
627
628#### Parameters
629
630##### options
631
632[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}`
633
634#### Returns
635
636`Set`\<`TKey`\>
637
638#### Overrides
639
640[`BaseIndex`](BaseIndex.md).[`rangeQuery`](BaseIndex.md#rangequery)
641
642***
643
644### rangeQueryReversed()
645
646```ts
647rangeQueryReversed(options): Set<TKey>;
648```
649
650Defined in: [packages/db/src/indexes/base-index.ts:188](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L188)
651
652#### Parameters
653
654##### options
655
656[`BTreeRangeQueryOptions`](../interfaces/BTreeRangeQueryOptions.md) = `{}`
657
658#### Returns
659
660`Set`\<`TKey`\>
661
662#### Inherited from
663
664[`BaseIndex`](BaseIndex.md).[`rangeQueryReversed`](BaseIndex.md#rangequeryreversed)
665
666***
667
668### remove()
669
670```ts
671remove(key, item): void;
672```
673
674Defined in: [packages/db/src/indexes/basic-index.ts:99](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L99)
675
676Removes a value from the index
677
678#### Parameters
679
680##### key
681
682`TKey`
683
684##### item
685
686`any`
687
688#### Returns
689
690`void`
691
692#### Overrides
693
694[`BaseIndex`](BaseIndex.md).[`remove`](BaseIndex.md#remove)
695
696***
697
698### removeRangeValue()
699
700```ts
701protected removeRangeValue(value): void;
702```
703
704Defined in: [packages/db/src/indexes/base-index.ts:219](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L219)
705
706#### Parameters
707
708##### value
709
710`unknown`
711
712#### Returns
713
714`void`
715
716#### Inherited from
717
718[`BaseIndex`](BaseIndex.md).[`removeRangeValue`](BaseIndex.md#removerangevalue)
719
720***
721
722### supports()
723
724```ts
725supports(operation): boolean;
726```
727
728Defined in: [packages/db/src/indexes/base-index.ts:202](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L202)
729
730#### Parameters
731
732##### operation
733
734`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
735
736#### Returns
737
738`boolean`
739
740#### Inherited from
741
742[`BaseIndex`](BaseIndex.md).[`supports`](BaseIndex.md#supports)
743
744***
745
746### take()
747
748```ts
749take(
750 n,
751 from,
752 filterFn?): TKey[];
753```
754
755Defined in: [packages/db/src/indexes/basic-index.ts:339](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L339)
756
757Returns the next n items in sorted order
758
759#### Parameters
760
761##### n
762
763`number`
764
765##### from
766
767`any`
768
769##### filterFn?
770
771(`key`) => `boolean`
772
773#### Returns
774
775`TKey`[]
776
777#### Overrides
778
779[`BaseIndex`](BaseIndex.md).[`take`](BaseIndex.md#take)
780
781***
782
783### takeFromStart()
784
785```ts
786takeFromStart(n, filterFn?): TKey[];
787```
788
789Defined in: [packages/db/src/indexes/basic-index.ts:386](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L386)
790
791Returns the first n items in sorted order (from the start)
792
793#### Parameters
794
795##### n
796
797`number`
798
799##### filterFn?
800
801(`key`) => `boolean`
802
803#### Returns
804
805`TKey`[]
806
807#### Overrides
808
809[`BaseIndex`](BaseIndex.md).[`takeFromStart`](BaseIndex.md#takefromstart)
810
811***
812
813### takeReversed()
814
815```ts
816takeReversed(
817 n,
818 from,
819 filterFn?): TKey[];
820```
821
822Defined in: [packages/db/src/indexes/basic-index.ts:360](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L360)
823
824Returns the next n items in reverse sorted order
825
826#### Parameters
827
828##### n
829
830`number`
831
832##### from
833
834`any`
835
836##### filterFn?
837
838(`key`) => `boolean`
839
840#### Returns
841
842`TKey`[]
843
844#### Overrides
845
846[`BaseIndex`](BaseIndex.md).[`takeReversed`](BaseIndex.md#takereversed)
847
848***
849
850### takeReversedFromEnd()
851
852```ts
853takeReversedFromEnd(n, filterFn?): TKey[];
854```
855
856Defined in: [packages/db/src/indexes/basic-index.ts:393](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L393)
857
858Returns the first n items in reverse sorted order (from the end)
859
860#### Parameters
861
862##### n
863
864`number`
865
866##### filterFn?
867
868(`key`) => `boolean`
869
870#### Returns
871
872`TKey`[]
873
874#### Overrides
875
876[`BaseIndex`](BaseIndex.md).[`takeReversedFromEnd`](BaseIndex.md#takereversedfromend)
877
878***
879
880### update()
881
882```ts
883update(
884 key,
885 oldItem,
886 newItem): void;
887```
888
889Defined in: [packages/db/src/indexes/basic-index.ts:153](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L153)
890
891Updates a value in the index
892
893#### Parameters
894
895##### key
896
897`TKey`
898
899##### oldItem
900
901`any`
902
903##### newItem
904
905`any`
906
907#### Returns
908
909`void`
910
911#### Overrides
912
913[`BaseIndex`](BaseIndex.md).[`update`](BaseIndex.md#update)