跳到內容
Islumina

aieventjs — 事件系統

import { Aside } from ‘@astrojs/starlight/components’;

aieventjs 是 ai*js 家族的事件發布訂閱核心。與 mitt API 形狀相近，但加入了 ai*js 的生命週期約束：on() 回傳 unsubscribe 函數、AbortSignal 第一級支援、dispose() 冪等且嚴格（呼叫後繼續操作會丟出 EmitterDisposedError）。

安裝

Section titled “安裝”
Terminal window
pnpm add aieventjs

快速開始

Section titled “快速開始”
import { createEmitter } from "aieventjs";


// 用 type（非 interface）宣告事件 map
type Events = {
  "user:login":  { id: string };
  "score:tick":  { delta: number };
  "user:logout": void;
};


const bus = createEmitter<Events>();


// on() 回傳 unsubscribe，不需要額外管理 listener reference
const off = bus.on("user:login", (u) => console.log("hi", u.id));


// 或交給 AbortSignal 管理清理時機
const ctrl = new AbortController();
bus.on("score:tick", (e) => render(e.delta), { signal: ctrl.signal });


// wildcard * 監聽全部事件，在 type-matched handlers 之後觸發
bus.on("*", (type, payload) => trace(type, payload));


// 發送
bus.emit("user:login", { id: "alice" });


// 清理
off();               // 取消單個訂閱
ctrl.abort();        // signal 取消
bus.dispose();       // 銷毀整個 emitter（冪等）

核心特性

Section titled “核心特性”
特性說明
on() 回傳 unsubscribe直接呼叫回傳值即可取消，不需要另存 handler reference
AbortSignal傳入 { signal } 選項，signal abort 時自動移除 listener
once()內建，只觸發一次後自動移除
wildcard *bus.on("*", (type, payload) => ...)
dispose() 冪等重複呼叫不會拋錯；之後的 on/emit/once 會丟出 EmitterDisposedError
可解構const { on, emit } = bus 可正常使用，不依賴 this

常見搭配

Section titled “常見搭配”
  • 與 aifsmjs 搭配：FSM 狀態轉移時透過 emitter 廣播給 UI 層
  • 與 aiecsjs 搭配：ECS system 完成一幀後 emit 事件通知其他模組
  • 與 aibridgejs 搭配：bridge 的 on() 事件語義與 aieventjs 形狀一致，方便替換