fetcher-eventbus Skill

使用時期

@ahoo-wang/fetcher-eventbus パッケージを操作する場合にこのスキルを使用してください。以下の場合にトリガーします:

• ユーザーがイベントバス、イベント、ブロードキャスト、またはクロスタブ通信について言及する
• ユーザーがSerialまたはParallelなイベント実行を望んでいる
• ユーザーがBroadcastChannelまたはStorageMessengerについて質問する
• ユーザーがTypeScriptサポート付きの型付きイベントハンドリングが必要である

主要概念

イベントバスの実装

このパッケージは3つのイベントバス実装を提供します:

1. SerialTypedEventBus

ハンドラーは優先度順(orderプロパティで決定)に実行されます。各ハンドラーが完了してから次が開始されます。

import { SerialTypedEventBus } from '@ahoo-wang/fetcher-eventbus';

const bus = new SerialTypedEventBus<string>('my-events');

bus.on({
  name: 'logger',
  order: 1,
  handle: event => console.log('Event:', event),
});

bus.on({
  name: 'processor',
  order: 2,
  handle: event => console.log('Processing:', event),
});

await bus.emit('hello'); // Executes in order: logger then processor

2. ParallelTypedEventBus

ハンドラーは順序に関係なく並行して実行されます。ハンドラーが独立している場合に使用します。

import { ParallelTypedEventBus } from '@ahoo-wang/fetcher-eventbus';

const bus = new ParallelTypedEventBus<string>('my-events');

bus.on({
  name: 'handler1',
  order: 1,
  handle: async event => console.log('Handler 1:', event),
});

bus.on({
  name: 'handler2',
  order: 2,
  handle: async event => console.log('Handler 2:', event),
});

await bus.emit('hello'); // Both execute in parallel

3. BroadcastTypedEventBus

デリゲートバスを使用して、イベントを他のブラウザタブにブロードキャストします。ローカルおよびクロスタブで動作します。

import {
  BroadcastTypedEventBus,
  SerialTypedEventBus,
} from '@ahoo-wang/fetcher-eventbus';

const delegate = new SerialTypedEventBus<string>('shared-events');
const bus = new BroadcastTypedEventBus({ delegate });

bus.on({
  name: 'cross-tab-handler',
  order: 1,
  handle: event => console.log('Received from other tab:', event),
});

await bus.emit('broadcast-message'); // Local + cross-tab

クロスタブメッセンジャー

ダイレクトなクロスタブ通信用の2つのメッセンジャー実装:

BroadcastChannelMessenger

効率的なクロスタブメッセージング用にネイティブBroadcastChannel APIを使用します。

import { BroadcastChannelMessenger } from '@ahoo-wang/fetcher-eventbus';

const messenger = new BroadcastChannelMessenger('my-channel');

messenger.onmessage = message => {
  console.log('Received:', message);
};

messenger.postMessage('Hello from another tab!');
messenger.close();

StorageMessenger

BroadcastChannelが利用不可な場合のフォールバックとしてlocalStorageイベントを使用します。TTLとクリーンアップをサポートします。

import { StorageMessenger } from '@ahoo-wang/fetcher-eventbus';

const messenger = new StorageMessenger({
  channelName: 'my-channel',
  ttl: 5000, // Messages expire after 5 seconds
  cleanupInterval: 1000, // Clean expired messages every 1 second
});

messenger.onmessage = message => {
  console.log('Received:', message);
};

messenger.postMessage('Hello from another tab!');
messenger.close();

createCrossTabMessenger

利用可能な最適なメッセンジャーを自動選択します:

import { createCrossTabMessenger } from '@ahoo-wang/fetcher-eventbus';

const messenger = createCrossTabMessenger('my-channel');
if (messenger) {
  messenger.onmessage = msg => console.log(msg);
  messenger.postMessage('Hello!');
}

イベントハンドラー

ハンドラーインターフェース

interface EventHandler<EVENT> {
  name: string; // Unique identifier
  order: number; // Execution priority (lower = earlier)
  handle: (event: EVENT) => void | Promise<void>;
  once?: boolean; // If true, auto-removes after first execution
}

Onceハンドラー

once: trueを指定したハンドラーは最初の実行後に自動的に登録解除されます:

bus.on({
  name: 'one-time-handler',
  order: 1,
  once: true,
  handle: event => console.log('This runs only once:', event),
});

汎用EventBus

遅延ロードされたバスで複数のイベントタイプを管理します:

import { EventBus, SerialTypedEventBus } from '@ahoo-wang/fetcher-eventbus';

const supplier = (type: string) => new SerialTypedEventBus(type);
const bus = new EventBus<{
  'user-login': string;
  'order-update': number;
}>(supplier);

bus.on('user-login', {
  name: 'welcome',
  order: 1,
  handle: username => console.log(`Welcome ${username}!`),
});

await bus.emit('user-login', 'john-doe');

エラーハンドリングパターン

1. ハンドラー内のtry-catch: 非同期操作をtry-catchで囲む
2. エラーバスデリゲーション: エラーを専用のエラー処理バスに渡す
3. ログ記録: 組み込みロガーを使用してエラーの可視化を行う

bus.on({
  name: 'safe-handler',
  order: 1,
  handle: async event => {
    try {
      await riskyOperation(event);
    } catch (error) {
      console.error('Handler failed:', error);
    }
  },
});

APIリファレンス

メソッド	説明
on(handler)	イベントハンドラーを登録する
off(name)	名前でハンドラーを削除する
emit(event)	すべてのハンドラーにイベントを発火
destroy()	すべてのハンドラーとリソースをクリーンアップする

ブラウザサポート

• BroadcastTypedEventBus: Chrome 54+、Firefox 38+、Safari 15.4+
• StorageMessenger: localStorageをサポートするすべてのブラウザ
• その他の実装: ES2020+ 環境(Node.js、ブラウザ)

ファイルロケーション

• パッケージ: /Users/ahoo/work/ahoo-git/agent-coder/fetcher/packages/eventbus/
• テスト: /Users/ahoo/work/ahoo-git/agent-coder/fetcher/packages/eventbus/test/