yann-idle

一个在浏览器空闲时间高效调度任务的工具库，兼容多种环境，支持超时控制，适用于需要在主线程空闲时执行任务的场景。

特性

• 自动优先使用 requestIdleCallback，兼容不支持的环境（如 Node.js、部分老旧浏览器）
• 支持任务超时（timeout）配置
• 支持同步与异步任务
• 提供同步风格和 Promise 风格的 API
• 任务可取消

安装

npm install yann-idle
# 或
yarn add yann-idle
# 或
pnpm add yann-idle

API

1. scheduleIdleTask

在浏览器空闲时间调度任务，自动选择最佳实现。

import { scheduleIdleTask } from 'yann-idle';

const cancel = scheduleIdleTask(
  deadline => {
    // deadline.timeRemaining() 可获取剩余空闲时间（ms）
    // deadline.didTimeout 是否超时
    while (deadline.timeRemaining() > 0 && tasks.length > 0) {
      doSomeWork(tasks.pop());
    }
  },
  { timeout: 1000 }
);

// 如需取消任务
cancel();

参数

• task: (deadline) => void | Promise<void> 要执行的任务函数，支持同步或异步。
• options?: number | { timeout?: number } 可选，超时时间（ms），超时后强制执行。

返回值

• () => void 取消函数，调用后任务不会被执行。

2. runTaskSync

同步风格的任务调度，自动判断空闲时间，不足时自动延迟。

import { runTaskSync } from 'yann-idle';

const cancel = runTaskSync(
  () => {
    // 你的任务逻辑
    doSomething();
  },
  { timeout: 500 }
);

参数

• fn: () => void | Promise<void> 要执行的任务函数。
• options?: number | { timeout?: number } 可选，超时时间（ms）。

返回值

• () => void 取消函数。

3. runTask

异步风格的任务调度，返回 Promise，适合 await 使用。

import { runTask } from 'yann-idle';

await runTask(async () => {
  await doAsyncWork();
}, 800);

参数

• fn: () => void | Promise<void> 要执行的任务函数。
• options?: number | { timeout?: number } 可选，超时时间（ms）。

返回值

• Promise<void> 任务完成时 resolve，异常时 reject。

类型定义

type IdleCallbackOptions = {
  timeout?: number;
};

type IdleCallbackDeadline = {
  timeRemaining: () => number;
  didTimeout: boolean;
};

兼容性

• 优先使用 requestIdleCallback，不支持时自动降级为 MessageChannel 或 setTimeout
• 支持所有现代浏览器

典型场景

• 大量数据分批处理，避免阻塞主线程
• 动画、渲染、输入等高优先级任务空闲时执行低优先级任务
• 需要超时保障的异步任务

License

MIT