feat: listeners api

[owenpearson]

adds channel.listeners and presence.listeners methods to get an array of listeners subscribed to the channel/presence.

Summary by CodeRabbit

• New Features
  • Added the ability to inspect event listeners on realtime channels and presence. Retrieve all listeners, those for a specific event, or aggregate listeners across multiple events, enabling easier debugging and introspection without changing subscriptions. Available in both runtime APIs and TypeScript definitions to improve developer ergonomics when working with realtime entities.

[coderabbitai[bot]]

Walkthrough

Adds listener retrieval APIs across realtime entities. RealtimeChannel and RealtimePresence expose listeners(event?: string | string[]): Function[]. EventEmitter.listeners now accepts undefined, string, or string[] and aggregates listeners for arrays. Type declarations in ably.d.ts updated to reflect these public methods.

Changes

Cohort / File(s)	Summary
Type Definitions ably.d.ts	Declares new overloads on RealtimeChannel and RealtimePresence: listeners(), listeners(event: string), listeners(events: string[]).
Realtime Entities src/common/lib/client/realtimechannel.ts, src/common/lib/client/realtimepresence.ts	Adds public listeners(event?: string | string[]): Function[] delegating to internal subscriptions.listeners(...), defaulting to [] when falsy.
Event Emitter Core src/common/lib/util/eventemitter.ts	Extends listeners signature to event?: string | string[]. For arrays, aggregates listeners across events; for single/undefined, preserves existing behavior (returns array or null).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant C as Caller
  participant RC as RealtimeChannel/Presence
  participant EE as EventEmitter (subscriptions)

  C->>RC: listeners(event?: string|string[])
  alt single event or undefined
    RC->>EE: listeners(event?)
    EE-->>RC: Function[] | null
    RC-->>C: Function[] (empty if null)
  else multiple events (string[])
    RC->>EE: listeners(events[])
    note over EE: Iterate events, collect listeners
    EE-->>RC: Combined Function[] | null
    RC-->>C: Function[] (empty if null)
  end

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my ears at signals’ dance,
New hooks to count—now I’ve a chance!
One hop, one event; or many in a row,
I gather the listeners, tally the flow.
Burrow logs whisper, “All’s in sight,”
Carrot-typed arrays—crisp and light. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly and accurately conveys the addition of a feature to expose listener APIs on realtime entities by describing it as a “listeners api” feature. It aligns directly with the main change of adding channel.listeners and presence.listeners methods.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• [ ] 📝 Generate Docstrings

🧪 Generate unit tests

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch listeners-api

[!TIP]

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

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.}

[VeskeR]

Some comments before review: Should we add the same for Annotations while we're at it? And callback types seem to mismatch, tests are not happy.

Also should discuss if there is a need to have the same for LiveObjects, can discuss it with Mike and can add it as part of the new location based API changes.