diff --git a/.changeset/optional-indexing.md b/.changeset/optional-indexing.md new file mode 100644 index 000000000..2e72f3d92 --- /dev/null +++ b/.changeset/optional-indexing.md @@ -0,0 +1,66 @@ +--- +'@tanstack/db': minor +--- + +Make indexing explicit with two index types for different use cases + +**Breaking Changes:** + +- `autoIndex` now defaults to `off` instead of `eager` +- `BTreeIndex` is no longer exported from `@tanstack/db` main entry point +- To use `createIndex()` or `autoIndex: 'eager'`, you must set `defaultIndexType` on the collection + +**Changes:** + +- New `@tanstack/db/indexing` entry point for tree-shakeable indexing +- **BasicIndex** - Lightweight index using Map + sorted Array for both equality and range queries (`eq`, `in`, `gt`, `gte`, `lt`, `lte`). O(n) updates but fast reads. +- **BTreeIndex** - Full-featured index with O(log n) updates and sorted iteration for ORDER BY optimization on large collections (10k+ items) +- Dev mode suggestions (ON by default) warn when indexes would help + +**Migration:** + +If you were relying on auto-indexing, set `defaultIndexType` on your collections: + +1. **Lightweight indexing** (good for most use cases): + +```ts +import { BasicIndex } from '@tanstack/db/indexing' + +const collection = createCollection({ + defaultIndexType: BasicIndex, + autoIndex: 'eager', + // ... +}) +``` + +2. **Full BTree indexing** (for ORDER BY optimization on large collections): + +```ts +import { BTreeIndex } from '@tanstack/db/indexing' + +const collection = createCollection({ + defaultIndexType: BTreeIndex, + autoIndex: 'eager', + // ... +}) +``` + +3. **Per-index explicit type** (mix index types): + +```ts +import { BasicIndex, BTreeIndex } from '@tanstack/db/indexing' + +const collection = createCollection({ + defaultIndexType: BasicIndex, // Default for createIndex() + // ... +}) + +// Override for specific indexes +collection.createIndex((row) => row.date, { indexType: BTreeIndex }) +``` + +**Bundle Size Impact:** + +- No indexing: ~30% smaller bundle +- BasicIndex: ~5 KB (~1.3 KB gzipped) +- BTreeIndex: ~33 KB (~7.8 KB gzipped) diff --git a/docs/reference/classes/BTreeIndex.md b/docs/reference/classes/BTreeIndex.md deleted file mode 100644 index 68054f1c3..000000000 --- a/docs/reference/classes/BTreeIndex.md +++ /dev/null @@ -1,848 +0,0 @@ ---- -id: BTreeIndex -title: BTreeIndex ---- - -# Class: BTreeIndex\ - -Defined in: [packages/db/src/indexes/btree-index.ts:31](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L31) - -B+Tree index for sorted data with range queries -This maintains items in sorted order and provides efficient range operations - -## Extends - -- [`BaseIndex`](BaseIndex.md)\<`TKey`\> - -## Type Parameters - -### TKey - -`TKey` *extends* `string` \| `number` = `string` \| `number` - -## Constructors - -### Constructor - -```ts -new BTreeIndex( - id, - expression, - name?, -options?): BTreeIndex; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:51](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L51) - -#### Parameters - -##### id - -`number` - -##### expression - -[`BasicExpression`](../@tanstack/namespaces/IR/type-aliases/BasicExpression.md) - -##### name? - -`string` - -##### options? - -`any` - -#### Returns - -`BTreeIndex`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`constructor`](BaseIndex.md#constructor) - -## Properties - -### compareOptions - -```ts -protected compareOptions: CompareOptions; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:87](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L87) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`compareOptions`](BaseIndex.md#compareoptions) - -*** - -### expression - -```ts -readonly expression: BasicExpression; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:81](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L81) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`expression`](BaseIndex.md#expression) - -*** - -### id - -```ts -readonly id: number; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:79](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L79) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`id`](BaseIndex.md#id) - -*** - -### lastUpdated - -```ts -protected lastUpdated: Date; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:86](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L86) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`lastUpdated`](BaseIndex.md#lastupdated) - -*** - -### lookupCount - -```ts -protected lookupCount: number = 0; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:84](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L84) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`lookupCount`](BaseIndex.md#lookupcount) - -*** - -### name? - -```ts -readonly optional name: string; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:80](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L80) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`name`](BaseIndex.md#name) - -*** - -### supportedOperations - -```ts -readonly supportedOperations: Set<"eq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "ilike">; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:34](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L34) - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`supportedOperations`](BaseIndex.md#supportedoperations) - -*** - -### totalLookupTime - -```ts -protected totalLookupTime: number = 0; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L85) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`totalLookupTime`](BaseIndex.md#totallookuptime) - -## Accessors - -### indexedKeysSet - -#### Get Signature - -```ts -get indexedKeysSet(): Set; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:337](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L337) - -##### Returns - -`Set`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`indexedKeysSet`](BaseIndex.md#indexedkeysset) - -*** - -### keyCount - -#### Get Signature - -```ts -get keyCount(): number; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:200](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L200) - -Gets the number of indexed keys - -##### Returns - -`number` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`keyCount`](BaseIndex.md#keycount) - -*** - -### orderedEntriesArray - -#### Get Signature - -```ts -get orderedEntriesArray(): [any, Set][]; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:341](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L341) - -##### Returns - -\[`any`, `Set`\<`TKey`\>\][] - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`orderedEntriesArray`](BaseIndex.md#orderedentriesarray) - -*** - -### orderedEntriesArrayReversed - -#### Get Signature - -```ts -get orderedEntriesArrayReversed(): [any, Set][]; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:347](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L347) - -##### Returns - -\[`any`, `Set`\<`TKey`\>\][] - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`orderedEntriesArrayReversed`](BaseIndex.md#orderedentriesarrayreversed) - -*** - -### valueMapData - -#### Get Signature - -```ts -get valueMapData(): Map>; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:354](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L354) - -##### Returns - -`Map`\<`any`, `Set`\<`TKey`\>\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`valueMapData`](BaseIndex.md#valuemapdata) - -## Methods - -### add() - -```ts -add(key, item): void; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:70](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L70) - -Adds a value to the index - -#### Parameters - -##### key - -`TKey` - -##### item - -`any` - -#### Returns - -`void` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`add`](BaseIndex.md#add) - -*** - -### build() - -```ts -build(entries): void; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:144](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L144) - -Builds the index from a collection of entries - -#### Parameters - -##### entries - -`Iterable`\<\[`TKey`, `any`\]\> - -#### Returns - -`void` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`build`](BaseIndex.md#build) - -*** - -### clear() - -```ts -clear(): void; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:155](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L155) - -Clears all data from the index - -#### Returns - -`void` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`clear`](BaseIndex.md#clear) - -*** - -### equalityLookup() - -```ts -equalityLookup(value): Set; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:209](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L209) - -Performs an equality lookup - -#### Parameters - -##### value - -`any` - -#### Returns - -`Set`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`equalityLookup`](BaseIndex.md#equalitylookup) - -*** - -### evaluateIndexExpression() - -```ts -protected evaluateIndexExpression(item): any; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:182](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L182) - -#### Parameters - -##### item - -`any` - -#### Returns - -`any` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`evaluateIndexExpression`](BaseIndex.md#evaluateindexexpression) - -*** - -### getStats() - -```ts -getStats(): IndexStats; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:169](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L169) - -#### Returns - -[`IndexStats`](../interfaces/IndexStats.md) - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`getStats`](BaseIndex.md#getstats) - -*** - -### inArrayLookup() - -```ts -inArrayLookup(values): Set; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:322](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L322) - -Performs an IN array lookup - -#### Parameters - -##### values - -`any`[] - -#### Returns - -`Set`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`inArrayLookup`](BaseIndex.md#inarraylookup) - -*** - -### initialize() - -```ts -protected initialize(_options?): void; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:65](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L65) - -#### Parameters - -##### \_options? - -[`BTreeIndexOptions`](../interfaces/BTreeIndexOptions.md) - -#### Returns - -`void` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`initialize`](BaseIndex.md#initialize) - -*** - -### lookup() - -```ts -lookup(operation, value): Set; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:165](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L165) - -Performs a lookup operation - -#### Parameters - -##### operation - -`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"` - -##### value - -`any` - -#### Returns - -`Set`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`lookup`](BaseIndex.md#lookup) - -*** - -### matchesCompareOptions() - -```ts -matchesCompareOptions(compareOptions): boolean; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:146](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L146) - -Checks if the compare options match the index's compare options. -The direction is ignored because the index can be reversed if the direction is different. - -#### Parameters - -##### compareOptions - -`CompareOptions` - -#### Returns - -`boolean` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`matchesCompareOptions`](BaseIndex.md#matchescompareoptions) - -*** - -### matchesDirection() - -```ts -matchesDirection(direction): boolean; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:165](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L165) - -Checks if the index matches the provided direction. - -#### Parameters - -##### direction - -[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md) - -#### Returns - -`boolean` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`matchesDirection`](BaseIndex.md#matchesdirection) - -*** - -### matchesField() - -```ts -matchesField(fieldPath): boolean; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:134](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L134) - -#### Parameters - -##### fieldPath - -`string`[] - -#### Returns - -`boolean` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`matchesField`](BaseIndex.md#matchesfield) - -*** - -### rangeQuery() - -```ts -rangeQuery(options): Set; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:218](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L218) - -Performs a range query with options -This is more efficient for compound queries like "WHERE a > 5 AND a < 10" - -#### Parameters - -##### options - -[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}` - -#### Returns - -`Set`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`rangeQuery`](BaseIndex.md#rangequery) - -*** - -### rangeQueryReversed() - -```ts -rangeQueryReversed(options): Set; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:251](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L251) - -Performs a reversed range query - -#### Parameters - -##### options - -[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) = `{}` - -#### Returns - -`Set`\<`TKey`\> - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`rangeQueryReversed`](BaseIndex.md#rangequeryreversed) - -*** - -### remove() - -```ts -remove(key, item): void; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:101](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L101) - -Removes a value from the index - -#### Parameters - -##### key - -`TKey` - -##### item - -`any` - -#### Returns - -`void` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`remove`](BaseIndex.md#remove) - -*** - -### supports() - -```ts -supports(operation): boolean; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:130](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L130) - -#### Parameters - -##### operation - -`"eq"` | `"gt"` | `"gte"` | `"lt"` | `"lte"` | `"in"` | `"like"` | `"ilike"` - -#### Returns - -`boolean` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`supports`](BaseIndex.md#supports) - -*** - -### take() - -```ts -take( - n, - from?, - filterFn?): TKey[]; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:299](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L299) - -Returns the next n items after the provided item or the first n items if no from item is provided. - -#### Parameters - -##### n - -`number` - -The number of items to return - -##### from? - -`any` - -The item to start from (exclusive). Starts from the smallest item (inclusive) if not provided. - -##### filterFn? - -(`key`) => `boolean` - -#### Returns - -`TKey`[] - -The next n items after the provided key. Returns the first n items if no from item is provided. - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`take`](BaseIndex.md#take) - -*** - -### takeReversed() - -```ts -takeReversed( - n, - from?, - filterFn?): TKey[]; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:310](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L310) - -Returns the next n items **before** the provided item (in descending order) or the last n items if no from item is provided. - -#### Parameters - -##### n - -`number` - -The number of items to return - -##### from? - -`any` - -The item to start from (exclusive). Starts from the largest item (inclusive) if not provided. - -##### filterFn? - -(`key`) => `boolean` - -#### Returns - -`TKey`[] - -The next n items **before** the provided key. Returns the last n items if no from item is provided. - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`takeReversed`](BaseIndex.md#takereversed) - -*** - -### trackLookup() - -```ts -protected trackLookup(startTime): void; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:187](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L187) - -#### Parameters - -##### startTime - -`number` - -#### Returns - -`void` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`trackLookup`](BaseIndex.md#tracklookup) - -*** - -### update() - -```ts -update( - key, - oldItem, - newItem): void; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:136](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L136) - -Updates a value in the index - -#### Parameters - -##### key - -`TKey` - -##### oldItem - -`any` - -##### newItem - -`any` - -#### Returns - -`void` - -#### Overrides - -[`BaseIndex`](BaseIndex.md).[`update`](BaseIndex.md#update) - -*** - -### updateTimestamp() - -```ts -protected updateTimestamp(): void; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:193](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L193) - -#### Returns - -`void` - -#### Inherited from - -[`BaseIndex`](BaseIndex.md).[`updateTimestamp`](BaseIndex.md#updatetimestamp) diff --git a/docs/reference/classes/BaseIndex.md b/docs/reference/classes/BaseIndex.md index 0327f8674..c6164642a 100644 --- a/docs/reference/classes/BaseIndex.md +++ b/docs/reference/classes/BaseIndex.md @@ -9,10 +9,6 @@ Defined in: [packages/db/src/indexes/base-index.ts:76](https://github.com/TanSta Base abstract class that all index types extend -## Extended by - -- [`BTreeIndex`](BTreeIndex.md) - ## Type Parameters ### TKey @@ -534,7 +530,7 @@ Defined in: [packages/db/src/indexes/base-index.ts:122](https://github.com/TanSt ##### options -[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) +`RangeQueryOptions` #### Returns @@ -558,7 +554,7 @@ Defined in: [packages/db/src/indexes/base-index.ts:123](https://github.com/TanSt ##### options -[`RangeQueryOptions`](../interfaces/RangeQueryOptions.md) +`RangeQueryOptions` #### Returns diff --git a/docs/reference/classes/CollectionImpl.md b/docs/reference/classes/CollectionImpl.md index de13b7c48..67039093a 100644 --- a/docs/reference/classes/CollectionImpl.md +++ b/docs/reference/classes/CollectionImpl.md @@ -5,7 +5,7 @@ title: CollectionImpl # Class: CollectionImpl\ -Defined in: [packages/db/src/collection/index.ts:266](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L266) +Defined in: [packages/db/src/collection/index.ts:264](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L264) ## Extended by @@ -42,7 +42,7 @@ Defined in: [packages/db/src/collection/index.ts:266](https://github.com/TanStac new CollectionImpl(config): CollectionImpl; ``` -Defined in: [packages/db/src/collection/index.ts:305](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L305) +Defined in: [packages/db/src/collection/index.ts:303](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L303) Creates a new Collection instance @@ -70,7 +70,7 @@ Error if sync config is missing _lifecycle: CollectionLifecycleManager; ``` -Defined in: [packages/db/src/collection/index.ts:283](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L283) +Defined in: [packages/db/src/collection/index.ts:281](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L281) *** @@ -80,7 +80,7 @@ Defined in: [packages/db/src/collection/index.ts:283](https://github.com/TanStac _state: CollectionStateManager; ``` -Defined in: [packages/db/src/collection/index.ts:295](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L295) +Defined in: [packages/db/src/collection/index.ts:293](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L293) *** @@ -90,7 +90,7 @@ Defined in: [packages/db/src/collection/index.ts:295](https://github.com/TanStac _sync: CollectionSyncManager; ``` -Defined in: [packages/db/src/collection/index.ts:284](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L284) +Defined in: [packages/db/src/collection/index.ts:282](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L282) *** @@ -100,7 +100,7 @@ Defined in: [packages/db/src/collection/index.ts:284](https://github.com/TanStac config: CollectionConfig; ``` -Defined in: [packages/db/src/collection/index.ts:274](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L274) +Defined in: [packages/db/src/collection/index.ts:272](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L272) *** @@ -110,7 +110,7 @@ Defined in: [packages/db/src/collection/index.ts:274](https://github.com/TanStac id: string; ``` -Defined in: [packages/db/src/collection/index.ts:273](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L273) +Defined in: [packages/db/src/collection/index.ts:271](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L271) *** @@ -120,7 +120,7 @@ Defined in: [packages/db/src/collection/index.ts:273](https://github.com/TanStac utils: Record = {}; ``` -Defined in: [packages/db/src/collection/index.ts:278](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L278) +Defined in: [packages/db/src/collection/index.ts:276](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L276) ## Accessors @@ -132,7 +132,7 @@ Defined in: [packages/db/src/collection/index.ts:278](https://github.com/TanStac get compareOptions(): StringCollationConfig; ``` -Defined in: [packages/db/src/collection/index.ts:579](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L579) +Defined in: [packages/db/src/collection/index.ts:567](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L567) ##### Returns @@ -148,7 +148,7 @@ Defined in: [packages/db/src/collection/index.ts:579](https://github.com/TanStac get indexes(): Map>; ``` -Defined in: [packages/db/src/collection/index.ts:564](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L564) +Defined in: [packages/db/src/collection/index.ts:552](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L552) Get resolved indexes for query optimization @@ -166,7 +166,7 @@ Get resolved indexes for query optimization get isLoadingSubset(): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:430](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L430) +Defined in: [packages/db/src/collection/index.ts:429](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L429) Check if the collection is currently loading more data @@ -186,7 +186,7 @@ true if the collection has pending load more operations, false otherwise get size(): number; ``` -Defined in: [packages/db/src/collection/index.ts:467](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L467) +Defined in: [packages/db/src/collection/index.ts:466](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L466) Get the current size of the collection (cached) @@ -204,7 +204,7 @@ Get the current size of the collection (cached) get state(): Map; ``` -Defined in: [packages/db/src/collection/index.ts:756](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L756) +Defined in: [packages/db/src/collection/index.ts:744](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L744) Gets the current state of the collection as a Map @@ -240,7 +240,7 @@ Map containing all items in the collection, with keys as identifiers get status(): CollectionStatus; ``` -Defined in: [packages/db/src/collection/index.ts:385](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L385) +Defined in: [packages/db/src/collection/index.ts:384](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L384) Gets the current status of the collection @@ -258,7 +258,7 @@ Gets the current status of the collection get subscriberCount(): number; ``` -Defined in: [packages/db/src/collection/index.ts:392](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L392) +Defined in: [packages/db/src/collection/index.ts:391](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L391) Get the number of subscribers to the collection @@ -276,7 +276,7 @@ Get the number of subscribers to the collection get toArray(): TOutput[]; ``` -Defined in: [packages/db/src/collection/index.ts:785](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L785) +Defined in: [packages/db/src/collection/index.ts:773](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L773) Gets the current state of the collection as an Array @@ -294,7 +294,7 @@ An Array containing all items in the collection iterator: IterableIterator<[TKey, TOutput]>; ``` -Defined in: [packages/db/src/collection/index.ts:495](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L495) +Defined in: [packages/db/src/collection/index.ts:494](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L494) Get all entries (virtual derived state) @@ -310,7 +310,7 @@ Get all entries (virtual derived state) cleanup(): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:919](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L919) +Defined in: [packages/db/src/collection/index.ts:907](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L907) Clean up the collection by stopping sync and clearing data This can be called manually or automatically by garbage collection @@ -324,10 +324,10 @@ This can be called manually or automatically by garbage collection ### createIndex() ```ts -createIndex(indexCallback, config): IndexProxy; +createIndex(indexCallback, config): BaseIndex; ``` -Defined in: [packages/db/src/collection/index.ts:554](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L554) +Defined in: [packages/db/src/collection/index.ts:542](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L542) Creates an index on a collection for faster queries. Indexes significantly improve query performance by allowing constant time lookups @@ -335,11 +335,9 @@ and logarithmic time range queries instead of full scans. #### Type Parameters -##### TResolver +##### TIndexType -`TResolver` *extends* [`IndexResolver`](../type-aliases/IndexResolver.md)\<`TKey`\> = *typeof* [`BTreeIndex`](BTreeIndex.md) - -The type of the index resolver (constructor or async loader) +`TIndexType` *extends* [`IndexConstructor`](../type-aliases/IndexConstructor.md)\<`TKey`\> #### Parameters @@ -351,40 +349,28 @@ Function that extracts the indexed value from each item ##### config -[`IndexOptions`](../interfaces/IndexOptions.md)\<`TResolver`\> = `{}` +[`IndexOptions`](../interfaces/IndexOptions.md)\<`TIndexType`\> = `{}` Configuration including index type and type-specific options #### Returns -[`IndexProxy`](IndexProxy.md)\<`TKey`\> +[`BaseIndex`](BaseIndex.md)\<`TKey`\> -An index proxy that provides access to the index when ready +The created index #### Example ```ts -// Create a default B+ tree index -const ageIndex = collection.createIndex((row) => row.age) +import { BasicIndex } from '@tanstack/db/indexing' -// Create a ordered index with custom options +// Create an index with explicit type const ageIndex = collection.createIndex((row) => row.age, { - indexType: BTreeIndex, - options: { - compareFn: customComparator, - compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' } - }, - name: 'age_btree' + indexType: BasicIndex }) -// Create an async-loaded index -const textIndex = collection.createIndex((row) => row.content, { - indexType: async () => { - const { FullTextIndex } = await import('./indexes/fulltext.js') - return FullTextIndex - }, - options: { language: 'en' } -}) +// Create an index with collection's default type +const nameIndex = collection.createIndex((row) => row.name) ``` *** @@ -397,7 +383,7 @@ currentStateAsChanges(options): | ChangeMessage[]; ``` -Defined in: [packages/db/src/collection/index.ts:823](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L823) +Defined in: [packages/db/src/collection/index.ts:811](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L811) Returns the current state of the collection as an array of changes @@ -441,7 +427,7 @@ const activeChanges = collection.currentStateAsChanges({ delete(keys, config?): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:733](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L733) +Defined in: [packages/db/src/collection/index.ts:721](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L721) Deletes one or more items from the collection @@ -504,7 +490,7 @@ try { entries(): IterableIterator<[TKey, TOutput]>; ``` -Defined in: [packages/db/src/collection/index.ts:488](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L488) +Defined in: [packages/db/src/collection/index.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L487) Get all entries (virtual derived state) @@ -520,7 +506,7 @@ Get all entries (virtual derived state) forEach(callbackfn): void; ``` -Defined in: [packages/db/src/collection/index.ts:502](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L502) +Defined in: [packages/db/src/collection/index.ts:501](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L501) Execute a callback for each entry in the collection @@ -542,7 +528,7 @@ Execute a callback for each entry in the collection get(key): TOutput | undefined; ``` -Defined in: [packages/db/src/collection/index.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L453) +Defined in: [packages/db/src/collection/index.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L452) Get the current value for a key (virtual derived state) @@ -564,7 +550,7 @@ Get the current value for a key (virtual derived state) getKeyFromItem(item): TKey; ``` -Defined in: [packages/db/src/collection/index.ts:517](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L517) +Defined in: [packages/db/src/collection/index.ts:516](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L516) #### Parameters @@ -584,7 +570,7 @@ Defined in: [packages/db/src/collection/index.ts:517](https://github.com/TanStac has(key): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:460](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L460) +Defined in: [packages/db/src/collection/index.ts:459](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L459) Check if a key exists in the collection (virtual derived state) @@ -608,7 +594,7 @@ insert(data, config?): | Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:620](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L620) +Defined in: [packages/db/src/collection/index.ts:608](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L608) Inserts one or more items into the collection @@ -679,7 +665,7 @@ try { isReady(): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:422](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L422) +Defined in: [packages/db/src/collection/index.ts:421](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L421) Check if the collection is ready for use Returns true if the collection has been marked as ready by its sync implementation @@ -709,7 +695,7 @@ if (collection.isReady()) { keys(): IterableIterator; ``` -Defined in: [packages/db/src/collection/index.ts:474](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L474) +Defined in: [packages/db/src/collection/index.ts:473](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L473) Get all keys (virtual derived state) @@ -725,7 +711,7 @@ Get all keys (virtual derived state) map(callbackfn): U[]; ``` -Defined in: [packages/db/src/collection/index.ts:511](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L511) +Defined in: [packages/db/src/collection/index.ts:510](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L510) Create a new array with the results of calling a function for each entry in the collection @@ -753,7 +739,7 @@ Create a new array with the results of calling a function for each entry in the off(event, callback): void; ``` -Defined in: [packages/db/src/collection/index.ts:898](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L898) +Defined in: [packages/db/src/collection/index.ts:886](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L886) Unsubscribe from a collection event @@ -793,7 +779,7 @@ Unsubscribe from a collection event on(event, callback): () => void; ``` -Defined in: [packages/db/src/collection/index.ts:878](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L878) +Defined in: [packages/db/src/collection/index.ts:866](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L866) Subscribe to a collection event @@ -839,7 +825,7 @@ Subscribe to a collection event once(event, callback): () => void; ``` -Defined in: [packages/db/src/collection/index.ts:888](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L888) +Defined in: [packages/db/src/collection/index.ts:876](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L876) Subscribe to a collection event once @@ -885,7 +871,7 @@ Subscribe to a collection event once onFirstReady(callback): void; ``` -Defined in: [packages/db/src/collection/index.ts:406](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L406) +Defined in: [packages/db/src/collection/index.ts:405](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L405) Register a callback to be executed when the collection first becomes ready Useful for preloading collections @@ -919,7 +905,7 @@ collection.onFirstReady(() => { preload(): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:446](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L446) +Defined in: [packages/db/src/collection/index.ts:445](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L445) Preload the collection data by starting sync if not already started Multiple concurrent calls will share the same promise @@ -936,7 +922,7 @@ Multiple concurrent calls will share the same promise startSyncImmediate(): void; ``` -Defined in: [packages/db/src/collection/index.ts:438](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L438) +Defined in: [packages/db/src/collection/index.ts:437](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L437) Start sync immediately - internal method for compiled queries This bypasses lazy loading for special cases like live query results @@ -953,7 +939,7 @@ This bypasses lazy loading for special cases like live query results stateWhenReady(): Promise>; ``` -Defined in: [packages/db/src/collection/index.ts:770](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L770) +Defined in: [packages/db/src/collection/index.ts:758](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L758) Gets the current state of the collection as a Map, but only resolves when data is available Waits for the first sync commit to complete before resolving @@ -972,7 +958,7 @@ Promise that resolves to a Map containing all items in the collection subscribeChanges(callback, options): CollectionSubscription; ``` -Defined in: [packages/db/src/collection/index.ts:868](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L868) +Defined in: [packages/db/src/collection/index.ts:856](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L856) Subscribe to changes in the collection @@ -1044,7 +1030,7 @@ const subscription = collection.subscribeChanges((changes) => { toArrayWhenReady(): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:795](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L795) +Defined in: [packages/db/src/collection/index.ts:783](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L783) Gets the current state of the collection as an Array, but only resolves when data is available Waits for the first sync commit to complete before resolving @@ -1065,7 +1051,7 @@ Promise that resolves to an Array containing all items in the collection update(key, callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:665](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L665) +Defined in: [packages/db/src/collection/index.ts:653](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L653) Updates one or more items in the collection using a callback function @@ -1136,7 +1122,7 @@ update( callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:671](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L671) +Defined in: [packages/db/src/collection/index.ts:659](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L659) Updates one or more items in the collection using a callback function @@ -1210,7 +1196,7 @@ try { update(id, callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:678](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L678) +Defined in: [packages/db/src/collection/index.ts:666](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L666) Updates one or more items in the collection using a callback function @@ -1281,7 +1267,7 @@ update( callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:684](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L684) +Defined in: [packages/db/src/collection/index.ts:672](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L672) Updates one or more items in the collection using a callback function @@ -1358,7 +1344,7 @@ validateData( key?): TOutput; ``` -Defined in: [packages/db/src/collection/index.ts:571](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L571) +Defined in: [packages/db/src/collection/index.ts:559](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L559) Validates the data against the schema @@ -1388,7 +1374,7 @@ Validates the data against the schema values(): IterableIterator; ``` -Defined in: [packages/db/src/collection/index.ts:481](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L481) +Defined in: [packages/db/src/collection/index.ts:480](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L480) Get all values (virtual derived state) @@ -1404,7 +1390,7 @@ Get all values (virtual derived state) waitFor(event, timeout?): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:908](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L908) +Defined in: [packages/db/src/collection/index.ts:896](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L896) Wait for a collection event diff --git a/docs/reference/classes/IndexProxy.md b/docs/reference/classes/IndexProxy.md deleted file mode 100644 index 203620ae0..000000000 --- a/docs/reference/classes/IndexProxy.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -id: IndexProxy -title: IndexProxy ---- - -# Class: IndexProxy\ - -Defined in: [packages/db/src/indexes/lazy-index.ts:131](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L131) - -Proxy that provides synchronous interface while index loads asynchronously - -## Type Parameters - -### TKey - -`TKey` *extends* `string` \| `number` = `string` \| `number` - -## Constructors - -### Constructor - -```ts -new IndexProxy(indexId, lazyIndex): IndexProxy; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:132](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L132) - -#### Parameters - -##### indexId - -`number` - -##### lazyIndex - -[`LazyIndexWrapper`](LazyIndexWrapper.md)\<`TKey`\> - -#### Returns - -`IndexProxy`\<`TKey`\> - -## Accessors - -### expression - -#### Get Signature - -```ts -get expression(): BasicExpression; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:178](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L178) - -Get the index expression (available immediately) - -##### Returns - -[`BasicExpression`](../@tanstack/namespaces/IR/type-aliases/BasicExpression.md) - -*** - -### id - -#### Get Signature - -```ts -get id(): number; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:161](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L161) - -Get the index ID - -##### Returns - -`number` - -*** - -### index - -#### Get Signature - -```ts -get index(): BaseIndex; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:140](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L140) - -Get the resolved index (throws if not ready) - -##### Returns - -[`BaseIndex`](BaseIndex.md)\<`TKey`\> - -*** - -### indexedKeysSet - -#### Get Signature - -```ts -get indexedKeysSet(): Set; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:216](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L216) - -##### Returns - -`Set`\<`TKey`\> - -*** - -### isReady - -#### Get Signature - -```ts -get isReady(): boolean; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:147](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L147) - -Check if index is ready - -##### Returns - -`boolean` - -*** - -### keyCount - -#### Get Signature - -```ts -get keyCount(): number; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:211](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L211) - -Get the key count (throws if not ready) - -##### Returns - -`number` - -*** - -### name - -#### Get Signature - -```ts -get name(): string | undefined; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:168](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L168) - -Get the index name (throws if not ready) - -##### Returns - -`string` \| `undefined` - -*** - -### orderedEntriesArray - -#### Get Signature - -```ts -get orderedEntriesArray(): [any, Set][]; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:221](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L221) - -##### Returns - -\[`any`, `Set`\<`TKey`\>\][] - -*** - -### valueMapData - -#### Get Signature - -```ts -get valueMapData(): Map>; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:226](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L226) - -##### Returns - -`Map`\<`any`, `Set`\<`TKey`\>\> - -## Methods - -### \_getLazyWrapper() - -```ts -_getLazyWrapper(): LazyIndexWrapper; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:248](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L248) - -#### Returns - -[`LazyIndexWrapper`](LazyIndexWrapper.md)\<`TKey`\> - -*** - -### equalityLookup() - -```ts -equalityLookup(value): Set; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:232](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L232) - -#### Parameters - -##### value - -`any` - -#### Returns - -`Set`\<`TKey`\> - -*** - -### getStats() - -```ts -getStats(): IndexStats; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:192](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L192) - -Get index statistics (throws if not ready) - -#### Returns - -[`IndexStats`](../interfaces/IndexStats.md) - -*** - -### inArrayLookup() - -```ts -inArrayLookup(values): Set; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:242](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L242) - -#### Parameters - -##### values - -`any`[] - -#### Returns - -`Set`\<`TKey`\> - -*** - -### matchesField() - -```ts -matchesField(fieldPath): boolean; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:199](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L199) - -Check if index matches a field path (available immediately) - -#### Parameters - -##### fieldPath - -`string`[] - -#### Returns - -`boolean` - -*** - -### rangeQuery() - -```ts -rangeQuery(options): Set; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:237](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L237) - -#### Parameters - -##### options - -`any` - -#### Returns - -`Set`\<`TKey`\> - -*** - -### supports() - -```ts -supports(operation): boolean; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:185](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L185) - -Check if index supports an operation (throws if not ready) - -#### Parameters - -##### operation - -`any` - -#### Returns - -`boolean` - -*** - -### whenReady() - -```ts -whenReady(): Promise>; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:154](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L154) - -Wait for index to be ready - -#### Returns - -`Promise`\<[`BaseIndex`](BaseIndex.md)\<`TKey`\>\> diff --git a/docs/reference/classes/LazyIndexWrapper.md b/docs/reference/classes/LazyIndexWrapper.md deleted file mode 100644 index 703809366..000000000 --- a/docs/reference/classes/LazyIndexWrapper.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -id: LazyIndexWrapper -title: LazyIndexWrapper ---- - -# Class: LazyIndexWrapper\ - -Defined in: [packages/db/src/indexes/lazy-index.ts:39](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L39) - -Wrapper that defers index creation until first sync - -## Type Parameters - -### TKey - -`TKey` *extends* `string` \| `number` = `string` \| `number` - -## Constructors - -### Constructor - -```ts -new LazyIndexWrapper( - id, - expression, - name, - resolver, - options, -collectionEntries?): LazyIndexWrapper; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:43](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L43) - -#### Parameters - -##### id - -`number` - -##### expression - -[`BasicExpression`](../@tanstack/namespaces/IR/type-aliases/BasicExpression.md) - -##### name - -`string` | `undefined` - -##### resolver - -[`IndexResolver`](../type-aliases/IndexResolver.md)\<`TKey`\> - -##### options - -`any` - -##### collectionEntries? - -`Iterable`\<\[`TKey`, `any`\], `any`, `any`\> - -#### Returns - -`LazyIndexWrapper`\<`TKey`\> - -## Methods - -### getExpression() - -```ts -getExpression(): BasicExpression; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:118](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L118) - -Get the index expression - -#### Returns - -[`BasicExpression`](../@tanstack/namespaces/IR/type-aliases/BasicExpression.md) - -*** - -### getId() - -```ts -getId(): number; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:104](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L104) - -Get the index ID - -#### Returns - -`number` - -*** - -### getName() - -```ts -getName(): string | undefined; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:111](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L111) - -Get the index name - -#### Returns - -`string` \| `undefined` - -*** - -### getResolved() - -```ts -getResolved(): BaseIndex; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:92](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L92) - -Get resolved index (throws if not ready) - -#### Returns - -[`BaseIndex`](BaseIndex.md)\<`TKey`\> - -*** - -### isResolved() - -```ts -isResolved(): boolean; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:85](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L85) - -Check if already resolved - -#### Returns - -`boolean` - -*** - -### resolve() - -```ts -resolve(): Promise>; -``` - -Defined in: [packages/db/src/indexes/lazy-index.ts:69](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/lazy-index.ts#L69) - -Resolve the actual index - -#### Returns - -`Promise`\<[`BaseIndex`](BaseIndex.md)\<`TKey`\>\> diff --git a/docs/reference/functions/configureIndexDevMode.md b/docs/reference/functions/configureIndexDevMode.md new file mode 100644 index 000000000..2c3004051 --- /dev/null +++ b/docs/reference/functions/configureIndexDevMode.md @@ -0,0 +1,24 @@ +--- +id: configureIndexDevMode +title: configureIndexDevMode +--- + +# Function: configureIndexDevMode() + +```ts +function configureIndexDevMode(config): void; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:50](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L50) + +Configure dev mode for index suggestions + +## Parameters + +### config + +`Partial`\<[`IndexDevModeConfig`](../interfaces/IndexDevModeConfig.md)\> + +## Returns + +`void` diff --git a/docs/reference/functions/createCollection.md b/docs/reference/functions/createCollection.md index 556471744..48df2ca01 100644 --- a/docs/reference/functions/createCollection.md +++ b/docs/reference/functions/createCollection.md @@ -11,7 +11,7 @@ title: createCollection function createCollection(options): Collection, TKey, TUtils, T, InferSchemaInput> & NonSingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:134](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L134) +Defined in: [packages/db/src/collection/index.ts:132](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L132) Creates a new Collection instance with the given configuration @@ -120,7 +120,7 @@ const todos = createCollection({ function createCollection(options): Collection, TKey, Exclude, T, InferSchemaInput> & NonSingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:151](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L151) +Defined in: [packages/db/src/collection/index.ts:149](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L149) Creates a new Collection instance with the given configuration @@ -229,7 +229,7 @@ const todos = createCollection({ function createCollection(options): Collection, TKey, TUtils, T, InferSchemaInput> & SingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:169](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L169) +Defined in: [packages/db/src/collection/index.ts:167](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L167) Creates a new Collection instance with the given configuration @@ -338,7 +338,7 @@ const todos = createCollection({ function createCollection(options): Collection, TKey, TUtils, T, InferSchemaInput> & SingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:185](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L185) +Defined in: [packages/db/src/collection/index.ts:183](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L183) Creates a new Collection instance with the given configuration @@ -447,7 +447,7 @@ const todos = createCollection({ function createCollection(options): Collection & NonSingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:198](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L198) +Defined in: [packages/db/src/collection/index.ts:196](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L196) Creates a new Collection instance with the given configuration @@ -556,7 +556,7 @@ const todos = createCollection({ function createCollection(options): Collection & NonSingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:211](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L211) +Defined in: [packages/db/src/collection/index.ts:209](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L209) Creates a new Collection instance with the given configuration @@ -665,7 +665,7 @@ const todos = createCollection({ function createCollection(options): Collection & SingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:223](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L223) +Defined in: [packages/db/src/collection/index.ts:221](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L221) Creates a new Collection instance with the given configuration @@ -774,7 +774,7 @@ const todos = createCollection({ function createCollection(options): Collection & SingleResult; ``` -Defined in: [packages/db/src/collection/index.ts:236](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L236) +Defined in: [packages/db/src/collection/index.ts:234](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L234) Creates a new Collection instance with the given configuration diff --git a/docs/reference/functions/isDevModeEnabled.md b/docs/reference/functions/isDevModeEnabled.md new file mode 100644 index 000000000..69fe65720 --- /dev/null +++ b/docs/reference/functions/isDevModeEnabled.md @@ -0,0 +1,18 @@ +--- +id: isDevModeEnabled +title: isDevModeEnabled +--- + +# Function: isDevModeEnabled() + +```ts +function isDevModeEnabled(): boolean; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:66](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L66) + +Check if dev mode is enabled + +## Returns + +`boolean` diff --git a/docs/reference/index.md b/docs/reference/index.md index e2be7f11f..fd2419521 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -15,7 +15,6 @@ title: "@tanstack/db" - [AggregateNotSupportedError](classes/AggregateNotSupportedError.md) - [BaseIndex](classes/BaseIndex.md) - [BaseQueryBuilder](classes/BaseQueryBuilder.md) -- [BTreeIndex](classes/BTreeIndex.md) - [CannotCombineEmptyExpressionListError](classes/CannotCombineEmptyExpressionListError.md) - [CollectionConfigurationError](classes/CollectionConfigurationError.md) - [CollectionImpl](classes/CollectionImpl.md) @@ -36,7 +35,6 @@ title: "@tanstack/db" - [EmptyReferencePathError](classes/EmptyReferencePathError.md) - [GroupByError](classes/GroupByError.md) - [HavingRequiresGroupByError](classes/HavingRequiresGroupByError.md) -- [IndexProxy](classes/IndexProxy.md) - [InvalidCollectionStatusTransitionError](classes/InvalidCollectionStatusTransitionError.md) - [InvalidJoinCondition](classes/InvalidJoinCondition.md) - [InvalidJoinConditionLeftSourceError](classes/InvalidJoinConditionLeftSourceError.md) @@ -52,7 +50,6 @@ title: "@tanstack/db" - [JoinConditionMustBeEqualityError](classes/JoinConditionMustBeEqualityError.md) - [JoinError](classes/JoinError.md) - [KeyUpdateNotAllowedError](classes/KeyUpdateNotAllowedError.md) -- [LazyIndexWrapper](classes/LazyIndexWrapper.md) - [LimitOffsetRequireOrderByError](classes/LimitOffsetRequireOrderByError.md) - [LocalStorageCollectionError](classes/LocalStorageCollectionError.md) - [MissingAliasInputsError](classes/MissingAliasInputsError.md) @@ -107,7 +104,6 @@ title: "@tanstack/db" - [BaseCollectionConfig](interfaces/BaseCollectionConfig.md) - [BaseStrategy](interfaces/BaseStrategy.md) -- [BTreeIndexOptions](interfaces/BTreeIndexOptions.md) - [ChangeMessage](interfaces/ChangeMessage.md) - [Collection](interfaces/Collection.md) - [CollectionConfig](interfaces/CollectionConfig.md) @@ -117,9 +113,11 @@ title: "@tanstack/db" - [CurrentStateAsChangesOptions](interfaces/CurrentStateAsChangesOptions.md) - [DebounceStrategy](interfaces/DebounceStrategy.md) - [DebounceStrategyOptions](interfaces/DebounceStrategyOptions.md) +- [IndexDevModeConfig](interfaces/IndexDevModeConfig.md) - [IndexInterface](interfaces/IndexInterface.md) - [IndexOptions](interfaces/IndexOptions.md) - [IndexStats](interfaces/IndexStats.md) +- [IndexSuggestion](interfaces/IndexSuggestion.md) - [InsertConfig](interfaces/InsertConfig.md) - [LiveQueryCollectionConfig](interfaces/LiveQueryCollectionConfig.md) - [LocalOnlyCollectionConfig](interfaces/LocalOnlyCollectionConfig.md) @@ -135,7 +133,6 @@ title: "@tanstack/db" - [PendingMutation](interfaces/PendingMutation.md) - [QueueStrategy](interfaces/QueueStrategy.md) - [QueueStrategyOptions](interfaces/QueueStrategyOptions.md) -- [RangeQueryOptions](interfaces/RangeQueryOptions.md) - [SimpleComparison](interfaces/SimpleComparison.md) - [SubscribeChangesOptions](interfaces/SubscribeChangesOptions.md) - [SubscribeChangesSnapshotOptions](interfaces/SubscribeChangesSnapshotOptions.md) @@ -165,7 +162,7 @@ title: "@tanstack/db" - [GetStorageSizeFn](type-aliases/GetStorageSizeFn.md) - [IndexConstructor](type-aliases/IndexConstructor.md) - [IndexOperation](type-aliases/IndexOperation.md) -- [IndexResolver](type-aliases/IndexResolver.md) +- [IndexOperation](type-aliases/IndexOperation-1.md) - [InferResultType](type-aliases/InferResultType.md) - [InferSchemaInput](type-aliases/InferSchemaInput.md) - [InferSchemaOutput](type-aliases/InferSchemaOutput.md) @@ -215,7 +212,6 @@ title: "@tanstack/db" ## Variables -- [IndexOperation](variables/IndexOperation.md) - [operators](variables/operators.md) - [Query](variables/Query.md) @@ -227,6 +223,7 @@ title: "@tanstack/db" - [coalesce](functions/coalesce.md) - [compileQuery](functions/compileQuery.md) - [concat](functions/concat.md) +- [configureIndexDevMode](functions/configureIndexDevMode.md) - [count](functions/count.md) - [createArrayChangeProxy](functions/createArrayChangeProxy.md) - [createChangeProxy](functions/createChangeProxy.md) @@ -246,6 +243,7 @@ title: "@tanstack/db" - [gte](functions/gte.md) - [ilike](functions/ilike.md) - [inArray](functions/inArray.md) +- [isDevModeEnabled](functions/isDevModeEnabled.md) - [isLimitSubset](functions/isLimitSubset.md) - [isNull](functions/isNull.md) - [isOrderBySubset](functions/isOrderBySubset.md) diff --git a/docs/reference/interfaces/BTreeIndexOptions.md b/docs/reference/interfaces/BTreeIndexOptions.md deleted file mode 100644 index 95e568924..000000000 --- a/docs/reference/interfaces/BTreeIndexOptions.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: BTreeIndexOptions -title: BTreeIndexOptions ---- - -# Interface: BTreeIndexOptions - -Defined in: [packages/db/src/indexes/btree-index.ts:12](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L12) - -Options for Ordered index - -## Properties - -### compareFn()? - -```ts -optional compareFn: (a, b) => number; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:13](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L13) - -#### Parameters - -##### a - -`any` - -##### b - -`any` - -#### Returns - -`number` - -*** - -### compareOptions? - -```ts -optional compareOptions: CompareOptions; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:14](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L14) diff --git a/docs/reference/interfaces/BaseCollectionConfig.md b/docs/reference/interfaces/BaseCollectionConfig.md index a9e36c7a1..ea787f3f3 100644 --- a/docs/reference/interfaces/BaseCollectionConfig.md +++ b/docs/reference/interfaces/BaseCollectionConfig.md @@ -5,7 +5,7 @@ title: BaseCollectionConfig # Interface: BaseCollectionConfig\ -Defined in: [packages/db/src/types.ts:438](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L438) +Defined in: [packages/db/src/types.ts:439](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L439) ## Extended by @@ -42,7 +42,7 @@ Defined in: [packages/db/src/types.ts:438](https://github.com/TanStack/db/blob/m optional autoIndex: "eager" | "off"; ``` -Defined in: [packages/db/src/types.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L487) +Defined in: [packages/db/src/types.ts:489](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L489) Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions. @@ -50,13 +50,14 @@ When enabled, indexes will be automatically created for simple where expressions #### Default ```ts -"eager" +"off" ``` #### Description -- "off": No automatic indexing -- "eager": Automatically create indexes for simple where expressions in subscribeChanges (default) +- "off": No automatic indexing (default). Use explicit indexes for better bundle size. +- "eager": Automatically create indexes for simple where expressions in subscribeChanges. + Requires setting defaultIndexType. *** @@ -66,7 +67,7 @@ When enabled, indexes will be automatically created for simple where expressions optional compare: (x, y) => number; ``` -Defined in: [packages/db/src/types.ts:498](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L498) +Defined in: [packages/db/src/types.ts:514](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L514) Optional function to compare two items. This is used to order the items in the collection. @@ -100,13 +101,37 @@ compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime() *** +### defaultIndexType? + +```ts +optional defaultIndexType: IndexConstructor; +``` + +Defined in: [packages/db/src/types.ts:503](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L503) + +Default index type to use when creating indexes without an explicit type. +Required for auto-indexing. Import from '@tanstack/db/indexing'. + +#### Example + +```ts +import { BasicIndex } from '@tanstack/db/indexing' +const collection = createCollection({ + defaultIndexType: BasicIndex, + autoIndex: 'eager', + // ... +}) +``` + +*** + ### defaultStringCollation? ```ts optional defaultStringCollation: StringCollationConfig; ``` -Defined in: [packages/db/src/types.ts:644](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L644) +Defined in: [packages/db/src/types.ts:660](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L660) Specifies how to compare data in the collection. This should be configured to match data ordering on the backend. @@ -121,7 +146,7 @@ E.g., when using the Electric DB collection these options optional gcTime: number; ``` -Defined in: [packages/db/src/types.ts:467](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L467) +Defined in: [packages/db/src/types.ts:468](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L468) Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms). @@ -134,7 +159,7 @@ when it has no active subscribers. Defaults to 5 minutes (300000ms). getKey: (item) => TKey; ``` -Defined in: [packages/db/src/types.ts:462](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L462) +Defined in: [packages/db/src/types.ts:463](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L463) Function to extract the ID from an object This is required for update/delete operations which now only accept IDs @@ -168,7 +193,7 @@ getKey: (item) => item.uuid optional id: string; ``` -Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L451) +Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) *** @@ -178,7 +203,7 @@ Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/m optional onDelete: DeleteMutationFn; ``` -Defined in: [packages/db/src/types.ts:636](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L636) +Defined in: [packages/db/src/types.ts:652](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L652) Optional asynchronous handler function called before a delete operation @@ -242,7 +267,7 @@ onDelete: async ({ transaction, collection }) => { optional onInsert: InsertMutationFn; ``` -Defined in: [packages/db/src/types.ts:549](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L549) +Defined in: [packages/db/src/types.ts:565](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L565) Optional asynchronous handler function called before an insert operation @@ -305,7 +330,7 @@ onInsert: async ({ transaction, collection }) => { optional onUpdate: UpdateMutationFn; ``` -Defined in: [packages/db/src/types.ts:593](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L593) +Defined in: [packages/db/src/types.ts:609](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L609) Optional asynchronous handler function called before an update operation @@ -369,7 +394,7 @@ onUpdate: async ({ transaction, collection }) => { optional schema: TSchema; ``` -Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) +Defined in: [packages/db/src/types.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L453) *** @@ -379,7 +404,7 @@ Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/m optional startSync: boolean; ``` -Defined in: [packages/db/src/types.ts:478](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L478) +Defined in: [packages/db/src/types.ts:479](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L479) Whether to eagerly start syncing on collection creation. When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches. @@ -402,7 +427,7 @@ false optional syncMode: SyncMode; ``` -Defined in: [packages/db/src/types.ts:507](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L507) +Defined in: [packages/db/src/types.ts:523](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L523) The mode of sync to use for the collection. @@ -424,4 +449,4 @@ The exact implementation of the sync mode is up to the sync implementation. optional utils: TUtils; ``` -Defined in: [packages/db/src/types.ts:646](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L646) +Defined in: [packages/db/src/types.ts:662](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L662) diff --git a/docs/reference/interfaces/ChangeMessage.md b/docs/reference/interfaces/ChangeMessage.md index dd5b3fb49..2e2121b32 100644 --- a/docs/reference/interfaces/ChangeMessage.md +++ b/docs/reference/interfaces/ChangeMessage.md @@ -5,7 +5,7 @@ title: ChangeMessage # Interface: ChangeMessage\ -Defined in: [packages/db/src/types.ts:314](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L314) +Defined in: [packages/db/src/types.ts:315](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L315) ## Extended by @@ -29,7 +29,7 @@ Defined in: [packages/db/src/types.ts:314](https://github.com/TanStack/db/blob/m key: TKey; ``` -Defined in: [packages/db/src/types.ts:318](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L318) +Defined in: [packages/db/src/types.ts:319](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L319) *** @@ -39,7 +39,7 @@ Defined in: [packages/db/src/types.ts:318](https://github.com/TanStack/db/blob/m optional metadata: Record; ``` -Defined in: [packages/db/src/types.ts:322](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L322) +Defined in: [packages/db/src/types.ts:323](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L323) *** @@ -49,7 +49,7 @@ Defined in: [packages/db/src/types.ts:322](https://github.com/TanStack/db/blob/m optional previousValue: T; ``` -Defined in: [packages/db/src/types.ts:320](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L320) +Defined in: [packages/db/src/types.ts:321](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L321) *** @@ -59,7 +59,7 @@ Defined in: [packages/db/src/types.ts:320](https://github.com/TanStack/db/blob/m type: OperationType; ``` -Defined in: [packages/db/src/types.ts:321](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L321) +Defined in: [packages/db/src/types.ts:322](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L322) *** @@ -69,4 +69,4 @@ Defined in: [packages/db/src/types.ts:321](https://github.com/TanStack/db/blob/m value: T; ``` -Defined in: [packages/db/src/types.ts:319](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L319) +Defined in: [packages/db/src/types.ts:320](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L320) diff --git a/docs/reference/interfaces/Collection.md b/docs/reference/interfaces/Collection.md index a11199f06..01354fdef 100644 --- a/docs/reference/interfaces/Collection.md +++ b/docs/reference/interfaces/Collection.md @@ -5,7 +5,7 @@ title: Collection # Interface: Collection\ -Defined in: [packages/db/src/collection/index.ts:48](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L48) +Defined in: [packages/db/src/collection/index.ts:46](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L46) Enhanced Collection interface that includes both data type T and utilities TUtils @@ -51,7 +51,7 @@ The type for insert operations (can be different from T for schemas with default _lifecycle: CollectionLifecycleManager; ``` -Defined in: [packages/db/src/collection/index.ts:283](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L283) +Defined in: [packages/db/src/collection/index.ts:281](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L281) #### Inherited from @@ -65,7 +65,7 @@ Defined in: [packages/db/src/collection/index.ts:283](https://github.com/TanStac _state: CollectionStateManager; ``` -Defined in: [packages/db/src/collection/index.ts:295](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L295) +Defined in: [packages/db/src/collection/index.ts:293](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L293) #### Inherited from @@ -79,7 +79,7 @@ Defined in: [packages/db/src/collection/index.ts:295](https://github.com/TanStac _sync: CollectionSyncManager; ``` -Defined in: [packages/db/src/collection/index.ts:284](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L284) +Defined in: [packages/db/src/collection/index.ts:282](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L282) #### Inherited from @@ -93,7 +93,7 @@ Defined in: [packages/db/src/collection/index.ts:284](https://github.com/TanStac config: CollectionConfig; ``` -Defined in: [packages/db/src/collection/index.ts:274](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L274) +Defined in: [packages/db/src/collection/index.ts:272](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L272) #### Inherited from @@ -107,7 +107,7 @@ Defined in: [packages/db/src/collection/index.ts:274](https://github.com/TanStac id: string; ``` -Defined in: [packages/db/src/collection/index.ts:273](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L273) +Defined in: [packages/db/src/collection/index.ts:271](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L271) #### Inherited from @@ -121,7 +121,7 @@ Defined in: [packages/db/src/collection/index.ts:273](https://github.com/TanStac readonly optional singleResult: true; ``` -Defined in: [packages/db/src/collection/index.ts:56](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L56) +Defined in: [packages/db/src/collection/index.ts:54](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L54) *** @@ -131,7 +131,7 @@ Defined in: [packages/db/src/collection/index.ts:56](https://github.com/TanStack readonly utils: TUtils; ``` -Defined in: [packages/db/src/collection/index.ts:55](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L55) +Defined in: [packages/db/src/collection/index.ts:53](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L53) #### Overrides @@ -147,7 +147,7 @@ Defined in: [packages/db/src/collection/index.ts:55](https://github.com/TanStack get compareOptions(): StringCollationConfig; ``` -Defined in: [packages/db/src/collection/index.ts:579](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L579) +Defined in: [packages/db/src/collection/index.ts:567](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L567) ##### Returns @@ -167,7 +167,7 @@ Defined in: [packages/db/src/collection/index.ts:579](https://github.com/TanStac get indexes(): Map>; ``` -Defined in: [packages/db/src/collection/index.ts:564](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L564) +Defined in: [packages/db/src/collection/index.ts:552](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L552) Get resolved indexes for query optimization @@ -189,7 +189,7 @@ Get resolved indexes for query optimization get isLoadingSubset(): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:430](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L430) +Defined in: [packages/db/src/collection/index.ts:429](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L429) Check if the collection is currently loading more data @@ -213,7 +213,7 @@ true if the collection has pending load more operations, false otherwise get size(): number; ``` -Defined in: [packages/db/src/collection/index.ts:467](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L467) +Defined in: [packages/db/src/collection/index.ts:466](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L466) Get the current size of the collection (cached) @@ -235,7 +235,7 @@ Get the current size of the collection (cached) get state(): Map; ``` -Defined in: [packages/db/src/collection/index.ts:756](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L756) +Defined in: [packages/db/src/collection/index.ts:744](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L744) Gets the current state of the collection as a Map @@ -275,7 +275,7 @@ Map containing all items in the collection, with keys as identifiers get status(): CollectionStatus; ``` -Defined in: [packages/db/src/collection/index.ts:385](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L385) +Defined in: [packages/db/src/collection/index.ts:384](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L384) Gets the current status of the collection @@ -297,7 +297,7 @@ Gets the current status of the collection get subscriberCount(): number; ``` -Defined in: [packages/db/src/collection/index.ts:392](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L392) +Defined in: [packages/db/src/collection/index.ts:391](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L391) Get the number of subscribers to the collection @@ -319,7 +319,7 @@ Get the number of subscribers to the collection get toArray(): TOutput[]; ``` -Defined in: [packages/db/src/collection/index.ts:785](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L785) +Defined in: [packages/db/src/collection/index.ts:773](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L773) Gets the current state of the collection as an Array @@ -341,7 +341,7 @@ An Array containing all items in the collection iterator: IterableIterator<[TKey, T]>; ``` -Defined in: [packages/db/src/collection/index.ts:495](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L495) +Defined in: [packages/db/src/collection/index.ts:494](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L494) Get all entries (virtual derived state) @@ -361,7 +361,7 @@ Get all entries (virtual derived state) cleanup(): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:919](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L919) +Defined in: [packages/db/src/collection/index.ts:907](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L907) Clean up the collection by stopping sync and clearing data This can be called manually or automatically by garbage collection @@ -379,10 +379,10 @@ This can be called manually or automatically by garbage collection ### createIndex() ```ts -createIndex(indexCallback, config): IndexProxy; +createIndex(indexCallback, config): BaseIndex; ``` -Defined in: [packages/db/src/collection/index.ts:554](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L554) +Defined in: [packages/db/src/collection/index.ts:542](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L542) Creates an index on a collection for faster queries. Indexes significantly improve query performance by allowing constant time lookups @@ -390,11 +390,9 @@ and logarithmic time range queries instead of full scans. #### Type Parameters -##### TResolver +##### TIndexType -`TResolver` *extends* [`IndexResolver`](../type-aliases/IndexResolver.md)\<`TKey`\> = *typeof* [`BTreeIndex`](../classes/BTreeIndex.md) - -The type of the index resolver (constructor or async loader) +`TIndexType` *extends* [`IndexConstructor`](../type-aliases/IndexConstructor.md)\<`TKey`\> #### Parameters @@ -406,40 +404,28 @@ Function that extracts the indexed value from each item ##### config -[`IndexOptions`](IndexOptions.md)\<`TResolver`\> = `{}` +[`IndexOptions`](IndexOptions.md)\<`TIndexType`\> = `{}` Configuration including index type and type-specific options #### Returns -[`IndexProxy`](../classes/IndexProxy.md)\<`TKey`\> +[`BaseIndex`](../classes/BaseIndex.md)\<`TKey`\> -An index proxy that provides access to the index when ready +The created index #### Example ```ts -// Create a default B+ tree index -const ageIndex = collection.createIndex((row) => row.age) +import { BasicIndex } from '@tanstack/db/indexing' -// Create a ordered index with custom options +// Create an index with explicit type const ageIndex = collection.createIndex((row) => row.age, { - indexType: BTreeIndex, - options: { - compareFn: customComparator, - compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' } - }, - name: 'age_btree' + indexType: BasicIndex }) -// Create an async-loaded index -const textIndex = collection.createIndex((row) => row.content, { - indexType: async () => { - const { FullTextIndex } = await import('./indexes/fulltext.js') - return FullTextIndex - }, - options: { language: 'en' } -}) +// Create an index with collection's default type +const nameIndex = collection.createIndex((row) => row.name) ``` #### Inherited from @@ -456,7 +442,7 @@ currentStateAsChanges(options): | ChangeMessage[]; ``` -Defined in: [packages/db/src/collection/index.ts:823](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L823) +Defined in: [packages/db/src/collection/index.ts:811](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L811) Returns the current state of the collection as an array of changes @@ -504,7 +490,7 @@ const activeChanges = collection.currentStateAsChanges({ delete(keys, config?): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:733](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L733) +Defined in: [packages/db/src/collection/index.ts:721](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L721) Deletes one or more items from the collection @@ -571,7 +557,7 @@ try { entries(): IterableIterator<[TKey, T]>; ``` -Defined in: [packages/db/src/collection/index.ts:488](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L488) +Defined in: [packages/db/src/collection/index.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L487) Get all entries (virtual derived state) @@ -591,7 +577,7 @@ Get all entries (virtual derived state) forEach(callbackfn): void; ``` -Defined in: [packages/db/src/collection/index.ts:502](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L502) +Defined in: [packages/db/src/collection/index.ts:501](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L501) Execute a callback for each entry in the collection @@ -617,7 +603,7 @@ Execute a callback for each entry in the collection get(key): T | undefined; ``` -Defined in: [packages/db/src/collection/index.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L453) +Defined in: [packages/db/src/collection/index.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L452) Get the current value for a key (virtual derived state) @@ -643,7 +629,7 @@ Get the current value for a key (virtual derived state) getKeyFromItem(item): TKey; ``` -Defined in: [packages/db/src/collection/index.ts:517](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L517) +Defined in: [packages/db/src/collection/index.ts:516](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L516) #### Parameters @@ -667,7 +653,7 @@ Defined in: [packages/db/src/collection/index.ts:517](https://github.com/TanStac has(key): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:460](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L460) +Defined in: [packages/db/src/collection/index.ts:459](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L459) Check if a key exists in the collection (virtual derived state) @@ -695,7 +681,7 @@ insert(data, config?): | Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:620](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L620) +Defined in: [packages/db/src/collection/index.ts:608](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L608) Inserts one or more items into the collection @@ -770,7 +756,7 @@ try { isReady(): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:422](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L422) +Defined in: [packages/db/src/collection/index.ts:421](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L421) Check if the collection is ready for use Returns true if the collection has been marked as ready by its sync implementation @@ -804,7 +790,7 @@ if (collection.isReady()) { keys(): IterableIterator; ``` -Defined in: [packages/db/src/collection/index.ts:474](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L474) +Defined in: [packages/db/src/collection/index.ts:473](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L473) Get all keys (virtual derived state) @@ -824,7 +810,7 @@ Get all keys (virtual derived state) map(callbackfn): U[]; ``` -Defined in: [packages/db/src/collection/index.ts:511](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L511) +Defined in: [packages/db/src/collection/index.ts:510](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L510) Create a new array with the results of calling a function for each entry in the collection @@ -856,7 +842,7 @@ Create a new array with the results of calling a function for each entry in the off(event, callback): void; ``` -Defined in: [packages/db/src/collection/index.ts:898](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L898) +Defined in: [packages/db/src/collection/index.ts:886](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L886) Unsubscribe from a collection event @@ -900,7 +886,7 @@ Unsubscribe from a collection event on(event, callback): () => void; ``` -Defined in: [packages/db/src/collection/index.ts:878](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L878) +Defined in: [packages/db/src/collection/index.ts:866](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L866) Subscribe to a collection event @@ -950,7 +936,7 @@ Subscribe to a collection event once(event, callback): () => void; ``` -Defined in: [packages/db/src/collection/index.ts:888](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L888) +Defined in: [packages/db/src/collection/index.ts:876](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L876) Subscribe to a collection event once @@ -1000,7 +986,7 @@ Subscribe to a collection event once onFirstReady(callback): void; ``` -Defined in: [packages/db/src/collection/index.ts:406](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L406) +Defined in: [packages/db/src/collection/index.ts:405](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L405) Register a callback to be executed when the collection first becomes ready Useful for preloading collections @@ -1038,7 +1024,7 @@ collection.onFirstReady(() => { preload(): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:446](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L446) +Defined in: [packages/db/src/collection/index.ts:445](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L445) Preload the collection data by starting sync if not already started Multiple concurrent calls will share the same promise @@ -1059,7 +1045,7 @@ Multiple concurrent calls will share the same promise startSyncImmediate(): void; ``` -Defined in: [packages/db/src/collection/index.ts:438](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L438) +Defined in: [packages/db/src/collection/index.ts:437](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L437) Start sync immediately - internal method for compiled queries This bypasses lazy loading for special cases like live query results @@ -1080,7 +1066,7 @@ This bypasses lazy loading for special cases like live query results stateWhenReady(): Promise>; ``` -Defined in: [packages/db/src/collection/index.ts:770](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L770) +Defined in: [packages/db/src/collection/index.ts:758](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L758) Gets the current state of the collection as a Map, but only resolves when data is available Waits for the first sync commit to complete before resolving @@ -1103,7 +1089,7 @@ Promise that resolves to a Map containing all items in the collection subscribeChanges(callback, options): CollectionSubscription; ``` -Defined in: [packages/db/src/collection/index.ts:868](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L868) +Defined in: [packages/db/src/collection/index.ts:856](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L856) Subscribe to changes in the collection @@ -1179,7 +1165,7 @@ const subscription = collection.subscribeChanges((changes) => { toArrayWhenReady(): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:795](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L795) +Defined in: [packages/db/src/collection/index.ts:783](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L783) Gets the current state of the collection as an Array, but only resolves when data is available Waits for the first sync commit to complete before resolving @@ -1204,7 +1190,7 @@ Promise that resolves to an Array containing all items in the collection update(key, callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:665](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L665) +Defined in: [packages/db/src/collection/index.ts:653](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L653) Updates one or more items in the collection using a callback function @@ -1279,7 +1265,7 @@ update( callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:671](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L671) +Defined in: [packages/db/src/collection/index.ts:659](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L659) Updates one or more items in the collection using a callback function @@ -1357,7 +1343,7 @@ try { update(id, callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:678](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L678) +Defined in: [packages/db/src/collection/index.ts:666](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L666) Updates one or more items in the collection using a callback function @@ -1432,7 +1418,7 @@ update( callback): Transaction; ``` -Defined in: [packages/db/src/collection/index.ts:684](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L684) +Defined in: [packages/db/src/collection/index.ts:672](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L672) Updates one or more items in the collection using a callback function @@ -1513,7 +1499,7 @@ validateData( key?): T; ``` -Defined in: [packages/db/src/collection/index.ts:571](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L571) +Defined in: [packages/db/src/collection/index.ts:559](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L559) Validates the data against the schema @@ -1547,7 +1533,7 @@ Validates the data against the schema values(): IterableIterator; ``` -Defined in: [packages/db/src/collection/index.ts:481](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L481) +Defined in: [packages/db/src/collection/index.ts:480](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L480) Get all values (virtual derived state) @@ -1567,7 +1553,7 @@ Get all values (virtual derived state) waitFor(event, timeout?): Promise; ``` -Defined in: [packages/db/src/collection/index.ts:908](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L908) +Defined in: [packages/db/src/collection/index.ts:896](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L896) Wait for a collection event diff --git a/docs/reference/interfaces/CollectionConfig.md b/docs/reference/interfaces/CollectionConfig.md index f4a8dbc89..0ede22f48 100644 --- a/docs/reference/interfaces/CollectionConfig.md +++ b/docs/reference/interfaces/CollectionConfig.md @@ -5,7 +5,7 @@ title: CollectionConfig # Interface: CollectionConfig\ -Defined in: [packages/db/src/types.ts:649](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L649) +Defined in: [packages/db/src/types.ts:665](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L665) ## Extends @@ -37,7 +37,7 @@ Defined in: [packages/db/src/types.ts:649](https://github.com/TanStack/db/blob/m optional autoIndex: "eager" | "off"; ``` -Defined in: [packages/db/src/types.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L487) +Defined in: [packages/db/src/types.ts:489](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L489) Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions. @@ -45,13 +45,14 @@ When enabled, indexes will be automatically created for simple where expressions #### Default ```ts -"eager" +"off" ``` #### Description -- "off": No automatic indexing -- "eager": Automatically create indexes for simple where expressions in subscribeChanges (default) +- "off": No automatic indexing (default). Use explicit indexes for better bundle size. +- "eager": Automatically create indexes for simple where expressions in subscribeChanges. + Requires setting defaultIndexType. #### Inherited from @@ -65,7 +66,7 @@ When enabled, indexes will be automatically created for simple where expressions optional compare: (x, y) => number; ``` -Defined in: [packages/db/src/types.ts:498](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L498) +Defined in: [packages/db/src/types.ts:514](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L514) Optional function to compare two items. This is used to order the items in the collection. @@ -103,13 +104,41 @@ compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime() *** +### defaultIndexType? + +```ts +optional defaultIndexType: IndexConstructor; +``` + +Defined in: [packages/db/src/types.ts:503](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L503) + +Default index type to use when creating indexes without an explicit type. +Required for auto-indexing. Import from '@tanstack/db/indexing'. + +#### Example + +```ts +import { BasicIndex } from '@tanstack/db/indexing' +const collection = createCollection({ + defaultIndexType: BasicIndex, + autoIndex: 'eager', + // ... +}) +``` + +#### Inherited from + +[`BaseCollectionConfig`](BaseCollectionConfig.md).[`defaultIndexType`](BaseCollectionConfig.md#defaultindextype) + +*** + ### defaultStringCollation? ```ts optional defaultStringCollation: StringCollationConfig; ``` -Defined in: [packages/db/src/types.ts:644](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L644) +Defined in: [packages/db/src/types.ts:660](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L660) Specifies how to compare data in the collection. This should be configured to match data ordering on the backend. @@ -128,7 +157,7 @@ E.g., when using the Electric DB collection these options optional gcTime: number; ``` -Defined in: [packages/db/src/types.ts:467](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L467) +Defined in: [packages/db/src/types.ts:468](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L468) Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms). @@ -145,7 +174,7 @@ when it has no active subscribers. Defaults to 5 minutes (300000ms). getKey: (item) => TKey; ``` -Defined in: [packages/db/src/types.ts:462](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L462) +Defined in: [packages/db/src/types.ts:463](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L463) Function to extract the ID from an object This is required for update/delete operations which now only accept IDs @@ -183,7 +212,7 @@ getKey: (item) => item.uuid optional id: string; ``` -Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L451) +Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) #### Inherited from @@ -197,7 +226,7 @@ Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/m optional onDelete: DeleteMutationFn; ``` -Defined in: [packages/db/src/types.ts:636](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L636) +Defined in: [packages/db/src/types.ts:652](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L652) Optional asynchronous handler function called before a delete operation @@ -265,7 +294,7 @@ onDelete: async ({ transaction, collection }) => { optional onInsert: InsertMutationFn; ``` -Defined in: [packages/db/src/types.ts:549](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L549) +Defined in: [packages/db/src/types.ts:565](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L565) Optional asynchronous handler function called before an insert operation @@ -332,7 +361,7 @@ onInsert: async ({ transaction, collection }) => { optional onUpdate: UpdateMutationFn; ``` -Defined in: [packages/db/src/types.ts:593](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L593) +Defined in: [packages/db/src/types.ts:609](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L609) Optional asynchronous handler function called before an update operation @@ -400,7 +429,7 @@ onUpdate: async ({ transaction, collection }) => { optional schema: TSchema; ``` -Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) +Defined in: [packages/db/src/types.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L453) #### Inherited from @@ -414,7 +443,7 @@ Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/m optional startSync: boolean; ``` -Defined in: [packages/db/src/types.ts:478](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L478) +Defined in: [packages/db/src/types.ts:479](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L479) Whether to eagerly start syncing on collection creation. When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches. @@ -441,7 +470,7 @@ false sync: SyncConfig; ``` -Defined in: [packages/db/src/types.ts:655](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L655) +Defined in: [packages/db/src/types.ts:671](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L671) *** @@ -451,7 +480,7 @@ Defined in: [packages/db/src/types.ts:655](https://github.com/TanStack/db/blob/m optional syncMode: SyncMode; ``` -Defined in: [packages/db/src/types.ts:507](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L507) +Defined in: [packages/db/src/types.ts:523](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L523) The mode of sync to use for the collection. @@ -477,7 +506,7 @@ The exact implementation of the sync mode is up to the sync implementation. optional utils: TUtils; ``` -Defined in: [packages/db/src/types.ts:646](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L646) +Defined in: [packages/db/src/types.ts:662](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L662) #### Inherited from diff --git a/docs/reference/interfaces/CollectionLike.md b/docs/reference/interfaces/CollectionLike.md index dd00a15d6..4c0474ed9 100644 --- a/docs/reference/interfaces/CollectionLike.md +++ b/docs/reference/interfaces/CollectionLike.md @@ -5,7 +5,7 @@ title: CollectionLike # Interface: CollectionLike\ -Defined in: [packages/db/src/types.ts:12](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L12) +Defined in: [packages/db/src/types.ts:13](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L13) Interface for a collection-like object that provides the necessary methods for the change events system to work @@ -32,7 +32,7 @@ for the change events system to work compareOptions: StringCollationConfig; ``` -Defined in: [packages/db/src/collection/index.ts:579](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L579) +Defined in: [packages/db/src/collection/index.ts:567](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L567) #### Inherited from @@ -46,7 +46,7 @@ Defined in: [packages/db/src/collection/index.ts:579](https://github.com/TanStac id: string; ``` -Defined in: [packages/db/src/collection/index.ts:273](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L273) +Defined in: [packages/db/src/collection/index.ts:271](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L271) #### Inherited from @@ -60,7 +60,7 @@ Defined in: [packages/db/src/collection/index.ts:273](https://github.com/TanStac indexes: Map>; ``` -Defined in: [packages/db/src/collection/index.ts:564](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L564) +Defined in: [packages/db/src/collection/index.ts:552](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L552) #### Inherited from @@ -76,7 +76,7 @@ Pick.indexes entries(): IterableIterator<[TKey, T]>; ``` -Defined in: [packages/db/src/collection/index.ts:488](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L488) +Defined in: [packages/db/src/collection/index.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L487) Get all entries (virtual derived state) @@ -98,7 +98,7 @@ Pick.entries get(key): T | undefined; ``` -Defined in: [packages/db/src/collection/index.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L453) +Defined in: [packages/db/src/collection/index.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L452) Get the current value for a key (virtual derived state) @@ -126,7 +126,7 @@ Pick.get has(key): boolean; ``` -Defined in: [packages/db/src/collection/index.ts:460](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L460) +Defined in: [packages/db/src/collection/index.ts:459](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L459) Check if a key exists in the collection (virtual derived state) diff --git a/docs/reference/interfaces/CreateOptimisticActionsOptions.md b/docs/reference/interfaces/CreateOptimisticActionsOptions.md index 3e20fe56d..dd24d349a 100644 --- a/docs/reference/interfaces/CreateOptimisticActionsOptions.md +++ b/docs/reference/interfaces/CreateOptimisticActionsOptions.md @@ -5,7 +5,7 @@ title: CreateOptimisticActionsOptions # Interface: CreateOptimisticActionsOptions\ -Defined in: [packages/db/src/types.ts:178](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L178) +Defined in: [packages/db/src/types.ts:179](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L179) Options for the createOptimisticAction helper @@ -31,7 +31,7 @@ Options for the createOptimisticAction helper optional autoCommit: boolean; ``` -Defined in: [packages/db/src/types.ts:169](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L169) +Defined in: [packages/db/src/types.ts:170](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L170) #### Inherited from @@ -45,7 +45,7 @@ Defined in: [packages/db/src/types.ts:169](https://github.com/TanStack/db/blob/m optional id: string; ``` -Defined in: [packages/db/src/types.ts:167](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L167) +Defined in: [packages/db/src/types.ts:168](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L168) Unique identifier for the transaction @@ -63,7 +63,7 @@ Omit.id optional metadata: Record; ``` -Defined in: [packages/db/src/types.ts:172](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L172) +Defined in: [packages/db/src/types.ts:173](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L173) Custom metadata to associate with the transaction @@ -81,7 +81,7 @@ Omit.metadata mutationFn: (vars, params) => Promise; ``` -Defined in: [packages/db/src/types.ts:185](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L185) +Defined in: [packages/db/src/types.ts:186](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L186) Function to execute the mutation on the server @@ -107,7 +107,7 @@ Function to execute the mutation on the server onMutate: (vars) => void; ``` -Defined in: [packages/db/src/types.ts:183](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L183) +Defined in: [packages/db/src/types.ts:184](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L184) Function to apply optimistic updates locally before the mutation completes diff --git a/docs/reference/interfaces/CurrentStateAsChangesOptions.md b/docs/reference/interfaces/CurrentStateAsChangesOptions.md index 0774a7c7b..4d691d421 100644 --- a/docs/reference/interfaces/CurrentStateAsChangesOptions.md +++ b/docs/reference/interfaces/CurrentStateAsChangesOptions.md @@ -5,7 +5,7 @@ title: CurrentStateAsChangesOptions # Interface: CurrentStateAsChangesOptions -Defined in: [packages/db/src/types.ts:741](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L741) +Defined in: [packages/db/src/types.ts:757](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L757) Options for getting current state as changes @@ -17,7 +17,7 @@ Options for getting current state as changes optional limit: number; ``` -Defined in: [packages/db/src/types.ts:745](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L745) +Defined in: [packages/db/src/types.ts:761](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L761) *** @@ -27,7 +27,7 @@ Defined in: [packages/db/src/types.ts:745](https://github.com/TanStack/db/blob/m optional optimizedOnly: boolean; ``` -Defined in: [packages/db/src/types.ts:746](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L746) +Defined in: [packages/db/src/types.ts:762](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L762) *** @@ -37,7 +37,7 @@ Defined in: [packages/db/src/types.ts:746](https://github.com/TanStack/db/blob/m optional orderBy: OrderBy; ``` -Defined in: [packages/db/src/types.ts:744](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L744) +Defined in: [packages/db/src/types.ts:760](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L760) *** @@ -47,6 +47,6 @@ Defined in: [packages/db/src/types.ts:744](https://github.com/TanStack/db/blob/m optional where: BasicExpression; ``` -Defined in: [packages/db/src/types.ts:743](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L743) +Defined in: [packages/db/src/types.ts:759](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L759) Pre-compiled expression for filtering the current state diff --git a/docs/reference/interfaces/IndexDevModeConfig.md b/docs/reference/interfaces/IndexDevModeConfig.md new file mode 100644 index 000000000..90dfadcd9 --- /dev/null +++ b/docs/reference/interfaces/IndexDevModeConfig.md @@ -0,0 +1,56 @@ +--- +id: IndexDevModeConfig +title: IndexDevModeConfig +--- + +# Interface: IndexDevModeConfig + +Defined in: [packages/db/src/indexes/index-registry.ts:15](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L15) + +## Properties + +### collectionSizeThreshold + +```ts +collectionSizeThreshold: number; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:19](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L19) + +Suggest indexes when collection has more than this many items + +*** + +### enabled + +```ts +enabled: boolean; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:17](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L17) + +Enable dev mode index suggestions + +*** + +### onSuggestion + +```ts +onSuggestion: (suggestion) => void | null; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:23](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L23) + +Custom handler for index suggestions + +*** + +### slowQueryThresholdMs + +```ts +slowQueryThresholdMs: number; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:21](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L21) + +Suggest indexes when queries take longer than this (ms) diff --git a/docs/reference/interfaces/IndexInterface.md b/docs/reference/interfaces/IndexInterface.md index 5a649aa31..9b3f13fe6 100644 --- a/docs/reference/interfaces/IndexInterface.md +++ b/docs/reference/interfaces/IndexInterface.md @@ -223,7 +223,7 @@ Defined in: [packages/db/src/indexes/base-index.ts:43](https://github.com/TanSta ##### options -[`RangeQueryOptions`](RangeQueryOptions.md) +`RangeQueryOptions` #### Returns @@ -243,7 +243,7 @@ Defined in: [packages/db/src/indexes/base-index.ts:44](https://github.com/TanSta ##### options -[`RangeQueryOptions`](RangeQueryOptions.md) +`RangeQueryOptions` #### Returns diff --git a/docs/reference/interfaces/IndexOptions.md b/docs/reference/interfaces/IndexOptions.md index 3ca169871..c3908219f 100644 --- a/docs/reference/interfaces/IndexOptions.md +++ b/docs/reference/interfaces/IndexOptions.md @@ -3,27 +3,29 @@ id: IndexOptions title: IndexOptions --- -# Interface: IndexOptions\ +# Interface: IndexOptions\ Defined in: [packages/db/src/indexes/index-options.ts:6](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L6) -Enhanced index options that support both sync and async resolvers +Options for creating an index ## Type Parameters -### TResolver +### TIndexType -`TResolver` *extends* [`IndexResolver`](../type-aliases/IndexResolver.md) = [`IndexResolver`](../type-aliases/IndexResolver.md) +`TIndexType` *extends* [`IndexConstructor`](../type-aliases/IndexConstructor.md) = [`IndexConstructor`](../type-aliases/IndexConstructor.md) ## Properties ### indexType? ```ts -optional indexType: TResolver; +optional indexType: TIndexType; ``` -Defined in: [packages/db/src/indexes/index-options.ts:8](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L8) +Defined in: [packages/db/src/indexes/index-options.ts:12](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L12) + +Index type to use (e.g., BasicIndex, BTreeIndex) *** @@ -33,14 +35,18 @@ Defined in: [packages/db/src/indexes/index-options.ts:8](https://github.com/TanS optional name: string; ``` -Defined in: [packages/db/src/indexes/index-options.ts:7](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L7) +Defined in: [packages/db/src/indexes/index-options.ts:10](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L10) + +Optional name for the index *** ### options? ```ts -optional options: TResolver extends IndexConstructor ? TResolver extends (id, expr, name?, options?) => any ? O : never : TResolver extends () => Promise ? TCtor extends (id, expr, name?, options?) => any ? O : never : never; +optional options: TIndexType extends (id, expr, name?, options?) => any ? O : never; ``` -Defined in: [packages/db/src/indexes/index-options.ts:9](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L9) +Defined in: [packages/db/src/indexes/index-options.ts:14](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-options.ts#L14) + +Options passed to the index constructor diff --git a/docs/reference/interfaces/IndexSuggestion.md b/docs/reference/interfaces/IndexSuggestion.md new file mode 100644 index 000000000..24cdd19e5 --- /dev/null +++ b/docs/reference/interfaces/IndexSuggestion.md @@ -0,0 +1,78 @@ +--- +id: IndexSuggestion +title: IndexSuggestion +--- + +# Interface: IndexSuggestion + +Defined in: [packages/db/src/indexes/index-registry.ts:26](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L26) + +## Properties + +### collectionId + +```ts +collectionId: string; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:28](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L28) + +*** + +### collectionSize? + +```ts +optional collectionSize: number; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:31](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L31) + +*** + +### fieldPath + +```ts +fieldPath: string[]; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:29](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L29) + +*** + +### message + +```ts +message: string; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:30](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L30) + +*** + +### queryCount? + +```ts +optional queryCount: number; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:33](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L33) + +*** + +### queryTimeMs? + +```ts +optional queryTimeMs: number; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:32](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L32) + +*** + +### type + +```ts +type: "collection-size" | "slow-query" | "frequent-field"; +``` + +Defined in: [packages/db/src/indexes/index-registry.ts:27](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/index-registry.ts#L27) diff --git a/docs/reference/interfaces/InsertConfig.md b/docs/reference/interfaces/InsertConfig.md index 47410c1e4..3506960fa 100644 --- a/docs/reference/interfaces/InsertConfig.md +++ b/docs/reference/interfaces/InsertConfig.md @@ -5,7 +5,7 @@ title: InsertConfig # Interface: InsertConfig -Defined in: [packages/db/src/types.ts:356](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L356) +Defined in: [packages/db/src/types.ts:357](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L357) ## Properties @@ -15,7 +15,7 @@ Defined in: [packages/db/src/types.ts:356](https://github.com/TanStack/db/blob/m optional metadata: Record; ``` -Defined in: [packages/db/src/types.ts:357](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L357) +Defined in: [packages/db/src/types.ts:358](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L358) *** @@ -25,6 +25,6 @@ Defined in: [packages/db/src/types.ts:357](https://github.com/TanStack/db/blob/m optional optimistic: boolean; ``` -Defined in: [packages/db/src/types.ts:359](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L359) +Defined in: [packages/db/src/types.ts:360](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L360) Whether to apply optimistic updates immediately. Defaults to true. diff --git a/docs/reference/interfaces/LocalOnlyCollectionConfig.md b/docs/reference/interfaces/LocalOnlyCollectionConfig.md index cfee0127e..d805188de 100644 --- a/docs/reference/interfaces/LocalOnlyCollectionConfig.md +++ b/docs/reference/interfaces/LocalOnlyCollectionConfig.md @@ -41,7 +41,7 @@ The type of the key returned by `getKey` optional autoIndex: "eager" | "off"; ``` -Defined in: [packages/db/src/types.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L487) +Defined in: [packages/db/src/types.ts:489](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L489) Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions. @@ -49,13 +49,14 @@ When enabled, indexes will be automatically created for simple where expressions #### Default ```ts -"eager" +"off" ``` #### Description -- "off": No automatic indexing -- "eager": Automatically create indexes for simple where expressions in subscribeChanges (default) +- "off": No automatic indexing (default). Use explicit indexes for better bundle size. +- "eager": Automatically create indexes for simple where expressions in subscribeChanges. + Requires setting defaultIndexType. #### Inherited from @@ -69,7 +70,7 @@ When enabled, indexes will be automatically created for simple where expressions optional compare: (x, y) => number; ``` -Defined in: [packages/db/src/types.ts:498](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L498) +Defined in: [packages/db/src/types.ts:514](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L514) Optional function to compare two items. This is used to order the items in the collection. @@ -109,13 +110,43 @@ Omit.compare *** +### defaultIndexType? + +```ts +optional defaultIndexType: IndexConstructor; +``` + +Defined in: [packages/db/src/types.ts:503](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L503) + +Default index type to use when creating indexes without an explicit type. +Required for auto-indexing. Import from '@tanstack/db/indexing'. + +#### Example + +```ts +import { BasicIndex } from '@tanstack/db/indexing' +const collection = createCollection({ + defaultIndexType: BasicIndex, + autoIndex: 'eager', + // ... +}) +``` + +#### Inherited from + +```ts +Omit.defaultIndexType +``` + +*** + ### defaultStringCollation? ```ts optional defaultStringCollation: StringCollationConfig; ``` -Defined in: [packages/db/src/types.ts:644](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L644) +Defined in: [packages/db/src/types.ts:660](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L660) Specifies how to compare data in the collection. This should be configured to match data ordering on the backend. @@ -136,7 +167,7 @@ Omit.defaultStringCollation getKey: (item) => TKey; ``` -Defined in: [packages/db/src/types.ts:462](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L462) +Defined in: [packages/db/src/types.ts:463](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L463) Function to extract the ID from an object This is required for update/delete operations which now only accept IDs @@ -176,7 +207,7 @@ Omit.getKey optional id: string; ``` -Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L451) +Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) #### Inherited from @@ -203,7 +234,7 @@ This data will be applied during the initial sync process optional onDelete: DeleteMutationFn; ``` -Defined in: [packages/db/src/types.ts:636](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L636) +Defined in: [packages/db/src/types.ts:652](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L652) Optional asynchronous handler function called before a delete operation @@ -273,7 +304,7 @@ Omit.onDelete optional onInsert: InsertMutationFn; ``` -Defined in: [packages/db/src/types.ts:549](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L549) +Defined in: [packages/db/src/types.ts:565](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L565) Optional asynchronous handler function called before an insert operation @@ -342,7 +373,7 @@ Omit.onInsert optional onUpdate: UpdateMutationFn; ``` -Defined in: [packages/db/src/types.ts:593](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L593) +Defined in: [packages/db/src/types.ts:609](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L609) Optional asynchronous handler function called before an update operation @@ -412,7 +443,7 @@ Omit.onUpdate optional schema: TSchema; ``` -Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) +Defined in: [packages/db/src/types.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L453) #### Inherited from @@ -428,7 +459,7 @@ Omit.schema optional syncMode: SyncMode; ``` -Defined in: [packages/db/src/types.ts:507](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L507) +Defined in: [packages/db/src/types.ts:523](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L523) The mode of sync to use for the collection. @@ -454,7 +485,7 @@ The exact implementation of the sync mode is up to the sync implementation. optional utils: LocalOnlyCollectionUtils; ``` -Defined in: [packages/db/src/types.ts:646](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L646) +Defined in: [packages/db/src/types.ts:662](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L662) #### Inherited from diff --git a/docs/reference/interfaces/LocalStorageCollectionConfig.md b/docs/reference/interfaces/LocalStorageCollectionConfig.md index 81c4b21db..26875160a 100644 --- a/docs/reference/interfaces/LocalStorageCollectionConfig.md +++ b/docs/reference/interfaces/LocalStorageCollectionConfig.md @@ -41,7 +41,7 @@ The type of the key returned by `getKey` optional autoIndex: "eager" | "off"; ``` -Defined in: [packages/db/src/types.ts:487](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L487) +Defined in: [packages/db/src/types.ts:489](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L489) Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions. @@ -49,13 +49,14 @@ When enabled, indexes will be automatically created for simple where expressions #### Default ```ts -"eager" +"off" ``` #### Description -- "off": No automatic indexing -- "eager": Automatically create indexes for simple where expressions in subscribeChanges (default) +- "off": No automatic indexing (default). Use explicit indexes for better bundle size. +- "eager": Automatically create indexes for simple where expressions in subscribeChanges. + Requires setting defaultIndexType. #### Inherited from @@ -69,7 +70,7 @@ When enabled, indexes will be automatically created for simple where expressions optional compare: (x, y) => number; ``` -Defined in: [packages/db/src/types.ts:498](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L498) +Defined in: [packages/db/src/types.ts:514](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L514) Optional function to compare two items. This is used to order the items in the collection. @@ -107,13 +108,41 @@ compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime() *** +### defaultIndexType? + +```ts +optional defaultIndexType: IndexConstructor; +``` + +Defined in: [packages/db/src/types.ts:503](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L503) + +Default index type to use when creating indexes without an explicit type. +Required for auto-indexing. Import from '@tanstack/db/indexing'. + +#### Example + +```ts +import { BasicIndex } from '@tanstack/db/indexing' +const collection = createCollection({ + defaultIndexType: BasicIndex, + autoIndex: 'eager', + // ... +}) +``` + +#### Inherited from + +[`BaseCollectionConfig`](BaseCollectionConfig.md).[`defaultIndexType`](BaseCollectionConfig.md#defaultindextype) + +*** + ### defaultStringCollation? ```ts optional defaultStringCollation: StringCollationConfig; ``` -Defined in: [packages/db/src/types.ts:644](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L644) +Defined in: [packages/db/src/types.ts:660](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L660) Specifies how to compare data in the collection. This should be configured to match data ordering on the backend. @@ -132,7 +161,7 @@ E.g., when using the Electric DB collection these options optional gcTime: number; ``` -Defined in: [packages/db/src/types.ts:467](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L467) +Defined in: [packages/db/src/types.ts:468](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L468) Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms). @@ -149,7 +178,7 @@ when it has no active subscribers. Defaults to 5 minutes (300000ms). getKey: (item) => TKey; ``` -Defined in: [packages/db/src/types.ts:462](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L462) +Defined in: [packages/db/src/types.ts:463](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L463) Function to extract the ID from an object This is required for update/delete operations which now only accept IDs @@ -187,7 +216,7 @@ getKey: (item) => item.uuid optional id: string; ``` -Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L451) +Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) #### Inherited from @@ -201,7 +230,7 @@ Defined in: [packages/db/src/types.ts:451](https://github.com/TanStack/db/blob/m optional onDelete: DeleteMutationFn; ``` -Defined in: [packages/db/src/types.ts:636](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L636) +Defined in: [packages/db/src/types.ts:652](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L652) Optional asynchronous handler function called before a delete operation @@ -269,7 +298,7 @@ onDelete: async ({ transaction, collection }) => { optional onInsert: InsertMutationFn; ``` -Defined in: [packages/db/src/types.ts:549](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L549) +Defined in: [packages/db/src/types.ts:565](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L565) Optional asynchronous handler function called before an insert operation @@ -336,7 +365,7 @@ onInsert: async ({ transaction, collection }) => { optional onUpdate: UpdateMutationFn; ``` -Defined in: [packages/db/src/types.ts:593](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L593) +Defined in: [packages/db/src/types.ts:609](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L609) Optional asynchronous handler function called before an update operation @@ -417,7 +446,7 @@ Defaults to JSON optional schema: TSchema; ``` -Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L452) +Defined in: [packages/db/src/types.ts:453](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L453) #### Inherited from @@ -431,7 +460,7 @@ Defined in: [packages/db/src/types.ts:452](https://github.com/TanStack/db/blob/m optional startSync: boolean; ``` -Defined in: [packages/db/src/types.ts:478](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L478) +Defined in: [packages/db/src/types.ts:479](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L479) Whether to eagerly start syncing on collection creation. When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches. @@ -496,7 +525,7 @@ The key to use for storing the collection data in localStorage/sessionStorage optional syncMode: SyncMode; ``` -Defined in: [packages/db/src/types.ts:507](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L507) +Defined in: [packages/db/src/types.ts:523](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L523) The mode of sync to use for the collection. @@ -522,7 +551,7 @@ The exact implementation of the sync mode is up to the sync implementation. optional utils: UtilsRecord; ``` -Defined in: [packages/db/src/types.ts:646](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L646) +Defined in: [packages/db/src/types.ts:662](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L662) #### Inherited from diff --git a/docs/reference/interfaces/OperationConfig.md b/docs/reference/interfaces/OperationConfig.md index 66c3e6e55..59bb5c03b 100644 --- a/docs/reference/interfaces/OperationConfig.md +++ b/docs/reference/interfaces/OperationConfig.md @@ -5,7 +5,7 @@ title: OperationConfig # Interface: OperationConfig -Defined in: [packages/db/src/types.ts:350](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L350) +Defined in: [packages/db/src/types.ts:351](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L351) ## Properties @@ -15,7 +15,7 @@ Defined in: [packages/db/src/types.ts:350](https://github.com/TanStack/db/blob/m optional metadata: Record; ``` -Defined in: [packages/db/src/types.ts:351](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L351) +Defined in: [packages/db/src/types.ts:352](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L352) *** @@ -25,6 +25,6 @@ Defined in: [packages/db/src/types.ts:351](https://github.com/TanStack/db/blob/m optional optimistic: boolean; ``` -Defined in: [packages/db/src/types.ts:353](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L353) +Defined in: [packages/db/src/types.ts:354](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L354) Whether to apply optimistic updates immediately. Defaults to true. diff --git a/docs/reference/interfaces/OptimisticChangeMessage.md b/docs/reference/interfaces/OptimisticChangeMessage.md index 9d38e5a51..0893a0361 100644 --- a/docs/reference/interfaces/OptimisticChangeMessage.md +++ b/docs/reference/interfaces/OptimisticChangeMessage.md @@ -5,7 +5,7 @@ title: OptimisticChangeMessage # Interface: OptimisticChangeMessage\ -Defined in: [packages/db/src/types.ts:325](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L325) +Defined in: [packages/db/src/types.ts:326](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L326) ## Extends @@ -25,7 +25,7 @@ Defined in: [packages/db/src/types.ts:325](https://github.com/TanStack/db/blob/m optional isActive: boolean; ``` -Defined in: [packages/db/src/types.ts:329](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L329) +Defined in: [packages/db/src/types.ts:330](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L330) *** @@ -35,7 +35,7 @@ Defined in: [packages/db/src/types.ts:329](https://github.com/TanStack/db/blob/m key: string | number; ``` -Defined in: [packages/db/src/types.ts:318](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L318) +Defined in: [packages/db/src/types.ts:319](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L319) #### Inherited from @@ -49,7 +49,7 @@ Defined in: [packages/db/src/types.ts:318](https://github.com/TanStack/db/blob/m optional metadata: Record; ``` -Defined in: [packages/db/src/types.ts:322](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L322) +Defined in: [packages/db/src/types.ts:323](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L323) #### Inherited from @@ -63,7 +63,7 @@ Defined in: [packages/db/src/types.ts:322](https://github.com/TanStack/db/blob/m optional previousValue: T; ``` -Defined in: [packages/db/src/types.ts:320](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L320) +Defined in: [packages/db/src/types.ts:321](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L321) #### Inherited from @@ -77,7 +77,7 @@ Defined in: [packages/db/src/types.ts:320](https://github.com/TanStack/db/blob/m type: OperationType; ``` -Defined in: [packages/db/src/types.ts:321](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L321) +Defined in: [packages/db/src/types.ts:322](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L322) #### Inherited from @@ -91,7 +91,7 @@ Defined in: [packages/db/src/types.ts:321](https://github.com/TanStack/db/blob/m value: T; ``` -Defined in: [packages/db/src/types.ts:319](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L319) +Defined in: [packages/db/src/types.ts:320](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L320) #### Inherited from diff --git a/docs/reference/interfaces/PendingMutation.md b/docs/reference/interfaces/PendingMutation.md index 2b9c68cc9..d6cc2b7c8 100644 --- a/docs/reference/interfaces/PendingMutation.md +++ b/docs/reference/interfaces/PendingMutation.md @@ -5,7 +5,7 @@ title: PendingMutation # Interface: PendingMutation\ -Defined in: [packages/db/src/types.ts:88](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L88) +Defined in: [packages/db/src/types.ts:89](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L89) Represents a pending mutation within a transaction Contains information about the original and modified data, as well as metadata @@ -32,7 +32,7 @@ Contains information about the original and modified data, as well as metadata changes: ResolveTransactionChanges; ``` -Defined in: [packages/db/src/types.ts:105](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L105) +Defined in: [packages/db/src/types.ts:106](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L106) *** @@ -42,7 +42,7 @@ Defined in: [packages/db/src/types.ts:105](https://github.com/TanStack/db/blob/m collection: TCollection; ``` -Defined in: [packages/db/src/types.ts:116](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L116) +Defined in: [packages/db/src/types.ts:117](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L117) *** @@ -52,7 +52,7 @@ Defined in: [packages/db/src/types.ts:116](https://github.com/TanStack/db/blob/m createdAt: Date; ``` -Defined in: [packages/db/src/types.ts:114](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L114) +Defined in: [packages/db/src/types.ts:115](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L115) *** @@ -62,7 +62,7 @@ Defined in: [packages/db/src/types.ts:114](https://github.com/TanStack/db/blob/m globalKey: string; ``` -Defined in: [packages/db/src/types.ts:106](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L106) +Defined in: [packages/db/src/types.ts:107](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L107) *** @@ -72,7 +72,7 @@ Defined in: [packages/db/src/types.ts:106](https://github.com/TanStack/db/blob/m key: any; ``` -Defined in: [packages/db/src/types.ts:108](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L108) +Defined in: [packages/db/src/types.ts:109](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L109) *** @@ -82,7 +82,7 @@ Defined in: [packages/db/src/types.ts:108](https://github.com/TanStack/db/blob/m metadata: unknown; ``` -Defined in: [packages/db/src/types.ts:110](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L110) +Defined in: [packages/db/src/types.ts:111](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L111) *** @@ -92,7 +92,7 @@ Defined in: [packages/db/src/types.ts:110](https://github.com/TanStack/db/blob/m modified: T; ``` -Defined in: [packages/db/src/types.ts:103](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L103) +Defined in: [packages/db/src/types.ts:104](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L104) *** @@ -102,7 +102,7 @@ Defined in: [packages/db/src/types.ts:103](https://github.com/TanStack/db/blob/m mutationId: string; ``` -Defined in: [packages/db/src/types.ts:99](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L99) +Defined in: [packages/db/src/types.ts:100](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L100) *** @@ -112,7 +112,7 @@ Defined in: [packages/db/src/types.ts:99](https://github.com/TanStack/db/blob/ma optimistic: boolean; ``` -Defined in: [packages/db/src/types.ts:113](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L113) +Defined in: [packages/db/src/types.ts:114](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L114) Whether this mutation should be applied optimistically (defaults to true) @@ -124,7 +124,7 @@ Whether this mutation should be applied optimistically (defaults to true) original: TOperation extends "insert" ? object : T; ``` -Defined in: [packages/db/src/types.ts:101](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L101) +Defined in: [packages/db/src/types.ts:102](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L102) *** @@ -134,7 +134,7 @@ Defined in: [packages/db/src/types.ts:101](https://github.com/TanStack/db/blob/m syncMetadata: Record; ``` -Defined in: [packages/db/src/types.ts:111](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L111) +Defined in: [packages/db/src/types.ts:112](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L112) *** @@ -144,7 +144,7 @@ Defined in: [packages/db/src/types.ts:111](https://github.com/TanStack/db/blob/m type: TOperation; ``` -Defined in: [packages/db/src/types.ts:109](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L109) +Defined in: [packages/db/src/types.ts:110](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L110) *** @@ -154,4 +154,4 @@ Defined in: [packages/db/src/types.ts:109](https://github.com/TanStack/db/blob/m updatedAt: Date; ``` -Defined in: [packages/db/src/types.ts:115](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L115) +Defined in: [packages/db/src/types.ts:116](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L116) diff --git a/docs/reference/interfaces/RangeQueryOptions.md b/docs/reference/interfaces/RangeQueryOptions.md deleted file mode 100644 index cdf9c1ba4..000000000 --- a/docs/reference/interfaces/RangeQueryOptions.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -id: RangeQueryOptions -title: RangeQueryOptions ---- - -# Interface: RangeQueryOptions - -Defined in: [packages/db/src/indexes/btree-index.ts:20](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L20) - -Options for range queries - -## Properties - -### from? - -```ts -optional from: any; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:21](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L21) - -*** - -### fromInclusive? - -```ts -optional fromInclusive: boolean; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:23](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L23) - -*** - -### to? - -```ts -optional to: any; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:22](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L22) - -*** - -### toInclusive? - -```ts -optional toInclusive: boolean; -``` - -Defined in: [packages/db/src/indexes/btree-index.ts:24](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/btree-index.ts#L24) diff --git a/docs/reference/interfaces/SubscribeChangesOptions.md b/docs/reference/interfaces/SubscribeChangesOptions.md index 901fa75b6..e30b7d5e0 100644 --- a/docs/reference/interfaces/SubscribeChangesOptions.md +++ b/docs/reference/interfaces/SubscribeChangesOptions.md @@ -5,7 +5,7 @@ title: SubscribeChangesOptions # Interface: SubscribeChangesOptions -Defined in: [packages/db/src/types.ts:723](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L723) +Defined in: [packages/db/src/types.ts:739](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L739) Options for subscribing to collection changes @@ -17,7 +17,7 @@ Options for subscribing to collection changes optional includeInitialState: boolean; ``` -Defined in: [packages/db/src/types.ts:725](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L725) +Defined in: [packages/db/src/types.ts:741](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L741) Whether to include the current state as initial changes @@ -29,6 +29,6 @@ Whether to include the current state as initial changes optional whereExpression: BasicExpression; ``` -Defined in: [packages/db/src/types.ts:727](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L727) +Defined in: [packages/db/src/types.ts:743](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L743) Pre-compiled expression for filtering changes diff --git a/docs/reference/interfaces/SubscribeChangesSnapshotOptions.md b/docs/reference/interfaces/SubscribeChangesSnapshotOptions.md index 891572c77..12ce89619 100644 --- a/docs/reference/interfaces/SubscribeChangesSnapshotOptions.md +++ b/docs/reference/interfaces/SubscribeChangesSnapshotOptions.md @@ -5,7 +5,7 @@ title: SubscribeChangesSnapshotOptions # Interface: SubscribeChangesSnapshotOptions -Defined in: [packages/db/src/types.ts:730](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L730) +Defined in: [packages/db/src/types.ts:746](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L746) ## Extends @@ -19,7 +19,7 @@ Defined in: [packages/db/src/types.ts:730](https://github.com/TanStack/db/blob/m optional limit: number; ``` -Defined in: [packages/db/src/types.ts:735](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L735) +Defined in: [packages/db/src/types.ts:751](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L751) *** @@ -29,7 +29,7 @@ Defined in: [packages/db/src/types.ts:735](https://github.com/TanStack/db/blob/m optional orderBy: OrderBy; ``` -Defined in: [packages/db/src/types.ts:734](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L734) +Defined in: [packages/db/src/types.ts:750](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L750) *** @@ -39,7 +39,7 @@ Defined in: [packages/db/src/types.ts:734](https://github.com/TanStack/db/blob/m optional whereExpression: BasicExpression; ``` -Defined in: [packages/db/src/types.ts:727](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L727) +Defined in: [packages/db/src/types.ts:743](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L743) Pre-compiled expression for filtering changes diff --git a/docs/reference/interfaces/Subscription.md b/docs/reference/interfaces/Subscription.md index c8cb4a790..0aa55abe0 100644 --- a/docs/reference/interfaces/Subscription.md +++ b/docs/reference/interfaces/Subscription.md @@ -5,7 +5,7 @@ title: Subscription # Interface: Subscription -Defined in: [packages/db/src/types.ts:251](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L251) +Defined in: [packages/db/src/types.ts:252](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L252) Public interface for a collection subscription Used by sync implementations to track subscription lifecycle @@ -22,7 +22,7 @@ Used by sync implementations to track subscription lifecycle readonly status: SubscriptionStatus; ``` -Defined in: [packages/db/src/types.ts:253](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L253) +Defined in: [packages/db/src/types.ts:254](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L254) Current status of the subscription diff --git a/docs/reference/interfaces/SubscriptionStatusChangeEvent.md b/docs/reference/interfaces/SubscriptionStatusChangeEvent.md index a14b841c3..ed2298b09 100644 --- a/docs/reference/interfaces/SubscriptionStatusChangeEvent.md +++ b/docs/reference/interfaces/SubscriptionStatusChangeEvent.md @@ -5,7 +5,7 @@ title: SubscriptionStatusChangeEvent # Interface: SubscriptionStatusChangeEvent -Defined in: [packages/db/src/types.ts:212](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L212) +Defined in: [packages/db/src/types.ts:213](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L213) Event emitted when subscription status changes @@ -17,7 +17,7 @@ Event emitted when subscription status changes previousStatus: SubscriptionStatus; ``` -Defined in: [packages/db/src/types.ts:215](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L215) +Defined in: [packages/db/src/types.ts:216](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L216) *** @@ -27,7 +27,7 @@ Defined in: [packages/db/src/types.ts:215](https://github.com/TanStack/db/blob/m status: SubscriptionStatus; ``` -Defined in: [packages/db/src/types.ts:216](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L216) +Defined in: [packages/db/src/types.ts:217](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L217) *** @@ -37,7 +37,7 @@ Defined in: [packages/db/src/types.ts:216](https://github.com/TanStack/db/blob/m subscription: Subscription; ``` -Defined in: [packages/db/src/types.ts:214](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L214) +Defined in: [packages/db/src/types.ts:215](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L215) *** @@ -47,4 +47,4 @@ Defined in: [packages/db/src/types.ts:214](https://github.com/TanStack/db/blob/m type: "status:change"; ``` -Defined in: [packages/db/src/types.ts:213](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L213) +Defined in: [packages/db/src/types.ts:214](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L214) diff --git a/docs/reference/interfaces/SubscriptionStatusEvent.md b/docs/reference/interfaces/SubscriptionStatusEvent.md index a84679586..0d55a134d 100644 --- a/docs/reference/interfaces/SubscriptionStatusEvent.md +++ b/docs/reference/interfaces/SubscriptionStatusEvent.md @@ -5,7 +5,7 @@ title: SubscriptionStatusEvent # Interface: SubscriptionStatusEvent\ -Defined in: [packages/db/src/types.ts:222](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L222) +Defined in: [packages/db/src/types.ts:223](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L223) Event emitted when subscription status changes to a specific status @@ -23,7 +23,7 @@ Event emitted when subscription status changes to a specific status previousStatus: SubscriptionStatus; ``` -Defined in: [packages/db/src/types.ts:225](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L225) +Defined in: [packages/db/src/types.ts:226](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L226) *** @@ -33,7 +33,7 @@ Defined in: [packages/db/src/types.ts:225](https://github.com/TanStack/db/blob/m status: T; ``` -Defined in: [packages/db/src/types.ts:226](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L226) +Defined in: [packages/db/src/types.ts:227](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L227) *** @@ -43,7 +43,7 @@ Defined in: [packages/db/src/types.ts:226](https://github.com/TanStack/db/blob/m subscription: Subscription; ``` -Defined in: [packages/db/src/types.ts:224](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L224) +Defined in: [packages/db/src/types.ts:225](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L225) *** @@ -53,4 +53,4 @@ Defined in: [packages/db/src/types.ts:224](https://github.com/TanStack/db/blob/m type: `status:${T}`; ``` -Defined in: [packages/db/src/types.ts:223](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L223) +Defined in: [packages/db/src/types.ts:224](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L224) diff --git a/docs/reference/interfaces/SubscriptionUnsubscribedEvent.md b/docs/reference/interfaces/SubscriptionUnsubscribedEvent.md index df71d1075..6eea86fa2 100644 --- a/docs/reference/interfaces/SubscriptionUnsubscribedEvent.md +++ b/docs/reference/interfaces/SubscriptionUnsubscribedEvent.md @@ -5,7 +5,7 @@ title: SubscriptionUnsubscribedEvent # Interface: SubscriptionUnsubscribedEvent -Defined in: [packages/db/src/types.ts:232](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L232) +Defined in: [packages/db/src/types.ts:233](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L233) Event emitted when subscription is unsubscribed @@ -17,7 +17,7 @@ Event emitted when subscription is unsubscribed subscription: Subscription; ``` -Defined in: [packages/db/src/types.ts:234](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L234) +Defined in: [packages/db/src/types.ts:235](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L235) *** @@ -27,4 +27,4 @@ Defined in: [packages/db/src/types.ts:234](https://github.com/TanStack/db/blob/m type: "unsubscribed"; ``` -Defined in: [packages/db/src/types.ts:233](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L233) +Defined in: [packages/db/src/types.ts:234](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L234) diff --git a/docs/reference/interfaces/SyncConfig.md b/docs/reference/interfaces/SyncConfig.md index 495813de2..703550b7d 100644 --- a/docs/reference/interfaces/SyncConfig.md +++ b/docs/reference/interfaces/SyncConfig.md @@ -5,7 +5,7 @@ title: SyncConfig # Interface: SyncConfig\ -Defined in: [packages/db/src/types.ts:285](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L285) +Defined in: [packages/db/src/types.ts:286](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L286) ## Type Parameters @@ -25,7 +25,7 @@ Defined in: [packages/db/src/types.ts:285](https://github.com/TanStack/db/blob/m optional getSyncMetadata: () => Record; ``` -Defined in: [packages/db/src/types.ts:302](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L302) +Defined in: [packages/db/src/types.ts:303](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L303) Get the sync metadata for insert operations @@ -43,7 +43,7 @@ Record containing relation information optional rowUpdateMode: "full" | "partial"; ``` -Defined in: [packages/db/src/types.ts:311](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L311) +Defined in: [packages/db/src/types.ts:312](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L312) The row update mode used to sync to the collection. @@ -67,7 +67,7 @@ sync: (params) => | SyncConfigRes; ``` -Defined in: [packages/db/src/types.ts:289](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L289) +Defined in: [packages/db/src/types.ts:290](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L290) #### Parameters diff --git a/docs/reference/interfaces/TransactionConfig.md b/docs/reference/interfaces/TransactionConfig.md index 3550c36dc..ae5f413e9 100644 --- a/docs/reference/interfaces/TransactionConfig.md +++ b/docs/reference/interfaces/TransactionConfig.md @@ -5,7 +5,7 @@ title: TransactionConfig # Interface: TransactionConfig\ -Defined in: [packages/db/src/types.ts:165](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L165) +Defined in: [packages/db/src/types.ts:166](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L166) ## Type Parameters @@ -21,7 +21,7 @@ Defined in: [packages/db/src/types.ts:165](https://github.com/TanStack/db/blob/m optional autoCommit: boolean; ``` -Defined in: [packages/db/src/types.ts:169](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L169) +Defined in: [packages/db/src/types.ts:170](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L170) *** @@ -31,7 +31,7 @@ Defined in: [packages/db/src/types.ts:169](https://github.com/TanStack/db/blob/m optional id: string; ``` -Defined in: [packages/db/src/types.ts:167](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L167) +Defined in: [packages/db/src/types.ts:168](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L168) Unique identifier for the transaction @@ -43,7 +43,7 @@ Unique identifier for the transaction optional metadata: Record; ``` -Defined in: [packages/db/src/types.ts:172](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L172) +Defined in: [packages/db/src/types.ts:173](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L173) Custom metadata to associate with the transaction @@ -55,4 +55,4 @@ Custom metadata to associate with the transaction mutationFn: MutationFn; ``` -Defined in: [packages/db/src/types.ts:170](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L170) +Defined in: [packages/db/src/types.ts:171](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L171) diff --git a/docs/reference/type-aliases/ChangeListener.md b/docs/reference/type-aliases/ChangeListener.md index 2c6c931b2..14ca8bbc6 100644 --- a/docs/reference/type-aliases/ChangeListener.md +++ b/docs/reference/type-aliases/ChangeListener.md @@ -9,7 +9,7 @@ title: ChangeListener type ChangeListener = (changes) => void; ``` -Defined in: [packages/db/src/types.ts:780](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L780) +Defined in: [packages/db/src/types.ts:796](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L796) Function type for listening to collection changes diff --git a/docs/reference/type-aliases/ChangesPayload.md b/docs/reference/type-aliases/ChangesPayload.md index 492558932..f0c036e07 100644 --- a/docs/reference/type-aliases/ChangesPayload.md +++ b/docs/reference/type-aliases/ChangesPayload.md @@ -9,7 +9,7 @@ title: ChangesPayload type ChangesPayload = ChangeMessage[]; ``` -Defined in: [packages/db/src/types.ts:681](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L681) +Defined in: [packages/db/src/types.ts:697](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L697) ## Type Parameters diff --git a/docs/reference/type-aliases/CleanupFn.md b/docs/reference/type-aliases/CleanupFn.md index 75202b7a1..11968a09d 100644 --- a/docs/reference/type-aliases/CleanupFn.md +++ b/docs/reference/type-aliases/CleanupFn.md @@ -9,7 +9,7 @@ title: CleanupFn type CleanupFn = () => void; ``` -Defined in: [packages/db/src/types.ts:278](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L278) +Defined in: [packages/db/src/types.ts:279](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L279) ## Returns diff --git a/docs/reference/type-aliases/CollectionConfigSingleRowOption.md b/docs/reference/type-aliases/CollectionConfigSingleRowOption.md index fb95fbc12..e952e77d5 100644 --- a/docs/reference/type-aliases/CollectionConfigSingleRowOption.md +++ b/docs/reference/type-aliases/CollectionConfigSingleRowOption.md @@ -9,7 +9,7 @@ title: CollectionConfigSingleRowOption type CollectionConfigSingleRowOption = CollectionConfig & MaybeSingleResult; ``` -Defined in: [packages/db/src/types.ts:674](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L674) +Defined in: [packages/db/src/types.ts:690](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L690) ## Type Parameters diff --git a/docs/reference/type-aliases/CollectionStatus.md b/docs/reference/type-aliases/CollectionStatus.md index de248cd6e..27dcf58f9 100644 --- a/docs/reference/type-aliases/CollectionStatus.md +++ b/docs/reference/type-aliases/CollectionStatus.md @@ -9,7 +9,7 @@ title: CollectionStatus type CollectionStatus = "idle" | "loading" | "ready" | "error" | "cleaned-up"; ``` -Defined in: [packages/db/src/types.ts:424](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L424) +Defined in: [packages/db/src/types.ts:425](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L425) Collection status values for lifecycle management diff --git a/docs/reference/type-aliases/DeleteMutationFn.md b/docs/reference/type-aliases/DeleteMutationFn.md index 35716ab0e..f396cb19a 100644 --- a/docs/reference/type-aliases/DeleteMutationFn.md +++ b/docs/reference/type-aliases/DeleteMutationFn.md @@ -9,7 +9,7 @@ title: DeleteMutationFn type DeleteMutationFn = (params) => Promise; ``` -Defined in: [packages/db/src/types.ts:402](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L402) +Defined in: [packages/db/src/types.ts:403](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L403) ## Type Parameters diff --git a/docs/reference/type-aliases/DeleteMutationFnParams.md b/docs/reference/type-aliases/DeleteMutationFnParams.md index 2e3885ea7..b59dcb222 100644 --- a/docs/reference/type-aliases/DeleteMutationFnParams.md +++ b/docs/reference/type-aliases/DeleteMutationFnParams.md @@ -9,7 +9,7 @@ title: DeleteMutationFnParams type DeleteMutationFnParams = object; ``` -Defined in: [packages/db/src/types.ts:379](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L379) +Defined in: [packages/db/src/types.ts:380](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L380) ## Type Parameters @@ -33,7 +33,7 @@ Defined in: [packages/db/src/types.ts:379](https://github.com/TanStack/db/blob/m collection: Collection; ``` -Defined in: [packages/db/src/types.ts:385](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L385) +Defined in: [packages/db/src/types.ts:386](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L386) *** @@ -43,4 +43,4 @@ Defined in: [packages/db/src/types.ts:385](https://github.com/TanStack/db/blob/m transaction: TransactionWithMutations; ``` -Defined in: [packages/db/src/types.ts:384](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L384) +Defined in: [packages/db/src/types.ts:385](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L385) diff --git a/docs/reference/type-aliases/Fn.md b/docs/reference/type-aliases/Fn.md index d4cc38176..e79a1aca2 100644 --- a/docs/reference/type-aliases/Fn.md +++ b/docs/reference/type-aliases/Fn.md @@ -9,7 +9,7 @@ title: Fn type Fn = (...args) => any; ``` -Defined in: [packages/db/src/types.ts:66](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L66) +Defined in: [packages/db/src/types.ts:67](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L67) Represents a utility function that can be attached to a collection diff --git a/docs/reference/type-aliases/IndexOperation-1.md b/docs/reference/type-aliases/IndexOperation-1.md new file mode 100644 index 000000000..3dbce14d1 --- /dev/null +++ b/docs/reference/type-aliases/IndexOperation-1.md @@ -0,0 +1,14 @@ +--- +id: IndexOperation +title: IndexOperation +--- + +# Type Alias: IndexOperation + +```ts +type IndexOperation = typeof comparisonFunctions[number]; +``` + +Defined in: [packages/db/src/indexes/base-index.ts:11](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L11) + +Type for index operation values diff --git a/docs/reference/type-aliases/IndexOperation.md b/docs/reference/type-aliases/IndexOperation.md index 3dbce14d1..23f84e1c0 100644 --- a/docs/reference/type-aliases/IndexOperation.md +++ b/docs/reference/type-aliases/IndexOperation.md @@ -6,9 +6,9 @@ title: IndexOperation # Type Alias: IndexOperation ```ts -type IndexOperation = typeof comparisonFunctions[number]; +type IndexOperation = readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike"]; ``` Defined in: [packages/db/src/indexes/base-index.ts:11](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L11) -Type for index operation values +Operations that indexes can support, imported from available comparison functions diff --git a/docs/reference/type-aliases/IndexResolver.md b/docs/reference/type-aliases/IndexResolver.md deleted file mode 100644 index 8dcd5c3e5..000000000 --- a/docs/reference/type-aliases/IndexResolver.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: IndexResolver -title: IndexResolver ---- - -# Type Alias: IndexResolver\ - -```ts -type IndexResolver = - | IndexConstructor -| () => Promise>; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:212](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L212) - -Index resolver can be either a class constructor or async loader - -## Type Parameters - -### TKey - -`TKey` *extends* `string` \| `number` = `string` \| `number` diff --git a/docs/reference/type-aliases/InferSchemaInput.md b/docs/reference/type-aliases/InferSchemaInput.md index e209e5475..1e6ad08ff 100644 --- a/docs/reference/type-aliases/InferSchemaInput.md +++ b/docs/reference/type-aliases/InferSchemaInput.md @@ -9,7 +9,7 @@ title: InferSchemaInput type InferSchemaInput = T extends StandardSchemaV1 ? StandardSchemaV1.InferInput extends object ? StandardSchemaV1.InferInput : Record : Record; ``` -Defined in: [packages/db/src/types.ts:55](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L55) +Defined in: [packages/db/src/types.ts:56](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L56) **`Internal`** diff --git a/docs/reference/type-aliases/InferSchemaOutput.md b/docs/reference/type-aliases/InferSchemaOutput.md index 9069db64b..7b170e663 100644 --- a/docs/reference/type-aliases/InferSchemaOutput.md +++ b/docs/reference/type-aliases/InferSchemaOutput.md @@ -9,7 +9,7 @@ title: InferSchemaOutput type InferSchemaOutput = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput extends object ? StandardSchemaV1.InferOutput : Record : Record; ``` -Defined in: [packages/db/src/types.ts:44](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L44) +Defined in: [packages/db/src/types.ts:45](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L45) **`Internal`** diff --git a/docs/reference/type-aliases/InputRow.md b/docs/reference/type-aliases/InputRow.md index 991ce93f7..430fbfc30 100644 --- a/docs/reference/type-aliases/InputRow.md +++ b/docs/reference/type-aliases/InputRow.md @@ -9,6 +9,6 @@ title: InputRow type InputRow = [unknown, Record]; ``` -Defined in: [packages/db/src/types.ts:688](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L688) +Defined in: [packages/db/src/types.ts:704](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L704) An input row from a collection diff --git a/docs/reference/type-aliases/InsertMutationFn.md b/docs/reference/type-aliases/InsertMutationFn.md index be33c491a..c6c3a38bf 100644 --- a/docs/reference/type-aliases/InsertMutationFn.md +++ b/docs/reference/type-aliases/InsertMutationFn.md @@ -9,7 +9,7 @@ title: InsertMutationFn type InsertMutationFn = (params) => Promise; ``` -Defined in: [packages/db/src/types.ts:388](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L388) +Defined in: [packages/db/src/types.ts:389](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L389) ## Type Parameters diff --git a/docs/reference/type-aliases/InsertMutationFnParams.md b/docs/reference/type-aliases/InsertMutationFnParams.md index 5a443bb6a..88df32638 100644 --- a/docs/reference/type-aliases/InsertMutationFnParams.md +++ b/docs/reference/type-aliases/InsertMutationFnParams.md @@ -9,7 +9,7 @@ title: InsertMutationFnParams type InsertMutationFnParams = object; ``` -Defined in: [packages/db/src/types.ts:371](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L371) +Defined in: [packages/db/src/types.ts:372](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L372) ## Type Parameters @@ -33,7 +33,7 @@ Defined in: [packages/db/src/types.ts:371](https://github.com/TanStack/db/blob/m collection: Collection; ``` -Defined in: [packages/db/src/types.ts:377](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L377) +Defined in: [packages/db/src/types.ts:378](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L378) *** @@ -43,4 +43,4 @@ Defined in: [packages/db/src/types.ts:377](https://github.com/TanStack/db/blob/m transaction: TransactionWithMutations; ``` -Defined in: [packages/db/src/types.ts:376](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L376) +Defined in: [packages/db/src/types.ts:377](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L377) diff --git a/docs/reference/type-aliases/KeyedNamespacedRow.md b/docs/reference/type-aliases/KeyedNamespacedRow.md index 8a1de5808..990c5484d 100644 --- a/docs/reference/type-aliases/KeyedNamespacedRow.md +++ b/docs/reference/type-aliases/KeyedNamespacedRow.md @@ -9,7 +9,7 @@ title: KeyedNamespacedRow type KeyedNamespacedRow = [unknown, NamespacedRow]; ``` -Defined in: [packages/db/src/types.ts:711](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L711) +Defined in: [packages/db/src/types.ts:727](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L727) A keyed namespaced row is a row with a key and a namespaced row This is the main representation of a row in a query pipeline diff --git a/docs/reference/type-aliases/KeyedStream.md b/docs/reference/type-aliases/KeyedStream.md index d8607f87a..88037ece8 100644 --- a/docs/reference/type-aliases/KeyedStream.md +++ b/docs/reference/type-aliases/KeyedStream.md @@ -9,7 +9,7 @@ title: KeyedStream type KeyedStream = IStreamBuilder; ``` -Defined in: [packages/db/src/types.ts:694](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L694) +Defined in: [packages/db/src/types.ts:710](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L710) A keyed stream is a stream of rows This is used as the inputs from a collection to a query diff --git a/docs/reference/type-aliases/LoadSubsetFn.md b/docs/reference/type-aliases/LoadSubsetFn.md index 540df483f..d13450074 100644 --- a/docs/reference/type-aliases/LoadSubsetFn.md +++ b/docs/reference/type-aliases/LoadSubsetFn.md @@ -9,7 +9,7 @@ title: LoadSubsetFn type LoadSubsetFn = (options) => true | Promise; ``` -Defined in: [packages/db/src/types.ts:274](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L274) +Defined in: [packages/db/src/types.ts:275](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L275) ## Parameters diff --git a/docs/reference/type-aliases/LoadSubsetOptions.md b/docs/reference/type-aliases/LoadSubsetOptions.md index 64c0a3c4e..677830ed0 100644 --- a/docs/reference/type-aliases/LoadSubsetOptions.md +++ b/docs/reference/type-aliases/LoadSubsetOptions.md @@ -9,7 +9,7 @@ title: LoadSubsetOptions type LoadSubsetOptions = object; ``` -Defined in: [packages/db/src/types.ts:256](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L256) +Defined in: [packages/db/src/types.ts:257](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L257) ## Properties @@ -19,7 +19,7 @@ Defined in: [packages/db/src/types.ts:256](https://github.com/TanStack/db/blob/m optional limit: number; ``` -Defined in: [packages/db/src/types.ts:262](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L262) +Defined in: [packages/db/src/types.ts:263](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L263) The limit of the data to load @@ -31,7 +31,7 @@ The limit of the data to load optional orderBy: OrderBy; ``` -Defined in: [packages/db/src/types.ts:260](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L260) +Defined in: [packages/db/src/types.ts:261](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L261) The order by clause to sort the data @@ -43,7 +43,7 @@ The order by clause to sort the data optional subscription: Subscription; ``` -Defined in: [packages/db/src/types.ts:271](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L271) +Defined in: [packages/db/src/types.ts:272](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L272) The subscription that triggered the load. Advanced sync implementations can use this for: @@ -63,6 +63,6 @@ Available when called from CollectionSubscription, may be undefined for direct c optional where: BasicExpression; ``` -Defined in: [packages/db/src/types.ts:258](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L258) +Defined in: [packages/db/src/types.ts:259](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L259) The where expression to filter the data diff --git a/docs/reference/type-aliases/MaybeSingleResult.md b/docs/reference/type-aliases/MaybeSingleResult.md index 95512ef93..a5585f931 100644 --- a/docs/reference/type-aliases/MaybeSingleResult.md +++ b/docs/reference/type-aliases/MaybeSingleResult.md @@ -9,7 +9,7 @@ title: MaybeSingleResult type MaybeSingleResult = object; ``` -Defined in: [packages/db/src/types.ts:666](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L666) +Defined in: [packages/db/src/types.ts:682](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L682) ## Properties @@ -19,6 +19,6 @@ Defined in: [packages/db/src/types.ts:666](https://github.com/TanStack/db/blob/m optional singleResult: true; ``` -Defined in: [packages/db/src/types.ts:670](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L670) +Defined in: [packages/db/src/types.ts:686](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L686) If enabled the collection will return a single object instead of an array diff --git a/docs/reference/type-aliases/MutationFn.md b/docs/reference/type-aliases/MutationFn.md index 9ebaa5538..33ff9dcf1 100644 --- a/docs/reference/type-aliases/MutationFn.md +++ b/docs/reference/type-aliases/MutationFn.md @@ -9,7 +9,7 @@ title: MutationFn type MutationFn = (params) => Promise; ``` -Defined in: [packages/db/src/types.ts:126](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L126) +Defined in: [packages/db/src/types.ts:127](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L127) ## Type Parameters diff --git a/docs/reference/type-aliases/MutationFnParams.md b/docs/reference/type-aliases/MutationFnParams.md index e7b51681f..7df30d800 100644 --- a/docs/reference/type-aliases/MutationFnParams.md +++ b/docs/reference/type-aliases/MutationFnParams.md @@ -9,7 +9,7 @@ title: MutationFnParams type MutationFnParams = object; ``` -Defined in: [packages/db/src/types.ts:122](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L122) +Defined in: [packages/db/src/types.ts:123](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L123) Configuration options for creating a new transaction @@ -27,4 +27,4 @@ Configuration options for creating a new transaction transaction: TransactionWithMutations; ``` -Defined in: [packages/db/src/types.ts:123](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L123) +Defined in: [packages/db/src/types.ts:124](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L124) diff --git a/docs/reference/type-aliases/NamespacedAndKeyedStream.md b/docs/reference/type-aliases/NamespacedAndKeyedStream.md index c7d501506..1d8f5c57b 100644 --- a/docs/reference/type-aliases/NamespacedAndKeyedStream.md +++ b/docs/reference/type-aliases/NamespacedAndKeyedStream.md @@ -9,7 +9,7 @@ title: NamespacedAndKeyedStream type NamespacedAndKeyedStream = IStreamBuilder; ``` -Defined in: [packages/db/src/types.ts:718](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L718) +Defined in: [packages/db/src/types.ts:734](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L734) A namespaced and keyed stream is a stream of rows This is used throughout a query pipeline and as the output from a query without diff --git a/docs/reference/type-aliases/NamespacedRow.md b/docs/reference/type-aliases/NamespacedRow.md index f2759dc9e..1e794449b 100644 --- a/docs/reference/type-aliases/NamespacedRow.md +++ b/docs/reference/type-aliases/NamespacedRow.md @@ -9,6 +9,6 @@ title: NamespacedRow type NamespacedRow = Record>; ``` -Defined in: [packages/db/src/types.ts:705](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L705) +Defined in: [packages/db/src/types.ts:721](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L721) A namespaced row is a row withing a pipeline that had each table wrapped in its alias diff --git a/docs/reference/type-aliases/NonEmptyArray.md b/docs/reference/type-aliases/NonEmptyArray.md index 563202223..3ff5d7dfa 100644 --- a/docs/reference/type-aliases/NonEmptyArray.md +++ b/docs/reference/type-aliases/NonEmptyArray.md @@ -9,7 +9,7 @@ title: NonEmptyArray type NonEmptyArray = [T, ...T[]]; ``` -Defined in: [packages/db/src/types.ts:133](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L133) +Defined in: [packages/db/src/types.ts:134](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L134) Represents a non-empty array (at least one element) diff --git a/docs/reference/type-aliases/NonSingleResult.md b/docs/reference/type-aliases/NonSingleResult.md index 7a7306afb..e08344959 100644 --- a/docs/reference/type-aliases/NonSingleResult.md +++ b/docs/reference/type-aliases/NonSingleResult.md @@ -9,7 +9,7 @@ title: NonSingleResult type NonSingleResult = object; ``` -Defined in: [packages/db/src/types.ts:662](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L662) +Defined in: [packages/db/src/types.ts:678](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L678) ## Properties @@ -19,4 +19,4 @@ Defined in: [packages/db/src/types.ts:662](https://github.com/TanStack/db/blob/m optional singleResult: never; ``` -Defined in: [packages/db/src/types.ts:663](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L663) +Defined in: [packages/db/src/types.ts:679](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L679) diff --git a/docs/reference/type-aliases/OperationType.md b/docs/reference/type-aliases/OperationType.md index 20c3578a8..2f9b1f6c7 100644 --- a/docs/reference/type-aliases/OperationType.md +++ b/docs/reference/type-aliases/OperationType.md @@ -9,4 +9,4 @@ title: OperationType type OperationType = "insert" | "update" | "delete"; ``` -Defined in: [packages/db/src/types.ts:202](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L202) +Defined in: [packages/db/src/types.ts:203](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L203) diff --git a/docs/reference/type-aliases/ResolveTransactionChanges.md b/docs/reference/type-aliases/ResolveTransactionChanges.md index 12a4e2ed0..fa6a413cb 100644 --- a/docs/reference/type-aliases/ResolveTransactionChanges.md +++ b/docs/reference/type-aliases/ResolveTransactionChanges.md @@ -9,7 +9,7 @@ title: ResolveTransactionChanges type ResolveTransactionChanges = TOperation extends "delete" ? T : Partial; ``` -Defined in: [packages/db/src/types.ts:79](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L79) +Defined in: [packages/db/src/types.ts:80](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L80) ## Type Parameters diff --git a/docs/reference/type-aliases/ResultStream.md b/docs/reference/type-aliases/ResultStream.md index bce6ea4af..c1553db05 100644 --- a/docs/reference/type-aliases/ResultStream.md +++ b/docs/reference/type-aliases/ResultStream.md @@ -9,7 +9,7 @@ title: ResultStream type ResultStream = IStreamBuilder<[unknown, [any, string | undefined]]>; ``` -Defined in: [packages/db/src/types.ts:700](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L700) +Defined in: [packages/db/src/types.ts:716](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L716) Result stream type representing the output of compiled queries Always returns [key, [result, orderByIndex]] where orderByIndex is undefined for unordered queries diff --git a/docs/reference/type-aliases/Row.md b/docs/reference/type-aliases/Row.md index 1fa149323..4e9a7cff1 100644 --- a/docs/reference/type-aliases/Row.md +++ b/docs/reference/type-aliases/Row.md @@ -9,7 +9,7 @@ title: Row type Row = Record>; ``` -Defined in: [packages/db/src/types.ts:200](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L200) +Defined in: [packages/db/src/types.ts:201](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L201) ## Type Parameters diff --git a/docs/reference/type-aliases/SingleResult.md b/docs/reference/type-aliases/SingleResult.md index f0b9e74b8..44accb62b 100644 --- a/docs/reference/type-aliases/SingleResult.md +++ b/docs/reference/type-aliases/SingleResult.md @@ -9,7 +9,7 @@ title: SingleResult type SingleResult = object; ``` -Defined in: [packages/db/src/types.ts:658](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L658) +Defined in: [packages/db/src/types.ts:674](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L674) ## Properties @@ -19,4 +19,4 @@ Defined in: [packages/db/src/types.ts:658](https://github.com/TanStack/db/blob/m singleResult: true; ``` -Defined in: [packages/db/src/types.ts:659](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L659) +Defined in: [packages/db/src/types.ts:675](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L675) diff --git a/docs/reference/type-aliases/StandardSchema.md b/docs/reference/type-aliases/StandardSchema.md index d59b54f94..ef93268c0 100644 --- a/docs/reference/type-aliases/StandardSchema.md +++ b/docs/reference/type-aliases/StandardSchema.md @@ -9,7 +9,7 @@ title: StandardSchema type StandardSchema = StandardSchemaV1 & object; ``` -Defined in: [packages/db/src/types.ts:336](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L336) +Defined in: [packages/db/src/types.ts:337](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L337) The Standard Schema interface. This follows the standard-schema specification: https://github.com/standard-schema/standard-schema diff --git a/docs/reference/type-aliases/StandardSchemaAlias.md b/docs/reference/type-aliases/StandardSchemaAlias.md index f2ac532e4..cf0d42dab 100644 --- a/docs/reference/type-aliases/StandardSchemaAlias.md +++ b/docs/reference/type-aliases/StandardSchemaAlias.md @@ -9,7 +9,7 @@ title: StandardSchemaAlias type StandardSchemaAlias = StandardSchema; ``` -Defined in: [packages/db/src/types.ts:348](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L348) +Defined in: [packages/db/src/types.ts:349](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L349) Type alias for StandardSchema diff --git a/docs/reference/type-aliases/StringCollationConfig.md b/docs/reference/type-aliases/StringCollationConfig.md index 9ca2c7b15..7ac99e3ab 100644 --- a/docs/reference/type-aliases/StringCollationConfig.md +++ b/docs/reference/type-aliases/StringCollationConfig.md @@ -17,7 +17,7 @@ type StringCollationConfig = }; ``` -Defined in: [packages/db/src/types.ts:29](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L29) +Defined in: [packages/db/src/types.ts:30](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L30) StringSortOpts - Options for string sorting behavior diff --git a/docs/reference/type-aliases/SubscriptionEvents.md b/docs/reference/type-aliases/SubscriptionEvents.md index 9beb16a79..5361b9956 100644 --- a/docs/reference/type-aliases/SubscriptionEvents.md +++ b/docs/reference/type-aliases/SubscriptionEvents.md @@ -9,7 +9,7 @@ title: SubscriptionEvents type SubscriptionEvents = object; ``` -Defined in: [packages/db/src/types.ts:240](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L240) +Defined in: [packages/db/src/types.ts:241](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L241) All subscription events @@ -21,7 +21,7 @@ All subscription events status:change: SubscriptionStatusChangeEvent; ``` -Defined in: [packages/db/src/types.ts:241](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L241) +Defined in: [packages/db/src/types.ts:242](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L242) *** @@ -31,7 +31,7 @@ Defined in: [packages/db/src/types.ts:241](https://github.com/TanStack/db/blob/m status:loadingSubset: SubscriptionStatusEvent<"loadingSubset">; ``` -Defined in: [packages/db/src/types.ts:243](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L243) +Defined in: [packages/db/src/types.ts:244](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L244) *** @@ -41,7 +41,7 @@ Defined in: [packages/db/src/types.ts:243](https://github.com/TanStack/db/blob/m status:ready: SubscriptionStatusEvent<"ready">; ``` -Defined in: [packages/db/src/types.ts:242](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L242) +Defined in: [packages/db/src/types.ts:243](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L243) *** @@ -51,4 +51,4 @@ Defined in: [packages/db/src/types.ts:242](https://github.com/TanStack/db/blob/m unsubscribed: SubscriptionUnsubscribedEvent; ``` -Defined in: [packages/db/src/types.ts:244](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L244) +Defined in: [packages/db/src/types.ts:245](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L245) diff --git a/docs/reference/type-aliases/SubscriptionStatus.md b/docs/reference/type-aliases/SubscriptionStatus.md index b036e0b41..3b35a5491 100644 --- a/docs/reference/type-aliases/SubscriptionStatus.md +++ b/docs/reference/type-aliases/SubscriptionStatus.md @@ -9,6 +9,6 @@ title: SubscriptionStatus type SubscriptionStatus = "ready" | "loadingSubset"; ``` -Defined in: [packages/db/src/types.ts:207](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L207) +Defined in: [packages/db/src/types.ts:208](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L208) Subscription status values diff --git a/docs/reference/type-aliases/SyncConfigRes.md b/docs/reference/type-aliases/SyncConfigRes.md index 6e0e64aca..d87743d4b 100644 --- a/docs/reference/type-aliases/SyncConfigRes.md +++ b/docs/reference/type-aliases/SyncConfigRes.md @@ -9,7 +9,7 @@ title: SyncConfigRes type SyncConfigRes = object; ``` -Defined in: [packages/db/src/types.ts:280](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L280) +Defined in: [packages/db/src/types.ts:281](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L281) ## Properties @@ -19,7 +19,7 @@ Defined in: [packages/db/src/types.ts:280](https://github.com/TanStack/db/blob/m optional cleanup: CleanupFn; ``` -Defined in: [packages/db/src/types.ts:281](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L281) +Defined in: [packages/db/src/types.ts:282](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L282) *** @@ -29,7 +29,7 @@ Defined in: [packages/db/src/types.ts:281](https://github.com/TanStack/db/blob/m optional loadSubset: LoadSubsetFn; ``` -Defined in: [packages/db/src/types.ts:282](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L282) +Defined in: [packages/db/src/types.ts:283](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L283) *** @@ -39,4 +39,4 @@ Defined in: [packages/db/src/types.ts:282](https://github.com/TanStack/db/blob/m optional unloadSubset: UnloadSubsetFn; ``` -Defined in: [packages/db/src/types.ts:283](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L283) +Defined in: [packages/db/src/types.ts:284](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L284) diff --git a/docs/reference/type-aliases/SyncMode.md b/docs/reference/type-aliases/SyncMode.md index 6e72cfbf4..c7205a9cc 100644 --- a/docs/reference/type-aliases/SyncMode.md +++ b/docs/reference/type-aliases/SyncMode.md @@ -9,4 +9,4 @@ title: SyncMode type SyncMode = "eager" | "on-demand"; ``` -Defined in: [packages/db/src/types.ts:436](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L436) +Defined in: [packages/db/src/types.ts:437](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L437) diff --git a/docs/reference/type-aliases/TransactionState.md b/docs/reference/type-aliases/TransactionState.md index 7f3c41897..2558a48d3 100644 --- a/docs/reference/type-aliases/TransactionState.md +++ b/docs/reference/type-aliases/TransactionState.md @@ -9,4 +9,4 @@ title: TransactionState type TransactionState = "pending" | "persisting" | "completed" | "failed"; ``` -Defined in: [packages/db/src/types.ts:61](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L61) +Defined in: [packages/db/src/types.ts:62](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L62) diff --git a/docs/reference/type-aliases/TransactionWithMutations.md b/docs/reference/type-aliases/TransactionWithMutations.md index 3aca2e51f..e6e1dc979 100644 --- a/docs/reference/type-aliases/TransactionWithMutations.md +++ b/docs/reference/type-aliases/TransactionWithMutations.md @@ -9,7 +9,7 @@ title: TransactionWithMutations type TransactionWithMutations = Omit, "mutations"> & object; ``` -Defined in: [packages/db/src/types.ts:139](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L139) +Defined in: [packages/db/src/types.ts:140](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L140) Utility type for a Transaction with at least one mutation This is used internally by the Transaction.commit method diff --git a/docs/reference/type-aliases/UnloadSubsetFn.md b/docs/reference/type-aliases/UnloadSubsetFn.md index 62f96c857..4cee722b8 100644 --- a/docs/reference/type-aliases/UnloadSubsetFn.md +++ b/docs/reference/type-aliases/UnloadSubsetFn.md @@ -9,7 +9,7 @@ title: UnloadSubsetFn type UnloadSubsetFn = (options) => void; ``` -Defined in: [packages/db/src/types.ts:276](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L276) +Defined in: [packages/db/src/types.ts:277](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L277) ## Parameters diff --git a/docs/reference/type-aliases/UpdateMutationFn.md b/docs/reference/type-aliases/UpdateMutationFn.md index 64965f2a0..d6f037dd1 100644 --- a/docs/reference/type-aliases/UpdateMutationFn.md +++ b/docs/reference/type-aliases/UpdateMutationFn.md @@ -9,7 +9,7 @@ title: UpdateMutationFn type UpdateMutationFn = (params) => Promise; ``` -Defined in: [packages/db/src/types.ts:395](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L395) +Defined in: [packages/db/src/types.ts:396](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L396) ## Type Parameters diff --git a/docs/reference/type-aliases/UpdateMutationFnParams.md b/docs/reference/type-aliases/UpdateMutationFnParams.md index 8aa5a3cba..853dcc3dc 100644 --- a/docs/reference/type-aliases/UpdateMutationFnParams.md +++ b/docs/reference/type-aliases/UpdateMutationFnParams.md @@ -9,7 +9,7 @@ title: UpdateMutationFnParams type UpdateMutationFnParams = object; ``` -Defined in: [packages/db/src/types.ts:362](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L362) +Defined in: [packages/db/src/types.ts:363](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L363) ## Type Parameters @@ -33,7 +33,7 @@ Defined in: [packages/db/src/types.ts:362](https://github.com/TanStack/db/blob/m collection: Collection; ``` -Defined in: [packages/db/src/types.ts:368](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L368) +Defined in: [packages/db/src/types.ts:369](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L369) *** @@ -43,4 +43,4 @@ Defined in: [packages/db/src/types.ts:368](https://github.com/TanStack/db/blob/m transaction: TransactionWithMutations; ``` -Defined in: [packages/db/src/types.ts:367](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L367) +Defined in: [packages/db/src/types.ts:368](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L368) diff --git a/docs/reference/type-aliases/UtilsRecord.md b/docs/reference/type-aliases/UtilsRecord.md index b2835a0a8..2a0a44b13 100644 --- a/docs/reference/type-aliases/UtilsRecord.md +++ b/docs/reference/type-aliases/UtilsRecord.md @@ -9,6 +9,6 @@ title: UtilsRecord type UtilsRecord = Record; ``` -Defined in: [packages/db/src/types.ts:71](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L71) +Defined in: [packages/db/src/types.ts:72](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L72) A record of utilities (functions or getters) that can be attached to a collection diff --git a/docs/reference/type-aliases/WritableDeep.md b/docs/reference/type-aliases/WritableDeep.md index fd6c796ed..7ecd8c63f 100644 --- a/docs/reference/type-aliases/WritableDeep.md +++ b/docs/reference/type-aliases/WritableDeep.md @@ -9,7 +9,7 @@ title: WritableDeep type WritableDeep = T extends BuiltIns ? T : T extends (...arguments_) => unknown ? object extends WritableObjectDeep ? T : HasMultipleCallSignatures extends true ? T : (...arguments_) => ReturnType & WritableObjectDeep : T extends ReadonlyMap ? WritableMapDeep : T extends ReadonlySet ? WritableSetDeep : T extends ReadonlyArray ? WritableArrayDeep : T extends object ? WritableObjectDeep : unknown; ``` -Defined in: [packages/db/src/types.ts:840](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L840) +Defined in: [packages/db/src/types.ts:856](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L856) ## Type Parameters diff --git a/docs/reference/variables/IndexOperation.md b/docs/reference/variables/IndexOperation.md deleted file mode 100644 index e0ec16ffa..000000000 --- a/docs/reference/variables/IndexOperation.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -id: IndexOperation -title: IndexOperation ---- - -# Variable: IndexOperation - -```ts -const IndexOperation: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike"] = comparisonFunctions; -``` - -Defined in: [packages/db/src/indexes/base-index.ts:11](https://github.com/TanStack/db/blob/main/packages/db/src/indexes/base-index.ts#L11) - -Operations that indexes can support, imported from available comparison functions diff --git a/packages/db/package.json b/packages/db/package.json index 586412841..6112173ed 100644 --- a/packages/db/package.json +++ b/packages/db/package.json @@ -36,6 +36,16 @@ "default": "./dist/cjs/index.cjs" } }, + "./indexing": { + "import": { + "types": "./dist/esm/indexing.d.ts", + "default": "./dist/esm/indexing.js" + }, + "require": { + "types": "./dist/cjs/indexing.d.cts", + "default": "./dist/cjs/indexing.cjs" + } + }, "./package.json": "./package.json" }, "sideEffects": false, diff --git a/packages/db/src/collection/index.ts b/packages/db/src/collection/index.ts index ce112024f..896fefd03 100644 --- a/packages/db/src/collection/index.ts +++ b/packages/db/src/collection/index.ts @@ -13,7 +13,7 @@ import { CollectionMutationsManager } from './mutations' import { CollectionEventsManager } from './events.js' import type { CollectionSubscription } from './subscription' import type { AllCollectionEvents, CollectionEventHandler } from './events.js' -import type { BaseIndex, IndexResolver } from '../indexes/base-index.js' +import type { BaseIndex, IndexConstructor } from '../indexes/base-index.js' import type { IndexOptions } from '../indexes/index-options.js' import type { ChangeMessage, @@ -35,8 +35,6 @@ import type { } from '../types' import type { SingleRowRefProxy } from '../query/builder/ref-proxy' import type { StandardSchemaV1 } from '@standard-schema/spec' -import type { BTreeIndex } from '../indexes/btree-index.js' -import type { IndexProxy } from '../indexes/lazy-index.js' /** * Enhanced Collection interface that includes both data type T and utilities TUtils @@ -322,7 +320,7 @@ export class CollectionImpl< // Set default values for optional config properties this.config = { ...config, - autoIndex: config.autoIndex ?? `eager`, + autoIndex: config.autoIndex ?? `off`, } this._changes = new CollectionChangesManager() @@ -347,6 +345,7 @@ export class CollectionImpl< this._indexes.setDeps({ state: this._state, lifecycle: this._lifecycle, + defaultIndexType: config.defaultIndexType, }) this._lifecycle.setDeps({ changes: this._changes, @@ -523,38 +522,27 @@ export class CollectionImpl< * Indexes significantly improve query performance by allowing constant time lookups * and logarithmic time range queries instead of full scans. * - * @template TResolver - The type of the index resolver (constructor or async loader) * @param indexCallback - Function that extracts the indexed value from each item * @param config - Configuration including index type and type-specific options - * @returns An index proxy that provides access to the index when ready + * @returns The created index * * @example - * // Create a default B+ tree index - * const ageIndex = collection.createIndex((row) => row.age) + * ```ts + * import { BasicIndex } from '@tanstack/db/indexing' * - * // Create a ordered index with custom options + * // Create an index with explicit type * const ageIndex = collection.createIndex((row) => row.age, { - * indexType: BTreeIndex, - * options: { - * compareFn: customComparator, - * compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' } - * }, - * name: 'age_btree' + * indexType: BasicIndex * }) * - * // Create an async-loaded index - * const textIndex = collection.createIndex((row) => row.content, { - * indexType: async () => { - * const { FullTextIndex } = await import('./indexes/fulltext.js') - * return FullTextIndex - * }, - * options: { language: 'en' } - * }) + * // Create an index with collection's default type + * const nameIndex = collection.createIndex((row) => row.name) + * ``` */ - public createIndex = typeof BTreeIndex>( + public createIndex>( indexCallback: (row: SingleRowRefProxy) => any, - config: IndexOptions = {}, - ): IndexProxy { + config: IndexOptions = {}, + ): BaseIndex { return this._indexes.createIndex(indexCallback, config) } diff --git a/packages/db/src/collection/indexes.ts b/packages/db/src/collection/indexes.ts index 037bd126c..3bfd508e1 100644 --- a/packages/db/src/collection/indexes.ts +++ b/packages/db/src/collection/indexes.ts @@ -1,11 +1,9 @@ -import { IndexProxy, LazyIndexWrapper } from '../indexes/lazy-index' import { createSingleRowRefProxy, toExpression, } from '../query/builder/ref-proxy' -import { BTreeIndex } from '../indexes/btree-index' import type { StandardSchemaV1 } from '@standard-schema/spec' -import type { BaseIndex, IndexResolver } from '../indexes/base-index' +import type { BaseIndex, IndexConstructor } from '../indexes/base-index' import type { ChangeMessage } from '../types' import type { IndexOptions } from '../indexes/index-options' import type { SingleRowRefProxy } from '../query/builder/ref-proxy' @@ -20,10 +18,9 @@ export class CollectionIndexesManager< > { private lifecycle!: CollectionLifecycleManager private state!: CollectionStateManager + private defaultIndexType: IndexConstructor | undefined - public lazyIndexes = new Map>() - public resolvedIndexes = new Map>() - public isIndexesResolved = false + public indexes = new Map>() public indexCounter = 0 constructor() {} @@ -31,18 +28,30 @@ export class CollectionIndexesManager< setDeps(deps: { state: CollectionStateManager lifecycle: CollectionLifecycleManager + defaultIndexType?: IndexConstructor }) { this.state = deps.state this.lifecycle = deps.lifecycle + this.defaultIndexType = deps.defaultIndexType } /** * Creates an index on a collection for faster queries. + * + * @example + * ```ts + * // With explicit index type (recommended for tree-shaking) + * import { BasicIndex } from '@tanstack/db/indexing' + * collection.createIndex((row) => row.userId, { indexType: BasicIndex }) + * + * // With collection's default index type + * collection.createIndex((row) => row.userId) + * ``` */ - public createIndex = typeof BTreeIndex>( + public createIndex>( indexCallback: (row: SingleRowRefProxy) => any, - config: IndexOptions = {}, - ): IndexProxy { + config: IndexOptions = {}, + ): BaseIndex { this.lifecycle.validateCollectionUsable(`createIndex`) const indexId = ++this.indexCounter @@ -50,97 +59,38 @@ export class CollectionIndexesManager< const indexExpression = indexCallback(singleRowRefProxy) const expression = toExpression(indexExpression) - // Default to BTreeIndex if no type specified - const resolver = config.indexType ?? (BTreeIndex as unknown as TResolver) + // Use provided index type, or fall back to collection's default + const IndexType = config.indexType ?? this.defaultIndexType + if (!IndexType) { + throw new Error( + `No index type specified and no defaultIndexType set on collection. ` + + `Either pass indexType in config, or set defaultIndexType on the collection:\n` + + ` import { BasicIndex } from '@tanstack/db/indexing'\n` + + ` createCollection({ defaultIndexType: BasicIndex, ... })`, + ) + } - // Create lazy wrapper - const lazyIndex = new LazyIndexWrapper( + // Create index synchronously + const index = new IndexType( indexId, expression, config.name, - resolver, config.options, - this.state.entries(), ) - this.lazyIndexes.set(indexId, lazyIndex) - - // For BTreeIndex, resolve immediately and synchronously - if ((resolver as unknown) === BTreeIndex) { - try { - const resolvedIndex = lazyIndex.getResolved() - this.resolvedIndexes.set(indexId, resolvedIndex) - } catch (error) { - console.warn(`Failed to resolve BTreeIndex:`, error) - } - } else if (typeof resolver === `function` && resolver.prototype) { - // Other synchronous constructors - resolve immediately - try { - const resolvedIndex = lazyIndex.getResolved() - this.resolvedIndexes.set(indexId, resolvedIndex) - } catch { - // Fallback to async resolution - this.resolveSingleIndex(indexId, lazyIndex).catch((error) => { - console.warn(`Failed to resolve single index:`, error) - }) - } - } else if (this.isIndexesResolved) { - // Async loader but indexes are already resolved - resolve this one - this.resolveSingleIndex(indexId, lazyIndex).catch((error) => { - console.warn(`Failed to resolve single index:`, error) - }) - } - - return new IndexProxy(indexId, lazyIndex) - } - - /** - * Resolve all lazy indexes (called when collection first syncs) - */ - public async resolveAllIndexes(): Promise { - if (this.isIndexesResolved) return - - const resolutionPromises = Array.from(this.lazyIndexes.entries()).map( - async ([indexId, lazyIndex]) => { - const resolvedIndex = await lazyIndex.resolve() + // Build with current data + index.build(this.state.entries()) - // Build index with current data - resolvedIndex.build(this.state.entries()) + this.indexes.set(indexId, index) - this.resolvedIndexes.set(indexId, resolvedIndex) - return { indexId, resolvedIndex } - }, - ) - - await Promise.all(resolutionPromises) - this.isIndexesResolved = true - } - - /** - * Resolve a single index immediately - */ - private async resolveSingleIndex( - indexId: number, - lazyIndex: LazyIndexWrapper, - ): Promise> { - const resolvedIndex = await lazyIndex.resolve() - resolvedIndex.build(this.state.entries()) - this.resolvedIndexes.set(indexId, resolvedIndex) - return resolvedIndex - } - - /** - * Get resolved indexes for query optimization - */ - get indexes(): Map> { - return this.resolvedIndexes + return index } /** * Updates all indexes when the collection changes */ public updateIndexes(changes: Array>): void { - for (const index of this.resolvedIndexes.values()) { + for (const index of this.indexes.values()) { for (const change of changes) { switch (change.type) { case `insert`: @@ -162,11 +112,9 @@ export class CollectionIndexesManager< } /** - * Clean up the collection by stopping sync and clearing data - * This can be called manually or automatically by garbage collection + * Clean up indexes */ public cleanup(): void { - this.lazyIndexes.clear() - this.resolvedIndexes.clear() + this.indexes.clear() } } diff --git a/packages/db/src/collection/lifecycle.ts b/packages/db/src/collection/lifecycle.ts index ee5fed5e7..2d8fb8bf7 100644 --- a/packages/db/src/collection/lifecycle.ts +++ b/packages/db/src/collection/lifecycle.ts @@ -106,17 +106,6 @@ export class CollectionLifecycleManager< const previousStatus = this.status this.status = newStatus - // Resolve indexes when collection becomes ready - if (newStatus === `ready` && !this.indexes.isIndexesResolved) { - // Resolve indexes asynchronously without blocking - this.indexes.resolveAllIndexes().catch((error) => { - console.warn( - `${this.config.id ? `[${this.config.id}] ` : ``}Failed to resolve indexes:`, - error, - ) - }) - } - // Emit event this.events.emitStatusChange(newStatus, previousStatus) } diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts index ccf7cbb6e..98c1b686e 100644 --- a/packages/db/src/index.ts +++ b/packages/db/src/index.ts @@ -17,12 +17,27 @@ export { deepEquals } from './utils' export * from './paced-mutations' export * from './strategies/index.js' -// Index system exports -export * from './indexes/base-index.js' -export * from './indexes/btree-index.js' -export * from './indexes/lazy-index.js' +// Index system exports - types only from main entry +// For BasicIndex, BTreeIndex and other index implementations, import from '@tanstack/db/indexing' +export type { + IndexInterface, + IndexConstructor, + IndexStats, + IndexOperation, +} from './indexes/base-index.js' +export { BaseIndex } from './indexes/base-index.js' export { type IndexOptions } from './indexes/index-options.js' +// Dev mode utilities +export { + configureIndexDevMode, + isDevModeEnabled, +} from './indexes/index-registry.js' +export type { + IndexDevModeConfig, + IndexSuggestion, +} from './indexes/index-registry.js' + // Expression helpers export * from './query/expression-helpers.js' diff --git a/packages/db/src/indexes/auto-index.ts b/packages/db/src/indexes/auto-index.ts index 098c92b50..1cfb985a9 100644 --- a/packages/db/src/indexes/auto-index.ts +++ b/packages/db/src/indexes/auto-index.ts @@ -1,5 +1,5 @@ import { DEFAULT_COMPARE_OPTIONS } from '../utils' -import { BTreeIndex } from './btree-index' +import { checkCollectionSizeForIndex, isDevModeEnabled } from './index-registry' import type { CompareOptions } from '../query/builder/types' import type { BasicExpression } from '../query/ir' import type { CollectionImpl } from '../collection/index.js' @@ -14,6 +14,19 @@ function shouldAutoIndex(collection: CollectionImpl) { return false } + // Check if defaultIndexType is set on the collection + if (!collection.config.defaultIndexType) { + if (isDevModeEnabled()) { + console.warn( + `[TanStack DB] Auto-indexing is enabled but no defaultIndexType is set. ` + + `Set defaultIndexType on the collection:\n` + + ` import { BasicIndex } from '@tanstack/db/indexing'\n` + + ` createCollection({ defaultIndexType: BasicIndex, autoIndex: 'eager', ... })`, + ) + } + return false + } + return true } @@ -46,9 +59,18 @@ export function ensureIndexForField< return // Index already exists } + // Dev mode: check if collection size warrants an index suggestion + if (isDevModeEnabled()) { + checkCollectionSizeForIndex( + collection.id || `unknown`, + collection.size, + fieldPath, + ) + } + // Create a new index for this field using the collection's createIndex method + // The collection will use its defaultIndexType try { - // Use the proxy-based approach to create the proper accessor for nested paths collection.createIndex( (row) => { // Navigate through the field path @@ -60,7 +82,6 @@ export function ensureIndexForField< }, { name: `auto:${fieldPath.join(`.`)}`, - indexType: BTreeIndex, options: compareFn ? { compareFn, compareOptions: compareOpts } : {}, }, ) diff --git a/packages/db/src/indexes/base-index.ts b/packages/db/src/indexes/base-index.ts index 18e58b7eb..2b2d5be2e 100644 --- a/packages/db/src/indexes/base-index.ts +++ b/packages/db/src/indexes/base-index.ts @@ -205,10 +205,3 @@ export type IndexConstructor = name?: string, options?: any, ) => BaseIndex - -/** - * Index resolver can be either a class constructor or async loader - */ -export type IndexResolver = - | IndexConstructor - | (() => Promise>) diff --git a/packages/db/src/indexes/basic-index.ts b/packages/db/src/indexes/basic-index.ts new file mode 100644 index 000000000..b8b1e37b3 --- /dev/null +++ b/packages/db/src/indexes/basic-index.ts @@ -0,0 +1,439 @@ +import { defaultComparator, normalizeValue } from '../utils/comparison.js' +import { BaseIndex } from './base-index.js' +import type { CompareOptions } from '../query/builder/types.js' +import type { BasicExpression } from '../query/ir.js' +import type { IndexOperation } from './base-index.js' + +/** + * Options for range queries + */ +export interface RangeQueryOptions { + from?: any + to?: any + fromInclusive?: boolean + toInclusive?: boolean +} + +/** + * Options for Basic index + */ +export interface BasicIndexOptions { + compareFn?: (a: any, b: any) => number + compareOptions?: CompareOptions +} + +/** + * Basic index using Map + sorted Array. + * + * - Map for O(1) equality lookups + * - Sorted Array for O(log n) range queries via binary search + * - O(n) updates to maintain sort order + * + * Simpler and smaller than BTreeIndex, good for read-heavy workloads. + * Use BTreeIndex for write-heavy workloads with large collections. + */ +export class BasicIndex< + TKey extends string | number = string | number, +> extends BaseIndex { + public readonly supportedOperations = new Set([ + `eq`, + `gt`, + `gte`, + `lt`, + `lte`, + `in`, + ]) + + // Map for O(1) equality lookups: indexedValue -> Set of PKs + private valueMap = new Map>() + // Sorted array of unique indexed values for range queries + private sortedValues: Array = [] + // Set of all indexed PKs + private indexedKeys = new Set() + // Comparator function + private compareFn: (a: any, b: any) => number = defaultComparator + + constructor( + id: number, + expression: BasicExpression, + name?: string, + options?: any, + ) { + super(id, expression, name, options) + this.compareFn = options?.compareFn ?? defaultComparator + if (options?.compareOptions) { + this.compareOptions = options!.compareOptions + } + } + + protected initialize(_options?: BasicIndexOptions): void {} + + /** + * Binary search to find insertion point in sorted array + */ + private findInsertionIndex(value: any): number { + let low = 0 + let high = this.sortedValues.length + + while (low < high) { + const mid = (low + high) >>> 1 + if (this.compareFn(this.sortedValues[mid], value) < 0) { + low = mid + 1 + } else { + high = mid + } + } + return low + } + + /** + * Adds a value to the index + */ + add(key: TKey, item: any): void { + let indexedValue: any + try { + indexedValue = this.evaluateIndexExpression(item) + } catch (error) { + throw new Error( + `Failed to evaluate index expression for key ${key}: ${error}`, + ) + } + + const normalizedValue = normalizeValue(indexedValue) + + if (this.valueMap.has(normalizedValue)) { + // Value already exists, just add the key to the set + this.valueMap.get(normalizedValue)!.add(key) + } else { + // New value - add to map and insert into sorted array + this.valueMap.set(normalizedValue, new Set([key])) + + // Insert into sorted position + const insertIdx = this.findInsertionIndex(normalizedValue) + this.sortedValues.splice(insertIdx, 0, normalizedValue) + } + + this.indexedKeys.add(key) + this.updateTimestamp() + } + + /** + * Removes a value from the index + */ + remove(key: TKey, item: any): void { + let indexedValue: any + try { + indexedValue = this.evaluateIndexExpression(item) + } catch (error) { + console.warn( + `Failed to evaluate index expression for key ${key} during removal:`, + error, + ) + return + } + + const normalizedValue = normalizeValue(indexedValue) + + if (this.valueMap.has(normalizedValue)) { + const keySet = this.valueMap.get(normalizedValue)! + keySet.delete(key) + + if (keySet.size === 0) { + // No more keys for this value, remove from map and sorted array + this.valueMap.delete(normalizedValue) + + const idx = this.findInsertionIndex(normalizedValue) + if ( + idx < this.sortedValues.length && + this.compareFn(this.sortedValues[idx], normalizedValue) === 0 + ) { + this.sortedValues.splice(idx, 1) + } + } + } + + this.indexedKeys.delete(key) + this.updateTimestamp() + } + + /** + * Updates a value in the index + */ + update(key: TKey, oldItem: any, newItem: any): void { + this.remove(key, oldItem) + this.add(key, newItem) + } + + /** + * Builds the index from a collection of entries + */ + build(entries: Iterable<[TKey, any]>): void { + this.clear() + + // Collect all entries first + const entriesArray: Array<{ key: TKey; value: any }> = [] + for (const [key, item] of entries) { + let indexedValue: any + try { + indexedValue = this.evaluateIndexExpression(item) + } catch (error) { + throw new Error( + `Failed to evaluate index expression for key ${key}: ${error}`, + ) + } + entriesArray.push({ key, value: normalizeValue(indexedValue) }) + this.indexedKeys.add(key) + } + + // Group by value + for (const { key, value } of entriesArray) { + if (this.valueMap.has(value)) { + this.valueMap.get(value)!.add(key) + } else { + this.valueMap.set(value, new Set([key])) + } + } + + // Build sorted array from unique values + this.sortedValues = Array.from(this.valueMap.keys()).sort(this.compareFn) + + this.updateTimestamp() + } + + /** + * Clears all data from the index + */ + clear(): void { + this.valueMap.clear() + this.sortedValues = [] + this.indexedKeys.clear() + this.updateTimestamp() + } + + /** + * Performs a lookup operation + */ + lookup(operation: IndexOperation, value: any): Set { + const startTime = performance.now() + + let result: Set + + switch (operation) { + case `eq`: + result = this.equalityLookup(value) + break + case `gt`: + result = this.rangeQuery({ from: value, fromInclusive: false }) + break + case `gte`: + result = this.rangeQuery({ from: value, fromInclusive: true }) + break + case `lt`: + result = this.rangeQuery({ to: value, toInclusive: false }) + break + case `lte`: + result = this.rangeQuery({ to: value, toInclusive: true }) + break + case `in`: + result = this.inArrayLookup(value) + break + default: + throw new Error(`Operation ${operation} not supported by BasicIndex`) + } + + this.trackLookup(startTime) + return result + } + + /** + * Gets the number of indexed keys + */ + get keyCount(): number { + return this.indexedKeys.size + } + + /** + * Performs an equality lookup - O(1) + */ + equalityLookup(value: any): Set { + const normalizedValue = normalizeValue(value) + return new Set(this.valueMap.get(normalizedValue) ?? []) + } + + /** + * Performs a range query using binary search - O(log n + m) + */ + rangeQuery(options: RangeQueryOptions = {}): Set { + const { from, to, fromInclusive = true, toInclusive = true } = options + const result = new Set() + + if (this.sortedValues.length === 0) { + return result + } + + const normalizedFrom = normalizeValue(from) + const normalizedTo = normalizeValue(to) + + // Find start index + let startIdx = 0 + if (normalizedFrom !== undefined) { + startIdx = this.findInsertionIndex(normalizedFrom) + // If not inclusive and we found exact match, skip it + if ( + !fromInclusive && + startIdx < this.sortedValues.length && + this.compareFn(this.sortedValues[startIdx], normalizedFrom) === 0 + ) { + startIdx++ + } + } + + // Find end index + let endIdx = this.sortedValues.length + if (normalizedTo !== undefined) { + endIdx = this.findInsertionIndex(normalizedTo) + // If inclusive and we found the value, include it + if ( + toInclusive && + endIdx < this.sortedValues.length && + this.compareFn(this.sortedValues[endIdx], normalizedTo) === 0 + ) { + endIdx++ + } + } + + // Collect all keys in range + for (let i = startIdx; i < endIdx; i++) { + const keys = this.valueMap.get(this.sortedValues[i]) + if (keys) { + keys.forEach((key) => result.add(key)) + } + } + + return result + } + + /** + * Performs a reversed range query + */ + rangeQueryReversed(options: RangeQueryOptions = {}): Set { + // For BasicIndex, reversed is the same result set, just different iteration order + // which doesn't matter for Set + return this.rangeQuery(options) + } + + /** + * Returns the next n items in sorted order + */ + take(n: number, from?: any, filterFn?: (key: TKey) => boolean): Array { + const result: Array = [] + + let startIdx = 0 + if (from !== undefined) { + const normalizedFrom = normalizeValue(from) + startIdx = this.findInsertionIndex(normalizedFrom) + // Skip past the 'from' value (exclusive) + while ( + startIdx < this.sortedValues.length && + this.compareFn(this.sortedValues[startIdx], normalizedFrom) <= 0 + ) { + startIdx++ + } + } + + for ( + let i = startIdx; + i < this.sortedValues.length && result.length < n; + i++ + ) { + const keys = this.valueMap.get(this.sortedValues[i]) + if (keys) { + for (const key of keys) { + if (result.length >= n) break + if (!filterFn || filterFn(key)) { + result.push(key) + } + } + } + } + + return result + } + + /** + * Returns the next n items in reverse sorted order + */ + takeReversed( + n: number, + from?: any, + filterFn?: (key: TKey) => boolean, + ): Array { + const result: Array = [] + + let startIdx = this.sortedValues.length - 1 + if (from !== undefined) { + const normalizedFrom = normalizeValue(from) + startIdx = this.findInsertionIndex(normalizedFrom) - 1 + // Skip past the 'from' value (exclusive) + while ( + startIdx >= 0 && + this.compareFn(this.sortedValues[startIdx], normalizedFrom) >= 0 + ) { + startIdx-- + } + } + + for (let i = startIdx; i >= 0 && result.length < n; i--) { + const keys = this.valueMap.get(this.sortedValues[i]) + if (keys) { + for (const key of keys) { + if (result.length >= n) break + if (!filterFn || filterFn(key)) { + result.push(key) + } + } + } + } + + return result + } + + /** + * Performs an IN array lookup - O(k) where k is values.length + */ + inArrayLookup(values: Array): Set { + const result = new Set() + + for (const value of values) { + const normalizedValue = normalizeValue(value) + const keys = this.valueMap.get(normalizedValue) + if (keys) { + keys.forEach((key) => result.add(key)) + } + } + + return result + } + + // Getter methods for testing/compatibility + get indexedKeysSet(): Set { + return this.indexedKeys + } + + get orderedEntriesArray(): Array<[any, Set]> { + return this.sortedValues.map((value) => [ + value, + this.valueMap.get(value) ?? new Set(), + ]) + } + + get orderedEntriesArrayReversed(): Array<[any, Set]> { + return [...this.sortedValues] + .reverse() + .map((value) => [value, this.valueMap.get(value) ?? new Set()]) + } + + get valueMapData(): Map> { + return this.valueMap + } +} diff --git a/packages/db/src/indexes/index-options.ts b/packages/db/src/indexes/index-options.ts index 6dfbc137b..7ea980fb0 100644 --- a/packages/db/src/indexes/index-options.ts +++ b/packages/db/src/indexes/index-options.ts @@ -1,42 +1,22 @@ -import type { IndexConstructor, IndexResolver } from './base-index.js' +import type { IndexConstructor } from './base-index.js' /** - * Enhanced index options that support both sync and async resolvers + * Options for creating an index */ -export interface IndexOptions { +export interface IndexOptions< + TIndexType extends IndexConstructor = IndexConstructor, +> { + /** Optional name for the index */ name?: string - indexType?: TResolver - options?: TResolver extends IndexConstructor - ? TResolver extends new ( - id: number, - expr: any, - name?: string, - options?: infer O, - ) => any - ? O - : never - : TResolver extends () => Promise - ? TCtor extends new ( - id: number, - expr: any, - name?: string, - options?: infer O, - ) => any - ? O - : never - : never + /** Index type to use (e.g., BasicIndex, BTreeIndex) */ + indexType?: TIndexType + /** Options passed to the index constructor */ + options?: TIndexType extends new ( + id: number, + expr: any, + name?: string, + options?: infer O, + ) => any + ? O + : never } - -/** - * Utility type to extract the constructed index type from a resolver - */ -export type ResolvedIndexType = - TResolver extends IndexConstructor - ? InstanceType - : TResolver extends () => Promise> - ? TResolver extends () => Promise - ? TCtor extends IndexConstructor - ? InstanceType - : never - : never - : never diff --git a/packages/db/src/indexes/index-registry.ts b/packages/db/src/indexes/index-registry.ts new file mode 100644 index 000000000..399d59be9 --- /dev/null +++ b/packages/db/src/indexes/index-registry.ts @@ -0,0 +1,170 @@ +/** + * Index Dev Mode - Helps developers identify when indexes would improve performance + * + * Dev mode suggestions are ON by default in non-production builds. + */ + +// Dev mode detection settings - ON by default in non-production +let devModeConfig: IndexDevModeConfig = { + enabled: true, + collectionSizeThreshold: 1000, + slowQueryThresholdMs: 10, + onSuggestion: null, +} + +export interface IndexDevModeConfig { + /** Enable dev mode index suggestions */ + enabled: boolean + /** Suggest indexes when collection has more than this many items */ + collectionSizeThreshold: number + /** Suggest indexes when queries take longer than this (ms) */ + slowQueryThresholdMs: number + /** Custom handler for index suggestions */ + onSuggestion: ((suggestion: IndexSuggestion) => void) | null +} + +export interface IndexSuggestion { + type: `collection-size` | `slow-query` | `frequent-field` + collectionId: string + fieldPath: Array + message: string + collectionSize?: number + queryTimeMs?: number + queryCount?: number +} + +// Track query patterns for dev mode +const queryPatterns = new Map< + string, + { + fieldPath: Array + queryCount: number + totalTimeMs: number + avgTimeMs: number + } +>() + +/** + * Configure dev mode for index suggestions + */ +export function configureIndexDevMode( + config: Partial, +): void { + devModeConfig = { ...devModeConfig, ...config } +} + +/** + * Get current dev mode configuration + */ +export function getIndexDevModeConfig(): IndexDevModeConfig { + return devModeConfig +} + +/** + * Check if dev mode is enabled + */ +export function isDevModeEnabled(): boolean { + return devModeConfig.enabled && process.env.NODE_ENV !== `production` +} + +/** + * Emit an index suggestion (dev mode only) + */ +export function emitIndexSuggestion(suggestion: IndexSuggestion): void { + if (!isDevModeEnabled()) return + + if (devModeConfig.onSuggestion) { + devModeConfig.onSuggestion(suggestion) + } else { + // Default: log to console with helpful formatting + console.warn( + `[TanStack DB] Index suggestion for "${suggestion.collectionId}":\n` + + ` ${suggestion.message}\n` + + ` Field: ${suggestion.fieldPath.join(`.`)}\n` + + ` Add index: collection.createIndex((row) => row.${suggestion.fieldPath.join(`.`)})`, + ) + } +} + +/** + * Track a query for dev mode analysis + */ +export function trackQuery( + collectionId: string, + fieldPath: Array, + executionTimeMs: number, +): void { + if (!isDevModeEnabled()) return + + const key = `${collectionId}:${fieldPath.join(`.`)}` + const existing = queryPatterns.get(key) + + if (existing) { + existing.queryCount++ + existing.totalTimeMs += executionTimeMs + existing.avgTimeMs = existing.totalTimeMs / existing.queryCount + } else { + queryPatterns.set(key, { + fieldPath, + queryCount: 1, + totalTimeMs: executionTimeMs, + avgTimeMs: executionTimeMs, + }) + } + + // Check if we should suggest an index + const pattern = queryPatterns.get(key)! + if (pattern.avgTimeMs > devModeConfig.slowQueryThresholdMs) { + emitIndexSuggestion({ + type: `slow-query`, + collectionId, + fieldPath, + message: `Queries on "${fieldPath.join(`.`)}" are slow (avg ${pattern.avgTimeMs.toFixed(1)}ms). Consider adding an index.`, + queryTimeMs: pattern.avgTimeMs, + queryCount: pattern.queryCount, + }) + } +} + +/** + * Check collection size and suggest index if needed (dev mode) + */ +export function checkCollectionSizeForIndex( + collectionId: string, + collectionSize: number, + fieldPath: Array, +): void { + if (!isDevModeEnabled()) return + + if (collectionSize > devModeConfig.collectionSizeThreshold) { + emitIndexSuggestion({ + type: `collection-size`, + collectionId, + fieldPath, + message: `Collection has ${collectionSize} items. Queries on "${fieldPath.join(`.`)}" may benefit from an index.`, + collectionSize, + }) + } +} + +/** + * Clear query pattern tracking (useful for tests) + */ +export function clearQueryPatterns(): void { + queryPatterns.clear() +} + +/** + * Get query patterns (useful for debugging/testing) + */ +export function getQueryPatterns(): Map< + string, + { + fieldPath: Array + queryCount: number + totalTimeMs: number + avgTimeMs: number + } +> { + return new Map(queryPatterns) +} diff --git a/packages/db/src/indexes/lazy-index.ts b/packages/db/src/indexes/lazy-index.ts deleted file mode 100644 index ca1dc6b02..000000000 --- a/packages/db/src/indexes/lazy-index.ts +++ /dev/null @@ -1,251 +0,0 @@ -import type { - BaseIndex, - IndexConstructor, - IndexResolver, -} from './base-index.js' -import type { BasicExpression } from '../query/ir.js' - -/** - * Utility to determine if a resolver is a constructor or async loader - */ -function isConstructor( - resolver: IndexResolver, -): resolver is IndexConstructor { - // Check if it's a function with a prototype (constructor) - return ( - typeof resolver === `function` && - resolver.prototype !== undefined && - resolver.prototype.constructor === resolver - ) -} - -/** - * Resolve index constructor from resolver - */ -async function resolveIndexConstructor( - resolver: IndexResolver, -): Promise> { - if (isConstructor(resolver)) { - return resolver - } else { - // It's an async loader function - return await resolver() - } -} - -/** - * Wrapper that defers index creation until first sync - */ -export class LazyIndexWrapper { - private indexPromise: Promise> | null = null - private resolvedIndex: BaseIndex | null = null - - constructor( - private id: number, - private expression: BasicExpression, - private name: string | undefined, - private resolver: IndexResolver, - private options: any, - private collectionEntries?: Iterable<[TKey, any]>, - ) { - // For synchronous constructors, resolve immediately - if (isConstructor(this.resolver)) { - this.resolvedIndex = new this.resolver( - this.id, - this.expression, - this.name, - this.options, - ) - // Build with initial data if provided - if (this.collectionEntries) { - this.resolvedIndex.build(this.collectionEntries) - } - } - } - - /** - * Resolve the actual index - */ - async resolve(): Promise> { - if (this.resolvedIndex) { - return this.resolvedIndex - } - - if (!this.indexPromise) { - this.indexPromise = this.createIndex() - } - - this.resolvedIndex = await this.indexPromise - return this.resolvedIndex - } - - /** - * Check if already resolved - */ - isResolved(): boolean { - return this.resolvedIndex !== null - } - - /** - * Get resolved index (throws if not ready) - */ - getResolved(): BaseIndex { - if (!this.resolvedIndex) { - throw new Error( - `Index ${this.id} has not been resolved yet. Ensure collection is synced.`, - ) - } - return this.resolvedIndex - } - - /** - * Get the index ID - */ - getId(): number { - return this.id - } - - /** - * Get the index name - */ - getName(): string | undefined { - return this.name - } - - /** - * Get the index expression - */ - getExpression(): BasicExpression { - return this.expression - } - - private async createIndex(): Promise> { - const IndexClass = await resolveIndexConstructor(this.resolver) - return new IndexClass(this.id, this.expression, this.name, this.options) - } -} - -/** - * Proxy that provides synchronous interface while index loads asynchronously - */ -export class IndexProxy { - constructor( - private indexId: number, - private lazyIndex: LazyIndexWrapper, - ) {} - - /** - * Get the resolved index (throws if not ready) - */ - get index(): BaseIndex { - return this.lazyIndex.getResolved() - } - - /** - * Check if index is ready - */ - get isReady(): boolean { - return this.lazyIndex.isResolved() - } - - /** - * Wait for index to be ready - */ - async whenReady(): Promise> { - return await this.lazyIndex.resolve() - } - - /** - * Get the index ID - */ - get id(): number { - return this.indexId - } - - /** - * Get the index name (throws if not ready) - */ - get name(): string | undefined { - if (this.isReady) { - return this.index.name - } - return this.lazyIndex.getName() - } - - /** - * Get the index expression (available immediately) - */ - get expression(): BasicExpression { - return this.lazyIndex.getExpression() - } - - /** - * Check if index supports an operation (throws if not ready) - */ - supports(operation: any): boolean { - return this.index.supports(operation) - } - - /** - * Get index statistics (throws if not ready) - */ - getStats() { - return this.index.getStats() - } - - /** - * Check if index matches a field path (available immediately) - */ - matchesField(fieldPath: Array): boolean { - const expr = this.expression - return ( - expr.type === `ref` && - expr.path.length === fieldPath.length && - expr.path.every((part, i) => part === fieldPath[i]) - ) - } - - /** - * Get the key count (throws if not ready) - */ - get keyCount(): number { - return this.index.keyCount - } - - // Test compatibility properties - delegate to resolved index - get indexedKeysSet(): Set { - const resolved = this.index as any - return resolved.indexedKeysSet - } - - get orderedEntriesArray(): Array<[any, Set]> { - const resolved = this.index as any - return resolved.orderedEntriesArray - } - - get valueMapData(): Map> { - const resolved = this.index as any - return resolved.valueMapData - } - - // BTreeIndex compatibility methods - equalityLookup(value: any): Set { - const resolved = this.index as any - return resolved.equalityLookup?.(value) ?? new Set() - } - - rangeQuery(options: any): Set { - const resolved = this.index as any - return resolved.rangeQuery?.(options) ?? new Set() - } - - inArrayLookup(values: Array): Set { - const resolved = this.index as any - return resolved.inArrayLookup?.(values) ?? new Set() - } - - // Internal method for the collection to get the lazy wrapper - _getLazyWrapper(): LazyIndexWrapper { - return this.lazyIndex - } -} diff --git a/packages/db/src/indexing.ts b/packages/db/src/indexing.ts new file mode 100644 index 000000000..a6f2ad0ce --- /dev/null +++ b/packages/db/src/indexing.ts @@ -0,0 +1,71 @@ +/** + * @tanstack/db/indexing - Optional indexing module + * + * This module provides indexing capabilities for TanStack DB. + * Import from this module to enable indexing features. + * + * @example + * ```ts + * import { BasicIndex } from '@tanstack/db/indexing' + * + * // Option 1: Set default index type on collection (for auto-indexing) + * const collection = createCollection({ + * defaultIndexType: BasicIndex, + * autoIndex: 'eager', + * // ... + * }) + * + * // Option 2: Create explicit indexes (best for tree-shaking) + * collection.createIndex((row) => row.userId, { indexType: BasicIndex }) + * + * // Option 3: Use BTreeIndex for ORDER BY optimization on large collections (10k+) + * import { BTreeIndex } from '@tanstack/db/indexing' + * collection.createIndex((row) => row.createdAt, { indexType: BTreeIndex }) + * ``` + */ + +// BasicIndex - Map + sorted Array, good balance of features and size +export { BasicIndex } from './indexes/basic-index.js' +export type { + BasicIndexOptions, + RangeQueryOptions, +} from './indexes/basic-index.js' + +// BTreeIndex - full-featured with efficient sorted iteration (for ORDER BY optimization) +export { BTreeIndex } from './indexes/btree-index.js' +export type { RangeQueryOptions as BTreeRangeQueryOptions } from './indexes/btree-index.js' + +// Re-export base index types +export { BaseIndex } from './indexes/base-index.js' +export type { + IndexInterface, + IndexConstructor, + IndexStats, + IndexOperation, +} from './indexes/base-index.js' + +// Re-export reverse index +export { ReverseIndex } from './indexes/reverse-index.js' + +// Re-export index options +export type { IndexOptions } from './indexes/index-options.js' + +// Re-export dev mode utilities +export { + configureIndexDevMode, + getIndexDevModeConfig, + isDevModeEnabled, + trackQuery, + clearQueryPatterns, + getQueryPatterns, +} from './indexes/index-registry.js' +export type { + IndexDevModeConfig, + IndexSuggestion, +} from './indexes/index-registry.js' + +// Re-export index optimization utilities +export { + optimizeExpressionWithIndexes, + findIndexForField, +} from './utils/index-optimization.js' diff --git a/packages/db/src/types.ts b/packages/db/src/types.ts index b6380e7e7..0eb107a6e 100644 --- a/packages/db/src/types.ts +++ b/packages/db/src/types.ts @@ -4,6 +4,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec' import type { Transaction } from './transactions' import type { BasicExpression, OrderBy } from './query/ir.js' import type { EventEmitter } from './event-emitter.js' +import type { IndexConstructor } from './indexes/base-index.js' /** * Interface for a collection-like object that provides the necessary methods @@ -479,12 +480,27 @@ export interface BaseCollectionConfig< /** * Auto-indexing mode for the collection. * When enabled, indexes will be automatically created for simple where expressions. - * @default "eager" + * @default "off" * @description - * - "off": No automatic indexing - * - "eager": Automatically create indexes for simple where expressions in subscribeChanges (default) + * - "off": No automatic indexing (default). Use explicit indexes for better bundle size. + * - "eager": Automatically create indexes for simple where expressions in subscribeChanges. + * Requires setting defaultIndexType. */ autoIndex?: `off` | `eager` + /** + * Default index type to use when creating indexes without an explicit type. + * Required for auto-indexing. Import from '@tanstack/db/indexing'. + * @example + * ```ts + * import { BasicIndex } from '@tanstack/db/indexing' + * const collection = createCollection({ + * defaultIndexType: BasicIndex, + * autoIndex: 'eager', + * // ... + * }) + * ``` + */ + defaultIndexType?: IndexConstructor /** * Optional function to compare two items. * This is used to order the items in the collection. diff --git a/packages/db/tests/collection-auto-index.test.ts b/packages/db/tests/collection-auto-index.test.ts index f40db1e61..eee7e14c5 100644 --- a/packages/db/tests/collection-auto-index.test.ts +++ b/packages/db/tests/collection-auto-index.test.ts @@ -12,6 +12,7 @@ import { import { createSingleRowRefProxy } from '../src/query/builder/ref-proxy' import { createLiveQueryCollection } from '../src' import { PropRef } from '../src/query/ir' +import { BTreeIndex } from '../src/indexes/btree-index' import { createIndexUsageTracker, expectIndexUsage, @@ -121,7 +122,7 @@ describe(`Collection Auto-Indexing`, () => { subscription.unsubscribe() }) - it(`should create auto-indexes by default when autoIndex is not specified`, async () => { + it(`should NOT create auto-indexes by default when autoIndex is not specified`, async () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, startSync: true, @@ -157,12 +158,8 @@ describe(`Collection Auto-Indexing`, () => { }, ) - // Should have created an auto-index for the status field (default is eager) - expect(autoIndexCollection.indexes.size).toBe(1) - - const autoIndex = Array.from(autoIndexCollection.indexes.values())[0]! - expect(autoIndex.expression.type).toBe(`ref`) - expect((autoIndex.expression as any).path).toEqual([`status`]) + // Should NOT have created an auto-index (default is off) + expect(autoIndexCollection.indexes.size).toBe(0) subscription.unsubscribe() }) @@ -171,6 +168,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -220,6 +218,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -267,6 +266,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -318,6 +318,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -358,6 +359,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -391,6 +393,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -436,6 +439,7 @@ describe(`Collection Auto-Indexing`, () => { const leftCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -456,6 +460,7 @@ describe(`Collection Auto-Indexing`, () => { const rightCollection = createCollection({ getKey: (item) => item.id2, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -548,6 +553,7 @@ describe(`Collection Auto-Indexing`, () => { const leftCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -568,6 +574,7 @@ describe(`Collection Auto-Indexing`, () => { const rightCollection = createCollection({ getKey: (item) => item.id2, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -667,6 +674,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -705,6 +713,7 @@ describe(`Collection Auto-Indexing`, () => { const autoIndexCollection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { @@ -801,6 +810,7 @@ describe(`Collection Auto-Indexing`, () => { const collection = createCollection({ getKey: (item) => item.id, autoIndex: `eager`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit, markReady }) => { diff --git a/packages/db/tests/collection-change-events.test.ts b/packages/db/tests/collection-change-events.test.ts index be59dde14..e1d912c1a 100644 --- a/packages/db/tests/collection-change-events.test.ts +++ b/packages/db/tests/collection-change-events.test.ts @@ -3,6 +3,7 @@ import { createCollection } from '../src/collection/index.js' import { currentStateAsChanges } from '../src/collection/change-events.js' import { Func, PropRef, Value } from '../src/query/ir.js' import { DEFAULT_COMPARE_OPTIONS } from '../src/utils.js' +import { BTreeIndex } from '../src/indexes/btree-index.js' interface TestUser { id: string @@ -39,6 +40,7 @@ describe(`currentStateAsChanges`, () => { id: `test-collection-${autoIndex}`, getKey: (user) => user.id, autoIndex, + defaultIndexType: autoIndex === `eager` ? BTreeIndex : undefined, sync: { sync: mockSync, }, diff --git a/packages/db/tests/collection-indexes.test.ts b/packages/db/tests/collection-indexes.test.ts index a8e3896fd..94aaa7f0f 100644 --- a/packages/db/tests/collection-indexes.test.ts +++ b/packages/db/tests/collection-indexes.test.ts @@ -14,6 +14,7 @@ import { or, } from '../src/query/builder/functions' import { PropRef } from '../src/query/ir' +import { BTreeIndex } from '../src/indexes/btree-index' import { expectIndexUsage, withIndexTracking } from './utils' import type { Collection } from '../src/collection/index.js' import type { MutationFn, PendingMutation } from '../src/types' @@ -87,6 +88,7 @@ describe(`Collection Indexes`, () => { collection = createCollection({ getKey: (item) => item.id, startSync: true, + defaultIndexType: BTreeIndex, sync: { sync: ({ begin, write, commit, markReady }) => { // Provide initial data through sync @@ -1320,6 +1322,7 @@ describe(`Collection Indexes`, () => { const specialCollection = createCollection({ getKey: (item) => item.id, startSync: true, + defaultIndexType: BTreeIndex, sync: { sync: ({ begin, write, commit }) => { begin() @@ -1381,6 +1384,7 @@ describe(`Collection Indexes`, () => { it(`should handle index creation on empty collection`, () => { const emptyCollection = createCollection({ getKey: (item) => item.id, + defaultIndexType: BTreeIndex, sync: { sync: () => {} }, }) diff --git a/packages/db/tests/query/indexes.test.ts b/packages/db/tests/query/indexes.test.ts index 9b221443c..3fa87d3a7 100644 --- a/packages/db/tests/query/indexes.test.ts +++ b/packages/db/tests/query/indexes.test.ts @@ -1,5 +1,6 @@ import { beforeEach, describe, expect, it } from 'vitest' import { createCollection } from '../../src/collection/index.js' +import { BTreeIndex } from '../../src/indexes/btree-index' import { createLiveQueryCollection } from '../../src/query/live-query-collection' import { @@ -234,6 +235,7 @@ function createTestItemCollection(autoIndex: `off` | `eager` = `off`) { getKey: (item) => item.id, initialData: testData, autoIndex, + defaultIndexType: BTreeIndex, }), ) } @@ -600,6 +602,7 @@ describe(`Query Index Optimization`, () => { const secondCollection = createCollection({ getKey: (item) => item.id, autoIndex: `off`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit }) => { @@ -894,6 +897,7 @@ describe(`Query Index Optimization`, () => { const secondCollection = createCollection({ getKey: (item) => item.id2, autoIndex: `off`, + defaultIndexType: BTreeIndex, startSync: true, sync: { sync: ({ begin, write, commit }) => { diff --git a/packages/db/tests/query/live-query-collection.test.ts b/packages/db/tests/query/live-query-collection.test.ts index 8c10c3eb8..5fe074720 100644 --- a/packages/db/tests/query/live-query-collection.test.ts +++ b/packages/db/tests/query/live-query-collection.test.ts @@ -15,6 +15,7 @@ import { mockSyncCollectionOptionsNoInitialState, } from '../utils.js' import { createDeferred } from '../../src/deferred' +import { BTreeIndex } from '../../src/indexes/btree-index' import type { ChangeMessage, LoadSubsetOptions } from '../../src/types.js' // Sample user type for tests @@ -1735,6 +1736,8 @@ describe(`createLiveQueryCollection`, () => { getKey: (item) => item.id, syncMode: `on-demand`, startSync: true, + autoIndex: `eager`, // Enable auto-indexing for orderBy optimization + defaultIndexType: BTreeIndex, sync: { sync: ({ markReady, begin, write, commit }) => { // Provide minimal initial data diff --git a/packages/db/tests/test-setup.ts b/packages/db/tests/test-setup.ts index a9d0dd31a..98bea44d1 100644 --- a/packages/db/tests/test-setup.ts +++ b/packages/db/tests/test-setup.ts @@ -1 +1,4 @@ import '@testing-library/jest-dom/vitest' + +// BTreeIndex is available via: import { BTreeIndex } from "../src/indexes/btree-index" +// Tests should pass defaultIndexType explicitly to collections when needed diff --git a/packages/db/tests/utils.ts b/packages/db/tests/utils.ts index 49b48db95..c096255f1 100644 --- a/packages/db/tests/utils.ts +++ b/packages/db/tests/utils.ts @@ -1,10 +1,12 @@ import { expect } from 'vitest' +import { BTreeIndex } from '../src/indexes/btree-index' import type { CollectionConfig, MutationFnParams, StringCollationConfig, SyncConfig, } from '../src/index.js' +import type { IndexConstructor } from '../src/indexes/base-index' // Index usage tracking utilities export interface IndexUsageStats { @@ -181,6 +183,7 @@ type MockSyncCollectionConfig> = { sync?: SyncConfig syncMode?: `eager` | `on-demand` defaultStringCollation?: StringCollationConfig + defaultIndexType?: IndexConstructor } export function mockSyncCollectionOptions< @@ -262,6 +265,10 @@ export function mockSyncCollectionOptions< utils, ...config, autoIndex: config.autoIndex, + // When autoIndex is 'eager', we need a defaultIndexType + defaultIndexType: + config.defaultIndexType ?? + (config.autoIndex === `eager` ? BTreeIndex : undefined), } return options @@ -271,6 +278,7 @@ type MockSyncCollectionConfigNoInitialState = { id: string getKey: (item: T) => string | number autoIndex?: `off` | `eager` + defaultIndexType?: IndexConstructor } export function mockSyncCollectionOptionsNoInitialState< @@ -344,6 +352,10 @@ export function mockSyncCollectionOptionsNoInitialState< utils, ...config, autoIndex: config.autoIndex, + // When autoIndex is 'eager', we need a defaultIndexType + defaultIndexType: + config.defaultIndexType ?? + (config.autoIndex === `eager` ? BTreeIndex : undefined), } return options diff --git a/packages/db/vite.config.ts b/packages/db/vite.config.ts index 62e1a9df2..2efafea83 100644 --- a/packages/db/vite.config.ts +++ b/packages/db/vite.config.ts @@ -16,7 +16,7 @@ const config = defineConfig({ export default mergeConfig( config, tanstackViteConfig({ - entry: `./src/index.ts`, + entry: [`./src/index.ts`, `./src/indexing.ts`], srcDir: `./src`, }), )