@zk-tech/bedrock 0.0.1

package/src/event/emitter.test.ts

@@ -0,0 +1,191 @@
+import type { Event } from './emitter';
+import { Emitter } from './emitter';
+import { listenOnce } from './once';
+import { listenWhen } from './when';
+import { asyncUnexpectedError, ignoreUnexpectedError, syncUnexpectedError } from './error-handler';
+
+interface IChangeData {
+  code: number;
+  msg: string;
+}
+
+class Foo {
+  readonly onChange: Event<[IChangeData]>;
+  private readonly _onChangeEmitter: Emitter<[IChangeData]>;
+
+  constructor(errorHandler = asyncUnexpectedError) {
+    this._onChangeEmitter = new Emitter({
+      onListenerError: errorHandler,
+    });
+    this.onChange = this._onChangeEmitter.event;
+  }
+
+  fire() {
+    this._onChangeEmitter.fire({
+      code: 0,
+      msg: '',
+    });
+  }
+}
+
+class Foo2 {
+  readonly onChange: Event<[number, string]>;
+  private readonly _onChangeEmitter: Emitter<[number, string]> = new Emitter();
+
+  constructor() {
+    this.onChange = this._onChangeEmitter.event;
+  }
+
+  fire() {
+    this._onChangeEmitter.fire(100, 'hello');
+  }
+
+  fireCustom(...args: [number, string]) {
+    this._onChangeEmitter.fire(...args);
+  }
+}
+
+describe('Emitter', () => {
+  test('Listen and unlisten event', () => {
+    const foo = new Foo();
+    let count = 0;
+    const disposable = foo.onChange(() => {
+      count++;
+    });
+
+    foo.fire();
+    foo.fire();
+    expect(count).toBe(2);
+
+    disposable.dispose();
+    foo.fire();
+    foo.fire();
+    expect(count).toBe(2);
+  });
+
+  test('Listen, unlisten, and re-listen event', () => {
+    const foo = new Foo();
+    let count = 0;
+
+    const disposable1 = foo.onChange(() => {
+      count++;
+    });
+    // Initially has one listener, can trigger normally
+    foo.fire();
+    expect(count).toBe(1);
+
+    const disposable2 = foo.onChange(() => {
+      count++;
+    });
+    // Now has two listeners, can still trigger normally
+    foo.fire();
+    expect(count).toBe(3);
+
+    disposable1.dispose();
+    // One listener removed, back to one listener, can still trigger normally
+    foo.fire();
+    expect(count).toBe(4);
+
+    disposable2.dispose();
+    // No listeners left, won't trigger
+    foo.fire();
+    expect(count).toBe(4);
+  });
+
+  test('listen to event only once', () => {
+    const foo = new Foo();
+    let count = 0;
+    listenOnce(foo.onChange)(() => {
+      count++;
+    });
+
+    foo.fire();
+    foo.fire();
+    expect(count).toBe(1);
+  });
+
+  test('listenWhen should only fire once when the predicate returns true', () => {
+    const foo2 = new Foo2();
+    let result = 0;
+    let count = 0;
+
+    listenWhen(foo2.onChange, (num) => {
+      return num === 200;
+    })((num) => {
+      count++;
+      result = num;
+    });
+
+    foo2.fire();
+    foo2.fireCustom(200, 'Yes');
+    foo2.fire();
+
+    expect(count).toBe(1);
+    expect(result).toBe(200);
+  });
+
+  test('multiple parameters', () => {
+    const foo = new Foo2();
+    let code;
+    let msg;
+    foo.onChange((c, m) => {
+      code = c;
+      msg = m;
+    });
+    foo.fire();
+
+    expect(code).toBe(100);
+    expect(msg).toBe('hello');
+  });
+});
+
+describe('ErrorHandler', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  test('async error', () => {
+    const foo = new Foo();
+    let count = 0;
+    foo.onChange(() => {
+      throw new Error('error');
+    });
+    foo.onChange(() => {
+      count++;
+    });
+
+    foo.fire();
+    expect(count).toBe(1);
+  });
+
+  test('sync error', () => {
+    const foo = new Foo(syncUnexpectedError);
+    let count = 0;
+    foo.onChange(() => {
+      throw new Error('error');
+    });
+    foo.onChange(() => {
+      count++;
+    });
+
+    expect(() => foo.fire()).toThrowError();
+    expect(count).toBe(0);
+  });
+
+  test('ignore error', () => {
+    const foo = new Foo(ignoreUnexpectedError);
+    let count = 0;
+    foo.onChange(() => {
+      throw new Error('error');
+    });
+    foo.onChange(() => {
+      count++;
+    });
+
+    foo.fire();
+    expect(count).toBe(1);
+  });
+});

