@wopjs/disposable

Manage side effect disposers in a compact, reusable and testable style. Designed and implemented with efficiency and ergonomics in mind.

Install

npm add @wopjs/disposable

Example

import {
  disposable,
  type IDisposable,
  type DisposableStore,
} from "@wopjs/disposable";

class A implements IDisposable {
  dispose: DisposableStore;
  constructor() {
    this.dispose = disposable();
    // Add a disposer function via `add`.
    this.dispose.add(
      someEvent.addListener("type", event => console.log(event))
    );
  }
  someMethod() {
    // Create side effects on demand.
    this.dispose.make(
      () => {
        const timeoutId = setTimeout(() => console.log("timeout"), 1000);
        return () => clearTimeout(timeoutId);
      },
      // Easily implements debounce by providing a id for the disposer.
      // When adding disposer with the same id to the store, the previous disposer will be disposed.
      "myIdForThisDebounce"
    );
  }
}

class B implements IDisposable {
  dispose: DisposableStore;
  a = new A();
  constructor() {
    // Add initial disposables.
    this.dispose = disposable([
      // A is a disposable so it can be added to the store.
      a,
      // Add a disposer function.
      someEvent.addListener("type", event => console.log(event)),
    ]);
  }
}

const b = new B();
b.dispose(); // All side effects in both a and b are disposed

If you prefer less type annotation and more auto type inference:

import { disposable } from "@wopjs/disposable";

class A {
  dispose = disposable();
  constructor() {
    this.dispose.add(() => console.log("a"));
  }
  print() {
    console.log("print a");
  }
}

class B {
  dispose = disposable();
  // A is a disposable so it can be added to the store.
  a = this.dispose.add(new A());
}

const b = new B();
b.a.print(); // "print a"
b.dispose(); // both a and b are disposed

Features

• Non-invasive.

  • Disposable adopts both disposer function () => any and .disposer() contracts which are widely accepted. Implementing these patterns does not require any extra effort.

    // disposer function pattern
    const disposer = () => console.log("dispose");
    
    // class disposable pattern
    class MyDisposable {
      dispose() {
        console.log("dispose");
      }
    }
    const myDisposable = new MyDisposable();
    
    // plain object disposable pattern
    const myDisposable = {
      dispose() {
        console.log("dispose");
      },
    };

  • And of course it works well with other @wopjs libraries.

    import { addEventListener } from "wopjs/dom";
    import { timeout } from "wopjs/time";

• Compact.

  • Disposables are designed to be composable and chainable.

    import { disposable, type IDisposable } from "@wopjs/disposable";
    
    class A implements IDisposable {
      dispose = disposable();
      constructor() {
        this.dispose.add(() => console.log("a"));
      }
      print() {
        console.log("print a");
      }
    }
    
    class B implements IDisposable {
      dispose = disposable();
      a = this.dispose.add(new A());
    }
    
    const b = new B();
    b.a.print(); // "print a"
    b.dispose(); // both a and b are disposed

  • You can also create your own side effects in a compact way.

    import { disposable } from "@wopjs/disposable";
    
    class A {
      dispose = disposable();
      constructor() {
        dispose.make(() => {
          const handler = () => console.log("click");
          someEvent.on("type", handler);
          return () => someEvent.off("type", handler);
        });
      }
    }
    
    const a = new A();
    a.dispose(); // clear all disposers

• Refresh-able

  • Disposables can use id as key when adding to the store. Adding a disposable with the same id will dispose (flush) the old one first.

    import { disposable } from "@wopjs/disposable";
    import { addEventListener } from "@wopjs/dom";
    import { timeout } from "@wopjs/time";
    
    const dispose = disposable();
    dispose.add(
      addEventListener(window, "click", event => {
        // Clicking within 1s will trigger debounce effect (the pending timeout is cancelled before adding the new one).
        dispose.add(
          timeout(() => console.log(event), 1000),
          "myId"
        );
      })
    );

• Small footprint.

  • Designed and implemented with efficiency and ergonomics in mind, not only the (minified) bundle size is less than 1kb, using this library also enables patterns that require way less code to manage side effect disposers.

Concepts

Disposable

A disposable is an object that has a dispose method. The dispose method is used to dispose the object, which means to clean up any resources it holds.

// class disposable
class MyDisposable {
  dispose() {
    console.log("clean up");
  }
}
const myDisposable = new MyDisposable();

// plain object disposable
const myDisposable = {
  dispose() {
    console.log("clean up");
  },
};

Disposer

A disposer is a function that disposes a disposable. It is usually created by a factory function, which is called a disposer factory.

const addListener = (target, type, listener) => {
  target.addEventListener(type, listener);
  // disposer function
  return () => target.removeEventListener(type, listener);
};

const disposer = addListener(window, "click", () => console.log("click"));

To make it easier to work with TypeScript, makeDisposable is provided to create a disposable disposer.

import { makeDisposable } from "@wopjs/disposable";

const addListener = (target, type, listener) => {
  target.addEventListener(type, listener);
  return makeDisposable(() => target.removeEventListener(type, listener));
};

DisposableStore

A disposable store is a disposable that manages disposables.

import { disposable } from "@wopjs/disposable";

const store = disposable();
store.add(() => console.log("disposer"));
store.make(() => {
  return () => console.log("disposable");
});
store.dispose(); // Logs "disposer" and "disposable"

It is also a disposer! So that it can be easily composed with other disposers.

import { disposable, type IDisposable } from "@wopjs/disposable";

class A implements IDisposable {
  dispose = disposable();
  constructor() {
    this.dispose.add(() => console.log("a"));
  }
  print() {
    console.log("print a");
  }
}

class B implements IDisposable {
  dispose = disposable();
  a = this.dispose.add(new A());
}

const b = new B();
b.a.print(); // "print a"
b.dispose(); // both a and b are disposed

DisposableDisposer

A disposable disposer is both a disposer an a disposable.

This pattern is useful for library authors who want to create disposers that are compatible to the majority of frameworks.

const addListener = (target, type, listener) => {
  target.addEventListener(type, listener);
  const disposer = () => target.removeEventListener(type, listener);
  disposer.dispose = disposer;
  return disposer;
};

const dispose = disposable();
dispose.add(addListener(window, "click"));

Abortable

Abortable is a special kind of disposable that can be disposed outside of the store (like when setTimeout or once event finishes). It will notify the store to delete itself from the store when disposed. The signature is the same as a disposable disposer so it is also compatible to the majority of frameworks.

const timeout = (handle, timeout) => {
  let id;
  const disposer = abortable(() => clearTimeout(id));
  id = setTimeout(() => {
    handler();
    disposer();
  }, timeout);
  return disposer;
};

const dispose = disposable();
dispose.add(timeout(() => console.log("timeout"), 1000));

License

MIT @ wopjs