fix(adapters): use latest onUnmount callback during cleanup

[gwagjiug]

🎯 Changes

This PR fixes a stale cleanup callback issue in adapter hooks that support onUnmount.

Before this change, these hooks registered an unmount cleanup with an empty dependency array and read mergedOptions.onUnmount directly inside that cleanup. That meant the cleanup closed over the value from the first render. If a consumer re-rendered with a new onUnmount callback, the hook could still call the old callback during unmount.

This change keeps the existing "register cleanup once" behavior, but makes the cleanup read the latest onUnmount callback instead of the initial one.

Updated hooks:

• packages/react-pacer/src/debouncer/useDebouncer.ts
• packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts
• packages/react-pacer/src/rate-limiter/useRateLimiter.ts
• packages/preact-pacer/src/debouncer/useDebouncer.ts

Why this approach

I wanted to keep this fix as small and low-risk as possible.

I considered whether the previous behavior might have been intentional, since the cleanup effect is deliberately registered with [] to keep teardown stable. However, the rest of these hooks already update runtime behavior from the latest render by reassigning fn and calling setOptions(mergedOptions) on each render. Given that, treating onUnmount as "initial render only" felt inconsistent with the rest of the hook contract and with how consumers would naturally expect a cleanup option to behave.

Because of that, I treated this as a stale-closure bug rather than an intentional "initial-only" API.

What changed in the implementation

The change is intentionally minimal:

• keep the existing empty-deps cleanup effect
• keep the existing default cleanup behavior
• avoid introducing a new custom hook such as useLatest
• avoid changing the public API
• store only the latest onUnmount callback in a ref
• read ref.current inside the unmount cleanup

So the behavior changes only in one place:

• previously: cleanup used the first-render onUnmount
• now: cleanup uses the latest onUnmount

Motivation

This matters when onUnmount depends on props or render-time values and changes over the component lifecycle. In that case, the old behavior could execute outdated cleanup logic during unmount.

This PR fixes that without changing how often the effect is registered or how the default teardown works.

Local validation

• pnpm run test:pr --base=53fb52ec --head=HEAD
  • Successfully ran targets test:eslint, test:sherif, test:knip, test:docs, test:lib, test:types, build for 86 projects and 4 tasks they depend on
• pnpm run test:ci
  • Successfully ran targets test:eslint, test:sherif, test:knip, test:docs, test:lib, test:types, build for 169 projects (3m)
• pnpm changeset status --since=53fb52ec --verbose
  • confirmed patch releases for @tanstack/react-pacer and @tanstack/preact-pacer

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes
  • Unmount cleanup now invokes the most recent onUnmount callback (instead of a stale reference), ensuring proper teardown when options change.
  • Applies to debouncer, async debouncer, and rate limiter behavior across React and Preact integrations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 251697b5-78d8-49f2-8d41-19649d78ff17

📥 Commits

Reviewing files that changed from the base of the PR and between c413741 and 93d17a5.

📒 Files selected for processing (4)

• packages/preact-pacer/src/debouncer/useDebouncer.ts
• packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts
• packages/react-pacer/src/debouncer/useDebouncer.ts
• packages/react-pacer/src/rate-limiter/useRateLimiter.ts

✅ Files skipped from review due to trivial changes (1)

• packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react-pacer/src/rate-limiter/useRateLimiter.ts

---

📝 Walkthrough

Walkthrough

Patch release: unmount teardown now calls the most recent onUnmount option via a ref instead of a stale callback captured by the effect closure.

Changes

Unmount callback ref sync

Layer / File(s)	Summary
Core Implementation packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts, packages/react-pacer/src/debouncer/useDebouncer.ts, packages/react-pacer/src/rate-limiter/useRateLimiter.ts, packages/preact-pacer/src/debouncer/useDebouncer.ts	Added useRef and an onUnmountRef updated each render to hold mergedOptions.onUnmount.
Effect Cleanup Wiring packages/.../useAsyncDebouncer.ts, packages/.../useDebouncer.ts, packages/.../useRateLimiter.ts, packages/preact-pacer/.../useDebouncer.ts	Updated unmount useEffect cleanup to call onUnmountRef.current(instance) when present; otherwise fall back to existing cancel/abort logic.
Release Metadata .changeset/fair-donuts-chew.md	Added changeset entry for a patch release documenting the unmount-callback cleanup fix for both packages.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble on refs and tidy the latch,
Stale closures hop off, fresh callbacks catch.
Teardown now calls the latest tune,
No more echoes from last afternoon—
A clean little thump as the code doors match.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main fix: using the latest onUnmount callback during cleanup, which directly addresses the stale closure bug fixed across multiple adapter hooks.
Description check	✅ Passed	The description is comprehensive and complete, covering all template sections with detailed motivation, implementation details, and validation steps, including the required checklist items and changeset confirmation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}