@cutticat/ms

A library for parsing and formatting time intervals (durations).

Contents

• Overview
• Installation
• Quick start
• Comparison with ms
• API
• Documentation
• Requirements

Overview

The library provides a single ms function that:

• Parses string duration representations into milliseconds
• Formats milliseconds into various string formats

Supports intervals (y, yr, mo, w, d, h, min, s, ms), operations (+/-), time formats (MM:SS, HH:MM:SS), and numbers in scientific notation.

Installation

pnpm i @cutticat/ms

Quick start

import { ms } from "@cutticat/ms"

// Parse strings into milliseconds
ms("10h + 5min") // 36_300_000
ms("1:30:45") // 5_445_000
ms("-5min") // -300_000
ms("1d 2mo - 1:10:20") // 5_266_180_000

// Format milliseconds into strings
ms(36_300_000) // "10h 5m"
ms(36_300_000, { format: "long" }) // "10 hours 5 minutes"
ms(36_300_000, { format: "iso" }) // "PT10H5M"
ms(36_300_000, { format: "colon" }) // "10:05:00"
ms(36_300_000, { format: "number" }) // "36300000"

Comparison with ms

This library is an extended alternative to the popular ms package:

API

Functions

• ms(input, options?) — parses a string into milliseconds or formats a number into a string
• createMs(options?) — creates a custom instance with its own formatters and default format

Output formats

• short — short format (“10h 5m”)
• long — full format (“10 hours 5 minutes”)
• iso — ISO 8601 Duration (“PT10H5M”)
• colon — colon-separated format (“10:05:00”)
• number — number as a string (“36300000”)

Types

• CreateMsOptions — options for createMs
• MsFormatOptions — formatting options
• Ms — type of the ms function

Documentation

Further documentation:

• Project structure
• Scripts
• Style guide
• Contributing

Full API documentation is available in JSDoc comments.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0