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

BasicIndex.md

913 lines15.5 KB

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)