@enableai-job-runtime/core 0.0.5

package/dist/core.cjs.prod.js

@@ -0,0 +1,899 @@
+/**
+* @enableai-job-runtime/core v0.0.5
+* (c) 2024-present Enableai
+* @license Proprietary
+**/
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var EventEmitter = require('eventemitter3');
+var PQueue = require('p-queue');
+
+const AsyncStatus = {
+  "Idle": 0,
+  "0": "Idle",
+  "Running": 1,
+  "1": "Running",
+  "Finished": 2,
+  "2": "Finished"
+};
+
+const DEFAULT_CONCURRENCY_POLICY = "allow";
+
+const JobErrorCode = { "ShouldYield": "ShouldYield" };
+class JobError extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.name = "JobError";
+    this.code = code;
+  }
+}
+function isShouldYieldError(error) {
+  return error instanceof JobError && error.code === "ShouldYield";
+}
+function createShouldYieldError() {
+  return new JobError("ShouldYield");
+}
+
+class JobContext {
+  constructor() {
+    /**
+     * HookSlot 数组，顺序即为 hook 调用顺序
+     */
+    this.slots = [];
+    /**
+     * 当前执行帧中的 slot 游标
+     */
+    this.hookIndex = 0;
+  }
+  /**
+   * 获取当前帧的全部 slot
+   */
+  getAllSlots() {
+    return this.slots;
+  }
+  /**
+   * Job 在每次运行步骤开始时调用
+   * 重置 hookIndex，确保从 slot[0] 开始
+   */
+  beginFrame() {
+    this.hookIndex = 0;
+  }
+  /**
+   * 获取或初始化一个 slot，
+   * 根据调用顺序递增 hookIndex。
+   */
+  useSlot(kind, init) {
+    const index = this.hookIndex++;
+    let slot = this.slots[index];
+    if (!slot) {
+      slot = init();
+      this.slots[index] = slot;
+      return slot;
+    }
+    if (slot.kind !== kind) {
+      throw new Error(
+        `[JobContext] \u7B2C ${index} \u4E2A Hook \u7684\u7C7B\u578B\u4E0D\u4E00\u81F4\uFF1A\u9884\u671F\u4E3A "${kind}"\uFF0C\u5B9E\u9645\u4E3A "${slot.kind}"\u3002\u8BF7\u786E\u4FDD\u6BCF\u6B21\u6267\u884C\u65F6 Hook \u7684\u8C03\u7528\u987A\u5E8F\u5B8C\u5168\u4E00\u81F4\u3002`
+      );
+    }
+    return slot;
+  }
+  /**
+   * 在 Job 结束（Completed / Cancelled / Error）时调用
+   *
+   * - 执行所有 effect cleanup
+   * - 清理 async promise（可选增强功能）
+   * - 清理 sleep timers（可选增强功能）
+   */
+  destroy() {
+    for (const slot of this.slots) {
+      if (slot.kind === "effect") {
+        slot.cleanup?.();
+      }
+      if (slot.kind === "async") {
+        slot.controller?.abort();
+        slot.cancel?.();
+      }
+    }
+    this.slots = [];
+  }
+}
+
+const JobStatus = {
+  "Idle": "Idle",
+  "Running": "Running",
+  "Yield": "Yield",
+  "Paused": "Paused",
+  "Cancelled": "Cancelled",
+  "Completed": "Completed",
+  "Error": "Error"
+};
+
+class JobLifecycle {
+  constructor() {
+    this._status = "Idle";
+    this.emitter = new EventEmitter();
+  }
+  get status() {
+    return this._status;
+  }
+  /**
+   * 判断一个 Job 是否处于终态
+   *
+   * - 终态：Cancelled / Completed / Error
+   */
+  static isTerminalStatus(status) {
+    return status === "Completed" || status === "Cancelled" || status === "Error";
+  }
+  /**
+   * 判断一个 Job 是否仍然处于活动状态
+   *
+   * - 活动状态：Idle / Running / Yield / Paused
+   * - 终态：Cancelled / Completed / Error
+   */
+  static isActiveStatus(status) {
+    return status === "Idle" || status === "Running" || status === "Yield" || status === "Paused";
+  }
+  /**
+   * 状态迁移 + 自动触发事件
+   */
+  transitionTo(next, ctx) {
+    const prev = this._status;
+    if (prev === next) return;
+    this._status = next;
+    this.emitter.emit("statusChange", next);
+    if (prev === "Idle" && next === "Running") {
+      this.emitter.emit("start", ctx.props);
+    } else if (prev === "Paused" && next === "Running") {
+      this.emitter.emit("resume", ctx.props);
+    }
+    if (next === "Completed") {
+      this.emitter.emit("complete", ctx.props);
+    } else if (next === "Cancelled") {
+      this.emitter.emit("cancel", ctx.props);
+    } else if (next === "Error" && ctx.error !== void 0) {
+      this.emitter.emit("error", { error: ctx.error, props: ctx.props });
+    }
+    if (JobLifecycle.isTerminalStatus(next)) {
+      this.emitter.removeAllListeners();
+    }
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+    return () => {
+      this.emitter.off(event, listener);
+    };
+  }
+}
+
+function invariant(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const jobStack = [];
+function pushCurrentJob(job) {
+  jobStack.push(job);
+}
+function popCurrentJob(job) {
+  const current = jobStack.pop();
+  if (current !== job) {
+    throw new Error(
+      "[JobRuntime] \u5F53\u524D Job \u51FA\u6808\u987A\u5E8F\u5F02\u5E38\uFF1A\u8BF7\u68C0\u67E5\u662F\u5426\u5728\u6B63\u786E\u7684 try/finally \u4E2D\u8C03\u7528 pushCurrentJob/popCurrentJob\u3002"
+    );
+  }
+}
+function getCurrentJob(allowNoJob = false) {
+  const current = jobStack[jobStack.length - 1];
+  if (!current && allowNoJob) {
+    return void 0;
+  }
+  invariant(
+    !!current,
+    "[JobRuntime] \u5F53\u524D\u6CA1\u6709\u6B63\u5728\u8FD0\u884C\u7684 Job\uFF0C\u8BF7\u786E\u8BA4 Job Hooks \u662F\u5426\u5728 Job \u51FD\u6570\u5185\u90E8\u88AB\u8C03\u7528\uFF08\u800C\u4E0D\u662F\u5728\u666E\u901A\u51FD\u6570\u6216\u5F02\u6B65\u56DE\u8C03\u4E2D\uFF09\u3002"
+  );
+  return current;
+}
+function getCurrentJobContext() {
+  return getCurrentJob().context;
+}
+
+const _Job = class _Job {
+  constructor(component, options, schedulerFallback) {
+    this.children = /* @__PURE__ */ new Set();
+    this._error = void 0;
+    /**
+     * Job 生命周期管理器
+     */
+    this.lifecycle = new JobLifecycle();
+    /**
+     * Job 执行上下文（保存 hooks slot）
+     */
+    this.context = new JobContext();
+    /**
+     * 当前调度任务句柄（用于取消）
+     */
+    this.currentTask = null;
+    /**
+     * 是否已destroy，防止重复销毁
+     */
+    this.destroyed = false;
+    invariant(typeof component === "function", "[Job] component \u5FC5\u987B\u662F\u51FD\u6570");
+    this.component = component;
+    const { id, key, props, scheduler, priority, parent } = options;
+    this.id = id ?? _Job.generateId();
+    this.key = key;
+    this.props = props;
+    this.scheduler = scheduler ?? schedulerFallback;
+    this.priority = priority ?? 3;
+    this.parent = parent;
+    if (parent) {
+      parent.children.add(this);
+    }
+  }
+  get error() {
+    return this._error;
+  }
+  /**
+   * 监听 Job 生命周期事件
+   */
+  on(event, listener) {
+    return this.lifecycle.on(event, listener);
+  }
+  /**
+   * Job 当前状态（只读）
+   */
+  get status() {
+    return this.lifecycle.status;
+  }
+  /**
+   * 提供给 Hook 使用的 shouldYield 查询接口
+   */
+  shouldYield() {
+    return this.scheduler.shouldYield();
+  }
+  static generateId() {
+    return `job_${this._idCounter++}`;
+  }
+  /**
+   * 启动 Job
+   */
+  start() {
+    if (this.destroyed) return;
+    if (this.status !== "Idle") return;
+    this.lifecycle.transitionTo("Running", { props: this.props });
+    this.scheduleNext();
+  }
+  /**
+   * 调度下一帧运行
+   */
+  scheduleNext() {
+    if (this.destroyed) return;
+    if (this.currentTask) {
+      this.scheduler.cancel(this.currentTask);
+      this.currentTask = null;
+    }
+    this.currentTask = this.scheduler.schedule(this.priority, () => this.runStep());
+  }
+  /**
+   * 执行一帧 Job
+   */
+  runStep() {
+    if (this.status !== "Running" && this.status !== "Yield") return;
+    if (this.destroyed) return;
+    if (JobLifecycle.isTerminalStatus(this.status)) return;
+    this.lifecycle.transitionTo("Running", { props: this.props });
+    pushCurrentJob(this);
+    this.context.beginFrame();
+    try {
+      this.component(this.props);
+      this.finishSuccessfully();
+    } catch (err) {
+      if (isShouldYieldError(err)) {
+        this.lifecycle.transitionTo("Yield", { props: this.props });
+        this.scheduleNext();
+        return;
+      }
+      this.handleError(err);
+    } finally {
+      popCurrentJob(this);
+    }
+  }
+  /**
+   * 正常完成 Job
+   */
+  finishSuccessfully() {
+    if (this.destroyed) return;
+    this.lifecycle.transitionTo("Completed", { props: this.props });
+    this.destroy();
+  }
+  /**
+   * 错误处理
+   */
+  handleError(error) {
+    if (this.destroyed) return;
+    this.lifecycle.transitionTo("Error", { props: this.props, error });
+    this._error = error;
+    this.destroy();
+  }
+  /**
+   * 释放上下文资源
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.currentTask) {
+      this.scheduler.cancel(this.currentTask);
+      this.currentTask = null;
+    }
+    this.context.destroy();
+    if (this.parent) {
+      this.parent.children.delete(this);
+    }
+  }
+  /**
+   * 暂停 Job：
+   * - 仅在 Running / Yield 状态下生效
+   * - 取消当前已调度但尚未执行的 task
+   * - 不销毁上下文，后续可以 resume() 继续执行
+   */
+  pause() {
+    if (this.destroyed) return;
+    if (this.lifecycle.status !== "Running" && this.lifecycle.status !== "Yield") return;
+    this.lifecycle.transitionTo("Paused", { props: this.props });
+    if (this.currentTask) {
+      this.scheduler.cancel(this.currentTask);
+      this.currentTask = null;
+    }
+  }
+  /**
+   * 恢复 Job：
+   * - 仅在 Paused 状态下生效
+   * - 重新调度下一帧执行
+   */
+  resume() {
+    if (this.destroyed) return;
+    if (this.status !== "Paused") return;
+    this.lifecycle.transitionTo("Running", { props: this.props });
+    this.scheduleNext();
+  }
+  /**
+   * 取消 Job：
+   * - 将状态置为 Cancelled
+   * - 调用 destroy() 统一清理资源
+   */
+  cancel() {
+    if (this.destroyed) return;
+    if (JobLifecycle.isTerminalStatus(this.status)) return;
+    this.lifecycle.transitionTo("Cancelled", { props: this.props });
+    this.destroy();
+  }
+};
+/**
+ * 生成简单自增 ID
+ */
+_Job._idCounter = 1;
+let Job = _Job;
+
+const useJobAsync = (fn) => {
+  const context = getCurrentJobContext();
+  const slot = context.useSlot("async", () => ({
+    kind: "async",
+    status: 0,
+    started: false,
+    value: void 0,
+    error: void 0,
+    controller: void 0,
+    cancel: void 0
+  }));
+  if (!slot.started) {
+    slot.started = true;
+    const controller = new AbortController();
+    slot.controller = controller;
+    const signal = controller.signal;
+    const returned = fn(signal);
+    let promise;
+    let cancel;
+    if (typeof returned === "object" && returned !== null && "promise" in returned) {
+      promise = returned.promise;
+      cancel = returned.cancel;
+    } else {
+      promise = returned;
+    }
+    slot.cancel = cancel;
+    slot.status = 1;
+    promise.then((res) => {
+      slot.value = res;
+    }).catch((err) => {
+      slot.error = err;
+    }).finally(() => {
+      slot.status = 2;
+    });
+  }
+  switch (slot.status) {
+    case 0:
+    case 1: {
+      throw createShouldYieldError();
+    }
+    case 2: {
+      return [slot.value, slot.error];
+    }
+    default: {
+      throw new Error("[useAsync] \u65E0\u6548\u7684\u5F02\u6B65\u72B6\u6001\uFF1A" + String(slot.status));
+    }
+  }
+};
+
+function depsAreEqual(prev, next) {
+  if (!prev || !next) return false;
+  if (prev.length !== next.length) return false;
+  for (let i = 0; i < prev.length; i++) {
+    if (!Object.is(prev[i], next[i])) {
+      return false;
+    }
+  }
+  return true;
+}
+function useJobEffect(effect, deps) {
+  const context = getCurrentJobContext();
+  const slot = context.useSlot("effect", () => ({
+    kind: "effect",
+    cleanup: void 0,
+    deps: void 0
+  }));
+  if (deps === void 0) {
+    if (slot.cleanup) {
+      slot.cleanup();
+    }
+    const cleanup2 = effect();
+    slot.cleanup = typeof cleanup2 === "function" ? cleanup2 : void 0;
+    slot.deps = void 0;
+    return;
+  }
+  const shouldRun = !slot.deps || !depsAreEqual(slot.deps, deps);
+  if (!shouldRun) return;
+  if (slot.cleanup) slot.cleanup();
+  const cleanup = effect();
+  slot.cleanup = typeof cleanup === "function" ? cleanup : void 0;
+  slot.deps = deps;
+}
+
+function useJobLoop(length, body) {
+  const job = getCurrentJob();
+  const context = getCurrentJobContext();
+  const slot = context.useSlot("loop", () => ({
+    kind: "loop",
+    index: 0
+  }));
+  for (let i = slot.index; i < length; i++) {
+    try {
+      body(i);
+    } catch (err) {
+      if (isShouldYieldError(err)) {
+        throw new Error(
+          "[useJobLoop] \u5FAA\u73AF\u4F53\u5185\u90E8\u4E0D\u5141\u8BB8\u76F4\u63A5\u89E6\u53D1\u8BA9\u6743\uFF08\u5982\u624B\u52A8 throw createShouldYieldError \u6216\u4F7F\u7528\u4F1A\u629B\u51FA ShouldYield \u7684 Hook\uFF09\u3002\u8BF7\u6539\u4E3A\u5728\u5FAA\u73AF\u5916\u90E8\u4F7F\u7528\u5176\u4ED6 Hook \u63A7\u5236\u8BA9\u6743\uFF0C\u6216\u62C6\u5206\u903B\u8F91\u3002"
+        );
+      }
+      throw err;
+    }
+    slot.index = i + 1;
+    if (job.shouldYield()) {
+      throw createShouldYieldError();
+    }
+  }
+  slot.index = length;
+}
+
+function getNow() {
+  if (typeof performance !== "undefined" && performance.now) {
+    return performance.now();
+  }
+  return Date.now();
+}
+function useJobSleep(ms) {
+  const context = getCurrentJobContext();
+  const slot = context.useSlot("sleep", () => ({
+    kind: "sleep",
+    until: null,
+    done: false,
+    promise: void 0,
+    resolve: void 0
+  }));
+  if (slot.done) return;
+  const now = getNow();
+  if (slot.until == null) {
+    slot.until = now + ms;
+  }
+  if (now < slot.until) {
+    throw createShouldYieldError();
+  }
+  slot.done = true;
+  slot.until = null;
+}
+
+function useJobState(initial) {
+  const context = getCurrentJobContext();
+  const slot = context.useSlot("state", () => {
+    const value = typeof initial === "function" ? initial() : initial;
+    return {
+      kind: "state",
+      value
+    };
+  });
+  const setValue = (next) => {
+    slot.value = next;
+  };
+  return [slot.value, setValue];
+}
+
+class JobHandleImpl {
+  constructor(job, key) {
+    this.job = job;
+    this.key = key;
+  }
+  get status() {
+    return this.job.status;
+  }
+  get error() {
+    return this.job.error;
+  }
+  cancel(cascade = false) {
+    this.job.cancel();
+    if (cascade) {
+      const cancelChildren = (job) => {
+        for (const child of job.children) {
+          child.cancel();
+          cancelChildren(child);
+        }
+      };
+      cancelChildren(this.job);
+    }
+  }
+  pause() {
+    this.job.pause();
+  }
+  resume() {
+    this.job.resume();
+  }
+  toPromise() {
+    if (this._promise) return this._promise;
+    this._promise = new Promise((resolve, reject) => {
+      const status = this.status;
+      if (status === "Completed") {
+        return resolve();
+      } else if (status === "Cancelled") {
+        return reject({ isCancelled: true });
+      } else if (status === "Error") {
+        return reject(this.error);
+      }
+      this.job.on("complete", () => resolve());
+      this.job.on("cancel", () => reject({ isCancelled: true }));
+      this.job.on("error", ({ error }) => reject(error));
+    });
+    return this._promise;
+  }
+  on(event, listener) {
+    return this.job.on(event, listener);
+  }
+}
+function createJobHandle(job, key) {
+  return new JobHandleImpl(job, key);
+}
+class NoopJobHandle {
+  constructor(key) {
+    this.key = key;
+  }
+  /**
+   * 永远返回 Completed：
+   * - 表示“这个调用已经结束，没有正在运行的 Job”
+   * - skip 语义下非常合理
+   */
+  get status() {
+    return "Completed";
+  }
+  /**
+   * 提供一个最小可用的 fake Job
+   *
+   * ⚠️ 只用于：
+   * - 测试
+   * - 调试 / 打 log
+   *
+   * 不建议业务侧真正依赖
+   */
+  get job() {
+    return void 0;
+  }
+  toPromise() {
+    return Promise.resolve();
+  }
+  cancel() {
+  }
+  pause() {
+  }
+  resume() {
+  }
+  on(_event, _listener) {
+    return () => {
+    };
+  }
+}
+function createNoopHandle(key) {
+  return new NoopJobHandle(key);
+}
+
+class JobQueueManager {
+  constructor() {
+    this.queues = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 获取 / 创建某个 key 对应的队列
+   */
+  getOrCreateQueue(key, concurrency) {
+    if (!key) {
+      throw new Error("JobQueueManager \u9700\u8981 key");
+    }
+    let queue = this.queues.get(key);
+    if (!queue) {
+      queue = new PQueue({ concurrency });
+      this.queues.set(key, queue);
+    } else {
+      queue.concurrency = concurrency;
+    }
+    return queue;
+  }
+  /**
+   * 将一个任务丢到指定 key 的队列里去执行
+   */
+  enqueue(key, concurrency, task) {
+    const queue = this.getOrCreateQueue(key, concurrency);
+    queue.add(task);
+  }
+}
+
+class ConcurrencyController {
+  // 用于创建 Job 的工厂：由 JobManager 注入
+  constructor(defaultScheduler, onCreateJob) {
+    this.defaultScheduler = defaultScheduler;
+    this.onCreateJob = onCreateJob;
+    this.queueManager = new JobQueueManager();
+  }
+  /**
+   * 统一入口，按 policy 决定如何处理
+   */
+  run(component, options, getExistingJobs) {
+    const { policy, key } = options;
+    const getActiveJobs = () => getExistingJobs().filter((job) => !JobStatusIsTerminal(job.status));
+    switch (policy) {
+      case "allow":
+        return this.runAllow(component, options);
+      case "skip":
+        return this.runSkip(component, options, getActiveJobs());
+      case "replace":
+        return this.runReplace(component, options, getActiveJobs());
+      case "queue":
+        if (!key) {
+          throw new Error("\u5E76\u53D1\u7B56\u7565 queue \u9700\u8981\u6307\u5B9A key");
+        }
+        return this.runQueue(component, options, key);
+      default:
+        throw new Error(`\u672A\u77E5\u7684\u5E76\u53D1\u7B56\u7565\uFF1A${policy}`);
+    }
+  }
+  createJob(component, options) {
+    const job = new Job(component, options, this.defaultScheduler);
+    this.onCreateJob(job);
+    return job;
+  }
+  enqueueJob(key, concurrency, job) {
+    return this.queueManager.enqueue(key, concurrency, async () => {
+      if (job.status === "Cancelled") return;
+      job.start();
+      await new Promise((resolve) => {
+        const offComplete = job.on("complete", () => {
+          offAll();
+          resolve();
+        });
+        const offCancel = job.on("cancel", () => {
+          offAll();
+          resolve();
+        });
+        const offError = job.on("error", () => {
+          offAll();
+          resolve();
+        });
+        const offAll = () => {
+          offComplete();
+          offCancel();
+          offError();
+        };
+      });
+    });
+  }
+  // ------- 各策略具体实现 -------
+  runAllow(component, options) {
+    const { key, maxConcurrency } = options;
+    if (!maxConcurrency || maxConcurrency <= 0 || !key) {
+      const job2 = this.createJob(component, options);
+      job2.start();
+      return job2;
+    }
+    const job = this.createJob(component, options);
+    this.enqueueJob(key, maxConcurrency, job);
+    return job;
+  }
+  runSkip(component, options, activeJobs) {
+    if (activeJobs.length > 0) {
+      return activeJobs[activeJobs.length - 1];
+    }
+    return this.runAllow(component, options);
+  }
+  runReplace(component, options, activeJobs) {
+    for (const job of activeJobs) {
+      job.cancel();
+    }
+    return this.runAllow(component, options);
+  }
+  runQueue(component, options, key) {
+    const job = this.createJob(component, options);
+    const concurrency = options.maxConcurrency && options.maxConcurrency > 0 ? options.maxConcurrency : 1;
+    this.enqueueJob(key, concurrency, job);
+    return job;
+  }
+}
+function JobStatusIsTerminal(status) {
+  return status === "Completed" || status === "Cancelled" || status === "Error";
+}
+
+class JobKeyRegistry {
+  constructor() {
+    this.jobsByKey = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 注册一个 Job 到指定 key 下
+   */
+  register(key, job) {
+    let set = this.jobsByKey.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.jobsByKey.set(key, set);
+    }
+    set.add(job);
+    const unsubscribe = job.on("statusChange", (status) => {
+      if (JobLifecycle.isTerminalStatus(status)) {
+        this.deleteJob(key, job);
+        unsubscribe();
+      }
+    });
+  }
+  /**
+   * 获取指定 key 下的所有 Job（可能为空数组）
+   */
+  getJobs(key) {
+    const set = this.jobsByKey.get(key);
+    if (!set) return [];
+    return Array.from(set);
+  }
+  /**
+   * 获取指定 key 下最近注册的一个 Job。
+   *
+   * - 用于 getJob 等场景，默认返回“最后一个创建”的 Job
+   */
+  getLatest(key) {
+    const set = this.jobsByKey.get(key);
+    if (!set) return void 0;
+    let latest;
+    for (const job of set) {
+      latest = job;
+    }
+    return latest;
+  }
+  /**
+   * 删除指定 key 下的某个 Job 引用
+   */
+  deleteJob(key, job) {
+    const set = this.jobsByKey.get(key);
+    if (!set) return;
+    set.delete(job);
+    if (set.size === 0) {
+      this.jobsByKey.delete(key);
+    }
+  }
+  /**
+   * 删除整个 key（通常在全量 reset 或不再需要管理该 key 时使用）
+   */
+  deleteKey(key) {
+    this.jobsByKey.delete(key);
+  }
+  /**
+   * 清空所有 key → Job 关联（通常在全量 reset 时使用）
+   */
+  clear() {
+    this.jobsByKey.clear();
+  }
+}
+
+class JobManager {
+  constructor(scheduler) {
+    this.registry = new JobKeyRegistry();
+    this.concurrency = new ConcurrencyController(scheduler, (job) => {
+      if (job.key) this.registry.register(job.key, job);
+    });
+  }
+  /**
+   * 创建并启动一个新的 Job，并根据并发策略处理同 key Job，并返回 JobHandle。
+   */
+  run(component, options) {
+    const { key, policy = DEFAULT_CONCURRENCY_POLICY, maxConcurrency, parent = getCurrentJob(true) } = options;
+    const job = this.concurrency.run(component, { ...options, policy, maxConcurrency, parent }, () => {
+      return key ? this.registry.getJobs(key) : [];
+    });
+    return job ? createJobHandle(job, key) : createNoopHandle(key);
+  }
+  /**
+   * 按 key 取消 Job：
+   * - 当前实现：取消该 key 下所有 Job（包含活动和终态，终态调用 cancel 为 no-op）
+   */
+  cancel(key) {
+    const jobs = this.registry.getJobs(key);
+    for (const job of jobs) {
+      job.cancel();
+    }
+  }
+  /**
+   * 按 key 暂停 Job：
+   * - 暂停该 key 下所有活跃 Job
+   */
+  pause(key) {
+    const jobs = this.registry.getJobs(key);
+    for (const job of jobs) {
+      if (JobLifecycle.isActiveStatus(job.status)) {
+        job.pause();
+      }
+    }
+  }
+  /**
+   * 按 key 恢复 Job：
+   * - 恢复该 key 下所有处于 Paused 状态的 Job
+   */
+  resume(key) {
+    const jobs = this.registry.getJobs(key);
+    for (const job of jobs) {
+      if (job.status === "Paused") {
+        job.resume();
+      }
+    }
+  }
+  /**
+   * 获取指定 key 对应的“最近的一个 Job”（主要用于测试/调试）
+   */
+  getJob(key) {
+    return this.registry.getLatest(key);
+  }
+}
+
+exports.AsyncStatus = AsyncStatus;
+exports.ConcurrencyController = ConcurrencyController;
+exports.DEFAULT_CONCURRENCY_POLICY = DEFAULT_CONCURRENCY_POLICY;
+exports.Job = Job;
+exports.JobContext = JobContext;
+exports.JobError = JobError;
+exports.JobErrorCode = JobErrorCode;
+exports.JobHandleImpl = JobHandleImpl;
+exports.JobKeyRegistry = JobKeyRegistry;
+exports.JobLifecycle = JobLifecycle;
+exports.JobManager = JobManager;
+exports.JobStatus = JobStatus;
+exports.createJobHandle = createJobHandle;
+exports.createNoopHandle = createNoopHandle;
+exports.createShouldYieldError = createShouldYieldError;
+exports.getCurrentJob = getCurrentJob;
+exports.getCurrentJobContext = getCurrentJobContext;
+exports.invariant = invariant;
+exports.isShouldYieldError = isShouldYieldError;
+exports.popCurrentJob = popCurrentJob;
+exports.pushCurrentJob = pushCurrentJob;
+exports.useJobAsync = useJobAsync;
+exports.useJobEffect = useJobEffect;
+exports.useJobLoop = useJobLoop;
+exports.useJobSleep = useJobSleep;
+exports.useJobState = useJobState;