README.md

MappedDisposable

Map-flavoured alternative to Atom's CompositeDisposable class.

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] ]);

Parameter	Type	Default	Attributes
iterable	Any	null	Optional

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.

Parameter	Type	Default	Attributes
...keys	Any	null	Optional, variable-length

add(key, [...disposables])

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

Parameter	Type	Default	Attributes
key	Any	None	Required
...disposables	Any	None	Optional, variable-length

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.

Parameter	Type	Default	Attributes
key	Any	None	Required
...disposables	Any	None	Optional, variable-length

delete(key, [...disposables])

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

Parameter	Type	Default	Attributes
key	Any	None	Required
...disposables	Any	None	Optional, variable-length

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.

Parameter	Type	Default	Attributes
key	Any	None	Required

get(key)

Returns: CompositeDisposable | undefined

Retrieve the disposables list keyed to an object.

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

Parameter	Type	Default	Attributes
key	Any	None	Required

set(key, value)

Replace the disposable that's keyed to an object.

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

Parameter	Type	Default	Attributes
key	Any	None	Required
value	Disposable	None	Required

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.