mana-common

Common utils for mana.

Usage no npm install needed!

<script type="module">
  import manaCommon from 'https://cdn.skypack.dev/mana-common';
</script>

README

mana-common

Common utils for mana.

NPM version NPM downloads

安装

npm i mana-common --save

用法

可销毁对象 Disposable

可销毁对象的定义,这里的销毁除有时候也代表撤销

interface Disposable {
  /**
   * Dispose this object.
   */
  dispose: () => void;
}

提供了一些工具方法

namespace Disposable {
  function is(arg: any): arg is Disposable; // 类型断言,判断是否为 Disposable 对象
  function create(func: () => void): Disposable; // 将方法创建为 Disposable 对象
  const NONE: Disposable; // 空的 Disposable 对象
}

可销毁集合 DisposableCollection

可毁对象的集合

constructor(...toDispose: Disposable[]) // 基于可销毁对象的列表创建
push(disposable: Disposable): Disposable // 加入一个可销毁对象
pushAll(disposable: Disposable[]): Disposable[] // 加入多个可销毁对象
get onDispose(): Event<void> // 监听集合的销毁事件
  • 可销毁对象集合本身就是可销毁的,其销毁动作可以销毁几个内的所有对象。
  • 可销毁对象的添加动作会返回一个可销毁对象,其销毁动作会撤销这些对象对集合的添加。
  • 可销毁对象销毁事件的监听,也会返回一个可销毁对象,其销毁动作会撤销监听动作。

事件定义,通过 Emitter 定义和发起事件,通过 Event 订阅事件,一个常见的使用方式如下

事件订阅 Emitter Event

class EventEmitter {
  protected emitter = new Emitter<void>();
  get onEventEmit(): Event<void> {
    return emitter.event;
  }
  emit() {
    emitter.fire();
  }
}
const emitter = new EventEmitter();
const disposable = emitter.onEventEmit(() => {});

可以方便的设置 Event 的 listener 限制

emitter.onEventEmit.maxListeners = 10; // 默认为 0,即没有限制

可以遍历事件的订阅者, 返回 false 以中止遍历

emitter.sequence(listener => {
  return true;
});

延迟取值 Deferred

作为 promise 的生成工具使用, 其定义非常简单,完整定义如下

export class Deferred<T> {
  public resolve: (value: T | PromiseLike<T>) => void;
  public reject: (err?: any) => void;
  public readonly promise: Promise<T>;

  constructor() {
    this.promise = new Promise<T>((resolve, reject) => {
      this.resolve = resolve;
      this.reject = reject;
    });
  }
}

中止器 Cancellation

作为可中止操作的句柄使用,实际上中止器的作用并不是在函数的执行过程中中止执行,而是提供一个标志来判断是否被中止过,函数本身是会被调用完的.

  • 执行结束后返回
const source = new CancellationTokenSource();
const wait = async (cb: () => Promise<void>, token: CancellationToken): Promise<boolean> => {
  await cb();
  if (token.isCancellationRequested) {
    return false;
  }
  return true;
};
wait(() => {
  // do something
}, source.token);
source.cancel();
  • 中止事立即返回
const source = new CancellationTokenSource();
// 中止时返回
const wait = async (cb: () => Promise<void>, token: CancellationToken): Promise<boolean> => {
  const waitDeferred = new Deferred<boolean>();
  token.onCancellationRequested(() => {
    waitDeferred.resolve(false);
  });
  cb().then(() => {
    waitDeferred.resolve(true);
  });
  return waitDeferred.promise;
};
wait(() => {
  // do something
}, source.token);
source.cancel();

重试 retry

对于同一操作在出错的情况下多次重试, 可设置重试间隔和重试次数上限

async function retry<T>(task: () => Promise<T>, delay: number, retries: number): Promise<T>;

超时 timeout

在程序中设置一个可取消的延迟

function timeout(ms: number, token = CancellationToken.None): Promise<void>;