# @matrixai/events

> Events for push-flow abstractions

Latest version **4.0.1** (published 2025-02-04) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @matrixai/events
pnpm add @matrixai/events
yarn add @matrixai/events
bun add @matrixai/events
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.1 |
| Published | 2025-02-04 |
| First published | 2023-08-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 53.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Matrix AI |
| Maintainers | brianbotha74, cmcdragonkai, matrixai-bot |

## Links

- npm: https://www.npmjs.com/package/@matrixai/events
- Repository: https://github.com/MatrixAI/js-events
- Homepage: https://github.com/MatrixAI/js-events#readme
- Issues: https://github.com/MatrixAI/js-events/issues
- npm.io page: https://npm.io/package/@matrixai/events

## Recent versions

- 4.0.1 (latest) — 2025-02-04
- 4.0.0 — 2024-05-14
- 3.2.3 — 2023-10-11
- 3.2.0 — 2023-09-20
- 3.1.0 — 2023-09-19
- 3.0.2 — 2023-09-03
- 3.0.1 — 2023-09-01
- 3.0.0 — 2023-08-31
- 2.0.2 — 2023-08-30
- 1.0.0 — 2023-08-28

## README

# js-events

Events for push-flow abstractions.

### `AbstractEvent`

```ts
// For when you just want a regular event without `detail`
// Note that the `detail` type is `undefined`, unlike `CustomEvent`
class Event1 extends AbstractEvent {}

// For when you want a event with `detail`
class Event2 extends AbstractEvent<string> {}

// Allow caller to customise the `detail` type
// Note that the `detail` type is `unknown`
// This would be rare to use, prefer `Event4`
class Event3<T> extends AbstractEvent<T> {}

// Allow caller to customise the `detail` type
class Event4<T extends Event = Event> extends AbstractEvent<T> {}

// When you need to customise the constructor signature
class Event5 extends AbstractEvent<string> {
  constructor(options: EventInit & { detail: string }) {
    // Make sure you pass `arguments`!
    super(Event5.name, options, arguments);
  }
}
```

When redispatching an event, you must call `event.clone()`. The same instance cannot be redispatched. When the event is cloned, all constructor parameters are shallow-copied.

### `Evented`

We combine `Evented` with `AbstractEvent` to gain type-safety and convenience of the wildcard any handler.

```ts
class EventCustom extends AbstractEvent {}

interface X extends Evented {}
@Evented()
class X {}

const x = new X();

// Handle specific event, use the `name` property as the key
x.addEventListener(EventCustom.name, (e) => {
  console.log(e as EventCustom);
});

// Handle unhandled events
x.addEventListener(EventDefault.name, (e) => {
  // This is the wrapped underlying event
  console.log((e as EventDefault).detail);
});

// Handle all events
x.addEventListener(EventAll.name, (e) => {
  // This is the wrapped underlying event
  console.log((e as EventAny).detail);
});
```

You can use this style to handle relevant events to perform side-effects, as well as propagate upwards irrelevant events.

Note that some side-effects you perform may trigger an infinite loop by causing something to emit the specific event type that you are handling. In these cases you should specialise handling of those events with a `once: true`  option, so that they are only handled once.

```ts
x.addEventListener(EventInfinite.name, (e) => {
  console.log(e as EventInfinite);
  performActionThatMayTriggerEventInfinite();
}, { once: true });
```

This will terminate the infinite loop on the first time it gets handled.

Therefore it is a good idea to always be as specific with your event types as possible.

Furthermore any unhandled rejections or uncaught exceptions will be redispatched as `EventError`. However if there's no listener registered for this, it will be thrown up as an uncaught exception.

## Installation

```sh
npm install --save @matrixai/events
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run ts-node
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-events/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```

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