Umi‑Time API Reference

Introduction

Umi‑Time is a UTC-based representation standard that expresses the UTC day as a continuous 360‑unit cycle called umi. Each umi corresponds to four minutes of UTC, providing a simple geometric representation of the daily cycle that is easy to compute and reason about.

The library mirrors the Umi‑Time architecture. UTC is represented as a Layer 1 Umi‑Time value, optional longitude information provides Layer 2 local interpretation, and solar‑geometry helpers provide Layer 3 solar context.

The core of the library is the UmiTime class. A UmiTime instance is anchored to a specific UTC moment and an approximate observer location, represented by latitude and longitude with uncertainty. From this single value, the class provides derived components: civil‑date fields (year, month, day) and Umi‑Time fields (umi, second, millisecond). Immutability helpers (withUTC, withLatitude, withLongitude) allow constructing new instances with updated context.

The library includes solar‑geometry helpers that operate on UmiTime instances. These derived properties compute quantities such as solar declination, equation of time, solar altitude and azimuth, sunrise, and sunset, using the UTC timestamp together with the observer’s latitude and longitude. These values support Layer 3 solar‑context features and do not affect the underlying Umi‑Time value or Layer 2 local interpretation.

Umi‑Time also supports formatting and parsing. The format(spec) method produces Umi‑Time strings according to predefined or custom format specifiers, and UmiTime.parse(input, opts) constructs a UmiTime instance from a string, optionally guided by explicit latitude and longitude hints.

This API reference documents the UmiTime class, the solar‑ geometry helpers, the formatting and parsing functions, the predefined format constants, and the supporting utility functions exported by the library. It serves as the authoritative guide for using Umi‑Time in applications, tools, and language bindings.

Core Concepts

Umi

Umi‑Time divides the UTC day into 360 equal units called umi. Each umi corresponds to four minutes of UTC. This creates a simple, uniform geometric representation of the daily cycle.

UTC and Location

Every Umi‑Time value is anchored to a specific UTC moment. Latitude and longitude provide optional context for local interpretation and solar calculations. Longitude may be used to derive Layer 2 local context, while latitude and longitude together are used for Layer 3 solar‑context calculations such as solar altitude, azimuth, sunrise, and sunset. These geographic values do not affect the underlying Umi‑Time value.

Day Segments

Day segments divide the local Umi‑Day into a fixed number of equal intervals. They provide a compact Layer 2 local-context representation by identifying where a Umi‑Time value falls within the observer's local day without altering the underlying Umi‑Time value.

Different segment systems may use different numbers of divisions. For example, the day‑phase system divides the local Umi‑Day into 24 equal segments of 15 umi each, while other segment schemes may use coarser or finer subdivisions. All segment systems are derived from the same longitude‑based local interpretation.

Refinement

Refinement is an optional offset inside a day segment. It describes how far the current umi value lies from the start of its segment. Refinement is used for more precise contextual labeling and does not modify the underlying Umi‑Time value.

Umi‑Time Strings

Umi‑Time strings provide textual representations of Umi‑Time values. Formats may include date prefixes, segment codes, refinement suffixes, and longitude annotations. These strings can be parsed back into fully constructed UmiTime instances.

The UmiTime Class

The UmiTime class represents a UTC moment together with an approximate observer location. It provides derived civil‑date fields, Umi‑Time fields (umi, second, millisecond), solar geometry, segment helpers, and formatting and parsing capabilities. All API functions operate on or produce UmiTime instances.

UmiTime Class

The UmiTime class represents a single moment in time anchored to a UTC timestamp and an approximate observer location. All Umi‑Time values, solar‑geometry context, segment information, and formatted string representations are derived from this core data.

Constructor

new UmiTime(
  utc: Date,
  latitude: ApproximateValue = { value: 0, uncertainty: 90 },
  longitude: ApproximateValue = { value: 0, uncertainty: 180 },
)

Creates a new UmiTime instance. The utc value is required. Latitude and longitude are optional and may include uncertainty. These geographic values are used only for solar‑geometry calculations and do not affect the underlying Umi‑Time value.

Properties

utc

A Date object representing the underlying UTC timestamp for this Umi‑Time value. All derived fields are computed from this moment.

latitude

An ApproximateValue describing the observer’s latitude. Used for solar‑geometry calculations. May include uncertainty.

longitude

An ApproximateValue describing the observer’s longitude. Used for solar‑geometry calculations and optional day‑segment inference. May include uncertainty.

Immutability Helpers

These methods return new UmiTime instances with updated values.

withUTC(utc: Date): UmiTime
withLatitude(value: number, uncertainty?: number): UmiTime
withLongitude(value: number, uncertainty?: number): UmiTime

Derived Civil‑Date Fields

  • year: number
  • month: number
  • day: number

These values are extracted directly from the underlying UTC timestamp.

Derived Umi‑Time Fields

  • umi: number — the umi position within the 360‑umi UTC day
  • second: number — the second within the current umi (0–239)
  • millisecond: number — the millisecond within the current second

