Add "single" as alternative for observables that only emit once or error and then complete

[NilsEngelbach]

Feature Request

A special type for observable that only emits one value or throws error and then completes.

Is your feature request related to a problem? Please describe.
The Angular HTTPClient returns observables for http requests, but you can be sure they will complete after one emission/error. I already saw people wrapping those observables in a Promise just to "make sure / emphasis" it will emit once (by the return type Promise). As trade off you loose the nice rxjs observables api (pipes etc.).

Describe the solution you'd like
The Java Implementation of Rx provides a special type for this use case called "Single".
http://reactivex.io/documentation/single.html
I know Java might not be the best source for inspiration, but in this case the additional type could provide useful additonal type information for consumers. There are things that "by nature" do not return a stream of multiple values but only one e.g. a http request.

The first sentence in rxjs documentation on observables states:

Observables are lazy Push collections of multiple values.

As beginner you can easily get confused by a http request returning an observable and therefore somehow emitting multiple values (multiple = more than one).

I can understand that such "Single" type could on the other hand cause some trouble for beginners because it seems to be something similar to a Promise. But imho it would be nice to have such a type with a subset of rxjs operators you already know from observables. The subset of operators would not include the operators that depend on the emission of multiple values or don't make sense for a single value (take, pairwise, ...).

Describe alternatives you've considered
If a new type like "Single" can not be taken into consideration, at least the documentation should be adjusted to clarify that observables can also emit 0 or only 1 value.

Additional context
What would be the reasons against having a new type of observables like single?

• More complex to understand for beginners?
• Bigger footprint of the library?
• Confusion with existing promise implementation?
• What else?

There were already discussions about similar topics in #2469 and #3424 but I couldn't find reasonable arguments against it, yet.

[cartant]

IMO, this is something that ought to be expressible with TypeScript. And my understanding is that there is some interest in this happening. I don't think there is any appetite for a runtime representation (e.g. a class hierarchy) for these sorts of observable behaviours. Personally, I would not be in favour of a runtime representation.

Mechanisms for augmenting the TypeScript declarations to identify observables that complete, etc. is being given some consideration. However, it is not at the top of the priority list. The top priority, ATM, is v7 - in which the package will be brought up to a more recent minimum version of TypeScript and the package's type signatures will be improved.

[NilsEngelbach]

Is there some documentation about what was already considered exactly for augmenting the TypeScript declarations? Do you think this could be handled completly by augmenting the TypeScript declarations?

From consumer point of view it still would be a new "type" that would require addtional documentation etc., correct?

[cartant]

Is there some documentation ... ?

No. It's literally just an idea, ATM.

[jgbpercy]

There's this discussion/proposal, which I believe would allow this to be expressed in TypeScript #5042

From that issue:

This technique would also give us a Single for free since fromFetch(), from(promise), and generated API could be set this hidden tuple to a single element. This can also remove the need for folks to do things like api.fetchData().pipe(take(1)).

[kwonoj]

Previous issues were mostly about not discussing necessary of this feature or not, but more of if this should be in core lib or not. I still stands for this would go in userland, either if it's runtime or type time interfaces.

[NilsEngelbach]

@kwonoj what are the main reasons for you against such a type/feature in rxjs, besides the ones I already mentioned?
What would be good criteria to judge if something is necessary or useful?

[kwonoj]

We strongly encourage to land new features / or operators / etcs into userland first to see if it's being widely used, discussing potential api surface changes, revealing edge cases, etcs then would like to discuss include in core as next step. It is nearly not possible to deprecate something landed in core, and even small modification can cause wide effect once it's landed.

So question we always ask is flipped: is there reason it can't be userland that user opt-in to install to use it? I don't see reason why this can't be userland implementation.

[tmtron]

is there reason it can't be userland that user opt-in to install to use it? I don't see reason why this can't be userland implementation.

Single/Maybe have different contracts than Observable and thus many types in the library would need to be changed.
e.g. the return type of these operators: first, last, toArray, etc. should be Single
I don't see how this could be done in a user-land library.

e.g. Quote from the RxJava docs for Single:

it can only emit either a single successful value or an error (there is no "onComplete" notification as there is for an Observable)

The Single operates with the following sequential protocol:
onSubscribe (onSuccess | onError)?
Note that onSuccess and onError are mutually exclusive events; unlike Observable, onSuccess is never followed by onError.

On the other hand I also don't know how this could easily be added in a type-safe way to RxJs: i.e. what would the pipe method and all it's overloads look like, when Single, Maybe and Observable can be used?

So, I understand that the RxJs authors are reluctant to introduce this feature. It would for sure be a lot of work and a major change.

[ynoplanetashka2]

in fact because Single's contract differ from Observable's contract there are some operations which are valid only applied to Single. for example, if we want to create operator similar to Promise.any for Observable's then we would find out that Observable contract isn't sufficient to create valid analogue for Promise.any. why? because for meaningful implementation of Promise.any analogue we have to know whenever Observable will reject or not at it's first emit.
consider we applied operator 'any' to observableA and observableB and suppose we have such marble diagrams:
observableA: --0--X
observableB: ---------0
we should mirror first observable which will not throw, but at the moment of observableA first emit we can't know will it throw or not, so we don't know should we mirror it's values or not.
such problem doesn't appear with Single, because by it's contract we can be sure to know will it throw or not at the moment of first(and only) emit.
and if we would implement Promise.any analogue operator it should probably work only with Single and probably throw for Observable.
and btw seeing something like this is always confusing

// will this function perform chunking?
// if no users found will it emit empty array or eventually complete without emitting?
getUsers(): Observable<User[]>
// that would be really cool to see something like this instead
getUsers(): Single<User[]>