good-timing

KO | EN

gitlite — search

#javascript #python #android #rust #deep-learning #nodejs #java #cli #vue #awesome-list #security #pytorch #ios #open-source

(★ 11)

Promise based timing composition

good-timing Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">
 Good Timing
</h1>

Powerful promise compositions for all things timing.

 

 <a href="https://www.npmjs.com/package/good-timing"><img alt="NPM" src="https://img.shields.io/npm/v/good-timing.svg"></a>

## Quick Start

> Install with preferred package manager
```bash
npm install --save good-timing
```

> Import what you need

```js
import { timeIn, sleep, atleast, defer, within } from "good-timing";
```

> Remember to ⭐️ if this helps your project!

## TimeDefintion

This package's central gimick.

While all helpers can accept a number of milliseconds, a better way to define duration is via the `TimeDefintion` interface. It is simply an object containing any combination of the following keys.

| ms | second(s) | minute(s) | hour(s) | day(s) | weeks(s) |
|:--:|:---------:|:---------:|:-------:|:------:|:--------:|
|    | sec(s)    | min(s)    | hr(s)   |        | wk(s)    |

- `{ hour: 1, min: 5, seconds: 30 }` => `3930000ms`

- `{ sec: 1 }` => `1000ms`
 
- `{ hr: 2, sec: 50 }` => `7250000ms`

- `{ second: 1, ms: 500 }` => `1500ms`

# API

Each of the exposed helper functions have overloads which tailor them to your specific use case.

Signatures are in typescript, everything in **`Bold`** is a type, of which package-specific ones are referenced above, as well as in the [Types Section](#Types).

## timeIn

<code>&nbsp;timeIn(time: TimeDefintion): number&nbsp;</code>

Converts `TimeDefintion` to `number` of seconds. Easy!

```js
const milliseconds = timeIn({ minutes: 15 });
// 900000
```

> Note: *This (or a sourced variable) can be used in place of any `Amount`, as it just returns a number of milliseconds.*

## sleep
More or less equivalent to `setTimeout`

<code>&nbsp;sleep(time: Amount): Promise\<number\>&nbsp;</code>

*Return a promise which waits specified time. Resolves to number of milliseconds elapsed.*

```js
const howLongWasThat = await sleep({ seconds: 12 });
// Twelve suspense filled seconds later...

howLongWasThat;
// 12000
```

<code>&nbsp;sleep(time: Amount, callback: Function): void&nbsp;</code>

*Run a callback after specified time.*

```js
sleep({ minute: 1 }, () => { 
    console.log("Hello to the future!") 
});

// One minute later...
// A hello from the not too distant past! Truly amazing.
```

## atleast

Useful where you want to ensure whatever you're waiting for takes a minimum amount of time.

> Useful in situations where an operation may sometimes finish "too fast". If showing an animation while loading, for instance, it may be less-than-ideal for that animation to terminate before completing its first cycle. `atleast()` would give you the ability to set for how long that loading state should remain on screen, making time-of-flight feel more consistent.

<code>&nbsp;atleast(time: Amount, promise: Promise\<T\>): Promise\<T\>&nbsp;</code>

*Resolve a promise only after specified time.*
*Will resolve as original promise does or after `time` elapses, whichever is later.*

```js
const { log } = console;
const justASec = sleep({ sec: 1 })
const justAMinute = sleep({ min: 1 })

log(await atleast({ seconds: 30 }, justASec))
// 30 seconds later... (deferral was longer)
// > 1000

log(await atleast({ seconds: 30 }, justAMinute))
// 1 minute later... (original was longer)
// > 60000
```

<code>&nbsp;atleast(time: Amount, executor: (resolve, reject) => void): Promise\<Value\>&nbsp;</code>

*Run function and return Promise resolving the async result. Will only resolve after `time` has elapsed.* *More or less equivalent to `new Promise()` but deferred.*

```js
await foo = atleast({ minute: 1 }, (resolve, reject) => { 
    setTimeout(() => resolve("bar"), 500)
});

// One minute later...
// foo === "bar"
```

## defer

Delays the resolution of a promise by set time.

<code>&nbsp;defer(time: Amount): (value: T) => Promise\<T\>&nbsp;</code>

*This function **will add** the amount of time specified, on top of existing time taken.*

> *This is intended for use in `.then()` chains, as a passthrough. It can be added anywhere within to introduce some slowdown.*

```js
async function HelloLater(to: string){
    await sleep({ sec: 5 });
    return `Hello, ${to}!`
}

HelloLater("World")
    .then(defer({ sec: 5 }))
    .then(salutation => {
        console.log(salutation)
    });

// 10 seconds later...
// > Hello!
```

## within

Returns a `Promise` which only resolves if timeout is not reached, will reject instead if timeout is reached.

> Useful to enforce a timeout on `Promisable` asyncronous operation.

<code>&nbsp;within(timeout: Amount, awaiting: Promisable\<T\>): Promise\<T\>&nbsp;</code>

*This function takes `awaiting` and resovlves as normal, so long `timeout` is not reached.*

> If timeout elapses, output Promise will reject with the message `"Timeout: {number}ms"`;

```js
async function HelloLater(to: string){
    await sleep({ sec: 30 });
    return `Hello, ${to}!`
}

await within({ sec: 29 }, HelloLater())
    .catch(e => console.error(e))

// 29 seconds later...
// > "Timeout: 29000ms"

await within({ sec: 31 }, HelloLater())
    .then(e => console.log(e))

// 30 seconds later...
// > 30000
```

<code>&nbsp;within(defer: Amount, timeout: Amount, awaiting: Promisable\<T\>): Promise\<T\>&nbsp;</code>

*Resolves `awaiting` only after `defer` has elapsed, but only if `timeout` has not.*

> Behaves exactly as `atleast(defer, within(timeout, awaiting))`

```js
async function justAMinute(){
    await sleep({ sec: 60 });
    return "foobar"
}

await within({ sec: 35 }, { sec: 60 }, justAMinute())
    .catch(e => console.error(e))

// 60 seconds later...
// > "Timeout: 60000ms"

await within({ sec: 31 }, { sec: 62 }, justAMinute())
    .catch(e => console.log(e))

// 61 seconds later...
// > 61000
```

# Other Types

More data types encontered in API.

###  PromiseExecutor

A function containing asyncronous operation. 
> Equivalent to that consumed by `new Promise()`

<code>&nbsp;(resolve: (value) => void), reject: (reason) => void): void&nbsp;</code>

###  Amount
Refers to anywhere `TimeDefinition` or `number` of milliseconds where interchangeable.

###  Promisable

Refers to anywhere `Promise` or `PromiseExecutor` are interchangeable.

# License

MIT license.

good-timing

good-timing Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

good-timing

good-timing Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README