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: numbermonth: numberday: 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.
-
Computes the Sun’s declination angle for this moment.get solarDeclination(): number -
Computes the equation of time, describing the difference between apparent and mean solar time.get equationOfTime(): number -
Computes the Sun’s altitude and azimuth for the observer’s location.get solarPosition(): { altitude: number; azimuth: number } -
Returns the umi of sunrise for the observer’s location.get sunrise(): number -
Returns the umi of sunset for the observer’s location.get sunset(): number
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 yearMM— 2‑digit monthdd— 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:
-
Compact Umi‑Time with a leadingUMI_COMPACT = "Uuuusss"U. No date, no segment, no refinement. -
Compact form without the leadingUMI_COMPACT_BARE = "uuusss"U. -
Extended compact form with a colon separator.UMI_EXTENDED = "Uuuu:sss" -
Extended compact form without the leadingUMI_EXTENDED_BARE = "uuu:sss"U. -
Date + compact Umi‑Time. Closest to ISO‑8601 in structure.UMI_DATE_TIME = "yyyy-MM-ddUuuusss" -
Date + extended Umi‑Time. More human‑readable variant ofUMI_DATE_TIME_EXT = "yyyy-MM-ddUuuu:sss"UMI_DATE_TIME. -
Full canonical Umi‑Time including segment and refinement suffixes.UMI_CANONICAL_FULL = "yyyy-MM-ddUuuusssG24+" -
Extended canonical form including segment and refinement.UMI_CANONICAL_FULL_EXT = "yyyy-MM-ddUuuu:sssG24+"
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 as042000) -
Optional leading U: any of the above may start with
U(e.g.U042180) -
Optional date prefix:
yyyy-MM-ddbefore the Umi‑Time portion -
Optional segment suffix:
Sindex/total(e.g.S3/24) -
Optional refinement suffix:
+nnn(e.g.+12) -
Optional longitude suffix:
+dddor-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.
-
Converts radians to degrees.toDeg(rad: number): number -
Converts degrees to radians.toRad(deg: number): number
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
valuewithin which the true coordinate may lie.
An uncertainty of 0 indicates an exact coordinate. Larger
uncertainties represent increasingly approximate positions. Examples:
-
— exact coordinate{ value: 34.9, uncertainty: 0 } -
— approximate longitude{ value: 120, uncertainty: 15 } -
— completely unknown longitude{ value: 0, uncertainty: 180 }
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:sssnoruuusss) - 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.