Enhanced MS provides convenient constants for working with time values in milliseconds. These constants help you write more readable code and avoid magic numbers.
Available constants
Enhanced MS exports two sets of constants: Time (PascalCase) and units (lowercase). They contain the same values but use different naming conventions.
Time constant
The Time constant uses PascalCase naming:
import { Time } from 'enhanced-ms';
Time.Nanosecond; // 0.000001
Time.Microsecond; // 0.001
Time.Millisecond; // 1
Time.Second; // 1000
Time.Minute; // 60000
Time.Hour; // 3600000
Time.Day; // 86400000
Time.Week; // 604800000
Time.Month; // 2628000000
Time.Year; // 31536000000
Time.Decade; // 315360000000
Time.Century; // 3153600000000
Time.Millennium; // 31536000000000
units constant
The units constant uses lowercase naming:
import { units } from 'enhanced-ms';
units.nanosecond; // 0.000001
units.microsecond; // 0.001
units.millisecond; // 1
units.second; // 1000
units.minute; // 60000
units.hour; // 3600000
units.day; // 86400000
units.week; // 604800000
units.month; // 2628000000
units.year; // 31536000000
units.decade; // 315360000000
units.century; // 3153600000000
units.millennium; // 31536000000000
Time unit definitions
Here’s what each unit represents:
One billionth of a second (10⁻⁹ seconds)
One millionth of a second (10⁻⁶ seconds)
One thousandth of a second (10⁻³ seconds). This is the base unit.
60 seconds = 60,000 milliseconds
60 minutes = 3,600,000 milliseconds
24 hours = 86,400,000 milliseconds
Week
number
default:"604800000"
7 days = 604,800,000 milliseconds
Month
number
default:"2628000000"
28 days = 2,628,000,000 milliseconds (average month approximation)
Year
number
default:"31536000000"
365 days = 31,536,000,000 milliseconds (not accounting for leap years)
Decade
number
default:"315360000000"
10 years = 315,360,000,000 milliseconds
Century
number
default:"3153600000000"
100 years = 3,153,600,000,000 milliseconds
Millennium
number
default:"31536000000000"
1,000 years = 31,536,000,000,000 milliseconds
Month is approximated as 28 days and Year as 365 days. These don’t account for varying month lengths or leap years.
Usage examples
Setting timeouts and intervals
import { Time } from 'enhanced-ms';
// Much more readable than magic numbers
setTimeout(() => {
console.log('5 seconds have passed');
}, Time.Second * 5);
// Set an interval for every minute
setInterval(() => {
console.log('One minute passed');
}, Time.Minute);
// Schedule something for 2 hours from now
const twoHoursLater = Date.now() + Time.Hour * 2;
Working with dates
import { Time } from 'enhanced-ms';
// Add days to a date
const today = new Date();
const nextWeek = new Date(today.getTime() + Time.Week);
// Calculate time differences
const startTime = Date.now();
// ... some operation ...
const endTime = Date.now();
const duration = endTime - startTime;
if (duration > Time.Second) {
console.log('Operation took more than a second');
}
Cache expiration
import { Time } from 'enhanced-ms';
const cache = new Map();
function setCacheWithExpiry(key, value, ttl = Time.Hour) {
const expiresAt = Date.now() + ttl;
cache.set(key, { value, expiresAt });
}
function getCacheValue(key) {
const item = cache.get(key);
if (!item) return null;
if (Date.now() > item.expiresAt) {
cache.delete(key);
return null;
}
return item.value;
}
// Cache for 30 minutes
setCacheWithExpiry('user:123', userData, Time.Minute * 30);
// Cache for 1 day
setCacheWithExpiry('config', config, Time.Day);
API rate limiting
import { Time } from 'enhanced-ms';
class RateLimiter {
private requests: number[] = [];
private limit: number;
private window: number;
constructor(limit: number, windowMs: number) {
this.limit = limit;
this.window = windowMs;
}
canMakeRequest(): boolean {
const now = Date.now();
const windowStart = now - this.window;
// Remove old requests
this.requests = this.requests.filter(time => time > windowStart);
if (this.requests.length < this.limit) {
this.requests.push(now);
return true;
}
return false;
}
}
// Allow 100 requests per hour
const limiter = new RateLimiter(100, Time.Hour);
if (limiter.canMakeRequest()) {
// Make API call
}
Using with ms() function
import ms, { Time } from 'enhanced-ms';
// Format time constants
ms(Time.Hour);
// Output: "1 hour"
ms(Time.Day * 7);
// Output: "7 days"
ms(Time.Minute * 90);
// Output: "1 hour 30 minutes"
// Combine with format options
ms(Time.Hour + Time.Minute * 30, 'short');
// Output: "1h 30m"
ms(Time.Day * 2, 'colonNotation');
// Output: "48:00:00"
Calculations
import { Time } from 'enhanced-ms';
// Calculate how many hours in a week
const hoursPerWeek = Time.Week / Time.Hour;
// Result: 168
// Convert days to milliseconds
const fiveDays = Time.Day * 5;
// Check if a duration is more than a day
function isLongerThanDay(ms: number): boolean {
return ms > Time.Day;
}
// Calculate percentage of day elapsed
function percentOfDayElapsed(ms: number): number {
return (ms / Time.Day) * 100;
}
Which constant to use?
Both Time and units provide the same functionality. Choose based on your preference:
Time (PascalCase)
units (lowercase)
import { Time } from 'enhanced-ms';
setTimeout(callback, Time.Second * 5);
const expires = Date.now() + Time.Hour;
- You prefer PascalCase for constants
- You want to distinguish time constants from other variables
- You’re using TypeScript and want the type name to match
import { units } from 'enhanced-ms';
setTimeout(callback, units.second * 5);
const expires = Date.now() + units.hour;
- You prefer lowercase naming
- You want consistency with other lowercase constants
- You find it more natural to read
src/time.ts:1. Both Time and units are typed as const objects with specific numeric values.
// Time type (union of all values)
type Time = 0.000001 | 0.001 | 1 | 1000 | 60000 | ...;
// Unit type (union of all keys)
type Unit = 'nanosecond' | 'microsecond' | 'millisecond' | ...;