mini-signals/docs/README.md

signals, in TypeScript, fast

mini-signals / [Exports](modules.md)

# mini-signals

signals, in JavaScript, fast

[![NPM](https://img.shields.io/npm/v/mini-signals.svg)](https://www.npmjs.com/package/mini-signals) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Hypercubed/mini-signals/blob/master/LICENSE)

## Description

Custom event/messaging system for TypeScript/JavaScript inspired by [js-signals](https://github.com/millermedeiros/js-signals) originally based on [EventEmitter3](https://github.com/primus/eventemitter3) code base.

There are several advantages to signals over event-emitters (see [Comparison between different Observer Pattern implementations](https://github.com/millermedeiros/js-signals/wiki/Comparison-between-different-Observer-Pattern-implementations)). However, the current implementation of [js-signals](https://github.com/millermedeiros/js-signals) is (arguably) slow compared to other implementations (see [EventsSpeedTests](https://github.com/Hypercubed/EventsSpeedTests)). `mini-signals` is a fast, minimal emitter, with an API similar to [js-signals](https://github.com/millermedeiros/js-signals).

> Note: Signals here are the type defined by [js-signals](https://github.com/millermedeiros/js-signals) inspired by AS3-Signals.  They should not to be confused with [SolidJS](https://www.solidjs.com/tutorial/introduction_signals) or Angular signals.

## mini-signals 2.0.0

MiniSignals v2.0.0 has been rewritten in TypeScript and had it's API changed to improve performance and add type safety.

New features:

- `.add` now returns a weak node reference which can be used to remove the listener directly from the signal.  Reduces memory leaks.
- `.add` is now type safe.  The type of the listener is checked against the type variable in the constructor.

Breaking changes:

- `.add` now returns a node reference instead of a object, which had a `detach` method.  The node reference can be used to remove the listener directly from the signal.
- `.once` has been removed.  Use `.add` instead with a call to `.detach` in the listener.
- The `thisArg` parameter has been removed from `.add`.  Use `.add` with a call to `.bind` or use an arrow function with a closure.
- `.dispatch` now throws an error if the signal is already dispatching.

## Install

### npm:

```sh
npm install mini-signals
```

## Example Usage

```ts
import { MiniSignal } from 'mini-signals';

const mySignal = new MiniSignal<[string, string]>();  // the type variable is optional and defines the parameters to be dispatched

const binding = mySignal.add((foo: string, bar: string) => { // add listener, note the parameter types match the type variable in the constructor
  console.log('signal dispatched');
  assert(foo === 'foo');
  assert(bar === 'bar');
});

mySignal.dispatch('foo', 'bar'); // dispatch signal passing custom parameters
binding.detach(); // remove a single listener
```

## Another Example

```ts
const myObject = {
  foo: "bar",
  updated: new MiniSignal<never, typeof myObject>() // in this case the type variable is never, since we are not passing any parameters
};

myObject.updated.add(() => {
  console.log('signal dispatched');
  assert(this === myObject);
  assert(this.foo === 'baz');
}, myObject); // add listener with context

myObject.foo = 'baz';
myObject.updated.dispatch(); // dispatch signal
```

## API

See [API.md](https://github.com/Hypercubed/mini-signals/blob/master/API.md)

## License

Copyright (c) 2015-2023 Jayson Harshbarger

MIT License