millisecs

Description:

millisecs

millisecs #
Converts various time formats to milliseconds and vice versa. Dart & Flutter adaptation of Vercel's ms npm package.
Usage #
Import #
import 'package:millisecs/millisecs.dart';
copied to clipboard
Convert from Time Formats #
ms('2 days'); // 172800000
ms('1d'); // 86400000
ms('10h'); // 36000000
ms('2.5 hrs'); // 9000000.0
ms('2h'); // 7200000
ms('1m'); // 60000
ms('5s'); // 5000
ms('1y'); // 31557600000.0
ms('100'); // 100
ms('-3 days'); // -259200000
ms('-1h'); // -3600000
ms('-200'); // -200
copied to clipboard
Convert from Milliseconds #
ms(60000); // "1m"
ms(2 * 60000); // "2m"
ms(-3 * 60000); // "-3m"
ms(ms('10 hours')); // "10h"
copied to clipboard
Time Format Written-Out #
ms(60000, long: true); // "1 minute"
ms(2 * 60000, long: true); // "2 minutes"
ms(-3 * 60000, long: true); // "-3 minutes"
ms(ms('10 hours'), long: true); // "10 hours"
copied to clipboard
parse and format #
parse('1h'); // 3600000
format(2000); // "2s"
format(2000, long: true); // "2 seconds"

tryParse('1h'); // 3600000
tryFormat(2000); // "2s"

tryParse('🎯'); // null
tryFormat(double.infinity); // null
copied to clipboard
Extensions #
'2.5 hrs'.parseMS(); // 9000000.0
'1y'.parseMS(); // 31557600000.0
'100'.parseMS(); // 100
'-3 days'.parseMS(); // -259200000

'10 hours'.parseMS().formatMS(); // "10h"
6000.formatMS(); // "2m"
(2 * 60000).formatMS(long: true); // "2 minutes"

'1h'.tryParseMS(); // 3600000
'🎯'.tryParseMS(); // null
2000.tryFormatMS(); // "2s"
double.infinity.tryFormatMS(); // null
copied to clipboard
Features #

Works both in Dart and Flutter.
If you pass a string with a number and a valid unit, the number of equivalent milliseconds is returned.
If a string that contains the number is supplied, it returns it as a number (e.g.: it returns 100 for '100').
If a number is supplied to ms, a string with a unit is returned.
ms throws ArgumentErrors if invalid strings or non-finite numbers are provided.
Use tryMS instead of ms to return null instead of throwing errors.
Parsing is case-insensitive. So '2.5 hrs' and '2.5 HRs' will both evaluate to 9000000.
The direct parse and format functions are also exposed. ms is built around them.
Extensions are available for the direct method calls on strings and numbers.

Additional Information #
Rounding #
When formatting, the numbers are been rounded up or down as appropriate. So ms(1499) will yield "1s". While ms(1500) will give "2s".
dynamic #
The parameter and return value of ms both have the dynamic type.
As of the time this paragraph was written (August 2024), this is the only native way to allow support for multiple types (Strings and nums) in the same variables. This is because Dart doesn't natively support Union types with raw types as you can see in TypeScript:
// Following is from ms in TypeScript at
// https://github.com/vercel/ms/blob/f150c1cfc73a8c08cfdb191b253a33d55462c327/src/index.ts#L42-L47

type UnitAnyCase = Unit | Uppercase<Unit> | Lowercase<Unit>;

export type StringValue =
| `${number}`
| `${number}${UnitAnyCase}`
| `${number} ${UnitAnyCase}`;
copied to clipboard
Coming over to Dart, as there is no way to achieve the above (to improve types), ms simply uses dynamic. The code works as expected. If need be, you might want to interpolate the result from ms into a string or cast it to your desired type (string or num):
final toDisplay1 = ms(24 * 60 * 60 * 1000) as String; // "1d"
final toDisplay2 = '${ms(24 * 60 * 60 * 1000)}'; // "1d"
copied to clipboard
If you want more type control, use the extensions or the parse and format functions. parse takes a String and returns a num, whereas format does the opposite (takes a num and returns a String). If you are not worried about the dynamic type, then enjoy ms as it is.
Formatting to weeks and years #
In the "inspirer" code (Vercel's), parsing goes up to years, but formatting stops at days. However, in this Dart implementation, formatting includes weeks and years, just as parsing does. Mentioning this here in case someone is already accustomed with the "no-weeks & no-years" formatted strings in JavaScript: the inclusion of weeks and years in Dart is rather intentional.
Contribute #
In case of bugs, feature requests, or enhancements, open an issue or send a pull request.