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

BasicIndex.md

883 lines15.0 KB

1---
2id: BasicIndex
3title: BasicIndex
4---
5​
6Defined in: [packages/db/src/indexes/basic-index.ts:39](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L39)
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:139](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L139)
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:130](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L130)
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:125](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L125)
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:123](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L123)
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:136](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L136)
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:121](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L121)
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:122](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L122)
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:42](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L42)
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:271](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L271)
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:205](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L205)
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:63](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L63)
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:209](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L209)
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:194](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L194)
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:231](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L231)
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:230](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L230)
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:227](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L227)
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:278](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L278)
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### evaluateIndexExpression()
408​
409```ts
410protected evaluateIndexExpression(item): any;
411```
412​
413Defined in: [packages/db/src/indexes/base-index.ts:299](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L299)
414​
415#### Parameters
416​
417##### item
418​
419`any`
420​
421#### Returns
422​
423`any`
424​
425#### Inherited from
426​
427[`BaseIndex`](BaseIndex.md).[`evaluateIndexExpression`](BaseIndex.md#evaluateindexexpression)
428​
429***
430​
431### inArrayLookup()
432​
433```ts
434inArrayLookup(values): Set<TKey>;
435```
436​
437Defined in: [packages/db/src/indexes/basic-index.ts:448](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L448)
438​
439Performs an IN array lookup - O(k) where k is values.length
440​
441#### Parameters
442​
443##### values
444​
445`any`[]
446​
447#### Returns
448​
449`Set`\<`TKey`\>
450​
451#### Overrides
452​
453[`BaseIndex`](BaseIndex.md).[`inArrayLookup`](BaseIndex.md#inarraylookup)
454​
455***
456​
457### initialize()
458​
459```ts
460protected initialize(_options?): void;
461```
462​
463Defined in: [packages/db/src/indexes/basic-index.ts:58](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L58)
464​
465#### Parameters
466​
467##### \_options?
468​
469[`BasicIndexOptions`](../interfaces/BasicIndexOptions.md)
470​
471#### Returns
472​
473`void`
474​
475#### Overrides
476​
477[`BaseIndex`](BaseIndex.md).[`initialize`](BaseIndex.md#initialize)
478​
479***
480​
481### lookup()
482​
483```ts
484lookup(operation, value): Set<TKey>;
485```
486​
487Defined in: [packages/db/src/indexes/basic-index.ts:240](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L240)
488​
489Performs a lookup operation
490​
491#### Parameters
492​
493##### operation
494​
495`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
496​
497##### value
498​
499`any`
500​
501#### Returns
502​
503`Set`\<`TKey`\>
504​
505#### Overrides
506​
507[`BaseIndex`](BaseIndex.md).[`lookup`](BaseIndex.md#lookup)
508​
509***
510​
511### matchesCompareOptions()
512​
513```ts
514matchesCompareOptions(compareOptions): boolean;
515```
516​
517Defined in: [packages/db/src/indexes/base-index.ts:253](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L253)
518​
519Checks if the compare options match the index's compare options.
520The direction is ignored because the index can be reversed if the direction is different.
521​
522#### Parameters
523​
524##### compareOptions
525​
526`CompareOptions`
527​
528#### Returns
529​
530`boolean`
531​
532#### Inherited from
533​
534[`BaseIndex`](BaseIndex.md).[`matchesCompareOptions`](BaseIndex.md#matchescompareoptions)
535​
536***
537​
538### matchesDirection()
539​
540```ts
541matchesDirection(direction): boolean;
542```
543​
544Defined in: [packages/db/src/indexes/base-index.ts:293](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L293)
545​
546Checks if the index matches the provided direction.
547​
548#### Parameters
549​
550##### direction
551​
552[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md)
553​
554#### Returns
555​
556`boolean`
557​
558#### Inherited from
559​
560[`BaseIndex`](BaseIndex.md).[`matchesDirection`](BaseIndex.md#matchesdirection)
561​
562***
563​
564### matchesField()
565​
566```ts
567matchesField(fieldPath): boolean;
568```
569​
570Defined in: [packages/db/src/indexes/base-index.ts:241](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L241)
571​
572#### Parameters
573​
574##### fieldPath
575​
576`string`[]
577​
578#### Returns
579​
580`boolean`
581​
582#### Inherited from
583​
584[`BaseIndex`](BaseIndex.md).[`matchesField`](BaseIndex.md#matchesfield)
585​
586***
587​
588### rangeQuery()
589​
590```ts
591rangeQuery(options): Set<TKey>;
592```
593​
594Defined in: [packages/db/src/indexes/basic-index.ts:286](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L286)
595​
596Performs a range query using binary search - O(log n + m)
597​
598#### Parameters
599​
600##### options
601​
602[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}`
603​
604#### Returns
605​
606`Set`\<`TKey`\>
607​
608#### Overrides
609​
610[`BaseIndex`](BaseIndex.md).[`rangeQuery`](BaseIndex.md#rangequery)
611​
612***
613​
614### rangeQueryReversed()
615​
616```ts
617rangeQueryReversed(options): Set<TKey>;
618```
619​
620Defined in: [packages/db/src/indexes/base-index.ts:187](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L187)
621​
622#### Parameters
623​
624##### options
625​
626[`BTreeRangeQueryOptions`](../interfaces/BTreeRangeQueryOptions.md) = `{}`
627​
628#### Returns
629​
630`Set`\<`TKey`\>
631​
632#### Inherited from
633​
634[`BaseIndex`](BaseIndex.md).[`rangeQueryReversed`](BaseIndex.md#rangequeryreversed)
635​
636***
637​
638### remove()
639​
640```ts
641remove(key, item): void;
642```
643​
644Defined in: [packages/db/src/indexes/basic-index.ts:103](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L103)
645​
646Removes a value from the index
647​
648#### Parameters
649​
650##### key
651​
652`TKey`
653​
654##### item
655​
656`any`
657​
658#### Returns
659​
660`void`
661​
662#### Overrides
663​
664[`BaseIndex`](BaseIndex.md).[`remove`](BaseIndex.md#remove)
665​
666***
667​
668### removeRangeValue()
669​
670```ts
671protected removeRangeValue(value): void;
672```
673​
674Defined in: [packages/db/src/indexes/base-index.ts:218](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L218)
675​
676#### Parameters
677​
678##### value
679​
680`unknown`
681​
682#### Returns
683​
684`void`
685​
686#### Inherited from
687​
688[`BaseIndex`](BaseIndex.md).[`removeRangeValue`](BaseIndex.md#removerangevalue)
689​
690***
691​
692### supports()
693​
694```ts
695supports(operation): boolean;
696```
697​
698Defined in: [packages/db/src/indexes/base-index.ts:201](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L201)
699​
700#### Parameters
701​
702##### operation
703​
704`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
705​
706#### Returns
707​
708`boolean`
709​
710#### Inherited from
711​
712[`BaseIndex`](BaseIndex.md).[`supports`](BaseIndex.md#supports)
713​
714***
715​
716### take()
717​
718```ts
719take(
720 n,
721 from,
722 filterFn?): TKey[];
723```
724​
725Defined in: [packages/db/src/indexes/basic-index.ts:350](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L350)
726​
727Returns the next n items in sorted order
728​
729#### Parameters
730​
731##### n
732​
733`number`
734​
735##### from
736​
737`any`
738​
739##### filterFn?
740​
741(`key`) => `boolean`
742​
743#### Returns
744​
745`TKey`[]
746​
747#### Overrides
748​
749[`BaseIndex`](BaseIndex.md).[`take`](BaseIndex.md#take)
750​
751***
752​
753### takeFromStart()
754​
755```ts
756takeFromStart(n, filterFn?): TKey[];
757```
758​
759Defined in: [packages/db/src/indexes/basic-index.ts:397](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L397)
760​
761Returns the first n items in sorted order (from the start)
762​
763#### Parameters
764​
765##### n
766​
767`number`
768​
769##### filterFn?
770​
771(`key`) => `boolean`
772​
773#### Returns
774​
775`TKey`[]
776​
777#### Overrides
778​
779[`BaseIndex`](BaseIndex.md).[`takeFromStart`](BaseIndex.md#takefromstart)
780​
781***
782​
783### takeReversed()
784​
785```ts
786takeReversed(
787 n,
788 from,
789 filterFn?): TKey[];
790```
791​
792Defined in: [packages/db/src/indexes/basic-index.ts:371](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L371)
793​
794Returns the next n items in reverse sorted order
795​
796#### Parameters
797​
798##### n
799​
800`number`
801​
802##### from
803​
804`any`
805​
806##### filterFn?
807​
808(`key`) => `boolean`
809​
810#### Returns
811​
812`TKey`[]
813​
814#### Overrides
815​
816[`BaseIndex`](BaseIndex.md).[`takeReversed`](BaseIndex.md#takereversed)
817​
818***
819​
820### takeReversedFromEnd()
821​
822```ts
823takeReversedFromEnd(n, filterFn?): TKey[];
824```
825​
826Defined in: [packages/db/src/indexes/basic-index.ts:404](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L404)
827​
828Returns the first n items in reverse sorted order (from the end)
829​
830#### Parameters
831​
832##### n
833​
834`number`
835​
836##### filterFn?
837​
838(`key`) => `boolean`
839​
840#### Returns
841​
842`TKey`[]
843​
844#### Overrides
845​
846[`BaseIndex`](BaseIndex.md).[`takeReversedFromEnd`](BaseIndex.md#takereversedfromend)
847​
848***
849​
850### update()
851​
852```ts
853update(
854 key,
855 oldItem,
856 newItem): void;
857```
858​
859Defined in: [packages/db/src/indexes/basic-index.ts:160](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L160)
860​
861Updates a value in the index
862​
863#### Parameters
864​
865##### key
866​
867`TKey`
868​
869##### oldItem
870​
871`any`
872​
873##### newItem
874​
875`any`
876​
877#### Returns
878​
879`void`
880​
881#### Overrides
882​
883[`BaseIndex`](BaseIndex.md).[`update`](BaseIndex.md#update)