mapped-disposable v1.0.3

MappedDisposable

Map-flavoured alternative to Atom's CompositeDisposable class. Intended for use in Atom package development, but compatible with any project that uses event-kit.

Usage

This class simplifies scenarios when multiple Disposable instances are grouped together and referenced by name. The existing practice was to create multiple CompositeDisposable objects, each bound to a different property or variable name:

let editorDisposables = new CompositeDisposable();
let projectDisposables = new CompositeDisposable();
let paneDisposables = new CompositeDisposable();

With a MappedDisposable, disposable groups become easier to manage:

let disposables = new MappedDisposable();
disposables.set("editor", new CompositeDisposable());
disposables.set("project", new CompositeDisposable());
disposables.set("pane", new CompositeDisposable());

disposables.add("editor", editor.onDidChange(…));
disposables.add("project", project.onDidChangePaths(…));

Entries can be disposed of individually or altogether:

disposables.dispose("editor"); // Dispose only editor-related disposables
disposables.dispose();         // Dispose of everything

A MappedDisposable operates just like an ordinary Map. Anything works as an entry key (not just strings), and values can be queried using the has() and get() methods that you're used to:

const packageObject = atom.packages.getActivePackage("file-icons");
disposables.add(packageObject, new Disposable(…));
disposables.get(packageObject); // => CompositeDisposable;

API

Constructor

new MappedDisposable([iterable])

Create a new instance, optionally with a list of keys and disposables.

new MappedDisposable([ [key1, disp1], [key2, disp2] ]);

Instance methods

dispose(...keys)

Delete keys and dispose of their values.

If passed no arguments, the method disposes of everything, rendering the MappedDisposable instance completely inert. Future method calls do nothing.

add(key, [...disposables])

Add one or more disposables to a key's disposables list

remove(key, [...disposables])

Remove one or more disposables from a key's disposables list.

If no disposables are passed, the object itself is removed from the MappedDisposable. Any disposables keyed to it are not disposed of.

delete(key, [...disposables])

Alias of remove(), included for parity with Map objects.

clear()

Clear the contents of the MappedDisposable.

Individual disposables are not disposed of.

has(key)

Returns: Boolean

Determine if an entry with the given key exists in the MappedDisposable.

get(key)

Returns: CompositeDisposable | undefined

Retrieve the disposables list keyed to an object.

If the MappedDisposable has been disposed, the method returns undefined.

set(key, value)

Replace the disposable that's keyed to an object.

A TypeError is thrown if the value argument lacks a dispose method.

Instance properties

disposed

Default: false
Type: Boolean

Whether the instance has been irrevocably disposed of.

size

Default: 0
Type: Number
Read-only

Number of entries (key/disposable pairs) stored in the instance.