@zk-tech/bedrock 0.0.1 → 0.1.0

package/src/event/phase-emitter.ts

@@ -1,209 +0,0 @@
-import { lvAssert } from '@/assert';
-import { Emitter, type Event, type EmitterOptions } from './emitter';
-import {
-  type IMakeShortcutEvent,
-  makeSyncShortcutEvent,
-  makeAsyncShortcutEvent,
-} from './shortcut-event-utils';
-import type { IDisposable } from '@/dispose';
-import { Logger } from '@/_internal/logger';
-
-export interface IPhaseChecker<T> {
-  (before: T, after: T): boolean;
-}
-
-function defaultCheck<T>(_before: T, _after: T) {
-  return true;
-}
-
-/**
- * WhenPhaseEvent相比较Event有如下特点
- * 1. 增加了callback前第一个参数，可以明确listener对应的phase
- * 2. 会进行状态补发
- */
-export interface WhenPhaseEvent<T> {
-  (phase: T, listener: () => any): IDisposable;
-}
-
-/**
- * PhaseEvent相比较Event有如下特点
- * 1. 参数一定为空
- * 2. 会进行状态补发
- */
-export type PhaseEvent = Event<[]>;
-
-interface IPhaseEmitter {
-  emitter: Emitter<[]>;
-  fn: Event<[]>;
-}
-
-export enum ShortcutEventMode {
-  Async,
-  Sync,
-}
-
-interface IPhaseEmitterConfig<T> {
-  checker?: IPhaseChecker<T>;
-  shortcutEventMode?: ShortcutEventMode;
-}
-
-/**
- * 阶段状态事件触发器，相比较原始的emitter有如下不同
- * 1. 明确了事件类型一定是生命周期的扭转
- *   a. 必须传入一个枚举表示阶段状态
- *   b. 抛出的事件只能是生命周期扭转，不允许携带参数
- *
- * 2. 当状态已经到达，后监听，进行补发事件
- *
- * -------------------------
- * 注意：由于存在事件补发，所以该事件触发器其实很危险，冲击到了依赖关系
- * 本身A依赖B的某个事件，那么正确的顺序应该是：
- * B模块初始化->A模块初始化->B抛出事件->A监听到事件
- *
- * 但如果存在事件补发，以下流程表面没有问题
- * B模块初始化->B抛出事件->A模块初始化->A监听到事件
- * 实际上可能有两个问题
- *   1. A监听到的事件，并不清楚在A初始化前触发还是初始化后触发，信息丢失
- *   2. B抛出事件，A其实必须要响应，响应晚了其实也是问题
- *
- * 所以事件补发是一件非常危险的事情，不要随意补发。
- * -------------------------
- *
- * 只有状态扭转的事件可以存在合理的补发
- * A监听B的状态变更
- * 一般来说，A模块内代码的写法可能是
- * ```
- * if (B.isReady) {
- *   doSomething();
- * } else {
- *   B.onReady(doSomething);
- * }
- * ```
- * 这种情况，我们借助事件补发可以变成如下来减少代码量。
- * ```
- * B.onReady(doSomething);
- * ```
- *
- * 最经典的事件补发就是CancellationSourceToken的设计，我们将其抽象出一种通用能力。
- * 使用demo如下：
- * ```
- * enum Phase {
- *   Waiting,
- *   Eventually,
- * }
- *
- * class Foo {
- *   phaseEmitter = new PhaseEmitter<Phase>(Phase.Waiting);
- *   // 方式1，监听指定的状态到达
- *   // 外部: foo.onEventually(doSomething);
- *   onEventually = this.phaseEmitter.when(Phase.Eventually);
- *
- *   // 方式2，给予外部更高的自由度
- *   // 外部: foo.onPhase(Phase.Eventually, doSomething);
- *   onPhase = this.phaseEmitter.whenPhase;
- *
- *   // 方式3，监听变更（该方式不会补发）
- *   // 外部: foo.onPhaseChange((phase) => doSomething)
- *   onPhaseChange = this.phaseEmitter.event;
- * }
- * ```
- * 有问题联系基建侧同学。
- */
-export class PhaseEmitter<T, K extends T = T> {
-  private _globalEmitter?: Emitter<[T]>;
-  private readonly _phaseEmitterMap: Map<K, IPhaseEmitter> = new Map();
-  private _phaseEvent?: WhenPhaseEvent<T>;
-  private readonly _shortcutEvent: IMakeShortcutEvent<T>;
-
-  constructor(
-    private _currentPhase: K,
-    config: IPhaseEmitterConfig<T> = {},
-    private readonly _phaseChecker: IPhaseChecker<T> = defaultCheck,
-    private readonly _options?: EmitterOptions,
-  ) {
-    this._phaseChecker = config.checker ?? defaultCheck;
-
-    const shortcutEventMode = config.shortcutEventMode ?? ShortcutEventMode.Async;
-    this._shortcutEvent =
-      shortcutEventMode === ShortcutEventMode.Async ? makeAsyncShortcutEvent : makeSyncShortcutEvent;
-  }
-
-  get currentPhase() {
-    return this._currentPhase;
-  }
-
-  get event(): Event<[T]> {
-    if (!this._globalEmitter) {
-      this._globalEmitter = new Emitter<T[]>();
-    }
-    return this._globalEmitter!.event;
-  }
-
-  get whenPhase(): WhenPhaseEvent<T> {
-    if (this._phaseEvent) {
-      return this._phaseEvent;
-    }
-
-    this._phaseEvent = (phase: T, listener: () => any) => {
-      if (this._currentPhase === phase) {
-        return this._shortcutEvent(this._currentPhase)(listener);
-      }
-      if (!this._phaseEmitterMap.has(phase as K)) {
-        this._setPhaseEmitter(phase as K);
-      }
-      return this._phaseEmitterMap.get(phase as K)!.fn(listener);
-    };
-
-    return this._phaseEvent;
-  }
-
-  when(phase: K): PhaseEvent {
-    if (this._currentPhase === phase) {
-      return this._shortcutEvent(phase);
-    }
-
-    if (!this._phaseEmitterMap.has(phase)) {
-      this._setPhaseEmitter(phase);
-    }
-    return this._phaseEmitterMap.get(phase)!.fn;
-  }
-
-  dispose(): void {
-    for (const [_phase, emitter] of this._phaseEmitterMap) {
-      emitter.emitter.dispose();
-    }
-    this._globalEmitter?.dispose();
-  }
-
-  setPhase(phase: K): void {
-    if (this._currentPhase === phase) {
-      Logger.warn(`duplicate set phase: ${phase}.`);
-      return;
-    }
-    lvAssert(this._phaseChecker(this._currentPhase, phase));
-    this._currentPhase = phase;
-    this._phaseEmitterMap.get(phase)?.emitter.fire();
-    this._globalEmitter?.fire(phase);
-  }
-
-  /**
-   * 该接口为了和emitter对齐，优先使用setPhase
-   * @deprecated 优先使用setPhase，未来可能会去掉
-   */
-  fire(phase: K): void {
-    this.setPhase(phase);
-  }
-
-  private _setPhaseEmitter(phase: K) {
-    const emitter = new Emitter<[]>(this._options);
-    this._phaseEmitterMap.set(phase, {
-      emitter,
-      fn: (listener: () => any) => {
-        if (this._currentPhase === phase) {
-          return this._shortcutEvent(this._currentPhase)(listener);
-        }
-        return emitter.event(listener);
-      },
-    });
-  }
-}

