# signalkit

> Signals & delegates

Latest version **1.0.3** (published 2014-11-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install signalkit
pnpm add signalkit
yarn add signalkit
bun add signalkit
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2014-11-23 |
| First published | 2013-08-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jason Frame |
| Maintainers | jaz303 |
| Keywords | signal, delegate |

## Links

- npm: https://www.npmjs.com/package/signalkit
- npm.io page: https://npm.io/package/signalkit

## Recent versions

- 1.0.3 (latest) — 2014-11-23
- 1.0.2 — 2014-10-24
- 1.0.1 — 2014-10-24
- 1.0.0 — 2014-10-24
- 0.3.0 — 2014-07-22
- 0.2.5 — 2014-07-22
- 0.2.4 — 2014-03-10
- 0.2.3 — 2013-09-07
- 0.2.2 — 2013-09-07
- 0.2.1 — 2013-09-07
- 0.2.0 — 2013-08-26
- 0.1.1 — 2013-08-26
- 0.1.0 — 2013-08-26
- 0.0.1 — 2013-08-18

## README

# signalkit

Tiny signals library. Signals are an alternative to `EventEmitter` wherein each possible event is represented by a unique object to which listeners can be attached. There are a couple of benefits to this approach:

### Anonymous signal objects can be passed around independently of their owner object

In the example below, `MyObserver` could be passed any signal at all:

    function MyObserver(signal) {
        signal.connect(function() {
            // do something
        })
    }

With `EventEmitter`, we'd need to attach to a fixed event of a given object, or pass in the event name explicitly. I find this less elegant.

    function MyObserver(obj, eventName) {
        obj.on(eventName || 'data', function() {
            // do something
        })
    }

### No subtle bugs caused by misspelt event names

    obj.on('foobar', function() { ... });
    obj.emit('foobaz'); // nothing happens

Contrast with:

    var obj = {};
    obj.foobar = new Signal();
    obj.foobar.connect(function() { ... });
    obj.foobaz.emit(); // runtime error

## Example

    var Signal = require('signalkit').Signal;
    var signal = new Signal('foo');

    var unsub1 = signal.connect(function(name) {
        console.log("handler 1: " + name);
    });

    var foo = {
        bar: function(name) {
            console.log("handler 2: " + name);
        }
    };

    var unsub2 = signal.connect(foo, 'bar');

    console.log("emit fred...");
    signal.emit("fred");

    console.log("emit bob...");
    unsub1();
    signal.emit("bob");

    console.log("emit alice...");
    unsub2();
    signal.emit("alice");

## API

### Signals

#### `var signal = new Signal(name, [parent])`

Create a new signal with a given `name` and optional `parent`. If a `parent` is specified all calls to `emit()` will propagate recursively through the parent chain.

#### `signal.connect(fn)`
#### `signal.connect_c(fn)`

Connect a supplied function so it will be called when this `Signal` is `emit`ted.

The `_c` suffixed version returns a function that can be called to cancel the connection.

#### `signal.connect(object, methodName)`
#### `signal.connect_c(object, methodName)`

Connect a supplied object/method to this `Signal`, i.e. call `object[methodName]()` when signal is emitted. The method lookup is lazy; that is, `object[methodName]` is resolved each time the signal is fired, rather than being bound at the time of connection.

The `_c` suffixed version returns a function that can be called to cancel the connection.

#### `signal.once(fn)`
#### `signal.once_c(fn)`

As per `signal.connect(fn)`, except that the function is called once and once only.

The `_c` suffixed version returns a function that can be called to cancel the connection.

#### `signal.once(object, methodName)`
#### `signal.once_c(object, methodName)`

As per `signal.connect(object, methodName)`, except that the method is called once and once only.

The `_c` suffixed version returns a function that can be called to cancel the connection.

#### `signal.emit(args...)`

Emit this signal, invoking each connected function with the given arguments. All handlers are guaranteed to fire; any errors thrown by handlers will be caught and re-raised asynchronously.

The `emit()` call will propagate recursively through the signal's parent chain.

#### `signal.clear()`

Remove all connections.

#### Error handling

You can catch - and handle - any errors thrown during event handling by overriding `signal.onError`, which receives the thrown error as an argument. Your error handler may return `false` to prevent any successive handlers from being fired. The default behaviour is to continue firing the remaining handlers and rethrow the error asynchronously.

The default error handler for all signals can be changed by setting `Signal.prototype.onError`.

## TODO

  * Async emit. Not sure if this should be specified at signal creation time or emission time.

---
_Source: https://npm.io/package/signalkit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._