Replace getPrimaryKey w/ getId (#80)

Author: KyleAMathews

README.md

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

docs/index.md

@@ -93,7 +93,7 @@ See the [Electric docs](https://electric-sql.com/docs/intro) for more informatio
 const todoCollection = createQueryCollection({
   queryKey: ['todoItems'],
   queryFn: async () => fetch('/api/todos'),
-  getPrimaryKey: (item) => item.id
+  getId: (item) => item.id
 })
 ```
 

examples/react/todo/src/App.tsx

@@ -167,7 +167,7 @@ const createTodoCollection = (type: CollectionType) => {
             updated_at: todo.updated_at ? new Date(todo.updated_at) : undefined,
           }))
         },
-        getPrimaryKey: (item) => String(item.id),
+        getId: (item) => String(item.id),
         schema: updateTodoSchema,
         queryClient,
       })
@@ -220,7 +220,7 @@ const createConfigCollection = (type: CollectionType) => {
               : undefined,
           }))
         },
-        getPrimaryKey: (item) => String(item.id),
+        getId: (item) => String(item.id),
         schema: updateConfigSchema,
         queryClient,
       })

packages/db-collections/src/query.ts

@@ -15,7 +15,7 @@ export interface QueryCollectionConfig<
 > extends Omit<CollectionConfig<TItem>, `sync`> {
   queryKey: TQueryKey
   queryFn: (context: QueryFunctionContext<TQueryKey>) => Promise<Array<TItem>>
-  getPrimaryKey: (item: TItem) => string
+  getId: (item: TItem) => string
 
   enabled?: boolean
   refetchInterval?: QueryObserverOptions<
@@ -71,11 +71,11 @@ export class QueryCollection<
     if (!queryClient)
       throw new Error(`[QueryCollection] queryClient must be provided.`)
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!baseCollectionConfig.getPrimaryKey) {
-      throw new Error(`[QueryCollection] getPrimaryKey must be provided.`)
+    if (!baseCollectionConfig.getId) {
+      throw new Error(`[QueryCollection] getId must be provided.`)
     }
 
-    const getPrimaryKeyFn = baseCollectionConfig.getPrimaryKey
+    const getIdFn = baseCollectionConfig.getId
 
     const internalSync: SyncConfig<TItem>[`sync`] = (params) => {
       const { begin, write, commit, collection } = params
@@ -124,7 +124,7 @@ export class QueryCollection<
           const newItemsMap = new Map<string, TItem>()
           newItemsArray.forEach((item) => {
             try {
-              const key = getPrimaryKeyFn(item)
+              const key = getIdFn(item)
               newItemsMap.set(key, item)
             } catch (e) {
               console.error(

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

@@ -9,7 +9,7 @@ interface TestItem {
   value?: number
 }
 
-const getPrimaryKey = (item: TestItem) => item.id
+const getId = (item: TestItem) => item.id
 
 // Helper to advance timers and allow microtasks to flush
 const flushPromises = () => new Promise((resolve) => setTimeout(resolve, 0))
@@ -49,7 +49,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getPrimaryKey,
+      getId,
     }
 
     const collection = createQueryCollection(config)
@@ -100,7 +100,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getPrimaryKey,
+      getId,
     }
 
     const collection = createQueryCollection(config)
@@ -168,7 +168,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getPrimaryKey,
+      getId,
       retry: 0, // Disable retries for this test case
     })
 
@@ -217,7 +217,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getPrimaryKey,
+      getId,
     })
 
     // Wait for the query to execute
@@ -264,7 +264,7 @@ describe(`QueryCollection`, () => {
       queryClient,
       queryKey,
       queryFn,
-      getPrimaryKey,
+      getId,
     })
 
     // Wait for initial data to load
@@ -320,7 +320,7 @@ describe(`QueryCollection`, () => {
     consoleSpy.mockRestore()
   })
 
-  it(`should use the provided getPrimaryKey function to identify items`, async () => {
+  it(`should use the provided getId function to identify items`, async () => {
     const queryKey = [`customKeyTest`]
 
     // Items with a non-standard ID field
@@ -331,15 +331,15 @@ describe(`QueryCollection`, () => {
 
     const queryFn = vi.fn().mockResolvedValue(items)
 
-    // Create a spy for the getPrimaryKey function
-    const getPrimaryKeySpy = vi.fn((item: any) => item.customId)
+    // Create a spy for the getId function
+    const getIdSpy = vi.fn((item: any) => item.customId)
 
     const collection = createQueryCollection({
       id: `test`,
       queryClient,
       queryKey,
       queryFn,
-      getPrimaryKey: getPrimaryKeySpy,
+      getId: getIdSpy,
     })
 
     // Wait for initial data to load
@@ -348,10 +348,10 @@ describe(`QueryCollection`, () => {
       expect(collection.state.size).toBe(items.length)
     })
 
-    // Verify getPrimaryKey was called for each item
-    expect(getPrimaryKeySpy).toHaveBeenCalledTimes(items.length)
+    // Verify getId was called for each item
+    expect(getIdSpy).toHaveBeenCalledTimes(items.length)
     items.forEach((item) => {
-      expect(getPrimaryKeySpy).toHaveBeenCalledWith(item)
+      expect(getIdSpy).toHaveBeenCalledWith(item)
     })
 
     // Verify items are stored with the custom keys
@@ -368,7 +368,7 @@ describe(`QueryCollection`, () => {
     ]
 
     // Reset the spy to track new calls
-    getPrimaryKeySpy.mockClear()
+    getIdSpy.mockClear()
     queryFn.mockResolvedValueOnce(updatedItems)
 
     // Trigger a refetch
@@ -380,11 +380,11 @@ describe(`QueryCollection`, () => {
       expect(collection.state.size).toBe(updatedItems.length)
     })
 
-    // Verify getPrimaryKey was called at least once for each item
+    // Verify getId was called at least once for each item
     // It may be called multiple times per item during the diffing process
-    expect(getPrimaryKeySpy).toHaveBeenCalled()
+    expect(getIdSpy).toHaveBeenCalled()
     updatedItems.forEach((item) => {
-      expect(getPrimaryKeySpy).toHaveBeenCalledWith(item)
+      expect(getIdSpy).toHaveBeenCalledWith(item)
     })
 
     // Verify the state reflects the changes