These values are computed from the UTC timestamp using the Umi‑Time day structure.

Solar Geometry

These getters compute solar‑related quantities for the current UTC moment and observer location. Some calculations require sufficiently precise latitude and longitude values and may throw UmiTimeError if the uncertainty is too large.

  • get solarDeclination(): number
    Computes the Sun’s declination angle for this moment.
  • get equationOfTime(): number
    Computes the equation of time, describing the difference between apparent and mean solar time.
  • get solarPosition(): { altitude: number; azimuth: number }
    Computes the Sun’s altitude and azimuth for the observer’s location.
  • get sunrise(): number
    Returns the umi of sunrise for the observer’s location.
  • get sunset(): number
    Returns the umi of sunset for the observer’s location.

These values are computed using the UTC timestamp together with the observer’s latitude and longitude. Some calculations require sufficiently precise geographic values and may throw UmiTimeError if the uncertainty is too large.

Day Segment Helpers

segmentIndex(total: number): number
segmentRefinement(total: number): number

These helpers divide the 360‑umi UTC day into equal parts and compute the current segment and the offset within that segment. They do not modify the underlying Umi‑Time value.

Format Tokens

Tokens fall into two categories: variable tokens, which insert computed values, and literal tokens, which appear exactly as written in the output.

  • Date tokens (variable)
    • yyyy — 4‑digit year
    • MM — 2‑digit month
    • dd — 2‑digit day of month
  • Umi‑Time tokens (variable)
    • uuu — umi (000–359), zero‑padded
    • sss — second within the umi (000–239), zero‑padded
  • Literal tokens
    • U — literal prefix indicating Umi‑Time
    • : — literal separator between umi and seconds
  • Segment tokens (variable)
    • G24 — segment suffix (e.g., S19/24)
  • Refinement tokens (variable)
    • + — refinement offset inside the segment (e.g., +12)

The predefined specifiers below combine these tokens into commonly used Umi‑Time formats.

The library provides the following predefined specifiers:

  • UMI_COMPACT = "Uuuusss"
    Compact Umi‑Time with a leading U. No date, no segment, no refinement.
  • UMI_COMPACT_BARE = "uuusss"
    Compact form without the leading U.
  • UMI_EXTENDED = "Uuuu:sss"
    Extended compact form with a colon separator.
  • UMI_EXTENDED_BARE = "uuu:sss"
    Extended compact form without the leading U.
  • UMI_DATE_TIME = "yyyy-MM-ddUuuusss"
    Date + compact Umi‑Time. Closest to ISO‑8601 in structure.
  • UMI_DATE_TIME_EXT = "yyyy-MM-ddUuuu:sss"
    Date + extended Umi‑Time. More human‑readable variant of UMI_DATE_TIME.
  • UMI_CANONICAL_FULL = "yyyy-MM-ddUuuusssG24+"
    Full canonical Umi‑Time including segment and refinement suffixes.
  • UMI_CANONICAL_FULL_EXT = "yyyy-MM-ddUuuu:sssG24+"
    Extended canonical form including segment and refinement.

Parsing

static parse(
  input: string,
  opts?: { latitude?: number; longitude?: number },
): UmiTime

Parses a Umi‑Time string and returns a fully constructed UmiTime instance. The parser recognizes a small set of built‑in patterns directly, without requiring an explicit format specifier. It accepts:

  • Basic Umi‑Time: uuusss (e.g. 042180)
  • Extended Umi‑Time: uuu:sss (e.g. 042:180)
  • Umi‑only: uuu (e.g. 042, interpreted as 042000)
  • Optional leading U: any of the above may start with U (e.g. U042180)
  • Optional date prefix: yyyy-MM-dd before the Umi‑Time portion
  • Optional segment suffix: Sindex/total (e.g. S3/24)
  • Optional refinement suffix: +nnn (e.g. +12)
  • Optional longitude suffix: +ddd or -ddd (e.g. +123)

If the string does not encode longitude, an explicit opts.longitude value or a segment/refinement suffix is used to infer an approximate longitude. If no latitude is provided via opts.latitude, a default approximate latitude is used.

Umi and second values are validated; out‑of‑range values or malformed input produce a ParseError.

For the full definition of Umi‑Time textual formats, see the Umi‑Time Specification. The parser accepts all standard forms described there.

Solar Geometry Helpers

The Umi‑Time library provides a small set of standalone functions for computing solar‑related quantities. These helpers operate on UTC timestamps and geographic coordinates, and are used internally by the UmiTime class’s solar‑geometry getters. They may also be used directly in applications that need lower‑level access to solar calculations.

Angle Conversion

Basic helpers for converting between radians and degrees.

  • toDeg(rad: number): number
    Converts radians to degrees.
  • toRad(deg: number): number
    Converts degrees to radians.

UT Umi From Date

Computes the umi position for a given UTC timestamp. This is the same calculation used internally by UmiTime to derive its umi getter.

utUmiFromDate(utc: Date): number

Solar Altitude

