chanjs

Крохотный типобезопасный канал pub/sub: один Channel<M> задаётся картой сообщений (MessageMap) и открыт с двух сторон — tx для отправки и rx для подписки. Канал широковещательный: send доставляет сообщение всем подписчикам — это не CSP-очередь, как в Go.

| | | |---|---| | Версия | 1.0.0 | | Формат | только ESM ("type": "module") | | Зависимости | нет | | Лицензия | MIT |

Установка

npm install @evgkch/chanjs

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

import Channel from '@evgkch/chanjs';

// Карта сообщений: ключ — событие, значение — кортеж аргументов слушателя.
type Events = {
    ':click': [x: number, y: number];
    ':close': [];
};

const channel = new Channel<Events>();

// `on` возвращает функцию отписки — держать сам слушатель необязательно.
const off = channel.rx.on(':click', (x: number, y: number) => {
    console.log(`клик по ${x}, ${y}`);
});

// Отправка — слушатель выше получит (10, 20).
channel.tx.send(':click', 10, 20);

off();             // отписаться
channel.clear();   // либо снять всех подписчиков сразу

Понятия

| Термин | Что это | |---|---| | MessageMap | Объект: ключ — сообщение (string \| number \| symbol), значение — кортеж аргументов для его слушателей. Например { ':click': [x: number, y: number] }. | | Channel<M> | Сам канал pub/sub, параметризованный картой M. Хранит подписчиков по каждому сообщению. | | tx | Сторона отправки (Tx<M>): send, has. | | rx | Сторона приёма (Rx<M>): on, once, off. | | Off | Функция отписки () => boolean; возвращает true, если слушатель был снят. |

API

channel.tx — отправка

| Метод | Сигнатура | Возвращает | |---|---|---| | send | send(msg, ...args) | true, если у сообщения были слушатели | | has | has(msg) | true, если у сообщения сейчас есть подписчики |

has — дешёвая проверка перед отправкой: не собирать тяжёлый payload, когда у сообщения нет подписчиков.

channel.rx — подписка

| Метод | Сигнатура | Возвращает | |---|---|---| | on | on(msg, listener, signal?) | функцию отписки Off | | once | once(msg, listener, signal?) | функцию отписки Off (снимается после первой доставки) | | off | off(msg, listener) | true, если такой слушатель был |

signal — необязательный AbortSignal. После abort слушатель отписывается; по уже отменённому сигналу подписка не создаётся, а полученный Off возвращает false. Один контроллер снимает группу подписок:

const ac = new AbortController();
channel.rx.on(':click', onClick, ac.signal);
channel.rx.on(':close', onClose, ac.signal);
ac.abort();   // оба слушателя отписаны

Любая отписка — через функцию Off, off или clear — заодно снимает с сигнала abort-обработчик слушателя, поэтому на долгоживущем контроллере не копятся обработчики уже снятых подписок.

channel — жизненный цикл

| Член | Описание | |---|---| | tx / rx | две стороны канала | | clear() | снять всех подписчиков |

Семантика доставки

• Состав получателей фиксируется на время отправки. Подписка или отписка изнутри обработчика не влияет на текущий send; изменение действует со следующего send.
• Без повторов. Один и тот же слушатель, подписанный дважды по одной и той же ссылке, регистрируется один раз.