I learned a lot from reading Angular's Developer Guide to Testing, one of which is that I have a significant weak spot in my Angular understanding: how and when to use RxJS for asynchronous operations. Not just for testing, but also for writing Angular application code. On my first run through "Tour of Heroes" tutorial, RxJS was a black box I didn't understand at all. On my second run, I understood the tutorial enough to understand specific uses of RxJS from context, but my understanding did not extend to the rest of that library. I certainly don't know how to employ RxJS for my own tasks. It's time to buckle down and read official RxJS documentation.

This was quite a chore. It appears RxJS official documentation was written by its development team for an audience that already knows what it does and why they would want it. It started with "RxJS is a library for composing asynchronous and event-based programs by using observable sequences" and jargon gets thicker from there. (Interspersed with words like "just" and "simply" which this beginner found ridiculous.) There was no "Getting Started" section. The next-best candidate section "Installation" is full of material telling existing users how to migrate breaking changes, not an introduction to new users.

The good news is that, as of this writing, RxJS is still under active development. Today's stable release 7.8.0 has a timestamp only a few weeks old. (December 15th, 2022.) I was concerned about that, because RxJS was a solution for JavaScript asynchronous programming before JavaScript evolved to have its own asynchronous constructs like async/await. It doesn't map cleanly to Promises and conversion is a bit of a mess. But RxJS still does things that standard JavaScript doesn't do, so there are still scenarios where RxJS would be the right tool for the job. It'll take more learning before I recognize those scenarios.

Observable: RxJS foundation class. One thing that demystified a lot was rewriting an analogy using plain JavaScript. Seeing something familiar and understandable (with my very recent JavaScript education) gave me a starting point to try understanding the rest of the page. Unhelpfully this was at the bottom of the page.

Observer: It took a while for me to understand observer where my code fits into the system and I can use as little or as much of it as I need for a scenario. It can be a single callback for receiving data ("next") but I can also register optional callbacks to be notified of problems ("error") or when there's no more data ("complete").

Operator: Documentation said this is the powerful part of RxJS, but didn't really explain why or how we would leverage that power. This is also where marble diagrams were explained, something that bewildered me when Angular testing discussed marble testing. The overview of available operators is a disappointing list of just names. Each name is a link to their reference page without any additional context. I'd have to click the link and read each one. I would love a reference where each link has an 1-2 sentence summary, but no luck here.

Subject: These are Observable that multicasts to more than one Observer. Up until this point I hadn't known a basic Observable only broadcast to a single Observer! This critical information should have been covered earlier.

Scheduler: No usage examples or scenarios were given so I have no idea when I should care about choosing a different RxJS scheduler. I see the "How to do X", but not "Why you want to do X."

I'm sure everything in official RxJS documentation is technically correct but the information lacks context. Or more precisely, I don't think they were even trying to provide context for readers who are unaware. Perhaps there are resources to help RxJS beginners elsewhere on the internet?