fix(realtime): suppress disconnected status from onHeartbeat consumers

[mandarini]

Description

What changed?

• _wrapHeartbeatCallback in RealtimeClient now silently drops any heartbeat status of 'disconnected' before forwarding to the consumer callback
• Removed disconnected from the onHeartbeat JSDoc example statuses

Why was this change needed?

onHeartbeat exposes a 'disconnected' status via HeartbeatStatus, but it fires nondeterministically. The emission comes from @supabase/phoenix's Socket.sendHeartbeat() as a race-condition safeguard: if the heartbeat timer fires after the connection closes but before clearHeartbeats() runs in onConnClose, the !isConnected() guard emits 'disconnected'. Whether a consumer's callback ever receives it depends entirely on OS scheduler timing.

Connection lifecycle signals belong to the close handler and state-change events, not the heartbeat path. Consumers relying on 'disconnected' from onHeartbeat cannot do so reliably.

Closes #2488

Screenshots/Examples

Before: consumers could receive 'disconnected' from onHeartbeat intermittently with no way to depend on it.

After: onHeartbeat only fires 'sent', 'ok', 'error', and 'timeout' -- all deterministic heartbeat lifecycle statuses. Use socket state-change events (onOpen, onClose, onError) for connection lifecycle.

Breaking changes

• This PR contains no breaking changes

HeartbeatStatus still includes 'disconnected' in the type union -- no type surface is removed. The only observable change is that the nondeterministic emission is swallowed before reaching any consumer. A follow-up breaking change to remove 'disconnected' from HeartbeatStatus entirely is tracked for v3.

Checklist

• I have read the Contributing Guidelines
• My PR title follows the conventional commit format: <type>(<scope>): <description>
• I have run pnpm nx format to ensure consistent code formatting
• I have added tests for new functionality (if applicable)
• I have updated documentation (if applicable)

Additional notes

The root-cause fix (removing the heartbeatCallback("disconnected") emission from @supabase/phoenix's sendHeartbeat()). Once that ships, the suppression guard added here can be removed as dead code.

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@2496

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@2496

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@2496

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@2496

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@2496

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@2496

commit: 94c0772

[coveralls]

coverage: 80.309% (+0.006%) from 80.303% — fix/realtime-suppress-disconnected-heartbeat into master