Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

BasicIndex.md

987 lines16.9 KB

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)