[DX-1204] Fix v1-callback overloads breaking mocks (never → void)

[umair-ably]

Background

#2226 (DX-1204) re-introduced the v1 callback-style method signatures as @deprecated overloads returning never, to steer users/LLMs toward the v2 promise API. The runtime guard (detectV1Callback, which throws a hinted error) is the part the PR's evidence measured, and it is not changed here.

@owenpearson reported that the never return type makes these methods impossible to mock by assignment — a common testing pattern:

channel.subscribe = vi.fn(() => Promise.reject()); // ❌ doesn't type-check on main

This fails because the assigned value must satisfy every overload, including the one returning never, and nothing is assignable to a never-returning signature.

Fix

Change the return type of the 14 deprecated v1-callback overloads from never → void (auth authorize/createTokenRequest/requestToken, presence get/history/subscribe/enter/update/leave, channel unsubscribe/history/subscribe/publish, connection.ping).

TypeScript allows a function returning any value to be assigned to a void-returning function type (the rule that makes arr.forEach(x => arr.push(x)) legal), so mock assignment now type-checks. never was the only return type that rejected it. (void also matches what these methods returned in v1.)

Diff is 14 lines — ): never; → ): void; — nothing else.

Intentionally out of scope: the no-deprecated warning on bare references

Owen also noted that @typescript-eslint/no-deprecated flags bare references like expect(channel.subscribe). We are not addressing that here. It's arguably an upstream issue: for a non-call reference the rule can't resolve a specific overload, so it treats the symbol as deprecated if any overload is. Removing the @deprecated tag would silence it but would also drop the editor strikethrough + migration hint on v1 call sites, which we want to keep. Consumers hitting the warning can disable the rule on those lines until it's fixed upstream.

Verification

• npx tsc --noEmit ably.d.ts modular.d.ts (the check CI gate), prettier --check, and eslint all pass.
• Mock assignment compiles for all 14 methods (verified against the real ably.d.ts with vitest and @types/jest): vi.fn(...), vi.fn(), jest.fn(...), jest.spyOn, direct assignment.
• The @deprecated strikethrough + migration hint on v1 call sites are unchanged.
• Runtime detectV1Callback guard and its tests are unchanged.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Corrected TypeScript type definitions for deprecated callback-based method overloads affecting authentication, realtime presence, channels, and connections. Return type annotations have been updated to more accurately reflect method behavior, enhancing type safety, improving IDE autocompletion accuracy, and reducing type-related issues for TypeScript developers using callback-style APIs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ee8fbfe2-5597-4bd5-8be1-f57bb81d4ce7

📥 Commits

Reviewing files that changed from the base of the PR and between 402e5e1 and e087e9d.

📒 Files selected for processing (1)

• ably.d.ts

---

Walkthrough

The PR updates the Ably JavaScript SDK TypeScript definitions to change deprecated v1 callback-based method overload return types from never to void across multiple classes including Auth, RealtimePresence, RealtimeChannel, and Connection.

Changes

Deprecated v1 Callback Overload Return Types

Layer / File(s)	Summary
Auth callback method overloads ably.d.ts	authorize, createTokenRequest, and requestToken callback overloads return type changed from never to void.
RealtimePresence callback method overloads ably.d.ts	get, history, subscribe, enter, update, and leave callback overloads return type changed from never to void.
RealtimeChannel callback method overloads ably.d.ts	unsubscribe, history, subscribe, and publish callback overloads return type changed from never to void.
Connection callback method overload ably.d.ts	ping callback overload return type changed from never to void.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A rabbit hops through types so grand,
From never void, with steady hand,
Callbacks dance in patterns true,
Six classes blessed, their defs made new! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing v1-callback overloads by changing their return type from 'never' to 'void', with reference to the issue number and the core problem (breaking mocks).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DX-1204/fix-v1-callback-overload-types

---

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

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

[owenpearson]

the change to void is good! i don't like the other one though, sorry: