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

Configuration Settings

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

Comprehensive settings system providing fine-grained control over formatting behavior, including trimming, precision, localization, value ranges, and output formatting.

Capabilities

Settings Object Interface

Complete configuration interface for customizing duration formatting behavior.

/**
 * Settings object for duration formatting
 * All properties are optional with intelligent defaults
 */
interface FormatSettings {
  // Core formatting
  template?: string | function;
  precision?: number;
  
  // Trimming control
  trim?: string | boolean | null;
  stopTrim?: string | string[] | null;
  largest?: number | null;
  
  // Value processing
  trunc?: boolean;
  forceLength?: boolean | null;
  useSignificantDigits?: boolean;
  
  // Value range limits
  minValue?: number | null;
  maxValue?: number | null;
  
  // Localization
  userLocale?: string | null;
  usePlural?: boolean;
  useLeftUnits?: boolean;
  useToLocaleString?: boolean;
  useGrouping?: boolean;
  
  // Fallback number formatting
  groupingSeparator?: string;
  decimalSeparator?: string;
  grouping?: number[];
}

Core Formatting Settings

Template

Controls the format pattern used for output generation.

template?: string | function;
// Default: defaultFormatTemplate function

Usage Examples:

// String templates
moment.duration(3661, "seconds").format({ template: "h:mm:ss" });
// "1:01:01"

// Function templates
function customTemplate() {
    return this.duration.asSeconds() > 3600 ? "h [hours]" : "m [minutes]";
}

moment.duration(3661, "seconds").format({ template: customTemplate });
// "1 hour"

Precision

Controls decimal places (positive) or integer truncation (negative).

precision?: number;
// Default: 0

Usage Examples:

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

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

// Negative precision: integer truncation
moment.duration(1234, "seconds").format({ 
    template: "s [seconds]", 
    precision: -1 
});  // "1230 seconds"

moment.duration(1234, "seconds").format({ 
    template: "s [seconds]", 
    precision: -2 
});  // "1200 seconds"

Trimming Control Settings

Trim

Controls which zero-value tokens are removed from output.

trim?: string | boolean | null;
// Default: null (treated as "large")
// Values: "large", "small", "both", "mid", "final", "all", 
//         "left", "right", true, false, null

Usage Examples:

var duration = moment.duration(123, "minutes");

// "large" - trim largest-magnitude zeros (default)
duration.format({ template: "d[d] h:mm:ss", trim: "large" });
// "2:03:00"

// "small" - trim smallest-magnitude zeros  
duration.format({ template: "d[d] h:mm:ss", trim: "small" });
// "0d 2:03"

// "both" - trim both ends
duration.format({ template: "d[d] h[h] m[m] s[s]", trim: "both" });
// "2h 3m"

// "mid" - trim middle zeros
moment.duration(1441, "minutes").format({ 
    template: "w[w] d[d] h[h] m[m] s[s]", 
    trim: "mid" 
});
// "0w 1d 1m 0s"

// "final" - trim final zero
moment.duration(0, "minutes").format({ 
    template: "d[d] h:mm:ss", 
    trim: "large final" 
});
// ""

// "all" - shorthand for "both mid final"
moment.duration(0, "minutes").format({ 
    template: "d[d] h[h] m[m] s[s]", 
    trim: "all" 
});
// ""

// false - no trimming
duration.format({ template: "d[d] h:mm:ss", trim: false });
// "0d 2:03:00"

Stop Trim

Specifies tokens where trimming should stop.

stopTrim?: string | string[] | null;
// Default: null
// Accepts moment token strings individually or in arrays

Usage Examples:

var duration = moment.duration(23, "minutes");

// Single token
duration.format({ 
    template: "d[d] h:mm:ss", 
    stopTrim: "h" 
});
// "0:23:00"

// Multiple tokens as string
moment.duration(2, "hours").format({ 
    template: "y [years], d [days], h [hours], m [minutes], s [seconds]",
    trim: "both",
    stopTrim: "d m"
});
// "0 days, 2 hours, 0 minutes"

