@ratio-hub/time

Type-safe time library for TypeScript. Branded types prevent mixing up seconds and milliseconds.

Install

bun add @ratio-hub/time

Quick Start

import { Time, Duration, dur } from "@ratio-hub/time";

// Create time from JWT expiration (unix seconds)
const exp = Time.seconds(jwt.exp);

// Check if token expired
if (exp.hasExpired()) {
  console.log("Token expired");
}

// Check if token expires within 5 minutes (proactive refresh)
if (exp.expiresWithin("5m")) {
  console.log("Token expiring soon, refresh it");
}

// Parse duration strings
const oneHour = dur("1h"); // Duration
const mixed = dur("1h30m"); // Duration (1.5 hours)
console.log(mixed.toMillis()); // 5400000
console.log(mixed.toMinutes()); // 90

Time

Creating Time Instances

// All factories are explicit about units
const now = Time.now(); // current time
const fromSec = Time.seconds(1704067200); // from unix seconds
const fromMs = Time.millis(1704067200000); // from unix milliseconds
const fromDate = Time.date(new Date()); // from Date object
const fromISO = Time.iso("2024-01-01T00:00:00Z"); // from ISO string

// Shortcuts for relative times
const inOneHour = Time.in("1h"); // Time: 1 hour from now
const thirtyMinsAgo = Time.ago("30m"); // Time: 30 minutes ago

Arithmetic

All operations return new Time instances (immutable).

const now = Time.now();

const later = now.add("1h"); // Time: 1 hour later
const earlier = now.subtract("30m"); // Time: 30 minutes earlier

// Get difference between two times
const t1 = Time.seconds(2000);
const t2 = Time.seconds(1000);
const diff = t1.diff(t2); // Duration: 1000 seconds
console.log(diff.toSeconds()); // 1000

Comparisons

const t1 = Time.seconds(1000);
const t2 = Time.seconds(2000);

t1.isBefore(t2); // true
t1.isAfter(t2); // false
t1.equals(t2); // false

// Relative to current time
const past = Time.ago("1h");
past.isPast(); // true
past.isFuture(); // false

Window Checks

const lastRequest = Time.ago("30s");

// Is this time within 1 minute of now?
lastRequest.isWithin("1m"); // true (30s < 1m)

// Is this time within 10 seconds of now?
lastRequest.isWithin("10s"); // false (30s > 10s)

// Check against a specific anchor time
const anchor = Time.seconds(1000);
const target = Time.seconds(1050);
target.isWithin("100s", anchor); // true (50s < 100s)

Expiration Helpers

const tokenExp = Time.in("10m"); // expires in 10 minutes

tokenExp.hasExpired(); // false (still in future)
tokenExp.expiresWithin("15m"); // true (expires within 15 min window)
tokenExp.expiresWithin("5m"); // false (won't expire in next 5 min)

const oldToken = Time.ago("5m"); // expired 5 minutes ago

oldToken.hasExpired(); // true
oldToken.expiredWithin("10m"); // true (expired within last 10 min)
oldToken.expiredWithin("2m"); // false (expired more than 2 min ago)

Output

const time = Time.seconds(1704067200);

time.toSeconds(); // 1704067200 (Seconds type)
time.toMillis(); // 1704067200000 (Milliseconds type)
time.toDate(); // Date object
time.toISO(); // '2024-01-01T00:00:00.000Z'

// Human-readable relative time
Time.in("5m").toRelative(); // 'in 5m'
Time.ago("2h").toRelative(); // '2h ago'
Time.ago("2h").toRelative({ long: true }); // '2 hours ago'

Duration

Creating Durations

// From strings using dur()
const d1 = dur("1h"); // 1 hour
const d2 = dur("30m"); // 30 minutes
const d3 = dur("1h30m"); // 1 hour 30 minutes (compound)
const d4 = dur("1w2d"); // 1 week 2 days
const d5 = dur("1 hour"); // with space
const d6 = dur("-5m"); // negative duration

// From numbers using static methods
const d7 = Duration.milliseconds(1000);
const d8 = Duration.seconds(60);
const d9 = Duration.minutes(30);
const d10 = Duration.hours(2);
const d11 = Duration.days(7);
const d12 = Duration.weeks(1);
const d13 = Duration.months(6); // approximate (year/12)
const d14 = Duration.years(1); // approximate (365.25 days)

Arithmetic

All operations return new Duration instances (immutable).

const oneHour = dur("1h");

oneHour.add("30m"); // Duration: 1h30m (5400000ms)
oneHour.subtract("15m"); // Duration: 45m (2700000ms)
oneHour.multiply(2); // Duration: 2h (7200000ms)
oneHour.divide(2); // Duration: 30m (1800000ms)

dur("-1h").abs(); // Duration: 1h (positive)
dur("1h").negate(); // Duration: -1h (negative)

Comparisons

dur("1h").equals("60m"); // true
dur("2h").greaterThan("1h"); // true
dur("30m").lessThan("1h"); // true

dur("0s").isZero(); // true
dur("-1h").isNegative(); // true
dur("1h").isPositive(); // true

Output

const d = dur("90m");

d.toMillis(); // 5400000
d.toSeconds(); // 5400
d.toMinutes(); // 90
d.toHours(); // 1.5
d.toDays(); // 0.0625

// Human-readable (rounds to largest sensible unit)
dur("90m").humanize(); // '2h'
dur("90m").humanize({ long: true }); // '2 hours'
dur("45s").humanize(); // '45s'
dur("3d").humanize({ long: true }); // '3 days'

Duration Strings

Supported formats:

| Unit | Formats | | ------------ | ---------------------------------------------------- | | Years | y, yr, yrs, year, years | | Months | mo, month, months | | Weeks | w, week, weeks | | Days | d, day, days | | Hours | h, hr, hrs, hour, hours | | Minutes | m, min, mins, minute, minutes | | Seconds | s, sec, secs, second, seconds | | Milliseconds | ms, msec, msecs, millisecond, milliseconds |

Compound: 1h30m, 1w2d, 2h30m15s

Case insensitive: 1H, 1Hour, 1HOUR all work.

Type Safety

The library exports branded Seconds and Milliseconds types. TypeScript will catch if you accidentally mix them:

import type { Seconds, Milliseconds } from "@ratio-hub/time";

const sec: Seconds = time.toSeconds(); // OK
const ms: Milliseconds = time.toMillis(); // OK

// TypeScript error: Type 'Seconds' is not assignable to type 'Milliseconds'
const wrong: Milliseconds = time.toSeconds();

This prevents bugs like passing seconds to an API that expects milliseconds.

License

MIT