package/src/event/shortcut-event-utils.ts

@@ -1,33 +0,0 @@
-import type { IDisposable } from '@/dispose';
-import type { Event } from './emitter';
-
-export interface IMakeShortcutEvent<T> {
-  (val: T): Event<[T]>;
-}
-
-export function makeSyncShortcutEvent<T>(val: T) {
-  return function (callback: (val: T) => void): IDisposable {
-    callback(val);
- 
-    return {
-      dispose() {
-        // eslint-disable-next-line @typescript-eslint/no-empty-function
-      },
-    };
-  };
-}
-
-export function makeAsyncShortcutEvent<T>(val: T) {
-  return function (callback: (val: T) => void): IDisposable {
-    const handle = setTimeout(() => {
-      callback(val);
-    }, 0);
-
-    return {
-      dispose() {
-        clearTimeout(handle);
-      },
-    };
-  };
-}
-

package/src/event/utils.ts

@@ -1,6 +0,0 @@
-import { EmptyDispose } from '@/dispose';
-import type { Event } from './emitter';
-
-export const NeverEvent: Event<[any]> = () => {
-  return EmptyDispose;
-};

package/src/event/when.ts

@@ -1,40 +0,0 @@
-import type { Event } from './emitter';
-import type { IDisposable } from '@/dispose';
-
-// 辅助能力：监听事件，直到事件满足某种状况为止，此时触发 listener callback 并停止监听
-// 类似 MobX 的 `when`
-export function listenWhen<TArgs extends any[]>(
-  event: Event<TArgs>,
-  predicate: (...args: TArgs) => boolean,
-): Event<TArgs> {
-  return (listener, thisArgs = null) => {
-    let hasBeenFulfilled = false;
-
-    // 必须这样写，事件可能同步触发
-    // eslint-disable-next-line no-undef-init
-    let result: IDisposable | undefined = undefined;
-
-    result = event((...args) => {
-      if (hasBeenFulfilled) {
-        result?.dispose();
-        return;
-      }
-
-      // 是否条件满足
-      hasBeenFulfilled = predicate(...args);
-
-      // 如果满足条件则触发回调
-      if (hasBeenFulfilled) {
-        listener.call(thisArgs, ...args);
-        result?.dispose();
-      }
-    }, null);
-
-    // 注册事件时可能就会被触发一次？
-    if (hasBeenFulfilled) {
-      result.dispose();
-    }
-
-    return result;
-  };
-}

