@enableai-job-runtime/core 0.0.5

package/dist/core.d.ts

@@ -0,0 +1,768 @@
+import { Scheduler, SchedulerPriority } from '@enableai-job-runtime/scheduler';
+
+/**
+ * 异步任务的执行状态。
+ *
+ * - Idle：尚未开始执行
+ * - Running：正在执行中
+ * - Finished：执行已完成（成功或失败）
+ */
+export declare enum AsyncStatus {
+    Idle = 0,
+    Running = 1,
+    Finished = 2
+}
+
+/**
+ * 同一个 key 的并发控制策略
+ *
+ * - allow   允许并发运行
+ * - skip    若同 key 有 Job 正在运行，则忽略新任务
+ * - replace 若同 key 有 Job 正在运行，则取消旧任务并启动新任务
+ * - queue   同 key Job 排队串行执行
+ */
+export type ConcurrencyPolicy = 'allow' | 'skip' | 'replace' | 'queue';
+/**
+ * 默认并发策略：允许并发
+ */
+export declare const DEFAULT_CONCURRENCY_POLICY: ConcurrencyPolicy;
+
+/**
+ * Job 内部使用的错误码。
+ */
+export declare enum JobErrorCode {
+    /**
+     * Hook 或 Job 内部用来表示“需要让出时间片”的信号。
+     * 这不是一个真正的错误，而是控制流的一部分。
+     */
+    ShouldYield = "ShouldYield"
+}
+/**
+ * Job 运行时错误。
+ *
+ * - 对于 ShouldYield 来说，这只是一个控制流信号；
+ * - 对于其他错误码，则代表真正的异常。
+ */
+export declare class JobError extends Error {
+    readonly code: JobErrorCode;
+    constructor(code: JobErrorCode, message?: string);
+}
+/**
+ * 工具函数：判断是否为“让出时间片”的控制流错误。
+ */
+export declare function isShouldYieldError(error: unknown): error is JobError;
+/**
+ * 创建一个 ShouldYield 错误实例，供 Hook 内部复用。
+ */
+export declare function createShouldYieldError(): JobError;
+
+/**
+ * HookSlot 类型体系
+ *
+ * 每个 Hook 对应一种 slot，用于保存内部状态。
+ * JobContext 内部维护一个 HookSlot[] 数组，
+ * Hook 调用顺序必须稳定，以保证 slot 索引稳定。
+ */
+/**
+ * Hook 类型标识
+ */
+export type HookKind = 'state' | 'effect' | 'async' | 'sleep' | 'loop';
+/**
+ * Slot 基类
+ */
+export interface BaseSlot {
+    kind: HookKind;
+}
+/**
+ * useJobState
+ */
+export interface StateSlot<T = any> extends BaseSlot {
+    kind: 'state';
+    value: T;
+}
+/**
+ * useJobEffect
+ */
+export interface EffectSlot extends BaseSlot {
+    kind: 'effect';
+    cleanup?: () => void;
+    deps?: unknown[];
+}
+/**
+ * useJobAsync
+ */
+export interface AsyncSlot<T = any> extends BaseSlot {
+    kind: 'async';
+    /**
+     * 当前异步任务状态
+     */
+    status: AsyncStatus;
+    /**
+     * 是否已经启动过（用于保证只执行一次）
+     */
+    started: boolean;
+    /**
+     * 成功结果
+     */
+    value?: T;
+    /**
+     * 错误结果
+     */
+    error?: unknown;
+    /**
+     * 中止控制器，用于在 Job destroy 时 abort
+     */
+    controller?: AbortController;
+    /**
+     * 用户提供的额外 cancel 函数
+     */
+    cancel?: () => void;
+}
+/**
+ * useJobSleep
+ */
+export interface SleepSlot extends BaseSlot {
+    kind: 'sleep';
+    /**
+     * 唤醒时间戳（performance.now / Date.now）
+     * 为 null 表示尚未设定
+     */
+    until: number | null;
+    /**
+     * 当前 sleep 是否已经完成。
+     * 完成后，再次调用 useJobSleep 不会重新进入等待。
+     */
+    done: boolean;
+    promise?: Promise<void>;
+    resolve?: () => void;
+}
+/**
+ * useJobLoop
+ */
+export interface LoopSlot extends BaseSlot {
+    kind: 'loop';
+    index: number;
+}
+/**
+ * Job 所有 Slot 联合类型
+ */
+export type HookSlot = StateSlot | EffectSlot | AsyncSlot | SleepSlot | LoopSlot;
+
+/**
+ * Job 逻辑函数（JobComponent）
+ *
+ * - Props 为 Job 的参数类型；
+ * - 函数内部可以使用 Job Hooks；
+ * - 返回值当前未使用，预留为 void。
+ */
+export type JobComponent<Props = unknown> = (props: Props) => void;
+
+/**
+ * JobContext
+ *
+ * 每个 Job 拥有独立的上下文，
+ * 内部包含所有 hook slot 数据。
+ *
+ * Job 每次执行一个“运行帧”时，JobContext.beginFrame() 会被调用，
+ * 用于重置 hookIndex，让 hooks 以固定顺序运行。
+ */
+export declare class JobContext {
+    /**
+     * HookSlot 数组，顺序即为 hook 调用顺序
+     */
+    private slots;
+    /**
+     * 当前执行帧中的 slot 游标
+     */
+    private hookIndex;
+    /**
+     * 获取当前帧的全部 slot
+     */
+    getAllSlots(): readonly HookSlot[];
+    /**
+     * Job 在每次运行步骤开始时调用
+     * 重置 hookIndex，确保从 slot[0] 开始
+     */
+    beginFrame(): void;
+    /**
+     * 获取或初始化一个 slot，
+     * 根据调用顺序递增 hookIndex。
+     */
+    useSlot<T extends HookSlot>(kind: HookKind, init: () => T): T;
+    /**
+     * 在 Job 结束（Completed / Cancelled / Error）时调用
+     *
+     * - 执行所有 effect cleanup
+     * - 清理 async promise（可选增强功能）
+     * - 清理 sleep timers（可选增强功能）
+     */
+    destroy(): void;
+}
+
+/**
+ * Job 生命周期状态
+ */
+export declare enum JobStatus {
+    /**
+     * 已创建但尚未开始执行
+     */
+    Idle = "Idle",
+    /**
+     * 当前正在执行（本时间片内）
+     */
+    Running = "Running",
+    /**
+     * 执行中主动让出时间片，等待下一次调度
+     */
+    Yield = "Yield",
+    /**
+     * 被外部暂停，不会被调度执行
+     */
+    Paused = "Paused",
+    /**
+     * 被外部取消或内部主动终止
+     */
+    Cancelled = "Cancelled",
+    /**
+     * 正常执行结束
+     */
+    Completed = "Completed",
+    /**
+     * 执行过程中发生未处理错误
+     */
+    Error = "Error"
+}
+
+export interface JobEvents<Props = unknown> {
+    /**
+     * Job 从 Idle -> Running 的第一次启动
+     */
+    start: (props: Props) => void;
+    /**
+     * Job 从 Paused -> Running 的恢复
+     */
+    resume: (props: Props) => void;
+    /**
+     * Job 正常完成（进入 Completed）
+     */
+    complete: (props: Props) => void;
+    /**
+     * Job 被取消（进入 Cancelled）
+     */
+    cancel: (props: Props) => void;
+    /**
+     * Job 执行出错（进入 Error）
+     */
+    error: (payload: {
+        error: unknown;
+        props: Props;
+    }) => void;
+    /**
+     * 任意状态变更
+     */
+    statusChange: (status: JobStatus) => void;
+}
+
+/**
+ * 状态迁移时的上下文参数
+ */
+interface TransitionContext<Props> {
+    props: Props;
+    error?: unknown;
+}
+/**
+ * Job 生命周期管理器
+ */
+export declare class JobLifecycle<Props = unknown> {
+    private _status;
+    private emitter;
+    get status(): JobStatus;
+    /**
+     * 判断一个 Job 是否处于终态
+     *
+     * - 终态：Cancelled / Completed / Error
+     */
+    static isTerminalStatus(status: JobStatus): boolean;
+    /**
+     * 判断一个 Job 是否仍然处于活动状态
+     *
+     * - 活动状态：Idle / Running / Yield / Paused
+     * - 终态：Cancelled / Completed / Error
+     */
+    static isActiveStatus(status: JobStatus): boolean;
+    /**
+     * 状态迁移 + 自动触发事件
+     */
+    transitionTo(next: JobStatus, ctx: TransitionContext<Props>): void;
+    on<E extends keyof JobEvents<Props>>(event: E, listener: JobEvents<Props>[E]): () => void;
+}
+
+/**
+ * 最小 Job 运行时宿主接口。
+ *
+ * - 真正的 Job 类会实现这个接口；
+ * - 这里不直接依赖具体 Job 类型，避免循环依赖。
+ * - 增加 shouldYield() 供 Hook 查询调度器是否需要让权。
+ */
+export interface JobRuntimeHost {
+    readonly context: JobContext;
+    shouldYield(): boolean;
+}
+/**
+ * 将一个 Job 压入当前执行栈。
+ * 由 Job 在每次执行步骤开始时调用。
+ */
+export declare function pushCurrentJob(job: JobRuntimeHost): void;
+/**
+ * 将当前 Job 从执行栈弹出。
+ * 由 Job 在每次执行步骤结束（无论正常或异常）时调用。
+ */
+export declare function popCurrentJob(job: JobRuntimeHost): void;
+/**
+ * 获取当前正在运行的 Job。
+ * 若在非 Job 执行上下文中调用，则抛出中文错误提示。
+ * 如果传入 `allowNoJob` 为 true，则在没有 Job 执行上下文时不抛出错误。
+ */
+export declare function getCurrentJob(allowNoJob?: boolean): JobRuntimeHost;
+/**
+ * 直接获取当前 Job 的 JobContext。
+ * 是大部分 Hook 的主要入口。
+ */
+export declare function getCurrentJobContext(): JobContext;
+
+/**
+ * Job 类
+ */
+export declare class Job<Props = unknown> implements JobRuntimeHost {
+    readonly id: string;
+    readonly key?: string;
+    readonly props: Props;
+    readonly parent?: Job<any>;
+    readonly children: Set<Job<any>>;
+    private _error;
+    get error(): unknown;
+    /**
+     * Job 生命周期管理器
+     */
+    private lifecycle;
+    /**
+     * 监听 Job 生命周期事件
+     */
+    on<E extends keyof JobEvents<Props>>(event: E, listener: JobEvents<Props>[E]): () => void;
+    /**
+     * 内部调度器
+     */
+    private scheduler;
+    /**
+     * Job 执行优先级
+     */
+    private priority;
+    /**
+     * Job 执行上下文（保存 hooks slot）
+     */
+    readonly context: JobContext;
+    /**
+     * Job 对应的运行逻辑函数
+     */
+    private component;
+    /**
+     * 当前调度任务句柄（用于取消）
+     */
+    private currentTask;
+    /**
+     * 是否已destroy，防止重复销毁
+     */
+    private destroyed;
+    constructor(component: JobComponent<Props>, options: JobOptions<Props>, schedulerFallback: Scheduler);
+    /**
+     * Job 当前状态（只读）
+     */
+    get status(): JobStatus;
+    /**
+     * 提供给 Hook 使用的 shouldYield 查询接口
+     */
+    shouldYield(): boolean;
+    /**
+     * 生成简单自增 ID
+     */
+    private static _idCounter;
+    private static generateId;
+    /**
+     * 启动 Job
+     */
+    start(): void;
+    /**
+     * 调度下一帧运行
+     */
+    private scheduleNext;
+    /**
+     * 执行一帧 Job
+     */
+    private runStep;
+    /**
+     * 正常完成 Job
+     */
+    private finishSuccessfully;
+    /**
+     * 错误处理
+     */
+    private handleError;
+    /**
+     * 释放上下文资源
+     */
+    destroy(): void;
+    /**
+     * 暂停 Job：
+     * - 仅在 Running / Yield 状态下生效
+     * - 取消当前已调度但尚未执行的 task
+     * - 不销毁上下文，后续可以 resume() 继续执行
+     */
+    pause(): void;
+    /**
+     * 恢复 Job：
+     * - 仅在 Paused 状态下生效
+     * - 重新调度下一帧执行
+     */
+    resume(): void;
+    /**
+     * 取消 Job：
+     * - 将状态置为 Cancelled
+     * - 调用 destroy() 统一清理资源
+     */
+    cancel(): void;
+}
+
+/**
+ * Job 实例配置。
+ *
+ * - id：实例唯一标识（可选，通常由 JobManager 自动注入）；
+ * - key：逻辑标识，用于并发控制；
+ * - policy：并发策略（allow/skip/replace/queue）；
+ * - priority：调度优先级；
+ * - scheduler：可选调度器，未提供时由 JobManager 注入默认值；
+ * - props：传给 JobComponent 的参数。
+ */
+export interface JobOptions<Props = unknown> {
+    /**
+     * 父 Job（可选）
+     */
+    parent?: Job;
+    /**
+     * Job 实例唯一标识（内部使用，可选）
+     */
+    id?: string;
+    /**
+     * Job 逻辑标识，用于并发控制（可选）
+     */
+    key?: string;
+    /**
+     * 调度优先级（默认 SchedulerPriority.Normal）
+     */
+    priority?: SchedulerPriority;
+    /**
+     * 该 Job 使用的调度器（可选）
+     * - 未指定时由 JobManager 提供默认调度器
+     */
+    scheduler?: Scheduler;
+    /**
+     * JobComponent 的参数
+     */
+    props: Props;
+}
+/**
+ * JobManager.run 的入参。
+ *
+ * 对外暴露时通常不包含 id（由 JobManager 自动生成）。
+ */
+export interface RunOptions<Props = unknown> {
+    /**
+     * 父 Job（可选）
+     */
+    parent?: Job;
+    /**
+     * Job 的逻辑标识（可选）
+     *
+     * - 用于按 key 管理 / 取消 / 暂停 / 恢复 Job
+     * - 支持并发控制策略
+     */
+    key?: string;
+    /**
+     * 透传给 JobComponent 的参数
+     */
+    props: Props;
+    /**
+     * 并发策略（可选）
+     */
+    policy?: ConcurrencyPolicy;
+    /**
+     * 最大并发数（仅对 allow 策略生效，可选）
+     */
+    maxConcurrency?: number;
+    /**
+     * 调度优先级（可选）
+     */
+    priority?: SchedulerPriority;
+    /**
+     * 调度器（可选）
+     */
+    scheduler?: Scheduler;
+    /**
+     * 延迟时间（可选）
+     */
+    delay?: number;
+    /**
+     * 间隔时间（可选）
+     */
+    interval?: number;
+}
+
+/**
+ * 异步任务的执行状态。
+ *
+ * 保留原来的枚举导出，方便外部使用。
+ */
+
+/**
+ * 执行异步任务并自动集成调度控制
+ *
+ * - 在首次执行时自动启动异步任务（只执行一次）
+ * - 状态管理：AsyncStatus（Idle -> Running -> Finished）
+ * - 当任务仍在进行中，会抛出 ShouldYield，以中断当前调度
+ * - 支持传入 AbortSignal（AbortController）以及 { promise, cancel } 形式
+ *
+ * 使用方式：
+ *
+ * const [result, error] = useAsync(signal => fetchData(signal))
+ */
+export declare const useJobAsync: <T>(fn: (signal: AbortSignal) => {
+    promise: Promise<T>;
+    cancel?: () => void;
+} | Promise<T>) => [T | undefined, unknown | undefined];
+
+/**
+ * useJobEffect
+ *
+ * - 语义上接近 React.useEffect
+ * - deps 为空数组 []：只在第一次执行时触发一次 effect
+ * - 省略 deps：每一帧都会重新执行 effect，并在执行前调用上一次 cleanup
+ * - deps 为数组：当依赖数组变化时，调用上一次 cleanup 并重新执行 effect
+ * - Job 完成 / 取消 / 出错销毁时，会调用最后一次 effect 的 cleanup
+ */
+export declare function useJobEffect(effect: () => void | (() => void), deps?: unknown[]): void;
+
+/**
+ * useJobLoop
+ *
+ * 用于在 Job 内部分片执行长循环任务。
+ *
+ * - length：循环总长度（通常是数组长度）
+ * - body：每次迭代的处理函数，接收当前 index
+ *
+ * 运行机制：
+ * - 内部通过 LoopSlot 记录当前已经执行到的 index
+ * - 每次执行时从 slot.index 开始继续往后处理
+ * - 每次 body 执行后检查 job.shouldYield()
+ *   - 若需要让权，则抛出 ShouldYield 错误，交由 Job 捕获并在下一帧继续
+ * - 当 index 走到 length 时，循环结束，slot.index 记录为 length
+ */
+export declare function useJobLoop(length: number, body: (index: number) => void): void;
+
+/**
+ * useJobSleep
+ *
+ * 在 Job 内“睡眠”一段时间：
+ * - 第一次调用时记录唤醒时间 until = now + ms；
+ * - 在 now < until 期间，每次调用都会抛出 ShouldYield，让出时间片；
+ * - 当 now >= until 时，本次 sleep 结束，不再抛错，后续逻辑继续执行；
+ *
+ * ⚠️ 使用约束：
+ * - 必须在 Job 顶层调用（遵守 Hook 规则），不要在循环体或回调中动态增删；
+ * - 尤其不要在 useJobLoop 的 body 里调用 useJobSleep，这会让控制流难以推理。
+ */
+export declare function useJobSleep(ms: number): void;
+
+/**
+ * useJobState
+ *
+ * - 与 React.useState 类似，用于在 Job 内部存储状态
+ * - 状态存储在当前 Job 的 JobContext 中，不会泄漏到其他 Job
+ * - 不会自动触发“重渲染”，Job 的推进依然由其他 Hook（loop/sleep/async）控制
+ */
+export declare function useJobState<T>(initial: T | (() => T)): [T, (next: T) => void];
+
+/**
+ * 运行时断言工具。
+ *
+ * - condition 为 false 时抛出带中文信息的错误；
+ * - 主要用于内部开发态校验，不用于业务异常控制。
+ */
+export declare function invariant(condition: unknown, message: string): asserts condition;
+
+/**
+ * Job 对外暴露的句柄类型
+ *
+ * - 业务侧通过 JobHandle 控制 Job
+ * - 不建议直接操作 Job 实例本身
+ */
+export interface JobHandle<Props = unknown> {
+    /**
+     * 逻辑标识（可选），通常对应 RunOptions.key
+     */
+    readonly key?: string;
+    /**
+     * 当前 Job 状态（读取自底层 Job）
+     */
+    readonly status: JobStatus;
+    /**
+     * 直接暴露 Job 实例（主要用于测试场景）
+     *
+     * - 业务代码建议只使用 handle 提供的方法，不直接操作 Job
+     */
+    readonly job: Job<Props>;
+    /**
+     * 取消 Job
+     */
+    cancel(cascade?: boolean): void;
+    /**
+     * 暂停 Job
+     */
+    pause(): void;
+    /**
+     * 恢复 Job
+     */
+    resume(): void;
+    /**
+     * 监听 Job 事件
+     */
+    on<E extends keyof JobEvents<Props>>(event: E, listener: JobEvents<Props>[E]): () => void;
+    /**
+     * 将 Job 状态转换为 Promise：
+     */
+    toPromise: () => Promise<void>;
+}
+/**
+ * JobHandle 的默认实现
+ *
+ * - 目前只是简单地代理到底层 Job
+ * - 后续如果需要可以在这里加更多 handle 级的逻辑（如埋点、缓存等）
+ */
+export declare class JobHandleImpl<Props = unknown> implements JobHandle<Props> {
+    readonly job: Job<Props>;
+    readonly key?: string | undefined;
+    private _promise?;
+    constructor(job: Job<Props>, key?: string | undefined);
+    get status(): JobStatus;
+    get error(): unknown;
+    cancel(cascade?: boolean): void;
+    pause(): void;
+    resume(): void;
+    toPromise(): Promise<void>;
+    on<E extends keyof JobEvents<Props>>(event: E, listener: JobEvents<Props>[E]): () => void;
+}
+/**
+ * 工具函数：从 Job 创建一个 JobHandle
+ */
+export declare function createJobHandle<Props>(job: Job<Props>, key?: string): JobHandle<Props>;
+/**
+ * 工具函数：创建一个 Noop JobHandle
+ */
+export declare function createNoopHandle<Props = unknown>(key?: string): JobHandle<Props>;
+
+/**
+ * JobManager：Job 的集合管理器
+ *
+ * - 负责创建并启动 Job
+ * - 通过 key 管理 Job 引用
+ * - 提供 cancel/pause/resume 能力
+ * - 带基础并发策略
+ */
+export declare class JobManager {
+    private readonly registry;
+    private concurrency;
+    constructor(scheduler: Scheduler);
+    /**
+     * 创建并启动一个新的 Job，并根据并发策略处理同 key Job，并返回 JobHandle。
+     */
+    run<Props>(component: JobComponent<Props>, options: RunOptions<Props>): JobHandle<Props>;
+    /**
+     * 按 key 取消 Job：
+     * - 当前实现：取消该 key 下所有 Job（包含活动和终态，终态调用 cancel 为 no-op）
+     */
+    cancel(key: string): void;
+    /**
+     * 按 key 暂停 Job：
+     * - 暂停该 key 下所有活跃 Job
+     */
+    pause(key: string): void;
+    /**
+     * 按 key 恢复 Job：
+     * - 恢复该 key 下所有处于 Paused 状态的 Job
+     */
+    resume(key: string): void;
+    /**
+     * 获取指定 key 对应的“最近的一个 Job”（主要用于测试/调试）
+     */
+    getJob<Props = unknown>(key: string): Job<Props> | undefined;
+}
+
+/**
+ * JobKeyRegistry
+ *
+ * - 按 key 管理 Job 引用
+ * - 当前版本：每个 key 下可以存在多个 Job 实例（用于 allow 并发）
+ * - 后续扩展并发策略时，可以基于此实现 skip/replace/queue 等行为
+ */
+export declare class JobKeyRegistry {
+    private readonly jobsByKey;
+    /**
+     * 注册一个 Job 到指定 key 下
+     */
+    register(key: string, job: Job<any>): void;
+    /**
+     * 获取指定 key 下的所有 Job（可能为空数组）
+     */
+    getJobs<Props = unknown>(key: string): Job<Props>[];
+    /**
+     * 获取指定 key 下最近注册的一个 Job。
+     *
+     * - 用于 getJob 等场景，默认返回“最后一个创建”的 Job
+     */
+    getLatest<Props = unknown>(key: string): Job<Props> | undefined;
+    /**
+     * 删除指定 key 下的某个 Job 引用
+     */
+    deleteJob(key: string, job: Job<any>): void;
+    /**
+     * 删除整个 key（通常在全量 reset 或不再需要管理该 key 时使用）
+     */
+    deleteKey(key: string): void;
+    /**
+     * 清空所有 key → Job 关联（通常在全量 reset 时使用）
+     */
+    clear(): void;
+}
+
+/**
+ * 并发控制器：根据不同并发策略管理 Job 的创建和启动
+ */
+export declare class ConcurrencyController {
+    private defaultScheduler;
+    private onCreateJob;
+    private queueManager;
+    constructor(defaultScheduler: Scheduler, onCreateJob: <Props>(job: Job<Props>) => void);
+    /**
+     * 统一入口，按 policy 决定如何处理
+     */
+    run<Props>(component: JobComponent<Props>, options: JobOptions<Props> & {
+        policy: ConcurrencyPolicy;
+        maxConcurrency?: number;
+    }, getExistingJobs: () => Job<Props>[]): Job<Props> | null;
+    private createJob;
+    private enqueueJob;
+    private runAllow;
+    private runSkip;
+    private runReplace;
+    private runQueue;
+}
+
+