Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/file-icons/mapped-disposable

Map-flavoured alternative to Atom's CompositeDisposable class.
https://github.com/file-icons/mapped-disposable

atom callback disposable event-kit events

Last synced: 3 days ago
JSON representation

Map-flavoured alternative to Atom's CompositeDisposable class.

Host: GitHub
URL: https://github.com/file-icons/mapped-disposable
Owner: file-icons
License: isc
Created: 2019-02-28T20:37:14.000Z (almost 6 years ago)
Default Branch: master
Last Pushed: 2020-05-08T05:32:33.000Z (over 4 years ago)
Last Synced: 2024-04-12T05:14:22.502Z (10 months ago)
Topics: atom, callback, disposable, event-kit, events
Language: JavaScript
Homepage: https://npmjs.com/package/mapped-disposable
Size: 20.5 KB
Stars: 1
Watchers: 2
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md

Awesome Lists containing this project

README

        MappedDisposable

================

[![Build status: TravisCI][TravisCI-badge]][TravisCI-link]

[![Build status: AppVeyor][AppVeyor-badge]][AppVeyor-link]

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:

~~~js

let editorDisposables = new CompositeDisposable();

let projectDisposables = new CompositeDisposable();

let paneDisposables = new CompositeDisposable();

~~~

With a `MappedDisposable`, disposable groups become easier to manage:

~~~js

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:

~~~js

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:

~~~js

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.

~~~js

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.

[Referenced links]:_________________________________________________________

[`Boolean`]:             https://mdn.io/Boolean

[`CompositeDisposable`]: https://atom.io/docs/api/latest/CompositeDisposable

[`Disposable`]:          https://atom.io/docs/api/latest/Disposable

[`Map`]:                 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map

[`Number`]:              https://mdn.io/Number

[`TypeError`]:           https://mdn.io/TypeError

[`event-kit`]:           https://npmjs.com/package/event-kit

[`remove()`]:            #remove

[AppVeyor-badge]:        https://ci.appveyor.com/api/projects/status/96j138oodm1q6txp?svg=true

[AppVeyor-link]:         https://ci.appveyor.com/project/Alhadis/mapped-disposable

[TravisCI-badge]:        https://travis-ci.org/file-icons/mapped-disposable.svg?branch=master

[TravisCI-link]:         https://travis-ci.org/file-icons/mapped-disposable