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

BasicIndex.md

852 lines14.5 KB

1---
2id: BasicIndex
3title: BasicIndex
4---
5​
6Defined in: [packages/db/src/indexes/basic-index.ts:45](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L45)
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/basic-index.ts:66](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L66)
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#### Overrides
64​
65[`BaseIndex`](BaseIndex.md).[`constructor`](BaseIndex.md#constructor)
66​
67## Properties
68​
69### compareOptions
70​
71```ts
72protected compareOptions: CompareOptions;
73```
74​
75Defined in: [packages/db/src/indexes/base-index.ts:122](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L122)
76​
77#### Inherited from
78​
79[`BaseIndex`](BaseIndex.md).[`compareOptions`](BaseIndex.md#compareoptions)
80​
81***
82​
83### expression
84​
85```ts
86readonly expression: BasicExpression;
87```
88​
89Defined in: [packages/db/src/indexes/base-index.ts:120](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L120)
90​
91#### Inherited from
92​
93[`BaseIndex`](BaseIndex.md).[`expression`](BaseIndex.md#expression)
94​
95***
96​
97### hasCustomComparator
98​
99```ts
100protected hasCustomComparator: boolean = false;
101```
102​
103Defined in: [packages/db/src/indexes/base-index.ts:128](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L128)
104​
105Set by subclasses when constructed with a user-supplied comparator, whose
106ordering may not match the WHERE evaluator's relational operators.
107​
108#### Inherited from
109​
110[`BaseIndex`](BaseIndex.md).[`hasCustomComparator`](BaseIndex.md#hascustomcomparator)
111​
112***
113​
114### id
115​
116```ts
117readonly id: number;
118```
119​
120Defined in: [packages/db/src/indexes/base-index.ts:118](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L118)
121​
122#### Inherited from
123​
124[`BaseIndex`](BaseIndex.md).[`id`](BaseIndex.md#id)
125​
126***
127​
128### name?
129​
130```ts
131readonly optional name: string;
132```
133​
134Defined in: [packages/db/src/indexes/base-index.ts:119](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L119)
135​
136#### Inherited from
137​
138[`BaseIndex`](BaseIndex.md).[`name`](BaseIndex.md#name)
139​
140***
141​
142### supportedOperations
143​
144```ts
145readonly supportedOperations: Set<"eq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "ilike">;
146```
147​
148Defined in: [packages/db/src/indexes/basic-index.ts:48](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L48)
149​
150#### Overrides
151​
152[`BaseIndex`](BaseIndex.md).[`supportedOperations`](BaseIndex.md#supportedoperations)
153​
154## Accessors
155​
156### keyCount
157​
158#### Get Signature
159​
160```ts
161get keyCount(): number;
162```
163​
164Defined in: [packages/db/src/indexes/basic-index.ts:294](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L294)
165​
166Gets the number of indexed keys
167​
168##### Returns
169​
170`number`
171​
172#### Overrides
173​
174[`BaseIndex`](BaseIndex.md).[`keyCount`](BaseIndex.md#keycount)
175​
176***
177​
178### supportsRangeOptimization
179​
180#### Get Signature
181​
182```ts
183get supportsRangeOptimization(): boolean;
184```
185​
186Defined in: [packages/db/src/indexes/base-index.ts:193](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L193)
187​
188Whether range lookups (gt/gte/lt/lte) on this index can be trusted to
189return every matching key. Range traversal relies on the index ordering, so
190it is unsafe when the index uses a custom comparator, whose order may not
191match the WHERE evaluator's relational operators. Callers must fall back to
192a full scan when this is `false`.
193​
194##### Returns
195​
196`boolean`
197​
198#### Inherited from
199​
200[`BaseIndex`](BaseIndex.md).[`supportsRangeOptimization`](BaseIndex.md#supportsrangeoptimization)
201​
202## Methods
203​
204### add()
205​
206```ts
207add(key, item): void;
208```
209​
210Defined in: [packages/db/src/indexes/basic-index.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L85)
211​
212Adds a value to the index
213​
214#### Parameters
215​
216##### key
217​
218`TKey`
219​
220##### item
221​
222`any`
223​
224#### Returns
225​
226`void`
227​
228#### Overrides
229​
230[`BaseIndex`](BaseIndex.md).[`add`](BaseIndex.md#add)
231​
232***
233​
234### addRangeValue()
235​
236```ts
237protected addRangeValue(value): void;
238```
239​
240Defined in: [packages/db/src/indexes/base-index.ts:197](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L197)
241​
242#### Parameters
243​
244##### value
245​
246`unknown`
247​
248#### Returns
249​
250`void`
251​
252#### Inherited from
253​
254[`BaseIndex`](BaseIndex.md).[`addRangeValue`](BaseIndex.md#addrangevalue)
255​
256***
257​
258### build()
259​
260```ts
261build(entries): void;
262```
263​
264Defined in: [packages/db/src/indexes/basic-index.ts:217](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L217)
265​
266Builds the index from a collection of entries
267​
268#### Parameters
269​
270##### entries
271​
272`Iterable`\<\[`TKey`, `any`\]\>
273​
274#### Returns
275​
276`void`
277​
278#### Overrides
279​
280[`BaseIndex`](BaseIndex.md).[`build`](BaseIndex.md#build)
281​
282***
283​
284### canOptimizeRangeFor()
285​
286```ts
287canOptimizeRangeFor(value): boolean;
288```
289​
290Defined in: [packages/db/src/indexes/base-index.ts:219](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L219)
291​
292Whether the live values in this index share the predicate operand's
293relational domain. Mixed domains can sort differently in the index and
294WHERE evaluator, which can make a range lookup omit matching rows.
295​
296#### Parameters
297​
298##### value
299​
300`unknown`
301​
302#### Returns
303​
304`boolean`
305​
306#### Inherited from
307​
308[`BaseIndex`](BaseIndex.md).[`canOptimizeRangeFor`](BaseIndex.md#canoptimizerangefor)
309​
310***
311​
312### clear()
313​
314```ts
315clear(): void;
316```
317​
318Defined in: [packages/db/src/indexes/basic-index.ts:253](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L253)
319​
320Clears all data from the index
321​
322#### Returns
323​
324`void`
325​
326#### Overrides
327​
328[`BaseIndex`](BaseIndex.md).[`clear`](BaseIndex.md#clear)
329​
330***
331​
332### clearRangeValues()
333​
334```ts
335protected clearRangeValues(): void;
336```
337​
338Defined in: [packages/db/src/indexes/base-index.ts:215](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L215)
339​
340#### Returns
341​
342`void`
343​
344#### Inherited from
345​
346[`BaseIndex`](BaseIndex.md).[`clearRangeValues`](BaseIndex.md#clearrangevalues)
347​
348***
349​
350### equalityLookup()
351​
352```ts
353equalityLookup(value): Set<TKey>;
354```
355​
356Defined in: [packages/db/src/indexes/basic-index.ts:301](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L301)
357​
358Performs an equality lookup - O(1)
359​
360#### Parameters
361​
362##### value
363​
364`any`
365​
366#### Returns
367​
368`Set`\<`TKey`\>
369​
370#### Overrides
371​
372[`BaseIndex`](BaseIndex.md).[`equalityLookup`](BaseIndex.md#equalitylookup)
373​
374***
375​
376### evaluateIndexExpression()
377​
378```ts
379protected evaluateIndexExpression(item): any;
380```
381​
382Defined in: [packages/db/src/indexes/base-index.ts:276](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L276)
383​
384#### Parameters
385​
386##### item
387​
388`any`
389​
390#### Returns
391​
392`any`
393​
394#### Inherited from
395​
396[`BaseIndex`](BaseIndex.md).[`evaluateIndexExpression`](BaseIndex.md#evaluateindexexpression)
397​
398***
399​
400### inArrayLookup()
401​
402```ts
403inArrayLookup(values): Set<TKey>;
404```
405​
406Defined in: [packages/db/src/indexes/basic-index.ts:471](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L471)
407​
408Performs an IN array lookup - O(k) where k is values.length
409​
410#### Parameters
411​
412##### values
413​
414`any`[]
415​
416#### Returns
417​
418`Set`\<`TKey`\>
419​
420#### Overrides
421​
422[`BaseIndex`](BaseIndex.md).[`inArrayLookup`](BaseIndex.md#inarraylookup)
423​
424***
425​
426### initialize()
427​
428```ts
429protected initialize(_options?): void;
430```
431​
432Defined in: [packages/db/src/indexes/basic-index.ts:80](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L80)
433​
434#### Parameters
435​
436##### \_options?
437​
438[`BasicIndexOptions`](../interfaces/BasicIndexOptions.md)
439​
440#### Returns
441​
442`void`
443​
444#### Overrides
445​
446[`BaseIndex`](BaseIndex.md).[`initialize`](BaseIndex.md#initialize)
447​
448***
449​
450### lookup()
451​
452```ts
453lookup(operation, value): Set<TKey>;
454```
455​
456Defined in: [packages/db/src/indexes/basic-index.ts:263](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L263)
457​
458Performs a lookup operation
459​
460#### Parameters
461​
462##### operation
463​
464`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
465​
466##### value
467​
468`any`
469​
470#### Returns
471​
472`Set`\<`TKey`\>
473​
474#### Overrides
475​
476[`BaseIndex`](BaseIndex.md).[`lookup`](BaseIndex.md#lookup)
477​
478***
479​
480### matchesCompareOptions()
481​
482```ts
483matchesCompareOptions(compareOptions): boolean;
484```
485​
486Defined in: [packages/db/src/indexes/base-index.ts:241](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L241)
487​
488Checks if the compare options match the index's compare options.
489The direction is ignored because the index can be reversed if the direction is different.
490​
491#### Parameters
492​
493##### compareOptions
494​
495`CompareOptions`
496​
497#### Returns
498​
499`boolean`
500​
501#### Inherited from
502​
503[`BaseIndex`](BaseIndex.md).[`matchesCompareOptions`](BaseIndex.md#matchescompareoptions)
504​
505***
506​
507### matchesDirection()
508​
509```ts
510matchesDirection(direction): boolean;
511```
512​
513Defined in: [packages/db/src/indexes/base-index.ts:270](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L270)
514​
515Checks if the index matches the provided direction.
516​
517#### Parameters
518​
519##### direction
520​
521[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md)
522​
523#### Returns
524​
525`boolean`
526​
527#### Inherited from
528​
529[`BaseIndex`](BaseIndex.md).[`matchesDirection`](BaseIndex.md#matchesdirection)
530​
531***
532​
533### matchesField()
534​
535```ts
536matchesField(fieldPath): boolean;
537```
538​
539Defined in: [packages/db/src/indexes/base-index.ts:229](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L229)
540​
541#### Parameters
542​
543##### fieldPath
544​
545`string`[]
546​
547#### Returns
548​
549`boolean`
550​
551#### Inherited from
552​
553[`BaseIndex`](BaseIndex.md).[`matchesField`](BaseIndex.md#matchesfield)
554​
555***
556​
557### rangeQuery()
558​
559```ts
560rangeQuery(options): Set<TKey>;
561```
562​
563Defined in: [packages/db/src/indexes/basic-index.ts:309](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L309)
564​
565Performs a range query using binary search - O(log n + m)
566​
567#### Parameters
568​
569##### options
570​
571[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}`
572​
573#### Returns
574​
575`Set`\<`TKey`\>
576​
577#### Overrides
578​
579[`BaseIndex`](BaseIndex.md).[`rangeQuery`](BaseIndex.md#rangequery)
580​
581***
582​
583### rangeQueryReversed()
584​
585```ts
586rangeQueryReversed(options): Set<TKey>;
587```
588​
589Defined in: [packages/db/src/indexes/base-index.ts:175](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L175)
590​
591#### Parameters
592​
593##### options
594​
595[`BTreeRangeQueryOptions`](../interfaces/BTreeRangeQueryOptions.md) = `{}`
596​
597#### Returns
598​
599`Set`\<`TKey`\>
600​
601#### Inherited from
602​
603[`BaseIndex`](BaseIndex.md).[`rangeQueryReversed`](BaseIndex.md#rangequeryreversed)
604​
605***
606​
607### remove()
608​
609```ts
610remove(key, item): void;
611```
612​
613Defined in: [packages/db/src/indexes/basic-index.ts:126](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L126)
614​
615Removes a value from the index
616​
617#### Parameters
618​
619##### key
620​
621`TKey`
622​
623##### item
624​
625`any`
626​
627#### Returns
628​
629`void`
630​
631#### Overrides
632​
633[`BaseIndex`](BaseIndex.md).[`remove`](BaseIndex.md#remove)
634​
635***
636​
637### removeRangeValue()
638​
639```ts
640protected removeRangeValue(value): void;
641```
642​
643Defined in: [packages/db/src/indexes/base-index.ts:206](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L206)
644​
645#### Parameters
646​
647##### value
648​
649`unknown`
650​
651#### Returns
652​
653`void`
654​
655#### Inherited from
656​
657[`BaseIndex`](BaseIndex.md).[`removeRangeValue`](BaseIndex.md#removerangevalue)
658​
659***
660​
661### supports()
662​
663```ts
664supports(operation): boolean;
665```
666​
667Defined in: [packages/db/src/indexes/base-index.ts:189](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L189)
668​
669#### Parameters
670​
671##### operation
672​
673`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"`
674​
675#### Returns
676​
677`boolean`
678​
679#### Inherited from
680​
681[`BaseIndex`](BaseIndex.md).[`supports`](BaseIndex.md#supports)
682​
683***
684​
685### take()
686​
687```ts
688take(
689 n,
690 from,
691 filterFn?): TKey[];
692```
693​
694Defined in: [packages/db/src/indexes/basic-index.ts:373](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L373)
695​
696Returns the next n items in sorted order
697​
698#### Parameters
699​
700##### n
701​
702`number`
703​
704##### from
705​
706`any`
707​
708##### filterFn?
709​
710(`key`) => `boolean`
711​
712#### Returns
713​
714`TKey`[]
715​
716#### Overrides
717​
718[`BaseIndex`](BaseIndex.md).[`take`](BaseIndex.md#take)
719​
720***
721​
722### takeFromStart()
723​
724```ts
725takeFromStart(n, filterFn?): TKey[];
726```
727​
728Defined in: [packages/db/src/indexes/basic-index.ts:420](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L420)
729​
730Returns the first n items in sorted order (from the start)
731​
732#### Parameters
733​
734##### n
735​
736`number`
737​
738##### filterFn?
739​
740(`key`) => `boolean`
741​
742#### Returns
743​
744`TKey`[]
745​
746#### Overrides
747​
748[`BaseIndex`](BaseIndex.md).[`takeFromStart`](BaseIndex.md#takefromstart)
749​
750***
751​
752### takeReversed()
753​
754```ts
755takeReversed(
756 n,
757 from,
758 filterFn?): TKey[];
759```
760​
761Defined in: [packages/db/src/indexes/basic-index.ts:394](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L394)
762​
763Returns the next n items in reverse sorted order
764​
765#### Parameters
766​
767##### n
768​
769`number`
770​
771##### from
772​
773`any`
774​
775##### filterFn?
776​
777(`key`) => `boolean`
778​
779#### Returns
780​
781`TKey`[]
782​
783#### Overrides
784​
785[`BaseIndex`](BaseIndex.md).[`takeReversed`](BaseIndex.md#takereversed)
786​
787***
788​
789### takeReversedFromEnd()
790​
791```ts
792takeReversedFromEnd(n, filterFn?): TKey[];
793```
794​
795Defined in: [packages/db/src/indexes/basic-index.ts:427](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L427)
796​
797Returns the first n items in reverse sorted order (from the end)
798​
799#### Parameters
800​
801##### n
802​
803`number`
804​
805##### filterFn?
806​
807(`key`) => `boolean`
808​
809#### Returns
810​
811`TKey`[]
812​
813#### Overrides
814​
815[`BaseIndex`](BaseIndex.md).[`takeReversedFromEnd`](BaseIndex.md#takereversedfromend)
816​
817***
818​
819### update()
820​
821```ts
822update(
823 key,
824 oldItem,
825 newItem): void;
826```
827​
828Defined in: [packages/db/src/indexes/basic-index.ts:183](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/basic-index.ts#L183)
829​
830Updates a value in the index
831​
832#### Parameters
833​
834##### key
835​
836`TKey`
837​
838##### oldItem
839​
840`any`
841​
842##### newItem
843​
844`any`
845​
846#### Returns
847​
848`void`
849​
850#### Overrides
851​
852[`BaseIndex`](BaseIndex.md).[`update`](BaseIndex.md#update)