polygala

Abstract

TS library about timing.

Install

npm install polygala --save

Usage

sleep

Asynchronous sleep.

import { sleep } from 'polygala';

async function main(): Promise<void> {
  await sleep(1000);
}

task

Simulative micro/macro task in browser.

import { micro, macro } from 'polygala';

const task1 = macro(() => console.log('task1'));
const task2 = micro(() => console.log('task2'));

task1();
task2();

//=> Prints 'task2', 'task1'

fifo

FIFO promise queue.

import { fifo, sleep } from 'polygala';

async function fa(): Promise<void> {
  // 2s delay
  await sleep(2000);
}

async function fb(): Promise<void> {
  // 1s delay
  await sleep(1000);
}

const globalFIFOName = Symbol('foobar');

const a = fifo(fa, globalFIFOName);
const b = fifo(fb, globalFIFOName);

let str = '';

a().then(() => {
  str += 'Hello';
});
b().then(() => {
  str += 'World';
});

//=> str === 'Hello World'

poll

An easy-to-use polling implemention.

import { poll } from 'polygala';

const stop = poll(
  async (polling) => {
    const { url } = polling.context;
    await fetch(url);
  },
  {
    delay: 3000,
    limit: 1000, // Repeats at most 1000 times, 0 means NO limit.
    context: {
      url: '//foobar.com/heartbeat',
    },
    onError: (err) => {
      console.error(err);
      return false; // False means "Don't stop polling", if you want to stop, return true.
    },
  }
);

// ...

stop(); // stop polling.

poll/until

Poll until compare function returns true.

import { poll } from 'polygala';

let i = 0;

try {
  const data = await poll(async () => i++).until((curr: any) => curr > 100, 1000);
} catch (err) {
  console.log(err.message);
}

quittable

Quittable asynchronous task.

import { quittable, sleep } from 'polygala';
import ajax from './ajax';
import store from './store';

const task = quittable(
  async (task) => {
    await sleep(1000);

    if (task.quitted) {
      // Task has been quitted.
      return;
    }

    const { url } = task.context;
    const data = await ajax.get(url);

    if (task.quitted) {
      return;
    }

    store.data = data;
  },
  // Name of quittable task, null means on name.
  // A named task would be quitted if a new task with the same name was run.
  'foobar',
  // context
  {
    url: '//foobar.com/heartbeat',
  }
);

task.run();

setTimeout((_) => {
  task.quit();
}, 1050);

API

sleep

Sleep Asynchronously.

function sleep(milliseconds: number): Promise<void>;

micro & macro

Invoke simulative micro/macro tasks in browser.

type FProcedure = (...args: any[]) => void;

function micro<Fn extends FProcedure>(fn: Fn): Fn;
function macro<Fn extends FProcedure>(fn: Fn): Fn;

fifo

Push an async function and its return value into a FIFO promise queue.

type AsyncFunc<RetType> = (...args: any[]) => Promise<RetType>;

export function fifo<Fn extends AsyncFunc<void>>(fn: Fn, queueName?: symbol): Fn;
export function fifo<RetType, Fn extends AsyncFunc<RetType>>(fn: Fn, queueName?: symbol): Fn;

poll

Start polling.

// Polling function type.
type PollingFunc<ContextType> = (p: Polling<ContextType>) => void;

// Error callbacl type.
type ErrorCallback = (error: Error) => boolean;

// Options type.
type PollingOptions<ContextType> = {
  context?: ContextType;
  delay?: number;
  limit?: number;
  onError?: ErrorCallback;
};

// Function to stop polling.
type StopFunc = () => void;

function poll<ContextType>(fn: PollingFunc<ContextType>, options?: PollingOptions<ContextType>): StopFunc;

quittable

Create a quittable task.

interface IQuittable<ContextType> {
  quitted: boolean;
  readonly context: ContextType;
  quit(): void;
}

type FQUITTED = () => void;

class Quittable<ContextType, RetType> implements IQuittable<ContextType> {
  // ...

  run(): Promise<FQUITTED | RetType>;
  quit(): void;
}

type QuittableCallable<ContextType, RetType> = (q: IQuittable<ContextType>) => RetType;

function quittable<ContextType, RetType = void>(
  context: ContextType,
  fn: QuittableCallable<ContextType, RetType>
): Quittable<ContextType, RetType>;

namedQuittable

Create a named quittable task.

If you've created a named quittable task, the last task with the same name was quitted automatically.

function namedQuittable<ContextType, RetType = void>(
  name: symbol,
  context: ContextType,
  fn: QuittableCallable<ContextType, RetType>
): Quittable<ContextType, RetType>;

getRunningNamedQuittable

Find the running named quittable task.

function getRunningNamedQuittable(name: symbol);

countdown

export type CountDownOptions = {
  // Countdown interval, the default value is 1000ms.
  interval?: number;
  total: number;
  onTimeout?: (total: number, countdown: CountDown) => void;
  onTick?: (residue: number, total: number, countdown: CountDown) => void;
};

export function countdown(options: CountDownOptions);