@enableai-job-runtime/scheduler 0.0.5

package/dist/scheduler.cjs.js

@@ -0,0 +1,23 @@
+/**
+* @enableai-job-runtime/scheduler v0.0.5
+* (c) 2024-present Enableai
+* @license Proprietary
+**/
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const SchedulerPriority = {
+  "Immediate": 1,
+  "1": "Immediate",
+  "UserBlocking": 2,
+  "2": "UserBlocking",
+  "Normal": 3,
+  "3": "Normal",
+  "Low": 4,
+  "4": "Low",
+  "Idle": 5,
+  "5": "Idle"
+};
+
+exports.SchedulerPriority = SchedulerPriority;

package/dist/scheduler.cjs.prod.js

@@ -0,0 +1,23 @@
+/**
+* @enableai-job-runtime/scheduler v0.0.5
+* (c) 2024-present Enableai
+* @license Proprietary
+**/
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const SchedulerPriority = {
+  "Immediate": 1,
+  "1": "Immediate",
+  "UserBlocking": 2,
+  "2": "UserBlocking",
+  "Normal": 3,
+  "3": "Normal",
+  "Low": 4,
+  "4": "Low",
+  "Idle": 5,
+  "5": "Idle"
+};
+
+exports.SchedulerPriority = SchedulerPriority;

package/dist/scheduler.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 任务优先级（SchedulerPriority）
+ *
+ * 描述 Job 在调度过程中所使用的执行优先级。
+ *
+ * Job Runtime 使用与 React Scheduler 类似的调度思想，但优先级枚举保持独立，
+ * 以便在不同环境（浏览器、Node、WASM）灵活映射到底层调度器实现。
+ *
+ * ⚠️ 优先级仅决定“调度器何时推动下一步 Job.runStep() 执行”。
+ *     它不会绕过 Job 内部的 shouldYield()，也不会阻止协作式让权逻辑。
+ *
+ * 设计目标：
+ *  - 高优先任务更快轮到
+ *  - 普通任务保持正常节奏
+ *  - 低优任务在空闲时慢慢执行
+ *  - 避免任意 Job 长时间独占主线程
+ *
+ * 使用建议：
+ *  - 除非极特殊场景，不推荐使用 Immediate（它无法进行时间片分割）
+ *  - 大部分业务逻辑使用 Normal 即可
+ *  - 与用户体验强相关、点击触发的逻辑，可视情况用 UserBlocking
+ *  - 后台批处理、日志收集等任务建议使用 Low 或 Idle
+ */
+export declare enum SchedulerPriority {
+    /**
+     * 🟥 Immediate — 立即执行（⚠️不建议使用）
+     *
+     * 特点：
+     *  - 调度器会优先推进此任务
+     *  - 可能不进行切分或切分极不充分
+     *  - 极易造成 UI 卡顿
+     *
+     * 使用场景（非常少见）：
+     *  - 需要强制同步执行的极短逻辑
+     *  - 避免被其它任务延迟的关键一瞬逻辑
+     *
+     * 强烈不推荐：
+     *  - 多维表格处理
+     *  - 大型循环
+     *  - 数据转换
+     *  - 网络序列任务
+     *
+     * 如果任务包含任何中等规模逻辑，应避免使用 Immediate，
+     * 因为它通常无法“分片执行”，容易阻塞主线程。
+     */
+    Immediate = 1,
+    /**
+     * 🟧 UserBlocking — 用户操作相关任务
+     *
+     * 特点：
+     *  - 优先级高于普通任务
+     *  - 仍支持 shouldYield() 协作式让权
+     *
+     * 推荐场景：
+     *  - 用户点击触发的数据准备逻辑
+     *  - UI 交互所需的轻中度处理逻辑
+     *  - 加载用户刚刚点开的内容结构
+     */
+    UserBlocking = 2,
+    /**
+     * 🟨 Normal — 默认优先级
+     *
+     * 特点：
+     *  - 绝大多数 Job 建议使用该优先级
+     *  - 足够快，又不会过份抢占调度时间片
+     *
+     * 推荐场景：
+     *  - 多维表格后台运算
+     *  - 点云/图像/数据预处理
+     *  - 分页数据计算
+     *  - 常规业务逻辑任务
+     */
+    Normal = 3,
+    /**
+     * 🟦 Low — 次级任务
+     *
+     * 特点：
+     *  - 相比 Normal 会更晚被调度
+     *  - 更适合“可延迟的任务”
+     *
+     * 推荐场景：
+     *  - 慢速批处理
+     *  - 难以感知延迟的逻辑
+     *  - 模型预热、数据缓存整理等
+     */
+    Low = 4,
+    /**
+     * 🟩 Idle — 空闲任务
+     *
+     * 特点：
+     *  - 在浏览器空闲时执行
+     *  - 对交互影响最低
+     *
+     * 推荐场景：
+     *  - Stats/日志分析
+     *  - 底层文件扫描
+     *  - 数据结构预构建
+     *  - 图片/缓存/元数据预热
+     *
+     * 注意：
+     *  - Idle Job 可能在页面高负载时迟迟不会启动
+     *  - 适合“能晚点做，但迟早得做一次”的任务
+     */
+    Idle = 5
+}
+/**
+ * 调度器返回的任务句柄。
+ *
+ * - 对于基于 React Scheduler 的实现，可以包装返回的任务 id；
+ * - 对于基于 requestIdleCallback 的实现，可以包装 callback id；
+ * - 如果底层调度器不支持取消，可以使用一个 no-op cancel。
+ */
+export interface SchedulerTask {
+    cancel(): void;
+}
+/**
+ * 调度器接口。
+ *
+ * Job 只依赖该接口，不依赖具体实现。
+ */
+export interface Scheduler {
+    /**
+     * 按指定优先级调度一个回调。
+     * 返回的 SchedulerTask 用于后续取消。
+     */
+    schedule(priority: SchedulerPriority, fn: () => void): SchedulerTask;
+    /**
+     * 取消一个未执行完的任务。
+     */
+    cancel(task: SchedulerTask): void;
+    /**
+     * 当前时间片是否应当让出控制权。
+     *
+     * - 在浏览器环境通常由 React Scheduler 或时间片实现决定；
+     * - 在简单实现中，也可以始终返回 false。
+     */
+    shouldYield(): boolean;
+}
+
+