package/src/function/debounce.test.ts

@@ -1,274 +0,0 @@
-/* eslint-disable max-lines-per-function */
-import { sleep } from '../async';
-import { debounce } from './debounce';
-
-describe('Debounce', () => {
-  test('should debounce a function', async () => {
-    let callCount = 0;
-
-    const debounced = debounce(function (value) {
-      ++callCount;
-      return value;
-    }, 32);
-
-    const results = [debounced('a'), debounced('b'), debounced('c')];
-    expect(results).toEqual([undefined, undefined, undefined]);
-    expect(callCount).toBe(0);
-
-    setTimeout(() => {
-      expect(callCount).toBe(1);
-
-      const results = [debounced('d'), debounced('e'), debounced('f')];
-      expect(results).toEqual(['c', 'c', 'c']);
-      expect(callCount).toBe(1);
-    }, 128);
-
-    await sleep(256);
-    expect(callCount).toBe(2);
-  });
-
-  test('subsequent debounced calls return the last func result', async () => {
-    const identity = (x: string) => x;
-    const debounced = debounce(identity, 32);
-    debounced('a');
-
-    setTimeout(() => {
-      expect(debounced('b')).not.toBe('b');
-    }, 64);
-
-    await sleep(128);
-    expect(debounced('c')).not.toBe('c');
-  });
-
-  test('should not immediately call func when wait is 0', async () => {
-    let callCount = 0;
-    const debounced = debounce(() => {
-      ++callCount;
-    }, 0);
-
-    debounced();
-    debounced();
-    expect(callCount).toBe(0);
-
-    await sleep(5);
-    expect(callCount).toBe(1);
-  });
-
-  test('should apply default options', async () => {
-    let callCount = 0;
-    const debounced = debounce(
-      () => {
-        callCount++;
-      },
-      32,
-      {},
-    );
-
-    debounced();
-    expect(callCount).toBe(0);
-
-    await sleep(64);
-    expect(callCount).toBe(1);
-  });
-
-  test('should support a leading option', async () => {
-    const callCounts = [0, 0];
-
-    const withLeading = debounce(
-      () => {
-        callCounts[0]++;
-      },
-      32,
-      { leading: true },
-    );
-
-    const withLeadingAndTrailing = debounce(
-      () => {
-        callCounts[1]++;
-      },
-      32,
-      { leading: true, trailing: true },
-    );
-
-    withLeading();
-    expect(callCounts[0]).toBe(1);
-
-    withLeadingAndTrailing();
-    withLeadingAndTrailing();
-    expect(callCounts[1]).toBe(1);
-
-    await sleep(64);
-    expect(callCounts).toEqual([1, 2]);
-
-    withLeading();
-    expect(callCounts[0]).toBe(2);
-  });
-
-  test('subsequent leading debounced calls return the last func result', async () => {
-    const debounced = debounce((x: string) => x, 32, { leading: true, trailing: false });
-    const results = [debounced('a'), debounced('b')];
-
-    expect(results).toEqual(['a', 'a']);
-
-    await sleep(64);
-    const results2 = [debounced('c'), debounced('d')];
-    expect(results2).toEqual(['c', 'c']);
-  });
-
-  test('should support a trailing option', async () => {
-    let withCount = 0;
-    let withoutCount = 0;
-
-    const withTrailing = debounce(
-      () => {
-        withCount++;
-      },
-      32,
-      { trailing: true },
-    );
-
-    const withoutTrailing = debounce(
-      () => {
-        withoutCount++;
-      },
-      32,
-      { trailing: false },
-    );
-
-    withTrailing();
-    expect(withCount).toBe(0);
-
-    withoutTrailing();
-    expect(withoutCount).toBe(0);
-
-    await sleep(64);
-    expect(withCount).toBe(1);
-    expect(withoutCount).toBe(0);
-  });
-
-  test('should support a maxWait option', async () => {
-    let callCount = 0;
-
-    const debounced = debounce(
-      () => {
-        callCount++;
-      },
-      32,
-      { maxWait: 64 },
-    );
-
-    debounced();
-    debounced();
-    expect(callCount).toBe(0);
-
-    // 超过原来的 maxWait 时间，不足下一个
-    await sleep(128);
-    expect(callCount).toBe(1); // maxWait 时间后应该调用过一次
-    debounced();
-    debounced();
-    expect(callCount).toBe(1); // 紧接着调用不会立即触发因为还在 maxWait 窗口内
-
-    // 确保超过第二个 maxWait 时间
-    await sleep(128);
-    expect(callCount).toBe(2); // 经过足够时间后，第二次 maxWait 达成，调用发生
-  });
-
-  test('should support maxWait in a tight loop', async () => {
-    const limit = 320;
-    let withCount = 0;
-    let withoutCount = 0;
-
-    const withMaxWait = debounce(
-      () => {
-        withCount++;
-      },
-      64,
-      { maxWait: 128 },
-    );
-
-    const withoutMaxWait = debounce(() => {
-      withoutCount++;
-    }, 96);
-
-    const start = Date.now();
-    while (Date.now() - start < limit) {
-      withMaxWait();
-      withoutMaxWait();
-    }
-
-    const actual = [Boolean(withoutCount), Boolean(withCount)];
-    await sleep(1);
-    expect(actual).toEqual([false, true]);
-  });
-
-  test('should queue a trailing call for subsequent debounced calls after maxWait', async () => {
-    let callCount = 0;
-
-    const debounced = debounce(
-      () => {
-        callCount++;
-      },
-      200,
-      { maxWait: 200 },
-    );
-
-    debounced(); // 第一次立即调用
-
-    setTimeout(debounced, 190); // 在 maxWait 之前调用
-    setTimeout(debounced, 200); // 正在 maxWait 边缘调用
-    setTimeout(debounced, 210); // 刚过 maxWait 时调用
-
-    // 等待足够时间以确保所有的debounce逻辑完成
-    await sleep(500);
-    expect(callCount).toBe(2); // 预期在 200 ms 后的某个时点触发了第二次调用
-  });
-
-  test('should cancel maxDelayed when delayed is invoked', async () => {
-    let callCount = 0;
-
-    const debounced = debounce(
-      () => {
-        callCount++;
-      },
-      32,
-      { maxWait: 64 },
-    );
-
-    debounced(); // 第一次立即调用
-
-    setTimeout(() => {
-      debounced(); // 第二次调用应该重置 maxWait 计时器
-      expect(callCount).toBe(1); // 检查到目前为止该函数被调用的次数
-    }, 128);
-
-    // 等待足够时间以确保所有的debounce逻辑完成
-    await sleep(256);
-    expect(callCount).toBe(2); // 最后，确认函数被调用了两次
-  });
-
-  test('should invoke the trailing call with the correct arguments and this binding', async () => {
-    let actual: any;
-    let callCount = 0;
-    const object = {};
-
-    const debounced = debounce(
-      function (value) {
-        actual = [this];
-        actual.push(value);
-        return ++callCount !== 2;
-      },
-      32,
-      { leading: true, maxWait: 64 },
-    );
-
-    while (true) {
-      if (!debounced.call(object, 'a')) {
-        break;
-      }
-    }
-
-    await sleep(64);
-    expect(callCount).toBe(2);
-    expect(actual).toEqual([object, 'a']);
-  });
-});