@dyxbenjamin/time-units ⏳

Type-safe time conversion utility.
Stop using magic numbers like 86400000 or 3600 in your code. Write readable, maintainable time logic.

📦 Installation

# npm
npm install @dyxbenjamin/time-units

# bun
bun add @dyxbenjamin/time-units

# pnpm
pnpm add @dyxbenjamin/time-units

# yarn
yarn add @dyxbenjamin/time-units

🚀 Usage

1. Fluent Conversion API

Convert easily between different units of time using a readable chainable syntax.

import { days, hours, minutes } from '@dyxbenjamin/time-units';

// Convert units
days(1).toHours();       // 24
hours(2).toMinutes();    // 120
minutes(30).toSeconds(); // 1800
weeks(1).toDays();       // 7

// Get raw milliseconds
days(1).toMilliseconds(); // 86400000

2. Millisecond Helpers (Perfect for Configs & Timeouts)

Use capitalized helper functions when you just need the value in milliseconds. This is ideal for setTimeout, setInterval, or configuration files.

import { Seconds, Minutes, Days } from '@dyxbenjamin/time-units';

// Instead of writing 5000
setTimeout(() => {
  console.log('Hello!');
}, Seconds(5));

// Instead of 86400000
const cacheTTL = Days(1); 

// Supports expressions
const timeout = Minutes(5) + Seconds(30);

3. Date Manipulation

Easily add or subtract time from a JavaScript Date object without manually calculating timestamps.

import { days, minutes } from '@dyxbenjamin/time-units';

const now = new Date();

// Add 7 days to current date
const nextWeek = days(7).addTo(now);

// Subtract 30 minutes from current date
const past = minutes(30).subtractFrom(now);

4. Reverse Conversion (from...)

Calculate how many units fit into a value.

import { days, hours } from '@dyxbenjamin/time-units';

// How many days are in 48 hours?
days.fromHours(48); // 2

// How many hours are in 1 week?
hours.fromWeeks(1); // 168

📚 Supported Units

The library exports the following converters, each supporting the full API (to..., from..., addTo, subtractFrom):

• ms (Milliseconds)
• seconds / Seconds
• minutes / Minutes
• hours / Hours
• days / Days
• weeks / Weeks

🛠️ Development

This project uses Bun and Rslib.

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

📄 License

MIT