duratii

A lightweight utility to convert duration strings into UTC timestamps, total seconds, and milliseconds, and vice versa.

Features

• Convert Duration to Timestamp: Add a duration (e.g., "1y 2mo 3w 4d 5h 6m 7s 250ms") to a base date (or current date) to get a UTC timestamp.
• Convert Timestamp to Duration: Get a human-readable duration string by comparing a UTC timestamp to a base date.
• Convert Duration to Numbers: Calculate the total duration in seconds and milliseconds.
• Supports Fractional and Negative Values: Parse and compute with decimals and negatives.
• Units Supported: Years (y), Months (mo), Weeks (w), Days (d), Hours (h), Minutes (m), Seconds (s), and Milliseconds (ms).

Installation

npm install duratii

Usage

import {
  convertDurationToUTCTimestamp,
  convertUTCTimestampToDurationString,
  convertDurationToNumbers
} from 'duratii';

// Convert a duration string to a UTC timestamp
const { utcTimestamp, durationMs } = convertDurationToUTCTimestamp("1y 2mo 3w 4d 5h 6m 7s 250ms");
console.log("UTC Timestamp:", utcTimestamp);
console.log("Duration in ms:", durationMs);

// Convert a UTC timestamp back to a duration string
const durationString = convertUTCTimestampToDurationString(utcTimestamp);
console.log("Duration String:", durationString);

// Convert a duration string to total seconds and milliseconds
const { totalSeconds, totalMilliseconds } = convertDurationToNumbers("1h 30m");
console.log("Total Seconds:", totalSeconds);
console.log("Total Milliseconds:", totalMilliseconds);

API

convertDurationToUTCTimestamp(durationStr: string, baseDate?: Date): DurationResult

• Parameters:
  • durationStr: The duration string to convert.
  • baseDate (optional): The base date for the calculation (defaults to now).
• Returns: An object with:
  • utcTimestamp: The resulting UTC timestamp (in milliseconds).
  • durationMs: The total milliseconds added to the base date.

convertUTCTimestampToDurationString(utcTimestamp: number, baseDate?: Date): string

• Parameters:
  • utcTimestamp: The target UTC timestamp.
  • baseDate (optional): The base date for comparison (defaults to now).
• Returns: A human-readable duration string.

convertDurationToNumbers(durationStr: string): { totalSeconds: number; totalMilliseconds: number }

• Parameters:
  • durationStr: The duration string to convert.
• Returns: An object containing the total duration in seconds and milliseconds.

License

MIT