js-events

Events for push-flow abstractions.

$3

``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 {}

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

// Allow caller to customise the detail type
class Event4 extends AbstractEvent {}

// When you need to customise the constructor signature
class Event5 extends AbstractEvent {
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.

$3

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
`

$3

`sh
npm run docs
`

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

$3

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
``