@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:

| Feature | ms | @cutticat/ms | | :-------------: | :--: | :------------: | | Simple parsing ("2 days") | ✅ | ✅ | | Arithmetic ("10h + 5min", "1d - 30min") | ❌ | ✅ | | MM:SS / HH:MM:SS format ("1:30:45") | ❌ | ✅ | | Output formats (short, long, iso, colon) | ❌ | ✅ | | Decimal numbers ("1.5h") | ❌ | ✅ | | Scientific notation ("12e3") | ❌ | ✅ | | Custom formats (createMs) | ❌ | ✅ | | Unary +/- ("-5min") | ❌ | ✅ |

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