Change collections to us key rather than id, change key to globalKey for transactions, and rename getId to getKey

Author: samwillis

README.md

@@ -53,7 +53,7 @@ import { createQueryCollection } from "@tanstack/db-collections"
 const todoCollection = createQueryCollection<Todo>({
   queryKey: ["todos"],
   queryFn: async () => fetch("/api/todos"),
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoSchema, // any standard schema
 })
 ```

docs/overview.md

@@ -173,7 +173,7 @@ If provided, this should be a [Standard Schema](https://standardschema.dev) comp
 const todoCollection = createCollection<Todo>(queryCollectionOptions({
   queryKey: ['todoItems'],
   queryFn: async () => fetch('/api/todos'),
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoSchema // any standard schema
 }))
 ```
@@ -198,7 +198,7 @@ export const todoCollection = createCollection<Todo>(electricCollectionOptions({
       table: 'todos'
     }
   },
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoSchema
 }).options)
 ```
@@ -208,7 +208,7 @@ The Electric collection requires two Electric-specific options:
 - `shapeOptions` &mdash; the Electric [ShapeStreamOptions](https://electric-sql.com/docs/api/clients/typescript#options) that define the [Shape](https://electric-sql.com/docs/guides/shapes) to sync into the collection; this includes the
   - `url` to your sync engine; and
   - `params` to specify the `table` to sync and any optional `where` clauses, etc.
-- `getId` &mdash; identifies the id for the rows being synced into the collection
+- `getKey` &mdash; identifies the id for the rows being synced into the collection
 
 When you create the collection, sync starts automatically.
 
@@ -228,7 +228,7 @@ export const myPendingTodos = createCollection<Todo>(electricCollectionOptions({
       `
     }
   },
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoSchema
 }).options)
 ```
@@ -515,7 +515,7 @@ import { queryCollectionOptions } from "@tanstack/db-collections"
 const todoCollection = createCollection<Todo>(queryCollectionOptions({
   queryKey: ["todos"],
   queryFn: async () => fetch("/api/todos"),
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoSchema, // any standard schema
   onInsert: ({ transaction }) => {
     const { changes: newTodo } = transaction.mutations[0]
@@ -528,7 +528,7 @@ const todoCollection = createCollection<Todo>(queryCollectionOptions({
 const listCollection = createCollection<TodoList>(queryCollectionOptions({
   queryKey: ["todo-lists"],
   queryFn: async () => fetch("/api/todo-lists"),
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoListSchema
   onInsert: ({ transaction }) => {
     const { changes: newTodo } = transaction.mutations[0]
@@ -586,7 +586,7 @@ export const todoCollection = createCollection(electricCollectionOptions<Todo>({
       table: 'todos'
     }
   },
-  getId: (item) => item.id,
+  getKey: (item) => item.id,
   schema: todoSchema
 }))
 

examples/react/todo/src/App.tsx

@@ -147,7 +147,7 @@ const createTodoCollection = (type: CollectionType) => {
               timestamptz: (date: string) => new Date(date),
             },
           },
-          getId: (item) => item.id,
+          getKey: (item) => item.id,
           schema: updateTodoSchema,
           onInsert: async ({ transaction }) => {
             const modified = transaction.mutations[0].modified
@@ -201,7 +201,7 @@ const createTodoCollection = (type: CollectionType) => {
                 : undefined,
             }))
           },
-          getId: (item: UpdateTodo) => String(item.id),
+          getKey: (item: UpdateTodo) => String(item.id),
           schema: updateTodoSchema,
           queryClient,
           onInsert: async ({ transaction }) => {
@@ -254,7 +254,7 @@ const createConfigCollection = (type: CollectionType) => {
               },
             },
           },
-          getId: (item: UpdateConfig) => item.id,
+          getKey: (item: UpdateConfig) => item.id,
           schema: updateConfigSchema,
           onInsert: async ({ transaction }) => {
             const modified = transaction.mutations[0].modified
@@ -297,7 +297,7 @@ const createConfigCollection = (type: CollectionType) => {
                 : undefined,
             }))
           },
-          getId: (item: UpdateConfig) => item.id,
+          getKey: (item: UpdateConfig) => item.id,
           schema: updateConfigSchema,
           queryClient,
           onInsert: async ({ transaction }) => {

packages/db-collections/src/electric.ts

@@ -30,7 +30,7 @@ export interface ElectricCollectionConfig<T extends Row<unknown>> {
    */
   id?: string
   schema?: CollectionConfig<T>[`schema`]
-  getId: CollectionConfig<T>[`getId`]
+  getKey: CollectionConfig<T>[`getKey`]
   sync?: CollectionConfig<T>[`sync`]
 
   /**

packages/db-collections/src/query.ts

@@ -53,7 +53,7 @@ export interface QueryCollectionConfig<
 
   // Standard Collection configuration properties
   id?: string
-  getId: CollectionConfig<TItem>[`getId`]
+  getKey: CollectionConfig<TItem>[`getKey`]
   schema?: CollectionConfig<TItem>[`schema`]
   sync?: CollectionConfig<TItem>[`sync`]
 
@@ -105,7 +105,7 @@ export function queryCollectionOptions<
     retry,
     retryDelay,
     staleTime,
-    getId,
+    getKey,
     onInsert,
     onUpdate,
     onDelete,
@@ -126,8 +126,8 @@ export function queryCollectionOptions<
     throw new Error(`[QueryCollection] queryClient must be provided.`)
   }
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (!getId) {
-    throw new Error(`[QueryCollection] getId must be provided.`)
+  if (!getKey) {
+    throw new Error(`[QueryCollection] getKey must be provided.`)
   }
 
   const internalSync: SyncConfig<TItem>[`sync`] = (params) => {
@@ -178,7 +178,7 @@ export function queryCollectionOptions<
         const newItemsMap = new Map<string, TItem>()
         newItemsArray.forEach((item) => {
           try {
-            const key = getId(item)
+            const key = getKey(item)
             newItemsMap.set(key, item)
           } catch (e) {
             console.error(
@@ -318,7 +318,7 @@ export function queryCollectionOptions<
   return {
     options: {
       ...baseCollectionConfig,
-      getId,
+      getKey,
       sync: { sync: internalSync },
       onInsert: wrappedOnInsert,
       onUpdate: wrappedOnUpdate,

packages/db-collections/tests/electric.test.ts

@@ -45,7 +45,7 @@ describe(`Electric Integration`, () => {
           table: `test_table`,
         },
       },
-      getId: (item: Row) => item.id,
+      getKey: (item: Row) => item.id,
     }
 
     const { options, awaitTxId: txIdFn } = electricCollectionOptions(config)
@@ -396,7 +396,7 @@ describe(`Electric Integration`, () => {
             table: `test_table`,
           },
         },
-        getId: (item: Row) => item.id,
+        getKey: (item: Row) => item.id,
         onInsert,
         onUpdate,
         onDelete,
@@ -426,7 +426,7 @@ describe(`Electric Integration`, () => {
             table: `test_table`,
           },
         },
-        getId: (item: Row) => item.id,
+        getKey: (item: Row) => item.id,
         onInsert,
       }
 
@@ -510,7 +510,7 @@ describe(`Electric Integration`, () => {
             table: `test_table`,
           },
         },
-        getId: (item: Row) => item.id,
+        getKey: (item: Row) => item.id,
         onInsert,
       }
 

packages/db-collections/tests/query.test.ts

@@ -11,7 +11,7 @@ interface TestItem {
   value?: number
 }
 
-const getId = (item: TestItem) => item.id
+const getKey = (item: TestItem) => item.id
 
 // Helper to advance timers and allow microtasks to flush
 const flushPromises = () => new Promise((resolve) => setTimeout(resolve, 0))
@@ -51,7 +51,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getId,
+      getKey,
     }
 
     const { options } = queryCollectionOptions(config)
@@ -111,7 +111,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getId,
+      getKey,
     }
 
     const { options, refetch } = queryCollectionOptions(config)
@@ -192,7 +192,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getId,
+      getKey,
       retry: 0, // Disable retries for this test case
     })
     const collection = new Collection(options)
@@ -242,7 +242,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getId,
+      getKey,
     })
     const collection = new Collection(options)
 
@@ -290,7 +290,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getId,
+      getKey,
     })
     const collection = new Collection(options)
 
@@ -353,7 +353,7 @@ describe(`QueryCollection`, () => {
     consoleSpy.mockRestore()
   })
 
-  it(`should use the provided getId function to identify items`, async () => {
+  it(`should use the provided getKey function to identify items`, async () => {
     const queryKey = [`customKeyTest`]
 
     // Items with a non-standard ID field
@@ -364,15 +364,15 @@ describe(`QueryCollection`, () => {
 
     const queryFn = vi.fn().mockResolvedValue(items)
 
-    // Create a spy for the getId function
-    const getIdSpy = vi.fn((item: any) => item.customId)
+    // Create a spy for the getKey function
+    const getKeySpy = vi.fn((item: any) => item.customId)
 
     const { options, refetch } = queryCollectionOptions({
       id: `test`,
       queryClient,
       queryKey,
       queryFn,
-      getId: getIdSpy,
+      getKey: getKeySpy,
     })
     const collection = new Collection(options)
 
@@ -382,10 +382,10 @@ describe(`QueryCollection`, () => {
       expect(collection.state.size).toBe(items.length)
     })
 
-    // Verify getId was called for each item
-    expect(getIdSpy).toHaveBeenCalledTimes(items.length * 2)
+    // Verify getKey was called for each item
+    expect(getKeySpy).toHaveBeenCalledTimes(items.length * 2)
     items.forEach((item) => {
-      expect(getIdSpy).toHaveBeenCalledWith(item)
+      expect(getKeySpy).toHaveBeenCalledWith(item)
     })
 
     // Verify items are stored with the custom keys
@@ -406,7 +406,7 @@ describe(`QueryCollection`, () => {
     ]
 
     // Reset the spy to track new calls
-    getIdSpy.mockClear()
+    getKeySpy.mockClear()
     queryFn.mockResolvedValueOnce(updatedItems)
 
     // Trigger a refetch
@@ -415,11 +415,11 @@ describe(`QueryCollection`, () => {
     expect(queryFn).toHaveBeenCalledTimes(2)
     expect(collection.state.size).toBe(updatedItems.length)
 
-    // Verify getId was called at least once for each item
+    // Verify getKey was called at least once for each item
     // It may be called multiple times per item during the diffing process
-    expect(getIdSpy).toHaveBeenCalled()
+    expect(getKeySpy).toHaveBeenCalled()
     updatedItems.forEach((item) => {
-      expect(getIdSpy).toHaveBeenCalledWith(item)
+      expect(getKeySpy).toHaveBeenCalledWith(item)
     })
 
     // Verify the state reflects the changes
@@ -450,7 +450,7 @@ describe(`QueryCollection`, () => {
         queryClient,
         queryKey,
         queryFn,
-        getId,
+        getKey,
         onInsert,
         onUpdate,
         onDelete,
@@ -483,7 +483,7 @@ describe(`QueryCollection`, () => {
         queryClient,
         queryKey,
         queryFn,
-        getId,
+        getKey,
         onInsert,
         onUpdate,
         onDelete,
@@ -520,7 +520,7 @@ describe(`QueryCollection`, () => {
         queryClient,
         queryKey: [`refetchTest`, `default`],
         queryFn: vi.fn().mockResolvedValue([{ id: `1`, name: `Item 1` }]),
-        getId,
+        getKey,
         onInsert: onInsertDefault,
       }
 
@@ -529,7 +529,7 @@ describe(`QueryCollection`, () => {
         queryClient,
         queryKey: [`refetchTest`, `false`],
         queryFn: vi.fn().mockResolvedValue([{ id: `1`, name: `Item 1` }]),
-        getId,
+        getKey,
         onInsert: onInsertFalse,
       }