@vitarx/responsive/dist/effect/effect.d.ts

Vitarx responsive package

import { AnyCallback, VoidCallback } from '@vitarx/utils';
import type { EffectCallbackErrorHandler, EffectInterface, EffectState } from './effect-interface.js';
/**
 * 副作用固有错误来源
 *
 * @remarks
 * 定义了副作用对象可能触发的三种错误来源：
 * - `dispose`: 销毁事件，表示资源释放
 * - `pause`: 暂停事件，临时停止副作用
 * - `resume`: 恢复事件，重新激活副作用
 */
export type EffectInherentErrorSource = 'dispose' | 'pause' | 'resume';
/**
 * Effect类提供了一个通用的副作用管理实现
 *
 * 该类设计用于管理具有生命周期的副作用操作，提供了：
 * - 状态管理：支持active（活跃）、paused（暂停）和deprecated（弃用）三种状态
 * - 生命周期钩子：可监听销毁(dispose)、暂停(pause)和恢复(resume)事件
 * - 错误处理：统一的错误捕获和处理机制
 *
 * 主要应用场景：
 * - 资源管理：管理需要及时清理的资源（如定时器、事件监听器等）
 * - 状态同步：协调多个相关联的副作用操作
 * - 可中断任务：支持暂停和恢复的长期运行任务
 *
 * @template ErrorSource - 错误源类型
 */
export declare class Effect<ErrorSource extends string = string> implements EffectInterface<EffectInherentErrorSource | ErrorSource> {
    /**
     * 回调函数集合
     *
     * @protected
     */
    protected callbacks?: Map<EffectInherentErrorSource | 'error', Set<AnyCallback>>;
    /**
     * 状态
     *
     * @protected
     */
    protected _state: EffectState;
    /**
     * 状态:
     *   - `active`: 活跃
     *   - `paused`: 暂停
     *   - `deprecated`: 弃用
     */
    get state(): EffectState;
    /**
     * 是否已弃用/销毁
     *
     * @readonly
     */
    get isDeprecated(): boolean;
    /**
     * 判断是否为暂停状态
     */
    get isPaused(): boolean;
    /**
     * 判断是否处于活跃状态
     */
    get isActive(): boolean;
    /**
     * 状态:
     *   - `active`: 活跃
     *   - `paused`: 暂停
     *   - `deprecated`: 弃用
     */
    getState(): EffectState;
    /**
     * @inheritDoc
     */
    dispose(): boolean;
    /**
     * @inheritDoc
     */
    onDispose(callback: VoidCallback): this;
    /**
     * @inheritDoc
     */
    pause(): boolean;
    /**
     * @inheritDoc
     */
    resume(): boolean;
    /**
     * 监听暂停事件
     *
     * @param {VoidCallback} callback - 回调函数
     * @returns {this}
     */
    onPause(callback: VoidCallback): this;
    /**
     * 监听恢复事件
     *
     * @param {VoidCallback} callback - 回调函数
     * @returns {this}
     */
    onResume(callback: VoidCallback): this;
    /**
     * 监听错误事件
     *
     * @param {EffectCallbackErrorHandler} callback - 回调函数
     * @returns {this}
     */
    onError(callback: EffectCallbackErrorHandler<EffectInherentErrorSource | ErrorSource>): this;
    /**
     * 清理所有回调函数
     *
     * @private
     */
    private clearCallbacks;
    /**
     * 报告回调异常
     *
     * @param {unknown} e - 捕获到的异常
     * @param {EffectInherentErrorSource} source - 回调事件源
     * @protected
     */
    protected reportError(e: unknown, source: EffectInherentErrorSource | ErrorSource): void;
    /**
     * 触发回调
     *
     * @param type
     * @protected
     */
    protected triggerCallback(type: EffectInherentErrorSource): void;
    /**
     * 添加回调函数
     *
     * @param callback
     * @param type
     * @private
     */
    private addCallback;
}
/**
 * 检测是否为可处置副作用对象
 *
 * @param {any} obj - 要检测的对象
 * @returns {boolean} 如果对象实现了 EffectInterface，则返回 true，否则返回 false
 */
export declare const isEffect: (obj: any) => obj is EffectInterface;