[DEBUG] Reproduce type problem with electric collection utils

packages/electric-db-collection/tests/electric.test-d.ts

@@ -8,7 +8,10 @@ import {
   gt,
 } from "@tanstack/db"
 import { electricCollectionOptions } from "../src/electric"
-import type { ElectricCollectionConfig } from "../src/electric"
+import type {
+  ElectricCollectionConfig,
+  ElectricCollectionUtils,
+} from "../src/electric"
 import type {
   DeleteMutationFnParams,
   InsertMutationFnParams,
@@ -97,6 +100,59 @@ describe(`Electric collection type resolution tests`, () => {
     expectTypeOf(options.getKey).parameters.toEqualTypeOf<[FallbackType]>()
   })
 
+  it(`should type collection.utils as ElectricCollectionUtils<T>`, () => {
+    const todoSchema = z.object({
+      id: z.string(),
+      title: z.string(),
+      completed: z.boolean(),
+    })
+
+    type TodoType = z.infer<typeof todoSchema>
+
+    const options = electricCollectionOptions({
+      id: `todos`,
+      getKey: (item) => item.id,
+      shapeOptions: {
+        url: `/api/todos`,
+        params: { table: `todos` },
+      },
+      schema: todoSchema,
+      /*
+      onInsert: async ({ collection }) => {
+        const testCollectionUtils: ElectricCollectionUtils<TodoType> =
+          collection.utils
+        expectTypeOf(testCollectionUtils.awaitTxId).toBeFunction
+        expectTypeOf(collection.utils.awaitTxId).toBeFunction
+        return Promise.resolve({ txid: 1 })
+      },
+      */
+    })
+
+    // ✅ Test that options.utils is typed as ElectricCollectionUtils<TodoType>
+    // The options object should have the correct type from electricCollectionOptions
+    const testOptionsUtils: ElectricCollectionUtils<TodoType> = options.utils
+
+    expectTypeOf(testOptionsUtils.awaitTxId).toBeFunction
+
+    const todosCollection = createCollection(options)
+
+    // Test that todosCollection.utils is ElectricCollectionUtils<TodoType>
+    // Note: We can't use expectTypeOf(...).toEqualTypeOf<ElectricCollectionUtils<T>> because
+    // expectTypeOf's toEqualTypeOf has a constraint that requires { [x: string]: any; [x: number]: never; },
+    // but ElectricCollectionUtils extends UtilsRecord which is Record<string, any> (no number index signature).
+    // This causes a constraint error instead of a type mismatch error.
+    // Instead, we test via type assignment which will show a proper type error if the types don't match.
+    // Currently this shows that todosCollection.utils is typed as UtilsRecord, not ElectricCollectionUtils<TodoType>
+    const testTodosUtils: ElectricCollectionUtils<TodoType> =
+      todosCollection.utils
+
+    expectTypeOf(testTodosUtils.awaitTxId).toBeFunction
+
+    // Verify the specific properties that define ElectricCollectionUtils exist and are functions
+    expectTypeOf(todosCollection.utils.awaitTxId).toBeFunction
+    expectTypeOf(todosCollection.utils.awaitMatch).toBeFunction
+  })
+
   it(`should properly type the onInsert, onUpdate, and onDelete handlers`, () => {
     const options = electricCollectionOptions<ExplicitType>({
       shapeOptions: {