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"}

pub fn countdown(until: i64, now: i64) -> Countdown

/// What is left of a wait, for a timer on screen.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Countdown {
    /// true from the second until is reached onwards
    pub expired: bool,
    /// seconds left, 0 or more
    pub seconds: i64,
    /// m:ss under an hour, h:mm:ss from an hour up; 0:00 once expired
    pub text: String,
}

fune!(time.countdown@^1);  // then call countdown(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one

/// 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), so
/// `now == until` is expired with nothing left.
pub fn countdown(until: i64, now: i64) -> Countdown {
    let seconds = if until > now { until - now } else { 0 };
    let h = seconds / 3600;
    let m = (seconds % 3600) / 60;
    let s = seconds % 60;
    let text = if h > 0 { format!("{}:{:02}:{:02}", h, m, s) } else { format!("{}:{:02}", m, s) };
    Countdown { expired: seconds == 0, seconds, text }
}

pub fn countdown_to_value(c: &Countdown) -> Value {
    Value::obj(vec![
        ("expired", Value::Bool(c.expired)),
        ("seconds", Value::Int(c.seconds)),
        ("text", Value::str(&c.text)),
    ])
}

fn whole(value: &Value, message: &str) -> i64 {
    match value {
        Value::Int(i) => *i,
        _ => panic!("{}", message),
    }
}

pub fn fune_vector(args: &[Value]) -> Value {
    let until = whole(&args[0], "until must be a whole number of seconds");
    let now = whole(&args[1], "now must be a whole number of seconds");
    countdown_to_value(&countdown(until, now))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add time.countdown

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

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