Core semantics

[benlesh]

This is a starting place to put together a document that outlines the semantics of functionality provided by the core library. This will be used as a reference for the "correct" behaviors of the library starting in version 8. We probably can't do that in version 7 without breaking someone, but it's definitely something we want to get defined, as it keeps coming.

[benlesh]

This was unrelated, but I saw it and it needs to be removed.

[benlesh]

This was automatic.

[backbone87]

questions that might be worth also answering here:

• which types of value emission should be allowed? maybe also add the TS type that is required (I guess ObservableInput<any>)
• what happens if a notifier errors before/after next?
• how to deal with subscription references of notifiers when they error/complete without next notification?
• should notifiers always be one-time emissions? basically, they always behave like from(notifier).pipe(take(1)) from the operator's point of view?
• "Notifiers must be unsubscribed from at the earliest possible moment once they notified or when the operator is not interested in being notified anymore"?

[backbone87]

where applicable it would be very helpful to have "dos and don'ts" examples

[backbone87]

it would be helpful to explain when to ultimately unsubscribe from the source and how to "detect" this case.

[backbone87]

just working on a window style custom operator and while looking at the window source code I noticed that this operator family unsubscribes the nested observables immediately when the primary subscription is unsubscribed from:
https://stackblitz.com/edit/qsuarg?devtoolsheight=33&file=index.ts

[backbone87]

The more i dig into the window/groupBy use cases the more I think that it is much more intuitive if the group lifecycles are tied to the top-level subscription and consuming them outside of its context is an anti-pattern, if we talk about window/groupBy as operators. is there some widely used pattern that I missed that requires this?

i also tried to compare it to the refactorings done to the multicasting operators, where connect/share operators are also entirely handled within the primary subscription(s), while the connectable observable factory was a part of the multicast operator that was taken out of pipeline/operators into an observable factory so the connect method can be handled outside of the scope of a primary subscription.

[benlesh]

how to "detect" this case.

If the operator takes a source of Observable<A> returns Observable<Observable<B>>, (windowX, groupBy) that's how you'd know. There's nothing to really "detect" in this case.

The more i dig into the window/groupBy use cases the more I think that it is much more intuitive...

Yeah, I don't disagree. I'm putting this in here as a starting/discussion point. A lot of people don't even realize that this is a thing. So, I've added it to the core semantics document so the core team can agree on a behavior and move that way over the course of 7 -> 8 -> 9 versions. It very well might be the correct decision to stop groupBy from behaving this way. Or maybe we need to add some sort of "eject" functionality... either way, it's a point of discussion, and I'm glad you're picking up on it.

[benlesh]

cc @cartant @kwonoj @kolodny @niklas-wortmann ☝️

[backbone87]

There's nothing to really "detect" in this case.

by "detect" I meant, how does the operator find out when to unsubscribe from the source. I know how groupBy does it and window* doesn't do it, but I would expect a general guideline here on what the correct "detection mechanism" is.

---

After giving this some more thought on my side, I have to justify my original opinion on this topic.
Lets first talk about window*:

const sub1 = of(1, 2, 3)
  .pipe(
    windowCount(1),
    take(1),
    mergeAll()
  ).subscribe()
  // I would expect this to emit `1` (it currently does not).

let w: Observable<number>;
const sub2 = of(1, 2, 3)
  .pipe(
    windowCount(1),
    take(1),
  )
  .subscribe((v) => void (w = v));
w.subscribe();
// I would expect this to be UB,
// it will never emit in a sync case and may or may not work in the async case

let w: Observable<number>;
const sub3 = of(1, 2, 3)
  .pipe(
    windowCount(1),
    take(1),
  )
  .subscribe((v) => void v.subscribe());
  // this could work and emit `1` (it currently does not),
  // but I would consider this bad practice and should be discouraged.
  // if it eases implementation then UB would be fine too IMHO.

why should the first example work? the reason is the semantics of the inner observable. it has a clear definition of its lifecycle: the first window starts before the first source emission, emits the following 1 next notification, and then completes. since windowCount only operates on the sequence of notifications (and not the contents of notifications) and/or external notifiers (on other variants of the window operator) it is "predictable" what the inner observables will emit and I can imagine uses cases for chaining it with take et al.

