# @picoware/signal

> Minimal signal/slot/observable library

Latest version **0.0.5** (published 2023-04-11) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @picoware/signal
pnpm add @picoware/signal
yarn add @picoware/signal
bun add @picoware/signal
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2023-04-11 |
| First published | 2022-06-16 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 8.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Elisabeth Rousset |
| Maintainers | erousset |

## Links

- npm: https://www.npmjs.com/package/@picoware/signal
- Repository: https://gitlab.com/erousset/picoware/-/tree/main/signal
- npm.io page: https://npm.io/package/@picoware/signal

## Recent versions

- 0.0.5 (latest) — 2023-04-11
- 0.0.4 — 2023-02-06
- 0.0.3 — 2022-08-02
- 0.0.2 — 2022-08-02
- 0.0.1 — 2022-06-16

## README

# @picoware/signal

A tiny signal library. 

[Signal programming](https://en.wikipedia.org/wiki/Signal_programming) is a particular type of [event driven programming](https://en.wikipedia.org/wiki/Event-driven_programming). This library provides: 

* signals and slots (aka. events emitting and callbacks)
* observable values with auto-emitted signals on set

This library runs both in browser and on Node.js

## Installation
```  npm install @picoware/signal```

## Usage

### Signal

#### Basic signal

Declare a new signal and register a slot (aka. callback) to it. Then the slot will be called every time the signal is emitted :
```js
let data = 0;
let signal = new Signal();
signal.on(() => { data++ });

assert.equal(data, 0);
signal.emit();
assert.equal(data, 1);
signal.emit();
assert.equal(data, 2);
```

#### Signal with parameter

You can provide a parameter when emitting a signal. The parameter will be forwarded to the slot:

```js
let data = 0;
let signal = new Signal();
signal.on((value) => { data = value });

assert.equal(data, 0);
signal.emit(3);
assert.equal(data, 3);
```

#### Signal with multiple slots
You can provide multiple slots to a signal. They will be called by order of registration:

```js
let data = 0;
let signal = new Signal();
signal.on((value) => { data = value });
signal.on(() => { data *= 2 });

assert.equal(data, 0);
signal.emit(3);
assert.equal(data, 6);
```

#### Unsubscribe

The registering function returns an unregistering function which can be called at anytime to remove the connection:

```js
    let data = 0;
    let signal = new Signal();
    let unsubscribe = signal.on(() => { data++ });

    assert.equal(data, 0);
    signal.emit();
    assert.equal(data, 1);
    unsubscribe();
    signal.emit();
    assert.equal(data, 1); // data was not increased
```

### Observable
#### Basic observable

An `Observable` contains a `value` and a signal named `changed` that is automatically emitted each time `value` is set :

```js
let computed = 0;
let observable = new Observable(1);
observable.changed.on((value) => { computed = value * 2; });

assert.equal(computed, 0); // not 2, slot hasn't been called
observable.value = 2;
assert.equal(computed, 4);
observable.value = 5;
assert.equal(computed, 10);
```

Notice that the slot is NOT called with the current value upon registration. See `subscribe` below if you need such behaviour.

#### Registration shortcut

You can use the `onChanged` shortcut instead of `changed.on` to register your slots:

```js
let computed = 0;
let observable = new Observable(1);
observable.onChanged((value) => { computed = value * 2; });

assert.equal(computed, 0); // not 2, slot hasn't been called
observable.value = 2;
assert.equal(computed, 4);
observable.value = 5;
assert.equal(computed, 10);
```

#### Registration with execution
 
You can use the `subscribe` method if you want both to:
* register your slot to an observable
* execute your slot with the current value of the observable

```js
let computed = 0;
let observable = new Observable(1);
observable.subscribe((value) => { computed = value * 2; });

assert.equal(computed, 2); // here slot has been called
observable.value = 2;
assert.equal(computed, 4);
observable.value = 5;
assert.equal(computed, 10);
```

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