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

Multiple Duration Formatting

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

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

Capabilities

Multiple Duration Format Method

Format arrays of duration objects with coordinated trimming and consistent token usage.

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

Usage Examples:

var durations = [
    moment.duration(1, "minute"),
    moment.duration(1, "hour"),
    moment.duration(1, "day")
];

// Basic multiple formatting
moment.duration.format(durations, "h:mm:ss");
// ["0:01:00", "1:00:00", "24:00:00"]

// With settings
moment.duration.format(durations, "d [days], h [hours], m [minutes]", {
    trim: "both"
});
// ["1 minute", "1 hour", "1 day"]

// Coordinated trimming demonstration
moment.duration.format([
    moment.duration(30, "seconds"),
    moment.duration(2, "hours"),
    moment.duration(3, "days")
], "d [days], h [hours], m [minutes], s [seconds]");
// [
//   "0 days, 0 hours, 0 minutes, 30 seconds",
//   "0 days, 2 hours, 0 minutes, 0 seconds", 
//   "3 days, 0 hours, 0 minutes, 0 seconds"
// ]

Coordinated Processing

Unified Token Analysis

The multiple duration formatter analyzes all durations to determine which tokens should appear in the final output, ensuring consistency across the result set.

Internal Process:

Format each duration individually with returnMomentTypes: true
Merge token types from all durations
Apply largest setting if specified to limit output types
Re-format all durations using the unified token types

Usage Examples:

// Different magnitude durations get consistent formatting
var mixedDurations = [
    moment.duration(30, "seconds"),      // Small magnitude
    moment.duration(2, "hours"),         // Medium magnitude  
    moment.duration(3, "days")           // Large magnitude
];

moment.duration.format(mixedDurations, "w [w] d [d] h [h] m [m] s [s]");
// All outputs include the same token types:
// [
//   "0w 0d 0h 0m 30s",
//   "0w 0d 2h 0m 0s",
//   "0w 3d 0h 0m 0s"  
// ]

// Compare with individual formatting (inconsistent)
mixedDurations.map(d => d.format("w [w] d [d] h [h] m [m] s [s]"));
// [
//   "30s",      // Only seconds shown
//   "2h",       // Only hours shown  
//   "3d"        // Only days shown
// ]

Coordinated Trimming

Trimming behavior is coordinated across all durations to maintain consistent output structure.

var durations = [
    moment.duration(1, "second"),
    moment.duration(1, "minute"), 
    moment.duration(1, "hour")
];

// Without coordination, individual formatting would vary
durations.map(d => d.format("h [hours], m [minutes], s [seconds]"));
// [
//   "1 second",           // Different structure
//   "1 minute",           // Different structure
//   "1 hour"              // Different structure
// ]

// With coordinated formatting
moment.duration.format(durations, "h [hours], m [minutes], s [seconds]");
// [
//   "0 hours, 0 minutes, 1 second",    // Consistent structure
//   "0 hours, 1 minute, 0 seconds",    // Consistent structure
//   "1 hour, 0 minutes, 0 seconds"     // Consistent structure
// ]

Largest Setting Application

The largest setting is applied to the unified token set, not individual durations.

var durations = [
    moment.duration(7322, "seconds"),      // 2 hours, 2 minutes, 2 seconds
    moment.duration(3661, "seconds"),      // 1 hour, 1 minute, 1 second
    moment.duration(61, "seconds")         // 1 minute, 1 second
];

moment.duration.format(durations, "h [hours], m [minutes], s [seconds]", {
    largest: 2
});
// All durations show the same 2 largest token types:
// [
//   "2 hours, 2 minutes",   // Hours and minutes (largest 2)
//   "1 hour, 1 minute",     // Hours and minutes (largest 2)  
//   "0 hours, 1 minute"     // Hours and minutes (largest 2)
// ]

Settings Inheritance

All settings available for single duration formatting apply to multiple duration formatting, with the same settings object used to format each individual duration.

Shared Configuration

var durations = [
    moment.duration(3661.5, "seconds"),
    moment.duration(7200.7, "seconds")
];

var settings = {
    template: "h [hrs] m [min] s [sec]",
    precision: 1,
    trim: "small",
    usePlural: true
};

moment.duration.format(durations, settings);
// [
//   "1.0 hr 1.0 min 1.5 sec",
//   "2.0 hrs 0.0 min 0.7 sec"  
// ]

Template Functions with Multiple Durations

Template functions receive the same context for each duration but can access individual duration values:

function adaptiveTemplate() {
    var seconds = this.duration.asSeconds();
    
    if (seconds < 60) {
        return "s [seconds]";
    } else if (seconds < 3600) {
        return "m:ss";
    } else {
        return "h:mm:ss";
    }
}

var durations = [
    moment.duration(30, "seconds"),
    moment.duration(90, "seconds"),
    moment.duration(3661, "seconds")
];

// Note: Template functions work differently with multiple durations
// Each duration gets its own template evaluation
moment.duration.format(durations, adaptiveTemplate);
// Results depend on individual duration magnitudes

Error Handling

Invalid durations in the array are treated consistently with single duration formatting:

var durations = [
    moment.duration(60, "seconds"),
    moment.duration(NaN, "seconds"),  // Invalid
    moment.duration(120, "seconds")
];

moment.duration.format(durations, "m:ss");
// [
//   "1:00",
//   "0:00",    // Invalid duration treated as 0
//   "2:00"
// ]