// Essential imports
import { eventMap, emit, on, off } from 'eventhoven';

// Event-map declaration
const emojiEvents = eventMap({
  // key - event name,
  // function arguments - event arguments,
  // function body - default handler for the event
  // (leave emtpy if you need to just declare the event)
  '👩'(context, emoji: '👨' | '👩') {},
  '🌈'(context, emoji: '🦄' | '🌧') {},
  '🎌'(context, emoji: '👘' | '🍣' | '🚗', amount: number) {},
});

on(emojiEvents)('🎌')(
  (context, emoji, amount) => console.log(`Yay!, ${amount} ${emoji}-s from ${context.event}!`)
);

on(emojiEvents)('🎌')(
  // Returning promises is also allowed (example API from http://www.sushicount.com/api)
  (context, emoji, amount) => fetch('http://api.sushicount.com/add-piece-of-sushi/')
    .then(_ => _.json())
    .then(resp => console.log(`Yay!, ${resp.pieces_of_sushi} ${emoji}-s loaded from sushicount!`))
);

// It's possible to await execution of all event handlers too
await emit(emojiEvents)(
  // Autocomplete for event names here!
  '🎌'
)(
  // Autocomplete for arguments here!
  '🍣', 10
);
// Console output:
// => Yay!, 10 🍣-s from 🎌!
// => Yay!, 11 🍣-s loaded from sushicount!

import { eventMap, emit, on, off } from 'eventhoven';

type Todo = { done: boolean; text: string; };

const todos: Todo[] = [];

// Event-map declaration
const todoEvents = eventMap({
  // key - event name,
  // first argument (context) - event contxext
  // function arguments - event arguments,
  // function body - default handler for the event
  // (leave emtpy if you need to just declare the event)
  'add-todos'(context, todos: Todo[], ...newTodos: Todo[]) {
    // Typically, a default handler is used to compose events from other event managers here.
    // But we'll just implement a simple todo-app for now
    todos.push(...newTodos);
  },
  'done-change'(context, todo: Todo, newDone: boolean) {
    todo.done = newDone;
  },
  'text-change'(context, todo: Todo, newText: string) {
    todo.text = newText;
  },
});

const emitTodo = emit(todoEvents);

const unsubFromAddTodos = on(todoEvents)('add-todos')(
  // Parameter types are inferred here
  (context, todos, ...newTodos) => newTodos.forEach(todo => console.log(
    `Wow, new todo added - "${todo.text}"!`,
    todo.done ? `And it's done already!` : 'Need to do it!'
  ))
);

const addTodos = emitTodo('add-todos');

addTodos(
  todos,
  { text: 'learn fp', done: true },
  { text: 'publish a cool event manager', done: true },
);
// => Wow, new todo added - "learn fp"! And it's done already!
// => Wow, new todo added - "publish a cool event manager"! And it's done already!

// Unsubbed the wow-ing console.log from the event
unsubFromAddTodos();

addTodos(
  todos,
  { text: 'buy milk', done: false }
);
// nothing happens in the console now

console.log(todos);
// => [
//   { text: 'learn fp', done: true },
//   { text: 'publish a cool event manager', done: true },
//   { text: 'buy milk', done: false }
// ]

const changeText = emitTodo('text-change');
const changeDone = emitTodo('done-change');

changeText(todos[2], 'write documentation');

changeDone(todos[2], true);

console.log(todos);
// => [
//   { text: 'learn fp', done: true },
//   { text: 'publish a cool event manager', done: true },
//   { text: 'buy milk', done: true }
// ]

eventMap(events)

Creates an event-map from event signatures.

Parameters:

Returns: TEventMap

This function is the main "entry point" to the whole event management pipeline. It constructs a base storage for events and their handlers, which is then used by all of the other functions.

In other words, to start working with events in eventhoven you start by creating an event-map:

import { eventMap } from 'eventhoven';

// `keyboardEvents` should now be used for all event interactions
const keyboardEvents = eventMap({
  keyup(context, e: KeyboardEvent) {},
  keydown(context, e: KeyboardEvent) {},
  keypress(context, e: KeyboardEvent, modifier?: string) {
    // This is a default handler for the event,
    // it's always executed when the event is invoked
    console.log('modifier:', modifier);
  },
});

In this example, keys in keyboardEvents correspond to event names ('keyup', 'keydown', etc.) and values contain handler maps and amount (and types) of arguments for a given event.

Event handler

As stated earlier, event signatures are read from the default event handlers in the event-map.

Any event handler has a following signature:

(context: TEventContext, ...args: any[]) => unknown | Promise<unknown>

Parameters:

Returns: any value or a promise with any value.
The type of said value is determined by the default handler in the event-map, or remains unknown.

const map = eventMap({
  // An event handler that returns a number
  numberEvent(context): number {
    // The default is 42
    return 42;
  }
});

