feat(tap): Adds subscribe, unsubscribe, finalize handlers

[benlesh]

This adds a common request/task for RxJS users, which are three new handlers:

• subscribe: fires on subscription to the source
• unsubscribe: fires when the subscription to the result is unsubscribed from, but NOT if the source completes or errors
• finalize: always fires on finalization, (basically equivalent to finalize)

This is useful for situations where you'd like to know that your consumer has decided to unsubscribe (and you're not terminating because of a complete or an error).

let subject = new Subject();

const sub1 = subject.pipe(
   tap({ 
      subscribe: () => console.log('subscribed'),
      complete: () => console.log('complete'),
      unsubscribe: () => console.log('unsubbed'),
      finalize: () => console.log('finalize')
   })
).subscribe();
// logs "subscribed"

sub1.unsubscribe();
// logs "unsubbed"
// logs "finalized"

const sub1 = subject.pipe(
   tap({ 
      complete: () => console.log('complete'),
      unsubscribe: () => console.log('unsubbed')
   })
).subscribe();
// logs "subscribed"

subject.complete();
// logs "complete"
// logs "finalized"

See included tests for more information.

[backbone87]

what is the reasoning behind doing this only for the tap operator and not for Subscribable.subscribe?

[backbone87]

nit: i think this comment can be removed

[kwonoj]

Just checking: did we discuss this in core meeting?

[benlesh]

@backbone87 the main reasoning is we're not attempting to change the semantics of observable, (which Subscribable is really just a super type of), this is about side-effects and observation on the part of the producer, which tap is defining.

import { interval, share, tap, take } from 'rxjs';

const producer = interval(1000).pipe(
  share(),
  take(100),
  tap({ 
    unsubscribe: () => console.log('a user has unsubscribed'),
  })
);

// At this point `producer` could be handed off to anyone.
// `tap` is concerned with side effects that _producer_ needs. Not the consumer.


// Here we have a consumer
const subscription = producer.subscribe({
   next: console.log,
   // (hypothetical)
   unsubscribe: () => console.log('you unsubscribed yourself')
});

// Why didn't you just console log here? :shrug:
subscription.unsubscribe(); 

the subscribe handler on the consumer end is honestly just as silly:

producer.subscribe({
  // Hypothetical:
  subscribe: () => console.log('you subscribed, lol');
});

Finalize might have merit however, and that's possibly worth discussing. Interestingly, it can be handled now like so (it's just non-obvious):

const subscription = producer.subscribe(console.log);

subscription.add(() => console.log('finalized');

In the future if we're using AbortSignal, and we land on not minding async completion (That's probably a non-starter), we could leverage forEach and Promise.prototype.finally:

// Hypothetical
const controller = new AbortControlelr();
const { signal } = controller;
producer.forEach(console.log, { signal }).finally(() => console.log('finalized'))

You can obviously do this now with forEach, it's just not cancellable. :)

[benlesh]

@kwonoj

Just checking: did we discuss this in core meeting?

Yes, but it's been a long time since we did.