circuition
v1.0.5
Published
An event emitter framework that allows you to control the full event lifecycle.
Downloads
3
Maintainers
Readme
circuition
An event emitter framework that allows you to control the full event lifecycle. This package is very simple and doesn't require any external dependencies.
Installation
npm install --save circuition
Usage
Circuition is like a typical event emitter library, except it allows you to hook into the lifecycle of an event. This gives you the ability to cancel an event before it happens and act on a successful event.
Import
TypeScript
import { Circuition, EventPayload } from 'circuition';
const circuition = new Circuition();
JavaScript
const { Circuition } = require('circuition');
const circuition = new Circuition();
registerEvent<T>(eventName: string, eventHandler: (payload: EventPayload<T>) => Promise<any>): void
Registers a new event and the handler that is executed when the event is invoked. Events must be registered before calling any other method on Circuition or an error will be thrown.
Parameters
eventName
- the name of the eventeventHandler
- the handler that performs the desired action when the event is fired
Example
circuition.registerEvent<FormData>('form:submit', async (payload: EventPayload<FormData>): Promise<void> => {
await fetch(url, {
method: 'POST',
body: JSON.stringify(payload.data),
});
});
registerBeforeListener<T>(eventName: string, listener: async (payload: EventPayload<T>) => Promise<void>): void
Registers a new before listener for the specified event. Before listeners can cancel an event by throwing an error (rejecting the returned Promise). All before listeners for an event execute in parallel, so order is not guaranteed.
Parameters
eventName
- the name of the event to which the listener should be addedlistener
- the function that will be executed before the event is fired
Example
circuition.registerBeforeListener<FormData>('form:submit', async (payload: EventPayload<FormData>): Promise<void> => {
// Check if the email is valid.
if (!emailRegex.test(payload.data?.email)) {
throw new Error('Invalid Email');
}
});
circuition.registerBeforeListener<FormData>('form:submit', async (payload: EventPayload<FormData>): Promise<void> => {
// Check if the email is taken.
const res = await fetch(url, {
method: 'POST',
body: JSON.stringify({ email: payload.data?.email }),
});
const { isTaken } = await res.json();
if (isTaken) {
throw new Error('Email address already taken.');
}
});
registerAfterListener<T>(eventName: string, listener: async (payload: EventPayload<T>) => Promise<void>): void
Registers a new after listener for the specified event. After listeners are only executed if the event as fired and successfully completed. All after listeners for an event execute in parallel, so order is not guaranteed.
Parameters
eventName
- the name of the event to which the listener should be addedlistener
- the function that will be executed after the event has successfully completed
Example
circuition.registerAfterListener<FormData>('form:submit', async (payload: EventPayload<FormData>): Promise<void> => {
window.location.replace(accountPage);
});
circuition.registerAfterListener<FormData>('form:submit', async (payload: EventPayload<FormData>): Promise<void> => {
await externalTracker.track('signup', payload.data);
});
invokeEvent<T>(payload: EventPayload<T>): Promise<void>
Invokes the action specified in the payload. This will cause the entire event lifecycle to trigger (i.e. before listeners will be invoked, then the event handler, and finally the after listeners).
Parameters
payload
- the EventPayload associated with the event. This object contains theeventName
and adata
object.
Example
circuition.invokeEvent<FormData>({
eventName: 'form:submit',
data: formData,
});
Testing
To run the tests for this project, just execute
npm test
To see a coverage report, check at the Codecov report.
Debugging
To help with debugging, Circuition can be passed a flag to enable logging and a custom logger (optional).
// Use default logger (console).
const circuition = new Circuition(true);
// Use winston
const winston = require('winston');
const logger = winston.createLogger({
level: 'debug',
});
const circuition = new Circuition(true, logger);
Contributing
What to contribute? Awesome! Pull requests are always welcome. If you'd like to contribute, please follow these simple rules:
- Base PRs against
master
- Either submit a PR for an existing ticket or create a new ticket to avoid duplication of work.
- Make sure to add any necessary tests and documentation for your changes.
Credit
This library is strongly based on Twilio's Action Framework for Twilio Flex. This framework has been very powerful while developing Flex plugins, but does not appear to be widely available outside of the Flex UI. While developing this library, I took the opportunity to address some of the parts of the Actions Framework I felt were a little off, like prepending before
and after
to the name of an event to hook into the action's lifecycle.