// Type is usually inferred automatically
const result: number[] = await emit(map)('numberEvent')();

console.log(result); // => [42]

// Let's add another handler to the mix
on(map)('numberEvent')(ctx => 43);

const result2 = await emit(map)('numberEvent')();

console.log(result2); // => [42, 43]

Event context

You've probably noticed by now, that all event handlers have a first context parameter.

This is the event context that's provided by eventhoven, and it is an object of the following signature:

const map = eventMap({
  eventName(context) {
    console.log(context.event); // => "eventName"
    console.log(typeof context.unsubscribe); // => "function"
  }
});

emit(eventMap)(event)(...args): Promise<void>

Creates event emitters for an event-map.
If an event does not exist, it will be ignored.

Note, that the function is curried, which means that it must be called partially

Parameters:

Returns: Promise<void> - a promise that is resolved when all event handlers have finished their execution

emitAll(eventMap)(eventArgs): object

Emits all events in an event map.

Note, that the function is curried, which means that it must be called partially

Parameters:

Returns: Record<keyof M, Promise<void>> - a map for all events' emits promises (each will resolve upon all event handlers' resolution).

subscribe(eventMap)(event)(...handlers): () => void

Creates event subscribers for an event in an event-map.
If an event does not exist, it will be ignored.

Note, that the function is curried, which means that it must be called partially

Parameters:

Returns: () => void - a function that unsubscribes the handler from the event

Alias: on

subscribeToAll(eventMap)(...handlers)

Subscribes handler(s) to all events in an event map.

Note, that the function is curried, which means that it must be called partially

Parameters:

Returns: void

Alias: onAll

unsubscribe(eventMap)(event)(...handlers)

Unsubscribes handlers from events of an event-map.
If an event does not exist, it will be ignored.

Note, that the function is curried, which means that it must be called partially

Parameters:

Returns: void

Alias: off

unsubscribeFromAll(eventMap)(...handlers)

Unsubscribes handler(s) from all events in an event map.

Note, that the function is curried, which means that it must be called partially

Parameters:

Returns: void

Alias: offAll

once(handler): handler

Makes a handler being called only once upon the subscribed event invocation.
Should be used with subscribe to reduce boilerplate for one-time handlers.

Parameters:

Returns: handler - a changed handler that was passed in

Usage example:

on(eventmap)('some-event')(once((ctx, arg) => {
  console.log('This handler will only be called once!');
}));

wait(eventMap)(event): Promise<args[]>

Allows to wait for an event without the need for callbacks.

Note, that the function is curried, which means that it must be called partially

Basically, promise-style subscribe with the once flag.
It is a way to block execution flow until some event occurs.

Parameters:

Returns: Promise<Array<unknown>> (contextual) - a promise with array of parameters passed to the event.

import { wait } from 'eventhoven';

const keydown = wait(keyboardEvents)('keydown');

//... some time later in async context

// Resolves upon the first 'keydown' event emit
// Returns a tuple of arguments that would otherwise go to the handler
// (excluding the context)
const [e] = await keydown;
console.log(e);
// => KeyboardEvent {}

harmonicWait(eventMap)(event)(): Promise<args[]>

Same as wait, but returns a promise factory instead of a plain promise.

Note, that the function is curried, which means that it must be called partially

Useful due to having the same signature as emit, subscribe and unsubscribe, which allows for an easier composition of waiters.

Parameters:

Returns: () => Promise<Array<unknown>> (contextual) - a promise factory with array of parameters passed to the event.

import { harmonicWait } from 'eventhoven';

// Function that initiates a waiter
const waitForKeydown = harmonicWait(keyboardEvents)('keydown');

//... some time later in async context

// Resolves upon the first 'keydown' event emit
// since the call of the `waitForKeydown`
const [e] = await waitForKeydown();
console.log(e);
// => KeyboardEvent {}

debug(isEnabled)

Sets the debug mode.

Parameters:

Returns: void

When debug mode is enabled, all emits, subscribes and unsubscribes are logged to the console in a following format (default):

MM:SS.fff [{event-type} {event-name}]: {event-handler-or-params}

Where:

• {event-type} - type of the event
• {event-name} - name of the event
• {event-handler-or-params}
  • the handler for the event (when subscribing or unsubscribing)
  • params of the event (when emitting)

Example:

import { emit, debug } from 'eventhoven';

debug(true);

emit(emojiEvents)('🎌')('🍣', 10);

// logs:
// 59:05.512 [EMIT "🎌"]: [🍣, 10]

If an event does not exist in an event-map, the log will contain (INVALID) mark:

import { emit, debug } from 'eventhoven';

debug(true);

// event "😎" doesn't exist in the `emojiEvents` map
emit(emojiEvents)('😎')('🍣', 10);

// logs:
// 59:05.512 [EMIT "😎" (INVALID)]: [🍣, 10]

Custom logging function

