Duration: Time Difference Made Readable

This is a small JavaScript library that calculates and displays the time between two dates in a human-friendly way. Instead of just telling you "321 billion milliseconds passed," it breaks that down into years, months, days, hours, and so on—letting you see that it's actually 10 years, 2 months, 6 days, and a bit of time left over.

You give the library two dates (a start date and an end date), and it figures out exactly how much time elapsed. The library then lets you access that information in multiple ways: you can ask for the total number of days, the total number of hours, or just the leftover days after you've counted all the complete months and years. For example, if you have 10 years and 2 months, you can ask "how many months total?" and get 122, or ask "how many months are left after counting the full years?" and get just 2.

The most useful part is the toString method, which converts a duration into readable text. By default it produces something like "10y 2m 6d 03:23:08.456" (10 years, 2 months, 6 days, 3 hours, 23 minutes, 8 seconds, 456 milliseconds). If you want a different format, you can supply your own pattern—like "H: %Hs m: %M"—and it will plug the numbers in where you tell it to.

This would be useful for any JavaScript application that needs to display how long something took or will take. A project tracker might use it to show "the deadline is 3 months and 5 days away." A fitness app could display "you've worked out for a total of 45 hours this year." A data backup tool could log "the last backup completed in 2 hours and 14 minutes." The library handles all the calendar math so you don't have to build it yourself.