@zk-tech/bedrock 0.0.1

package/dist/event/index.d.cts

@@ -0,0 +1,139 @@
+import { b as EmitterOptions, E as Event } from '../emitter-CAfCtSTg.cjs';
+export { a as Emitter } from '../emitter-CAfCtSTg.cjs';
+import { I as IDisposable } from '../dispose-base-CAeXDpjg.cjs';
+import '../linked-list-CUkue5DZ.cjs';
+
+interface IPhaseChecker<T> {
+    (before: T, after: T): boolean;
+}
+/**
+ * WhenPhaseEvent相比较Event有如下特点
+ * 1. 增加了callback前第一个参数，可以明确listener对应的phase
+ * 2. 会进行状态补发
+ */
+interface WhenPhaseEvent<T> {
+    (phase: T, listener: () => any): IDisposable;
+}
+/**
+ * PhaseEvent相比较Event有如下特点
+ * 1. 参数一定为空
+ * 2. 会进行状态补发
+ */
+type PhaseEvent = Event<[]>;
+declare enum ShortcutEventMode {
+    Async = 0,
+    Sync = 1
+}
+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;
+ * }
+ * ```
+ * 有问题联系基建侧同学。
+ */
+declare class PhaseEmitter<T, K extends T = T> {
+    private _currentPhase;
+    private readonly _phaseChecker;
+    private readonly _options?;
+    private _globalEmitter?;
+    private readonly _phaseEmitterMap;
+    private _phaseEvent?;
+    private readonly _shortcutEvent;
+    constructor(_currentPhase: K, config?: IPhaseEmitterConfig<T>, _phaseChecker?: IPhaseChecker<T>, _options?: EmitterOptions | undefined);
+    get currentPhase(): K;
+    get event(): Event<[T]>;
+    get whenPhase(): WhenPhaseEvent<T>;
+    when(phase: K): PhaseEvent;
+    dispose(): void;
+    setPhase(phase: K): void;
+    /**
+     * 该接口为了和emitter对齐，优先使用setPhase
+     * @deprecated 优先使用setPhase，未来可能会去掉
+     */
+    fire(phase: K): void;
+    private _setPhaseEmitter;
+}
+
+declare function makeSyncShortcutEvent<T>(val: T): (callback: (val: T) => void) => IDisposable;
+declare function makeAsyncShortcutEvent<T>(val: T): (callback: (val: T) => void) => IDisposable;
+
+declare function listenOnce<TArgs extends any[]>(event: Event<TArgs>): Event<TArgs>;
+
+declare function listenWhen<TArgs extends any[]>(event: Event<TArgs>, predicate: (...args: TArgs) => boolean): Event<TArgs>;
+
+declare const NeverEvent: Event<[any]>;
+
+/**
+ * 针对未捕获的错误，异步抛出，不阻塞事件响应主流程
+ * 默认模式
+ */
+declare function asyncUnexpectedError(e: any): void;
+/**
+ * 针对未捕获的错误，同步抛出，阻塞事件响应主流程
+ */
+declare function syncUnexpectedError(e: any): void;
+/**
+ * 针对未捕获的错误，静默掉，不进行处理
+ */
+declare function ignoreUnexpectedError(e: any): void;
+
+export { Event, NeverEvent, PhaseEmitter, type PhaseEvent, ShortcutEventMode, type WhenPhaseEvent, asyncUnexpectedError, ignoreUnexpectedError, listenOnce, listenWhen, makeAsyncShortcutEvent, makeSyncShortcutEvent, syncUnexpectedError };

package/dist/event/index.d.ts

@@ -0,0 +1,139 @@
+import { b as EmitterOptions, E as Event } from '../emitter-DeM5mlEm.js';
+export { a as Emitter } from '../emitter-DeM5mlEm.js';
+import { I as IDisposable } from '../dispose-base-CAeXDpjg.js';
+import '../linked-list-CUkue5DZ.js';
+
+interface IPhaseChecker<T> {
+    (before: T, after: T): boolean;
+}
+/**
+ * WhenPhaseEvent相比较Event有如下特点
+ * 1. 增加了callback前第一个参数，可以明确listener对应的phase
+ * 2. 会进行状态补发
+ */
+interface WhenPhaseEvent<T> {
+    (phase: T, listener: () => any): IDisposable;
+}
+/**
+ * PhaseEvent相比较Event有如下特点
+ * 1. 参数一定为空
+ * 2. 会进行状态补发
+ */
+type PhaseEvent = Event<[]>;
+declare enum ShortcutEventMode {
+    Async = 0,
+    Sync = 1
+}
+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;
+ * }
+ * ```
+ * 有问题联系基建侧同学。
+ */
+declare class PhaseEmitter<T, K extends T = T> {
+    private _currentPhase;
+    private readonly _phaseChecker;
+    private readonly _options?;
+    private _globalEmitter?;
+    private readonly _phaseEmitterMap;
+    private _phaseEvent?;
+    private readonly _shortcutEvent;
+    constructor(_currentPhase: K, config?: IPhaseEmitterConfig<T>, _phaseChecker?: IPhaseChecker<T>, _options?: EmitterOptions | undefined);
+    get currentPhase(): K;
+    get event(): Event<[T]>;
+    get whenPhase(): WhenPhaseEvent<T>;
+    when(phase: K): PhaseEvent;
+    dispose(): void;
+    setPhase(phase: K): void;
+    /**
+     * 该接口为了和emitter对齐，优先使用setPhase
+     * @deprecated 优先使用setPhase，未来可能会去掉
+     */
+    fire(phase: K): void;
+    private _setPhaseEmitter;
+}
+
+declare function makeSyncShortcutEvent<T>(val: T): (callback: (val: T) => void) => IDisposable;
+declare function makeAsyncShortcutEvent<T>(val: T): (callback: (val: T) => void) => IDisposable;
+
+declare function listenOnce<TArgs extends any[]>(event: Event<TArgs>): Event<TArgs>;
+
+declare function listenWhen<TArgs extends any[]>(event: Event<TArgs>, predicate: (...args: TArgs) => boolean): Event<TArgs>;
+
+declare const NeverEvent: Event<[any]>;
+
+/**
+ * 针对未捕获的错误，异步抛出，不阻塞事件响应主流程
+ * 默认模式
+ */
+declare function asyncUnexpectedError(e: any): void;
+/**
+ * 针对未捕获的错误，同步抛出，阻塞事件响应主流程
+ */
+declare function syncUnexpectedError(e: any): void;
+/**
+ * 针对未捕获的错误，静默掉，不进行处理
+ */
+declare function ignoreUnexpectedError(e: any): void;
+
+export { Event, NeverEvent, PhaseEmitter, type PhaseEvent, ShortcutEventMode, type WhenPhaseEvent, asyncUnexpectedError, ignoreUnexpectedError, listenOnce, listenWhen, makeAsyncShortcutEvent, makeSyncShortcutEvent, syncUnexpectedError };