p-event

通过等待事件触发来将其转换为 Promise

当你只需要一次事件触发并希望使用 Promise 或在异步函数中等待它时，这个工具非常有用。

它适用于 Node.js 和浏览器（使用打包工具）中的任何事件 API。

如果你想获取多个独立事件的触发，可以使用 pEventIterator() 方法。Observables 也可能很有用。

安装

npm install p-event

使用方法

在 Node.js 中：

import {pEvent} from 'p-event';
import emitter from './some-event-emitter';

try {
	const result = await pEvent(emitter, 'finish');

	// `emitter` 触发了 `finish` 事件
	console.log(result);
} catch (error) {
	// `emitter` 触发了 `error` 事件
	console.error(error);
}

在浏览器中：

import {pEvent} from 'p-event';

await pEvent(document, 'DOMContentLoaded');
console.log('😎');

异步迭代：

import {pEventIterator} from 'p-event';
import emitter from './some-event-emitter';

const asyncIterator = pEventIterator(emitter, 'data', {
	resolutionEvents: ['finish']
});

for await (const event of asyncIterator) {
	console.log(event);
}

API

pEvent(emitter, event, options?)

pEvent(emitter, event, filter)

返回一个 Promise，当 emitter 触发匹配 event 的事件时该 Promise 将被解决，或者当 emitter 触发 rejectionEvents 选项中定义的任何事件时该 Promise 将被拒绝。

注意：event 是一个表示单个事件类型的字符串，例如 'data'。要监听多个事件，请传递一个字符串数组，如 ['started', 'stopped']。

返回的 promise 有一个 .cancel() 方法，调用该方法会移除事件监听器并导致 promise 永远不会被解决。

emitter

类型：object

事件发射器对象。

应该具有 .on()/.addListener()/.addEventListener() 和 .off()/.removeListener()/.removeEventListener() 方法，类似于 Node.js 的 EventEmitter 和 DOM 事件。

event

类型：string | string[]

要监听的事件名称或事件名称数组。

如果同一个事件在这里和 rejectionEvents 中都定义了，这里的定义优先。

options

类型：object

rejectionEvents

类型：string[]
默认值：['error']

将拒绝 promise 的事件。

multiArgs

类型：boolean
默认值：false

默认情况下，promise 化的函数只会返回事件回调的第一个参数，这对大多数 API 来说已经足够了。当 API 在回调中返回多个参数时，这个选项可能会很有用。启用这个选项会使函数返回回调中所有参数的数组，而不仅仅是第一个参数。这也适用于拒绝。

示例：

import {pEvent} from 'p-event';
import emitter from './some-event-emitter';

const [foo, bar] = await pEvent(emitter, 'finish', {multiArgs: true});

timeout

类型：number
默认值：Infinity

超时时间（毫秒）。

filter

类型：Function

用于接受事件的过滤函数。

import {pEvent} from 'p-event';
import emitter from './some-event-emitter';

const result = await pEvent(emitter, '🦄', value => value > 3);
// 对第一个值大于 3 的 🦄 事件做一些处理

signal

类型：AbortSignal

一个 AbortSignal 用于中止等待事件。

pEventMultiple(emitter, event, options)

等待多次事件触发。返回一个数组。

这个方法具有与 pEvent() 相同的参数和选项，并额外添加了以下选项：

options

类型：object

count

必需
类型：number

在 promise 解决之前事件需要被触发的次数。

resolveImmediately

类型：boolean
默认值：false

是否立即解决 promise。触发 rejectionEvents 中的一个事件不会抛出错误。

注意：当事件被触发时，返回的数组将被修改。

示例：

import {pEventMultiple} from 'p-event';

const emitter = new EventEmitter();

const promise = pEventMultiple(emitter, 'hello', {
	resolveImmediately: true,
	count: Infinity
});

const result = await promise;
console.log(result);
//=> []

emitter.emit('hello', 'Jack');
console.log(result);
//=> ['Jack']

emitter.emit('hello', 'Mark');
console.log(result);
//=> ['Jack', 'Mark']

// 停止监听
emitter.emit('error', new Error('😿'));

emitter.emit('hello', 'John');
console.log(result);
//=> ['Jack', 'Mark']

pEventIterator(emitter, event, options?)

pEventIterator(emitter, event, filter)

返回一个异步迭代器，允许你异步迭代 emitter 触发的 event 事件。当 emitter 触发与 resolutionEvents 中定义的任何事件匹配的事件时，迭代器结束，或者当 emitter 触发 rejectionEvents 选项中定义的任何事件时，迭代器拒绝。

这个方法具有与 pEvent() 相同的参数和选项，并额外添加了以下选项：

options

类型：object

limit

类型：number（非负整数）
默认值：Infinity

迭代器结束前的最大事件数。当达到限制时，迭代器将被标记为 done。这个选项对于分页事件很有用，例如，每页获取 10 个事件。

resolutionEvents

类型：string[]
默认值：[]

将结束迭代器的事件。

TimeoutError

暴露用于实例检查和子类化。

示例：

import {pEvent} from 'p-event';

try {
	await pEvent(emitter, 'finish');
} catch (error) {
	if (error instanceof pEvent.TimeoutError) {
		// 对超时错误执行特定操作
	}
}

前后对比

import fs from 'node:fs';

function getOpenReadStream(file, callback) {
	const stream = fs.createReadStream(file);

	stream.on('open', () => {
		callback(null, stream);
	});

	stream.on('error', error => {
		callback(error);
	});
}

getOpenReadStream('unicorn.txt', (error, stream) => {
	if (error) {
		console.error(error);
		return;
	}

	console.log('文件描述符:', stream.fd);
	stream.pipe(process.stdout);
});

import fs from 'node:fs';
import {pEvent} from 'p-event';

async function getOpenReadStream(file) {
	const stream = fs.createReadStream(file);
	await pEvent(stream, 'open');
	return stream;
}

(async () => {
	const stream = await getOpenReadStream('unicorn.txt');
	console.log('文件描述符:', stream.fd);
	stream.pipe(process.stdout);
})()
	.catch(console.error);

提示

处理以错误代码解决的调用

某些函数可能会使用单个事件来表示成功和某些错误。Promise 使得为错误事件和包含表示错误的值的成功结果提供组合错误处理器变得容易。

import {pEvent} from 'p-event';
import emitter from './some-event-emitter';

try {
	const result = await pEvent(emitter, 'finish');

	if (result === 'unwanted result') {
		throw new Error('Emitter 以错误结束');
	}

	// `emitter` 触发了带有可接受值的 `finish` 事件
	console.log(result);
} catch (error) {
	// `emitter` 触发了 `error` 事件或
	// 触发了带有 'unwanted result' 的 `finish` 事件
	console.error(error);
}