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 <[email protected]>

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: electricCollectionOptions
 function electricCollectionOptions<T>(config): CollectionConfig<InferSchemaOutput<T>, string | number, T, UtilsRecord> & object;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:254](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L254)
+Defined in: [packages/electric-db-collection/src/electric.ts:277](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L277)
 
 Creates Electric collection options for use with a standard Collection
 
@@ -43,7 +43,7 @@ Collection options with utilities
 function electricCollectionOptions<T>(config): CollectionConfig<T, string | number, never, UtilsRecord> & object;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:265](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L265)
+Defined in: [packages/electric-db-collection/src/electric.ts:288](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L288)
 
 Creates Electric collection options for use with a standard Collection
 

docs/reference/electric-db-collection/functions/electricCollectionOptions.md

@@ -5,13 +5,13 @@ title: ElectricCollectionConfig
 
 # Interface: ElectricCollectionConfig\<T, TSchema\>
 
-Defined in: [packages/electric-db-collection/src/electric.ts:80](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L80)
+Defined in: [packages/electric-db-collection/src/electric.ts:102](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L102)
 
 Configuration interface for Electric collection options
 
 ## Extends
 
-- `Omit`\<`BaseCollectionConfig`\<`T`, `string` \| `number`, `TSchema`, `UtilsRecord`, `any`\>, `"onInsert"` \| `"onUpdate"` \| `"onDelete"`\>
+- `Omit`\<`BaseCollectionConfig`\<`T`, `string` \| `number`, `TSchema`, `UtilsRecord`, `any`\>, `"onInsert"` \| `"onUpdate"` \| `"onDelete"` \| `"syncMode"`\>
 
 ## Type Parameters
 
@@ -35,7 +35,7 @@ The schema type for validation
 optional onDelete: (params) => Promise<MatchingStrategy>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:185](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L185)
+Defined in: [packages/electric-db-collection/src/electric.ts:208](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L208)
 
 Optional asynchronous handler function called before a delete operation
 
@@ -87,7 +87,7 @@ onDelete: async ({ transaction, collection }) => {
 optional onInsert: (params) => Promise<MatchingStrategy>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:128](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L128)
+Defined in: [packages/electric-db-collection/src/electric.ts:151](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L151)
 
 Optional asynchronous handler function called before an insert operation
 
@@ -150,7 +150,7 @@ onInsert: async ({ transaction, collection }) => {
 optional onUpdate: (params) => Promise<MatchingStrategy>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:157](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L157)
+Defined in: [packages/electric-db-collection/src/electric.ts:180](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L180)
 
 Optional asynchronous handler function called before an update operation
 
@@ -203,6 +203,16 @@ onUpdate: async ({ transaction, collection }) => {
 shapeOptions: ShapeStreamOptions<GetExtensions<T>>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:90](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L90)
+Defined in: [packages/electric-db-collection/src/electric.ts:112](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L112)
 
 Configuration options for the ElectricSQL ShapeStream
+
+***
+
+### syncMode?
+
+```ts
+optional syncMode: ElectricSyncMode;
+```
+
+Defined in: [packages/electric-db-collection/src/electric.ts:113](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L113)

docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md

@@ -5,7 +5,7 @@ title: ElectricCollectionUtils
 
 # Interface: ElectricCollectionUtils\<T\>
 
-Defined in: [packages/electric-db-collection/src/electric.ts:237](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L237)
+Defined in: [packages/electric-db-collection/src/electric.ts:260](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L260)
 
 Electric collection utilities type
 
@@ -33,7 +33,7 @@ Electric collection utilities type
 awaitMatch: AwaitMatchFn<T>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:240](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L240)
+Defined in: [packages/electric-db-collection/src/electric.ts:263](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L263)
 
 ***
 
@@ -43,4 +43,4 @@ Defined in: [packages/electric-db-collection/src/electric.ts:240](https://github
 awaitTxId: AwaitTxIdFn;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:239](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L239)
+Defined in: [packages/electric-db-collection/src/electric.ts:262](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L262)

docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md

@@ -9,7 +9,7 @@ title: AwaitTxIdFn
 type AwaitTxIdFn = (txId, timeout?) => Promise<boolean>;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:224](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L224)
+Defined in: [packages/electric-db-collection/src/electric.ts:247](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L247)
 
 Type for the awaitTxId utility function
 

docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md

@@ -9,6 +9,6 @@ title: Txid
 type Txid = number;
 ```
 
-Defined in: [packages/electric-db-collection/src/electric.ts:42](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L42)
+Defined in: [packages/electric-db-collection/src/electric.ts:46](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L46)
 
 Type representing a transaction ID in ElectricSQL

docs/reference/electric-db-collection/type-aliases/Txid.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)