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

bower 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

Module

To use this plugin as a module, use the require function:

require("moment-duration-format");

The plugin does not export anything, so there is no need to assign the require output to a variable.

The plugin depends on moment.js and lodash.js or underscore.js. These are not specified as package dependencies in the currently published plugin version.

Arguments

The duration format method may be called with three optional arguments:

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

template is a string. It is parsed for moment-token characters, which are replaced with the duration value for that type. Moment-tokens may be 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

precision is an integer. Positive precision defines the number of decimal digits to display. Negative precision will truncate the value to the left of the decimal point.

Both the template and precision arguments may be specified as properties of a single settings object argument if desired, or they may be passed separately along with an optional settings object.

Basics

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 settings for more thorough option descriptions.