moment-duration-format

What is moment-duration-format?

The moment-duration-format npm package is an extension for the Moment.js library that allows for the formatting of durations. It provides a simple and flexible way to format durations in various human-readable formats.

What are moment-duration-format's main functionalities?

Basic Duration Formatting

This feature allows you to format a duration into a human-readable string. In this example, a duration of 123 minutes is formatted into '2 hrs, 3 min'.

const moment = require('moment');
require('moment-duration-format');

const duration = moment.duration(123, 'minutes');
const formattedDuration = duration.format('h [hrs], m [min]');
console.log(formattedDuration); // Output: '2 hrs, 3 min'

Customizing Output

This feature allows you to customize the output format of the duration. In this example, a duration of 3661 seconds is formatted into '1:01:01'.

const moment = require('moment');
require('moment-duration-format');

const duration = moment.duration(3661, 'seconds');
const formattedDuration = duration.format('h:mm:ss');
console.log(formattedDuration); // Output: '1:01:01'

Truncating Zero Values

This feature allows you to control whether zero values are included in the formatted output. In this example, a duration of 65 seconds is formatted into '0:01:05' without trimming zero values.

const moment = require('moment');
require('moment-duration-format');

const duration = moment.duration(65, 'seconds');
const formattedDuration = duration.format('h:mm:ss', { trim: false });
console.log(formattedDuration); // Output: '0:01:05'

Other packages similar to moment-duration-format

dayjs

Day.js is a minimalist JavaScript library that parses, validates, manipulates, and displays dates and times. It has a plugin called 'duration' that provides similar functionality to moment-duration-format, allowing you to format durations in a human-readable way. Compared to moment-duration-format, Day.js is smaller in size and has a more modern API.

luxon

Luxon is a powerful, modern JavaScript library for working with dates and times. It provides a Duration class that can be used to format durations. Luxon is designed to be a more modern and comprehensive alternative to Moment.js, with better support for internationalization and time zones. It offers similar functionality to moment-duration-format but with a more extensive feature set.

date-fns

date-fns is a modern JavaScript date utility library that provides a wide range of functions for manipulating dates and times. It includes functions for formatting durations, similar to moment-duration-format. date-fns is known for its modular approach, allowing you to import only the functions you need, which can result in smaller bundle sizes compared to Moment.js and its plugins.

README

#Moment Duration Format

###Format plugin for the Moment Duration object.

This is a plugin to the Moment.js JavaScript date library to add comprehensive formatting to Moment Durations.

Format template grammar is patterned on the existing Moment Date format template grammar, with a few modifications because durations are fundamentally different from dates.

This plugin depends on Lo-Dash or Underscore, and is tested with both libraries.

---

Installation

Node.js

npm install moment-duration-format

Bower

bowser install moment-duration-format

Browser

<script src="path/to/moment-duration-format.js"></script>

Be sure to include moment.js and lodash.js or underscore.js on your page before loading this plugin.

---

Usage

The format function may be called with three optional arguments:

moment.duration.format([template] [, precision] [, settings])

Both the template and precision arguments may be specified as part of a single settings object argument if desired.

Within the template string, moment-token characters will be replaced with the duration value for that type. Moment-tokens maybe be customized (see test cases for examples), but the default token map is:

years:   Y or y
months:  M
weeks:   W or w
days:    D or d
hours:   H or h
minutes: m
seconds: s
ms:      S

Basic usage:

moment.duration(123, "minutes").format();
// "2:03:00"

moment.duration(123, "minutes").format("h:mm");
// "2:03"

moment.duration(123, "minutes").format("h [hrs], m [min]");
// "2 hrs, 3 min"
// escape moment-tokens using square brackets
// this can be customized using `settings.escape`

moment.duration(123, "minutes").format("h [hrs]", 2);
// "2.04 hrs"
// show arbitrary decimal precision with positive precision

moment.duration(123, "minutes").format("m [min]", -1);
// "120 min"
// truncate the final value with negative precision

moment.duration(123, "minutes").format("d[d] h:mm:ss");
// "2:03:00"
// automatically trim leading tokens that have no value

moment.duration(123, "minutes").format("[seconds:] s -- [minutes:] m -- [hours:] h -- [days:] d", { trim: "right" });
// "seconds: 0 -- minutes: 3 -- hours: 2"
// or trim from the right

moment.duration(123, "minutes").format("d[d] h:mm:ss", { trim: false });
// "0d 2:03:00"
// or don't trim at all

See the test cases and the default options for more thorough option descriptions.