Skip to content

Add Observable API #2863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Observable API #2863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions features/draft/spec/observable.yml → features/observable.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
draft_date: 2025-04-10
name: Observable
description: TODO
description: The `Observable` API provides a composable, ergonomic way of handling an asynchronous stream of events.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description is directly from the spec, because I don't understand the API well enough to describe it myself.

@domfarolino how would you describe this to a web developer in more objective terms? In particular I think we shouldn't claim it's ergonomic here, that's up to developers to judge I think.

I'm thinking something like:

The Observable API allows you to subscribe to events in a new way. The when() method does something that is different than addEventListener().

Help? :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention the when method earlier in the description.

Suggested change
description: The `Observable` API provides a composable, ergonomic way of handling an asynchronous stream of events.
description: The `when()` method of an `EventTarget` object, such as a DOM element, returns an `Observable` API instance which allows to ...

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Developers telling us it was ergonomic1 is what led me to ship the API and write the spec, so I feel like that description isn't a declaration as much as it is a response. But something like:

An Observable is an object representing a stream of events that you can operate on declaratively, even before it emits any events. `EventTarget#when()` returns an Observable that you can immediately subscribe to and direct with native operators, providing an ergonomic, composable alternative to `addEventListener()`.

Maybe something like that?

Footnotes

  1. In a way that Promise ergonomics compare to callbacks. ↩

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll be OOO for a week so if anyone wants to make a decision and land this, that's totally OK and appreciated!

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, doing my best here to synthesize everyone's comments here. How about this?

Suggested change
description: The `Observable` API provides a composable, ergonomic way of handling an asynchronous stream of events.
description: The `when()` method on a event target returns an `Observable` object, which provides a declarative API for subscribing to and operating on events. It's an alternative to `addEventListener()` callbacks.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.

spec: https://wicg.github.io/observable/
compat_features:
- api.EventTarget.when
Expand Down
0 features/draft/spec/observable.yml.dist → features/observable.yml.dist
View file
Open in desktop
File renamed without changes.