Computes the Sun’s altitude angle for a given UTC moment and observer location. Altitude is measured in degrees above the horizon.

solarAltitude(
  utc: Date,
  latitude: number,
  longitude: number,
): number

Hour Angle

Computes the solar hour angle for a given UTC moment and observer location. The hour angle describes the Sun’s position relative to local solar noon.

getHourAngle(
  utc: Date,
  longitude: number,
  equationOfTime: number,
): number

ApproximateValue

ApproximateValue represents a numeric value together with an uncertainty radius. It is used for geographic coordinates in UmiTime, allowing the library to express both exact and approximate positions. Solar‑geometry calculations rely on these values to determine whether the observer’s location is sufficiently precise for computing solar context.

interface ApproximateValue {
  value: number;        // central value
  uncertainty: number;  // ± range around the value
}

Semantics

  • value — the estimated latitude or longitude.
  • uncertainty — the radius of the interval around value within which the true coordinate may lie.

An uncertainty of 0 indicates an exact coordinate. Larger uncertainties represent increasingly approximate positions. Examples:

  • { value: 34.9, uncertainty: 0 }
    — exact coordinate
  • { value: 120, uncertainty: 15 }
    — approximate longitude
  • { value: 0, uncertainty: 180 }
    — completely unknown longitude

Usage in UmiTime

ApproximateValue is used for both latitude and longitude in the UmiTime constructor and in parsing. When a Umi‑Time string does not specify location, the parser constructs approximate values using default uncertainties:

  • latitude:
    { value: 0, uncertainty: 90 }
  • longitude:
    { value: 0, uncertainty: 180 }

Segment and refinement suffixes (Sindex/total and +refinement) reduce longitude uncertainty by narrowing the inferred solar segment.

Errors

Umi‑Time defines two error classes used throughout parsing and solar‑geometry evaluation. Both extend the built‑in Error type and provide descriptive messages indicating what went wrong.

ParseError

class ParseError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "ParseError";
  }
}

ParseError is thrown when a Umi‑Time string cannot be parsed. This includes malformed input, invalid umi or second ranges, or unrecognized combinations of date, segment, refinement, or longitude suffixes.

Examples of conditions that produce a ParseError:

  • umi outside 0–359
  • second outside 0–239
  • invalid Umi‑Time portion (neither uuu:sss nor uuusss)
  • malformed segment suffix (e.g., S3/x)
  • malformed refinement suffix (e.g., +abc)

UmiTimeError

class UmiTimeError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "UmiTimeError";
  }
}

UmiTimeError is thrown when a valid UmiTime instance cannot perform a requested computation. This occurs when solar‑geometry calculations require more precise geographic information than the instance contains.

Common reasons for UmiTimeError:

  • latitude uncertainty too large for solar altitude/azimuth
  • longitude uncertainty too large for sunrise/sunset computation
  • segment/refinement inference insufficiently precise

These errors indicate that the caller should provide more precise latitude or longitude values, either via withLatitude(), withLongitude(), or by supplying explicit coordinates when parsing.

Module Parity Matrix

Umi‑Time is designed as a multi‑language library. Each language binding implements the same conceptual modules, though some bindings may not yet support all modules. The table below summarizes current parity across official implementations.

Module JavaScript / TypeScript Python Rust C++
Core UmiTime Class ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
Formatting API ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
Parsing API ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
Solar Geometry API ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
Segment API ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
UT Math API ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
Utilities ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned
Error Model ✔ Implemented ⧗ Planned ⧗ Planned ⧗ Planned

“✔ Implemented” indicates full support in the current release. “⧗ Planned” indicates modules that will be added as the corresponding language binding matures. All bindings aim for complete parity with the JavaScript reference implementation.

Roadmap

Umi‑Time is evolving toward a complete, multi‑language ecosystem. The roadmap below outlines the major milestones planned for the next phases of development. Timelines are approximate and will adjust based on community feedback and implementation experience.

Core Specification

  • Refine and stabilize the Umi‑Time specification
  • Expand examples and edge‑case definitions in the specification
  • Formalize segment and refinement semantics for cross‑language parity

Reference Implementation (JavaScript / TypeScript)

  • Complete solar‑geometry coverage
  • Finalize formatting and parsing APIs
  • Improve error diagnostics and uncertainty reporting
  • Publish additional demos (map, clock, solar‑context visualizations)

Language Bindings

  • Python binding with full module parity
  • Rust binding with zero‑copy geometry primitives
  • C++ binding for embedded and high‑performance environments
  • Shared test suite across all bindings

Tools & Ecosystem

  • CLI utilities for converting and inspecting Umi‑Time strings
  • Browser‑based playground for interactive exploration
  • Reference datasets for sunrise/sunset validation
  • Integration examples for mapping and visualization frameworks

Community & Governance

  • Establish the Umi‑Time GitHub organization
  • Define contribution guidelines and module ownership
  • Publish long‑term adoption and compatibility policy

As the ecosystem grows, the roadmap will continue to evolve. Community feedback is encouraged and will guide future priorities.

Documentation
Developer
Project