chromium/third_party/blink/renderer/core/dom/observable.idl

// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// https://github.com/WICG/observable

callback SubscribeCallback = void (Subscriber subscriber);
callback ObserverCallback = void (any value);
callback ObserverCompleteCallback = void ();

callback Reducer = any (any accumulator, any currentValue, unsigned long long index);
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);
// This matches the predicate in the ECMAScript Iterator helpers proposal, i.e.,
// including the `index` parameter.
callback Predicate = boolean (any value, unsigned long long index);

// This callback returns an `any` that must convert into an `Observable`, via
// the `Observable` conversion semantics.
callback CatchCallback = any (any value);

callback ObservableInspectorAbortHandler = undefined (any value);
dictionary ObservableInspector {
  ObserverCallback next;
  ObserverCallback error;
  ObserverCompleteCallback complete;

  VoidFunction subscribe;
  ObservableInspectorAbortHandler abort;
};

dictionary Observer {
  ObserverCallback next;
  ObserverCallback error;
  ObserverCompleteCallback complete;
};

dictionary SubscribeOptions {
  AbortSignal signal;
};

typedef (ObserverCallback or Observer) ObserverUnion;
typedef (ObserverCallback or ObservableInspector) ObservableInspectorUnion;

[Exposed=(Window,Worker), RuntimeEnabled=ObservableAPI]
interface Observable {
  [CallWith=ScriptState, MeasureAs=ObservableConstructor] constructor(SubscribeCallback callback);
  [CallWith=ScriptState] void subscribe(optional ObserverUnion observer = {}, optional SubscribeOptions options = {});

  [CallWith=ScriptState, RaisesException] static Observable from(any value);

  // Observable-returning operators.
  // See https://wicg.github.io/observable/#observable-returning-operators.
  //
  // TODO(crbug.com/1485981): The `Observable` argument type below should be
  // `any`, and the conversion semantics (that have not yet been implemented)
  // should convert that `any` into an `Observable`.
  [CallWith=ScriptState] Observable takeUntil(Observable notifier);
  [CallWith=ScriptState] Observable map(Mapper mapper);
  [CallWith=ScriptState] Observable filter(Predicate predicate);
  [CallWith=ScriptState] Observable take(unsigned long long number_to_take);
  [CallWith=ScriptState] Observable drop(unsigned long long number_to_drop);
  [CallWith=ScriptState, RaisesException] Observable flatMap(Mapper mapper);
  [CallWith=ScriptState, RaisesException] Observable switchMap(Mapper mapper);
  [CallWith=ScriptState] Observable inspect(optional ObservableInspectorUnion inspect_observer = {});
  [CallWith=ScriptState, RaisesException, ImplementedAs=catchImpl] Observable catch(CatchCallback callback);

  // Promise-returning operators.
  // See https://wicg.github.io/observable/#promise-returning-operators.
  [CallWith=ScriptState] Promise<sequence<any>> toArray(optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<undefined> forEach(Visitor callback, optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<any> first(optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<any> last(optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<boolean> some(Predicate predicate, optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<boolean> every(Predicate predicate, optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<any> find(Predicate predicate, optional SubscribeOptions options = {});
  [CallWith=ScriptState] Promise<any> reduce(Reducer reducer, optional any initialValue, optional SubscribeOptions options = {});
};