tessl/npm-moment-duration-format

A moment.js plugin for formatting durations with comprehensive template-based formatting and localization support.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Duration Formatting

Name: tessl/npm-moment-duration-format
Author: tessl

Single duration formatting provides comprehensive control over how individual moment duration objects are converted to formatted strings.

Capabilities

Format Method

The primary method for formatting individual duration objects with flexible argument patterns.

/**
 * 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;

Usage Examples:

var duration = moment.duration(3661, "seconds");

// Using template only
duration.format("h:mm:ss");
// "1:01:01"

// Using precision only
duration.format(2);
// "1.02 hours" (default template with 2 decimal places)

// Using settings only
duration.format({ template: "h [hrs] m [min]", trim: "both" });
// "1 hr 1 min"

// Using template and precision
duration.format("h [hours]", 1);
// "1.0 hours"

// Using template and settings
duration.format("h:mm:ss", { forceLength: true });
// "01:01:01"

// Using precision and settings
duration.format(1, { template: "m [minutes]" });
// "61.0 minutes"

// Using all three arguments
duration.format("h [hrs] m [min]", 1, { trim: "both" });
// "1.0 hr 1.0 min"

Default Template Function

Automatically generates appropriate templates based on duration magnitude.

/**
 * Default template function that generates templates based on duration magnitude
 * Executed with 'this' binding to settings object
 * @returns Template string appropriate for the duration's magnitude
 */
function defaultFormatTemplate(): string;

The default template function analyzes the duration's largest unit type and returns templates optimized for that magnitude:

Milliseconds: "S __" (e.g., "100 milliseconds")
Seconds/Minutes: "*_MS_" (e.g., "1:40")
Hours: "_HMS_" (e.g., "1:01:01")
Days: "d __" or falls through to weeks format
Weeks: "w __, d __, h __" with trim: "both"
Months: "M __" or falls through to years format
Years: "y __, M __, d __" with trim: "both"

Usage Examples:

moment.duration(100, "milliseconds").format();
// "100 milliseconds"

moment.duration(100, "seconds").format();
// "1:40"

moment.duration(100, "days").format();
// "3 months, 9 days"

moment.duration(100, "weeks").format();
// "1 year, 10 months, 30 days"

Format Defaults

Global default settings that can be modified to change plugin behavior.

/**
 * Default settings object for duration formatting
 * Can be modified to change global defaults
 */
moment.duration.fn.format.defaults: {
  template: defaultFormatTemplate,
  precision: 0,
  trim: null,
  largest: null,
  maxValue: null,
  minValue: null,
  trunc: false,
  forceLength: null,
  userLocale: null,
  usePlural: true,
  useLeftUnits: false,
  useGrouping: true,
  useSignificantDigits: false,
  stopTrim: null,
  useToLocaleString: true,
  groupingSeparator: ",",
  decimalSeparator: ".",
  grouping: [3]
};

Usage Examples:

// Change global defaults
moment.duration.fn.format.defaults.precision = 2;
moment.duration.fn.format.defaults.trim = "both";

// All subsequent format calls will use new defaults
moment.duration(3661, "seconds").format("h [hours]");
// "1.02 hours" (with 2 decimal places due to changed default)

Template Processing

Token Recognition

The format function recognizes moment tokens and replaces them with duration values:

// Basic tokens
moment.duration(1, "year").format("y");        // "1"
moment.duration(1, "month").format("M");       // "1"
moment.duration(1, "week").format("w");        // "1"
moment.duration(1, "day").format("d");         // "1"
moment.duration(1, "hour").format("h");        // "1"
moment.duration(1, "minute").format("m");      // "1"
moment.duration(1, "second").format("s");      // "1"
moment.duration(1, "millisecond").format("S"); // "1"

// Token length controls padding
moment.duration(5, "minutes").format("mm");    // "05"
moment.duration(5, "minutes").format("mmm");   // "005"

Custom Template Functions

Create dynamic templates based on duration values or other conditions:

function customTemplate() {
    // 'this' is bound to the settings object
    // 'this.duration' provides access to the duration being formatted
    var duration = this.duration;
    
    if (duration.asSeconds() >= 86400) {
        return "w [weeks], d [days]";
    } else if (duration.asSeconds() >= 3600) {
        return "h:mm:ss";
    } else {
        return "m:ss";
    }
}

moment.duration(65, 'seconds').format(customTemplate);
// "1:05"

moment.duration(1347840, 'seconds').format(customTemplate);
// "2 weeks, 2 days"

Value Processing

Precision Control

Positive precision adds decimal places, negative precision truncates integer places:

var duration = moment.duration(3661, "seconds");

// Positive precision - decimal places
duration.format("h [hours]", 0);  // "1 hour"
duration.format("h [hours]", 1);  // "1.0 hours"
duration.format("h [hours]", 2);  // "1.02 hours"

// Negative precision - integer truncation
moment.duration(1234, "seconds").format("s [seconds]", -1);  // "1230 seconds"
moment.duration(1234, "seconds").format("s [seconds]", -2);  // "1200 seconds"

Rounding vs Truncation

Control whether final values are rounded or truncated:

var duration = moment.duration(179, "seconds");

// Default behavior (rounding)
duration.format("m [minutes]");           // "3 minutes"

// Truncation behavior
duration.format("m [minutes]", { trunc: true }); // "2 minutes"