time.countdown

countdown(1790427600, 1790424000)   # {expired: false, seconds: 3600, text: "1:00:00"}
countdown(1000754, 1000000)         # {expired: false, seconds: 754,  text: "12:34"}
countdown(1790427600, 1790427600)   # {expired: true,  seconds: 0,    text: "0:00"}

export function countdown(until: number, now: number): Countdown

/** What is left of a wait, for a timer on screen. */
export interface Countdown {
  /** true from the second until is reached onwards */
  readonly expired: boolean;
  /** seconds left, 0 or more */
  readonly seconds: number;
  /** m:ss under an hour, h:mm:ss from an hour up; 0:00 once expired */
  readonly text: string;
}

import { countdown } from "#fune/time.countdown@^1";

import { type Countdown } from "./time_countdown_types.ts";

function pad2(n: number): string {
  return n < 10 ? "0" + n : String(n);
}

/**
 * The time left until `until`, as a number and as a timer's text. A moment is
 * reached at `until` itself, as a JWT's exp is (RFC 7519 4.1.4: "on or
 * after"), so `now === until` is expired with nothing left.
 */
export function countdown(until: number, now: number): Countdown {
  if (typeof until !== "number" || !Number.isSafeInteger(until)) throw new RangeError("until must be a whole number of seconds");
  if (typeof now !== "number" || !Number.isSafeInteger(now)) throw new RangeError("now must be a whole number of seconds");
  const seconds = until > now ? until - now : 0;
  const h = Math.floor(seconds / 3600);
  const m = Math.floor((seconds % 3600) / 60);
  const s = seconds % 60;
  const text = h > 0 ? `${h}:${pad2(m)}:${pad2(s)}` : `${m}:${pad2(s)}`;
  return { expired: seconds === 0, seconds, text };
}

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 time.countdown

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

The whole function, every language, is one file too: time.countdown-1.0.0.fune, 8,884 bytes, sha256 5f79273496584521bbb68fa26b0ddacef830b3504a91209b74ff3a0c133ebbac. It installs into a project of any language.

// fune: before time.countdown

// fune: after time.countdown

// fune: step time.countdown after <n|label>

More from the author

Use it for an access token's remaining life (`until` is the token's `exp`), for how long a locked-out login must wait (`until` is now plus Retry-After), or for a cookie's `Max-Age` (`seconds`). The caller reads the clock and passes `now`, so the function stays pure and a page can call it once a second to tick.

**Reached means expired.** The moment is reached at `until` itself, not one second later: RFC 7519 section 4.1.4 says a token MUST NOT be accepted "on or after" its `exp`. So `now == until` is `expired: true` with `seconds: 0`, and `expired` is exactly `seconds == 0`. A moment already past is also 0, never negative, so a timer never shows "-0:05".

**Text.** `m:ss` under an hour (`0:59`, `12:34`), `h:mm:ss` from an hour up (`1:00:00`). Hours are not wrapped at 24, because a wait is a length of time and not a time of day: 25 hours and a bit is `25:01:01`.

**Whole seconds.** Both arguments are whole Unix seconds, as JWT `exp` and `time.iso-to-unix` give them. A fraction (JavaScript's `Date.now() / 1000` not floored) is refused: "until must be a whole number of seconds" or "now must be a whole number of seconds".

Files