Pulse

# Introduction

# Events

Events are handy for emitting UI updates and passing data with them. Both core functions and components can subscribe to events.

A prime example for when to use events would be showing an alert dropdown inside your app. Your core can emit the event and a top-level component can listen and render alert dropdown with a message.

const App = new Pulse();

const ALERT = App.Event();

TypeScript: Payload Type

Events support an optional generic parameter for the payload type, providing typesafety and VScode intellisense when using your Event.

const ALERT = App.Event<{ message: string }>();

# Configuration

Events can optionally receive a configuration object as the first and only parameter.

const ALERT = App.Event({ enabled: false });

All config parameters (optional)

property type description default
name? string The name of this Event, if Event is defined within an EventGroup it will inherit the key name. N/A
maxSubs? number Set a maximum amount of subscribers to listen to this event. N/A
enabled? boolean Enable/disable Event, will block emitting if disabled. true
disableAfterUses? number If set, Event will be set to enabled: false once amount of uses is met. N/A
throttle? number Time in milliseconds to throttle emitting this Event N/A
queue? number For use in conjunction with throttle, will add emit calls to a queue N/A

# Emitting

Events can be emitted from anywhere in your application, from your core to your components themselves, though usually the best usage is from the core.

ALERT.emit({ message: 'notify events best events!' });

The only parameter of the Event.emit() function is an optional payload.

# Listening

There are two ways to listen to events, firstly using Event.on() and secondly using the useEvent() hook for React which can be imported from Pulse.

ALERT.on(payload => {
    // do something
});

The Event.on() function returns a cleanup function, which should be used inside components to cleanup when the component unmounts. Most frameworks will complain if you do not cleanup listeners inside your components when they unmount.

const cleanup = ALERT.on(payload => {});

cleanup();

This syntax is bulky considering you must invoke the cleanup function on component unmount, so with React the useEvent() hook will cleanup for you!

import React from 'react';
import { useEvent } from '@pulse/react';

export function MyComponent() {
	useEvent(ALERT, payload => {
		// do anything
	});
	return <div></div>;
};

Eventually we will implement similar support for Vue components.

# Event Groups

In some cases you might want a cleaner way to define a group of Events at the same time. They are not related to each other in any way other than defining them with a cleaner syntax. Event Groups also assign the name property automatically.

const events = App.EventGroup(Event => ({
	JUST_AN_EVENT: Event(),
	ALERT: Event<{ message: string }>({ throttle: 100 })
}));

# useEvent()

This is a React hook for functional components that allows you to use an Event with automatic cleanup

import React from 'react';

export function MyComponent(props) {
	
	useEvent(events.ALERT, () => {
		// do something
	})

	return <div></div>
}

In this example events is referencing the EventGroup created above, however usually this would be located inside your Core.

This is a really handy syntax for using Events and we'd recommend all React users.

# Importing Events

It's best practice to export your Events in your Core object, so they can easily be used within your components.

You might want to make your events global to your core, such as core.events, or maybe you'll put them in your Controllers core.accounts.events.MY_EVENT. It's up to you!

← Snippets →