Durations

Elemental also provides tools for representing and formatting periods of time using the LmnDuration class and lmnDuration pipe. These are useful for displaying things like video lengths, estimated completion times, or any other time spans.

The Elemental Duration system allows you to represent, manipulate, and format periods of time. It leverages some of the same underlying localization concepts (like language settings for humanized output) as our main Date & Time system. For details on setting up your application's global locale and language, please refer to the Date & Timezone Localization Guide.

All duration functionalities are available from @elemental/common.

For a complete list of all methods and their detailed parameters, please refer to the LmnDuration API documentation.

Introduction to LmnDuration

• Purpose: Manages periods of time, distinct from specific points in time (which LmnDate handles).
• Based on dayjs.duration: Leverages the duration capabilities of dayjs.
• Reactive Properties: Offers computed signals for common string representations of the duratio

Creating LmnDuration Instances

You can create LmnDuration objects from various inputs:

• From Milliseconds:

  const fiveSeconds = new LmnDuration(5000); // 5000 milliseconds

• From an ISO 8601 Duration String:

  const complexDuration = new LmnDuration('P1Y2M3DT4H5M6S'); // 1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds

• From an Object:

  const twoHoursThirtyMinutes = new LmnDuration({ hours: 2, minutes: 30 });

• Cloning: Create a copy with const clonedDuration = myLmnDuration.clone();.

Accessing Duration Values

• As Milliseconds, Seconds, etc.:
  • myLmnDuration.asMilliseconds(): number
  • myLmnDuration.asSeconds(): number
  • And similar methods for minutes, hours, days, weeks, months, years.
• Getting Individual Components:
  • myLmnDuration.getMilliseconds(): number (0-999)
  • myLmnDuration.getSeconds(): number (0-59)
  • myLmnDuration.getMinutes(): number (0-59)
  • myLmnDuration.getHours(): number (0-23)
  • And similar for days, weeks, months, years. These return the component part, not the total duration in that unit (e.g., a duration of 25 hours will return 1 for getDays() and 1 for getHours()).

Reactive Formatted Properties

LmnDuration instances expose computed Signals for easy display:

• myLmnDuration.time(): Standard HMS format (e.g., "5h 4m 25s").
• myLmnDuration.extendedTime(): Extended HMS format, better for screen readers (e.g., "5hr 4min 25sec").
• myLmnDuration.fullTime(): Full HMS format (e.g., "5 hours 4 minutes 25 seconds").

These formats use translated units (hours, minutes, seconds) based on the currentLanguage() and labels defined in LABELS.duration (part of the translation system).

// my-component.ts
import { LmnDuration } from '@elemental/common';

// ...
videoLength = new LmnDuration({ minutes: 4, seconds: 30 });

// In template: <p>Length: {{ videoLength.time() }}</p> -> "4m 30s" (assuming appropriate labels)

Formatting Durations (.format(options?))

The .format() method provides more control:

myLmnDuration.format(options: LmnDurationFormatOptions = {}): string

• options.as: 'time' | 'extended-time' | 'full-time'
  • Determines the style of the HMS formatting, using localized terms. Default is 'time'.
• options.dropBlankUnits: boolean
  • If true (default), leading/trailing zero units are omitted (e.g., new LmnDuration(7000).format() gives "7s").
  • If false, zero units are shown (e.g., new LmnDuration(7000).format({ dropBlankUnits: false }) gives "0h 0m 7s").
• options.format: string
  • A custom dayjs.duration format string (e.g., 'HH:mm:ss', 'Y [years and] M [months]'). If provided, as and dropBlankUnits are ignored.

Examples:

const myDuration = new LmnDuration({ hours: 1, minutes: 0, seconds: 5 });

console.log(myDuration.format()); // Default: "1h 0m 5s" (if 'hm' label is "Hh Mm Ss", could be "1h 0m 5s")
// or "1h 5s" if 'hs' label is "Hh Ss" and default dropBlankUnits is true
// Actual output depends on LABELS.duration values for 'hms' or 'hs'

console.log(myDuration.format({ as: 'full-time', dropBlankUnits: false }));
// e.g., "1 hours 0 minutes 5 seconds" (depends on LABELS.duration.hoursMinutesSeconds)

console.log(myDuration.format({ format: 'HH [hrs], mm [mins]' }));
// e.g., "01 hrs, 00 mins"

Other Useful Methods

• myLmnDuration.humanize(): Returns an approximated, human-readable string (e.g., "an hour", "2 days"), respecting currentLanguage().
• myLmnDuration.toISOString(): Returns the duration in ISO 8601 format (e.g., "PT1H5M").
• myLmnDuration.add(value) and myLmnDuration.subtract(value): For manipulating durations. value can be milliseconds or an LmnDurationObject.

Displaying Durations in Templates (Pipe)

The lmnDuration pipe simplifies formatting LmnDuration objects in templates.

lmnDuration Pipe

• transform(duration?: LmnDuration, format?: string): Signal<string>
  • If format is not provided, it defaults to the duration.time() Signal (standard HMS format, e.g., "4h 5m 29s").
  • If format is provided, it uses duration.format({ format }).

<!-- Assumes myTrackDuration is an LmnDuration instance -->
<p>Track length: {{ (myTrackDuration | lmnDuration)() }}</p>
<p>Formatted length: {{ (myTrackDuration | lmnDuration: 'mm:ss')() }}</p>