@xan/observable

A template for connecting a consumer to a producer to be observed

Build

Automated by JSR

Publishing

Automated by .github\workflows\publish.yml.

Running unit tests

Run deno task test or deno task test:ci to execute the unit tests via Deno.

Example

import { Observable } from "@xan/observable";

const observable = new Observable<0>((observer) => {
  // Note that this logic is invoked for every new subscribe action.

  // If the observer is already aborted, there's no work to do.
  if (observer.signal.aborted) return;

  // Create a timeout as our producer to next a value after 1 second.
  const producer = setTimeout(() => {
    // Next the value to the observer.
    observer.next(0);
    // The producer is done, notify complete.
    observer.complete();
  }, 1000);

  // Add an abort listener to handle unsubscription by canceling the producer.
  observer.signal.addEventListener("abort", () => clearTimeout(producer), {
    once: true,
  });
});

Glossary And Semantics

When discussing and documenting observables, it's important to have a common language and a known set of rules around what is going on. This document is an attempt to standardize these things so we can try to control the language in our docs, and hopefully other publications about this library, so we can discuss reactive programming with this library on consistent terms.

While not all of the documentation for this library reflects this terminology, it is a goal of the team to ensure it does, and to ensure the language and names around the library use this document as a source of truth and unified language.

Major Actions

There are specific actions and events that occur between major entities in the library that need to be defined. These major actions are the highest level events that occur within various parts of the library.

Observation Chain

When an observable uses another observable as a producer, an "observation chain" is set up. That is a chain of observation such that multiple observers are notifying each other in a unidirectional way toward the final consumer.

Major Concepts

Some of what we discuss is conceptual. These are mostly common traits of behaviors that can manifest in observables or in push-based reactive systems.

Cold

An observable is "cold" when it creates a new producer during subscribe for every new subscription. As a result, "cold" observables are always unicast, being one producer observed by one consumer. Cold observables can be made hot but not the other way around.

Hot

An observable is "hot", when its producer was created outside of the context of the subscribe action. This means that the "hot" observable is almost always multicast. It is possible that a "hot" observable is still technically unicast, if it is engineered to only allow one subscription at a time, however, there is no straightforward mechanism for this in the library, and the scenario is an unlikely one. For the purposes of discussion, all "hot" observables can be assumed to be multicast. Hot observables cannot be made cold.

Minor Entities

Source

An observable that will supply values to another observable. This source, will be the producer for the resulting observable and all of its subscriptions. Sources may generally be any type of observable.

Notifier

An observable that is being used to notify another observable that it needs to perform some action. The action should only occur on a next and never on throw or return.

Other Concepts

@xan/observer