@polyv/utils-polling

执行轮询（定时）任务。与纯粹的 setTimeout 或 setInterval 实现的定时任务相比，本模块还支持在异步操作（比如对后端接口的请求）完成之后，再进行下一轮计时。

安装

pnpm add @polyv/utils-polling

调用

基本调用

import { Polling } from '@polyv/utils-polling';

const polling = new Polling(
  () => {
    return new Promise(resolve => {
      setTimeout(() => {
        console.log('executed');
        resolve();
      }, 500);
    });
  },
  {
    // 1 秒执行一次
    interval: 1000,
  },
);
// 开始轮询
polling.start();
// 停止轮询
polling.stop();

调用 start 后会马上执行一次操作函数，如果不希望马上执行，可以传入参数 false：

polling.start(false);

动态轮询间隔

const polling = new Polling(
  () => {
    // ...
  },
  {
    // 越来越短的轮询间隔
    interval: function (lastInterval) {
      return lastInterval == null ? 10000 : Math.max(1000, lastInterval - 200);
    },
  },
);
polling.start();

通过钩子函数停止轮询

可以通过传入 shouldContinue 钩子函数控制是否继续轮询（返回值为 false 时停止轮询），可结合终止控制函数去使用：

import { Polling, breakBy } from '@polyv/utils-polling';

const polling = new Polling(
  () => {
    // ...
  },
  {
    interval: 1000,
    // 轮询 3 次停止
    shouldContinue: breakBy.maxTimes(3),
  },
);
polling.start();

出错后停止轮询

可以通过传入 breakOnError: true 在执行出错的时候停止轮询：

const polling = new Polling(
  () => {
    return new Promise((resolve, reject) => {
      // 模拟出错的情况
      setTimeout(() => {
        if (Math.random < 0.5) {
          resolve();
        } else {
          reject();
        }
      }, 1000);
    });
  },
  {
    interval: 2000,
    breakOnError: true,
  },
);
polling.start();

更新轮询选项

可以调用实例方法 updateOptions 更新轮询选项：

const polling = new Polling(
  () => {
    // ...
  },
  {
    interval: 2000,
    breakOnError: true,
  },
);
polling.start();

// 3 秒后轮询间隔改为 1 秒
setTimeout(() => {
  polling.updateOptions({
    interval: 1000,
  });
}, 3000);

轮询过程中立刻执行一次操作函数

const polling = new Polling(
  () => {
    // ...
  },
  {
    interval: 2000,
    breakOnError: true,
  },
);
polling.start();

setTimeout(() => {
  // 注意，如果操作函数是异步的而且当前还未执行完，
  // 那么 execImmediately 会等待它执行完之后才再次执行操作函数
  polling.execImmediately();
}, 3000);

监听事件

import { Polling, breakBy } from '@polyv/utils-polling';
const polling = new Polling(
  () => {
    // ...
  },
  {
    interval: 1000,
    shouldContinue: breakBy.maxTimes(3),
  },
);
polling.on('start', () => {
  console.log('start');
});
polling.on('stop', () => {
  console.log('stop');
});
polling.start();