npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

circuition

v1.0.5

Published

An event emitter framework that allows you to control the full event lifecycle.

Downloads

3

Readme

circuition

codecov c1moore

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 event
  • eventHandler - 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 added
  • listener - 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 added
  • listener - 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 the eventName and a data 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:

  1. Base PRs against master
  2. Either submit a PR for an existing ticket or create a new ticket to avoid duplication of work.
  3. 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.