https://github.com/yusangeng/polygala
Toolset about time & timing.
https://github.com/yusangeng/polygala
asynchronous macrotask microtask polling timing
Last synced: 5 months ago
JSON representation
Toolset about time & timing.
- Host: GitHub
- URL: https://github.com/yusangeng/polygala
- Owner: yusangeng
- License: mit
- Created: 2018-01-04T16:52:25.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2020-11-11T11:24:53.000Z (almost 5 years ago)
- Last Synced: 2025-03-31T10:51:16.016Z (6 months ago)
- Topics: asynchronous, macrotask, microtask, polling, timing
- Language: TypeScript
- Homepage:
- Size: 50.8 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# polygala
[](https://www.tslang.cn/) [](https://travis-ci.org/yusangeng/polygala) [](https://coveralls.io/github/yusangeng/polygala?branch=master) [](https://www.npmjs.com/package/polygala) [](https://www.npmjs.com/package/polygala)
## Abstract
TS library about timing.
## Install
```bash
npm install polygala --save
```
## Usage
### sleep
Asynchronous sleep.
```ts
import { sleep } from 'polygala';
async function main(): Promise {
await sleep(1000);
}
```
### task
Simulative micro/macro task in browser.
```ts
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.
```ts
import { fifo, sleep } from 'polygala';
async function fa(): Promise {
// 2s delay
await sleep(2000);
}
async function fb(): Promise {
// 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.
```ts
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.
```ts
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.
```ts
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.
```ts
function sleep(milliseconds: number): Promise;
```
### micro & macro
Invoke simulative micro/macro tasks in browser.
```ts
type FProcedure = (...args: any[]) => void;
function micro(fn: Fn): Fn;
function macro(fn: Fn): Fn;
```
### fifo
Push an async function and its return value into a FIFO promise queue.
```ts
type AsyncFunc = (...args: any[]) => Promise;
export function fifo>(fn: Fn, queueName?: symbol): Fn;
export function fifo>(fn: Fn, queueName?: symbol): Fn;
```
### poll
Start polling.
```ts
// Polling function type.
type PollingFunc = (p: Polling) => void;
// Error callbacl type.
type ErrorCallback = (error: Error) => boolean;
// Options type.
type PollingOptions = {
context?: ContextType;
delay?: number;
limit?: number;
onError?: ErrorCallback;
};
// Function to stop polling.
type StopFunc = () => void;
function poll(fn: PollingFunc, options?: PollingOptions): StopFunc;
```
### quittable
Create a quittable task.
```ts
interface IQuittable {
quitted: boolean;
readonly context: ContextType;
quit(): void;
}
type FQUITTED = () => void;
class Quittable implements IQuittable {
// ...
run(): Promise;
quit(): void;
}
type QuittableCallable = (q: IQuittable) => RetType;
function quittable(
context: ContextType,
fn: QuittableCallable
): Quittable;
```
### namedQuittable
Create a named quittable task.
If you've created a named quittable task, the last task with the same name was quitted automatically.
```ts
function namedQuittable(
name: symbol,
context: ContextType,
fn: QuittableCallable
): Quittable;
```
### getRunningNamedQuittable
Find the running named quittable task.
```typescript
function getRunningNamedQuittable(name: symbol);
```
### countdown
```ts
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);
```