BrightDate — Workspace

Named in homage to Star Trek's Stardate — one universal scalar to rule them all.

This workspace contains the BrightDate libraries: a scientifically grounded, timezone-free decimal day representation anchored at J2000.0 via a TAI substrate. The v1 f64 decimal-day value remains the ergonomic dashboard; the v2 canonical engine stores attoseconds since J2000.0 and derives decimal days through an integer lens (Euclidean divmod).

Crates

TypeScript library

Showcase

The BrightDate v1.0 Design

Epoch: J2000.0 — Astronomically Correct

J2000.0 is defined in Terrestrial Time (TT) as 2000-01-01T12:00:00 TT.

BrightDate = 0 at 2000-01-01T11:58:55.816Z.

TAI Substrate

bd = (taiUnixSeconds − 946_727_967.816) / 86400

BrightDate ticks in exact SI seconds. Leap seconds exist only at UTC boundary conversions.

Key Constants

Reference Epochs

Companion Types

Pick the representation that matches your boundary: store in an exact integer engine, compute in BrightDate when f64 is enough, label with BD / PBD. All types share the same J2000.0 / TAI semantics; they differ only in storage and how decimal days are produced.

Integer lens (engine ↔ decimal days)

Canonical ticks use Euclidean divmod; decimal days are a presentation lens:

bd = days + rem / ticks_per_day     (days, rem from divmod on attoseconds or picoseconds)

Exported helpers: ticks_to_brightdate, brightdate_to_attoseconds, brightdate_to_picoseconds, and day constants such as ATTOSECONDS_PER_DAY.

Rust and TypeScript both ship these types. BrightDate::from_unix_ms / to_unix_ms apply the leap-second table on the UTC label; ExactBrightAtto uses linear Unix-ms offset from the J2000 UTC anchor — use the engine at storage boundaries and the dashboard for human-facing decimal days.

Unit hierarchies (do not conflate)

use brightdate::{
    format_bd, ticks_to_brightdate, ATTOSECONDS_PER_DAY, BrightDate, BrightInstant,
    ExactBrightAtto, ExactBrightDate,
};

// v1 dashboard
let bd = BrightDate::now();
let inst = BrightInstant::from_brightdate(bd.value).unwrap();
let back = BrightDate::from_value(inst.to_brightdate());

// v2 canonical engine
let atto = ExactBrightAtto::from_unix_ms(1_700_000_000_000);
assert_eq!(atto.encode(), format!("EBA1:{}", atto.attoseconds()));
assert!((atto.to_brightdate() - ticks_to_brightdate(atto.attoseconds(), ATTOSECONDS_PER_DAY)).abs() < 1e-10);

// Bridge: dashboard decimal days match the lens
assert!((BrightDate::from_exact_bright_atto(atto).value - atto.to_brightdate()).abs() < 1e-10);
// Whole-day attosecond ticks round-trip exactly through the f64 bridge
let whole_day = ExactBrightAtto::from_attoseconds(ATTOSECONDS_PER_DAY);
assert_eq!(
    BrightDate::from_exact_bright_atto(whole_day)
        .to_exact_bright_atto()
        .unwrap(),
    whole_day,
);

// Picosecond engine (optional)
let ps = ExactBrightDate::from_unix_ms(1_700_000_000_000);
let from_ps = ExactBrightAtto::from_exact_brightdate(ps);

// Pre-J2000.0 instants: PBD display label (no leading minus in user strings)
let pre = BrightDate::from_value(-11125.154);
assert_eq!(format_bd(pre.value, 3).unwrap(), "PBD 11125.154");

Installing

From crates.io

The brightdate library and all five CLI tools are published on crates.io:

# Library (for use in Rust projects)
cargo add brightdate

# CLI tools
cargo install bdate     # date(1) replacement
cargo install btime     # time(1) replacement
cargo install buptime   # uptime(1) replacement
cargo install bcal      # cal(1) replacement
cargo install bwatch    # watch(1) replacement

From Homebrew (macOS / Linux)

The CLI tools are available via the Digital Defiance Homebrew tap:

brew tap digital-defiance/tap
brew install digital-defiance/tap/bdate
brew install digital-defiance/tap/btime
brew install digital-defiance/tap/buptime
brew install digital-defiance/tap/bcal
brew install digital-defiance/tap/bwatch

After tapping you can also use the short names: brew install bdate, etc.

Using the Rust library

# Cargo.toml
[dependencies]
brightdate = "0.5"

use brightdate::{BrightDate, ExactBrightAtto};

let now = BrightDate::now();
println!("{:.5}", now);           // e.g. 9603.57128
println!("{}", now.to_iso());     // 2026-05-11T12:34:56.789Z

let exact = ExactBrightAtto::from_unix_ms(now.to_unix_ms() as i64);
println!("{}", exact.encode());   // EBA1:… attoseconds since J2000.0

See the crates.io docs for the full API.

Building from source

Rust

cargo build --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings

TypeScript

cd brightdate
yarn install
yarn build
yarn test

Showcase

cd brightdate/showcase
yarn install
yarn dev

Format characters

BrightDate % extensions (%Wt, %Ws, %dE, …) are documented in FORMAT-SPEC.md. The %W* family matches bright-findutils bfind -printf; btime -f adds timing-only letters and %d* milliday durations aligned with BSH TIMEFMT.

License

MIT © Digital Defiance