events-to-async

Treat EventEmitter-like object using Async/Await or Async Iterator.

Similar one of Node.js events.on and event.once, but it is generic.

Features

• events to Async Iterator
• once event to a Promise
• support EventEmitter-like libraries
  • events.on and event.once only support events
• LightWeight: ~1kb (gzip)

Install

Install with npm:

npm install events-to-async

Usage

once an event to Promise

import { EventEmitter } from "events";
import { on } from "events-to-async";

const events = new EventEmitter();
setTimeout(() => {
    events.emit("change", 1);
});
const event = await once((handler) => events.once("change", handler));
console.log(event); // => [1]

on events to AsyncIterator

import { EventEmitter } from "events";
import { on } from "events-to-async";

const events = new EventEmitter();
const asyncIterator = on((handler) => {
    event.on("change", handler); // Listen
    return () => {
        // This function is called on occuring error or `break;`
        event.off("change", handler); // UnListen
    }
});
setTimeout(() => {
    events.emit("change", 1);
    events.emit("change", 2);
    events.emit("change", 3);
});
for await(const event of asyncIterator) {
    console.log(event); // [1] → [2] → [3]
}
// Unreachable here

You can stop the async iterator by using break;

import { EventEmitter } from "events";
import { on } from "events-to-async";

const events = new EventEmitter();
const asyncIterator = on((handler) => {
    events.on("change", handler); // Listen
    return () => {
        // This function is called on occuring error or `break;`
        events.off("change", handler); // UnListen
    }
});
setTimeout(() => {
    events.emit("change", 1);
    events.emit("change", 2);
    events.emit("change", 3);
});
for await(const [num] of asyncIterator) {
    console.log(num); // 1 → 2 → 3
    if (num === 3) {
        break;
    }
}
console.log("4!!!"); 

AbortController supports

You can cancel events using AbortController.

• Browser: Modern browsers supports
• Node.js 15+: supports
  • Node.js 14 requires polyfills
  • abort-controller - npm
  • node-abort-controller - npm

once an event with cancel

import { EventEmitter } from "events";
import { on } from "events-to-async";

const events = new EventEmitter();
const abortController = new AbortController();
const event = once((handler) => {
    event.once("change", handler);
    return () => {
        event.off("change", handler);  // call it when occur error or abort
    }
}, { signal: abortController.signal });
// Abort
abortController.abort();
await event; // => throw Abort Error

on events with cancel

import { EventEmitter } from "events";
import { on } from "events-to-async";

const events = new EventEmitter();
const abortController = new AbortController();
const asyncIterator = on((handler) => {
    events.on("change", handler);
    return () => {
        events.off("change", handler);
    }
}, { signal: abortController.signal });
// Abort
abortController.abort();

TypeScript supports

on<T> and once<T> support generics that represent iterated value.

:memo: on<T> and once<T> always return an array

import { EventEmitter } from "events";
import { on } from "events-to-async";

const events = new EventEmitter();
type Event = number;
const asyncIterator = on<[Event]>((handler) => {
    events.on("change", handler);
    return () => events.off("change", handler)
});
setTimeout(() => {
    events.emit("change", 1);
    events.emit("change", 2);
    events.emit("change", 3);
});
for await(const event of asyncIterator) {
    console.log(event); // [1] → [2] → [3]
}

Yet another EventEmitter supports

This library aim to support yet another events module like eventmit.

import { eventmit } from "eventmit";
import { on } from "events-to-async";

type Event = { key: string };
const events = eventmit<Event>();
const asyncIterator = on<[Event]>((handler) => {
    events.on(handler);
    return () => events.off(handler);
});
setTimeout(() => {
    events.emit({ key: "value" });
});
for await (const event of asyncIterator) {
    assert.deepStrictEqual(event, [{ key: "value" }]);
    break;
}

Changelog

See Releases page.

Running tests

Install devDependencies and Run npm test:

npm test

Contributing

Pull requests and stars are always welcome.

For bugs and feature requests, please create an issue.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Author

• azu: GitHub, Twitter

License

MIT © azu

Related

• Node.js events.on and event.once: https://github.com/nodejs/node/blob/master/lib/events.js
• Async Iterable EventEmitter.on(emitter, "event") · Issue #27847 · nodejs/node
• rolftimmermans/event-iterator: Convert event emitters and event targets to ES async iterators