Listeners

New event listeners can be registrated by using either listen or register. There is no significant difference except usage:

listen.ts
herald.listen({
    event: 'event',
    subscription: () => {
        console.log('Event fired!');
    },
})

register.ts
herald.register("event", () => {
    console.log('Event fired!');
});

For some cases it is better to have a function that accepts an object: it's more robust, flexible and easier to maintain. But takes more space when used. As an alternative you can use register which will result in smaller size but might be harder to maintain, if, for example, new version introduces another parameter which will change order of the arguments.

Registration parameters

Registration accepts quite a few parameters, to make sure you have control over you event.

event* - name of the event

subscription* - methods/methods to execute when event fires. You can pass it in few ways:

string - just the name of the method to execute (like "onClick") which must be combined with constraint

herald.listen({
    event: 'event',
    subscription: 'onClick',
    constraint: onClickHandlerObject,
})

function - normal function, potentially accepting the event

herald.listen({
    event: 'event',
    subscription: (e: CustomEvent) => {},
})

object - object defining details of event execution like priority

herald.listen({
    event: 'event',
    subscription: {
        method: () => {},
        priority: 0,
        constraint: "boardmeister/router",
        anchor: document.createElement('div'),
    },
})

array - an array of subscription objects

herald.listen({
    event: 'event',
    subscription: [
        {
            method: () => {},
            priority: 0,
            constraint: "boardmeister/router",
            anchor: document.createElement('div'),
        }, {
            method: () => {},
        }, {
            method: () => {},
            priority: 20,
            anchor: null,
        }
    ],
})

Registration object

Registration object is probably the most important part of registration as it allows you to set multiple listeners on single event and decide on their priority among other things.

import { OptionalSubscription } from "@boardmeister/herald";

const minimalSubscriptionObject: OptionalSubscription = {
    method: (e: CustomEvent): Promise<void> => {
        console.log('Event fired!');
    },
}

const maximalSubscriptionObject: OptionalSubscription = {
    method: (e: CustomEvent): Promise<void> => {
        console.log('Event fired!');
    },
    priority: 20,
    constraint: "boardmeister/plugin",
    anchor: document.createElement('div'),
}

`method`*

Method is a required parameter of the object, one that defines the behavior of the listener. It can be either string or a function, where if string was passed you also have to define constraint.

Marshal integration

Herald was created as a part of Marshal library, as a was for better communication between plugins. Each time you see a constraint it means it is a part of that integration.

`priority`

One of the core functionalities of this library is ability to set order of your listeners. This is the place to do it. It can be any number - negative, decimal, zero - will be placed properly in the queue. Although events which fire on the same time are sorted by the time of registration - who was quicker will be fired first.

`constraint`

Cen be either string or object - will be used to execute the listener when method was passed as a string. As mentioned before this is a part of integration with Marshal library to allow registration of event listeners that don't exist of the time of registration.

`anchor`

Used when preforming localized events, accepts any document Node which will be used as a reference of where in the page, this listener is listening. Events fired in specific places in document, are filtered based on the position. If this isn't empty than this event listener will be partaking in the filtration. Overwrites the anchor from the method.

Register multiple events

For cases when you have multiple events you want to listen to, there is batch method.

herald.batch([
    {
        event: 'event',
        subscription: () => {},
    },
    {
        event: 'event',
        subscription: () => {},
        constraint: null,
        sort: true,
        symbol: null,
        anchor: null,
    },
])

It is quite literally an array of listen methods. All the parameters work the same so for detailed explanation go back to the first paragraph.

How to remove the listener

There are two options: either you pass your own identifying symbol when registrating and pass it along or use generated function returned by registration methods (listen, register and batch).

Owned identifier

You can use your own symbol to use for registration and removal. To do so you have to pass it during registration and use unregister later:

const myIdSymbol = Symbol('event-symbol');
herald.listen({
    event: 'my-event',
    subscription: () => {},
    symbol: myIdSymbol,
});
herald.unregister('my-event', myIdSymbol);

Be aware!

Be aware if you register two different listeners with the same symbol for the same event, unregister will remove both of them

const myIdSymbol = Symbol('event-symbol');
herald.listen({
    event: 'my-event',
    subscription: () => {
        console.loh('Event 1!')
    },
    symbol: myIdSymbol,
});
herald.listen({
    event: 'my-event',
    subscription: () => {
        console.loh('Event 2!')
    },
    symbol: myIdSymbol,
});
herald.unregister('my-event', myIdSymbol);

await herald.dispatch(new CustomEvent('my-event')); // No output!

Generated method

The better idea would be to use special generated functions that registration methods (listen, register and batch) return:

const unregister = herald.register('my-event', () => {
    console.log('Second event fired!')
});
const unregisterListen = herald.listen({
    event: 'my-event',
    subscription: () => {
        console.log('Event fired!')
    },
});
const unregisterBatch = herald.batch([{
    event: 'my-event',
    subscription: () => {
        console.log('Third event fired!')
    },
}]);
// Event fired!
// Second event fired!
// Third event fired!
await herald.dispatch(new CustomEvent('my-event'));
unregister();
unregisterListen();
unregisterBatch();
 // No output!
await herald.dispatch(new CustomEvent('my-event'));

Registration parameters​

Registration object​

method*​

priority​

constraint​

anchor​

Register multiple events​

How to remove the listener​

Owned identifier​

Generated method​