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();
Documentation
Developer
Project