feat: Make mutationFn optional for read-only collections (#12)

Author: KyleAMathews

.changeset/cruel-ducks-fix.md

@@ -0,0 +1,6 @@
+---
+"@tanstack/react-optimistic": patch
+"@tanstack/optimistic": patch
+---
+
+make mutationFn optional for read-only collections

packages/optimistic/src/TransactionManager.ts

@@ -231,6 +231,13 @@ export class TransactionManager<T extends object = Record<string, unknown>> {
     const transaction = this.getTransaction(transactionId)
     if (!transaction) return
 
+    // If no mutationFn is provided, throw an error
+    if (!this.collection.config.mutationFn) {
+      throw new Error(
+        `Cannot process transaction without a mutationFn in the collection config`
+      )
+    }
+
     this.setTransactionState(transactionId, `persisting`)
 
     this.collection.config.mutationFn
@@ -243,14 +250,14 @@ export class TransactionManager<T extends object = Record<string, unknown>> {
         if (!tx) return
 
         tx.isPersisted?.resolve(true)
-        if (this.collection.config.mutationFn.awaitSync) {
+        if (this.collection.config.mutationFn?.awaitSync) {
           this.setTransactionState(transactionId, `persisted_awaiting_sync`)
 
           // Create a promise that rejects after 2 seconds
           const timeoutPromise = new Promise<never>((_, reject) => {
             setTimeout(() => {
               reject(new Error(`Sync operation timed out after 2 seconds`))
-            }, this.collection.config.mutationFn.awaitSyncTimeoutMs ?? 2000)
+            }, this.collection.config.mutationFn?.awaitSyncTimeoutMs ?? 2000)
           })
 
           // Race the awaitSync promise against the timeout

packages/optimistic/src/collection.ts

@@ -45,6 +45,7 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
  *   await preloadCollection({
  *     id: `users-${params.userId}`,
  *     sync: { ... },
+ *     // mutationFn is optional - provide it if you need mutation capabilities
  *     mutationFn: { ... }
  *   });
  *
@@ -53,7 +54,7 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
  * ```
  *
  * @template T - The type of items in the collection
- * @param config - Configuration for the collection, including id, sync, and mutationFn
+ * @param config - Configuration for the collection, including id, sync, and optional mutationFn
  * @returns Promise that resolves when the initial sync is finished
  */
 export function preloadCollection<T extends object = Record<string, unknown>>(
@@ -182,15 +183,12 @@ export class Collection<T extends object = Record<string, unknown>> {
    * Creates a new Collection instance
    *
    * @param config - Configuration object for the collection
-   * @throws Error if sync config or mutationFn is missing
+   * @throws Error if sync config is missing
    */
   constructor(config?: CollectionConfig<T>) {
     if (!config?.sync) {
       throw new Error(`Collection requires a sync config`)
     }
-    if (!config.mutationFn as unknown) {
-      throw new Error(`Collection requires a mutationFn`)
-    }
 
     this.transactionStore = new TransactionStore()
     this.transactionManager = getTransactionManager<T>(
@@ -517,6 +515,7 @@ export class Collection<T extends object = Record<string, unknown>> {
    * @param config - Optional configuration including metadata and custom keys
    * @returns A Transaction object representing the insert operation(s)
    * @throws {SchemaValidationError} If the data fails schema validation
+   * @throws {Error} If mutationFn is not provided
    * @example
    * // Insert a single item
    * insert({ text: "Buy groceries", completed: false })
@@ -531,6 +530,13 @@ export class Collection<T extends object = Record<string, unknown>> {
    * insert({ text: "Buy groceries" }, { key: "grocery-task" })
    */
   insert = (data: T | Array<T>, config?: InsertConfig) => {
+    // Throw error if mutationFn is not provided
+    if (!this.config.mutationFn) {
+      throw new Error(
+        `Cannot use mutation operators without providing a mutationFn in the collection config`
+      )
+    }
+
     const items = Array.isArray(data) ? data : [data]
     const mutations: Array<PendingMutation> = []
 
@@ -582,6 +588,7 @@ export class Collection<T extends object = Record<string, unknown>> {
    * @param maybeCallback - Update callback if config was provided
    * @returns A Transaction object representing the update operation(s)
    * @throws {SchemaValidationError} If the updated data fails schema validation
+   * @throws {Error} If mutationFn is not provided
    * @example
    * // Update a single item
    * update(todo, (draft) => { draft.completed = true })
@@ -612,6 +619,13 @@ export class Collection<T extends object = Record<string, unknown>> {
     configOrCallback: ((draft: TItem | Array<TItem>) => void) | OperationConfig,
     maybeCallback?: (draft: TItem | Array<TItem>) => void
   ) {
+    // Throw error if mutationFn is not provided
+    if (!this.config.mutationFn) {
+      throw new Error(
+        `Cannot use mutation operators without providing a mutationFn in the collection config`
+      )
+    }
+
     if (typeof items === `undefined`) {
       throw new Error(`The first argument to update is missing`)
     }
@@ -702,6 +716,7 @@ export class Collection<T extends object = Record<string, unknown>> {
    * @param items - Single item/key or array of items/keys to delete
    * @param config - Optional configuration including metadata
    * @returns A Transaction object representing the delete operation(s)
+   * @throws {Error} If mutationFn is not provided
    * @example
    * // Delete a single item
    * delete(todo)
@@ -716,6 +731,13 @@ export class Collection<T extends object = Record<string, unknown>> {
     items: Array<T | string> | T | string,
     config?: OperationConfig
   ) => {
+    // Throw error if mutationFn is not provided
+    if (!this.config.mutationFn) {
+      throw new Error(
+        `Cannot use mutation operators without providing a mutationFn in the collection config`
+      )
+    }
+
     const itemsArray = Array.isArray(items) ? items : [items]
     const mutations: Array<PendingMutation> = []
 

packages/optimistic/src/types.ts

@@ -138,6 +138,6 @@ export interface InsertConfig {
 export interface CollectionConfig<T extends object = Record<string, unknown>> {
   id: string
   sync: SyncConfig<T>
-  mutationFn: MutationFn<T>
+  mutationFn?: MutationFn<T>
   schema?: StandardSchema<T>
 }

packages/optimistic/tests/collection.test.ts

@@ -10,15 +10,63 @@ describe(`Collection`, () => {
     expect(() => new Collection()).toThrow(`Collection requires a sync config`)
   })
 
-  it(`should throw if there's no mutationFn`, () => {
-    expect(
-      () =>
-        // @ts-expect-error mutationFn is supposed to be missing.
-        new Collection({
-          id: `foo`,
-          sync: { sync: async () => {} },
-        })
-    ).toThrow(`Collection requires a mutationFn`)
+  it(`should allow creating a collection without a mutationFn`, () => {
+    // This should not throw an error
+    const collection = new Collection({
+      id: `foo`,
+      sync: { sync: async () => {} },
+    })
+
+    // Verify that the collection was created successfully
+    expect(collection).toBeInstanceOf(Collection)
+  })
+
+  it(`should throw an error when trying to use mutation operations without a mutationFn`, async () => {
+    // Create a collection with sync but no mutationFn
+    const collection = new Collection<{ value: string }>({
+      id: `no-mutation-fn`,
+      sync: {
+        sync: ({ begin, write, commit }) => {
+          // Immediately execute the sync cycle
+          begin()
+          write({
+            type: `insert`,
+            key: `initial`,
+            value: { value: `initial value` },
+          })
+          commit()
+        },
+      },
+    })
+
+    // Wait for the collection to be ready
+    await collection.stateWhenReady()
+
+    // Verify initial state
+    expect(collection.state.get(`initial`)).toEqual({ value: `initial value` })
+
+    // Verify that insert throws an error
+    expect(() => {
+      collection.insert({ value: `new value` }, { key: `new-key` })
+    }).toThrow(
+      `Cannot use mutation operators without providing a mutationFn in the collection config`
+    )
+
+    // Verify that update throws an error
+    expect(() => {
+      collection.update(collection.state.get(`initial`)!, (draft) => {
+        draft.value = `updated value`
+      })
+    }).toThrow(
+      `Cannot use mutation operators without providing a mutationFn in the collection config`
+    )
+
+    // Verify that delete throws an error
+    expect(() => {
+      collection.delete(`initial`)
+    }).toThrow(
+      `Cannot use mutation operators without providing a mutationFn in the collection config`
+    )
   })
 
   it(`It shouldn't expose any state until the initial sync is finished`, () => {
@@ -333,20 +381,6 @@ describe(`Collection`, () => {
     expect(collection.state).toEqual(new Map([[`foo`, { value: `bar` }]]))
   })
 
-  // Skip until e2e working
-  it(`If the mutationFn throws error, it get retried`, () => {
-    // new collection w/ mock sync/mutation
-    // insert
-    // mutationFn fails the first time and then succeeds
-  })
-
-  // Skip until e2e working
-  it(`If the mutationFn throws NonRetriableError, it doesn't get retried and optimistic state is rolled back`, () => {
-    // new collection w/ mock sync/mutation
-    // insert
-    // mutationFn fails w/ NonRetriableError and the check that optimistic state is rolledback.
-  })
-
   it(`should handle sparse key arrays for bulk inserts`, () => {
     const collection = new Collection<{ value: string }>({
       id: `test`,

packages/react-optimistic/src/useCollection.ts

@@ -152,6 +152,7 @@ export function useCollection<T extends object>(
    * @param maybeCallback - Callback function if config was provided
    * @returns {Transaction} A Transaction object representing the update operation
    * @throws {SchemaValidationError} If the updated data fails schema validation
+   * @throws {Error} If mutationFn is not provided in the collection config
    * @example
    * // Update a single item
    * update(todo, (draft) => { draft.completed = true })
@@ -173,6 +174,7 @@ export function useCollection<T extends object>(
    * @returns {Transaction} A Transaction object representing the insert operation
    * @throws {SchemaValidationError} If the data fails schema validation
    * @throws {Error} If more keys provided than items to insert
+   * @throws {Error} If mutationFn is not provided in the collection config
    * @example
    * // Insert a single item
    * insert({ text: "Buy groceries", completed: false })
@@ -193,6 +195,7 @@ export function useCollection<T extends object>(
    * @param items - Item(s) to delete (must exist in collection) or their key(s)
    * @param config - Optional configuration including metadata
    * @returns {Transaction} A Transaction object representing the delete operation
+   * @throws {Error} If mutationFn is not provided in the collection config
    * @example
    * // Delete a single item
    * delete(todo)
@@ -228,6 +231,7 @@ export function useCollection<T extends object, R>(
    * @param maybeCallback - Callback function if config was provided
    * @returns {Transaction} A Transaction object representing the update operation
    * @throws {SchemaValidationError} If the updated data fails schema validation
+   * @throws {Error} If mutationFn is not provided in the collection config
    * @example
    * // Update a single item
    * update(todo, (draft) => { draft.completed = true })
@@ -249,6 +253,7 @@ export function useCollection<T extends object, R>(
    * @returns {Transaction} A Transaction object representing the insert operation
    * @throws {SchemaValidationError} If the data fails schema validation
    * @throws {Error} If more keys provided than items to insert
+   * @throws {Error} If mutationFn is not provided in the collection config
    * @example
    * // Insert a single item
    * insert({ text: "Buy groceries", completed: false })
@@ -269,6 +274,7 @@ export function useCollection<T extends object, R>(
    * @param items - Item(s) to delete (must exist in collection) or their key(s)
    * @param config - Optional configuration including metadata
    * @returns {Transaction} A Transaction object representing the delete operation
+   * @throws {Error} If mutationFn is not provided in the collection config
    * @example
    * // Delete a single item
    * delete(todo)