package/dist/scheduler.esm-bundler.mjs

@@ -0,0 +1,19 @@
+/**
+* @enableai-job-runtime/scheduler v0.0.5
+* (c) 2024-present Enableai
+* @license Proprietary
+**/
+const SchedulerPriority = {
+  "Immediate": 1,
+  "1": "Immediate",
+  "UserBlocking": 2,
+  "2": "UserBlocking",
+  "Normal": 3,
+  "3": "Normal",
+  "Low": 4,
+  "4": "Low",
+  "Idle": 5,
+  "5": "Idle"
+};
+
+export { SchedulerPriority };

package/index.js

@@ -0,0 +1,7 @@
+'use strict'
+
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('./dist/scheduler.cjs.prod.js')
+} else {
+  module.exports = require('./dist/scheduler.cjs.js')
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@enableai-job-runtime/scheduler",
+  "version": "0.0.5",
+  "order": -1,
+  "description": "",
+  "main": "index.js",
+  "types": "dist/scheduler.d.ts",
+  "files": [
+    "dist",
+    "index.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/scheduler.d.ts",
+      "module": "./dist/scheduler.esm-bundler.mjs",
+      "import": "./dist/scheduler.esm-bundler.mjs",
+      "require": "./index.js"
+    },
+    "./*": "./*"
+  },
+  "buildOptions": {
+    "name": "scheduler",
+    "formats": [
+      "esm-bundler",
+      "cjs"
+    ]
+  },
+  "keywords": [],
+  "license": "Proprietary"
+}