this is also still in line with what I originally said: the observable is consumed within its "primary" subscription (referring to sub1 here), as the nested/inner subscriptions are "invisible" to the user. this is not the case for the second example.

in the groupBy case it's basically the same, but I just don't see any use case for pipe(groupBy(selector), take(n)) without having the possibility to control group openings. this was proposed in #6425. currently this can be worked around with something like pipe(startWith(x, y, z), groupBy(selector), map(skip(1)), take(n)), but it does not feel very nice.

[trxcllnt]

Operators that split a source Observable<T> into many child observables Observable<Observable<T>> should emit child observables that do not stop because the original consumer subscription is unsubscribed.

Why not just multicast the groupBy() Observable and manually connect it?

The inner Observables are tied to the lifetime of the groupBy() subscriber because Observables are pure functions. The inner GroupedObservables are not meant to leak outside the monad:

// good
src.groupBy().flatMap((group) => {
   return group.map((x) => `${group.key}:${x}`);
}).subscribe(console.log.bind(console));

// bad
src.groupBy().subscribe((group) => {
   group.subscribe((x) => console.log(`${group.key}:${x}`));
});

Multiple subscriptions to the inner GroupedObservables (or leaking them via subscribe()) necessarily represents mutable state, which is what multicast() and connect() are for:

const groups = src.groupBy()
   .map((group) => group.map((x) => `${group.key}:${x}`))
   .multicast();

const groupState = groups.connect();

groups.subscribe((group) => {
   group.subscribe((x) => console.log(`${x}-1`));
   group.subscribe((x) => console.log(`${x}-2`));
});

// kill all subscribers to all inner groups
setTimeout(() => groupState.unsubscribe(), 1000);

[benlesh]

@trxcllnt LMAO. I swear I didn't write groupBy to behave like this, I thought you did. I agree it's weird. I only recorded this semantic because I wanted to draw attention to it. I'd be much happier if it did not have that behavior.

[backbone87]

"event" is a confusing term here. is general behavior meant, like cleanup or downstream notifications?

[benlesh]

We should probably link terms to the glossary.

[kolodny]

nit: ...can tell it does not change... I had trouble parsing this sentence without that

[kolodny]

Can you give examples or some guidance on what "longer than necessary" means? If I ever plan on sending the error to the user then, by definition, it will be necessary.

[benlesh]

I'm not sure what else to put here. Basically like creating an Error object well in advance of some async throw. They should be created on-demand if at all possible.

[trxcllnt]

And if you create a rejected Promise and don't call .catch() before the next turn of the event loop, node will throw an unhandledRejection event.

[benlesh]

@ReactiveX/rxjs-core I think we should try to get this landed and iterate on it. Otherwise it's going to flounder as a PR like most of our documentation PRs do. haha. I think the main thing I want to settle though is around the "splitting operators" mentioned above.

[kolodny]

Looks good, I'm very happy with having a doc like this to get everything on the same mindset. Agree that we can iterate on the harder splitting operators.

[cartant]

Approving this, but IMO the referentially-transparent bit isn't quite right.

[cartant]

It's the operator that must be referentially transparent; not the operator function. There should be no requirement for the returned function to be referentially transparent.

Calls to share must be referentially transparent, but calls to the operator function - that share returns - are not.

My understanding of referential transparency is that a function is referentially transparent if you can replace its being called with the value that it returns, so it's the operator that needs to be referentially transparent for this to make sense:

That is to say, that if you capture the return value of the operator...

[cartant]

Should this really be a 'MUST'. There will be no subscription to the source for a take(0), for example. Is that something that is going to have to change?

[benlesh]

Okay... I'm going to merge this as-is, and we can make subsequent PRs to clean up the minutiae. I will be VERY happy to fix the semantics of groupBy, which IMO are a nightmare. I'm glad @trxcllnt pointed out that he didn't agree with it, either. haha.