If you want coloring or some other features - pass a custom logging function to the customDebug factory. It accepts a function of the same signature as any other event handler:

import { customDebug, TLogHandler, emit } from 'eventhoven';

// Let's say we want warnings instead of logs
const customLogFunction: TLogHandler = (ctx, ...args) => console.warn('custom!', ctx.event, ...args);

const debug = customDebug(customLog);

// Then use your custom debug function exactly like the default one:
debug(true);

emit(emojiEvents)('🎌')('🍣', 10);

// logs:
// custom! EMIT [object Object] 🎌 [🍣, 10]

Collections

eventhoven provides a way to group your event-managing needs using collections.

Parameters:

Return: A map of event names to the action for that event name.

Currently available collections are:

import {
  eventMap,
  emitCollection,
  subscribeCollection,
  unsubscribeCollection,
  eventCollection
} from 'eventhoven';

const myEvents = eventMap({
  event1() {},
  event2(ctx, arg1: number, arg2: string) {},
  event3(ctx, arg: boolean) {},
});

const emit = emitCollection(myEvents);

emit.event1();// => Promise<void>
emit.event2(12, 'some string');// => Promise<void>
emit.event3(true);// => Promise<void>

const on = subscribeCollection(myEvents);
const handler = (ctx, arg: boolean) => console.log(arg);

on.event3(handler);

const off = unsubscribeCollection(myEvents);

off.event3(handler);

const myCollection = eventCollection(myEvents);
// The same as
/*
const myCollection = {
  emit: emitCollection(myEvents),
  subscribe: subscribeCollection(myEvents),
  unsubscribe: unsubscribeCollection(myEvents)
};
*/

myCollection.emit.event1();// => Promise<void>
myCollection.emit.event2(12, 'some string');// => Promise<void>
myCollection.emit.event3(true);// => Promise<void>

myCollection.subscribe.event3(handler);
myCollection.unsubscribe.event3(handler);

Meta-Events (Plugin API)

It's also possible to write custom plugins for eventhoven thanks to meta-events!

Meta-events is a simple event-map with events for internal eventhoven actions, like emit.
One can subscribe to these events to execute some actions or emit these events to emulate them for the eventhoven.

The simplest possible plugin is already written for you - the debug plugin.
It can be used as an example for writing your own plugins for eventhoven!

Note:

• A meta-event is always emitted before the event itself happens.
• Any meta-event that returns a promise is going to be executed in parallel with the handlers for the event itself.

Current list of all meta-events is as follows:

This list is also described as a const enum EMetaEvents.

Simple example:

import { metaEvents, EMetaEvents, on } from 'eventhoven';

on(metaEvents)(EMetaEvents.EMIT)(
  (ctx, eventMap, eventName, eventArgs) => console.log(
    `This handler will be executed when ANY event is emitted, for example ${eventName}!`
  )
);

Class API

Even though eventhoven is functional in its nature, nothing prohibits to use it in Object-Oriented way.
Class API can help with this:

import { Eventhoven } from 'eventhoven';

const myEventManager = new Eventhoven({
  myEvent1(ctx, arg: string) {
    console.log('yay, my oop event!', arg);
  }
});

myEventManager.emit('myEvent1', 'first emit');
// => yay, my oop event! first emit

myEventManager.on('myEvent1', (ctx, arg) => {
  console.log('another handler!', arg);
});

myEventManager.emit('myEvent1', 'second emit');
// => yay, my oop event! second emit
// => another handler! second emit

console.log(Object.keys(myEventManager.map));
// => ['myEvent1']

Basically, the Eventhoven class is a wrapper of eventCollection with the following properties:

It's also possible to utilize static methods of the Eventhovent class in order to use a shorter version of main API:

import { Eventhoven } from 'eventhoven';

const myEventManager = new Eventhoven({
  myEvent1(ctx, arg: string) {
    console.log('yay, my oop event!', arg);
  }
});

const myEvents = eventMap({
  someEvent(ctx, arg: boolean) {
    console.log('functional event -', arg);
  },
});

// All three methods accept an event-map or an Eventhoven instance as a first argument

// Accepting a class
Eventhoven.on(myEventManager, 'myEvent1', (ctx, arg) => {
  console.log('another handler!', arg);
});
Eventhoven.emit(myEventManager, 'myEvent1', 'static emit');
// => yay, my oop event! static emit
// => another handler! static emit

// Accepting an event-map
Eventhoven.on(myEvents, 'someEvent', (ctx, arg) => {
  console.log('another handler:', arg);
});
Eventhoven.emit(myEvents, 'someEvent', true);
// => functional event - true
// => another handler: true

Contribute

First, fork the repo and clone it:

git clone https://github.com/%your-github-username%/eventhoven.git

Then:

npm install

Then:

npm run dev

Then introduce changes and propose a PR!
I'll be happy to review it!

Something's missing or found a bug?
Feel free to create an issue! 😉