@tanstack/angular-query-experimental 5.103.2 → 5.104.0

package/src/__tests__/inject-mutation.test.ts

@@ -0,0 +1,1161 @@
+import {
+  ApplicationRef,
+  Component,
+  Injector,
+  input,
+  provideZonelessChangeDetection,
+  signal,
+} from '@angular/core'
+import { TestBed } from '@angular/core/testing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { By } from '@angular/platform-browser'
+import { render } from '@testing-library/angular'
+import { queryKey, sleep } from '@tanstack/query-test-utils'
+import { noop } from '@tanstack/query-core'
+import { QueryClient, injectMutation, provideTanStackQuery } from '..'
+import { expectSignals, setFixtureSignalInputs } from './test-utils'
+
+describe('injectMutation', () => {
+  let queryClient: QueryClient
+
+  beforeEach(() => {
+    queryClient = new QueryClient()
+    vi.useFakeTimers()
+    TestBed.configureTestingModule({
+      providers: [
+        provideZonelessChangeDetection(),
+        provideTanStackQuery(queryClient),
+      ],
+    })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('should be in idle state initially', () => {
+    const mutation = TestBed.runInInjectionContext(() => {
+      return injectMutation(() => ({
+        mutationFn: (params) => sleep(0).then(() => params),
+      }))
+    })
+
+    expectSignals(mutation, {
+      isIdle: true,
+      isPending: false,
+      isError: false,
+      isSuccess: false,
+    })
+  })
+
+  it('should change state after invoking mutate', async () => {
+    const result = 'Mock data'
+
+    @Component({
+      template: `
+        <div>isIdle: {{ mutation.isIdle() }}</div>
+        <div>isPending: {{ mutation.isPending() }}</div>
+        <div>isError: {{ mutation.isError() }}</div>
+        <div>isSuccess: {{ mutation.isSuccess() }}</div>
+        <div>data: {{ mutation.data() ?? 'none' }}</div>
+        <div>error: {{ mutation.error()?.message ?? 'none' }}</div>
+      `,
+    })
+    class Page {
+      readonly mutation = injectMutation(() => ({
+        mutationFn: (params: string) => sleep(10).then(() => params),
+      }))
+    }
+
+    const rendered = await render(Page)
+
+    rendered.fixture.componentInstance.mutation.mutate(result)
+    await vi.advanceTimersByTimeAsync(0)
+    rendered.fixture.detectChanges()
+
+    expect(rendered.getByText('isIdle: false')).toBeInTheDocument()
+    expect(rendered.getByText('isPending: true')).toBeInTheDocument()
+    expect(rendered.getByText('isError: false')).toBeInTheDocument()
+    expect(rendered.getByText('isSuccess: false')).toBeInTheDocument()
+    expect(rendered.getByText('data: none')).toBeInTheDocument()
+    expect(rendered.getByText('error: none')).toBeInTheDocument()
+  })
+
+  it('should return error when request fails', async () => {
+    @Component({
+      template: `
+        <div>isIdle: {{ mutation.isIdle() }}</div>
+        <div>isPending: {{ mutation.isPending() }}</div>
+        <div>isError: {{ mutation.isError() }}</div>
+        <div>isSuccess: {{ mutation.isSuccess() }}</div>
+        <div>data: {{ mutation.data() ?? 'none' }}</div>
+        <div>error: {{ mutation.error()?.message ?? 'none' }}</div>
+      `,
+    })
+    class Page {
+      readonly mutation = injectMutation(() => ({
+        mutationFn: () =>
+          sleep(10).then(() => Promise.reject(new Error('Some error'))),
+      }))
+    }
+
+    const rendered = await render(Page)
+
+    rendered.fixture.componentInstance.mutation.mutate()
+
+    await vi.advanceTimersByTimeAsync(11)
+    rendered.fixture.detectChanges()
+
+    expect(rendered.getByText('isIdle: false')).toBeInTheDocument()
+    expect(rendered.getByText('isPending: false')).toBeInTheDocument()
+    expect(rendered.getByText('isError: true')).toBeInTheDocument()
+    expect(rendered.getByText('isSuccess: false')).toBeInTheDocument()
+    expect(rendered.getByText('data: none')).toBeInTheDocument()
+    expect(rendered.getByText('error: Some error')).toBeInTheDocument()
+  })
+
+  it('should return data when request succeeds', async () => {
+    const result = 'Mock data'
+
+    @Component({
+      template: `
+        <div>isIdle: {{ mutation.isIdle() }}</div>
+        <div>isPending: {{ mutation.isPending() }}</div>
+        <div>isError: {{ mutation.isError() }}</div>
+        <div>isSuccess: {{ mutation.isSuccess() }}</div>
+        <div>data: {{ mutation.data() ?? 'none' }}</div>
+        <div>error: {{ mutation.error()?.message ?? 'none' }}</div>
+      `,
+    })
+    class Page {
+      readonly mutation = injectMutation(() => ({
+        mutationFn: (params: string) => sleep(10).then(() => params),
+      }))
+    }
+
+    const rendered = await render(Page)
+
+    rendered.fixture.componentInstance.mutation.mutate(result)
+
+    await vi.advanceTimersByTimeAsync(11)
+    rendered.fixture.detectChanges()
+
+    expect(rendered.getByText('isIdle: false')).toBeInTheDocument()
+    expect(rendered.getByText('isPending: false')).toBeInTheDocument()
+    expect(rendered.getByText('isError: false')).toBeInTheDocument()
+    expect(rendered.getByText('isSuccess: true')).toBeInTheDocument()
+    expect(rendered.getByText(`data: ${result}`)).toBeInTheDocument()
+    expect(rendered.getByText('error: none')).toBeInTheDocument()
+  })
+
+  it('should update mutation when reactive options change', () => {
+    const mutationCache = queryClient.getMutationCache()
+    // Signal will be updated before the mutation is called
+    // this test confirms that the mutation uses the updated value
+    const key1 = queryKey()
+    const key2 = queryKey()
+    const mutationKey = signal(key1)
+    const mutation = TestBed.runInInjectionContext(() => {
+      return injectMutation(() => ({
+        mutationKey: mutationKey(),
+        mutationFn: (params: string) => sleep(0).then(() => params),
+      }))
+    })
+
+    mutationKey.set(key2)
+
+    mutation.mutate('xyz')
+
+    const mutations = mutationCache.find({ mutationKey: key2 })
+
+    expect(mutations?.options.mutationKey).toEqual(key2)
+  })
+
+  it('should reset state after invoking mutation.reset', async () => {
+    @Component({
+      template: `
+        <div>isIdle: {{ mutation.isIdle() }}</div>
+        <div>isPending: {{ mutation.isPending() }}</div>
+        <div>isError: {{ mutation.isError() }}</div>
+        <div>isSuccess: {{ mutation.isSuccess() }}</div>
+        <div>data: {{ mutation.data() ?? 'none' }}</div>
+        <div>error: {{ mutation.error()?.message ?? 'none' }}</div>
+      `,
+    })
+    class Page {
+      readonly mutation = injectMutation(() => ({
+        mutationFn: () =>
+          sleep(10).then(() => Promise.reject(new Error('Some error'))),
+      }))
+    }
+
+    const rendered = await render(Page)
+
+    rendered.fixture.componentInstance.mutation.mutate()
+
+    await vi.advanceTimersByTimeAsync(11)
+    rendered.fixture.detectChanges()
+
+    expect(rendered.getByText('isError: true')).toBeInTheDocument()
+    expect(rendered.getByText('error: Some error')).toBeInTheDocument()
+
+    rendered.fixture.componentInstance.mutation.reset()
+
+    await vi.advanceTimersByTimeAsync(0)
+    rendered.fixture.detectChanges()
+
+    expect(rendered.getByText('isIdle: true')).toBeInTheDocument()
+    expect(rendered.getByText('isPending: false')).toBeInTheDocument()
+    expect(rendered.getByText('isError: false')).toBeInTheDocument()
+    expect(rendered.getByText('isSuccess: false')).toBeInTheDocument()
+    expect(rendered.getByText('data: none')).toBeInTheDocument()
+    expect(rendered.getByText('error: none')).toBeInTheDocument()
+  })
+
+  describe('side effects', () => {
+    beforeEach(() => {
+      vi.clearAllMocks()
+    })
+
+    it('should call onMutate when passed as an option', async () => {
+      const onMutate = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+          onMutate,
+        }))
+      })
+
+      mutation.mutate('')
+
+      await vi.advanceTimersByTimeAsync(0)
+
+      expect(onMutate).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onError when passed as an option', async () => {
+      const onError = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (_params: string) =>
+            sleep(10).then(() => Promise.reject(new Error('Some error'))),
+          onError,
+        }))
+      })
+
+      mutation.mutate('')
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onError).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onSuccess when passed as an option', async () => {
+      const onSuccess = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+          onSuccess,
+        }))
+      })
+
+      mutation.mutate('')
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onSettled when passed as an option', async () => {
+      const onSettled = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+          onSettled,
+        }))
+      })
+
+      mutation.mutate('')
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSettled).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onError when passed as an argument of mutate function', async () => {
+      const onError = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (_params: string) =>
+            sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        }))
+      })
+
+      mutation.mutate('', { onError })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onError).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onSuccess when passed as an argument of mutate function', async () => {
+      const onSuccess = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+        }))
+      })
+
+      mutation.mutate('', { onSuccess })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onSettled when passed as an argument of mutate function', async () => {
+      const onSettled = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+        }))
+      })
+
+      mutation.mutate('', { onSettled })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSettled).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onSuccess and onSettled when passed as arguments of mutate function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+        }))
+      })
+
+      mutation.mutate('', {
+        onSuccess: () => callbacks.push('mutate.onSuccess'),
+        onSettled: () => callbacks.push('mutate.onSettled'),
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual(['mutate.onSuccess', 'mutate.onSettled'])
+    })
+
+    it('should call onError and onSettled when passed as arguments of mutate function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (_params: string) =>
+            sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        }))
+      })
+
+      mutation.mutate('', {
+        onError: () => callbacks.push('mutate.onError'),
+        onSettled: () => callbacks.push('mutate.onSettled'),
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual(['mutate.onError', 'mutate.onSettled'])
+    })
+
+    it('should call onSuccess and onSettled when passed as arguments of mutateAsync function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+        }))
+      })
+
+      mutation.mutateAsync('', {
+        onSuccess: () => callbacks.push('mutateAsync.onSuccess'),
+        onSettled: () => callbacks.push('mutateAsync.onSettled'),
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual([
+        'mutateAsync.onSuccess',
+        'mutateAsync.onSettled',
+      ])
+    })
+
+    it('should call onError and onSettled when passed as arguments of mutateAsync function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (_params: string) =>
+            sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        }))
+      })
+
+      mutation
+        .mutateAsync('', {
+          onError: () => callbacks.push('mutateAsync.onError'),
+          onSettled: () => callbacks.push('mutateAsync.onSettled'),
+        })
+        .catch(noop)
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual([
+        'mutateAsync.onError',
+        'mutateAsync.onSettled',
+      ])
+    })
+
+    it('should call onSuccess when passed as an argument of mutateAsync function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+        }))
+      })
+
+      mutation.mutateAsync('', {
+        onSuccess: () => callbacks.push('mutateAsync.onSuccess'),
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual(['mutateAsync.onSuccess'])
+    })
+
+    it('should call onError when passed as an argument of mutateAsync function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (_params: string) =>
+            sleep(10).then(() => Promise.reject(new Error('Some error'))),
+        }))
+      })
+
+      mutation
+        .mutateAsync('', {
+          onError: () => callbacks.push('mutateAsync.onError'),
+        })
+        .catch(noop)
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual(['mutateAsync.onError'])
+    })
+
+    it('should call onSettled when passed as an argument of mutateAsync function', async () => {
+      const callbacks: Array<string> = []
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+        }))
+      })
+
+      mutation.mutateAsync('', {
+        onSettled: () => callbacks.push('mutateAsync.onSettled'),
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(callbacks).toEqual(['mutateAsync.onSettled'])
+    })
+
+    it('should fire both onSettled functions', async () => {
+      const onSettled = vi.fn()
+      const onSettledMutate = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (params: string) => sleep(10).then(() => params),
+          onSettled,
+        }))
+      })
+
+      mutation.mutate('', { onSettled: onSettledMutate })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSettled).toHaveBeenCalledTimes(1)
+      expect(onSettledMutate).toHaveBeenCalledTimes(1)
+    })
+
+    it('should pass a non-undefined onMutateResult alongside context to onSuccess', async () => {
+      const onSuccess = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (text: string) =>
+            sleep(10).then(() => text.toUpperCase()),
+          onMutate: (text: string) => ({ startedWith: text }),
+          onSuccess,
+        }))
+      })
+
+      mutation.mutate('todo')
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+      const [data, variables, onMutateResult, context] =
+        onSuccess.mock.calls[0]!
+      expect(data).toBe('TODO')
+      expect(variables).toBe('todo')
+      expect(onMutateResult).toEqual({ startedWith: 'todo' })
+      expect(context.client).toBe(queryClient)
+      expect(context.meta).toBeUndefined()
+      expect(context.mutationKey).toBeUndefined()
+    })
+
+    it('should give mutationFn the same QueryClient instance via context', async () => {
+      const key = queryKey()
+      queryClient.setQueryData(key, 'tag-from-this-client')
+
+      @Component({
+        template: `<div>data: {{ mutation.data() ?? 'none' }}</div>`,
+      })
+      class Page {
+        readonly mutation = injectMutation(() => ({
+          mutationFn: (_text: string, context) =>
+            sleep(10).then(() => context.client.getQueryData(key)),
+        }))
+      }
+
+      const rendered = await render(Page)
+
+      rendered.fixture.componentInstance.mutation.mutate('todo')
+
+      await vi.advanceTimersByTimeAsync(11)
+      rendered.fixture.detectChanges()
+
+      expect(
+        rendered.getByText('data: tag-from-this-client'),
+      ).toBeInTheDocument()
+    })
+
+    it('should include mutationKey in the context passed to hook-level callbacks', async () => {
+      const onSuccess = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationKey: ['todos', 'add'],
+          mutationFn: (text: string) => sleep(10).then(() => text),
+          onSuccess,
+        }))
+      })
+
+      mutation.mutate('todo')
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+      expect(onSuccess.mock.calls[0]?.[3].mutationKey).toEqual(['todos', 'add'])
+    })
+
+    it('should let onSuccess invalidate queries via context.client without an injected QueryClient', async () => {
+      const key = queryKey()
+      queryClient.setQueryData(key, 'data')
+
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: () => sleep(10).then(() => 'mutated'),
+          onSuccess: (_data, _variables, _onMutateResult, context) => {
+            context.client.invalidateQueries({ queryKey: key })
+          },
+        }))
+      })
+
+      expect(queryClient.getQueryState(key)?.isInvalidated).toBe(false)
+
+      mutation.mutate()
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(queryClient.getQueryState(key)?.isInvalidated).toBe(true)
+    })
+
+    it('should give a per-call onSuccess the same QueryClient instance via context', async () => {
+      const onSuccessMutate = vi.fn()
+      const mutation = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationFn: (text: string) => sleep(10).then(() => text),
+        }))
+      })
+
+      mutation.mutate('todo', { onSuccess: onSuccessMutate })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(onSuccessMutate).toHaveBeenCalledTimes(1)
+      expect(onSuccessMutate.mock.calls[0]?.[3].client).toBe(queryClient)
+    })
+  })
+
+  it('should support required signal inputs', async () => {
+    const mutationCache = queryClient.getMutationCache()
+
+    @Component({
+      selector: 'app-fake',
+      template: `
+        <button (click)="mutate()"></button>
+        <span>{{ mutation.data() }}</span>
+      `,
+    })
+    class FakeComponent {
+      name = input.required<string>()
+
+      mutation = injectMutation(() => ({
+        mutationKey: ['fake', this.name()],
+        mutationFn: () => sleep(10).then(() => this.name()),
+      }))
+
+      mutate(): void {
+        this.mutation.mutate()
+      }
+    }
+
+    const fixture = TestBed.createComponent(FakeComponent)
+    const { debugElement } = fixture
+    setFixtureSignalInputs(fixture, { name: 'value' })
+
+    const button = debugElement.query(By.css('button'))
+    button.triggerEventHandler('click')
+
+    await vi.advanceTimersByTimeAsync(11)
+    fixture.detectChanges()
+
+    const text = debugElement.query(By.css('span')).nativeElement.textContent
+    expect(text).toEqual('value')
+    const mutation = mutationCache.find({ mutationKey: ['fake', 'value'] })
+    expect(mutation?.options.mutationKey).toStrictEqual(['fake', 'value'])
+  })
+
+  it('should update options on required signal input change', async () => {
+    const mutationCache = queryClient.getMutationCache()
+
+    @Component({
+      selector: 'app-fake',
+      template: `
+        <button (click)="mutate()"></button>
+        <span>{{ mutation.data() }}</span>
+      `,
+    })
+    class FakeComponent {
+      name = input.required<string>()
+
+      mutation = injectMutation(() => ({
+        mutationKey: ['fake', this.name()],
+        mutationFn: () => sleep(10).then(() => this.name()),
+      }))
+
+      mutate(): void {
+        this.mutation.mutate()
+      }
+    }
+
+    const fixture = TestBed.createComponent(FakeComponent)
+    const { debugElement } = fixture
+    setFixtureSignalInputs(fixture, { name: 'value' })
+
+    const button = debugElement.query(By.css('button'))
+    const span = debugElement.query(By.css('span'))
+
+    button.triggerEventHandler('click')
+    await vi.advanceTimersByTimeAsync(11)
+    fixture.detectChanges()
+
+    expect(span.nativeElement.textContent).toEqual('value')
+
+    setFixtureSignalInputs(fixture, { name: 'updatedValue' })
+
+    button.triggerEventHandler('click')
+    await vi.advanceTimersByTimeAsync(11)
+    fixture.detectChanges()
+
+    expect(span.nativeElement.textContent).toEqual('updatedValue')
+
+    const mutations = mutationCache.findAll()
+    expect(mutations.length).toBe(2)
+    const [mutation1, mutation2] = mutations
+    expect(mutation1!.options.mutationKey).toEqual(['fake', 'value'])
+    expect(mutation2!.options.mutationKey).toEqual(['fake', 'updatedValue'])
+  })
+
+  describe('throwOnError', () => {
+    it('should evaluate throwOnError when mutation is expected to throw', async () => {
+      const key = queryKey()
+      const err = new Error('Expected mock error. All is well!')
+      const throwOnError = vi.fn()
+      const { mutate } = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: () => {
+            return Promise.reject(err)
+          },
+          throwOnError,
+        }))
+      })
+
+      TestBed.tick()
+
+      mutate()
+
+      await vi.advanceTimersByTimeAsync(0)
+
+      expect(throwOnError).toHaveBeenCalledTimes(1)
+      expect(throwOnError).toHaveBeenCalledWith(err)
+    })
+
+    it('should throw when throwOnError is true and mutate is used', async () => {
+      const key = queryKey()
+      const { mutate } = TestBed.runInInjectionContext(() => {
+        return injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: () => {
+            return Promise.reject(
+              new Error('Expected mock error. All is well!'),
+            )
+          },
+          throwOnError: true,
+        }))
+      })
+
+      TestBed.tick()
+
+      mutate()
+
+      await expect(vi.advanceTimersByTimeAsync(0)).rejects.toThrow(
+        'Expected mock error. All is well!',
+      )
+    })
+  })
+
+  it('should throw when throwOnError is true', async () => {
+    const key = queryKey()
+    const err = new Error('Expected mock error. All is well!')
+    const { mutateAsync } = TestBed.runInInjectionContext(() => {
+      return injectMutation(() => ({
+        mutationKey: key,
+        mutationFn: () => {
+          return Promise.reject(err)
+        },
+        throwOnError: true,
+      }))
+    })
+
+    await expect(() => mutateAsync()).rejects.toThrow(err)
+  })
+
+  it('should throw when throwOnError function returns true', async () => {
+    const key = queryKey()
+    const err = new Error('Expected mock error. All is well!')
+    const { mutateAsync } = TestBed.runInInjectionContext(() => {
+      return injectMutation(() => ({
+        mutationKey: key,
+        mutationFn: () => {
+          return Promise.reject(err)
+        },
+        throwOnError: () => true,
+      }))
+    })
+
+    await expect(() => mutateAsync()).rejects.toThrow(err)
+  })
+
+  it('should resolve mutateAsync with the value returned from mutationFn', async () => {
+    const key = queryKey()
+    const { mutateAsync } = TestBed.runInInjectionContext(() => {
+      return injectMutation(() => ({
+        mutationKey: key,
+        mutationFn: (params: string) => sleep(10).then(() => params),
+      }))
+    })
+
+    const promise = mutateAsync('Mock data')
+    await vi.advanceTimersByTimeAsync(10)
+
+    await expect(promise).resolves.toBe('Mock data')
+  })
+
+  describe('injection context', () => {
+    it('should throw NG0203 with descriptive error outside injection context', () => {
+      const key = queryKey()
+      expect(() => {
+        injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: () => Promise.resolve(),
+        }))
+      }).toThrow(/NG0203(.*?)injectMutation/)
+    })
+
+    it('should be usable outside injection context when passing an injector', () => {
+      const key = queryKey()
+      expect(() => {
+        injectMutation(
+          () => ({
+            mutationKey: key,
+            mutationFn: () => Promise.resolve(),
+          }),
+          {
+            injector: TestBed.inject(Injector),
+          },
+        )
+      }).not.toThrow()
+    })
+
+    it('should complete mutation before whenStable() resolves', async () => {
+      const app = TestBed.inject(ApplicationRef)
+      let mutationStarted = false
+      let mutationCompleted = false
+
+      const key = queryKey()
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: async (data: string) => {
+            mutationStarted = true
+            await sleep(50)
+            mutationCompleted = true
+            return `processed: ${data}`
+          },
+        })),
+      )
+
+      // Initial state
+      expect(mutation.data()).toBeUndefined()
+      expect(mutationStarted).toBe(false)
+
+      // Start mutation
+      mutation.mutate('test')
+
+      // Wait for mutation to start and Angular to be "stable"
+      const stablePromise = app.whenStable()
+      await vi.advanceTimersByTimeAsync(60)
+      await stablePromise
+
+      // After whenStable(), mutation should be complete
+      expect(mutationStarted).toBe(true)
+      expect(mutationCompleted).toBe(true)
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('processed: test')
+    })
+
+    it('should handle synchronous mutation with retry', async () => {
+      const app = TestBed.inject(ApplicationRef)
+      let attemptCount = 0
+
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          retry: 2,
+          retryDelay: 0, // No delay for synchronous retry
+          mutationFn: async (data: string) => {
+            attemptCount++
+            if (attemptCount <= 2) {
+              throw new Error(`Sync attempt ${attemptCount} failed`)
+            }
+            return `processed: ${data}`
+          },
+        })),
+      )
+
+      // Start mutation
+      mutation.mutate('retry-test')
+
+      // Synchronize pending effects for each retry attempt
+      TestBed.tick()
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+
+      TestBed.tick()
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(10)
+      await stablePromise
+
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('processed: retry-test')
+      expect(attemptCount).toBe(3) // Initial + 2 retries
+    })
+
+    it('should handle multiple synchronous mutations on same key', async () => {
+      const app = TestBed.inject(ApplicationRef)
+      let callCount = 0
+
+      const key = queryKey()
+
+      const mutation1 = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: async (data: string) => {
+            callCount++
+            return `mutation1: ${data}`
+          },
+        })),
+      )
+
+      const mutation2 = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: async (data: string) => {
+            callCount++
+            return `mutation2: ${data}`
+          },
+        })),
+      )
+
+      // Start both mutations
+      mutation1.mutate('test1')
+      mutation2.mutate('test2')
+
+      // Synchronize pending effects
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      // Flush microtasks to allow TanStack Query's scheduled notifications to process
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(1)
+      await stablePromise
+
+      expect(mutation1.isSuccess()).toBe(true)
+      expect(mutation1.data()).toBe('mutation1: test1')
+      expect(mutation2.isSuccess()).toBe(true)
+      expect(mutation2.data()).toBe('mutation2: test2')
+      expect(callCount).toBe(2)
+    })
+
+    it('should handle synchronous mutation with optimistic updates', async () => {
+      const app = TestBed.inject(ApplicationRef)
+      const testQueryKey = queryKey()
+      let onMutateCalled = false
+      let onSuccessCalled = false
+
+      // Set initial data
+      queryClient.setQueryData(testQueryKey, 'initial')
+
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationFn: async (data: string) => `final: ${data}`, // Synchronous resolution
+          onMutate: async (variables) => {
+            onMutateCalled = true
+            const previousData = queryClient.getQueryData(testQueryKey)
+            queryClient.setQueryData(testQueryKey, `optimistic: ${variables}`)
+            return { previousData }
+          },
+          onSuccess: (data) => {
+            onSuccessCalled = true
+            queryClient.setQueryData(testQueryKey, data)
+          },
+        })),
+      )
+
+      // Start mutation
+      mutation.mutate('test')
+
+      // Synchronize pending effects
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      // Flush microtasks to allow TanStack Query's scheduled notifications to process
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(1)
+      await stablePromise
+
+      expect(onMutateCalled).toBe(true)
+      expect(onSuccessCalled).toBe(true)
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('final: test')
+      expect(queryClient.getQueryData(testQueryKey)).toBe('final: test')
+    })
+
+    it('should handle synchronous mutation cancellation', async () => {
+      const app = TestBed.inject(ApplicationRef)
+
+      const key = queryKey()
+      const mutation = TestBed.runInInjectionContext(() =>
+        injectMutation(() => ({
+          mutationKey: key,
+          mutationFn: async (data: string) => `processed: ${data}`, // Synchronous resolution
+        })),
+      )
+
+      // Start mutation
+      mutation.mutate('test')
+
+      // Synchronize pending effects
+      TestBed.tick()
+
+      const stablePromise = app.whenStable()
+      // Flush microtasks to allow TanStack Query's scheduled notifications to process
+      await Promise.resolve()
+      await vi.advanceTimersByTimeAsync(1)
+      await stablePromise
+
+      // Synchronous mutations complete immediately
+      expect(mutation.isSuccess()).toBe(true)
+      expect(mutation.data()).toBe('processed: test')
+    })
+  })
+
+  describe('optimistic updates', () => {
+    it('should update the cache in onMutate and roll back via onMutateResult in onError', async () => {
+      const key = queryKey()
+      queryClient.setQueryData<Array<string>>(key, ['Todo 1'])
+
+      @Component({
+        template: `<div>isError: {{ mutation.isError() }}</div>`,
+      })
+      class Page {
+        readonly mutation = injectMutation(() => ({
+          mutationFn: () =>
+            sleep(10).then(() => Promise.reject(new Error('Some error'))),
+          onMutate: async (newTodo: string) => {
+            await queryClient.cancelQueries({ queryKey: key })
+            const previousTodos = queryClient.getQueryData<Array<string>>(key)
+
+            queryClient.setQueryData<Array<string>>(key, (old) => [
+              ...(old ?? []),
+              newTodo,
+            ])
+
+            return { previousTodos }
+          },
+          onError: (_err, _newTodo, onMutateResult) => {
+            queryClient.setQueryData(key, onMutateResult?.previousTodos)
+          },
+        }))
+      }
+
+      const rendered = await render(Page)
+
+      rendered.fixture.componentInstance.mutation.mutate('Todo 2')
+      // onMutate runs synchronously up to its first await, so the optimistic
+      // value is visible immediately, before the mutationFn settles.
+      await vi.advanceTimersByTimeAsync(0)
+
+      expect(queryClient.getQueryData(key)).toEqual(['Todo 1', 'Todo 2'])
+
+      await vi.advanceTimersByTimeAsync(11)
+      rendered.fixture.detectChanges()
+
+      expect(rendered.getByText('isError: true')).toBeInTheDocument()
+      expect(queryClient.getQueryData(key)).toEqual(['Todo 1'])
+    })
+
+    it('should keep the optimistic update in place when the mutation succeeds', async () => {
+      const key = queryKey()
+      queryClient.setQueryData<Array<string>>(key, ['Todo 1'])
+
+      @Component({
+        template: `<div>isSuccess: {{ mutation.isSuccess() }}</div>`,
+      })
+      class Page {
+        readonly mutation = injectMutation(() => ({
+          mutationFn: (newTodo: string) => sleep(10).then(() => newTodo),
+          onMutate: async (newTodo: string) => {
+            await queryClient.cancelQueries({ queryKey: key })
+            const previousTodos = queryClient.getQueryData<Array<string>>(key)
+
+            queryClient.setQueryData<Array<string>>(key, (old) => [
+              ...(old ?? []),
+              newTodo,
+            ])
+
+            return { previousTodos }
+          },
+          onError: (_err, _newTodo, onMutateResult) => {
+            queryClient.setQueryData(key, onMutateResult?.previousTodos)
+          },
+        }))
+      }
+
+      const rendered = await render(Page)
+
+      rendered.fixture.componentInstance.mutation.mutate('Todo 2')
+      await vi.advanceTimersByTimeAsync(11)
+      rendered.fixture.detectChanges()
+
+      expect(rendered.getByText('isSuccess: true')).toBeInTheDocument()
+      expect(queryClient.getQueryData(key)).toEqual(['Todo 1', 'Todo 2'])
+    })
+  })
+
+  describe('concurrent mutate calls', () => {
+    it('should report each mutateAsync call result independently when some fail', async () => {
+      @Component({
+        template: `<div>isPending: {{ mutation.isPending() }}</div>`,
+      })
+      class Page {
+        readonly mutation = injectMutation(() => ({
+          mutationFn: (todo: string) =>
+            todo === 'bad'
+              ? sleep(10).then(() => Promise.reject(new Error('Some error')))
+              : sleep(10).then(() => todo),
+        }))
+      }
+
+      const rendered = await render(Page)
+      const todos = ['Todo 1', 'bad', 'Todo 3']
+
+      expect(rendered.getByText('isPending: false')).toBeInTheDocument()
+
+      const settledPromise = Promise.allSettled(
+        todos.map((todo) =>
+          rendered.fixture.componentInstance.mutation.mutateAsync(todo),
+        ),
+      )
+      await vi.advanceTimersByTimeAsync(0)
+      rendered.fixture.detectChanges()
+
+      expect(rendered.getByText('isPending: true')).toBeInTheDocument()
+
+      await vi.advanceTimersByTimeAsync(11)
+      rendered.fixture.detectChanges()
+      const results = await settledPromise
+
+      expect(results).toEqual([
+        { status: 'fulfilled', value: 'Todo 1' },
+        { status: 'rejected', reason: Error('Some error') },
+        { status: 'fulfilled', value: 'Todo 3' },
+      ])
+      expect(rendered.getByText('isPending: false')).toBeInTheDocument()
+    })
+
+    it('should only fire the per-call onSuccess for the last mutate() call', async () => {
+      const onSuccessMutate = vi.fn()
+
+      @Component({
+        template: `<div>data: {{ mutation.data() ?? 'none' }}</div>`,
+      })
+      class Page {
+        readonly mutation = injectMutation(() => ({
+          mutationFn: (todo: string) => sleep(10).then(() => todo),
+        }))
+      }
+
+      const rendered = await render(Page)
+
+      rendered.fixture.componentInstance.mutation.mutate('Todo 1', {
+        onSuccess: onSuccessMutate,
+      })
+      rendered.fixture.componentInstance.mutation.mutate('Todo 2', {
+        onSuccess: onSuccessMutate,
+      })
+      await vi.advanceTimersByTimeAsync(11)
+      rendered.fixture.detectChanges()
+
+      expect(onSuccessMutate).toHaveBeenCalledTimes(1)
+      expect(onSuccessMutate).toHaveBeenCalledWith(
+        'Todo 2',
+        'Todo 2',
+        undefined,
+        expect.anything(),
+      )
+      expect(rendered.getByText('data: Todo 2')).toBeInTheDocument()
+    })
+  })
+})