Skip to content

repraze-org/delta-time

Repository files navigation

⏲️ delta-time

npm GitHub Workflow CI Status Codecov GitHub npm

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;