Moment Duration Format

Moment Duration Format is a comprehensive plugin for Moment.js that adds powerful formatting capabilities to Moment Duration objects. It provides a template-based formatting system with extensive customization options including precision control, intelligent trimming, localization support, and flexible output formatting.

Package Information

• Package Name: moment-duration-format
• Package Type: npm
• Language: JavaScript
• Installation: npm install moment-duration-format
• Dependencies: moment.js (peer dependency)

Core Imports

CommonJS (Node.js):

var moment = require("moment");
var momentDurationFormatSetup = require("moment-duration-format");

AMD:

define(['moment'], factory);

Browser (global):

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

Manual setup for other moment packages:

var moment = require("moment-timezone");
var momentDurationFormatSetup = require("moment-duration-format");
momentDurationFormatSetup(moment);

Basic Usage

var moment = require("moment");
require("moment-duration-format");

// Basic formatting with default template
moment.duration(123, "minutes").format();
// "2:03:00"

// Custom template formatting
moment.duration(3661, "seconds").format("h [hours], m [minutes], s [seconds]");
// "1 hour, 1 minute, 1 second"

// Formatting with precision
moment.duration(3780, "seconds").format("h [hours]", 1);
// "1.1 hours"

// Multiple duration formatting
moment.duration.format([
    moment.duration(1, "hour"),
    moment.duration(30, "minutes")
], "h:mm");
// ["1:00", "0:30"]

Architecture

Moment Duration Format extends the Moment.js Duration prototype with formatting capabilities:

• Template System: Flexible template strings with moment tokens (y, M, w, d, h, m, s, S)
• Format Functions: Both single duration (duration.fn.format) and multi-duration (duration.format) formatting
• Settings Engine: Comprehensive configuration system with intelligent defaults
• Trimming Logic: Smart removal of zero-value tokens based on magnitude and user preferences
• Localization: Full i18n support with auto-pluralization and number formatting
• Fallback System: Robust fallback number formatting when native APIs are unavailable

Capabilities

Single Duration Formatting

Format individual moment duration objects with extensive customization options including templates, precision, and comprehensive settings.

/**
 * Format a duration using template, precision, and settings
 * @param template - Format template string or function (optional)
 * @param precision - Number of decimal places or integer truncation (optional)
 * @param settings - Configuration object (optional)
 * @returns Formatted duration string
 */
moment.duration.fn.format([template] [, precision] [, settings]): string

Duration Formatting

Multiple Duration Formatting

Format arrays of duration objects with coordinated output, ensuring consistent formatting across all durations in the set.

/**
 * Format multiple durations with coordinated output
 * @param durationsArray - Array of moment duration objects  
 * @param template - Format template string or function (optional)
 * @param precision - Number of decimal places or integer truncation (optional)
 * @param settings - Configuration object (optional)
 * @returns Array of formatted duration strings
 */
moment.duration.format(durationsArray, [template] [, precision] [, settings]): string[]

Multiple Duration Formatting

Template System

Powerful template engine with moment tokens, escape sequences, auto-localization markers, and dynamic template functions.

// Template tokens: Y/y (years), M (months), W/w (weeks), D/d (days), 
// H/h (hours), m (minutes), s (seconds), S (milliseconds)
// Escape sequences: [text]
// Auto-localization: _ (short), __ (standard), _HMS_, _HM_, _MS_

Template System

Configuration Settings

Comprehensive settings system controlling trimming, precision, localization, value ranges, and output formatting.

interface FormatSettings {
  template?: string | function;
  precision?: number;
  trim?: string | boolean | null;
  largest?: number | null;
  useSignificantDigits?: boolean;
  // ... 20+ additional configuration options
}

Configuration Settings

Localization

Complete internationalization support with auto-pluralization, locale-specific number formatting, and extensible locale definitions.

// Locale extensions for duration labels and pluralization
moment.updateLocale('en', {
  durationLabelsStandard: { /* ... */ },
  durationLabelsShort: { /* ... */ },
  durationTimeTemplates: { /* ... */ },
  durationPluralKey: function(token, integerValue, decimalValue) { /* ... */ }
});

Localization

Setup and Installation

Manual Setup Function

/**
 * Setup function to initialize the plugin on a moment instance
 * @param moment - The moment instance to extend
 */
function momentDurationFormatSetup(moment: any): void;

The plugin automatically attempts to install on the global moment instance if available, but the setup function can be used to manually initialize on specific moment instances (useful with moment-timezone or other moment variants).

Error Handling

Invalid durations are treated as having a value of 0 for formatting purposes:

var invalidDuration = moment.duration(NaN, "second");
invalidDuration.isValid(); // false
invalidDuration.format(); // "0 seconds"

Feature Detection

The plugin performs feature tests on initialization to determine the best number formatting method available:

• Intl.NumberFormat: Modern internationalization API with full locale support
• Number.toLocaleString: Fallback locale-aware number formatting
• Internal Formatter: Plugin's own number formatting when native APIs are unavailable or buggy

The plugin automatically selects the most capable formatter and handles cross-browser compatibility transparently. Use useToLocaleString: false in settings to force the internal formatter.