From c5a259ad93b2768c274198b40cb892b0b7ffd858 Mon Sep 17 00:00:00 2001
From: Ben Lesh <ben@benlesh.com>
Date: Tue, 21 Nov 2023 14:54:07 -0600
Subject: [PATCH] Adds the catch operator to the README

---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/README.md b/README.md
index 591345f..6a9bae2 100644
--- a/README.md
+++ b/README.md
@@ -295,6 +295,94 @@ the platform, since it's an easy drop-in wherever you're handling events today.
 The proposed API shape can be found in
 https://wicg.github.io/observable/#core-infrastructure.
 
+```js
+dictionary ObservableEventListenerOptions {
+  boolean capture = false;
+  boolean passive;
+};
+
+partial interface EventTarget {
+  Observable on(DOMString type, optional ObservableEventListenerOptions options);
+};
+
+// `SubscribeCallback` is where the Observable "creator's" code lives. It's
+// called when `subscribe()` is called, to set up a new subscription.
+callback SubscribeCallback = undefined (Subscriber subscriber);
+callback ObserverCallback = undefined (any value);
+
+dictionary Observer {
+  ObserverCallback next;
+  VoidFunction complete;
+  ObserverCallback error;
+};
+
+dictionary SubscribeOptions {
+  AbortSignal signal;
+};
+
+dictionary PromiseOptions {
+  AbortSignal signal;
+};
+
+[Exposed=*]
+interface Subscriber {
+  undefined next(any result);
+  undefined complete();
+  undefined error(any error);
+  undefined addTeardown(VoidFunction teardown);
+
+  // True after the Subscriber is created, up until either
+  // `complete()`/`error()` are invoked, or the subscriber unsubscribes. Inside
+  // `complete()`/`error()`, this attribute is true.
+  readonly attribute boolean active;
+
+  readonly attribute AbortSignal signal;
+};
+
+callback Predicate = boolean (any value);
+callback Reducer = any (any accumulator, any currentValue)
+callback Mapper = any (any element, unsigned long long index)
+// Differs from `Mapper` only in return type, since this callback is exclusively
+// used to visit each element in a sequence, not transform it.
+callback Visitor = undefined (any element, unsigned long long index)
+
+[Exposed=*]
+interface Observable {
+  constructor(SubscribeCallback callback);
+  undefined subscribe(optional Observer observer = {}, optional SubscribeOptions = {});
+
+  undefined finally(VoidFunction callback);
+
+  // Constructs a native Observable from `value` if it's any of the following:
+  //   - Observable
+  //   - AsyncIterable
+  //   - Iterable
+  //   - Promise
+  static Observable from(any value);
+
+  // Observable-returning operators. See "Operators" section below.
+  // `takeUntil()` can consume promises, iterables, async iterables, and other
+  // observables.
+  Observable takeUntil(any notifier);
+  Observable map(Mapper mapper);
+  Observable filter(Predicate predicate);
+  Observable take(unsigned long long);
+  Observable drop(unsigned long long);
+  Observable flatMap(Mapper mapper);
+  Observable catch(Mapper mapper);
+
+  Promise<sequence<any>> toArray(optional PromiseOptions options);
+  Promise<undefined> forEach(Visitor callback, optional PromiseOptions options);
+
+  // Promise-returning. See "Concerns" section below.
+  Promise<boolean> every(Predicate predicate, optional PromiseOptions options);
+  // Maybe? Promise<any> first(optional PromiseOptions options);
+  Promise<any> find(Predicate predicate, optional PromiseOptions options);
+  Promise<boolean> some(Predicate predicate, optional PromiseOptions options);
+  Promise<any> reduce(Reducer reducer, optional any initialValue, optional PromiseOptions options);
+};
+```
+
 The creator of an Observable passes in a callback that gets invoked
 synchronously whenever `subscribe()` is called. The `subscribe()` method can be
 called _any number of times_, and the callback it invokes sets up a new
@@ -416,6 +504,10 @@ If the subscriber has already been aborted (i.e., `subscriber.signal.aborted` is
 
 We propose the following operators in addition to the `Observable` interface:
 
+- `catch()`
+  - Like `Promise.catch()`, it takes a callback which gets fired after the source
+    observable errors. It will then map to a new observable, returned by the callback,
+    unless the error is rethrown.
 - `takeUntil(Observable)`
   - Returns an observable that mirrors the one that this method is called on,
     until the input observable emits its first value