// Multiple tokens as array
moment.duration(2, "hours").format({ 
    template: "y [years], d [days], h [hours], m [minutes], s [seconds]",
    trim: "both", 
    stopTrim: ["d", "m"]
});
// "0 days, 2 hours, 0 minutes"

Largest

Limits output to N largest-magnitude tokens with values.

largest?: number | null;
// Default: null
// Automatically sets trim to "all" when specified

Usage Examples:

var duration = moment.duration(7322, "seconds"); // 2h 2m 2s

// Show only 2 largest units
duration.format({ 
    template: "d [days], h [hours], m [minutes], s [seconds]",
    largest: 2
});
// "2 hours, 2 minutes"

// Interaction with trim setting
duration.format({ 
    template: "d [days], h [hours], m [minutes], s [seconds]",
    largest: 3,
    trim: "both"
});
// "0 days, 2 hours, 2 minutes"

// Interaction with stopTrim
moment.duration(1216800, "seconds").format({
    template: "y [years], w [weeks], d [days], h [hours], m [minutes], s [seconds]",
    largest: 3,
    trim: "both",
    stopTrim: "m"
});
// "2 weeks, 0 days, 2 hours"

Value Processing Settings

Trunc

Controls whether final token values are truncated or rounded.

trunc?: boolean;
// Default: false (rounding behavior)

Usage Examples:

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

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

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

// With precision
moment.duration(3780, "seconds").format({ 
    template: "h [hours]", 
    precision: 1,
    trunc: false 
});
// "1.1 hours"

moment.duration(3780, "seconds").format({ 
    template: "h [hours]", 
    precision: 1,
    trunc: true 
});
// "1.0 hours"

Force Length

Forces first token with value to render at full length.

forceLength?: boolean | null;
// Default: null (auto-determined by template)

Usage Examples:

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

// Default behavior - first token length may be trimmed
duration.format({ template: "h:mm:ss" });
// "2:03"

// Force length - first token always full length
duration.format({ template: "h:mm:ss", forceLength: true });
// "02:03"

// Compare with explicit token length
duration.format({ template: "hh:mm:ss" });
// "02:03" (same result, different approach)

Use Significant Digits

Treats precision as significant digits across all units.

useSignificantDigits?: boolean;
// Default: false
// Automatically sets trim to "all" when true

Usage Examples:

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

// Regular precision (decimal places on final token)
duration.format({ 
    template: "d [days], h [hours], m [minutes], s [seconds]",
    precision: 3
});
// "1 day, 3 hours, 46 minutes, 39.000 seconds"

// Significant digits (across all tokens)
duration.format({ 
    template: "d [days], h [hours], m [minutes], s [seconds]",
    useSignificantDigits: true,
    precision: 3
});
// "1 day, 3 hours, 50 minutes"

// With truncation
duration.format({ 
    template: "d [days], h [hours], m [minutes], s [seconds]",
    useSignificantDigits: true,
    precision: 5,
    trunc: true
});
// "1 day, 3 hours, 46 minutes, 30 seconds"

Value Range Settings

Min Value

Shows "< N units" for small values on least-magnitude token.

minValue?: number | null;
// Default: null

Usage Examples:

// Basic min value
moment.duration(59, "seconds").format({ 
    template: "h [hours], m [minutes]",
    minValue: 1
});
// "< 1 minute"

// With bubbling to larger units
moment.duration(59, "seconds").format({ 
    template: "m:ss",
    minValue: 60
});
// "< 1:00"

// With negative durations
moment.duration(-59, "seconds").format({ 
    template: "h [hours], m [minutes]",
    minValue: 1
});
// "> -1 minute"

// With decimal min values
moment.duration(89, "seconds").format({ 
    template: "m",
    minValue: 1.5,
    precision: 1
});
// "< 1.5"

Max Value

Shows "> N units" for large values on greatest-magnitude token.

