API Examples
These examples demonstrate how to construct UmiTime
instances, work with Layer 1 Umi‑Time values, derive Layer 2 local interpretation,
compute Layer 3 solar context, and use formatting, parsing, and helper utilities.
All examples match the current Umi‑Time implementation.
1. Creating a Umi‑Time Value
A UmiTime instance is created by passing a UTC
Date. Latitude and longitude are optional
ApproximateValue objects used for local interpretation and
solar‑context calculations.
import { UmiTime } from "umi-time";
// Basic: no location (max uncertainty)
const umi1 = new UmiTime(new Date());
// With precise location
const umi2 = new UmiTime(
new Date(),
{ value: 35.14, uncertainty: 0 }, // latitude
{ value: -120.64, uncertainty: 0 } // longitude
);
2. Derived Fields
Umi‑Time exposes civil‑date fields and Umi‑Time fields derived from the UTC timestamp.
const umi = new UmiTime(new Date());
console.log(umi.year); // UTC year
console.log(umi.month); // UTC month (1–12)
console.log(umi.day); // UTC day
console.log(umi.umi); // umi (0–359)
console.log(umi.second); // second within umi (0–239)
3. Immutability Helpers
withUTC, withLatitude, and
withLongitude return new instances with updated values.
const umi = new UmiTime(new Date());
const later = umi.withUTC(new Date(Date.now() + 60000));
const precise = umi.withLatitude(35.14, 0).withLongitude(-120.64, 0);
4. Formatting Umi‑Time
Formatting uses format(spec) with tokens defined in the
API Reference.
const umi = new UmiTime(new Date());
umi.format("Uuuusss"); // "U042180"
umi.format("Uuuu:sss"); // "U042:180"
umi.format("yyyy-MM-ddUuuusss"); // "2026-09-25U042180"
umi.format(UMI_CANONICAL_FULL); // "2026-09-25U042180+S21/24"
5. Parsing Umi‑Time Strings
UmiTime.parse() accepts compact, extended, date-prefixed, and
canonical forms, including segment, refinement, and longitude suffixes.
import { UmiTime } from "umi-time";
// Basic
UmiTime.parse("042180");
// Extended
UmiTime.parse("042:180");
// Date + Umi‑Time
UmiTime.parse("2026-09-25U042180");
// With segment + refinement
UmiTime.parse("042180S3/24+12");
// With explicit coordinates
UmiTime.parse("042180", { latitude: 35.14, longitude: -120.64 });
6. Segment & Refinement Helpers
Segments divide the local Umi‑Day into equal parts and provide optional Layer 2 local-context representations. Refinement measures position within a segment. Day phases are a specific segment system consisting of 24 equal divisions of the local Umi‑Day.
const umi = new UmiTime(
new Date(),
{ value: 35.14, uncertainty: 0 },
{ value: -120.64, uncertainty: 0 }
);
console.log(umi.segmentIndex(24)); // 0–23
console.log(umi.segmentRefinement(24)); // offset inside segment
7. Solar Geometry (via UmiTime)
Segments divide the local Umi‑Day into equal parts and provide optional Layer 2 local-context representations. Refinement measures position within a segment. Day phases are a specific segment system consisting of 24 equal divisions of the local Umi‑Day.
const umi = new UmiTime(
new Date(),
{ value: 35.14, uncertainty: 0 },
{ value: -120.64, uncertainty: 0 }
);
console.log(umi.solarDeclination);
console.log(umi.equationOfTime);
console.log(umi.solarPosition); // { altitude, azimuth }
console.log(umi.sunrise); // umi of sunrise
console.log(umi.sunset); // umi of sunset
8. Live Umi‑Time Display
A simple example showing how to update a Umi‑Time display every second.
import { UmiTime, UMI_EXTENDED } from "umi-time";
function updateUmiTime() {
const now = new Date();
const umi = new UmiTime(now);
const text = umi.format(UMI_EXTENDED);
const el = document.getElementById("umi-live-time");
if (el) el.textContent = text;
}
setInterval(updateUmiTime, 1000);
updateUmiTime();