feat: Add versatile duration formatting and parsing function

[SeanLuis]

Overview

This pull request introduces a new feature: the formatOrParseDuration function. This function provides the ability to both format durations given in milliseconds to a specified string format and parse duration strings back into milliseconds. This enhancement aims to offer a robust and scalable solution for duration handling within the library.

Features

• Formatting Durations: Converts durations from milliseconds to formatted strings in various styles.
  • Supported formats include:
    • hh:mm:ss
    • mm:ss
    • DD:hh:mm:ss
    • hh:mm:ss,SSS
• Parsing Durations: Converts duration strings in specified formats back into milliseconds.
  • Supported formats include:
    • hh:mm:ss
    • mm:ss
    • DD:hh:mm:ss
    • hh:mm:ss,SSS

Tasks Completed

• [x] Implemented formatOrParseDuration function
  • [x] Added support for formatting durations from milliseconds to various string formats
  • [x] Added support for parsing duration strings back into milliseconds
• [x] Enhanced duration formatting options to include milliseconds (hh:mm:ss,SSS)
• [x] Updated types and interfaces to support the new duration formatting and parsing
• [x] Wrote comprehensive unit tests for:
  • [x] Formatting durations (hh:mm:ss, mm:ss, DD:hh:mm:ss, hh:mm:ss,SSS)
  • [x] Parsing durations (hh:mm:ss, mm:ss, DD:hh:mm:ss, hh:mm:ss,SSS)
  • [x] Handling invalid inputs and duration strings

Implementation Details

Function: formatOrParseDuration

• Parameters:

  • input (number | string): Duration in milliseconds to format or a string to parse.
  • options (DurationOptions): Options to define formatting or parsing behavior, including:
    • format: Desired format for the duration string or parsing pattern.
    • parse: Boolean indicating whether to parse a string or format a duration.
    • locale: Locale string for future compatibility.

• Behavior:

  • When parse is true, it parses the provided duration string into milliseconds based on the specified format.
  • When parse is false, it formats the given duration in milliseconds to a string based on the specified format.
  • Throws an error for invalid inputs or options.

Tests

Comprehensive tests have been added to cover various scenarios for both formatting and parsing:

• Formatting durations to hh:mm:ss, mm:ss, DD:hh:mm:ss, hh:mm:ss,SSS.
• Parsing duration strings in the above formats back into milliseconds.
• Handling invalid inputs and duration strings with appropriate error messages.

Example Usage

import { formatOrParseDuration } from "@formkit/tempo";

// Formatting durations
formatOrParseDuration(3661000); // Output: "01:01:01"
formatOrParseDuration(61000, { format: "mm:ss" }); // Output: "01:01"
formatOrParseDuration(3660000, { format: "hh:mm" }); // Output: "01:01"
formatOrParseDuration(90061000, { format: "DD:hh:mm:ss" }); // Output: "01:01:01:01"
formatOrParseDuration(90061001, { format: "DD:hh:mm:ss,SSS" }); // Output: "01:01:01:01,001"
formatOrParseDuration(3661001, { format: "hh:mm:ss,SSS" }); // Output: "01:01:01,001"

// Parsing durations
formatOrParseDuration("01:01:01", { format: "hh:mm:ss", parse: true }); // Output: 3661000
formatOrParseDuration("01:01", { format: "mm:ss", parse: true }); // Output: 61000
formatOrParseDuration("01:01", { format: "hh:mm", parse: true }); // Output: 3660000
formatOrParseDuration("01:01:01:01", { format: "DD:hh:mm:ss", parse: true }); // Output: 90061000
formatOrParseDuration("01:01:01,001", { format: "hh:mm:ss,SSS", parse: true }); // Output: 3661001

// Error handling
try {
  formatOrParseDuration("invalid input");
} catch (error) {
  console.error(error); // Output: Error: Invalid input or options.
}

try {
  formatOrParseDuration("invalid input", { format: "hh:mm:ss", parse: true });
} catch (error) {
  console.error(error); // Output: Error: Invalid duration string.
}