package/src/event/emitter.ts

@@ -0,0 +1,162 @@
+import { makeSafeDisposable } from '@/dispose';
+import type { IDisposable } from '@/dispose';
+import { DisposableLinkedList } from './disposable-linked-list';
+import { asyncUnexpectedError } from './error-handler';
+
+export interface EmitterOptions {
+  onAddListener?: (...args: any) => any;
+  onRemoveListener?: (...args: any) => any;
+  onListenerError?: (e: any) => void;
+}
+
+//
+// 事件监听中的回调实体
+//
+class Listener<TArgs extends any[]> {
+  private readonly _callback: (...args: TArgs) => void;
+  private readonly _callbackThis: any | undefined;
+
+  constructor(callback: (...args: TArgs) => void, callbackThis: any | undefined) {
+    this._callback = callback;
+    this._callbackThis = callbackThis;
+  }
+
+  invoke(...args: TArgs): void {
+    this._callback.call(this._callbackThis, ...args);
+  }
+}
+
+//
+// 存放在EventDeliveryQueue中的元素
+//
+class EventDeliveryQueueElement<TArgs extends any[]> {
+  readonly emitter: Emitter<TArgs>;
+  readonly listener: Listener<TArgs>;
+  readonly event: TArgs;
+  constructor(emitter: Emitter<TArgs>, listener: Listener<TArgs>, event: TArgs) {
+    this.emitter = emitter;
+    this.listener = listener;
+    this.event = event;
+  }
+}
+
+export class EventDeliveryQueue {
+  protected _queue = new DisposableLinkedList<EventDeliveryQueueElement<any>>();
+
+  constructor(private readonly _onListenerError: (e: unknown) => void = asyncUnexpectedError) {}
+
+  get size(): number {
+    return this._queue.size;
+  }
+
+  push<TArgs extends any[]>(emitter: Emitter<TArgs>, listener: Listener<TArgs>, event: TArgs): void {
+    this._queue.push(new EventDeliveryQueueElement(emitter, listener, event));
+  }
+
+  clear<TArgs extends any[]>(emitter: Emitter<TArgs>): void {
+    const newQueue = new DisposableLinkedList<EventDeliveryQueueElement<TArgs>>();
+    for (const element of this._queue) {
+      if (element.emitter !== emitter) {
+        newQueue.push(element);
+      }
+    }
+    this._queue = newQueue;
+  }
+
+  deliver(): void {
+    while (this._queue.size > 0) {
+      const element = this._queue.shift()!;
+      try {
+        element.listener.invoke(...element.event);
+      } catch (e) {
+        this._onListenerError(e);
+      }
+    }
+  }
+}
+
+export interface Event<T extends any[]> {
+  (listener: (...args: T) => any, thisArgs?: any): IDisposable;
+}
+
+export class Emitter<TArgs extends any[]> {
+  protected _listeners?: DisposableLinkedList<Listener<TArgs>>;
+  private readonly _options?: EmitterOptions;
+  private _disposed = false;
+  private _event?: Event<TArgs>;
+  private _deliveryQueue?: EventDeliveryQueue;
+
+  constructor(options?: EmitterOptions) {
+    this._options = options;
+  }
+
+  get event(): Event<TArgs> {
+    if (this._event) {
+      return this._event;
+    }
+
+    this._event = (callback: (...args: TArgs) => any, thisArgs?: any): IDisposable => {
+      const listener = new Listener(callback, thisArgs);
+
+      if (!this._listeners) {
+        this._listeners = new DisposableLinkedList();
+      }
+
+      const removeListener = this._listeners.pushAndGetDisposableNode(listener);
+
+      if (this._options?.onAddListener) {
+        this._options.onAddListener(this, callback, thisArgs);
+      }
+
+      // 生成可销毁函数返回
+      const result = () => {
+        if (!this._disposed) {
+          removeListener();
+          if (this._options?.onRemoveListener) {
+            this._options.onRemoveListener(this, callback, thisArgs);
+          }
+        }
+      };
+
+      return makeSafeDisposable(result);
+    };
+
+    return this._event;
+  }
+
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+    this._disposed = true;
+    this._listeners?.clear();
+    this._deliveryQueue?.clear(this);
+  }
+
+  fire(...event: TArgs): void {
+    if (!this._listeners || this._listeners.size === 0) {
+      return;
+    }
+    // 绝大部分场景事件只会有一个监听器，针对性进行性能优化，没必要构造DeliveryQueue结构
+    if (this._listeners.size === 1) {
+      const listener = this._listeners.firstNode!;
+      try {
+        listener.value.invoke(...event);
+      } catch (e) {
+        if (this._options?.onListenerError) {
+          this._options.onListenerError(e);
+        } else {
+          asyncUnexpectedError(e);
+        }
+      }
+      return;
+    }
+
+    this._deliveryQueue ??= new EventDeliveryQueue(this._options?.onListenerError);
+
+    for (const listener of this._listeners) {
+      this._deliveryQueue.push(this, listener, event);
+    }
+    this._deliveryQueue.deliver();
+  }
+}

