⏲️ delta-time

A simple module to compute intervals

• Simple function to parse user friendly intervals
• Clear-up your code from messy time computations
• Comes with a utility to delay a promise
• Dependency free and typed

📦 Installation

npm install delta-time

📚 Usage

import {calculate as dt, delay} from "delta-time";

// human friendly string conversion
dt("2 days"); // 172800000
dt("1d"); // 86400000
dt("1 micro"); // 0.001
dt("1h1m1s", "sec"); // 3661

// typed objects
dt({hours: 1, minutes: 30}); // 5400000

// pass-through ms numbers
dt(123); // 123
dt(456, "sec"); // 0.456

// delay utility
await delay("1min"); // block and resolve to undefined
const out = await delay({seconds: 1}, {value: "⏲️ timey wimey"}); // block and resolve to value
await delay({seconds: 30}, {reject: true, value: new Error("💣 timed error")}); // block and throw value

Perfect for timeouts and intervals

setTimeout(function () {
    console.log("foo");
}, dt("500ms"));

setTimeout(function () {
    console.log("bar");
}, dt("5 secs"));

setTimeout(function () {
    console.log("baz");
}, dt("1h30m5s"));

Allows complex specifications

dt("- 1 day"); // -86400000
dt("2 hours - 30 seconds"); // 7170000

Not just for milliseconds

dt("1000 ms", "s"); // 1
dt("2 week", "days"); // 14
dt("300 Years, 5 Months and 2 Hours", "days"); // 109727.28333333334

📖 API

calculate(time: TimeValue, unit?: TimeUnit): number

• Takes a number, a string or an object describing a time interval
  • A combination of units can be given
  • For better typing, prefer the object
• Returns the value of the interval in the specified unit (default is milliseconds)

delay<T = undefined>(time: TimeValue, config?: DelayConfig): Promise<T | undefined>

• Takes a number, a string or an object describing a time interval to block
• Takes an optional configuration object with:
  • An optional value T field to resolve or error to reject
  • An optional reject boolean field, set it to true to reject (default is false)
• Returns a Promise that resolves or rejects the optional value given after the time given

🌐 Language

| Unit | Duration | String units | Object key | | ----------- | ----------------------- | ---------------------------- | ------------ | | nanosecond | 10−9 seconds | ns, nano(s), nanosecond(s) | nanoseconds | | microsecond | 10−6 seconds | μs, micro(s), microsecond(s) | microseconds | | millisecond | 0.001 seconds | ms, milli(s), millisecond(s) | milliseconds | | second | 1 seconds | s, sec(s), second(s) | seconds | | minute | 60 seconds | m, min(s), minute(s) | minutes | | hour | 60 minutes | h, hr(s), hour(s) | hours | | day | 24 hours | d, day(s) | days | | week | 7 days | w, wk(s), week(s) | weeks | | month | 30.44 days | mo(s), month(s) | months | | year | 365.25 days | y, yr(s), year(s) | years |

🧪 Environment import

The package is bundled in cjs and esm for bundlers.

Bundler

import dt from "delta-time";

import {calculate as dt, delay} from "delta-time";

NodeJs

const {calculate: dt, delay} = require("delta-time");

NodeJs (module)

import dt from "delta-time";
const {calculate, delay} = dt;