totalUnits

Unreleased

Not in @northguild/gmt 1.18.0 on npm yet. It is on main and ships in the next release.

Signature

totalUnits(units: Partial<Record<"days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", number>>, unit: "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | "day" | TimeUnit): number | null

Express an amount written as a unit object, such as { minutes: 15 }, as a single fractional total in one unit.

• Uses Temporal.Duration.from and .total: every field is converted, so totalUnits({ days: 1, hours: 12 }, “seconds”) is 129600.
• Which function to use: totalUnits takes a unit object. totalDuration takes an ISO 8601 duration string ("PT15M"). durationFromUnits turns a unit object into the duration string that the other duration functions take.
• Takes exact units only: days, hours, minutes, seconds, milliseconds, microseconds and nanoseconds. A day is 24 hours, as Temporal’s Duration.prototype.total reads a day when it has no relativeTo. For a day in a time zone, which can be 23 or 25 hours across a clock change, use totalDuration with a zoned relativeTo.
• A year, a month or a week returns null, as a key and as unit: Temporal gives them no length without a date to measure from. Write a week as { days: 7 }. For a calendar amount, build the string with durationFromUnits and pass it to totalDuration with relativeTo.
• The result is fractional, not rounded: totalUnits({ hours: 36 }, “days”) is 1.5. It is a JavaScript number, so a total past 2^53 is the nearest double.
• Every key is a unit name in the plural, and every amount is a whole finite number. All nonzero amounts share one sign, as Temporal requires of a duration. A unit set to undefined is absent, as Temporal reads it.
• An unknown key returns null, even beside a valid one. Temporal on its own ignores an unknown key, so a misspelt { minutes: 15, hour: 1 } would total 900 with no warning.
• unit accepts the plural or singular name ("seconds" or "second"), as Temporal does.
• Returns null on an object with no unit, a non-object units (a duration string included), an invalid amount, an amount past Temporal’s duration range, or an invalid unit.

Parameters

Parameter	Type	Description
units	Partial<Record<"days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", number>>	Partial<Record<ExactDurationUnit, number>> object holding the amount to total
unit	"days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | "day" | TimeUnit	ExactDurationUnit to total into (“days” | “hours” | “minutes” | “seconds” | “milliseconds” | “microseconds” | “nanoseconds”, or the singular name)

Returns

the fractional total in unit, or null on invalid input

Types

ExactDurationUnit

The plural name of a duration field that has an exact length: "days", or a time field from "hours" down to "nanoseconds". A day is 24 hours when nothing anchors it, as TC39 Temporal’s Duration.prototype.total reads one without relativeTo. Years, months and weeks are left out: Temporal gives them no length without a date to measure from.

import type { ExactDurationUnit } from "@northguild/gmt";

"days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds"

Related types

• TimeUnit

Examples

import { totalUnits } from "@northguild/gmt/duration/calculate";

totalUnits({ minutes: 15 }, "seconds") // 900

output

 

Source

duration/calculate/totalUnits.ts