package/src/event/error-handler.ts

@@ -0,0 +1,22 @@
+/**
+ * 针对未捕获的错误，异步抛出，不阻塞事件响应主流程
+ * 默认模式
+ */
+export function asyncUnexpectedError(e: any): void {
+  setTimeout(() => {
+    throw e;
+  }, 0);
+}
+
+/**
+ * 针对未捕获的错误，同步抛出，阻塞事件响应主流程
+ */
+export function syncUnexpectedError(e: any): void {
+  throw e;
+}
+
+/**
+ * 针对未捕获的错误，静默掉，不进行处理
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export function ignoreUnexpectedError(e: any): void {}

package/src/event/index.ts

@@ -0,0 +1,34 @@
+// 事件触发器
+export { Emitter } from './emitter';
+// 事件监听
+export type { Event } from './emitter';
+
+// 状态扭转事件触发器
+// 需要绑定生命周期，默认提供事件补发
+export { PhaseEmitter } from './phase-emitter';
+// 状态扭转事件监听
+export type { PhaseEvent } from './phase-emitter';
+export type { WhenPhaseEvent } from './phase-emitter';
+
+// 快捷事件类型
+export { ShortcutEventMode } from './phase-emitter';
+// 辅助函数，生成快捷事件
+// 生成一个异步快捷事件
+export { makeAsyncShortcutEvent } from './shortcut-event-utils';
+// 生成一个同步快捷事件
+export { makeSyncShortcutEvent } from './shortcut-event-utils';
+
+// 辅助函数，监听事件一次后解绑
+export { listenOnce } from './once';
+// 辅助函数，监听事件满足回调后解绑
+export { listenWhen } from './when';
+// 辅助常量，空事件监听，永不触发
+export { NeverEvent } from './utils';
+
+// 针对事件抛出过程中，遇到错误，对应的处理方案（构建Emitter对象中参数）
+// 异步抛出错误
+export { asyncUnexpectedError } from './error-handler';
+// 同步抛出错误
+export { syncUnexpectedError } from './error-handler';
+// 忽略错误
+export { ignoreUnexpectedError } from './error-handler';

package/src/event/once.ts

@@ -0,0 +1,29 @@
+import type { Event } from './emitter';
+import type { IDisposable } from '@/dispose';
+
+// 辅助能力：只监听某个事件一次
+export function listenOnce<TArgs extends any[]>(event: Event<TArgs>): Event<TArgs> {
+  return (listener, thisArgs = null) => {
+    let didFire = false;
+    // 必须这样写，事件可能同步触发
+    // eslint-disable-next-line no-undef-init
+    let result: IDisposable | undefined = undefined;
+    result = event((...args) => {
+      if (didFire) {
+        return;
+      } else if (result) {
+        result.dispose();
+      } else {
+        didFire = true;
+      }
+
+      return listener.call(thisArgs, ...args);
+    }, null);
+
+    if (didFire) {
+      result.dispose();
+    }
+
+    return result;
+  };
+}

package/src/event/phase-emitter.test.ts

@@ -0,0 +1,212 @@
+import { PhaseEmitter, type IPhaseChecker, type WhenPhaseEvent } from './phase-emitter';
+import type { Event } from './emitter';
+
+enum Phase {
+  Aaa,
+  Bbb,
+  Ccc,
+}
+
+class Lifecycle {
+  readonly onBbb: Event<[]>;
+  readonly onCcc: Event<[]>;
+  readonly whenPhase: WhenPhaseEvent<Phase>;
+  readonly onPhaseChange: Event<[Phase]>;
+  private readonly _phaseEmitter: PhaseEmitter<Phase>;
+
+  constructor(checker?: IPhaseChecker<Phase>) {
+    this._phaseEmitter = new PhaseEmitter(Phase.Aaa, {
+      checker,
+    });
+    this.onBbb = this._phaseEmitter.when(Phase.Bbb);
+    this.onCcc = this._phaseEmitter.when(Phase.Ccc);
+    this.whenPhase = this._phaseEmitter.whenPhase;
+    this.onPhaseChange = this._phaseEmitter.event;
+  }
+
+  toB() {
+    this._phaseEmitter.setPhase(Phase.Bbb);
+  }
+
+  toC() {
+    this._phaseEmitter.setPhase(Phase.Ccc);
+  }
+}
+
+describe('PhaseEmitter', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  test('listens to state transition 1', () => {
+    const lifecycle = new Lifecycle();
+    let count = 0;
+    lifecycle.onBbb(() => {
+      count += 1;
+    });
+    lifecycle.onCcc(() => {
+      count += 10;
+    });
+
+    lifecycle.toB();
+    lifecycle.toC();
+    expect(count).toBe(11);
+  });
+
+  test('listens to state transition 2', () => {
+    const lifecycle = new Lifecycle();
+    let count = 0;
+    lifecycle.whenPhase(Phase.Bbb, () => {
+      count += 1;
+    });
+    lifecycle.whenPhase(Phase.Ccc, () => {
+      count += 10;
+    });
+
+    lifecycle.toB();
+    lifecycle.toC();
+    expect(count).toBe(11);
+  });
+
+  test('listens to state transition 3', () => {
+    const lifecycle = new Lifecycle();
+    let count = 0;
+    lifecycle.onPhaseChange((phase) => {
+      if (phase === Phase.Bbb) {
+        count += 1;
+      } else if (phase === Phase.Ccc) {
+        count += 10;
+      }
+    });
+
+    lifecycle.toB();
+    lifecycle.toC();
+    expect(count).toBe(11);
+  });
+
+  test('state replay 1', async () => {
+    const lifecycle = new Lifecycle();
+    lifecycle.toB();
+    lifecycle.toC();
+
+    // Since final state is C, only state C will be replayed
+    let count = 0;
+    lifecycle.onBbb(() => {
+      count += 1;
+    });
+    lifecycle.onCcc(() => {
+      count += 10;
+    });
+
+    vi.advanceTimersByTime(6);
+    expect(count).toBe(10);
+  });
+
+  test('state replay 2', async () => {
+    const lifecycle = new Lifecycle();
+    lifecycle.toC();
+    lifecycle.toB();
+
+    // Since final state is B, only state B will be replayed
+    let count = 0;
+    lifecycle.whenPhase(Phase.Bbb, () => {
+      count += 1;
+    });
+    lifecycle.whenPhase(Phase.Ccc, () => {
+      count += 10;
+    });
+
+    vi.advanceTimersByTime(6);
+    expect(count).toBe(1);
+  });
+
+  test('state replay 3', async () => {
+    const lifecycle = new Lifecycle();
+    lifecycle.toB();
+    lifecycle.toC();
+
+    // Since we're listening to state changes, no replay will occur
+    let count = 0;
+    lifecycle.onPhaseChange((phase) => {
+      if (phase === Phase.Bbb) {
+        count += 1;
+      } else if (phase === Phase.Ccc) {
+        count += 10;
+      }
+    });
+
+    vi.advanceTimersByTime(6);
+    expect(count).toBe(0);
+  });
+
+  test('state replay 4', async () => {
+    const lifecycle = new Lifecycle();
+    // Listen and replay trigger simultaneously
+    let count = 0;
+    lifecycle.whenPhase(Phase.Bbb, () => {
+      count += 1;
+    });
+
+    lifecycle.toB();
+    lifecycle.toC();
+
+    lifecycle.whenPhase(Phase.Ccc, () => {
+      count += 10;
+    });
+
+    vi.advanceTimersByTime(6);
+    expect(count).toBe(11);
+  });
+
+  test('state replay 5', async () => {
+    const lifecycle = new Lifecycle();
+    // Multiple replay triggers
+    let count = 0;
+    lifecycle.toB();
+    lifecycle.whenPhase(Phase.Bbb, () => {
+      count += 10;
+    });
+    lifecycle.onBbb(() => {
+      count += 10;
+    });
+
+    lifecycle.toC();
+    lifecycle.whenPhase(Phase.Ccc, () => {
+      count += 10;
+    });
+    lifecycle.onCcc(() => {
+      count += 10;
+    });
+
+    vi.advanceTimersByTime(6);
+    expect(count).toBe(40);
+  });
+
+  test('repeated transitions do not trigger', () => {
+    const lifecycle = new Lifecycle();
+    let count = 0;
+    lifecycle.onBbb(() => {
+      count += 1;
+    });
+
+    lifecycle.toB();
+    lifecycle.toB();
+    expect(count).toBe(1);
+  });
+
+  test('invalid transition throws error', () => {
+    const lifecycle = new Lifecycle((before, after) => {
+      return after > before;
+    });
+    let count = 0;
+    lifecycle.onBbb(() => {
+      count += 1;
+    });
+
+    lifecycle.toC();
+    expect(() => {
+      lifecycle.toB();
+    }).toThrowError();
+    expect(count).toBe(0);
+  });
+});