Skip to content

Instant ​

Instant represents an absolute point on the timeline with signed seconds and a non-negative nanosecond remainder.

When Tyrus serializes an Instant as JSON, it uses the UTC ISO 8601 string returned by instantToString, including it as a string field in HTTP responses. OpenAPI describes this value as type: "string" with format: "date-time", matching values such as 2026-09-05T18:32:52.54345Z.

API ​

  • instantNow(): Instant reads the current native clock.
  • instantFrom(value: string): Result<Instant, TemporalError> parses an ISO instant.
  • instantFromEpochMilliseconds(milliseconds: i64): Result<Instant, TemporalError> creates an instant from Unix epoch milliseconds.
  • instantToEpochMilliseconds(value: Instant): Result<i64, TemporalError> converts an instant to epoch milliseconds.
  • instantToString(value: Instant): Result<string, TemporalError> formats an instant as UTC ISO text.
  • instantAddDuration and instantSubtractDuration return Result<Instant, TemporalError> and apply fixed-length durations; calendar units are rejected.
  • instantToZonedDateTime(value: Instant, timeZone: TimeZone): ZonedDateTime associates an instant with a checked-in IANA zone.
tyrus
import { Duration, Instant, TemporalError, TimeZone, ZonedDateTime, instantAddDuration, instantFrom, instantFromEpochMilliseconds, instantNow, instantToEpochMilliseconds, instantToString, instantToZonedDateTime, timeZone } from "tyrus:temporal";

export const example = (): void => {
    const now: Instant = instantNow();
    const parsed: Instant = match instantFrom("2026-07-09T15:30:00Z") { Ok(value) => value, Err(error) => { printError(error.code); return; } };
    const epoch: Instant = match instantFromEpochMilliseconds(0) { Ok(value) => value, Err(error) => { printError(error.code); return; } };
    const milliseconds: i64 = match instantToEpochMilliseconds(epoch) { Ok(value) => value, Err(error) => { printError(error.code); return; } }; // 0
    const text: string = match instantToString(epoch) { Ok(value) => value, Err(error) => { printError(error.code); return; } }; // "1970-01-01T00:00:00Z"
    const second: Duration = { years: 0, months: 0, weeks: 0, days: 0, hours: 0, minutes: 0, seconds: 1, milliseconds: 0, microseconds: 0, nanoseconds: 0 };
    const later: Instant = match instantAddDuration(epoch, second) { Ok(value) => value, Err(error) => { printError(error.code); return; } };
    const paris: TimeZone = match timeZone("Europe/Paris") { Ok(value) => value, Err(error) => { printError(error.code); return; } };
    const zoned: ZonedDateTime = instantToZonedDateTime(parsed, paris);
};