Key Features

✨ Features

• 🔄 Bidirectional conversion

  • "1h 30m" → 5400000
  • 5400000 → "1 hour, 30 minutes"

• 📏 Supports all major time units in short, long and plurals

  • years (y), months (mo), weeks (w), days (d), hours (h), minutes (m), seconds (s), milliseconds (ms)

• 📅 Leap year support (isLeapYear)

• 🪶 Formatting options

  • compactUnits → "1d 1h 1m 1s"
  • returnAllUnits → "0 year, 0 month, …"
  • skipUnits → Exclude certain units from output
  • staticUnits → Works only when skipUnits is set. Decides how skipped units behave:

• ➖ Negative duration support

• 🧪 Extensive test coverage (handles edge cases, invalid input, etc.)

Installation

npm install advanced-ms

or

yarn add advanced-ms

How To Use

Import

import AdvancedMS from "advanced-ms";

Convert string → milliseconds

AdvancedMS("1h");         // 3600000
AdvancedMS("2d 3h 15m");  // 184500000
AdvancedMS("1y 2mo");     // 36792000000
AdvancedMS("1000");       // 1000 (plain number strings are parsed)
AdvancedMS("1.5h");       // 5400000

Supports negatives and spaces

AdvancedMS("-1d");        // -86400000
AdvancedMS("-2h -30m");   // -9000000
AdvancedMS(" 2h -30m ");    // 5400000

Convert milliseconds → formatted string

AdvancedMS(3600000);         // "1 hour"
AdvancedMS(31536000000);     // "1 year"
AdvancedMS(90061000);        // "1 day, 1 hour, 1 minute, 1 second"

Options

isLeapYear: boolean

• Determines whether a year should be treated as a leap year (366 days) instead of a normal year (365 days). This only affects conversions involving months or years.
  • Default: false

// Normal year (365 days)
AdvancedMS(31536000000, { isLeapYear: false }); // "1 year"

// Leap year (366 days)
AdvancedMS(31622400000, { isLeapYear: true }); // "1 year"

// Example with months
AdvancedMS("1mo", { isLeapYear: true });  // 31622400000 / 12
AdvancedMS("1mo", { isLeapYear: false }); // 31536000000 / 12

returnAllUnits: boolean

• If true, lists all units, including those with a value of 0.
  • Default: false (only non-zero units are shown)

// Only non-zero units
AdvancedMS(90061000, { returnAllUnits: false }); // "1 day, 1 hour, 1 minute, 1 second"

// All units, including zeros
AdvancedMS(90061000, { returnAllUnits: true }); // "0 year, 0 month, 0 week, 1 day, 1 hour, 1 minute, 1 second, 0 millisecond"

compactUnits: boolean

• Controls the output style of the duration string:
  • Default: false (Full words, e.g., "2 hours, 30 minutes")

// Expanded (default)
AdvancedMS(90061000, { compactUnits: false }); // "1 day, 1 hour, 1 minute, 1 second"

// Compact
AdvancedMS(90061000, { compactUnits: true }); // "1d 1h 1m 1s"

skipUnits: Array<CompactUnit>

• Specifies which units to exclude from the output. Units can be: 'y' | 'mo' | 'w' | 'd' | 'h' | 'm' | 's' | 'ms'
  • Default: false

// Default 
AdvancedMS(90061000, { skipUnits: [] }); // "1 day, 1 hour, 1 minute, 1 second"

// Roll skipped units into smaller units
AdvancedMS(90061000, { skipUnits: ['h', 'm'] }); // "1 day, 3661 seconds"

lockUnits: boolean

• Used only with skipUnits. Determines how skipped units behave:
  • Default: false (Skipped unit values roll down to smaller units.)
  • true (Skipped units value does NOT add onto smaller units.)

// Normal behavior (skipped units roll down)
AdvancedMS(90061000, { skipUnits: ['h', 'm'], lockUnits: false }); // "1 day, 3661 seconds"

// Ignore skipped units entirely
AdvancedMS(90061000, { skipUnits: ['h', 'm'], lockUnits: true }); // "1 day, 1 second"

⚠️ Error Handling

Throws clear errors on invalid input:

AdvancedMS("");          // ❌ Error: Value is not a valid string
AdvancedMS("1x");        // ❌ Error: Value is not a valid string
AdvancedMS({} as any);   // ❌ Error: Value is not a valid string nor number

Contributors

License

GPL-3.0