Add optional compareOptions to the Collection Config which act as col… (#762)

* Add optional compareOptions to the Collection Config which act as collection-wide config and allow queries to override those.

* Fix import

* changeset

* Ran prettier

* update docs

* Live queries inherit compare options from collection in the FROM clause

* Explicit compare options for live queries

* Rename compareOptions to defaultStringCollation in the collection config and live query collection config

* Docs update

---------

Co-authored-by: Sam Willis <sam.willis@gmail.com>

Author: kevin-dp

.changeset/all-meals-follow.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add optional compareOptions to collection configuration.

docs/reference/classes/CollectionImpl.md

@@ -11,7 +11,7 @@ title: createCollection
 function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & NonSingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:130](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L130)
+Defined in: [packages/db/src/collection/index.ts:131](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L131)
 
 Creates a new Collection instance with the given configuration
 
@@ -120,7 +120,7 @@ const todos = createCollection({
 function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & SingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:143](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L143)
+Defined in: [packages/db/src/collection/index.ts:144](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L144)
 
 Creates a new Collection instance with the given configuration
 
@@ -229,7 +229,7 @@ const todos = createCollection({
 function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & NonSingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:157](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L157)
+Defined in: [packages/db/src/collection/index.ts:158](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L158)
 
 Creates a new Collection instance with the given configuration
 
@@ -338,7 +338,7 @@ const todos = createCollection({
 function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & SingleResult;
 ```
 
-Defined in: [packages/db/src/collection/index.ts:170](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L170)
+Defined in: [packages/db/src/collection/index.ts:171](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L171)
 
 Creates a new Collection instance with the given configuration
 

docs/reference/functions/createCollection.md

@@ -110,6 +110,7 @@ title: "@tanstack/db"
 - [ChangeMessage](../interfaces/ChangeMessage.md)
 - [Collection](../interfaces/Collection.md)
 - [CollectionConfig](../interfaces/CollectionConfig.md)
+- [CollectionLike](../interfaces/CollectionLike.md)
 - [Context](../interfaces/Context.md)
 - [CreateOptimisticActionsOptions](../interfaces/CreateOptimisticActionsOptions.md)
 - [CurrentStateAsChangesOptions](../interfaces/CurrentStateAsChangesOptions.md)
@@ -193,6 +194,7 @@ title: "@tanstack/db"
 - [StorageEventApi](../type-aliases/StorageEventApi.md)
 - [Strategy](../type-aliases/Strategy.md)
 - [StrategyOptions](../type-aliases/StrategyOptions.md)
+- [StringCollationConfig](../type-aliases/StringCollationConfig.md)
 - [SubscriptionEvents](../type-aliases/SubscriptionEvents.md)
 - [SubscriptionStatus](../type-aliases/SubscriptionStatus.md)
 - [SyncConfigRes](../type-aliases/SyncConfigRes.md)

docs/reference/index.md

@@ -5,7 +5,7 @@ title: BaseCollectionConfig
 
 # Interface: BaseCollectionConfig\<T, TKey, TSchema, TUtils, TReturn\>
 
-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:416](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L416)
 
 ## Extended by
 
@@ -42,7 +42,7 @@ Defined in: [packages/db/src/types.ts:385](https://github.com/TanStack/db/blob/m
 optional autoIndex: "eager" | "off";
 ```
 
-Defined in: [packages/db/src/types.ts:434](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L434)
+Defined in: [packages/db/src/types.ts:465](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L465)
 
 Auto-indexing mode for the collection.
 When enabled, indexes will be automatically created for simple where expressions.
@@ -66,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:445](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L445)
+Defined in: [packages/db/src/types.ts:476](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L476)
 
 Optional function to compare two items.
 This is used to order the items in the collection.
@@ -100,13 +100,28 @@ compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
 
 ***
 
+### defaultStringCollation?
+
+```ts
+optional defaultStringCollation: StringCollationConfig;
+```
+
+Defined in: [packages/db/src/types.ts:622](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L622)
+
+Specifies how to compare data in the collection.
+This should be configured to match data ordering on the backend.
+E.g., when using the Electric DB collection these options
+      should match the database's collation settings.
+
+***
+
 ### gcTime?
 
 ```ts
 optional gcTime: number;
 ```
 
-Defined in: [packages/db/src/types.ts:414](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L414)
+Defined in: [packages/db/src/types.ts:445](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L445)
 
 Time in milliseconds after which the collection will be garbage collected
 when it has no active subscribers. Defaults to 5 minutes (300000ms).
@@ -119,7 +134,7 @@ when it has no active subscribers. Defaults to 5 minutes (300000ms).
 getKey: (item) => TKey;
 ```
 
-Defined in: [packages/db/src/types.ts:409](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L409)
+Defined in: [packages/db/src/types.ts:440](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L440)
 
 Function to extract the ID from an object
 This is required for update/delete operations which now only accept IDs
@@ -153,7 +168,7 @@ getKey: (item) => item.uuid
 optional id: string;
 ```
 
-Defined in: [packages/db/src/types.ts:398](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L398)
+Defined in: [packages/db/src/types.ts:429](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L429)
 
 ***
 
@@ -163,7 +178,7 @@ Defined in: [packages/db/src/types.ts:398](https://github.com/TanStack/db/blob/m
 optional onDelete: DeleteMutationFn<T, TKey, TUtils, TReturn>;
 ```
 
-Defined in: [packages/db/src/types.ts:583](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L583)
+Defined in: [packages/db/src/types.ts:614](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L614)
 
 Optional asynchronous handler function called before a delete operation
 
@@ -227,7 +242,7 @@ onDelete: async ({ transaction, collection }) => {
 optional onInsert: InsertMutationFn<T, TKey, TUtils, TReturn>;
 ```
 
-Defined in: [packages/db/src/types.ts:496](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L496)
+Defined in: [packages/db/src/types.ts:527](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L527)
 
 Optional asynchronous handler function called before an insert operation
 
@@ -290,7 +305,7 @@ onInsert: async ({ transaction, collection }) => {
 optional onUpdate: UpdateMutationFn<T, TKey, TUtils, TReturn>;
 ```
 
-Defined in: [packages/db/src/types.ts:540](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L540)
+Defined in: [packages/db/src/types.ts:571](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L571)
 
 Optional asynchronous handler function called before an update operation
 
@@ -354,7 +369,7 @@ onUpdate: async ({ transaction, collection }) => {
 optional schema: TSchema;
 ```
 
-Defined in: [packages/db/src/types.ts:399](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L399)
+Defined in: [packages/db/src/types.ts:430](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L430)
 
 ***
 
@@ -364,7 +379,7 @@ Defined in: [packages/db/src/types.ts:399](https://github.com/TanStack/db/blob/m
 optional startSync: boolean;
 ```
 
-Defined in: [packages/db/src/types.ts:425](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L425)
+Defined in: [packages/db/src/types.ts:456](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L456)
 
 Whether to eagerly start syncing on collection creation.
 When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches.
@@ -387,7 +402,7 @@ false
 optional syncMode: SyncMode;
 ```
 
-Defined in: [packages/db/src/types.ts:454](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L454)
+Defined in: [packages/db/src/types.ts:485](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L485)
 
 The mode of sync to use for the collection.
 
@@ -409,4 +424,4 @@ The exact implementation of the sync mode is up to the sync implementation.
 optional utils: TUtils;
 ```
 
-Defined in: [packages/db/src/types.ts:585](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L585)
+Defined in: [packages/db/src/types.ts:624](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L624)

docs/reference/interfaces/BaseCollectionConfig.md

@@ -5,7 +5,7 @@ title: ChangeMessage
 
 # Interface: ChangeMessage\<T, TKey\>
 
-Defined in: [packages/db/src/types.ts:261](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L261)
+Defined in: [packages/db/src/types.ts:292](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L292)
 
 ## Extended by
 
@@ -29,7 +29,7 @@ Defined in: [packages/db/src/types.ts:261](https://github.com/TanStack/db/blob/m
 key: TKey;
 ```
 
-Defined in: [packages/db/src/types.ts:265](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L265)
+Defined in: [packages/db/src/types.ts:296](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L296)
 
 ***
 
@@ -39,7 +39,7 @@ Defined in: [packages/db/src/types.ts:265](https://github.com/TanStack/db/blob/m
 optional metadata: Record<string, unknown>;
 ```
 
-Defined in: [packages/db/src/types.ts:269](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L269)
+Defined in: [packages/db/src/types.ts:300](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L300)
 
 ***
 
@@ -49,7 +49,7 @@ Defined in: [packages/db/src/types.ts:269](https://github.com/TanStack/db/blob/m
 optional previousValue: T;
 ```
 
-Defined in: [packages/db/src/types.ts:267](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L267)
+Defined in: [packages/db/src/types.ts:298](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L298)
 
 ***
 
@@ -59,7 +59,7 @@ Defined in: [packages/db/src/types.ts:267](https://github.com/TanStack/db/blob/m
 type: OperationType;
 ```
 
-Defined in: [packages/db/src/types.ts:268](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L268)
+Defined in: [packages/db/src/types.ts:299](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L299)
 
 ***
 
@@ -69,4 +69,4 @@ Defined in: [packages/db/src/types.ts:268](https://github.com/TanStack/db/blob/m
 value: T;
 ```
 
-Defined in: [packages/db/src/types.ts:266](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L266)
+Defined in: [packages/db/src/types.ts:297](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L297)