maxValue?: number | null;
// Default: null
// Automatically sets trim to "all" when specified

Usage Examples:

// Basic max value
moment.duration(15, "days").format({ 
    template: "w [weeks]",
    maxValue: 2
});
// "> 2 weeks"

// With negative durations
moment.duration(-15, "days").format({ 
    template: "w [weeks]",
    maxValue: 2
});
// "< -2 weeks"

// With multiple tokens (lesser tokens forced to 0)
moment.duration(15.5, "days").format({ 
    template: "w [weeks], d [days], h [hours]",
    maxValue: 2,
    trim: false,
    largest: 2
});
// "> 2 weeks, 0 days"

Localization Settings

User Locale

Specifies locale for numerical formatting (overrides moment locale).

userLocale?: string | null;
// Default: null (uses moment.locale())

Usage Examples:

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

// Default locale formatting
duration.format({ template: "m [minutes]", precision: 3 });
// "20,576.117 minutes"

// German locale formatting
duration.format({ 
    template: "m [minutes]", 
    precision: 3,
    userLocale: "de-DE" 
});
// "20.576,117 minutes"

Use Plural

Enables automatic pluralization of unit labels.

usePlural?: boolean;
// Default: true

Usage Examples:

// With pluralization (default)
moment.duration(1, "minutes").format("m [minutes]");
// "1 minute"
moment.duration(2, "minutes").format("m [minute]");  
// "2 minutes"

// Without pluralization
moment.duration(1, "minutes").format({ 
    template: "m [minutes]",
    usePlural: false 
});
// "1 minutes"
moment.duration(2, "minutes").format({ 
    template: "m [minute]",
    usePlural: false 
});
// "2 minute"

Use Left Units

Processes units to the left of tokens instead of right.

useLeftUnits?: boolean;
// Default: false

Usage Examples:

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

// Default behavior (units on right)
duration.format("h [hours], m [minutes], s [seconds]");
// "2 hours, 2 minutes, 2 seconds"

// Left units behavior
duration.format({ 
    template: "[hours] h, [minutes] m, [seconds] s",
    useLeftUnits: true 
});
// "hours 2, minutes 2, seconds 2"

// With auto-localization
duration.format({ 
    template: "_ h, _ m, _ s",
    useLeftUnits: true 
});
// "hrs 2, mins 2, secs 2"

Use Grouping

Enables digit grouping in numerical output.

useGrouping?: boolean;  
// Default: true

Usage Examples:

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

// With grouping (default)
duration.format("s [seconds]");
// "1,234 seconds"

// Without grouping
duration.format({ 
    template: "s [seconds]",
    useGrouping: false 
});
// "1234 seconds"

Fallback Number Formatting Settings

Used when native toLocaleString or Intl.NumberFormat are unavailable or disabled.

Use To Locale String

Controls whether to use native number formatting APIs.

useToLocaleString?: boolean;
// Default: true

Grouping Separator

Thousands separator for fallback formatting.

groupingSeparator?: string;
// Default: ","

Decimal Separator

Decimal point character for fallback formatting.

decimalSeparator?: string;
// Default: "."

Grouping Pattern

Digit grouping pattern for fallback formatting.

grouping?: number[];
// Default: [3] (standard thousands grouping)

Usage Examples:

// Custom fallback number formatting
moment.duration(100000.1, "seconds").format({ 
    template: "s",
    userLocale: "de-DE",
    precision: 2,
    useToLocaleString: false,    // Force fallback
    decimalSeparator: ",",
    groupingSeparator: ".",
    grouping: [3]
});
// "100.000,10"

// Indian locale-style grouping
moment.duration(100000000000, "seconds").format({ 
    template: "m",
    useToLocaleString: false,
    precision: 2,
    decimalSeparator: ",",
    groupingSeparator: " ",
    grouping: [3, 2]  // Thousand/lakh/crore grouping
});
// "1 66 66 66 666,67"