@shelamkoff/event-bus

Небольшая синхронная шина событий без внешних зависимостей для браузерных библиотек и Node.js.

English README

Текущая версия: 1.0.0.

Требования и установка

• окружение с поддержкой модулей ECMAScript;
• Node.js 20 или новее при использовании в Node.js;
• внешние зависимости отсутствуют.

npm install @shelamkoff/event-bus

Быстрый старт

import { EventBus } from '@shelamkoff/event-bus'

interface EditorEvents {
  ready: [documentId: string]
  change: [version: number]
  close: []
}

const events = new EventBus<EditorEvents>()
const unsubscribe = events.on('change', version => {
  console.log('Версия документа:', version)
})

events.once('ready', documentId => console.log('Готов:', documentId))
events.emit('ready', 'document-1')
events.emit('change', 2)

unsubscribe()
events.clear()

Тип карты событий необязателен, но рекомендуется при использовании TypeScript. Каждому событию соответствует кортеж аргументов, которые принимает emit() и получает обработчик.

Программный интерфейс

| Элемент | Поведение | | --- | --- | | new EventBus({ debug?: boolean }) | Создаёт независимую шину. debug: true выводит отправляемые события через console.log. | | on(event, handler) | Регистрирует обработчик и возвращает идемпотентную функцию отписки. Повторная регистрация той же функции для того же события не создаёт дубликат. | | once(event, handler) | Регистрирует обработчик на один вызов и возвращает функцию отписки. | | off(event, handler) | Удаляет указанный обработчик. Отсутствующий обработчик игнорируется. | | emit(event, ...args) | Синхронно вызывает текущие обработчики в порядке регистрации. Возвращает void. | | has(event) | Показывает, есть ли у события хотя бы один обработчик. | | clear(event) | Удаляет все обработчики одного события. | | clear() | Удаляет все обработчики из шины. |

Имя события должно быть непустой строкой, а обработчик — функцией. Нарушение этих требований приводит к TypeError.

Порядок отправки событий

emit() создаёт устойчивый снимок набора обработчиков. Добавление или удаление обработчиков во время отправки повлияет только на следующую отправку. once() удаляет свою обёртку до вызова пользовательской функции, поэтому рекурсивный emit() не вызовет её повторно.

Ошибки обработчиков изолированы:

• синхронное исключение передаётся в console.error, после чего вызываются остальные обработчики;
• возвращённое обещание не ожидается, поскольку отправка синхронна;
• отклонение возвращённого обещания перехватывается и передаётся в console.error.

Если результаты обработчиков нужно ожидать или собирать, организуйте асинхронную последовательность в прикладном коде.

Освобождение ресурсов

Сохраняйте и вызывайте функцию, возвращаемую on() или once(), если срок жизни подписчика короче срока жизни шины. Используйте clear() только тогда, когда владелец намеренно освобождает всех подписчиков.

Демонстрационный пример в репозитории

Из корня рабочей области:

npm run demo:event-bus

Из каталога пакета ту же страницу запускает npm run demo. Демонстрационный файл остаётся в репозитории и не включается в пакет npm.

Точки входа пакета

• @shelamkoff/event-bus — класс EventBus и тип EventMap для TypeScript;
• @shelamkoff/event-bus/package.json — метаданные пакета.

Пакет распространяется по лицензии MIT.