indefinite-observable

What is indefinite-observable?

The indefinite-observable npm package provides a simple and lightweight way to create observables that can emit values indefinitely. It is particularly useful for scenarios where you need to handle asynchronous data streams, such as user input events, WebSocket messages, or other continuous data sources.

What are indefinite-observable's main functionalities?

Creating an Observable

This feature allows you to create an observable that emits a sequence of numbers every second. The observer's `next` method is called with the current count, and the observable can be unsubscribed from to stop the emission.

const { create } = require('indefinite-observable');

const observable = create(observer => {
  let count = 0;
  const intervalId = setInterval(() => {
    observer.next(count++);
  }, 1000);

  return () => clearInterval(intervalId);
});

const subscription = observable.subscribe(value => {
  console.log(value);
});

// To unsubscribe
// subscription.unsubscribe();

Handling Errors

This feature demonstrates how to handle errors within an observable. When the count reaches 5, an error is emitted, and the observer's `error` method is called.

const { create } = require('indefinite-observable');

const observable = create(observer => {
  let count = 0;
  const intervalId = setInterval(() => {
    if (count === 5) {
      observer.error(new Error('An error occurred at count 5'));
    } else {
      observer.next(count++);
    }
  }, 1000);

  return () => clearInterval(intervalId);
});

const subscription = observable.subscribe({
  next: value => console.log(value),
  error: err => console.error(err)
});

Completing an Observable

This feature shows how to complete an observable. When the count reaches 5, the observer's `complete` method is called, signaling that no more values will be emitted.

const { create } = require('indefinite-observable');

const observable = create(observer => {
  let count = 0;
  const intervalId = setInterval(() => {
    if (count === 5) {
      observer.complete();
    } else {
      observer.next(count++);
    }
  }, 1000);

  return () => clearInterval(intervalId);
});

const subscription = observable.subscribe({
  next: value => console.log(value),
  complete: () => console.log('Observable completed')
});

Other packages similar to indefinite-observable

rxjs

RxJS is a library for reactive programming using Observables, to make it easier to compose asynchronous or callback-based code. It is more feature-rich and complex compared to indefinite-observable, offering a wide range of operators and utilities for working with observables.

most

Most.js is a high-performance FRP (Functional Reactive Programming) library. It provides a minimal API for creating and transforming streams, similar to indefinite-observable but with a focus on performance and functional programming paradigms.

baconjs

Bacon.js is a small functional reactive programming library for JavaScript. It provides a way to work with events and values over time, similar to indefinite-observable, but with a more comprehensive set of tools for handling complex data flows.

README

Indefinite Observable

Why?

There are a lot of great Observable implementations, but they're baked into featureful libraries which contribute to both complexity and filesize. We wanted the simplest-possible Observable implementation, with no operators, no fancy scheduling. The entire thing is basically three statements in subscribe.

Indefinite Observable is a subset of the TC39 Observable proposal that never completes or errors. It implements the minimal-necessary functionality, but it should be completely interchangeable with the TC39 proposal for the subset that it does implement.

If you want a complete Observables library that works out-of-the-box, check out xstream, RxJS, Most, Bacon, or Kefir. If you want to build your own Observables library that includes just the functionality you need, try Indefinite Observable.

Usage

import { IndefiniteObservable } from 'indefinite-observable';

const moveEvent$ = new IndefiniteObservable(
  (observer) => {
    // Whenever you want the observable to dispatch a value, call
    // observer.next(value).
    element.addEventListener('pointermove', observer.next);

    // Return a function that will perform any necessary clean up when the
    // observable is unsubscribed from.
    return () => {
      element.removeEventListener('pointermove', observer.next);
    }
  }
);

// To receive the values dispatched by an observable, pass an observer to its
// subscribe method.  An observer is just an object with a next method.
//
// subscribe returns a unsubscribe function.  Call that when you no longer want
// to receive dispatches from the observable.
const unsubscribe = moveEvent$.subscribe({
  next(moveEvent) {
    console.log('got a pointer event: ', moveEvent);
  }
});

Learn more about How Indefinite Observables work.

Installation

yarn add indefinite-observable

or include as a script tag:

<script type = "module">
  import { IndefiniteObservable } from "https://ajax.googleapis.com/ajax/libs/indefinite-observable/2.0.1/indefinite-observable.bundle.js"
</script>

Contributing

This library aims to be as simple as possible, so modifications will be rare. Reasons we might make changes are limited to:

• bugs, or
• remaining compatible with the subset of the Observable spec that we support.

If you'd like to add operators, static methods, or other features, we invite you to depend upon us subclassing IndefiniteObservable in your own module. In fact, that's how we add features too.

Of course, we welcome improvements to the examples and documentation in this repo.

Bundling

Our source is available in 3 flavors: a TypeScript module, a JavaScript module, and a JavaScript bundle. Any changes made to the first need to be reflected in the other two. This should be handled for you automatically via a pre-commit hook. If you have a clean working copy after committing, you're good. If not, amend the commit with the new build before pushing.

If you need to bundle it independently, run

yarn run build

Testing

yarn run test

License

Apache 2.0