Refine subscribe and tap signatures

[benlesh]

Currently we have a variety of ways you can use subscribe and tap:

o.subscribe(fn, fn, fn);
o.subscribe(fn, fn);
o.subscribe(fn);
o.subscribe(void, void, fn);
o.subscribe(void, fn, fn);
o.subscribe(void, fn);
o.subscribe(observer);


o.pipe(tap(fn, fn, fn));
o.pipe(tap(fn, fn));
o.pipe(tap(fn));
o.pipe(tap(void, void, fn));
o.pipe(tap(void, fn, fn));
o.pipe(tap(void, fn));
o.pipe(tap(observer));

It's been my personnel recommendation that people stick to the following two signatures:

o.subscribe(fn);
o.subscribe(observer);

// or likewise with tap:
o.pipe(tap(fn));
o.pipe(tap(observer));

The reason being is:

// POOR readability (I have to count arguments?)
o.subscribe(null, null, () => {
  // side effect here
});

// BETTER readability
o.subscribe({
  complete() {
    // side effect here
  }
});

// GOOD readability
o.subscribe(x => {
  // side effect here
});

// GOOD readability (if unnecessarily verbose)
o.subscribe({
   next(x) { 
      // side effect here
   }
});

Proposal

I'd like to deprecate the other signatures to subscribe and tap, and narrow down the signature to just those two prescribed above for the next major version

Pros

• Simplify subscription code slightly.
• Simpler typing for TypeScript.
• Guides people into writing cleaner, more readable code

Cons

• The behavior around handling errors at the point of subscription may get a slightly harder to control, with only one way of adding error handling at subscription time. (NOTE: errors should really be handled by a catchError or retry-type operator, rather than in the subscribe.)

Other thoughts

It would also be good to add some lint rules around this to rxjs-tslint and the like.

[kwonoj]

I think we can have tslint rules easily, that's probably not a problem.

For librarywise, I'd like to think bit more: specifically, you'd like to allow form of

subscribe(next);

but do not allow any other forms? or it is still allowed

subscribe(next, error);
subscribe(next, error, complete);

form?

[benlesh]

but do not allow any other forms? or it is still allowed

It would be allowed in the short term, but in the long term (next major version or some future major version), it would be a hard API change.

[benlesh]

And if anyone is wondering "why not just subscribe(observer) and forEach(fn)?"... Well, forEach is supposed to have the semantic of nexting on a microtask, and forEach returns a promise and is currently non-cancellable.

I'd expect that .subscribe(fn) is probably the 90% use case for people.

[kwonoj]

I'd expect that .subscribe(fn) is probably the 90% use case for people.

I agree it's major usecase, but not sure about 90%. i.e these two form

subscribe(next, error);
subscribe(next, error, complete);

I've been used all time, personally I never used observer object form (.subscribe({next: ...})).
I don't have strong opinion around readability between observer form vs. fn arguments, but does not allowing fn form except next bitters me, bit downvote around those decisions.

what if we allow fn form as is, only disallow optional form?

subscribe(null, error); //meh, not allowed
subscribe(next, error); //allowed

[ajcrites]

I'm all for this change; in fact I've recently started doing subscribe({ error }) instead of subscribe(null, error) simply because I found out that you could even do the former. I think that this deprecation will coach people into what I see as a better way of writing subscription code.

I'd like to discuss the "Con" a bit more:

The behavior around handling errors at the point of subscription may get a slightly harder to control...

Do you have more specifics about this? It seems like .subscribe({ error }) is not harder than .subscribe(null, error), but I'm not sure if I'm missing something.

...errors should really be handled by a catchError or retry-type operator, rather than in the subscribe.

I don't fully agree with this for a couple of reasons:

1. We need a way to handle errors that happen in next.
2. This requires a particular way of thinking about Observables -- specifically that everything flows through to the subscription handler and caught errors need to emit something that can be handled by that logic. Are you suggesting that we always want that to be the case?

[crutchcorn]

I honestly could not agree more. With our work with RxJS, we've had so many bike shedding discussions due to this issue and the students I've helped teach RxJS often get caught on this issue (of error handling/syntax) based on the numerous ways to approach things and the different (usually 3rd party) resources.

[billba]

What I specifically like about observable.subscribe(next, error) is that it's a nice parallel to promise.then(result, error). Although since the semantics are different, maybe that's an argument for getting rid of this "faux amis" situation. Okay, I've convinced myself that I agree with this proposal.

[cmckni3]

I agree with this. I found having the next, error, and complete handlers becomes difficult to read. Moved to pipe approach for everything with v5 and v6.

[benlesh]

From the core team meeting:

Start with deprecating signatures like null, null, fn. Perhaps add some tslint rules to help guide people. Maybe move on to deprecating fn, fn, fn... @kwonoj is the voice of dissent.

[cartant]

BTW, there is a TSLint rule in rxjs-tslint-rules - named rxjs-prefer-observer - that relates to this issue.