monitor.format-duration

export function formatDuration(seconds: number, maxUnits: number): string

import { formatDuration } from "#fune/monitor.format-duration@^1";

const UNITS: readonly (readonly [string, number])[] = [["d", 86400], ["h", 3600], ["m", 60], ["s", 1]];

/**
 * Seconds as "3h 12m". Starts at the largest non-zero unit and looks at
 * `maxUnits` consecutive units from there, leaving out the zero ones, so
 * 3605 s with two units is "1h", not "1h 0m" and not "1h 5s": the seconds
 * are beyond the precision asked for. Truncates, never rounds up, so a
 * duration is never shown longer than it was (86399 s is "23h", not "1d").
 */
export function formatDuration(seconds: number, maxUnits: number): string {
  if (!Number.isSafeInteger(seconds)) throw new RangeError(`seconds must be a whole number, received ${seconds}`);
  if (seconds < 0) throw new RangeError(`seconds must not be negative, received ${seconds}`);
  if (!Number.isSafeInteger(maxUnits) || maxUnits < 1 || maxUnits > 4) {
    throw new RangeError(`maxUnits must be 1 to 4, received ${maxUnits}`);
  }
  if (seconds === 0) return "0s";
  let first = 0;
  while (Math.floor(seconds / UNITS[first][1]) === 0) first += 1;
  const parts: string[] = [];
  let rest = seconds;
  for (let i = 0; i < UNITS.length; i++) {
    const [label, size] = UNITS[i];
    const n = Math.floor(rest / size);
    rest -= n * size;
    if (i >= first && i < first + maxUnits && n > 0) parts.push(`${n}${label}`);
  }
  return parts.join(" ");
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.format-duration

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./monitor.format-duration-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.format-duration@1.0.0:typescript.

The whole function, every language, is one file too: monitor.format-duration-1.0.0.fune, 9,390 bytes, sha256 44f871f699d6fea3ca40422a12abc585030b3392315c13e5dd4c90297fe0841f. It installs into a project of any language.

// fune: before monitor.format-duration

// fune: after monitor.format-duration

// fune: step monitor.format-duration after <n|label>

More from the author

1. Find the largest unit that is not zero. 2. Look at `maxUnits` consecutive units from there, down to seconds at most. 3. Show the non-zero ones among them, separated by a space.

So zeros in between are dropped (`3605` with 3 units is `"1h 5s"`, not `"1h 0m 5s"`), and a unit beyond the window is never shown however large (`3605` with 2 units is `"1h"`: minutes are zero and seconds are beyond the precision asked for). The result is always truncated, never rounded up: a duration is never displayed longer than it was, so `86399` with one unit is `"23h"`, not `"1d"`.

Zero is `"0s"`, never an empty string.

`time.duration` also formats durations, but in whole minutes with no spaces (`"2h15m"`); this one is the second-resolution format monitoring tools use.

## Errors

- `seconds must be a whole number, received X` - `seconds must not be negative, received X` - `maxUnits must be 1 to 4, received X`

Files