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

BasicIndex.md

944 lines16.4 KB

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